Thales Maciel
59f2766139
Daemon no longer owns a coarse mu shared across unrelated concerns.
Each subsystem now carries its own state and lock:
- tapPool: entries, next, and mu move onto a new tapPool struct.
- sessionRegistry: sessionControllers + its mutex move off Daemon.
- opRegistry[T asyncOp]: generic registry collapses the two ad-hoc
vm-create and image-build operation maps (and their mutexes) into one
shared type; the Begin/Status/Cancel/Prune methods simplify.
- vmLockSet: the sync.Map of per-VM mutexes moves into its own type;
lockVMID forwards.
- Daemon.mu splits into imageOpsMu (image-registry mutations) and
createVMMu (CreateVM serialisation) so image ops and VM creates no
longer block each other.
Lock ordering collapses to vmLocks[id] -> {createVMMu, imageOpsMu} ->
subsystem-local leaves. doc.go and ARCHITECTURE.md updated.
No behavior change; tests green.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2.5 KiB
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.
Composition
Daemon is the composition root. Subsystem state and locks have moved onto
owning types:
- Layout, config, store, runner, logger, pid — infrastructure handles.
vmLocks vmLockSet— per-VM*sync.Mutex, one per VM ID.createVMMu sync.Mutex— serialisesCreateVM(guards name uniqueness- 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.tapPool tapPool— TAP interface pool; 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.
Lock ordering
Acquire in this order, release in reverse. Never acquire in the opposite 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.
Notes:
vmLocks[id]is the outer lock for any operation scoped to a single VM. Acquired viawithVMLockByID/withVMLockByRef.createVMMuandimageOpsMuare narrow: each guards one family of mutations and is released before any blocking guest I/O.- Holding a subsystem-local lock while calling into guest SSH is discouraged; copy needed state out under the lock and release before blocking I/O.
External API
Only internal/cli imports this package. The surface is:
daemon.Open(ctx) (*Daemon, error)(*Daemon).Serve(ctx) error(*Daemon).Close() errordaemon.Doctor(...)— host diagnostics (no receiver).
All other *Daemon methods are reached only through the RPC dispatch
switch in daemon.go and are free to move/rename during refactoring.