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