Crate dvm_api 

dvm.run’s REST API: what it takes and returns. dvm.run’s controller serves it, and the SDKs and its panel call it; the controller, the panel and the Rust SDK check a sandbox’s spec with the same code.

A type that holds an invariant (a checked spec, an image reference) keeps its fields private; a plain record of what the controller answers has them public.

Structs

ApiError

What the controller answers instead, when it refuses a request: the body of every response that isn’t a success.

ApiKey

One of a user’s API keys, as they list them: never the key itself, of which the controller keeps only the SHA-256. A request that bears it (Authorization: Bearer <key>) acts as its user.

ByteChunk

Bytes as a program wrote them, or as it’s given them (its stdin, a file written into its sandbox): base64 in JSON, since they needn’t be UTF-8.

Capacity

CPUs and memory: what a runner hands out, and what a run takes of it (SandboxSpec::footprint).

CliLogin

A login from a terminal, as its page shows it to the user who may approve it.

CollectCliLogin

What a terminal asks for its key with: POST /api/cli-logins/key.

CommandNumber

A command’s number in its sandbox’s execution, the controller’s: 1, 2, … in the order the commands were sent. A replay’s commands have their recording’s numbers.

CommandSignal

A signal for a command’s process, POST …/commands/{n}/signal’s body: 15 for SIGTERM, 9 for SIGKILL. It goes to the command’s process alone, not what that started, and to none once it exited.

CreatedApiKey

A key just made, and the key itself: shown this once.

EnvironmentVariable

An environment variable the program is given.

Execution

A sandbox’s execution, GET /api/executions/{id}: what it ran, one log from its start to its end, under its sandbox’s id. Its spec, its seed among it; its run, how and when it ended, and its log’s size; each command it was sent, as it ran; and its replays.

FileMode

A file’s mode, as a file written into a sandbox is made with: its permission bits, at most 0o7777; 0o644 unless given.

ImageReference

A Docker image reference, as docker run takes it: alpine, alpine:3.20, ghcr.io/owner/name:tag, name@sha256:<hex>.

InvalidImageReference

Why a text isn’t an image reference.

InvalidRunAction

An action the run’s state doesn’t allow.

MachineState

What dvm’s kernel holds at a replay’s stop: its processes, as dvm describes them.

Me

The user signed in: GET /api/me.

MemoryRegion

A region of a process’s memory, as /proc/<pid>/maps lists it: its addresses in hex, its protection (r-x), and what it maps, if named.

NewApiKey

A key to make: POST /api/keys.

NewCliLogin

A login to start from a terminal: POST /api/cli-logins, with no session or key.

NewCommand

A command to run in a sandbox, POST /api/sandboxes/{id}/commands’ body.

NewReplay

How to start a replay, POST /api/executions/{id}/replays’ body, which may be left out: played to its end, watching the events watch asks for, if any (WatchedEvents); or held at its start, waiting for a seek, which watches nothing.

OpenFile

An open file of a process: its descriptor, where it leads, as /proc/<pid>/fd/<n> says (a path, pipe:[n], socket:[n]), and its offset.

ProcessState

A process at a stop: its id and its parent’s (0 for the first’s), its name, the program it runs, its directory, its threads, its open files, and its memory’s regions.

ReplayStop

A replay held at a moment, and the machine there: what a seek answers. Seeking back starts the replay again, and goes forward to the moment.

Run

A sandbox’s run, of its spec, recorded; or a replay of its recording.

RunId

A run’s id, the controller’s.

RunOutput

What a run’s program has written so far, as text: bytes that aren’t UTF-8 are replaced.

Sandbox

A sandbox: one run of its spec, recorded, started as it’s made, and the replays of its recording. Its id is its run’s.

SandboxCommand

A command sent to a sandbox, or one its replay ran again.

SandboxDraft

A sandbox’s spec as a person writes it, unchecked: what the panel’s form holds, and what the controller takes to create a sandbox. Each field but the image may be left out, for dvm run’s defaults.

SandboxId

A sandbox’s id: its run’s, as its runner and its output know it.

SandboxPath

A file’s path in a sandbox, checked: absolute, or from its image’s working directory. PUT and GET /api/sandboxes/{id}/files?path= name a file by it.

SandboxSpec

What a sandbox runs, checked: each value is one dvm run may be given as it is. Only a SandboxDraft that passes becomes one, deserialized too.

SandboxesPage

A page of the sandboxes a user sees, GET /api/sandboxes?before=: the newest before the sandbox before, if given, newest first.

Seek

Where to take a replay, POST /api/replays/{id}/seek’s body.

SpecError

Why a draft isn’t a spec: the first field that’s wrong, and how.

StartedCliLogin

A login started: the panel’s page that approves it, the code that page shows, and the token the terminal collects its key with, which only the terminal holds.

StoppedThread

A thread at its stop: the operation it stops before, and what that does, in dvm’s words (syscall 263, a wait's end, by time).

ThreadState

A thread at a stop: its id, its name, its state (Running, Ready, Waiting, as dvm’s kernel names them), and the syscall it waits in, or last waited in, which its state tells apart.

ThreadWait

A syscall a thread waits in: its name and number, and its first argument (a futex’s address, a file’s descriptor), in hex.

Timestamp

A point in time: milliseconds since the Unix epoch, UTC.

UserLimits

What a user who isn’t an admin may use.

WatchKinds

The kinds of events a replay watches. Read and written as a list of kinds; as text, as dvm’s --watch takes them, comma-separated, empty for none.

WatchedEvent

An event a replay watched.

WatchedEvents

What a replay watched, and what it saw: its events, in the order the replay made them, of a kind with more than MOST_OF_A_KIND a sample spread over the run (its first in each thousandth of the run, and every so many beside, about the most); and how many of each kind there were, all of them.

Enums

CommandLine

What a command runs: its argv, as it is, its program found in the sandbox’s PATH; or a script, which the sandbox’s shell runs, /bin/bash -lc if its image has bash, else /bin/sh -c (dvm chooses once, as the sandbox starts). In JSON, an array of strings, or a string.

CommandOutputEvent

What GET /api/sandboxes/{id}/commands/{n}/output?follow=true sends, each event’s data: a command’s output as it’s written, from the offsets asked for, and the command each time it changes. The stream ends once the command ended, after all it wrote.

CommandState

Where a command is:

CommandStdin

A command’s stdin.

EventPosition

Where an event is among its thread’s operations (dvm’s positions).

Moment

Where a replay stops, as dvm names it (its docs/05-replay.md, A moment): before one thread’s operation exactly, or at a time of the recorded run.

OutputStream

One of a program’s output streams.

ReplayVerdict

Whether a replay was the run it replayed, as far as can be seen from outside: its exit code, and its output, byte for byte; a sandbox’s that took commands, each command’s, in their order. A replay that isn’t the run, where dvm sees it, fails instead (RunState::Failed, dvm’s reason).

RunAction

What an owner may do to a sandbox’s run, besides starting it, as it’s made: the last segment of its path, POST /api/sandboxes/{id}/{action}; a replay may be stopped, POST /api/replays/{id}/stop.

RunState

Where a run is:

SpecField

A field of a SandboxDraft.

WatchKind

A kind of event a replay may watch: syscalls of a kind, or page faults.