wrapper

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 10, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package wrapper implements the finops-run CLI loop-interception supervisor.

It runs a child CLI agent, watches its output for a loop signal (the proxy's agent_loop_exception 429), and on detection kills the child, clears its loop history on the proxy, and restarts it with a recovery prompt.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultAgentID

func DefaultAgentID(bin string, args []string) string

DefaultAgentID derives a stable 16-hex-char id from the full child command line so restarts of the same command hit the same history bucket. Two concurrent runs of the identical command collide — a documented limitation; use --agent-id to disambiguate.

func Run

func Run(ctx context.Context, cfg Config, bin string, args []string,
	stdin io.Reader, stdout, stderr io.Writer) int

Run executes the child binary under the loop-interception supervision loop and returns the process exit code suitable for os.Exit.

The state machine (WRAPPER_PLAN.md §8): on a loop marker the child is killed, its history cleared on the proxy, and it is restarted with a recovery prompt up to MaxRestarts times. A clean exit 0 returns 0; a non-zero exit without a marker is optionally retried; an external interrupt returns 130.

Types

type Child

type Child struct {
	// contains filtered or unexported fields
}

Child wraps a running child process with the group-kill machinery that guarantees a graceful SIGTERM, a SIGKILL escalation, and reaping without zombies (see WRAPPER_PLAN.md §6).

func (*Child) ExitCode

func (c *Child) ExitCode() int

ExitCode returns the child's exit status suitable for os.Exit: 128+signal for signal-terminated children, otherwise the process exit code.

func (*Child) Wait

func (c *Child) Wait() error

Wait blocks until the child exits and returns its exit error (nil on exit 0). It must be called exactly once per Child; it also stops the watchdog.

type Config

type Config struct {
	// AgentID scopes loop history on the proxy. Empty means "derive from the
	// child command line" (resolved in ParseArgs).
	AgentID string

	// ProxyURL is the base URL of the FinOps proxy (default http://localhost:8080).
	ProxyURL string

	// MaxRestarts caps automatic restarts. -1 is unlimited, 0 means never
	// auto-restart (run once and propagate the child's exit).
	MaxRestarts int

	// RecoveryPrompt is delivered to the child on restart via FINOPS_RECOVERY_PROMPT.
	RecoveryPrompt string

	// Marker is the literal substring that signals a loop (default agent_loop_exception).
	Marker string

	// KillGrace is how long the child gets to shut down on SIGTERM before the
	// process group is SIGKILLed.
	KillGrace time.Duration

	// DeleteTimeout is the HTTP client timeout for the cleanup DELETE call.
	DeleteTimeout time.Duration

	// MaxDeleteRetries is how many times the DELETE is retried on transient failure.
	MaxDeleteRetries int

	// RetryOnNonzero treats a child exit with a non-zero code and no loop
	// marker as a recoverable failure worth one restart attempt.
	RetryOnNonzero bool

	// Watch renders a live status bar by polling the proxy's /v1/metrics.
	Watch bool

	// WatchInterval is the status bar refresh interval.
	WatchInterval time.Duration

	// Version is set by the -version flag; when true ParseArgs returns
	// immediately (no child binary required) so the caller can print the build
	// version and exit.
	Version bool
}

Config holds the tunables for a supervision run. Flag-exposed values live in args.go; the remaining fields are internal knobs with sensible defaults.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns the recommended defaults.

func ParseArgs

func ParseArgs(args []string) (cfg Config, bin string, passthrough []string, err error)

ParseArgs parses finops-run's own flags out of args (os.Args[1:]) and returns the resolved config, the child binary, and its passthrough arguments.

finops-run flags must precede the binary name: stdlib flag stops parsing at the first non-flag argument, so every token after <binary> is passed through untouched — even tokens that collide with finops-run flag names.

type ProxyClient

type ProxyClient struct {
	// contains filtered or unexported fields
}

ProxyClient is a minimal stdlib client for the proxy's control-plane route DELETE /v1/agent/{id}/history.

func NewProxyClient

func NewProxyClient(proxyURL string, timeout time.Duration, maxRetries int) *ProxyClient

NewProxyClient builds a ProxyClient for the given proxy base URL, HTTP timeout, and retry count (negative retries are clamped to zero).

func (*ProxyClient) DeleteHistory

func (c *ProxyClient) DeleteHistory(ctx context.Context, agentID string) error

DeleteHistory clears one agent's loop history on the proxy. It is idempotent: 2xx and 404 (already empty) both mean success. Transient failures (network, 5xx) are retried with backoff; after exhausting retries it returns the last error so the caller can log it and continue (fail-open).

func (*ProxyClient) Metrics

func (c *ProxyClient) Metrics(ctx context.Context) (metricsSnapshot, error)

Metrics fetches the proxy's /v1/metrics snapshot into the local DTO. It is best-effort: a non-2xx or network error is returned so the caller can treat it fail-open.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL