api

Documentation

Overview

Package api allows Go projects to use func-e as a library, decoupled from how the func-e binary reads environment variables or CLI args.

Index

• type RunFunc
• type RunOption
  • func ConfigHome(configHome string) RunOption
  • func DataHome(dataHome string) RunOption
  • func EnvoyErr(w io.Writer) RunOption
  • func EnvoyOut(w io.Writer) RunOption
  • func EnvoyVersion(envoyVersion string) RunOption
  • func EnvoyVersionsURL(envoyVersionsURL string) RunOption
  • func HomeDir(homeDir string) RunOption
  • func Out(out io.Writer) RunOption
  • func RunID(runID string) RunOption
  • func RuntimeDir(runtimeDir string) RunOption
  • func StateHome(stateHome string) RunOption

Types

type RunFunc

type RunFunc func(ctx context.Context, args []string, options ...RunOption) error

RunFunc downloads Envoy and runs it as a process with the arguments passed to it. Use api.RunOption for configuration options.

On success, this blocks and returns nil when either `ctx` is done, or the process exits with status zero.

The default implementation of RunFunc is func_e.Run.

type RunOption

type RunOption func(*api.RunOpts)

RunOption is a configuration for RunFunc.

Note: None of these default to values read from OS environment variables. If you wish to introduce such behavior, populate them in calling code.

func ConfigHome

func ConfigHome(configHome string) RunOption

ConfigHome is the directory containing configuration files. Defaults to "~/.config/func-e"

Files stored here: - envoy-version (selected version preference)

func DataHome

func DataHome(dataHome string) RunOption

DataHome is the directory containing downloaded Envoy binaries. Defaults to "~/.local/share/func-e"

Files stored here: - envoy-versions/{version}/bin/envoy (downloaded Envoy binaries)

func EnvoyErr

func EnvoyErr(w io.Writer) RunOption

EnvoyErr sets the writer for Envoy stderr

func EnvoyOut

func EnvoyOut(w io.Writer) RunOption

EnvoyOut sets the writer for Envoy stdout

func EnvoyVersion

func EnvoyVersion(envoyVersion string) RunOption

EnvoyVersion overrides the version of Envoy to run. Defaults to the contents of "$ConfigHome/envoy-version".

When that file is missing, it is generated from ".latestVersion" from the EnvoyVersionsURL. Its value can be in full version major.minor.patch format, e.g. 1.18.1 or without patch component, major.minor, e.g. 1.18.

func EnvoyVersionsURL

func EnvoyVersionsURL(envoyVersionsURL string) RunOption

EnvoyVersionsURL is the path to the envoy-versions.json. Defaults to "https://archive.tetratelabs.io/envoy/envoy-versions.json"

func HomeDir

func HomeDir(homeDir string) RunOption

Deprecated: Use ConfigHome, DataHome, StateHome or RuntimeDir instead. This function will be removed in a future version.

func Out

func Out(out io.Writer) RunOption

Out is where status messages are written. Defaults to os.Stdout

func RunID

func RunID(runID string) RunOption

RunID sets a custom run identifier used in StateDir and RuntimeDir paths. By default, a timestamp-based runID is auto-generated (e.g., "20250115_123456_789").

Use this to: - Create predictable directories for Docker/K8s (e.g., RunID("0")) - Implement custom naming schemes

Validation: runID cannot contain path separators (/ or \)

func RuntimeDir

func RuntimeDir(runtimeDir string) RunOption

RuntimeDir is the directory containing ephemeral runtime files. Defaults to "/tmp/func-e-${UID}"

Files stored here: - {runID}/admin-address.txt (Envoy admin API endpoint)

Note: Runtime files are ephemeral and may be cleaned up on system restart.

func StateHome

func StateHome(stateHome string) RunOption

StateHome is the directory containing persistent state like run logs. Defaults to "~/.local/state/func-e"

Files stored here: - envoy-runs/{runID}/stdout.log,stderr.log (per-run logs) - envoy-runs/{runID}/config_dump.json (Envoy configuration snapshot)