Refresh daemon docs and mark web UI experimental
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 <noreply@anthropic.com>
This commit is contained in:
parent
1d51370d26
commit
ca4865447c
4 changed files with 99 additions and 43 deletions
|
|
@ -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.
|
||||
|
|
|
|||
11
README.md
11
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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
// 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 materialising host repos into guest
|
||||
// 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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue