From ca4865447cb492be34861bebee4da6a30d27ef77 Mon Sep 17 00:00:00 2001 From: Thales Maciel Date: Wed, 15 Apr 2026 16:44:11 -0300 Subject: [PATCH] Refresh daemon docs and mark web UI experimental MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit internal/daemon/doc.go and ARCHITECTURE.md were written before the subpackage extractions and still referenced old structure (in-progress phrasing, missing opstate/dmsnap/fcproc/imagemgr/session/workspace, mentions of opRegistry by its old name). Both now describe the current shape: composition root + six leaf subpackages, lock ordering rooted at vmLocks[id], and the one intra-package dependency (workspace → session for ShellQuote + FormatStepError). README.md and AGENTS.md mark the local web UI as experimental. It is still enabled by default at 127.0.0.1:7777, but the docs now state plainly that its surface is not stable or hardened and not intended for anything beyond single-user localhost use. AGENTS.md also points at ARCHITECTURE.md for the subpackage layout. No code changes; tests still green. Co-Authored-By: Claude Sonnet 4.6 --- AGENTS.md | 3 +- README.md | 11 +++-- internal/daemon/ARCHITECTURE.md | 52 ++++++++++++++++------ internal/daemon/doc.go | 76 ++++++++++++++++++++++----------- 4 files changed, 99 insertions(+), 43 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e6c5039..1a5f801 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,7 +5,8 @@ Always run `make build` before commit. ## Project Structure - `cmd/banger` and `cmd/bangerd` are the main user entrypoints. -- `internal/` contains the daemon, CLI, RPC, storage, Firecracker integration, guest helpers, and web UI. +- `internal/` contains the daemon, CLI, RPC, storage, Firecracker integration, guest helpers, and the experimental web UI. +- `internal/daemon/` is the composition root; pure helpers live in its subpackages (`opstate`, `dmsnap`, `fcproc`, `imagemgr`, `session`, `workspace`). See `internal/daemon/ARCHITECTURE.md`. - `scripts/` contains explicit manual helper workflows for rootfs and kernel preparation. - `build/bin/` is the canonical source-checkout build output. - `build/manual/` is the canonical source-checkout location for manual rootfs/kernel artifacts. diff --git a/README.md b/README.md index 401d389..f1960fc 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # banger -`banger` manages Firecracker development VMs with a local daemon, managed image artifacts, and a localhost web UI. +`banger` manages Firecracker development VMs with a local daemon, managed image artifacts, and an experimental localhost web UI. ## Requirements @@ -152,12 +152,17 @@ If you want reusable orchestration primitives instead of the `vm run` convenienc `vm session attach` is currently exclusive and same-host only. The daemon exposes a local Unix socket bridge using `stdio_mux_v1`, so only one active attach is allowed at a time. Pipe-mode sessions keep enough guest-side state for the daemon to rebuild that bridge after a daemon restart. -## Web UI +## Web UI (experimental) -`bangerd` serves a local web UI by default at: +`bangerd` serves an experimental local web UI by default at: - `http://127.0.0.1:7777` +The UI is convenient for local observability but is **not a stable or +supported interface**. Its endpoints, layout, and behaviour may change +without notice, and it has not been hardened for anything beyond single-user +localhost use. Do not expose the listen address to a shared network. + See the effective URL with: ```bash diff --git a/internal/daemon/ARCHITECTURE.md b/internal/daemon/ARCHITECTURE.md index da61adf..306d7d9 100644 --- a/internal/daemon/ARCHITECTURE.md +++ b/internal/daemon/ARCHITECTURE.md @@ -1,13 +1,12 @@ # `internal/daemon` architecture -This document captures the current (pre-refactor) layout of the daemon -package and the lock ordering its callers must respect. It is the baseline -against which the phased split described in -`~/.claude/plans/fluffy-seeking-teapot.md` is executed. +This document describes the current daemon package layout: the `Daemon` +composition root, the subpackages that own stateless helpers and shared +primitives, and the lock ordering every caller must respect. ## Composition -`Daemon` is the composition root. Subsystem state and locks have moved onto +`Daemon` is the composition root. Subsystem state and locks live on their owning types: - Layout, config, store, runner, logger, pid — infrastructure handles. @@ -16,18 +15,37 @@ owning types: + guest IP allocation window). - `imageOpsMu sync.Mutex` — serialises image-registry mutations (`BuildImage`, `RegisterImage`, `PromoteImage`, `DeleteImage`). -- `createOps opRegistry[*vmCreateOperationState]` — in-flight VM create - operations, owns its own lock. -- `imageBuildOps opRegistry[*imageBuildOperationState]` — in-flight image - build operations, owns its own lock. +- `createOps opstate.Registry[*vmCreateOperationState]` — in-flight VM + create operations; owns its own lock. +- `imageBuildOps opstate.Registry[*imageBuildOperationState]` — in-flight + image build operations; owns its own lock. - `tapPool tapPool` — TAP interface pool; owns its own lock. -- `sessions sessionRegistry` — active guest session controllers; owns its - own lock. +- `sessions sessionRegistry` — active guest session controllers; owns + its own lock. - `listener`, `webListener`, `webServer`, `webURL`, `vmDNS` — networking. - `vmCaps` — registered VM capability hooks. - `imageBuild`, `requestHandler`, `guestWaitForSSH`, `guestDial`, `waitForGuestSessionReady` — injectable seams used by tests. +## Subpackages + +Pure helpers have moved into subpackages so the daemon package itself stays +focused on orchestration. Each subpackage takes explicit dependencies +(typically a `system.Runner`-compatible interface) and holds no global +state beyond small test seams. + +| Subpackage | Purpose | +| --------------------------------- | ---------------------------------------------------------------------- | +| `internal/daemon/opstate` | Generic `Registry[T AsyncOp]` for async-operation bookkeeping. | +| `internal/daemon/dmsnap` | Device-mapper COW snapshot create/cleanup/remove. | +| `internal/daemon/fcproc` | Firecracker process primitives (bridge, tap, binary, PID, kill, wait). | +| `internal/daemon/imagemgr` | Image subsystem pure helpers: validators, staging, build script gen. | +| `internal/daemon/session` | Guest-session helpers: state paths, scripts, parsing, utilities. | +| `internal/daemon/workspace` | Workspace helpers: git inspection, copy prep, guest import script. | + +`workspace` imports `session` for `ShellQuote` and `FormatStepError`; all +other subpackages are leaves (no other intra-daemon subpackage imports). + ## Lock ordering Acquire in this order, release in reverse. Never acquire in the opposite @@ -37,9 +55,9 @@ direction. vmLocks[id] → {createVMMu, imageOpsMu} → subsystem-local locks ``` -Subsystem-local locks (tapPool.mu, sessionRegistry.mu, opRegistry.mu, -guestSessionController.attachMu/writeMu) are leaves. They do not contend -with each other. +Subsystem-local locks (`tapPool.mu`, `sessionRegistry.mu`, +`opstate.Registry` mu, `guestSessionController.attachMu` / +`writeMu`) are leaves. They do not contend with each other. Notes: @@ -62,3 +80,9 @@ Only `internal/cli` imports this package. The surface is: All other `*Daemon` methods are reached only through the RPC `dispatch` switch in `daemon.go` and are free to move/rename during refactoring. + +## Web UI + +The optional web UI served at `web_listen_addr` is experimental. It is +enabled by default for local observability but is not considered a stable +or supported interface. Set `web_listen_addr = ""` in config to disable. diff --git a/internal/daemon/doc.go b/internal/daemon/doc.go index 395a516..0f66d4b 100644 --- a/internal/daemon/doc.go +++ b/internal/daemon/doc.go @@ -1,61 +1,87 @@ // Package daemon hosts the Banger daemon process. // // The daemon exposes a JSON-RPC endpoint over a Unix socket and, optionally, -// a local web UI. It owns VM lifecycle, image management, guest sessions, -// host networking bootstrap, and state persistence via internal/store. +// an experimental local web UI. It owns VM lifecycle, image management, +// guest sessions, host networking bootstrap, and state persistence via +// internal/store. // -// The package is organised into cohesive groups. A phased refactor is -// splitting each group into a subpackage; file names below reflect the -// current (in-progress) grouping. +// The package is organised into cohesive groups. Pure stateless helpers for +// each group have been lifted into subpackages; orchestrator methods +// (Daemon receivers) stay here and compose them. // -// VM lifecycle: +// Subpackages: +// +// internal/daemon/opstate Generic Registry[T AsyncOp] for async +// operations (VM create, image build). +// internal/daemon/dmsnap Device-mapper COW snapshot lifecycle. +// internal/daemon/fcproc Firecracker process helpers: bridge/tap, +// binary resolution, PID lookup, wait/kill. +// internal/daemon/imagemgr Image subsystem helpers: path validation, +// artifact staging, guest provisioning script +// generator, metadata. +// internal/daemon/session Guest-session helpers: state paths, runner +// / inspect / signal scripts, state snapshot +// parsing, launch helpers, ShellQuote, +// FormatStepError. +// internal/daemon/workspace Workspace helpers: git repo inspection, +// shallow copy prep, guest-side import, +// finalize script generation. +// +// VM lifecycle (in this package): // // vm_create.go CreateVM and create-time disk provisioning // vm_lifecycle.go Start/Stop/Restart/Kill/Delete // vm_set.go SetVM mutation // vm_stats.go stats, health, ping, stale reaper // vm_disk.go system overlay, work disk provisioning -// vm_authsync.go per-VM authorized_key, git identity, and auth file sync -// vm_create_ops.go async begin/status/cancel registry for create +// vm_authsync.go per-VM authorized_key, git identity, auth file sync +// vm_create_ops.go async begin/status/cancel (uses opstate.Registry) +// vm_locks.go vmLockSet: per-VM mutex set +// vm.go fcproc forwarders, DNS helpers, small utilities // capabilities.go pluggable capability hooks executed at VM start // preflight.go prereq validation for VM start -// snapshot.go device-mapper COW snapshot helpers +// snapshot.go dmsnap forwarders + dmSnapshotHandles type alias // ports.go port forwarding inspection // -// Image management: +// Image management (in this package): // // images.go register, promote, delete, find, list -// imagebuild.go build via firecracker build VM -// image_build_ops.go async begin/status/cancel registry for build -// image_seed.go managed work-seed fingerprint refresh +// imagebuild.go orchestrates the transient firecracker build VM +// image_build_ops.go async begin/status/cancel (uses opstate.Registry) +// image_seed.go managed work-seed SSH fingerprint refresh // -// Guest interaction: +// Guest interaction (in this package): // -// guest_sessions.go long-lived guest commands, attach, logs -// ssh_client_config.go daemon-managed SSH client key material -// workspace.go materialising host repos into guest -// opencode.go opencode host-side helpers +// guest_sessions.go dialGuest, waitForGuestSSH, refresh/inspect +// session_lifecycle.go Start/Stop/Kill/Get/List/signal orchestrators +// session_attach.go BeginGuestSessionAttach + bridge/forward/watch +// session_stream.go GuestSessionLogs, SendToGuestSession +// session_controller.go guestSessionController, sessionRegistry +// ssh_client_config.go daemon-managed SSH client key material +// workspace.go ExportVMWorkspace, PrepareVMWorkspace +// opencode.go opencode host-side helpers // -// Host bootstrap: +// Host bootstrap (in this package): // // nat.go NAT prereq registration // dns_routing.go systemd-resolved per-interface routing -// tap_pool.go TAP interface pool +// tap_pool.go TAP interface pool (state in tapPool type) // -// Core: +// Core (in this package): // // daemon.go Daemon struct, Open/Close/Serve, dispatch // dashboard.go dashboard metrics aggregation // doctor.go host diagnostics // logger.go slog configuration // runtime_assets.go paths to bundled companion binaries -// web.go embedded web UI server +// web.go experimental local web UI server // // Lock ordering: // // vmLocks[id] → {createVMMu, imageOpsMu} → subsystem-local locks // -// Subsystem-local locks live on the owning type (tapPool.mu, -// sessionRegistry.mu, opRegistry.mu, guestSessionController.attachMu/writeMu) -// and do not contend with each other. See ARCHITECTURE.md for details. +// Subsystem-local locks live on their owning type (tapPool.mu, +// sessionRegistry.mu, opstate.Registry mu, guestSessionController.attachMu / +// writeMu) and do not contend with each other. See ARCHITECTURE.md for +// details. package daemon