Crate strop_containers 

strop-containers: attach to an existing container on the local Docker engine and browse/read its filesystem (0037 DC1a — browse/read).

Capability boundary (read-only by construction)

This crate exposes exactly four engine conversations: probe (docker info), discovery (docker ps + docker inspect), and filesystem reads (docker cp … - tar streams). There is deliberately no write, delete, exec-of-arbitrary-argv, LSP or Git surface: those are DC1b policy decisions, not accidental omissions. Unsupported operations are refused with typed errors (ContainerError::CapabilityRefused), never silently approximated.

Ownership and identity

• Attaching never transfers lifecycle ownership: nothing here creates, stops, restarts or removes a container, and no local path is ever touched — a container path is not aliased to an analogous host path.
• The engine is the local Docker CLI only (argv arrays, never shell strings). Remote engines are DC5; no SSH daemon inside the container is required or used.
• Identity is the canonical 64-hex inspect id plus the incarnation (State.StartedAt), never a container name alone. A name that re-resolves to a different id is a stale-identity refusal; a container that restarts between inspect and read is detected by a cheap started_at re-check before every read.

Process policy

Every docker invocation runs through strop_core::process supervision: an OwnedProcess process group, the caller’s [CancelToken], a wall-clock deadline and bounded pipe retention. Directory listings stream the tar archive through an incremental parser that retains only direct-child metadata, so a subtree’s bulk bounds the transfer, never the memory; a listing whose retained metadata overflows its bound is refused, and file reads truncate by explicit max semantics — nothing partial is ever presented as complete.

Structs

ContainerIdentity

One container as the engine described it at inspect time. Plain data — resolving or re-checking it is crate::inspect / crate::revalidate’s job, never this struct’s.

ContainerRef

A canonical, incarnation-pinned reference to one running container.

DirEntry

One direct child of a listed directory.

EngineRef

The local Docker engine, proven reachable by a bounded probe.

Enums

ContainerError

Why a container operation did not produce a result.

DirEntryKind

What one directory entry is.

Functions

engine

Probe the local engine: docker info must succeed and report a server version. CLI missing, daemon down or a timed-out probe are all ContainerError::EngineUnavailable.

exec_capture

One bounded command run inside the container (0037 DC1b): Git and friends. argv-only, supervised, deadline-bounded pipes. The engine was probed by the caller; the container id is canonical.

exec_command

A docker exec -i command channel for one in-container program: piped stdin/stdout/stderr, working directory inside the container. The caller owns process supervision (group, kill-on-drop) as with every strop process launch. The id is the canonical inspect id — incarnation pinning is the read path’s concern; a spawned session’s liveness is scoped to itself.

inspect

Resolve a name or id prefix to the container’s identity, canonical 64-hex id included. Names are validated before the engine sees them; an unknown name is ContainerError::NoSuchContainer, never a best-effort guess.

list_dir

The direct children of path inside the container, parsed strictly from the tar archive the engine streams for the directory.

list_running

The engine’s running containers as full identities: ps for the id set, one batched inspect for the records. Containers that stop in between are dropped — this lists running containers only.

read_file

The first max bytes of the file at path inside the container (head -c semantics: a larger file yields exactly max bytes, never an error for size alone).

revalidate

Re-resolve a previously inspected identity by name. The stale-identity refusal lives here: a name that now maps to a different id, or the same id restarted since, must not silently inherit the old identity’s reads, caches or completions.