execution

type Admission struct {
	Profile string
	Limits  Limits
	Network NetworkPolicy
	// Expires is when the task must no longer run. The caller stops it then;
	// a driver refuses to create a task already expired.
	Expires time.Time
}

type AgentGit struct {
	Branch     string
	Base       string `json:",omitempty"`
	BaseCommit string `json:",omitempty"`
}

type AgentImage struct {
	Name   string            `json:"name"`
	Labels map[string]string `json:"labels"`
}

type Build func(ctx context.Context, args ...string) ([]byte, error)

type Capabilities struct {
	PrivateDocker bool // the task can run its own containers
	Terminal      bool // an interactive terminal can attach
	Persistence   bool // the task's files survive it for capture
	Inputs        bool // TaskSpec.Inputs are presented under /apptown/in (inputs.go)
	Results       bool // TaskSpec.Results are captured when the task exits
	Images        bool // TaskSpec.Images are captured when the task exits, and served by file
}

type DockerCLI func(ctx context.Context, stdin io.Reader, args ...string) ([]byte, error)

type DockerSelection struct {
	// Host is the daemon's address, as the docker CLI takes it.
	Host string
	// Context is the context Host was read from, empty when DOCKER_HOST
	// named it.
	Context string
	// Refused is why no address could be pinned: the context could not be
	// read, or it needs TLS files a bare address does not carry. A driver
	// with a refused selection creates nothing and observes nothing until
	// AppTown restarts with a selection that resolves.
	Refused error
	// TLSFromEnvironment is whether the CLI would take TLS settings from
	// DOCKER_TLS_VERIFY, DOCKER_TLS and DOCKER_CERT_PATH for this daemon: it
	// does for DOCKER_HOST and the default context, not for a named context,
	// which carries its own. A call passes them on only then.
	TLSFromEnvironment bool
}

type DockerTasks struct {
	Binary string
	// Now is the clock a task's admission expiry is judged on: the one that
	// wrote it. Nil is the real clock.
	Now func() time.Time
	// Daemon pins the Docker daemon every call uses (SelectDocker). Its
	// address is passed on each call, so nothing the CLI would look up again
	// can move a call to another daemon. A zero Daemon follows the CLI's own
	// selection (the worker's own daemon, tests).
	Daemon DockerSelection
	// Namespace keeps one installation's containers apart from another's on
	// a shared Docker daemon: it is part of every container name.
	Namespace string
	// Files is the folder tasks' generated files are kept in, one folder per
	// task until it is released. "" refuses a task with generated files.
	Files string
	// ToolVersions names the df image a disk read runs in, read once at
	// each admission or read. nil: the disk cannot be read, so new tasks
	// are refused.
	ToolVersions toolversions.Source
	// CallerAdmitsDisk says the caller reads this daemon's data disk before
	// its own first effect of a task (a worker, before the task's workspace
	// or record), so Ensure does not read it again. Otherwise Ensure admits
	// it before anything of the task is written (admitDisk).
	CallerAdmitsDisk bool
}

type File struct {
	Path    string      `json:"path"` // absolute and clean, in the container
	Content []byte      `json:"content"`
	Mode    fs.FileMode `json:"mode"` // permission bits only
}

type FileIdentity struct {
	Path   string      `json:"path"`
	Mode   fs.FileMode `json:"mode"`
	SHA256 string      `json:"sha256"`
}

type History struct {
	Repository string
	Commits    []string
}

type ImageAnswer struct {
	ID     string            `json:"id,omitempty"`
	Labels map[string]string `json:"labels,omitempty"`
	// NotBuilt: nothing was there, and the caller did not allow a build.
	NotBuilt bool   `json:"notBuilt,omitempty"`
	Err      string `json:"err,omitempty"`
}

type ImageCapture struct {
	State  ResultState `json:"state"`
	Reason string      `json:"reason,omitempty"` // refused only
	Size   int64       `json:"size,omitempty"`   // present and too large
}

type ImageFiles interface {
	ImageFile(ctx context.Context, ref TaskRef, image, file string) (io.ReadCloser, int64, error)
}

type ImageLayout struct {
	Files ImageFiles
	Ref   TaskRef
	Image string
}

type ImageRequest struct {
	Tag        string
	Pull       string
	Tree       string // the staged tree a build's context is under
	Context    string // the build context, relative to Tree
	AllowBuild bool
	Registry   *RegistryLogin
	// Anonymous isolates registry authentication without changing the selected daemon.
	Anonymous bool
	Timeout   time.Duration
	// Scratch is where a login's Docker configuration is made, for the one
	// request: a folder its owner sweeps, so a request interrupted mid-pull
	// leaves no credentials behind for long. "" is the system's temporary
	// folder.
	Scratch string
}

type ImageResult struct {
	Name string `json:"name"`
	// Path is under /apptown/state/, never in the tree: the source cannot
	// have put an image there.
	Path string `json:"path"`
	// Max is the admitted size, in bytes, of all the layout's files
	// together; a larger capture is ResultTooLarge.
	Max int64 `json:"max"`
}

type Input struct {
	Blob string      `json:"blob"` // SHA-256 of the blob's tar, hex
	Path string      `json:"path"` // absolute and clean, under /apptown/in/
	Mode fs.FileMode `json:"mode"` // 0644 or 0755
	// contains filtered or unexported fields
}

type Limits struct {
	CPUs        float64
	MemoryBytes int64
	PIDs        int64
	WallClock   time.Duration
}

type NetworkPolicy string

type Outcome struct {
	Output      []byte
	RunErr      error
	TimedOut    bool // compatibility for existing consumers; Termination is authoritative
	Termination Termination
	ExitCode    int // -1 when no normal exit code is available
	CleanupErr  error
	// Report is the requested report's bytes, when it was read; ReportErr
	// says why it was not (missing, not a regular file, too large, or outside
	// the workspace). A caller whose tool declares a report treats a missing
	// one as an error, never as a clean answer.
	Report    []byte
	ReportErr error
}

type OutputPage struct {
	Data []byte
	Next int64 // the cursor after Data
	// Truncated: bytes before Cursor are no longer available.
	Truncated bool
}

type OutputRead struct {
	Cursor int64 // byte offset already read
	Max    int   // at most this many bytes; 0 means a driver default
}

type PrivateDocker struct {
	Daemon   bool                 `json:"daemon,omitempty"`
	Services []deploy.ServiceSpec `json:"services,omitempty"`
	// Mirror is the Docker Hub mirror the daemon and its builder pull
	// through ("" none). Resolvers are the backend's own.
	Mirror string `json:"mirror,omitempty"`
	// Profile is the worker's profile the task was admitted on, as the
	// worker reported it. A worker refuses the request when what it
	// measures now differs (WorkerProfile.Changed).
	Profile *WorkerProfile `json:"profile,omitempty"`
}

type Refusal struct {
	Code   RefusalCode `json:"code,omitempty"`
	Detail string      `json:"detail"`
}

type RefusalCode string

type RegistryLogin struct{ Host, Username, Token string }

type Request struct {
	Workspace    string
	WorkspaceRO  bool
	Mounts       []string
	Argv         []string
	Env          []string
	Timeout      time.Duration
	Image        string
	Name         string
	Network      string
	NoEntrypoint bool
	Labels       []string // key=value, supplied by the owner
	ExtraHosts   []string
	OnLine       func(string)
	// Report names one file the command writes under its workspace, which
	// the answer carries back (Outcome.Report): a caller never reads it off
	// the disk itself, so a check reads the same whichever machine ran it.
	Report string
	// History is a repository presented read-only at /history: the commits
	// a check reads beyond its tree (a landing's history scan).
	History *History
	// ExportImage names an image (by ID) saved to .apptown/image.tar in the
	// workspace before the command runs: an image scan reads the image
	// there, on the machine that has it.
	ExportImage string
	// Files are generated files presented read-only in the container
	// (files.go), written beside the tree by whoever runs it: never in it.
	Files []File
	// FilesDir is where they are written: a folder the caller owns, that
	// does not exist yet. "" is a folder the runner makes under its
	// Scratch, and removes after the run.
	FilesDir string
	// Services run beside a Docker run, on a network of its own that the
	// run joins, each reachable by its name (services.go): made healthy
	// before the command starts and removed with it. The run's Network is
	// then "" (the network reaches out) or "none" (it does not).
	Services []deploy.ServiceSpec
	// Limits, when set, bound this run in place of the runner's own.
	Limits Limits
}

