feat(sdk): static stub configuration

pkg/adaptation/adaptation.go

@@ -0,0 +1,59 @@
+package adaptation
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+const (
+	// PluginLaunchedByEngineVar is used to inform engine-launched plugins about their name.
+	PluginLaunchedByEngineVar = "DOCKER_SECRETS_ENGINE_PLUGIN_LAUNCH_CFG"
+	// DefaultPluginRegistrationTimeout is the default timeout for plugin registration.
+	DefaultPluginRegistrationTimeout = 5 * time.Second
+)
+
+func DefaultSocketPath() string {
+	if dir := os.Getenv("XDG_RUNTIME_DIR"); dir != "" {
+ return filepath.Join(dir, "secrets-engine", "engine.sock")
+	}
+	if home, err := os.UserHomeDir(); err == nil {
+ return filepath.Join(home, ".cache", "secrets-engine", "engine.sock")
+	}
+	return filepath.Join(os.TempDir(), "secrets-engine", "engine.sock")
+}
+
+type PluginConfigFromEngine struct {
+	Name string `json:"name"`
+	RegistrationTimeout time.Duration `json:"timeout"`
+	Fd int `json:"fd"`
+}
+
+func (c *PluginConfigFromEngine) ToString() (string, error) {
+	result, err := json.Marshal(c)
+	if err != nil {
+ return "", err
+	}
+	return string(result), nil
+}
+
+func NewPluginConfigFromEngineEnv(in string) (*PluginConfigFromEngine, error) {
+	var result PluginConfigFromEngine
+	if err := json.Unmarshal([]byte(in), &result); err != nil {
+ return nil, fmt.Errorf("failed to decode plugin config from engine %q: %w", PluginLaunchedByEngineVar, err)
+	}
+	if result.Name == "" {
+ return nil, errors.New("plugin name is required")
+	}
+	if result.RegistrationTimeout == 0 {
+ return nil, errors.New("plugin registration timeout is required")
+	}
+	if result.Fd <= 2 {
+ // File descriptors 0, 1, and 2 are reserved for stdin, stdout, and stderr.
+ return nil, errors.New("invalid file descriptor for plugin connection")
+	}
+	return &result, nil
+}

pkg/adaptation/adaptation_test.go

@@ -0,0 +1,75 @@
+package adaptation
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestPluginConfigFromEngine_ToString(t *testing.T) {
+	in := PluginConfigFromEngine{
+ Name: strings.Repeat("ab", 250), // 500 characters
+ RegistrationTimeout: 27 * time.Nanosecond,
+ Fd: 10,
+	}
+	out, err := in.ToString()
+	assert.NoError(t, err)
+	// This is coming from here: https://superuser.com/questions/1070272/why-does-windows-have-a-limit-on-environment-variables-at-all
+	// -> we verify that a plugin name of 500 characters is still within the limit
+	assert.LessOrEqual(t, len(out), 2048)
+	restored, err := NewPluginConfigFromEngineEnv(out)
+	assert.NoError(t, err)
+	assert.Equal(t, in, *restored)
+}
+
+func TestNewPluginConfigFromEngineFromString(t *testing.T) {
+	tests := []struct {
+ name string
+ in PluginConfigFromEngine
+ err string
+	}{
+ {
+ name: "name is empty",
+ err: "name is required",
+ },
+ {
+ name: "registration timeout is zero",
+ in: PluginConfigFromEngine{
+ Name: "test-plugin",
+ },
+ err: "registration timeout is required",
+ },
+ {
+ name: "fd is nonsense",
+ in: PluginConfigFromEngine{
+ Name: "test-plugin",
+ RegistrationTimeout: 10 * time.Second,
+ Fd: 2,
+ },
+ err: "invalid file descriptor",
+ },
+ {
+ name: "valid config",
+ in: PluginConfigFromEngine{
+ Name: "test-plugin",
+ RegistrationTimeout: 10 * time.Second,
+ Fd: 10,
+ },
+ },
+	}
+	for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ out, err := tt.in.ToString()
+ require.NoError(t, err)
+ _, err = NewPluginConfigFromEngineEnv(out)
+ if tt.err != "" {
+ assert.ErrorContains(t, err, tt.err)
+ } else {
+ assert.NoError(t, err)
+ }
+ })
+	}
+}

pkg/stub/config.go

@@ -0,0 +1,128 @@
+package stub
+
+import (
+	"errors"
+	"fmt"
+	"net"
+	"os"
+	"path/filepath"
+	"strconv"
+	"time"
+
+	"github.com/docker/secrets-engine/pkg/adaptation"
+)
+
+// ManualLaunchOption to apply to a plugin during its creation
+// when it's manually launched (not by the secrets engine).
+type ManualLaunchOption func(c *cfg) error
+
+// WithPluginName sets the name to use in plugin registration.
+func WithPluginName(name string) ManualLaunchOption {
+	return func(s *cfg) error {
+ if name == "" {
+ return errors.New("plugin name cannot be empty")
+ }
+ s.name = name
+ return nil
+	}
+}
+
+// WithRegistrationTimeout sets custom registration timeout.
+func WithRegistrationTimeout(timeout time.Duration) ManualLaunchOption {
+	return func(s *cfg) error {
+ s.registrationTimeout = timeout
+ return nil
+	}
+}
+
+// WithConnection sets an existing secrets engine connection to use.
+func WithConnection(conn net.Conn) ManualLaunchOption {
+	return func(s *cfg) error {
+ if s.conn != nil {
+ return errors.New("connection already set")
+ }
+ s.conn = conn
+ return nil
+	}
+}
+
+type cfg struct {
+	plugin Plugin
+	name string
+	conn net.Conn
+	registrationTimeout time.Duration
+}
+
+func newCfg(p Plugin, opts ...ManualLaunchOption) (*cfg, error) {
+	engineCfg, err := restoreConfig(p)
+	if errors.Is(err, errPluginNotLaunchedByEngine) {
+ return newCfgForManualLaunch(p, opts...)
+	}
+	return engineCfg, err
+}
+
+func newCfgForManualLaunch(p Plugin, opts ...ManualLaunchOption) (*cfg, error) {
+	cfg := &cfg{
+ plugin: p,
+ registrationTimeout: adaptation.DefaultPluginRegistrationTimeout,
+	}
+	for _, o := range opts {
+ if err := o(cfg); err != nil {
+ return nil, err
+ }
+	}
+	if cfg.conn == nil {
+ defaultSocketPath := adaptation.DefaultSocketPath()
+ conn, err := net.Dial("unix", defaultSocketPath)
+ if err != nil {
+ return nil, fmt.Errorf("failed to connect to default socket %q: %w", defaultSocketPath, err)
+ }
+ cfg.conn = conn
+	}
+	if cfg.name == "" {
+ if len(os.Args) == 0 {
+ // This should never happen in practice but can happen in tests or when something else empties os.Args for whatever reason.
+ return nil, errors.New("plugin name must be specified (could not derive from os.Args)")
+ }
+ cfg.name = filepath.Base(os.Args[0])
+	}
+	return cfg, nil
+}
+
+var (
+	errPluginNotLaunchedByEngine = errors.New("plugin not launched by secrets engine")
+)
+
+func restoreConfig(p Plugin) (*cfg, error) {
+	cfgString := os.Getenv(adaptation.PluginLaunchedByEngineVar)
+	if cfgString == "" {
+ return nil, errPluginNotLaunchedByEngine
+	}
+	c, err := adaptation.NewPluginConfigFromEngineEnv(cfgString)
+	if err != nil {
+ return nil, err
+	}
+	conn, err := connectionFromFileDescriptor(c.Fd)
+	if err != nil {
+ return nil, fmt.Errorf("invalid socket (%d) in environment: %w", c.Fd, err)
+	}
+	return &cfg{
+ plugin: p,
+ name: c.Name,
+ conn: conn,
+ registrationTimeout: c.RegistrationTimeout,
+	}, nil
+}
+
+func connectionFromFileDescriptor(fd int) (net.Conn, error) {
+	f := os.NewFile(uintptr(fd), "fd #"+strconv.Itoa(fd))
+	if f == nil {
+ return nil, fmt.Errorf("failed to open FD %d", fd)
+	}
+	defer f.Close()
+	conn, err := net.FileConn(f)
+	if err != nil {
+ return nil, fmt.Errorf("failed to create net.Conn for fd #%d: %w", fd, err)
+	}
+	return conn, nil
+}