/**
* Segregated Docker service interfaces following Interface Segregation Principle (ISP).
* These interfaces provide cohesive, focused Docker contracts.
*
* Each interface represents a specific area of Docker functionality:
* - IContainerOperations: Container lifecycle and inspection
* - IImageOperations: Image management and builds
* - IResourceOperations: Networks, volumes, and resource cleanup
* - IDockerSystemInfo: System information and status
* - IDockerClientProvider: Low-level client access (internal use)
*/
import type Docker from "dockerode";
import type {
ContainerExecResult,
ContainerInfo,
ContainerProcessList,
ContainerStats,
DockerDiskUsage,
DockerNetworkInfo,
DockerRawContainerInfo,
DockerRawContainerInspectInfo,
DockerSystemInfo,
DockerVolumeInfo,
HostConfig,
HostStatus,
ImageInfo,
ListImagesOptions,
LogEntry,
PruneResult,
} from "../types.js";
/**
* Container lifecycle operations and inspection.
* Provides methods for starting, stopping, monitoring, and interacting with containers.
*/
export interface IContainerOperations {
/**
* List containers across multiple hosts with optional filtering and pagination.
*
* @param hosts - Array of host configurations to query
* @param options - Filtering and pagination options
* @param options.state - Filter by container state (all, running, stopped, paused)
* @param options.nameFilter - Filter by container name (partial match)
* @param options.imageFilter - Filter by image name (partial match)
* @param options.labelFilter - Filter by label (format: "key=value")
* @param options.limit - Maximum number of containers to return
* @param options.offset - Number of containers to skip before returning results
* @returns Array of containers with their details and host information
*/
listContainers(
hosts: HostConfig[],
options?: {
state?: "all" | "running" | "stopped" | "paused";
nameFilter?: string;
imageFilter?: string;
labelFilter?: string;
limit?: number;
offset?: number;
}
): Promise<ContainerInfo[]>;
/**
* Perform a lifecycle action on a container.
*
* @param containerId - Container ID or name
* @param action - Action to perform (start, stop, restart, pause, unpause)
* @param host - Host configuration where container is located
*/
containerAction(
containerId: string,
action: "start" | "stop" | "restart" | "pause" | "unpause",
host: HostConfig
): Promise<void>;
/**
* Retrieve logs from a container.
*
* @param containerId - Container ID or name
* @param host - Host configuration where container is located
* @param options - Log retrieval options
* @param options.lines - Number of lines to retrieve (default: 100)
* @param options.since - Show logs since timestamp or duration (e.g., "2023-01-01T00:00:00Z" or "10m")
* @param options.until - Show logs until timestamp or duration
* @param options.stream - Stream to retrieve (all, stdout, stderr)
* @returns Array of log entries with timestamps and content
*/
getContainerLogs(
containerId: string,
host: HostConfig,
options?: {
lines?: number;
since?: string;
until?: string;
stream?: "all" | "stdout" | "stderr";
}
): Promise<LogEntry[]>;
/**
* Get resource usage statistics for a container.
*
* @param containerId - Container ID or name
* @param host - Host configuration where container is located
* @returns Resource statistics including CPU, memory, network, and I/O
*/
getContainerStats(containerId: string, host: HostConfig): Promise<ContainerStats>;
/**
* Execute a command inside a container.
*
* @param containerId - Container ID or name
* @param host - Host configuration where container is located
* @param options - Exec options
* @param options.command - Command to execute (allowlisted)
* @param options.user - Run as specific user
* @param options.workdir - Working directory
* @param options.timeout - Execution timeout in ms (default 30s, max 5min)
* @returns Exec result with stdout, stderr, and exit code
* @throws Error if timeout exceeded or buffer limit exceeded
*/
execContainer(
containerId: string,
host: HostConfig,
options: { command: string; user?: string; workdir?: string; timeout?: number }
): Promise<ContainerExecResult>;
/**
* Get running processes inside a container.
*
* @param containerId - Container ID or name
* @param host - Host configuration where container is located
* @returns Process list with titles and rows
*/
getContainerProcesses(containerId: string, host: HostConfig): Promise<ContainerProcessList>;
/**
* Get detailed information about a container.
*
* @param containerId - Container ID or name
* @param host - Host configuration where container is located
* @returns Full container inspection data from Docker API
*/
inspectContainer(containerId: string, host: HostConfig): Promise<DockerRawContainerInspectInfo>;
/**
* Find which host a container is running on.
* Searches across all provided hosts.
*
* @param containerId - Container ID or name to find
* @param hosts - Array of host configurations to search
* @returns Host config and container info if found, null otherwise
*/
findContainerHost(
containerId: string,
hosts: HostConfig[]
): Promise<{ host: HostConfig; container: DockerRawContainerInfo } | null>;
/**
* Recreate a container with the same configuration.
* Optionally pulls the latest image before recreating.
*
* @param containerId - Container ID or name to recreate
* @param host - Host configuration where container is located
* @param options - Recreate options
* @param options.pull - Whether to pull latest image before recreating
* @returns Operation status and new container ID
*/
recreateContainer(
containerId: string,
host: HostConfig,
options?: { pull?: boolean }
): Promise<{ status: string; containerId: string }>;
}
/**
* Image management operations.
* Provides methods for listing, pulling, removing, and building Docker images.
*/
export interface IImageOperations {
/**
* List Docker images across multiple hosts with optional filtering.
*
* @param hosts - Array of host configurations to query
* @param options - Filtering options (dangling, reference, etc.)
* @returns Array of images with their details and host information
*/
listImages(hosts: HostConfig[], options?: ListImagesOptions): Promise<ImageInfo[]>;
/**
* Pull a Docker image from a registry.
*
* @param imageName - Image name with optional tag (e.g., "nginx:latest")
* @param host - Host configuration where image should be pulled
* @returns Operation status
*/
pullImage(imageName: string, host: HostConfig): Promise<{ status: string }>;
/**
* Remove a Docker image.
*
* @param imageId - Image ID or name to remove
* @param host - Host configuration where image is located
* @param options - Removal options
* @param options.force - Force removal even if image is in use
* @returns Operation status
*/
removeImage(
imageId: string,
host: HostConfig,
options?: { force?: boolean }
): Promise<{ status: string }>;
/**
* Build a Docker image from a Dockerfile.
*
* @param host - Host configuration where build should occur
* @param options - Build options
* @param options.context - Path to build context directory
* @param options.tag - Tag for the built image
* @param options.dockerfile - Path to Dockerfile (relative to context, default: "Dockerfile")
* @param options.noCache - Disable build cache
* @returns Operation status
*/
buildImage(
host: HostConfig,
options: { context: string; tag: string; dockerfile?: string; noCache?: boolean }
): Promise<{ status: string }>;
}
/**
* Docker resource operations (networks, volumes, cleanup).
* Provides methods for managing Docker resources and disk usage.
*/
export interface IResourceOperations {
/**
* List Docker networks across multiple hosts.
*
* @param hosts - Array of host configurations to query
* @returns Array of network details with host information
*/
listNetworks(hosts: HostConfig[]): Promise<DockerNetworkInfo[]>;
/**
* List Docker volumes across multiple hosts.
*
* @param hosts - Array of host configurations to query
* @returns Array of volume details with host information
*/
listVolumes(hosts: HostConfig[]): Promise<DockerVolumeInfo[]>;
/**
* Get Docker disk usage information.
*
* @param host - Host configuration to query
* @returns Disk usage breakdown for images, containers, volumes, and build cache
*/
getDockerDiskUsage(host: HostConfig): Promise<DockerDiskUsage>;
/**
* Remove unused Docker resources (prune operation).
* This is a destructive operation — callers must pass `force: true` to confirm.
*
* @param host - Host configuration where pruning should occur
* @param target - Resource type to prune (containers, images, volumes, networks, buildcache, all)
* @param options - Options for the prune operation
* @param options.force - Must be true to confirm destructive operation
* @returns Array of prune results showing what was removed and space reclaimed
* @throws Error if force is not true
*/
pruneDocker(
host: HostConfig,
target: "containers" | "images" | "volumes" | "networks" | "buildcache" | "all",
options?: { force?: boolean }
): Promise<PruneResult[]>;
}
/**
* Docker system information and status.
* Provides methods for checking Docker daemon status and configuration.
*/
export interface IDockerSystemInfo {
/**
* Get Docker daemon system information.
*
* @param host - Host configuration to query
* @returns System info including version, OS, architecture, and resource limits
*/
getDockerInfo(host: HostConfig): Promise<DockerSystemInfo>;
/**
* Get Docker daemon status and version info for multiple hosts.
*
* @param hosts - Array of host configurations to check
* @returns Array of host statuses with daemon info and reachability
*/
getHostStatus(hosts: HostConfig[]): Promise<HostStatus[]>;
}
/**
* Low-level Docker client provider (internal use).
* Provides access to raw dockerode clients for advanced operations.
*
* @internal This interface is primarily for internal service implementations.
* Most consumers should use the higher-level operation interfaces instead.
*/
export interface IDockerClientProvider {
/**
* Get a Docker client instance for the specified host configuration.
* Clients are cached per host to reuse connections.
*
* @param config - Host configuration containing connection details
* @returns Docker client instance (dockerode)
*/
getDockerClient(config: HostConfig): Promise<Docker>;
/**
* Clear all cached Docker client connections.
* Useful for cleanup during shutdown or when connections need to be reset.
*/
clearClients(): void;
}
/**
* Composed Docker contract for components that need full Docker capabilities.
* This is a type composition, not a monolithic interface declaration.
*/
export type DockerOperations = IContainerOperations &
IImageOperations &
IResourceOperations &
IDockerSystemInfo &
IDockerClientProvider;
