Add AdminClient for Envoy admin API access (#483)

Signed-off-by: Adrian Cole <[email protected]>

Author: codefromthecrypt

api/run.go

@@ -9,21 +9,21 @@ import (
 	"context"
 	"io"
 
-	"github.com/tetratelabs/func-e/internal/opts"
+	"github.com/tetratelabs/func-e/internal/api"
 )
 
 // HomeDir is an absolute path which most importantly contains "versions"
 // installed from EnvoyVersionsURL. Defaults to "${HOME}/.func-e"
 func HomeDir(homeDir string) RunOption {
-	return func(o *opts.RunOpts) {
+	return func(o *api.RunOpts) {
 		o.HomeDir = homeDir
 	}
 }
 
 // EnvoyVersionsURL is the path to the envoy-versions.json.
 // Defaults to "https://archive.tetratelabs.io/envoy/envoy-versions.json"
 func EnvoyVersionsURL(envoyVersionsURL string) RunOption {
-	return func(o *opts.RunOpts) {
+	return func(o *api.RunOpts) {
 		o.EnvoyVersionsURL = envoyVersionsURL
 	}
 }
@@ -35,28 +35,28 @@ func EnvoyVersionsURL(envoyVersionsURL string) RunOption {
 // 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 EnvoyVersion(envoyVersion string) RunOption {
-	return func(o *opts.RunOpts) {
+	return func(o *api.RunOpts) {
 		o.EnvoyVersion = envoyVersion
 	}
 }
 
 // Out is where status messages are written. Defaults to os.Stdout
 func Out(out io.Writer) RunOption {
-	return func(o *opts.RunOpts) {
+	return func(o *api.RunOpts) {
 		o.Out = out
 	}
 }
 
 // EnvoyOut sets the writer for Envoy stdout
 func EnvoyOut(w io.Writer) RunOption {
-	return func(o *opts.RunOpts) {
+	return func(o *api.RunOpts) {
 		o.EnvoyOut = w
 	}
 }
 
 // EnvoyErr sets the writer for Envoy stderr
 func EnvoyErr(w io.Writer) RunOption {
-	return func(o *opts.RunOpts) {
+	return func(o *api.RunOpts) {
 		o.EnvoyErr = w
 	}
 }
@@ -65,7 +65,7 @@ func EnvoyErr(w io.Writer) RunOption {
 //
 // Note: None of these default to values read from OS environment variables.
 // If you wish to introduce such behavior, populate them in calling code.
-type RunOption func(*opts.RunOpts)
+type RunOption func(*api.RunOpts)
 
 // RunFunc downloads Envoy and runs it as a process with the arguments
 // passed to it. Use api.RunOption for configuration options.

e2e/func-e_run_test.go

@@ -4,28 +4,35 @@
 package e2e
 
 import (
-	"context"
 	"testing"
 
 	"github.com/tetratelabs/func-e/internal/test/e2e"
 )
 
 func TestRun(t *testing.T) {
-	e2e.TestRun(context.Background(), t, funcEFactory{})
+	e2e.TestRun(t.Context(), t, funcEFactory{})
+}
+
+func TestRun_AdminAddressPath(t *testing.T) {
+	e2e.TestRun_AdminAddressPath(t.Context(), t, funcEFactory{})
+}
+
+func TestRun_LogWarn(t *testing.T) {
+	e2e.TestRun_LogWarn(t.Context(), t, funcEFactory{})
 }
 
 func TestRun_RunDirectory(t *testing.T) {
-	e2e.TestRun_RunDirectory(context.Background(), t, funcEFactory{})
+	e2e.TestRun_RunDirectory(t.Context(), t, funcEFactory{})
 }
 
 func TestRun_InvalidConfig(t *testing.T) {
-	e2e.TestRun_InvalidConfig(context.Background(), t, funcEFactory{})
+	e2e.TestRun_InvalidConfig(t.Context(), t, funcEFactory{})
 }
 
 func TestRun_StaticFile(t *testing.T) {
-	e2e.TestRun_StaticFile(context.Background(), t, funcEFactory{})
+	e2e.TestRun_StaticFile(t.Context(), t, funcEFactory{})
 }
 
 func TestRun_CtrlCs(t *testing.T) {
-	e2e.TestRun_CtrlCs(context.Background(), t, funcEFactory{})
+	e2e.TestRun_CtrlCs(t.Context(), t, funcEFactory{})
 }

e2e/func-e_test.go

@@ -14,9 +14,9 @@ import (
 	"runtime"
 	"syscall"
 	"testing"
+	"time"
 
-	"github.com/shirou/gopsutil/v4/process"
-
+	"github.com/tetratelabs/func-e/experimental/admin"
 	"github.com/tetratelabs/func-e/internal/test/build"
 	"github.com/tetratelabs/func-e/internal/test/e2e"
 )
@@ -62,8 +62,8 @@ func readOrBuildFuncEBin() error {
 }
 
 // funcEExec is a temporary adapter for e2e tests except run.
-func funcEExec(args ...string) (string, string, error) {
-	cmd := exec.CommandContext(context.Background(), funcEBin, args...)
+func funcEExec(ctx context.Context, args ...string) (string, string, error) {
+	cmd := exec.CommandContext(ctx, funcEBin, args...)
 	stdout := new(bytes.Buffer)
 	stderr := new(bytes.Buffer)
 	cmd.Stdout = io.MultiWriter(os.Stdout, stdout) // we want to see full `func-e` output in the test log
@@ -85,42 +85,19 @@ type funcE struct {
 	stdout, stderr io.Writer
 }
 
-// OnStart inspects the running func-e process tree to find the Envoy process and its run directory.
-func (a *funcE) OnStart(ctx context.Context) (runDir string, envoyPid int32, err error) {
+// OnStart inspects the running func-e process tree to find the Envoy process and its run directory,
+// then waits for Envoy's admin API to be ready.
+func (a *funcE) OnStart(ctx context.Context) (admin.AdminClient, error) {
 	if a.cmd == nil || a.cmd.Process == nil {
-		return "", 0, fmt.Errorf("no active process")
-	}
-	funcEPid := int32(a.cmd.Process.Pid)
-	funcEProc, err := process.NewProcessWithContext(ctx, funcEPid)
-	if err != nil {
-		return "", 0, fmt.Errorf("failed to get func-e process: %w", err)
-	}
-
-	children, err := funcEProc.Children()
-	if err != nil {
-		return "", 0, fmt.Errorf("failed to get child processes: %w", err)
-	}
-
-	if len(children) == 0 {
-		return "", 0, fmt.Errorf("no child processes found")
+		return nil, fmt.Errorf("no active process")
 	}
+	funcEPid := a.cmd.Process.Pid
 
-	envoyProc := children[0]
-	envoyPidValue := envoyProc.Pid
-
-	// Get command line args to find run directory
-	cmdline, err := envoyProc.CmdlineSlice()
-	if err != nil {
-		return "", 0, fmt.Errorf("failed to get command line of envoy: %w", err)
-	}
-
-	// Look for the run directory in the command line
-	for i, arg := range cmdline {
-		if arg == "--func-e-run-dir" && i+1 < len(cmdline) {
-			return cmdline[i+1], envoyPidValue, nil
-		}
+	adminClient, err := admin.NewAdminClient(ctx, funcEPid)
+	if err == nil {
+		err = adminClient.AwaitReady(ctx, 100*time.Millisecond)
 	}
-	return "", 0, fmt.Errorf("failed to find run dir in envoy args: %v", cmdline)
+	return adminClient, err
 }
 
 // Run invokes `func-e run args...` and blocks until the process exits.

e2e/func-e_use_test.go

@@ -22,7 +22,7 @@ func TestFuncEUse(t *testing.T) {
 	homeDir := t.TempDir()
 
 	t.Run("not yet installed", func(t *testing.T) {
-		stdout, stderr, err := funcEExec("--home-dir", homeDir, "use", version.LastKnownEnvoy.String())
+		stdout, stderr, err := funcEExec(t.Context(), "--home-dir", homeDir, "use", version.LastKnownEnvoy.String())
 		require.NoError(t, err)
 		require.Regexp(t, `^downloading https:.*tar.*z\r?\n$`, stdout)
 		require.Empty(t, stderr)
@@ -38,7 +38,7 @@ func TestFuncEUse(t *testing.T) {
 	})
 
 	t.Run("already installed", func(t *testing.T) {
-		stdout, stderr, err := funcEExec("--home-dir", homeDir, "use", version.LastKnownEnvoy.String())
+		stdout, stderr, err := funcEExec(t.Context(), "--home-dir", homeDir, "use", version.LastKnownEnvoy.String())
 
 		require.NoError(t, err)
 		require.Equal(t, fmt.Sprintf("%s is already downloaded\n", version.LastKnownEnvoy.String()), stdout)
@@ -48,7 +48,7 @@ func TestFuncEUse(t *testing.T) {
 
 func TestFuncEUse_UnknownVersion(t *testing.T) {
 	v := "1.1.1"
-	stdout, stderr, err := funcEExec("use", v)
+	stdout, stderr, err := funcEExec(t.Context(), "use", v)
 
 	require.EqualError(t, err, "exit status 1")
 	require.Empty(t, stdout)
@@ -58,7 +58,7 @@ func TestFuncEUse_UnknownVersion(t *testing.T) {
 
 func TestFuncEUse_UnknownMinorVersion(t *testing.T) {
 	v := "1.1"
-	stdout, stderr, err := funcEExec("use", v)
+	stdout, stderr, err := funcEExec(t.Context(), "use", v)
 
 	require.EqualError(t, err, "exit status 1")
 	require.Regexp(t, `^looking up the latest patch for Envoy version 1.1\r?\n$`, stdout)
@@ -73,15 +73,15 @@ func TestFuncEUse_MinorVersion(t *testing.T) {
 	// The intended minor version to be installed. This version is known to have darwin and linux binaries.
 	minorVersion := "1.24"
 
-	allVersions, _, err := funcEExec("versions", "-a")
+	allVersions, _, err := funcEExec(t.Context(), "versions", "-a")
 	require.NoError(t, err)
 
 	baseVersion, upgradedVersion := getVersionsRange(allVersions, minorVersion)
 
 	homeDir := t.TempDir()
 
 	t.Run("install last known", func(t *testing.T) {
-		stdout, stderr, err := funcEExec("--home-dir", homeDir, "use", version.LastKnownEnvoy.String())
+		stdout, stderr, err := funcEExec(t.Context(), "--home-dir", homeDir, "use", version.LastKnownEnvoy.String())
 
 		require.NoError(t, err)
 		require.Regexp(t, `^downloading https:.*tar.*z\r?\n$`, stdout)
@@ -98,7 +98,7 @@ func TestFuncEUse_MinorVersion(t *testing.T) {
 	})
 
 	t.Run(fmt.Sprintf("install %s as base version", baseVersion), func(t *testing.T) {
-		stdout, stderr, err := funcEExec("--home-dir", homeDir, "use", baseVersion)
+		stdout, stderr, err := funcEExec(t.Context(), "--home-dir", homeDir, "use", baseVersion)
 
 		require.NoError(t, err)
 		require.Regexp(t, `^downloading https:.*tar.*z\r?\n$`, stdout)
@@ -115,7 +115,7 @@ func TestFuncEUse_MinorVersion(t *testing.T) {
 	})
 
 	t.Run(fmt.Sprintf("install %s as upgraded version", upgradedVersion), func(t *testing.T) {
-		stdout, stderr, err := funcEExec("--home-dir", homeDir, "use", minorVersion)
+		stdout, stderr, err := funcEExec(t.Context(), "--home-dir", homeDir, "use", minorVersion)
 
 		require.NoError(t, err)
 		require.Regexp(t, `^looking up the latest patch for Envoy version 1.24\r?\ndownloading https:.*tar.*z\r?\n$`, stdout)
@@ -132,14 +132,14 @@ func TestFuncEUse_MinorVersion(t *testing.T) {
 	})
 
 	t.Run("use upgraded version after downloaded", func(t *testing.T) {
-		stdout, stderr, err := funcEExec("--home-dir", homeDir, "use", minorVersion)
+		stdout, stderr, err := funcEExec(t.Context(), "--home-dir", homeDir, "use", minorVersion)
 		require.NoError(t, err)
 		require.Equal(t, fmt.Sprintf("looking up the latest patch for Envoy version 1.24\n%s is already downloaded\n", upgradedVersion), stdout)
 		require.Empty(t, stderr)
 	})
 
 	t.Run("which upgraded version", func(t *testing.T) {
-		stdout, stderr, err := funcEExec("--home-dir", homeDir, "which")
+		stdout, stderr, err := funcEExec(t.Context(), "--home-dir", homeDir, "which")
 		relativeEnvoyBin := filepath.Join("versions", upgradedVersion, "bin", "envoy"+"")
 		require.Contains(t, stdout, fmt.Sprintf("%s\n", relativeEnvoyBin))
 		require.Empty(t, stderr)

e2e/func-e_version_test.go

@@ -12,7 +12,7 @@ import (
 func TestFuncEVersion(t *testing.T) {
 	t.Parallel()
 
-	stdout, stderr, err := funcEExec("--version")
+	stdout, stderr, err := funcEExec(t.Context(), "--version")
 
 	require.Regexp(t, `^func-e version ([^\s]+)\r?\n$`, stdout)
 	require.Empty(t, stderr)

e2e/func-e_versions_test.go

@@ -17,7 +17,7 @@ import (
 func TestFuncEVersions_NothingYet(t *testing.T) {
 	homeDir := t.TempDir()
 
-	stdout, stderr, err := funcEExec("--home-dir", homeDir, "versions")
+	stdout, stderr, err := funcEExec(t.Context(), "--home-dir", homeDir, "versions")
 
 	require.NoError(t, err)
 	require.Empty(t, stdout)
@@ -27,7 +27,7 @@ func TestFuncEVersions_NothingYet(t *testing.T) {
 func TestFuncEVersions(t *testing.T) {
 	t.Parallel()
 
-	stdout, stderr, err := funcEExec("versions")
+	stdout, stderr, err := funcEExec(t.Context(), "versions")
 
 	// Depending on ~/func-e/version, what's selected may not be the latest version or even installed at all.
 	require.Regexp(t, "[ *] [1-9][0-9]*\\.[0-9]+\\.[0-9]+(_debug)? 202[1-9]-[01][0-9]-[0-3][0-9].*\n", stdout)
@@ -38,7 +38,7 @@ func TestFuncEVersions(t *testing.T) {
 func TestFuncEVersions_All(t *testing.T) {
 	t.Parallel()
 
-	stdout, stderr, err := funcEExec("versions", "-a")
+	stdout, stderr, err := funcEExec(t.Context(), "versions", "-a")
 
 	require.Regexp(t, fmt.Sprintf("[ *] %s 202[1-9]-[01][0-9]-[0-3][0-9].*\n", version.LastKnownEnvoy), stdout)
 	require.Empty(t, stderr)
@@ -50,9 +50,9 @@ func TestFuncEVersions_AllIncludesInstalled(t *testing.T) {
 
 	// Cheap test that one includes the other. It doesn't actually parse the output, but the above tests prove the
 	// latest version is in each deviation.
-	allVersions, _, err := funcEExec("versions", "-a")
+	allVersions, _, err := funcEExec(t.Context(), "versions", "-a")
 	require.NoError(t, err)
-	installedVersions, _, err := funcEExec("versions")
+	installedVersions, _, err := funcEExec(t.Context(), "versions")
 	require.NoError(t, err)
 
 	require.Greater(t, countLines(allVersions), countLines(installedVersions), "expected more versions available than installed")

e2e/func-e_which_test.go

@@ -18,10 +18,10 @@ import (
 // lagging on Homebrew maintenance (OS/x), or lag in someone re-releasing on archive-envoy after Homebrew is updated.
 func TestFuncEWhich(t *testing.T) { // not parallel as it can end up downloading concurrently
 	// Explicitly issue "use" for the last known version to ensure when latest is ahead of this, the test doesn't fail.
-	_, _, err := funcEExec("use", version.LastKnownEnvoy.String())
+	_, _, err := funcEExec(t.Context(), "use", version.LastKnownEnvoy.String())
 	require.NoError(t, err)
 
-	stdout, stderr, err := funcEExec("which")
+	stdout, stderr, err := funcEExec(t.Context(), "which")
 	relativeEnvoyBin := filepath.Join("versions", version.LastKnownEnvoy.String(), "bin", "envoy")
 	require.Contains(t, stdout, fmt.Sprintf("%s\n", relativeEnvoyBin))
 	require.Empty(t, stderr)

e2e/main_test.go

@@ -4,6 +4,7 @@
 package e2e
 
 import (
+	"context"
 	"fmt"
 	"io"
 	"net/http"
@@ -28,7 +29,7 @@ func TestMain(m *testing.M) {
 	}
 
 	// pre-flight check the binary is usable
-	versionLine, _, err := funcEExec("--version")
+	versionLine, _, err := funcEExec(context.Background(), "--version")
 	if err != nil {
 		exitOnInvalidBinary(err)
 	}

experimental/admin/admin.go

@@ -0,0 +1,48 @@
+// Copyright func-e contributors
+// SPDX-License-Identifier: Apache-2.0
+
+package admin
+
+import (
+	"context"
+
+	"github.com/tetratelabs/func-e/api"
+	"github.com/tetratelabs/func-e/internal/admin"
+	internalapi "github.com/tetratelabs/func-e/internal/api"
+)
+
+// AdminClient provides methods to interact with Envoy's admin API.
+//
+// This type alias exposes the internal AdminClient interface for experimental use.
+type AdminClient = internalapi.AdminClient
+
+// NewAdminClient returns an AdminClient if `funcEPid` has a child envoy process.
+func NewAdminClient(ctx context.Context, funcEPid int) (AdminClient, error) {
+	// Poll for the run directory and admin address path from the Envoy process command line
+	runDir, adminAddressPath, err := admin.PollAdminAddressPathAndRunDir(ctx, funcEPid)
+	if err != nil {
+		return nil, err
+	}
+	return admin.NewAdminClient(ctx, runDir, adminAddressPath)
+}
+
+// StartupHook runs once the Envoy admin server is ready. Configure this
+// via the WithStartupHook api.RunOption.
+//
+// Note: Startup hooks are considered mandatory and will stop the run with
+// error if failed. If your hook is optional, rescue panics and log your own
+// errors.
+type StartupHook = internalapi.StartupHook
+
+// WithStartupHook returns a RunOption that sets a startup hook.
+//
+// This is an experimental API that should only be used by CLI entrypoints.
+// See package documentation for usage constraints.
+//
+// If provided, this hook will REPLACE the default config dump hook.
+// If you want to preserve default behavior, do not use this option.
+func WithStartupHook(hook StartupHook) api.RunOption {
+	return func(o *internalapi.RunOpts) {
+		o.StartupHook = hook
+	}
+}