type Result struct {
	Name string `json:"name"`
	Path string `json:"path"`
	Max  int64  `json:"max"` // bytes; a larger file is ResultTooLarge
	// Fresh: any file at Path is removed before the task starts, so what is
	// read after it exits was left by this task.
	Fresh bool `json:"fresh,omitempty"`
}

type ResultFile struct {
	State   ResultState `json:"state"`
	Content []byte      `json:"content,omitempty"` // present only
	Reason  string      `json:"reason,omitempty"`  // refused only
	Size    int64       `json:"size,omitempty"`    // present and too large
}

type ResultState string

type Runner struct {
	DockerBinary string
	// Scratch is where a request's generated files are written when it
	// names no folder of its own: a folder the Docker daemon can mount from.
	// "" is the system's temporary folder.
	Scratch string
	// Refused, when set, refuses every run with it: the project-process
	// runner of an AppTown that runs no project process on its own host.
	Refused error
	// ServiceLimits are each of a request's services' limits (services.go);
	// zero is DefaultServiceLimits.
	ServiceLimits Limits
	// Limits bound every Docker run this runner makes (LimitFlags); a zero
	// field is not bounded. AppTown sets them to its task limits.
	Limits Limits
}

type TaskDriver interface {
	Capabilities() Capabilities
	Ensure(context.Context, TaskSpec) (TaskObservation, error)
	Start(context.Context, TaskRef) error
	Observe(context.Context, TaskRef) (TaskObservation, error)
	// Wait blocks until the task exits and returns its exit code. Cancelling
	// ctx stops waiting, never the task.
	Wait(context.Context, TaskRef) (int, error)
	Stop(context.Context, TaskRef) error
	Output(context.Context, TaskRef, OutputRead) (OutputPage, error)
	// Release removes the task once its result is collected. A task in a
	// shared workspace (TaskSpec.SharedWorkspace) leaves the workspace.
	Release(context.Context, TaskRef) error
	// ReleaseWorkspace removes a shared workspace. It is refused
	// (ErrWorkspaceInUse) while any task in it is not released, and a
	// workspace already gone is released. A driver without shared
	// workspaces returns ErrUnsupported.
	ReleaseWorkspace(ctx context.Context, key string) error
}

type TaskObservation struct {
	ID       string
	State    TaskState
	ExitCode int
	// OOMKilled: Docker killed the task at its memory limit. Its exit code
	// is then not its answer (a killed child in a pipeline can leave 0).
	OOMKilled bool `json:"oomKilled,omitempty"`
	// Request is the request digest the task was created for, where the
	// backend keeps it: a caller acting on a task found by its key alone
	// checks it is its own.
	Request string
}

type TaskRef struct {
	Key        string
	ProviderID string
}

type TaskSource struct {
	Repository string
	Commit     string
}

type TaskSpec struct {
	Key       string
	Admission Admission
	Image     string
	Argv      []string
	Env       []string
	// Workspace is a host directory mounted at /work. Mounts and ExtraHosts
	// are for the local Docker profile's caches and host routing. A remote
	// driver shares no files with AppTown and refuses all three.
	Workspace   string
	WorkspaceRO bool
	Mounts      []string
	ExtraHosts  []string
	Labels      []string
	// Source is the committed tree a remote task works on at /work, sent to
	// the backend as a Git bundle. A local driver refuses it.
	Source *TaskSource
	// SharedWorkspace names a workspace on the backend the task shares with
	// other tasks (the invocations of one agent step attempt) instead of
	// owning one. The workspace is made from Source the first time and must
	// hold that commit after. Releasing the task leaves the workspace;
	// ReleaseWorkspace removes it. Empty: the task owns its workspace, which
	// goes with it. A driver without shared workspaces refuses it.
	SharedWorkspace string `json:",omitempty"`
	// AgentGit, with Source, gives the task a Git repository of its own at
	// /work/.git when its workspace is made (an agent or review step's).
	// Nil: /work has no .git.
	AgentGit *AgentGit `json:",omitempty"`
	// Files are generated files presented read-only in the task's container
	// (files.go). The driver keeps them in a folder the task owns, from
	// before it is created until it is released, and never rewrites them.
	Files []File
	// Inputs are files the task reads under /apptown/in, sent to the backend
	// as content-addressed blobs (inputs.go). Results are files it declares
	// it will leave, captured by the backend when it exits. Both need a
	// backend claiming them (Capabilities).
	// Left out of a request's identity when there are none, so a request
	// without them keeps the identity it had before they existed.
	Inputs  []Input  `json:",omitempty"`
	Results []Result `json:",omitempty"`
	// Images are OCI image layouts a release build declares it will leave
	// in its workspace's state (image_results.go), captured when it exits.
	// A request declaring them carries no environment, inputs or services.
	Images []ImageResult `json:",omitempty"`
	// Private is the task's own network, services and Docker daemon
	// (private.go), on a backend claiming PrivateDocker. Network is the
	// Docker network such a backend joins the task to, which it names
	// itself: WorkerTasks refuses it, as it refuses Mounts.
	Private *PrivateDocker `json:",omitempty"`
	Network string         `json:",omitempty"`
	// Request is the caller's identity for what the task runs, when paths in
	// the spec vary between identical requests (a freshly staged copy).
	// Empty: Digest computes it from the spec.
	Request string
}

type TaskState string

type Termination string

type WorkerAvailability uint8

type WorkerClient struct {
	URL    string
	Client *http.Client
}

type WorkerProfile struct {
	Name          string `json:"name"`
	OS            string `json:"os"`
	Architecture  string `json:"architecture"`
	Kernel        string `json:"kernel"`
	Cgroup        string `json:"cgroup"`
	Docker        string `json:"docker"`
	StorageDriver string `json:"storageDriver"`
	// DindImage is the private daemon's image as the worker is configured
	// with it (a tag, such as docker:27-dind), or "none".
	DindImage string `json:"dindImage"`
	// DindImageID is Docker's local id of that image on the worker: what
	// the worker compares to notice the image changed under a request.
	DindImageID string `json:"dindImageId"`
	// DindDigest is the image's repository digest (RepoDigests), as pulled
	// from its registry; "unknown: ..." for an image without one.
	DindDigest string `json:"dindDigest"`
	// DindVersion is the version the image's own dockerd reports.
	DindVersion string `json:"dindVersion"`
	// Privileged says whether a privileged container ran when probed.
	Privileged string `json:"privileged"`
	// Exclusive is declared by the operator (apptown-worker -exclusive): the
	// machine is the installation's alone. It is not measured.
	Exclusive bool `json:"exclusive"`
	// Egress is never contained in this profile.
	Egress   string    `json:"egress"`
	Measured time.Time `json:"measured"`
}

type WorkerTaskRequest struct {
	Key       string    `json:"key"`
	Admission Admission `json:"admission"`
	Image     string    `json:"image"`
	Argv      []string  `json:"argv"`
	Env       []string  `json:"env"`
	Workspace string    `json:"workspace,omitempty"`
	// Source is the commit the workspace was uploaded with.
	Source string `json:"source,omitempty"`
	// Request is the client's identity for what the task runs. The worker
	// holds a key to it; without one, to the request as sent.
	Request  string   `json:"request,omitempty"`
	ReadOnly bool     `json:"readOnly,omitempty"`
	Labels   []string `json:"labels,omitempty"`
	// Files are generated files the task sees read-only, kept in the
	// task's own folder until it is released.
	Files []File `json:"files,omitempty"`
	// Inputs name blobs sent to the worker, presented read-only under
	// /apptown/in; Results are files captured when the task exits.
	Inputs  []Input  `json:"inputs,omitempty"`
	Results []Result `json:"results,omitempty"`
	// Images are OCI image layouts a release build leaves in its
	// workspace's state, captured when it exits.
	Images []ImageResult `json:"images,omitempty"`
	// Private is the task's own network, services and daemon.
	Private *PrivateDocker `json:"private,omitempty"`
}

type WorkerTasks struct {
	URL    string
	Client *http.Client
	// Now is the clock a task's admission expiry is judged on before it is
	// sent: the one that wrote it. Nil is the real clock.
	Now func() time.Time
	// MaxResultBytes bounds a returned bundle; zero means 256 MiB.
	MaxResultBytes int64
}