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
- Variables
- func BasicAuthHeader(password string) string
- func Check(s Spec) error
- func DefaultRuntime(goos string) string
- func LocalImage(ref string) bool
- func LoopbackURL(port int) *url.URL
- func NewSecret() string
- func Pinned(ref string) bool
- func RedactKeys(s string) string
- func SaveSettings(path string, s Settings) error
- type Backend
- type Choice
- type Container
- type Fake
- func (f *Fake) Add(labels map[string]string, running bool) string
- func (f *Fake) Available(context.Context) Status
- func (f *Fake) Create(_ context.Context, s Spec) (string, error)
- func (f *Fake) EnsureNetwork(_ context.Context, n NetworkSpec) (NetworkInfo, error)
- func (f *Fake) Exit(id string)
- func (f *Fake) Inspect(_ context.Context, id string) (Info, error)
- func (f *Fake) List(_ context.Context, labels map[string]string) ([]Info, error)
- func (f *Fake) Live() int
- func (f *Fake) Logs(_ context.Context, id string, _ int) (string, error)
- func (f *Fake) Pause(_ context.Context, id string) error
- func (f *Fake) Pull(_ context.Context, ref string) error
- func (f *Fake) Remove(_ context.Context, id string) error
- func (f *Fake) Start(_ context.Context, id string) error
- func (f *Fake) Stop(_ context.Context, id string, _ time.Duration) error
- func (f *Fake) Unpause(_ context.Context, id string) error
- type FakeContainer
- type Field
- type GPU
- type Info
- type KasmProxy
- func (p *KasmProxy) Forget(session string)
- func (p *KasmProxy) Path(session string) (string, bool)
- func (p *KasmProxy) Register(session string, upstream *url.URL, password string, ttl time.Duration) (string, error)
- func (p *KasmProxy) ServeHTTP(w http.ResponseWriter, r *http.Request)
- func (p *KasmProxy) Ticket(session string) (string, bool)
- type Lifecycle
- func (l *Lifecycle) Count() int
- func (l *Lifecycle) ForUser(user string) *Container
- func (l *Lifecycle) Get(sessionID string) *Container
- func (l *Lifecycle) Pause(ctx context.Context, sessionID string) error
- func (l *Lifecycle) Reap(ctx context.Context)
- func (l *Lifecycle) Resume(ctx context.Context, sessionID string) error
- func (l *Lifecycle) Run(ctx context.Context)
- func (l *Lifecycle) Start(ctx context.Context, s Spec) (*Container, error)
- func (l *Lifecycle) Stop(ctx context.Context, sessionID string) error
- func (l *Lifecycle) StopAll(ctx context.Context)
- func (l *Lifecycle) StopBecause(ctx context.Context, sessionID, why string) error
- func (l *Lifecycle) SweepOrphans(ctx context.Context) (removed int, err error)
- func (l *Lifecycle) Touch(sessionID string)
- type Limits
- type Mount
- type NetworkInfo
- type NetworkSpec
- type Publish
- type Request
- type Runtime
- type Settings
- type Spec
- type Status
Constants ¶
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.
const ( DefaultMaxContainers = 2 DefaultIdle = 10 * time.Minute DefaultLifetime = 6 * time.Hour )
Defaults for the lifecycle.
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.
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.
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.
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.
const ContainerIO = "/run/wittyplay/io"
ContainerIO is where a Local sandbox finds the socket to WittyPlay.
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.
const LocalNetwork = "isolated"
LocalNetwork is the network a Local spec names: none at all but its own loopback.
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 ¶
var Backends = []Backend{BackendProcess, BackendDockerWebRTC, BackendDockerKasmVNC, BackendLocalWebRTC, BackendHostWebRTC}
Backends lists them, for a settings page.
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.
var ErrNoContainer = errors.New("that session has no container")
ErrNoContainer: that session has no container.
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.
ErrUnavailable is Docker not being reachable. Callers carry on with the process sandbox.
Functions ¶
func BasicAuthHeader ¶
BasicAuthHeader is what the proxy adds, for a test or a health check.
func Check ¶
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 ¶
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 ¶
LocalImage says a reference is an image id on this machine, which can't be pulled.
func LoopbackURL ¶
LoopbackURL is a published KasmVNC port on this machine.
func RedactKeys ¶
RedactKeys hides key material in what an emulator printed, before it reaches a log.
func SaveSettings ¶
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 ¶
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 ¶
Choice is one value a setting may take, and what a page calls it.
func RuntimeChoices ¶
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 ¶
LastLog is the end of what an emulator said before it ended by itself, for the log.
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) EnsureNetwork ¶
func (f *Fake) EnsureNetwork(_ context.Context, n NetworkSpec) (NetworkInfo, error)
type FakeContainer ¶
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.
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) Path ¶
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.
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) Pause ¶
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 ¶
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) Start ¶
Start creates and starts the container for a session. A session has one container: starting it again stops the old one first.
func (*Lifecycle) StopBecause ¶
StopBecause is Stop with a reason of the caller's.
func (*Lifecycle) SweepOrphans ¶
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.
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 LoadSettings ¶
LoadSettings reads settings saved by SaveSettings. A file that isn't there is the defaults.
func (Settings) Clean ¶
Clean checks settings that came from a request and fills in what was left out.
func (Settings) HostPath ¶
HostPath is a folder of this module's as the Docker host sees it: HostPaths' longest match, or the path itself.
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.
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. |