docker

package
v0.7.1 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: AGPL-3.0 Imports: 26 Imported by: 0

Documentation

Overview

Package docker is WittyPlay's optional Docker backend: a standalone emulator (emulators) in a container of its own, one per session. The process sandbox (stream, hostsandbox) stays the default and is what every libretro core runs in. This backend is off until an administrator turns it on, and when Docker can't be reached it says so and nothing else changes.

Only the engine subpackage imports the Docker Engine SDK. Everything else here, and everything that uses this package, speaks the small Runtime interface below with this package's own types, so tests run against a fake (Fake) and nothing but the module's command links the SDK.

Index

Constants

View Source
const (
	RuntimeDocker = "docker" // a Docker (or Podman) daemon
	RuntimeLocal  = "local"  // a display of its own on this machine: bubblewrap on Linux, limits only on FreeBSD
	RuntimeHost   = "host"   // this machine's own desktop and sandbox: macOS and Windows
)

Runtimes an administrator can choose between.

View Source
const (
	DefaultMaxContainers = 2
	DefaultIdle          = 10 * time.Minute
	DefaultLifetime      = 6 * time.Hour
)

Defaults for the lifecycle.

View Source
const (
	LabelManaged = "wittyplay.managed"
	LabelSession = "wittyplay.session"
	LabelUser    = "wittyplay.user"
	LabelEmu     = "wittyplay.emulator"
)

Labels every WittyPlay container carries, so that what a crash left behind can be found and removed at the next start, and nothing else on the machine is ever touched.

View Source
const (
	KasmPort  = 6901 // KasmVNC's web server, plain HTTP inside the network; only the proxy reaches it
	InputPort = 7000 // the input agent: pad states from WittyPlay, over TCP
)

Ports inside a container.

View Source
const (
	DefaultUID       = 1000
	DefaultPids      = 512
	DefaultMemoryMB  = 4096
	DefaultCPUs      = 2.0
	DefaultShmMB     = 512 // Chromium-style GPU stacks and PulseAudio want a real /dev/shm
	DefaultTmpMB     = 256
	DefaultAppMB     = 1536 // an unpacked AppImage: the largest listed is a few hundred MB packed
	DefaultStop      = 20 * time.Second
	ContainerROM     = "/game"     // the game file, read-only
	ContainerSaves   = "/saves"    // this person's saves and settings for this emulator
	ContainerBIOS    = "/bios"     // firmware the person provided, read-only
	ContainerEmuHome = "/home/emu" // HOME, which is a tmpfs: config is linked into /saves
	// ContainerProgram is an emulator installed by the emulators package, read-only, for an
	// image that runs the program it's given rather than one of its own.
	ContainerProgram = "/opt/emulator"
	// ContainerAppRun is where an AppImage unpacks itself (--appimage-extract-and-run): the one
	// place with exec, as FUSE isn't available to an unprivileged container.
	ContainerAppRun = "/run/app"
)

Defaults for a session's container. An administrator can lower or raise the limits; nothing can turn the hardening off.

View Source
const (
	LocalRTPVideo = 5004
	LocalRTPAudio = 5006
)

The ports a Local sandbox's FFmpeg sends RTP to on its own loopback, where the agent picks it up. Nothing outside the sandbox can reach them.

View Source
const ContainerIO = "/run/wittyplay/io"

ContainerIO is where a Local sandbox finds the socket to WittyPlay.

View Source
const HostNetwork = "this-machine"

HostNetwork is the network a Host spec names: the system's own sandbox decides what the emulator may reach (on a Mac and in a FreeBSD jail, nothing), and only the encoder beside it sends anything, to WittyPlay on loopback.

View Source
const LocalNetwork = "isolated"

LocalNetwork is the network a Local spec names: none at all but its own loopback.

View Source
const SandboxPolicy = "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; " +
	"connect-src 'self'; font-src 'self' data:; media-src 'self' blob:; worker-src 'self' blob:; object-src 'none'; " +
	"base-uri 'none'; form-action 'none'; frame-ancestors 'self'; sandbox allow-scripts allow-pointer-lock"

