stepchild

Documentation

Overview

Package stepchild is the far side of a remote func step: this binary, staged on a target by a coordinator and re-entered there as `senro-<binaryDigest> __step --state-fd 0`, with the step's state as JSON on stdin and length-prefixed frames back on stdout (internal/stepwire is the protocol).

The child is the SAME BUILD as the coordinator, by construction: that is what makes a registry lookup here meaningful, since a function's body is compiled in and nothing about it travels on the wire. The first frame carries this binary's own digest: if the file at the named path is not the file the coordinator put there, everything after is a guess.

senro.Run and senro.RunPlan check for this argv before anything else, so an ordinary main needs no change. A main that parses its own flags and exits on an unrecognised one never reaches that check; senro.StepChild is the front door for such a main to call first.

Index

• Constants
• func Invoked(argv []string) bool
• func Run(ctx context.Context, argv []string, stdin io.Reader, stdout, stderr io.Writer, ...) error
• type Option
  • func WithHalt(fn func(int)) Option

Constants

const ExitProtocol = 70

ExitProtocol is the exit status for a child that could not speak the protocol at all. The value matters less than what it is NOT: never 0, and never 255, which ssh spends on its own transport failures (see sshexec's classify).

const ExitTimedOut = 71

ExitTimedOut is the process exit status when the child stopped itself on the deadline the coordinator gave it.

const Sentinel = "__step"

Sentinel is the argv token a coordinator re-enters a staged binary with. Two leading underscores and absent from usage text: it is one build of senro talking to another, not a command anybody types.

Functions

func Invoked

func Invoked(argv []string) bool

Invoked reports whether argv (os.Args[1:]) is a coordinator's re-entry of this binary. Only the first token is examined, so nothing after it can confuse the answer.

func Run

func Run(
	ctx context.Context, argv []string, stdin io.Reader, stdout, stderr io.Writer, opts ...Option,
) error

Run executes one remote step: read the state, say hello, invoke the function, report the verdict.

The returned error is the CHILD's failure, never the step's: a function error or panic is a verdict and travels in the result frame, while an error here means the protocol itself did not happen. Nothing in this package writes to os.Stderr on its own; stderr belongs to the step.

Types

type Option

type Option func(*config)

Option configures Run.

func WithHalt

func WithHalt(fn func(int)) Option

WithHalt replaces the process-ending call the deadline path makes. Default os.Exit: a function that does not select on its context cannot be made to return by anything short of ending the process, and a remote host is where a function must not be left running forever. A seam only for this package's tests.