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 ¶
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).
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 ParseArgs ¶
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).