SandboxPolicy is the content policy every answer from a desktop carries, whatever the container sent: its own scripts and its own connection, in a sandbox without the server's origin. A frame that shows it sets the same sandbox.

Variables

Backends lists them, for a settings page.

View Source
var ErrBusy = errors.New("this server is already running as many emulator containers as it allows; stop one first")

ErrBusy is the concurrency limit, in the same words the process sandbox uses.

View Source
var ErrNoContainer = errors.New("that session has no container")

ErrNoContainer: that session has no container.

View Source
var ErrNotPinned = errors.New("the container image isn't pinned to a digest")

ErrNotPinned is an image without a digest. Tags move; a digest doesn't.

View Source
var ErrUnavailable = errors.New("Docker isn't available on this server")

ErrUnavailable is Docker not being reachable. Callers carry on with the process sandbox.

Functions

func BasicAuthHeader

func BasicAuthHeader(password string) string

BasicAuthHeader is what the proxy adds, for a test or a health check.

func Check

func Check(s Spec) error

Check says what's wrong with a Spec, if anything: the same rules Build follows, for a Spec made some other way. The engine runs it before every create, so nothing weaker reaches Docker.

func DefaultRuntime

func DefaultRuntime(goos string) string

DefaultRuntime is what a new server starts with: this machine's own sandbox where there is one that needs no daemon, Docker on Linux (whose own sandbox needs bubblewrap installed).

func LocalImage

func LocalImage(ref string) bool

LocalImage says a reference is an image id on this machine, which can't be pulled.

func LoopbackURL

func LoopbackURL(port int) *url.URL

LoopbackURL is a published KasmVNC port on this machine.

func NewSecret

func NewSecret() string

NewSecret makes a random secret, 32 bytes as hex.

func Pinned

func Pinned(ref string) bool

Pinned says an image reference names a digest.

func RedactKeys

func RedactKeys(s string) string

RedactKeys hides key material in what an emulator printed, before it reaches a log.

func SaveSettings

func SaveSettings(path string, s Settings) error

SaveSettings writes settings in one step.

Types

type Backend

type Backend string

Backend is where a game runs.

const (
	// BackendProcess: the game runner in its own sandboxed process. The default, and the only
	// one for libretro cores.
	BackendProcess Backend = "process"
	// BackendDockerWebRTC: a standalone emulator in a container, captured by FFmpeg inside it
	// and relayed into the same WebRTC session a libretro game has.
	BackendDockerWebRTC Backend = "docker+webrtc"
	// BackendDockerKasmVNC: a standalone emulator in a container, shown through its KasmVNC,
	// reached only through WittyPlay's authenticated proxy. The fallback.
	BackendDockerKasmVNC Backend = "docker+kasmvnc"
)
const BackendHostWebRTC Backend = "host+webrtc"

BackendHostWebRTC: a standalone emulator on this machine's own desktop, in the system's own sandbox (sandbox/host), captured and streamed the way BackendDockerWebRTC is. It's what a game gets when docker.runtime is "host": a Mac or a Windows server.

const BackendLocalWebRTC Backend = "local+webrtc"

BackendLocalWebRTC: a standalone emulator in the sandbox without Docker (sandbox/local), streamed the way BackendDockerWebRTC is. It's what a game gets when docker.runtime is "local"; nobody picks it per emulator.

func Choose

func Choose(s Settings, dockerUp bool, emulatorID, stream string) (Backend, error)

Choose picks the backend for a game. A libretro core always runs as a process. A standalone emulator runs in Docker only when Docker is on and reachable; its list entry says which stream, an administrator's override wins, and "process" means it isn't offered here.

stream is the list's "pipe" or "kasmvnc".

type Choice

type Choice struct {
	Value string `json:"value"`
	Label string `json:"label"`
}

Choice is one value a setting may take, and what a page calls it.

func RuntimeChoices

func RuntimeChoices(goos string) []Choice

RuntimeChoices are the runtimes a server on goos can use, for its settings page.

type Container

type Container struct {
	SessionID string
	UserID    string
	ID        string
	Info      Info
	Started   time.Time
	// contains filtered or unexported fields
}

Container is one session's container.

func (*Container) Done

func (c *Container) Done() <-chan struct{}

Done is closed once the container has been stopped and removed.

func (*Container) LastLog

func (c *Container) LastLog() string

LastLog is the end of what an emulator said before it ended by itself, for the log.

func (*Container) Paused

func (c *Container) Paused() bool

Paused says a session's emulator is frozen.

func (*Container) Reason

func (c *Container) Reason() string

Reason says why it ended: "stopped", "idle", "lifetime", "exited", "replaced" (the same person started another), "unwatched".

type Fake

type Fake struct {
	Down       bool // Available says no, and every call fails
	Containers map[string]*FakeContainer
	Pulled     []string
	Specs      []Spec // every spec created, in order

	// CreateErr, StartErr: the next call fails with it.
	CreateErr, StartErr error
	// Machine, when set, is what Available says of the machine: a small one, for a test.
	Machine *Status
	// contains filtered or unexported fields
}

Fake is a Runtime in memory, for tests here and in packages that use this one.

func (*Fake) Add

func (f *Fake) Add(labels map[string]string, running bool) string

Add puts a container in, as one left by an earlier run would be.

func (*Fake) Available

func (f *Fake) Available(context.Context) Status

func (*Fake) Create

func (f *Fake) Create(_ context.Context, s Spec) (string, error)

func (*Fake) EnsureNetwork

func (f *Fake) EnsureNetwork(_ context.Context, n NetworkSpec) (NetworkInfo, error)

func (*Fake) Exit

func (f *Fake) Exit(id string)

func (*Fake) Inspect

func (f *Fake) Inspect(_ context.Context, id string) (Info, error)

func (*Fake) List

func (f *Fake) List(_ context.Context, labels map[string]string) ([]Info, error)

func (*Fake) Live

func (f *Fake) Live() int

Live counts containers not removed.

func (*Fake) Logs

func (f *Fake) Logs(_ context.Context, id string, _ int) (string, error)

func (*Fake) Pause

func (f *Fake) Pause(_ context.Context, id string) error

Exit makes a container stop by itself.

func (*Fake) Pull

func (f *Fake) Pull(_ context.Context, ref string) error

func (*Fake) Remove

func (f *Fake) Remove(_ context.Context, id string) error

func (*Fake) Start

func (f *Fake) Start(_ context.Context, id string) error

func (*Fake) Stop

func (f *Fake) Stop(_ context.Context, id string, _ time.Duration) error

func (*Fake) Unpause

func (f *Fake) Unpause(_ context.Context, id string) error

type FakeContainer

type FakeContainer struct {
	Info    Info
	Spec    Spec
	Removed bool
}

FakeContainer is one container in a Fake.

type Field

type Field struct {
	Key     string   `json:"key"`
	Kind    string   `json:"kind"` // toggle | number | text | choice | map
	Label   string   `json:"label"`
	Help    string   `json:"help,omitempty"`
	Default any      `json:"default"`
	Min     float64  `json:"min,omitempty"`
	Max     float64  `json:"max,omitempty"`
	Step    float64  `json:"step,omitempty"`
	Choices []Choice `json:"choices,omitempty"`
	// Scope is who may set it. Every setting of the backend is the administrator's.
	Scope string `json:"scope"`
	// MapOf and MapKeys describe a map: what each value is, and the keys it may have.
	MapOf   string   `json:"mapOf,omitempty"`
	MapKeys []Choice `json:"mapKeys,omitempty"`
}

Field describes one setting, for a settings page to draw. Keys are Settings' JSON names. It's the same shape an emulator's own settings have (emulators.Setting), so one form draws both.

func Schema

func Schema(emus []Choice) []Field

Schema is the settings schema of the Docker backend, in the order a page shows it. emus are the emulators the per-emulator maps may name: their ids and names.

type GPU

type GPU struct {
	DRI    bool // /dev/dri: Intel and AMD, and the Mesa stack in the image
	Nvidia bool // the NVIDIA container runtime's device request
}

GPU is optional passthrough, off unless an administrator turns it on.

type Info

type Info struct {
	ID      string            `json:"id"`
	Name    string            `json:"name"`
	Image   string            `json:"image"`
	Running bool              `json:"running"`
	Paused  bool              `json:"paused,omitempty"`
	State   string            `json:"state"`
	Labels  map[string]string `json:"labels,omitempty"`
	// IP is its address on WittyPlay's network.
	IP netip.Addr `json:"ip,omitzero"`
	// HostPorts are published ports, by "6901/tcp", on 127.0.0.1.
	HostPorts map[string]int `json:"hostPorts,omitempty"`
	Created   time.Time      `json:"created"`
}

Info is what's known about a container.

type KasmProxy

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

KasmProxy is the only way to a container's KasmVNC: a reverse proxy that lets a request through only with that session's ticket in its path, and adds the container's own per-session password on the way in. The container's port is never published beyond 127.0.0.1, and the browser never learns the password.

Why the ticket is in the path, and is the whole of the way in. The desktop's page and its scripts come from inside the container, and a container is treated as something that may have been taken over. So that page must never run as one of the server's own: it's shown in a sandboxed frame with an origin of its own (SandboxPolicy), where it can't read the app's storage or ask the server anything as the person signed in. A browser sends no sign-in cookie from such a frame, so the page's own requests, and its WebSocket, can't be told apart by who is signed in. They're told apart by the address: a random 256-bit ticket made for one session, given only to the person who started it, and gone when the game ends.

func (*KasmProxy) Forget

func (p *KasmProxy) Forget(session string)

Forget closes a session's way in.

func (*KasmProxy) Path

func (p *KasmProxy) Path(session string) (string, bool)

Path is where a session's desktop is, on the module's own routes: the session, then its ticket.

func (*KasmProxy) Register

func (p *KasmProxy) Register(session string, upstream *url.URL, password string, ttl time.Duration) (string, error)

Register makes a session reachable through the proxy. upstream is the container's KasmVNC: its address on WittyPlay's network, or 127.0.0.1 and its published port. password is the secret the container was started with. It returns the ticket for the browser.

func (*KasmProxy) ServeHTTP

func (p *KasmProxy) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP serves "<prefix>/<session>/<ticket>/...". prefix is stripped by the caller with http.StripPrefix. Anything without the session's ticket gets the same "not found" a session that doesn't exist gets.

func (*KasmProxy) Ticket

func (p *KasmProxy) Ticket(session string) (string, bool)

Ticket returns a session's ticket, for the server to hand to the person playing.

type Lifecycle

type Lifecycle struct {
	RT          Runtime
	Max         int           // containers at once; DefaultMaxContainers if 0
	Idle        time.Duration // with no input for this long, it's stopped; DefaultIdle if 0
	MaxLifetime time.Duration // however busy, never longer; DefaultLifetime if 0
	Pull        bool          // pull the image before each create (it's pinned, so a cache hit is free)
	Log         *slog.Logger
	Now         func() time.Time // for tests
	// contains filtered or unexported fields
}

Lifecycle runs one container per session, holds them to a limit, and ends those that sit idle or run too long. It owns only containers carrying WittyPlay's labels.

func (*Lifecycle) Count

func (l *Lifecycle) Count() int

Count is how many containers are running.

func (*Lifecycle) ForUser

func (l *Lifecycle) ForUser(user string) *Container

ForUser returns the container a person is playing in, or nil.

func (*Lifecycle) Get

func (l *Lifecycle) Get(sessionID string) *Container

Get returns a session's container, or nil.

func (*Lifecycle) Pause

func (l *Lifecycle) Pause(ctx context.Context, sessionID string) error

Pause freezes a session's emulator, and Resume lets it go on. A paused session still counts against the limit, and is still stopped when it has sat for as long as an idle one may.

func (*Lifecycle) Reap

func (l *Lifecycle) Reap(ctx context.Context)

Reap ends what has sat idle or run too long, and forgets what has exited by itself. The background loop calls it; a test calls it with a clock of its own.

func (*Lifecycle) Resume

func (l *Lifecycle) Resume(ctx context.Context, sessionID string) error

Resume lets a paused emulator go on.

func (*Lifecycle) Run

func (l *Lifecycle) Run(ctx context.Context)

Run reaps until ctx ends. It's started once, however often it's called.

func (*Lifecycle) Start

func (l *Lifecycle) Start(ctx context.Context, s Spec) (*Container, error)

Start creates and starts the container for a session. A session has one container: starting it again stops the old one first.

func (*Lifecycle) Stop

func (l *Lifecycle) Stop(ctx context.Context, sessionID string) error

Stop stops and removes a session's container.

func (*Lifecycle) StopAll

func (l *Lifecycle) StopAll(ctx context.Context)

StopAll ends every container, as the module goes away.

func (*Lifecycle) StopBecause

func (l *Lifecycle) StopBecause(ctx context.Context, sessionID, why string) error

StopBecause is Stop with a reason of the caller's.

func (*Lifecycle) SweepOrphans

func (l *Lifecycle) SweepOrphans(ctx context.Context) (removed int, err error)

SweepOrphans removes every container carrying WittyPlay's label that this Lifecycle didn't start: what a crash or a killed module left. Run it once, at startup.

func (*Lifecycle) Touch

func (l *Lifecycle) Touch(sessionID string)

Touch notes someone playing, which holds off the idle limit.

type Limits

type Limits struct {
	UID      int
	Pids     int64
	MemoryMB int64
	CPUs     float64
	ShmMB    int64
	TmpMB    int64
	AppMB    int64 // the size of ContainerAppRun, for an AppImage
}

Limits on one container.

type Mount

type Mount struct {
	Source   string `json:"source"`
	Target   string `json:"target"`
	ReadOnly bool   `json:"readOnly"`
}

Mount is one folder or file from the host.

type NetworkInfo

type NetworkInfo struct {
	ID       string     `json:"id"`
	Name     string     `json:"name"`
	Internal bool       `json:"internal"`
	Gateway  netip.Addr `json:"gateway,omitzero"` // the host's address on it
}

NetworkInfo is the network as it was found or made.

type NetworkSpec

type NetworkSpec struct {
	Name string
	// Internal: no way out of it, and no published ports. The proxy reaches containers at their
	// address on it, which works where the host shares Docker's network (Linux).
	Internal bool
}

NetworkSpec is WittyPlay's own network.

type Publish

type Publish struct {
	Port   int        `json:"port"`
	Proto  string     `json:"proto"` // tcp | udp
	HostIP netip.Addr `json:"hostIp"`
}

Publish exposes a container port on the host. HostIP is always loopback: Build refuses anything else.

type Request

type Request struct {
	SessionID string
	UserID    int64
	Emulator  string // the id, for the label
	Image     string // pinned reference: repo@sha256:...
	ROM       string // a file
	SaveDir   string // this person's folder for this emulator
	BIOSDir   string // optional
	// ProgramDir is an installed emulator's folder, for an image without one built in. Optional.
	ProgramDir string
	// AppImage says the program in ProgramDir is an AppImage. Only then does the container get
	// ContainerAppRun, the one tmpfs where files may be executed (still nosuid and nodev), for
	// the AppImage to unpack itself into: FUSE isn't available to an unprivileged container.
	// It needs ProgramDir.
	AppImage bool
	Cmd      []string
	Env      []string

	Stream string // "pipe" or "kasmvnc"
	// Network is WittyPlay's bridge network. Empty means "none": no network at all, which
	// leaves only the pipe stream's RTP impossible, so Build refuses that combination.
	Network string
	// PublishLoopback publishes the stream port on 127.0.0.1, for a host that can't reach a
	// container's address on the network (Docker Desktop). Never on another address.
	PublishLoopback bool
	// RTPHost is where the in-container FFmpeg sends RTP: the host's address on Network.
	RTPHost   string
	RTPVideo  int
	RTPAudio  int
	KasmToken string // per-session secret the container's KasmVNC requires
	// InputToken is the per-session secret the input agent requires: inputagent.
	InputToken string

	// Local asks for the sandbox without Docker (sandbox/local): no image, and no network at
	// all. The picture, sound and input cross through a socket in IODir instead.
	Local bool
	// IODir is that socket's folder on the host, for Local only.
	IODir string
	// Host asks for the emulator to run on this machine's own desktop, in the system's own
	// sandbox (sandbox/host: sandbox-exec on a Mac, a job object at low integrity on Windows),
	// captured there and sent as RTP to RTPHost, which must be loopback. No image, no ports.
	Host bool

	// The stream's size, rate and starting bitrate; zero means 1280x720, 60 and 6000 kbit/s.
	Width, Height, FPS, Kbps int
	// Encoder is "x264" (the processor) or "vaapi" (the graphics card, which needs GPU.DRI).
	Encoder string
	// Keys is the input agent's key map as JSON (inputagent.KeyMap), or "" for its own.
	Keys string

	Limits Limits
	GPU    GPU
}

Request is what a session asks for. Paths are on the host and must be absolute; Build checks every one.

type Runtime

type Runtime interface {
	Available(ctx context.Context) Status
	Pull(ctx context.Context, ref string) error
	Create(ctx context.Context, spec Spec) (id string, err error)
	Start(ctx context.Context, id string) error
	Stop(ctx context.Context, id string, timeout time.Duration) error
	Remove(ctx context.Context, id string) error
	// Pause freezes every process in a container, and Unpause lets them go on.
	Pause(ctx context.Context, id string) error
	Unpause(ctx context.Context, id string) error
	Logs(ctx context.Context, id string, tail int) (string, error)
	Inspect(ctx context.Context, id string) (Info, error)
	// List finds containers carrying all of these labels, running or not.
	List(ctx context.Context, labels map[string]string) ([]Info, error)
	EnsureNetwork(ctx context.Context, n NetworkSpec) (NetworkInfo, error)
}

Runtime is what WittyPlay asks of Docker. Every call takes a context, and none may block past it.

type Settings

type Settings struct {
	Enabled bool `json:"docker.enabled"`
	// Runtime is what runs the emulators: "docker" (the default) or "local".
	Runtime string `json:"docker.runtime,omitempty"`
	// Overrides: a backend for an emulator, by its id, over what the list says.
	Overrides map[string]Backend `json:"docker.backend,omitempty"`
	// Network is the name of WittyPlay's own Docker network.
	Network string `json:"docker.network,omitempty"`
	// Internal makes that network internal: no way out to the internet. Set it where the
	// module can reach the containers' addresses directly (Linux without Docker Desktop).
	Internal bool `json:"docker.internal,omitempty"`
	// PublishLoopback publishes the stream ports on 127.0.0.1 instead, for Docker Desktop.
	PublishLoopback bool    `json:"docker.publishLoopback,omitempty"`
	MaxContainers   int     `json:"docker.maxContainers,omitempty"`
	MemoryMB        int64   `json:"docker.memoryMB,omitempty"`
	CPUs            float64 `json:"docker.cpus,omitempty"`
	Pids            int64   `json:"docker.pids,omitempty"`
	IdleMinutes     int     `json:"docker.idleMinutes,omitempty"`
	MaxHours        int     `json:"docker.maxHours,omitempty"`
	GPU             GPU     `json:"docker.gpu"`
	// Images: an image an administrator built (docker/images), by emulator id, over the list's.
	// Each must be pinned to a digest.
	Images map[string]string `json:"docker.images,omitempty"`
	// HostPaths turn this module's own paths into the Docker host's, for a server that runs in
	// a container itself (WittyMediaServer's Docker release): the daemon finds a folder to mount
	// on its host, where the server's /config is wherever its volume is. Folder as the server
	// sees it -> the same folder on the host: {"/config": "/srv/wms/config", "/media": "/volume1/media"}.
	HostPaths map[string]string `json:"docker.hostPaths,omitempty"`
}

Settings are what an administrator sets for the Docker backend. Docker is off until Enabled is set, and with it off nothing here runs and nothing reaches the daemon.

func DefaultSettings

func DefaultSettings() Settings

DefaultSettings: off.

func LoadSettings

func LoadSettings(path string) (Settings, error)

LoadSettings reads settings saved by SaveSettings. A file that isn't there is the defaults.

func (Settings) Clean

func (s Settings) Clean() (Settings, error)

Clean checks settings that came from a request and fills in what was left out.

func (Settings) HostPath

func (s Settings) HostPath(p string) string

HostPath is a folder of this module's as the Docker host sees it: HostPaths' longest match, or the path itself.

func (Settings) Lifecycle

func (s Settings) Lifecycle(rt Runtime) *Lifecycle

Lifecycle makes the lifecycle these settings describe.

func (Settings) Limits

func (s Settings) Limits() Limits

Limits makes container limits from the settings.

type Spec

type Spec struct {
	Name   string
	Image  string
	User   string // uid:gid, never root
	Env    []string
	Cmd    []string
	Labels map[string]string

	ReadOnlyRoot bool
	CapDrop      []string
	CapAdd       []string
	SecurityOpt  []string
	Privileged   bool
	Init         bool

	PidsLimit   int64
	MemoryBytes int64
	NanoCPUs    int64
	ShmBytes    int64
	Tmpfs       map[string]string

	Mounts     []Mount
	Devices    []string // host device paths mapped at the same path, such as /dev/dri
	NvidiaGPUs bool     // ask the NVIDIA runtime for every GPU

	// Local: this is for the sandbox without Docker (sandbox/local), which has no images and
	// no network at all. Docker's engine refuses such a spec.
	Local bool
	// Host: an emulator on this machine's own desktop (sandbox/host). Docker's engine and the
	// local sandbox refuse such a spec.
	Host bool

	Network    string // a network name; "isolated" for Local
	Publish    []Publish
	ExtraHosts []string

	StopTimeout time.Duration
}

Spec is everything a container is created with. Build makes one; the engine turns it into the SDK's types word for word.

func Build

func Build(r Request) (Spec, error)

Build makes the hardened Spec for one session. Everything a container gets is decided here, in one place, and a test checks every field.

type Status

type Status struct {
	Available  bool   `json:"available"`
	Host       string `json:"host"` // DOCKER_HOST, or the default socket
	APIVersion string `json:"apiVersion,omitempty"`
	OS         string `json:"os,omitempty"`
	// Arch is the machine containers run on, in Go's names (amd64, arm64). On Docker Desktop
	// that's the virtual machine, which is where an emulator's download has to fit.
	Arch string `json:"arch,omitempty"`
	// Rootless: the daemon itself doesn't run as root, so reaching it isn't root on this machine.
	Rootless bool `json:"rootless,omitempty"`
	// CPUs and MemoryMB are what the daemon has to give, for refusing what can't run here.
	CPUs     int    `json:"cpus,omitempty"`
	MemoryMB int64  `json:"memoryMB,omitempty"`
	Error    string `json:"error,omitempty"`
}

Status says whether Docker can be used.

Directories

Path Synopsis
Package inputagent carries a player's input into a standalone emulator's container.
Package inputagent carries a player's input into a standalone emulator's container.

Jump to

Keyboard shortcuts

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