remote

type Agent interface {
	// Start hands over the work and returns the stream, with the instance that
	// took it when the agent advertises one.
	Start(ctx context.Context, req StartRequest) (Session, error)

	// Resume picks the same execution's stream back up after `after`, AT THE
	// INSTANCE THAT TOOK IT. It returns a GapError when its buffer no longer
	// reaches that far.
	Resume(ctx context.Context, instance, execID string, r Resume) (io.ReadCloser, error)

	// Cancel asks the host to stop the process, at that same instance. See
	// Executor.Cancel for what its error means, which is the part that matters.
	Cancel(ctx context.Context, instance, execID string) error
}

type Executor struct {
	Agent Agent
	Host  string

	// LeaseLimit is how long the stream may go without any line -- including
	// the agent's periodic `alive` -- before the step is failed. Zero takes
	// DefaultLeaseLimit.
	LeaseLimit time.Duration

	// HandOver lets a shutdown leave the step running on its agent, to be
	// reattached by the next scheduler (#125), instead of cancelling it. Only a
	// shutdown: any other end of the run's context still cancels. Off is
	// #122's behaviour.
	HandOver bool

	// Retries is how many times a dropped connection is resumed before the step
	// is failed. Zero takes defaultRetries.
	//
	// It is bounded rather than endless because an agent that drops the
	// connection every second is not a network blip, and retrying forever turns
	// a broken host into a step that never ends.
	Retries int
	// contains filtered or unexported fields
}

type GapError struct {
	Wanted    int64 `json:"wanted"`
	Available int64 `json:"available"`
}

type HTTPAgent struct {
	BaseURL string
	Token   string
	Client  *http.Client

	// StartBackoff is the wait before each further try of a start that ran
	// nothing (#136); its length + 1 is how many tries. Nil takes
	// defaultStartBackoff. A test passes milliseconds.
	StartBackoff []time.Duration

	// Replicas reaches a pool behind one name, and steers a start away from a
	// replica that refused one for draining (#146). Nil dials the name as the
	// system resolves it, which is one agent at one address.
	Replicas *Replicas
}

type Line struct {
	// Seq is monotonic from 1, per execution, and never reused. It is what
	// makes a resumed stream safe: see the package comment, decision 1.
	Seq int64 `json:"seq"`

	Kind    string `json:"kind"`
	Stream  string `json:"stream,omitempty"`
	Message string `json:"message,omitempty"`

	// Code is the process's exit status, on a KindExit line.
	Code int `json:"code,omitempty"`
}

type Replicas struct {
	// Lookup resolves a host to the addresses (host:port) to dial. Nil takes
	// the system resolver. A test passes a map.
	Lookup func(ctx context.Context, host, port string) ([]string, error)

	// TLSClientConfig is for an agent behind a certificate the system does not
	// trust. Nil is the system's roots, as without Replicas.
	TLSClientConfig *tls.Config
	// contains filtered or unexported fields
}

type Resume struct {
	Protocol int    `json:"protocol"`
	After    int64  `json:"after"`
	Reason   string `json:"reason,omitempty"`
}

type Session struct {
	Instance string
	Stream   io.ReadCloser
}

type StartRequest struct {
	Protocol    int    `json:"protocol"`
	ExecutionID string `json:"execution_id"`
	NodeID      string `json:"node_id"`

	// Identifying, not behavioural: they let an operator on the host see which
	// run a process belongs to, which is the whole reason the pod carries them
	// as labels.
	Workflow string `json:"workflow"`
	RunID    string `json:"run_id"`
	Attempt  int    `json:"attempt"`

	Command string            `json:"command"`
	WorkDir string            `json:"workdir,omitempty"`
	Env     map[string]string `json:"env,omitempty"`

	// Secrets is variable-name -> `secret-name/key`, UNRESOLVED, and it is the
	// point of decision 3.
	//
	// The engine does not hold these values and does not learn them. The agent
	// resolves each coordinate against its own store, under its own allowlist,
	// on the host that administers them. That is what the kubelet does for a
	// pod and what the OS does for a local process; sending resolved values
	// over mTLS instead would protect the wire and do nothing about the
	// dispatcher, the task assembly log, or any TaskExec dump somebody writes
	// later -- which is what `TaskExec.Secrets`' own comment was written about.
	//
	// An agent that cannot resolve one must FAIL the step naming the
	// coordinate. Starting a step with a variable silently unset is how a 401
	// three layers down gets blamed on the wrong service.
	Secrets map[string]string `json:"secrets,omitempty"`

	// TimeoutSeconds is zero for no limit, matching TaskExec.Timeout.
	TimeoutSeconds int `json:"timeout_seconds,omitempty"`
}