Thales Maciel
e69810610a
Two promises the doc was making that the code doesn't keep: 1. "Helpers moved out so the package stays focused on orchestration." The package still has ~29 files and ~130 func (d *Daemon) methods wiring VM lifecycle, image management, host networking, background reconciliation, and JSON-RPC dispatch. Calling it "just orchestration" sets readers up for surprise. Rewrite the subpackages preamble to say so, and flag the service split as a post-v0.1.0 project. 2. "vmLocks[id] is held only across short synchronous state validation and DB mutations." That's what workspace.prepare does; regular lifecycle ops (start/stop/delete/set) go through withVMLockByRef and hold the lock across the whole callback body, which for `start` means preflight + bridge + firecracker spawn + post-boot wiring. Rewrite the vmLocks bullet and the lock-ordering section to say that explicitly, so readers don't build "surely my long flow under the lock can't be what the doc means" reasoning on top of a false premise. Doc-only change. Code behaviour is unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
76 lines
3.4 KiB
Go
76 lines
3.4 KiB
Go
// Package daemon hosts the Banger daemon process.
|
|
//
|
|
// The daemon exposes a JSON-RPC endpoint over a Unix socket. It owns VM
|
|
// lifecycle, image management, host networking bootstrap, and state
|
|
// persistence via internal/store.
|
|
//
|
|
// 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.
|
|
//
|
|
// Subpackages:
|
|
//
|
|
// internal/daemon/opstate Generic Registry[T AsyncOp] for async
|
|
// operations (VM create).
|
|
// 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/workspace Workspace helpers: git repo inspection,
|
|
// shallow copy prep, guest-side import,
|
|
// finalize script generation, shell quoting.
|
|
//
|
|
// 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, 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 dmsnap forwarders + dmSnapshotHandles type alias
|
|
// ports.go port forwarding inspection
|
|
//
|
|
// Image management (in this package):
|
|
//
|
|
// images.go register, promote, delete, find, list
|
|
// images_pull.go image pull: catalog (bundle) + OCI paths
|
|
// image_seed.go managed work-seed SSH fingerprint refresh
|
|
//
|
|
// Guest interaction (in this package):
|
|
//
|
|
// guest_ssh.go guestSSHClient, dialGuest, waitForGuestSSH
|
|
// ssh_client_config.go daemon-managed SSH client key material
|
|
// workspace.go ExportVMWorkspace, PrepareVMWorkspace
|
|
//
|
|
// Host bootstrap (in this package):
|
|
//
|
|
// nat.go NAT prereq registration
|
|
// dns_routing.go systemd-resolved per-interface routing
|
|
// tap_pool.go TAP interface pool (state in tapPool type)
|
|
//
|
|
// Core (in this package):
|
|
//
|
|
// daemon.go Daemon struct, Open/Close/Serve, dispatch
|
|
// doctor.go host diagnostics
|
|
// logger.go slog configuration
|
|
// runtime_assets.go paths to bundled companion binaries
|
|
//
|
|
// Lock ordering:
|
|
//
|
|
// vmLocks[id] → workspaceLocks[id] → {createVMMu, imageOpsMu} → subsystem-local locks
|
|
//
|
|
// vmLocks[id] is held across entire lifecycle ops (start/stop/delete/set),
|
|
// not just a validation window — callers that want to avoid blocking
|
|
// lifecycle on slow guest I/O must explicitly split off to
|
|
// workspaceLocks[id] the way workspace.prepare does. Subsystem-local
|
|
// locks (tapPool.mu, opstate.Registry mu) are leaves and do not contend
|
|
// with each other. See ARCHITECTURE.md for details.
|
|
package daemon
|