Documentation
¶
Overview ¶
Package job is the document a device sends a remote runhost to start one run: the release it verified, what it decided about the run, and what the run needs from the device. It is typed and versioned, and it is the only thing the service reads from a device before it runs anything.
On the wire a job is one length-prefixed JSON document at the start of the `job` verb's input. The service then answers whether it needs the release's archive (FrameRelease); when it does, the archive's bytes follow the document, exactly Release.Size of them.
Index ¶
Constants ¶
const ( StateVerified = "verified" StateUnsigned = "unsigned" StateUnscanned = "unscanned" )
Attestation states a release may arrive in, as the device judged it.
const MaxArchive = 512 << 20
MaxArchive bounds a release archive a job carries: the CLI's own cap on a downloaded archive.
const MaxDocument = 1 << 20
MaxDocument bounds a job document on the wire.
const Version = 1
Version is the job document's version.
Variables ¶
This section is empty.
Functions ¶
func ValidKeyEnv ¶
ValidKeyEnv says whether name may carry a model key into a run on a runhost: a key's name, and none the run's environment reserves.
Types ¶
type Job ¶
type Job struct {
V int `json:"v"`
// ID names the job on the server: its job directory and its sealed
// output. The device makes it.
ID string `json:"id"`
// Device is the id of the device that sent the job, one of the paired
// devices.
Device string `json:"device"`
Release Release `json:"release"`
Run Run `json:"run"`
}
Job is one run on a remote runhost.
type Model ¶
type Model struct {
Provider string `json:"provider"`
Name string `json:"name"`
APIKeyEnv string `json:"apiKeyEnv"`
APIKeyKind string `json:"apiKeyKind,omitempty"`
BaseURL string `json:"baseUrl,omitempty"`
ProxyAllow []string `json:"proxyAllow"`
}
Model is the model a run uses: the device policy's, less where its key comes from, which on the runhost is always the run's environment.
type Release ¶
type Release struct {
Namespace string `json:"namespace"`
Name string `json:"name"`
Version string `json:"version"`
// Digest is the archive's sha256:… digest.
Digest string `json:"digest"`
// Size is the archive's length in bytes.
Size int64 `json:"size"`
// Registry is the registry the release came from.
Registry string `json:"registry"`
// State is the device's verdict: verified, unsigned or unscanned.
State string `json:"state"`
// Attestation is the registry's DSSE envelope for the release, as the
// device fetched it, for a verified release; empty otherwise.
Attestation json.RawMessage `json:"attestation,omitempty"`
// Keys are the signing keys the device holds pinned for Registry. The
// runhost pins them the first time a release from that registry
// arrives, and verifies every later one against its own pins.
Keys trust.KeySet `json:"keys"`
}
Release is the release to run, as the device resolved and verified it.
type Run ¶
type Run struct {
// Task is the run's task text; empty sends the agent its own
// instruction.
Task string `json:"task,omitempty"`
// AllowUnsigned and AllowUnscanned are the person's own flags for this
// run.
AllowUnsigned bool `json:"allowUnsigned,omitempty"`
AllowUnscanned bool `json:"allowUnscanned,omitempty"`
// Adapter is the harness adapter the person asked for. A runhost takes
// only its default, the container harness: the host-process harnesses
// would run outside gVisor.
Adapter string `json:"adapter,omitempty"`
// Timeout, MaxTurns and MaxCost are the person's overrides of the
// policy's budgets; a negative MaxTurns or MaxCost and a zero Timeout
// leave the policy's.
Timeout int `json:"timeout,omitempty"`
MaxTurns int `json:"maxTurns"`
MaxCost float64 `json:"maxCost"`
// Model is the device policy's model, which the run uses in place of
// the runhost's.
Model Model `json:"model"`
// ModelKey is the model's key, read from the device's environment or
// keychain. It lives in the service's memory and the run's environment
// only, and never in a file.
ModelKey string `json:"modelKey,omitempty"`
}
Run is what the device decided about the run.