docs(arch): draft alknet-docker architecture specs (ADRs 058-063, OQs 048-051)
Greenfield architecture spec set for the alknet-docker crate — a thin, single-host bollard wrapper exposing docker container/image operations as call-protocol ops on the shared alknet/call ALPN, plus a DockerTtyBackend (impl TtyBackend) behind a tty feature for interactive terminal sessions into containers over alknet/tty. Six ADRs: - 058: docker ops on alknet/call (no separate ALPN; raw-carriage handoff dissolved by alknet-tty extraction — interactive attach moved to alknet/tty via DockerTtyBackend, no carriage field on call.requested) - 059: bollard 0.21 (verified current on crates.io) + feature selection (http+pipe+time; no ssl/ssh/websocket/buildkit) - 060: container resource model (ADR-050 application) — alknet.managed/ alknet.owner labels, list owned_only flag, hosted-services operator role via static-resource fallback, handler-driven revoke with autonomous-death tolerance, resource-action vocabulary - 061: DockerTtyBackend in alknet-docker behind tty feature (attach vs exec mode; POC drive_attach_raw as reference) - 062: Docker client + OwnershipStore injection via closure capture (not Capabilities, not OperationContext — matches from_openapi pattern) - 063: exit code on terminal call.responded for non-interactive exec (call.completed stays empty, ADR-012 unchanged) Four spec docs (crates/docker/): README, overview, docker-operations, docker-tty-backend. Four deferred-scope OQs (048-051): network/volume ops, buildkit, system events subscription, create options surface. Updates the tty-backend.md Backend implementations table (DockerTtyBackend row now specced) and the architecture README (doc table, ADR table, current-state paragraph, OQ count). Grounded in the alknet-docker POC (docs/research/alknet-docker/poc-summary.md) which validated the hard parts; the remaining lifecycle ops are mechanical bollard wrapping. Reviewed by architecture-reviewer subagent; criticals (the docker_client injection model conflicting with the Capabilities contract) resolved via ADR-062/063 before commit.
This commit is contained in:
1 parent
5873fa22d6
commit
1ce11717d8
17 files changed
+3196
-9
No files matched your search
@@ -0,0 +1,34 @@
|
||||
# OQ-50: Docker System Events Subscription
|
||||
|
||||
- **Origin**:
|
||||
[crates/docker/docker-operations.md](crates/docker/docker-operations.md)
|
||||
§"Out of scope for v1";
|
||||
[ADR-060](decisions/060-container-resource-model-and-label-namespace.md)
|
||||
§4 (autonomous-death tolerance).
|
||||
- **Status**: deferred(scope)
|
||||
- **Door type**: Two-way
|
||||
- **Priority**: low
|
||||
- **Blocked on**: a concrete use case for prompt stale-ownership
|
||||
cleanup. The base model (ADR-060 §4) tolerates stale ownership
|
||||
entries from autonomous container death (a `--rm` exit, external
|
||||
`docker rm`, daemon restart) — they're inert (a reused container ID
|
||||
gets a fresh `record` on its next `create`). A reaper that
|
||||
subscribes to docker daemon events would clean them promptly, but
|
||||
the promptness gain is marginal for the current use cases.
|
||||
- **Resolution**: Not yet decidable. bollard's `events()`
|
||||
(system.rs:128) returns a `Stream<SystemEventsMessage>` of daemon
|
||||
events (container start/stop/die/destroy, image pull, etc.). A
|
||||
`docker/system/events` `Subscription` operation would surface these
|
||||
as `call.responded` frames; the ownership store could subscribe
|
||||
internally to revoke on `destroy` events. The deferral is scope:
|
||||
the base model works without it; the events subscription is a
|
||||
refinement for when prompt cleanup matters (e.g., a high-churn
|
||||
coordinator that spawns/removes many containers and wants the
|
||||
ownership store to stay tight). Adding it is additive (a new
|
||||
operation + an internal store subscription) and does not break the
|
||||
existing surface.
|
||||
- **Cross-references**:
|
||||
[ADR-060](decisions/060-container-resource-model-and-label-namespace.md)
|
||||
§4 (teardown coupling — stale-entry tolerance is the base model
|
||||
this subscription would refine),
|
||||
[crates/docker/docker-operations.md](crates/docker/docker-operations.md)
|
||||
Reference in new issue
Block a user