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>
64 lines
2.5 KiB
Markdown
64 lines
2.5 KiB
Markdown
# `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` — serialises `CreateVM` (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 via `withVMLockByID` / `withVMLockByRef`.
|
|
- `createVMMu` and `imageOpsMu` are 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() error`
|
|
- `daemon.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.
|