wrap

package
v0.18.4 Latest Latest
Warning

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

Go to latest
Published: Oct 22, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package wrap runs one program for a handler, such as a worker, as Wrapped programs in contract.md defines. It checks the program as doctor does, and starts it without the terminal, with an empty stdin. The program gets only the keys that it names, and wrap keeps its output up to a limit. Run turns each failure into the result that the contract defines for it, and the handler's decoder maps the rest. A handler that runs more than one program uses sdk/runner directly.

Pass Run the ctx of the handler, which only a signal ends, so that a deadline of the caller never reads as a signal. Program.Timeout bounds the program instead.

Index

Constants

View Source
const OutputLimit = 1_000_000

OutputLimit is the default bound of what Run keeps of stdout, and of stderr: 1 MB, in the decimal units that the SDK shows.

View Source
const ProbeLimit = 10 * time.Second

ProbeLimit bounds the version probe of a program, within its Timeout.

Variables

This section is empty.

Functions

func Run

func Run(ctx context.Context, call extension.Call, p Program, decode func(Ended) contract.Outcome) contract.Outcome

Run checks the program, then runs it from the caller's folder, and returns what decode makes of its end. A failure that the contract defines never reaches decode. Run answers PREREQ_MISSING for a program that is missing, too old, or whose probe fails or times out. It answers RUNTIME for a timeout, a start that fails, and stdout over the limit. A signal gives the outcome of that signal.

Types

type Ended

type Ended struct {
	// Exit is the exit code of the program.
	Exit int
	// Stdout holds all that the program wrote on stdout.
	Stdout []byte
	// Stderr holds what the program wrote on stderr, up to the limit.
	Stderr []byte
	// contains filtered or unexported fields
}

Ended is how a program ended on its own, which the decoder of Run maps.

func (Ended) Failed

func (e Ended) Failed() contract.Outcome

Failed returns the RUNTIME outcome of an end that the decoder does not map, such as an exit other than 0. A decoder returns it for every exit that it does not know, so no exit code of the program passes through.

func (Ended) Malformed

func (e Ended) Malformed() contract.Outcome

Malformed returns the RUNTIME outcome of output that the decoder cannot read, such as missing or invalid JSON. A decoder returns it, so it never turns a failure into a success.

type Program

type Program struct {
	// Name is a program that the command declares in requires.bins, such as
	// bash. Run looks it up in PATH and probes its version as doctor does.
	Name string
	// Args follow the name, such as the path that Call.Worker returns.
	Args []string
	// Keys holds the services whose keys the program receives, each one that
	// the command declares. Run reads each key through Call.Key, and a key
	// that Call.Key does not return stops the call before any work.
	Keys []string
	// Env sets more variables of the program. Run drops each name that ends
	// in _API_KEY, so a key reaches the program only through Keys.
	Env map[string]string
	// Timeout bounds the probe and the run together. Zero means no bound.
	Timeout time.Duration
	// OutputLimit bounds what Run keeps of stdout, and of stderr, in bytes.
	// Zero means the OutputLimit of the package.
	OutputLimit int
}

Program is one program that a handler runs through Run.

Jump to

Keyboard shortcuts

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