extension

type Bundle ¶ added in v1.2.0

type Bundle struct {
	Path string
	// contains filtered or unexported fields
}

Bundle is the installed multi-call bundle: the path to its binary and the commands it provides with their help descriptions, taken from the descriptions file.

func LoadBundle(dir string, logger log.Logger) (*Bundle, error)

func (b *Bundle) Description(name string) string

func (b *Bundle) Names() []string

func (b *Bundle) Provides(name string) bool

type Context ¶

type Context struct {
	ConfigDir      string     `json:"configDir"`
	AuthToken      string     `json:"authToken,omitempty"`
	NonInteractive bool       `json:"nonInteractive"`
	JSON           bool       `json:"json"`
	SessionID      string     `json:"sessionId,omitempty"`
	MachineID      string     `json:"machineId,omitempty"`
	EndpointURL    string     `json:"endpointUrl,omitempty"`
	Emulators      []Emulator `json:"emulators"`
}

Context is the resolved runtime context lstk conveys to an extension, rendered as the LSTK_EXT_CONTEXT JSON object. The command boundary populates it (resolving running emulators, config dir, auth token, interactivity, the resolved --json flag, and the telemetry session id) and Environ renders it. An empty AuthToken is omitted from the JSON; Emulators is always present, marshalling to [] when no emulator is running so an extension always decodes a list.

SessionID is lstk's per-process telemetry correlation id, conveyed so an extension emitting its own telemetry can join it to the ext:<name> event lstk records for the same invocation. It is omitted when lstk telemetry is disabled (there is no session to correlate), which means absence is ambiguous to the extension: it cannot tell a telemetry-disabled lstk from an lstk predating the field. Like every field added after version 1 it is detected by presence, not by LSTK_EXT_API_VERSION.

MachineID is the anonymized machine identity lstk stamps on its own telemetry events — already the salted hash, never a raw Docker or system id — conveyed so an extension emitting telemetry reports the same machine without re-deriving it. Conveying it exposes nothing new: it is the prepared hash, and the child environment already carries AuthToken. It is omitted when lstk telemetry is disabled, which a disabled client makes absent together with SessionID (it computes neither), so absence is ambiguous in the same way SessionID's is.

EndpointURL is the endpoint lstk was asked to target instead of a locally managed emulator, resolved with lstk's own source precedence (--endpoint-url, then LSTK_ENDPOINT_URL, then AWS_ENDPOINT_URL) and conveyed verbatim: it is not validated, normalized, or probed. A malformed or unreachable value reaches the extension unchanged on purpose — judging it is the extension's job, and an extension diagnosing a broken endpoint has to see exactly what the user set. It is omitted when no endpoint source was given, i.e. the invocation targets the default local emulator. Note that Emulators is independent of it: that array is what local Docker discovery found, not what lstk was told to target.

func (c Context) Environ(base []string) ([]string, error)

type Emulator ¶

type Emulator struct {
	Type     string `json:"type"`     // emulator type, e.g. "aws", "snowflake", "azure"
	Endpoint string `json:"endpoint"` // full URL, e.g. "http://localhost:4566"
	Port     string `json:"port"`     // resolved host port, e.g. "4566"
}

Emulator describes one running LocalStack emulator in the context payload.

type Extension ¶

type Extension struct {
	Name        string
	Path        string
	Bundled     bool
	Argv0       string
	Description string
}

Extension is a resolved extension executable: its command name (the part after the "lstk-" prefix) and the absolute path to the executable that provides it. Bundled reports whether it was resolved from the bundled-extensions directory (which ships with lstk and takes precedence over PATH) rather than from PATH.

Argv0 is the name the executable is invoked as (its argv[0]). For a standalone lstk-<name> file it is simply the file's own base name; for a command provided by the multi-call bundle (BundledBinaryName) it is "lstk-<name>", which is how that one binary learns which extension to be.

Description is the one-line help text for a bundled extension, taken from the descriptions file beside it. It is empty for PATH extensions (help lists them name-only) and for bundled files the file does not describe. Resolver.List fills it in; Resolve leaves it empty, since dispatch never renders it.

func NewExtension(name, path string, bundled bool) *Extension

type QuietOptions ¶ added in v1.3.0

type QuietOptions struct {
	ConfigDir string
	// AuthToken is conveyed because extensions may refuse to run without it.
	AuthToken string
}

QuietOptions is what a caller of InvokeQuietlyWithJSON chooses. Everything else about the run is fixed by the helper; justify any field added here.

type Resolver ¶

type Resolver struct {
	BundledDir string
	// contains filtered or unexported fields
}

Resolver discovers and resolves extension executables. It searches the bundled-extensions directory (BundledDir) before PATH, so a bundled extension wins over a same-named executable on PATH. A zero BundledDir disables the bundled search (used in tests that exercise only the PATH path).

func NewResolver(logger log.Logger) *Resolver

func (r *Resolver) List() []Extension

func (r *Resolver) Resolve(name string) (*Extension, error)