Documentation
¶
Overview ¶
Package container emulates the altengine container service: a Docker image run as a background job for as long as the work takes.
WHAT IS FAITHFUL, AND WHAT IS NOT ¶
Faithful: the API — start a job and get its id back immediately, poll it, list, cancel — and every bound the hosted service applies before the job starts. The allowed-image list (empty means nothing runs), the per-instance timeout, the concurrency cap, the per-job cost ceiling checked against the worst case, the reserved AE_/environment-name refusals, and the completion callback into a function. A request refused here is refused there, for the same reason and with the same message.
NOT faithful, deliberately:
- Jobs run on YOUR Docker daemon, in whatever isolation you have configured it with. The hosted service runs each job as a single-use machine with no inbound network, no persistent disk and no route back into the platform. Locally a container can reach your network and your daemon can do whatever you have allowed it to. Run images you trust.
- Without a working `docker`, the service refuses with 503 rather than pretending a job ran. A simulated success is the one behaviour that would make this useless: the whole point of running a container is that something happened.
- There is no size difference. `small`, `medium` and `large` are recorded and billed exactly as hosted, so cost estimates match, but the local container gets whatever your daemon gives it — a job that fits in 512 MB here may not fit hosted.
- AE_BLOB_TOKEN bounds nothing. Naming a `blobStore` injects the same two variables a job gets hosted, so an image is written once and runs in both places, but this data plane is dev-open: hosted the token is scoped to one store and refuses delete and publish, and here any bearer works. See blobjob.go.
Index ¶
- Constants
- Variables
- func BlobJobEnv(cfg Config, r *http.Request) map[string]string
- func BuildEnv(in map[string]string, jobID string, platform map[string]string) (map[string]string, error)
- func ImageAllowed(c Config, image string) bool
- func MaxTimeoutMSForBudget(size string, budgetUSD float64) int64
- func RunCostUSD(runSeconds int64) float64
- func RunSecondsFor(size string, elapsedMS int64) int64
- func ValidImageRef(image string) bool
- func ValidateConfig(cfg map[string]any) error
- func WorstCaseHoldUSD(size string, timeoutMS int64) float64
- type Config
- type DockerRunner
- type Handler
- type Job
- type LaunchRequest
- type LogLine
- type LogPage
- type RunSpec
- type Runner
- type Size
- type Store
- func (s *Store) Available() bool
- func (s *Store) Cancel(instanceID string, cfg Config, jobID string) (*Job, bool)
- func (s *Store) Drop(instanceID string)
- func (s *Store) Get(instanceID, jobID string) (*Job, bool)
- func (s *Store) Launch(instanceID string, cfg Config, req LaunchRequest, platform map[string]string) (*Job, error)
- func (s *Store) List(instanceID, status string, limit int, before int64) ([]*Job, *int64)
- func (s *Store) Logs(instanceID, jobID string, from int) (LogPage, bool)
- func (s *Store) OnComplete(fn func(instanceID string, cfg Config, job *Job))
- func (s *Store) RunningCount(instanceID string) int
Constants ¶
const ( // Lines kept per job. A few thousand is enough to see how something failed and small // enough that a hundred finished jobs are still nothing. MaxLogLines = 2000 // One pathological line can be as big as a whole log. MaxLogLineChars = 4000 // Lines returned in one page, matching the hosted cap. LogPageSize = 500 )
const ( DefaultSize = "small" MaxTimeoutMS = int64(60 * 60 * 1000) DefaultTimeoutMS = int64(5 * 60 * 1000) MaxConcurrency = 50 // Rates, matching the hosted pricing rows. Duplicated here for the same reason the hosted // service duplicates them in code: the per-job ceiling has to be computed before the job // starts, and a local estimate that disagreed with the real bill would be worse than none. PricePer1000RunSeconds = 0.02 PricePer1000Jobs = 1.00 MaxEnvVars = 32 MaxEnvBytes = 8192 MaxCmdArgs = 64 MaxCmdArgLen = 4096 MaxListLimit = 100 DefaultLimit = 25 )
Variables ¶
var MaxKeptJobs = 500
MaxKeptJobs is how many jobs an instance's history holds in memory, with their logs. The oldest FINISHED ones go first; a running job is never dropped.
var Sizes = map[string]Size{
"small": {CPUs: 1, MemoryMB: 512, Factor: 1},
"medium": {CPUs: 2, MemoryMB: 2048, Factor: 4},
"large": {CPUs: 4, MemoryMB: 8192, Factor: 12},
}
Functions ¶
func BlobJobEnv ¶
BlobJobEnv is the platform environment for one job's blob access, or nil when the instance names no store — which is exactly the behaviour before this existed.
The store is NOT checked for existence: instances here are created on first use, so a name that does not resolve yet is a store the job is about to create by writing to it.
func BuildEnv ¶
func BuildEnv(in map[string]string, jobID string, platform map[string]string) (map[string]string, error)
BuildEnv validates the caller's variables and appends ours last, so a caller cannot shadow them even if the prefix check ever loosens. `platform` is whatever else the platform injects beyond the job id — today the blob store's URL and token, when the instance names one (blobjob.go). It is added after the caller's budget is checked: a platform credential must not be the thing that pushes a job over a limit the caller was told about.
func ImageAllowed ¶
ImageAllowed reports whether this instance may run the image. An exact tag matches only itself; a trailing ":*" allows any tag of one repository — and must not leak past the repository boundary, so "ghcr.io/me/worker:*" does not admit "ghcr.io/me/worker-evil:v2".
func MaxTimeoutMSForBudget ¶
MaxTimeoutMSForBudget is the longest timeout whose worst case fits a budget. Used to say what WOULD have worked, rather than clamping silently to it.
Round DOWN to whole billable seconds BEFORE converting back to a wall-clock timeout. Flooring after the division instead lets the answer come back a fraction of a second too long, which WorstCaseHoldUSD then rounds up into an extra billable second — so the refusal names a timeout that is itself refused. An error telling you to do something that also fails is worse than no suggestion at all.
func RunCostUSD ¶
func RunSecondsFor ¶
RunSecondsFor is billable seconds: wall-clock scaled by size, rounded up — a job that ran for a tenth of a second still occupied a container that had to be created and destroyed.
func ValidImageRef ¶
ValidImageRef reports whether `image` is a plausible image reference rather than an argument docker would interpret. A job's image is caller-supplied, and an instance whose allowlist is "*" accepts anything — so "--privileged" with a cmd of ["-v","/:/host","alpine","chroot",…] was a root shell on the machine running the emulator.
func ValidateConfig ¶
ValidateConfig is the container instance's config check on a write, with the hosted rules: a value out of range is refused rather than clamped, so a mistake is reported.
func WorstCaseHoldUSD ¶
WorstCaseHoldUSD is the most a job could possibly cost, from its timeout. The per-job ceiling is checked against THIS, so a job that might exceed it never starts.
Types ¶
type Config ¶
type Config struct {
AllowedImages []string `json:"allowedImages"`
MaxTimeoutMS int64 `json:"maxTimeoutMs"`
MaxConcurrent int `json:"maxConcurrent"`
MaxJobCostUSD float64 `json:"maxJobCostUsd"`
OnComplete string `json:"onComplete,omitempty"`
// BlobStore is the blob instance a job launched here may reach, by name. Empty means a job
// gets no blob credential at all — which is what an instance that has not set it does.
BlobStore string `json:"blobStore,omitempty"`
}
Config is a container instance's settings.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig is what a new instance starts with. AllowedImages is EMPTY, and that is the point: an allowlist defaulting to "everything" is not an allowlist, and this is the one service whose literal description is "run code someone else wrote".
func ParseConfig ¶
ParseConfig reads an instance's stored config blob, clamping anything out of range rather than trusting it — an out-of-range stored value is a bug somewhere else, and honouring it would spend money.
type DockerRunner ¶
type DockerRunner struct {
// contains filtered or unexported fields
}
DockerRunner runs jobs on the local Docker daemon.
func (*DockerRunner) Available ¶
func (d *DockerRunner) Available() bool
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler serves the container data plane.
func NewHandler ¶
type Job ¶
type Job struct {
ID string `json:"id"`
Instance string `json:"-"`
Status string `json:"status"` // running | done | failed | canceled
Image string `json:"image"`
Size string `json:"size"`
ExitCode *int `json:"exit_code"`
TimeoutMS int64 `json:"timeout_ms"`
Error string `json:"error,omitempty"`
StartedAt int64 `json:"started_at"`
EndedAt *int64 `json:"ended_at"`
CostUSD float64 `json:"cost_usd"`
// contains filtered or unexported fields
}
Job is one container run.
type LaunchRequest ¶
type LaunchRequest struct {
Image string `json:"image"`
Size string `json:"size"`
Cmd []string `json:"cmd"`
Env map[string]string `json:"env"`
TimeoutMS int64 `json:"timeout_ms"`
}
LaunchRequest is a start-a-job call.
type LogLine ¶
type LogLine struct {
Timestamp string `json:"timestamp"`
Stream string `json:"level,omitempty"` // "stdout" | "stderr", in hosted's `level` slot
Message string `json:"message"`
}
LogLine matches the hosted log shape field for field, so a caller rendering one renders the other.
type LogPage ¶
type LogPage struct {
Lines []LogLine `json:"lines"`
Cursor *int `json:"cursor"`
Note string `json:"note,omitempty"`
}
LogPage is one page of output, oldest first.
type RunSpec ¶
type RunSpec struct {
JobID string
Image string
Cmd []string
Env map[string]string
MemoryMB int
CPUs int
// Where the container's output goes. Nil discards it — which is what os/exec does by
// default, and what this did for every job until logs existed.
Stdout io.Writer
Stderr io.Writer
}
RunSpec is what a runner needs.
type Runner ¶
type Runner interface {
// Available reports whether jobs can run at all. False => the service refuses honestly.
Available() bool
// Run blocks until the container exits, ctx is cancelled, or it fails to start.
Run(ctx context.Context, spec RunSpec) (exitCode int, err error)
}
Runner starts a container and reports how it ended. Swapped out in tests, which is the only way to exercise the lifecycle without a Docker daemon.
type Size ¶
Sizes offered, matching the hosted service. `Factor` scales billed seconds; it is the whole reason one rate can cover every size.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store holds every instance's jobs and runs them.
func (*Store) Cancel ¶
Cancel stops a running job. Idempotent: cancelling a finished job does nothing.
func (*Store) Drop ¶
Drop forgets an instance's jobs, cancelling anything still running — the local equivalent of deleting an instance, where the hosted service destroys the machines first.
func (*Store) Launch ¶
func (s *Store) Launch(instanceID string, cfg Config, req LaunchRequest, platform map[string]string) (*Job, error)
Launch validates everything, starts the container, and returns immediately. `platform` is the environment the platform adds to this job — see BlobJobEnv.
func (*Store) List ¶
List returns jobs newest-first, optionally filtered by status, with a keyset cursor.
func (*Store) Logs ¶
RunningCount is what the console shows and what the concurrency cap is measured against. Logs returns one page of a job's captured output, oldest first.
Best effort, exactly as hosted: a job we no longer hold (the emulator was restarted, or the job predates log capture) gets an empty page with a note rather than an error. The job's own record never depends on this.