container

package
v0.2.37 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: MIT Imports: 22 Imported by: 0

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

View Source
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
)
View Source
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

View Source
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.

View Source
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

func BlobJobEnv(cfg Config, r *http.Request) map[string]string

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

func ImageAllowed(c Config, image string) bool

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

func MaxTimeoutMSForBudget(size string, budgetUSD float64) int64

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 RunCostUSD(runSeconds int64) float64

func RunSecondsFor

func RunSecondsFor(size string, elapsedMS int64) int64

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

func ValidImageRef(image string) bool

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

func ValidateConfig(cfg map[string]any) error

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

func WorstCaseHoldUSD(size string, timeoutMS int64) float64

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

func ParseConfig(raw map[string]any) Config

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

func (*DockerRunner) Run

func (d *DockerRunner) Run(ctx context.Context, spec RunSpec) (int, error)

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler serves the container data plane.

func NewHandler

func NewHandler(reg *control.Registry, a *auth.Store, store *Store, mux http.Handler) *Handler

func (*Handler) Register

func (h *Handler) Register(mux *http.ServeMux)

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

type Size struct {
	CPUs     int `json:"cpus"`
	MemoryMB int `json:"memory_mb"`
	Factor   int `json:"-"`
}

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 NewStore

func NewStore(runner Runner) *Store

func (*Store) Available

func (s *Store) Available() bool

Available reports whether the runner can run anything.

func (*Store) Cancel

func (s *Store) Cancel(instanceID string, cfg Config, jobID string) (*Job, bool)

Cancel stops a running job. Idempotent: cancelling a finished job does nothing.

func (*Store) Drop

func (s *Store) Drop(instanceID string)

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) Get

func (s *Store) Get(instanceID, jobID string) (*Job, bool)

Get returns one job.

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

func (s *Store) List(instanceID, status string, limit int, before int64) ([]*Job, *int64)

List returns jobs newest-first, optionally filtered by status, with a keyset cursor.

func (*Store) Logs

func (s *Store) Logs(instanceID, jobID string, from int) (LogPage, bool)

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.

func (*Store) OnComplete

func (s *Store) OnComplete(fn func(instanceID string, cfg Config, job *Job))

func (*Store) RunningCount

func (s *Store) RunningCount(instanceID string) int

Jump to

Keyboard shortcuts

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