runtime

type Runtime interface {
	// Create provisions and starts a managed container. The caller owns the
	// sandbox ID. The runtime sets it as the container's canonical name so
	// the sandbox ID is the end-to-end identifier (the container ID is an
	// internal detail). The chosen OCI runtime is read from
	// req.Runtime; the implementation is expected to substitute its own
	// default when req.Runtime is empty.
	Create(ctx context.Context, req models.CreateSandboxRequest, sandboxID, toolboxToken string, hostMounts []mounts.ContainerBind) (*models.SandboxRuntimeState, error)

	// Start boots a previously created container and waits for the in-container
	// toolbox to become reachable.
	Start(ctx context.Context, containerRef string) (*models.SandboxRuntimeState, error)

	// Stop sends a graceful stop with a default timeout.
	Stop(ctx context.Context, containerRef string) error

	// Destroy removes the container and clears any per-IP network rules.
	// Passing nil is a no-op — convenient for cleanup paths that may not yet
	// have a sandbox record.
	Destroy(ctx context.Context, sandbox *models.Sandbox) error

	// Resize updates CPU/memory caps on a running container. DiskGB is not
	// resizable on a live container; resize-up at create time is honored
	// per-runtime.
	Resize(ctx context.Context, containerRef string, req models.ResizeSandboxRequest) error

	// Inspect returns the current runtime state for a single container.
	Inspect(ctx context.Context, containerRef string) (*models.SandboxRuntimeState, error)

	// ListManaged returns the runtime state of every container managed by
	// this sandboxd, keyed by sandbox ID. Used by reconcile.
	ListManaged(ctx context.Context) (map[string]*models.SandboxRuntimeState, error)

	// Ping verifies the underlying runtime daemon is reachable.
	Ping(ctx context.Context) error

	// RemoveImage GCs an image from the runtime's local store. 404/409 are
	// treated as success — see implementation notes.
	RemoveImage(ctx context.Context, imageRef string) error

	// PushAllowedPorts updates the in-container toolbox's allowlist of ports
	// reachable through its proxy. Best-effort; callers log on failure.
	PushAllowedPorts(ctx context.Context, containerIP, toolboxToken string, ports []int) error

	// ClearNetworkRules releases any per-IP network rules previously attached
	// to a sandbox. Used by the event-driven path when a container exits or
	// is destroyed out-of-band; Destroy() handles this during normal teardown.
	ClearNetworkRules(containerIP string) error
}