Skip to content

feat(serve): berth serve --simulate for testing against the API - #73

Merged
helightdev merged 4 commits into
mainfrom
simulated-server
Nov 15, 2026
Merged

helightdev merged 4 commits into
mainfrom
simulated-server

Conversation

@helightdev

Copy link
Copy Markdown
Owner

Adds a simulated berth server so applications can test against the real API in CI without machines, SSH, Ansible or a cloud account.

berth serve --simulate [--listen ADDR] [--seed FILE] [--delay SECONDS] [--data DIR] [--keep] runs the real berth serve (routes, roles, tokens, store, jobs, events, portal) on a scratch directory. Only what would reach another machine is stood in for:

  • Hosts: each is a real berthd in single-user mode in the scratch directory, reached over a link like any host (Host::link returns it while a simulation runs). Its commands go through a small shell of canned commands. It lists and signals only its own processes, and it refuses ports. Until the first apply the link reports no berthd, as on a fresh machine.
  • Apply and install-controller write progress lines over a few steps, then the records a real apply leaves (applied.json, profile.json, actions). After that apply::settle_with runs as usual.
  • Provisioner: the plugin sim holds sim/cloud, with kinds machine (setup apply) and service. It runs as berth simulated-provisioner VERB through the ordinary plugin protocol, and provision::Options waits for nothing.
  • Tailnet: made-up keys, and no requests.
  • Rollout, rotate-key, adopt, trust-key, host-key, seed and installer are unavailable and say why. resources.connect refuses every endpoint.

It is marked everywhere: a berth-simulated: 1 header on every answer, "simulated": true in the server's and each host's version, and simulated in the screens' header.

State goes in a new directory under TMPDIR, removed on Ctrl+C or SIGTERM. XDG_* are pointed into it for the process and what it starts, so it never touches the user's own configuration or socket. --data refuses berth's own directories and any directory that holds something else. BERTH_SIMULATE=1 and BERTH_SIMULATE_SEED turn the published image into a simulated server, because GitHub Actions services cannot change the image's command.

Docs: docs/content/docs/api/testing.mdx covers starting it, the seed format, what is real and what is simulated, timings and a GitHub Actions services: example.

Tests: crates/berth/tests/simulate.rs starts the built berth with a seed and goes through a host's whole life: token login, create through sim/cloud, apply, an action, a session through the portal, stop/start, removal, events through the portal, cleanup on exit. Unit tests cover seed parsing, refusal of the user's own and foreign directories, and the provisioner's states.

Not run here: the container end-to-end shards and an image build (the disk was nearly full), and the Windows and macOS checks (ring needs a cross C toolchain this machine lacks). The client-side changes are platform-neutral or behind cfg(target_os = "linux").

Each host is a berthd in single-user mode in the scratch directory, and its commands run through a shell of a few canned commands. The plugin sim holds the provisioner sim/cloud, which berth runs itself.
Comment thread crates/berth/tests/simulate.rs Fixed
@helightdev
helightdev merged commit adb3356 into main Nov 15, 2026
21 checks passed
@helightdev
helightdev deleted the simulated-server branch November 15, 2026 23:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants