alkdev/alknet

0 Fork 0

Files

T

glm-5.2 1ce11717d8 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.

2026-07-08 09:29:22 +00:00

1.8 KiB

Raw Blame History

OQ-50: Docker System Events Subscription

Origin: crates/docker/docker-operations.md §"Out of scope for v1"; ADR-060 §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 §4 (teardown coupling — stale-entry tolerance is the base model this subscription would refine), crates/docker/docker-operations.md

1.8 KiB Raw Blame History

OQ-50: Docker System Events Subscription

1.8 KiB

Raw Blame History