feat: backend service

backend/internal/dockerclient/client.go

@@ -0,0 +1,37 @@
+package dockerclient
+
+import "context"
+
+// Client is the narrow Docker port consumed by `internal/runtime`. The
+// production adapter is *Adapter (see adapter.go); tests substitute a
+// hand-rolled stub or generated mock.
+//
+// Method semantics:
+//
+//   - EnsureNetwork verifies a user-defined Docker network exists on
+//     the daemon. Adapter never creates networks.
+//   - PullImage pulls ref according to policy. Implementations must
+//     honour PullPolicyNever by skipping the pull and returning nil
+//     when the image is already present, or ErrImageNotFound otherwise.
+//   - InspectImage / InspectContainer return ErrImageNotFound /
+//     ErrContainerNotFound for missing inputs.
+//   - Run creates and starts one container. The returned RunResult
+//     carries the container id, the stable engine endpoint URL, and
+//     the wall-clock observed by the daemon.
+//   - Stop sends SIGTERM and waits up to the spec timeout before
+//     SIGKILL. Returns ErrContainerNotFound when the target is already
+//     gone.
+//   - Remove deletes the container. Idempotent: nil when already
+//     removed.
+//   - List returns container summaries that match filter. Adapter
+//     translates filter.Labels into the daemon-side filters argument.
+type Client interface {
+	EnsureNetwork(ctx context.Context, name string) error
+	PullImage(ctx context.Context, ref string, policy PullPolicy) error
+	InspectImage(ctx context.Context, ref string) (ImageInspect, error)
+	InspectContainer(ctx context.Context, idOrName string) (ContainerInspect, error)
+	Run(ctx context.Context, spec RunSpec) (RunResult, error)
+	Stop(ctx context.Context, idOrName string, timeoutSeconds int) error
+	Remove(ctx context.Context, idOrName string) error
+	List(ctx context.Context, filter ListFilter) ([]ContainerSummary, error)
+}