jobsv0

package
v5.8.0 Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package jobsv0 defines the extension point through which the jobs extension exposes its client-facing API on the daemon socket.

A Job is a daemon-managed resource holding a container spec plus a trigger declaration; each execution is a Run with a stable identity that survives container removal. Jobs fire manually or on a cron schedule; the daemon evaluates schedule triggers on its own clock, so scheduled work keeps firing while no client is connected.

Wire-format conventions, constrained by the mobyextgen generator (unary methods only; no enums, oneof, or well-known types):

  • enumerations are documented strings (see the *State and policy constants);
  • timestamps are int64 Unix nanoseconds, zero meaning "not set";
  • the container definition travels as a JSON payload (see JobSpec.ContainerSpec);
  • trigger kinds are mutually exclusive fields on a single message, and a trigger declaring no known kind is rejected rather than interpreted (see Trigger).

Index

Constants

View Source
const (
	// JobStateIdle means no run is currently executing.
	JobStateIdle = "idle"
	// JobStateRunning means a run is pending or running.
	JobStateRunning = "running"
)

Job states. A job is a trigger declaration: it is idle between fires, even when it has never run. Whether the last execution worked lives on the run.

View Source
const (
	// RunStatePending covers the window between run-record creation and
	// container start. A run that fails to create its container goes from
	// pending straight to failed, with Error set and no exit code.
	RunStatePending = "pending"
	// RunStateRunning means the container is executing.
	RunStateRunning = "running"
	// RunStateSucceeded means the container exited zero.
	RunStateSucceeded = "succeeded"
	// RunStateFailed means the container exited nonzero after its restart
	// policy was exhausted, or its creation failed.
	RunStateFailed = "failed"
	// RunStateTimedOut means the run exceeded JobSpec.TimeoutSeconds and was
	// stopped by the daemon.
	RunStateTimedOut = "timed_out"
	// RunStateCancelled means the run was stopped by an explicit Cancel.
	RunStateCancelled = "cancelled"
)

Run states. Terminal states (succeeded, failed, timed_out, cancelled) are sticky: a terminal run never changes again, re-execution creates a new run.

View Source
const (
	// ConcurrencyForbid drops the new fire.
	ConcurrencyForbid = "forbid"
	// ConcurrencyQueue defers a single fire until the current run ends;
	// further fires while one is queued are dropped.
	ConcurrencyQueue = "queue"
)

Concurrency policies, applied when a trigger fires while a run is already in flight. An empty value defaults to forbid.

View Source
const (
	// MissedFiresOne fires a single catch-up run, then re-arms from the next
	// cron tick.
	MissedFiresOne = "one"
	// MissedFiresSkip drops missed fires and re-arms from the next cron tick.
	MissedFiresSkip = "skip"
)

Missed-fire policies, applied when the daemon starts up after schedule fires were missed. An empty value defaults to one.

View Source
const (
	// TriggerKindManual identifies jobs fired only by explicit Run calls.
	TriggerKindManual = "manual"
	// TriggerKindSchedule identifies jobs fired by the cron scheduler.
	TriggerKindSchedule = "schedule"
)

Trigger kinds, as recorded on run evidence and used in list filters.

View Source
const (
	// RunsKeep retains all run records of the removed job.
	RunsKeep = "keep"
	// RunsRemove drops all run records, including terminal ones.
	RunsRemove = "remove"
	// RunsRemoveFinished drops terminal run records and keeps in-flight ones.
	RunsRemoveFinished = "remove-finished"
)

Run-history removal modes for Remove. An empty value defaults to keep.

View Source
const (
	// WaitConditionTerminal waits until the run reaches a terminal state.
	WaitConditionTerminal = "terminal"
	// WaitConditionRunning waits until the run leaves pending.
	WaitConditionRunning = "running"
)

Wait conditions. An empty value defaults to terminal.

View Source
const EnableFlag = "--extension-enable org.mobyproject.jobs.v0"

EnableFlag is the dockerd option enabling the engine's jobs extension.

Variables

View Source
var Point = extensions.DefineSinglePoint[Jobs]("org.mobyproject.extension.jobs.api.v0")

Point is single-cardinality: the jobs API has one authoritative provider, and the host rejects a second one at startup.

Functions

func MapError

func MapError(err error) error

MapError translates the Jobs API's gRPC status codes into containerd/errdefs errors, so callers can reuse the same errdefs.IsXxx checks Compose already applies to the container/network/volume APIs. jobsv0.Jobs methods return raw gRPC errors (extensionclient.Resolve is lazy: unavailability only surfaces as codes.Unimplemented on the first real call), so callers must map each returned error explicitly.

Types

type CancelReply

type CancelReply struct {
	// RunID is the ID of the run that was cancelled, empty if no run was in
	// flight.
	RunID string `pb:"1"`
}

CancelReply reports the cancelled run.

type CancelRequest

type CancelRequest struct {
	// JobRef is the job's ID or name.
	JobRef string `pb:"1"`
}

CancelRequest stops a job's in-flight run.

type CreateAndRunReply

type CreateAndRunReply struct {
	// Job is the resolved job, carrying the daemon-generated name when the
	// request had none.
	Job *Job `pb:"1"`
	// Run is the newly created run.
	Run *Run `pb:"2"`
	// Created is false when the job already existed.
	Created bool `pb:"3"`
}

CreateAndRunReply reports the resolved job and its new run.

type CreateAndRunRequest

type CreateAndRunRequest struct {
	// Name is the job name. Optional when Spec is set; the daemon then
	// generates one.
	Name string `pb:"1"`
	// Spec is the job definition. Optional when Name refers to an existing
	// job.
	Spec *JobSpec `pb:"2"`
}

CreateAndRunRequest atomically registers a job if needed and runs it.

type CreateReply

type CreateReply struct {
	// Job is the registered (or pre-existing identical) job.
	Job *Job `pb:"1"`
	// Created is false when an identical job already existed and the call
	// was a no-op.
	Created bool `pb:"2"`
}

CreateReply reports the registered job.

type CreateRequest

type CreateRequest struct {
	// Name is the job name, unique across the daemon. Required.
	Name string `pb:"1"`
	// Spec is the job definition. Required.
	Spec *JobSpec `pb:"2"`
}

CreateRequest registers a job.

type ExitCode

type ExitCode struct {
	// Value is the container's exit code.
	Value int64 `pb:"1"`
}

ExitCode wraps an exit code so that absence (run never exited) is distinguishable from zero (run exited successfully).

type InspectReply

type InspectReply struct {
	// Job is the inspected job.
	Job *Job `pb:"1"`
}

InspectReply carries the inspected job.

type InspectRequest

type InspectRequest struct {
	// JobRef is the job's ID or name.
	JobRef string `pb:"1"`
}

InspectRequest fetches one job.

type InspectRunReply

type InspectRunReply struct {
	// Run is the inspected run.
	Run *Run `pb:"1"`
}

InspectRunReply carries the inspected run.

type InspectRunRequest

type InspectRunRequest struct {
	// JobRef is the job's ID or name.
	JobRef string `pb:"1"`
	// RunRef is the run's ID, or "latest" for the most recent run.
	RunRef string `pb:"2"`
}

InspectRunRequest fetches one run.

type Job

type Job struct {
	// ID is the daemon-generated stable identifier.
	ID string `pb:"1"`
	// Name is unique across all jobs on the daemon.
	Name string `pb:"2"`
	// Spec is the job definition as submitted, before canonicalization.
	Spec *JobSpec `pb:"3"`
	// SpecHash is the canonical hash of the spec after daemon-side
	// canonicalization. Callers can compare hashes to check spec equality
	// before a Create.
	SpecHash string `pb:"4"`
	// State is the job's execution state. See the JobState constants.
	State string `pb:"5"`
	// Paused reports whether the schedule trigger is suppressed.
	Paused bool `pb:"6"`
	// NextFireAtNano is the next scheduled fire in Unix nanoseconds. Zero
	// when the job is manual, paused, or currently running.
	NextFireAtNano int64 `pb:"7"`
	// CreatedAtNano is the registration time in Unix nanoseconds.
	CreatedAtNano int64 `pb:"8"`
	// UpdatedAtNano is the last state-change time in Unix nanoseconds.
	UpdatedAtNano int64 `pb:"9"`
	// LatestRun is the most recent run, nil if the job never ran.
	LatestRun *Run `pb:"10"`
}

Job is a registered job and its current state.

type JobSpec

type JobSpec struct {
	// ContainerSpec is the JSON-encoded container definition, in the exact
	// format of the container-create API request body (Config, HostConfig,
	// NetworkingConfig). It is decoded and validated by the same path as the
	// container API; unknown fields are rejected. HostConfig.AutoRemove and
	// the always/unless-stopped restart policies are rejected: run outcome
	// capture requires the container to outlive its exit, and a job is
	// expected to terminate.
	ContainerSpec []byte `pb:"1"`
	// Trigger declares what fires the job. A nil Trigger is the manual
	// shorthand; a non-nil Trigger must declare exactly one kind (see
	// Trigger).
	Trigger *Trigger `pb:"2"`
	// Labels are applied to the job itself, not to run containers. Run
	// containers carry the reserved com.docker.job.id and
	// com.docker.job.run-id labels instead.
	Labels map[string]string `pb:"3"`
	// TimeoutSeconds bounds a run's execution; past the deadline the daemon
	// stops the container and the run ends timed_out. Zero means no timeout.
	TimeoutSeconds int64 `pb:"4"`
	// RemoveOnSuccess removes the run container after a successful exit,
	// once the terminal run record is written. Logs are lost with the
	// container; exit code and error are preserved on the run record.
	RemoveOnSuccess bool `pb:"5"`
	// RemoveOnFailure removes the run container after a failed exit. False
	// by default so failed containers are kept for postmortem.
	RemoveOnFailure bool `pb:"6"`
	// RunHistoryLimit caps retained run records, evicting the oldest
	// terminal runs first. The in-flight run is never evicted. Zero means
	// the daemon default of 10000; retaining no history is deliberately
	// not supported.
	RunHistoryLimit uint32 `pb:"7"`
}

JobSpec is the immutable definition of a job. The daemon canonicalizes the spec (applying defaults) before hashing it; the resulting hash is the job's identity for idempotent re-registration.

type Jobs

type Jobs interface {
	// Create registers a job without ever starting a run. It is idempotent on
	// the spec hash: re-submitting the same name+spec is a no-op (Created is
	// false), a new name registers the job (Created is true), and an existing
	// name with a different spec fails with AlreadyExists. Registering a
	// schedule job arms its trigger.
	Create(ctx context.Context, req *CreateRequest) (*CreateReply, error)

	// Run executes an existing job, creating the next run. It fails with
	// FailedPrecondition if the job is already running and its concurrency
	// policy forbids overlap.
	Run(ctx context.Context, req *RunRequest) (*RunReply, error)

	// CreateAndRun atomically registers a job if needed and starts a run.
	// At least one of Name and Spec must be set; a missing name is generated
	// by the daemon. Only manual jobs are served: a manual-trigger spec (or
	// the nil-Trigger shorthand) is required, and a Name resolving to an
	// existing schedule job is rejected with InvalidArgument. The name/spec
	// resolution matrix mirrors Create:
	// same spec runs the existing job, a different spec for an existing name
	// fails with AlreadyExists.
	CreateAndRun(ctx context.Context, req *CreateAndRunRequest) (*CreateAndRunReply, error)

	// Inspect returns a job with its latest run summary.
	Inspect(ctx context.Context, req *InspectRequest) (*InspectReply, error)

	// List returns jobs matching all the given filters.
	List(ctx context.Context, req *ListRequest) (*ListReply, error)

	// Pause suppresses a job's schedule trigger. An in-flight run is not
	// affected, and explicit Run calls still work. Idempotent; a no-op for
	// manual jobs.
	Pause(ctx context.Context, req *PauseRequest) error

	// Resume re-arms a paused job's schedule trigger from the next cron tick.
	// Fires missed while paused are not backfilled. Idempotent.
	Resume(ctx context.Context, req *ResumeRequest) error

	// Cancel stops the job's in-flight run. Triggers keep firing; use Pause
	// to suppress them.
	Cancel(ctx context.Context, req *CancelRequest) (*CancelReply, error)

	// Remove deletes a job, cancelling its in-flight run and disarming its
	// trigger. Run history retention is controlled by RunsRemoval; for
	// retention purposes the run cancelled by Remove itself counts as
	// in-flight, so remove-finished keeps its record.
	Remove(ctx context.Context, req *RemoveRequest) error

	// Prune removes idle manual jobs. Schedule jobs are never pruned: an
	// idle schedule job is armed, not abandoned.
	Prune(ctx context.Context, req *PruneRequest) (*PruneReply, error)

	// ListRuns returns a job's runs, most recent first.
	ListRuns(ctx context.Context, req *ListRunsRequest) (*ListRunsReply, error)

	// InspectRun returns a single run.
	InspectRun(ctx context.Context, req *InspectRunRequest) (*InspectRunReply, error)

	// Wait blocks until the run satisfies the requested condition and
	// returns the run as it is then. A run that jumps past the condition
	// still satisfies it: waiting for running on a run that went straight
	// from pending to a terminal state returns that terminal run. It returns
	// immediately when the condition is already met. Cancelling the request
	// context detaches the caller without affecting the run.
	Wait(ctx context.Context, req *WaitRequest) (*WaitReply, error)
}

Jobs is the jobs service. All methods are unary; blocking semantics (Wait) hold the request open until the condition is met.

Errors are returned as gRPC status codes: InvalidArgument for a spec that fails validation, NotFound for an unknown job or run, AlreadyExists for a Create whose name is taken by a different spec (the message mentions both spec hashes for diagnostics only; the code is the contract), and FailedPrecondition for an execution refused by the concurrency policy.

type ListReply

type ListReply struct {
	// Jobs are the matching jobs. LatestRun is not trimmed: each entry
	// carries the same fields as Inspect.
	Jobs []Job `pb:"1"`
}

ListReply carries the matching jobs.

type ListRequest

type ListRequest struct {
	// Names filters on exact job names.
	Names []string `pb:"1"`
	// Labels filters on job labels, each entry either "key" or "key=value".
	Labels []string `pb:"2"`
	// States filters on job states. See the JobState constants.
	States []string `pb:"3"`
	// TriggerKinds filters on trigger kinds. See the TriggerKind constants.
	TriggerKinds []string `pb:"4"`
	// Paused filters on the paused flag: "true", "false", or empty for both.
	Paused string `pb:"5"`
	// LatestRunStates filters on the state of each job's latest run. See the
	// RunState constants.
	LatestRunStates []string `pb:"6"`
}

ListRequest filters jobs. All filters are conjunctive; within one filter, values are disjunctive, matching the filter semantics of the container API.

type ListRunsReply

type ListRunsReply struct {
	// Runs are the page's runs, most recent first.
	Runs []Run `pb:"1"`
	// NextCursor resumes the listing on the next call, empty on the last
	// page.
	NextCursor string `pb:"2"`
	// CursorStale reports that the requested Before cursor was evicted from
	// history; the listing restarted from the most recent run.
	CursorStale bool `pb:"3"`
}

ListRunsReply carries one page of runs.

type ListRunsRequest

type ListRunsRequest struct {
	// JobRef is the job's ID or name.
	JobRef string `pb:"1"`
	// Limit caps the page size. Zero means the daemon default of 20; a
	// negative value is rejected with InvalidArgument.
	Limit int32 `pb:"2"`
	// Before restricts the page to runs older than the given cursor; pass
	// the previous reply's NextCursor to fetch the next page.
	Before string `pb:"3"`
}

ListRunsRequest pages through a job's runs, most recent first.

type PauseRequest

type PauseRequest struct {
	// JobRef is the job's ID or name.
	JobRef string `pb:"1"`
}

PauseRequest suppresses a job's schedule trigger.

type PruneReply

type PruneReply struct {
	// RemovedJobIDs are the IDs of the removed jobs.
	RemovedJobIDs []string `pb:"1"`
}

PruneReply reports what was pruned.

type PruneRequest

type PruneRequest struct {
	// Labels restricts pruning to jobs matching all entries, each either
	// "key" or "key=value".
	Labels []string `pb:"1"`
}

PruneRequest removes idle manual jobs.

type RemoveRequest

type RemoveRequest struct {
	// JobRef is the job's ID or name.
	JobRef string `pb:"1"`
	// RunsRemoval controls run-history retention. See the Runs constants;
	// empty means keep.
	RunsRemoval string `pb:"2"`
}

RemoveRequest deletes a job.

type ResumeRequest

type ResumeRequest struct {
	// JobRef is the job's ID or name.
	JobRef string `pb:"1"`
}

ResumeRequest re-arms a paused job's schedule trigger.

type Run

type Run struct {
	// ID is the daemon-generated stable identifier, valid across container
	// removal and daemon restarts.
	ID string `pb:"1"`
	// JobID identifies the owning job.
	JobID string `pb:"2"`
	// Iteration is the 1-indexed position of this run in the job's history.
	Iteration uint64 `pb:"3"`
	// ContainerID is the container backing this run. Consumers read run logs
	// from the standard container logs API using this ID; the jobs service
	// does not proxy logs.
	ContainerID string `pb:"4"`
	// ContainerGone reports that the container was removed while the run
	// record was kept; its logs are no longer available.
	ContainerGone bool `pb:"5"`
	// State is the run's execution state. See the RunState constants.
	State string `pb:"6"`
	// CreatedAtNano is the run-record creation time in Unix nanoseconds. The
	// record is written before the container is created, so a run exists
	// even when container creation fails.
	CreatedAtNano int64 `pb:"7"`
	// StartedAtNano is the container start time in Unix nanoseconds, zero if
	// the container never started.
	StartedAtNano int64 `pb:"8"`
	// FinishedAtNano is the terminal-transition time in Unix nanoseconds,
	// zero while the run is in flight.
	FinishedAtNano int64 `pb:"9"`
	// ExitCode is the container's exit code, nil while in flight or when the
	// container never ran.
	ExitCode *ExitCode `pb:"10"`
	// Error describes why a run failed outside the container's own exit,
	// such as a container-create failure or a container lost across a daemon
	// restart.
	Error string `pb:"11"`
	// Trigger records what fired this run.
	Trigger *TriggerEvidence `pb:"12"`
}

Run is a single execution attempt of a job.

type RunReply

type RunReply struct {
	// Run is the newly created run. ContainerID is set once the container
	// is created.
	Run *Run `pb:"1"`
}

RunReply reports the created run.

type RunRequest

type RunRequest struct {
	// JobRef is the job's ID or name.
	JobRef string `pb:"1"`
	// Reschedule makes this fire stand in for the job's next scheduled
	// occurrence, which is skipped; later occurrences keep the cron
	// alignment. Rejected for jobs without a schedule trigger.
	Reschedule bool `pb:"2"`
}

RunRequest executes an existing job.

type ScheduleTrigger

type ScheduleTrigger struct {
	// Cron is a strict five-field POSIX crontab expression. Shortcuts such
	// as @daily are not accepted on the wire; clients expand them.
	Cron string `pb:"1"`
	// Timezone is an IANA timezone name for evaluating the expression.
	// Empty means UTC, never the daemon host's local timezone, so a spec
	// evaluates identically on every host.
	Timezone string `pb:"2"`
	// Concurrency is the policy applied when the schedule fires while a run
	// is in flight. See the Concurrency constants; empty means forbid.
	Concurrency string `pb:"3"`
	// MissedFires is the policy applied to fires missed while the daemon was
	// down. See the MissedFires constants; empty means one.
	MissedFires string `pb:"4"`
}

ScheduleTrigger fires a job on the daemon's clock.

type Trigger

type Trigger struct {
	// Manual declares that the job fires only on explicit Run calls.
	// Mutually exclusive with Schedule.
	Manual bool `pb:"1"`
	// Schedule fires the job on a cron schedule. Mutually exclusive with
	// Manual.
	Schedule *ScheduleTrigger `pb:"2"`
}

Trigger declares what fires a job. Exactly one field must be set.

A nil Trigger on the JobSpec is the manual shorthand; a non-nil Trigger that declares no known kind is rejected with InvalidArgument rather than interpreted. This is deliberate: protobuf silently drops fields it does not know, so a spec using a trigger kind from a newer contract version must fail loudly on an older daemon instead of silently registering as a manual job that never fires. Future trigger kinds (events) are added as new fields under this rule.

type TriggerEvidence

type TriggerEvidence struct {
	// Kind is the trigger kind. See the TriggerKind constants.
	Kind string `pb:"1"`
	// ScheduledAtNano is the cron time the fire was due, in Unix
	// nanoseconds. Zero for manual fires.
	ScheduledAtNano int64 `pb:"2"`
	// FiredAtNano is when the daemon actually fired the run, in Unix
	// nanoseconds.
	FiredAtNano int64 `pb:"3"`
}

TriggerEvidence records what fired a run.

type WaitReply

type WaitReply struct {
	// Run is the run that reached the condition.
	Run *Run `pb:"1"`
}

WaitReply carries the run in its awaited state.

type WaitRequest

type WaitRequest struct {
	// JobRef is the job's ID or name.
	JobRef string `pb:"1"`
	// RunRef is the run's ID, or "latest" (also the default when empty).
	// For an idle schedule job, "latest" resolves to the next run to fire,
	// so the call may block until the next cron tick.
	RunRef string `pb:"2"`
	// Condition is the state to wait for. See the WaitCondition constants;
	// empty means terminal.
	Condition string `pb:"3"`
}

WaitRequest blocks until a run reaches a condition.

Directories

Path Synopsis
Code generated by mobyextgen.
Code generated by mobyextgen.

Jump to

Keyboard shortcuts

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