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)
}