/**
* Configuration for connecting to a Docker host in a multi-host homelab setup.
* Supports SSH tunneling, HTTP/HTTPS connections, and local socket connections.
*
* @example
* ```typescript
* const config: HostConfig = {
* name: "homelab-main",
* host: "192.168.1.100",
* protocol: "ssh",
* sshUser: "admin",
* sshKeyPath: "/home/user/.ssh/id_rsa",
* tags: ["production", "homelab"]
* };
* ```
*/
export interface HostConfig {
/** Unique identifier for this host */
name: string;
/** Hostname or IP address of the Docker host */
host: string;
/** Port number for the connection (defaults based on protocol) */
port?: number;
/** Connection protocol (ssh is recommended for security) */
protocol: "http" | "https" | "ssh";
/** SSH username for SSH protocol connections */
sshUser?: string;
/** Path to SSH private key for authentication */
sshKeyPath?: string;
/** Path to Docker socket for direct API access */
dockerSocketPath?: string;
/** Tags for filtering and organizing hosts */
tags?: string[];
/** Custom paths to search for docker-compose.yml files */
composeSearchPaths?: string[];
}
/**
* Detailed information about a Docker container.
* Returned from Docker API queries and used throughout the system.
*
* @example
* ```typescript
* const container: ContainerInfo = {
* id: "abc123def456",
* name: "web-server",
* image: "nginx:latest",
* state: "running",
* status: "Up 2 hours",
* created: "2026-02-01T10:30:00Z",
* ports: [],
* labels: { "app": "nginx" },
* hostName: "homelab-main"
* };
* ```
*/
export interface ContainerInfo {
/** Docker container ID (shortened hash) */
id: string;
/** Container name (without leading slash) */
name: string;
/** Docker image name and tag */
image: string;
/** Current container lifecycle state */
state: "running" | "paused" | "exited" | "created" | "restarting" | "removing" | "dead";
/** Human-readable status string (e.g., "Up 2 hours", "Exited (0) 5 minutes ago") */
status: string;
/** ISO 8601 timestamp when container was created */
created: string;
/** Port mappings for this container */
ports: PortBinding[];
/** Container labels (key-value metadata) */
labels: Record<string, string>;
/** Name of the host where this container is running */
hostName: string;
}
/**
* Port mapping between container and host network.
* Represents a published port from a Docker container.
*/
export interface PortBinding {
/** Port number inside the container */
containerPort: number;
/** Port number on the host machine (if published) */
hostPort?: number;
/** Network protocol for this port binding */
protocol: "tcp" | "udp";
/** Host IP address to bind to (defaults to 0.0.0.0 if not specified) */
hostIp?: string;
}
/**
* Real-time resource usage statistics for a running container.
* Used for monitoring and alerting on container performance.
*
* @example
* ```typescript
* const stats: ContainerStats = {
* containerId: "abc123",
* containerName: "web-server",
* cpuPercent: 15.5,
* memoryUsage: 536870912, // 512 MB
* memoryLimit: 1073741824, // 1 GB
* memoryPercent: 50.0,
* networkRx: 1048576, // 1 MB
* networkTx: 524288, // 512 KB
* blockRead: 2097152, // 2 MB
* blockWrite: 1048576 // 1 MB
* };
* ```
*/
export interface ContainerStats {
/** Docker container ID */
containerId: string;
/** Container name */
containerName: string;
/** CPU usage as a percentage (0-100+) */
cpuPercent: number;
/** Current memory usage in bytes */
memoryUsage: number;
/** Memory limit in bytes (container or host limit) */
memoryLimit: number;
/** Memory usage as a percentage of limit (0-100) */
memoryPercent: number;
/** Total bytes received over network */
networkRx: number;
/** Total bytes transmitted over network */
networkTx: number;
/** Total bytes read from block devices */
blockRead: number;
/** Total bytes written to block devices */
blockWrite: number;
}
/**
* Result of executing a command inside a Docker container.
* Contains output streams and exit status.
*/
export interface ContainerExecResult {
/** Standard output stream from the command */
stdout: string;
/** Standard error stream from the command */
stderr: string;
/** Exit code from the command (0 indicates success) */
exitCode: number;
}
/**
* Process list from inside a Docker container.
* Result of running 'ps' or equivalent process listing command.
*/
export interface ContainerProcessList {
/** Column headers for the process list (e.g., ["PID", "USER", "CMD"]) */
titles: string[];
/** Process data rows, each row matching the titles columns */
processes: string[][];
}
/**
* Single log entry from a Docker container.
* Structured format for container log messages with metadata.
*/
export interface LogEntry {
/** ISO 8601 timestamp when the log was generated */
timestamp: string;
/** Output stream that produced this log entry */
stream: "stdout" | "stderr";
/** Log message content */
message: string;
}
/**
* Aggregated health information for a service/container.
* Used for monitoring dashboards and health check endpoints.
*
* @example
* ```typescript
* const health: ServiceHealth = {
* name: "web-server",
* host: "homelab-main",
* containerId: "abc123",
* state: "running",
* uptime: "2 days",
* restartCount: 0,
* healthStatus: "healthy",
* lastHealthCheck: "2026-02-03T10:30:00Z"
* };
* ```
*/
export interface ServiceHealth {
/** Service/container name */
name: string;
/** Host where the service is running */
host: string;
/** Docker container ID */
containerId: string;
/** Current container state */
state: string;
/** Human-readable uptime duration */
uptime: string;
/** Number of times the container has restarted */
restartCount: number;
/** Docker health check status (if health check is configured) */
healthStatus?: "healthy" | "unhealthy" | "starting" | "none";
/** ISO 8601 timestamp of the last health check */
lastHealthCheck?: string;
}
// Response format enum
export enum ResponseFormat {
JSON = "json",
MARKDOWN = "markdown",
}
/**
* Metadata for paginated API responses.
* Provides information about the current page and navigation.
*/
export interface PaginationMeta {
/** Total number of items available across all pages */
total: number;
/** Number of items in the current page */
count: number;
/** Current offset position in the full result set */
offset: number;
/** Whether more items are available after this page */
hasMore: boolean;
/** Offset value to use for fetching the next page */
nextOffset?: number;
}
/**
* Generic wrapper for paginated API responses.
* Contains items for the current page and pagination metadata.
*
* @typeParam T - Type of items in the paginated list
*
* @example
* ```typescript
* const response: PaginatedResponse<ContainerInfo> = {
* items: [container1, container2, container3],
* pagination: {
* total: 50,
* count: 3,
* offset: 0,
* hasMore: true,
* nextOffset: 3
* }
* };
* ```
*/
export interface PaginatedResponse<T> {
/** Array of items for the current page */
items: T[];
/** Pagination metadata for navigation */
pagination: PaginationMeta;
}
/**
* Connection status and summary for a Docker host.
* Used in overview dashboards and health monitoring.
*
* @example
* ```typescript
* const status: HostStatus = {
* name: "homelab-main",
* host: "192.168.1.100",
* connected: true,
* containerCount: 15,
* runningCount: 12,
* };
* ```
*/
export interface HostStatus {
/** Host identifier */
name: string;
/** Hostname or IP address */
host: string;
/** Whether the host is currently reachable */
connected: boolean;
/** Total number of containers on this host */
containerCount: number;
/** Number of containers currently running */
runningCount: number;
/** Error message if connection failed */
error?: string;
}
// Compose project summary (legacy - use ComposeProject from services/compose.ts for detailed info)
export interface ComposeProjectSummary {
name: string;
host: string;
services: string[];
status: "running" | "partial" | "stopped";
configPath?: string;
}
/**
* Information about a Docker image on a host.
* Includes metadata and usage information.
*
* @example
* ```typescript
* const image: ImageInfo = {
* id: "sha256:abc123...",
* tags: ["nginx:latest", "nginx:1.25"],
* size: 142606336, // bytes
* created: "2026-01-15T08:00:00Z",
* containers: 2,
* hostName: "homelab-main"
* };
* ```
*/
export interface ImageInfo {
/** Docker image ID (full SHA256 hash) */
id: string;
/** Image tags (repository:tag format) */
tags: string[];
/** Image size in bytes */
size: number;
/** ISO 8601 timestamp when image was created */
created: string;
/** Number of containers using this image */
containers: number;
/** Name of the host where this image exists */
hostName: string;
}
/**
* Information about a Docker network.
* Represents a network configuration on a Docker host.
*
* @example
* ```typescript
* const network: DockerNetworkInfo = {
* id: "abc123def456",
* name: "my-network",
* driver: "bridge",
* scope: "local",
* created: "2026-02-01T10:00:00Z",
* internal: false,
* attachable: true,
* ingress: false,
* hostName: "homelab-main"
* };
* ```
*/
export interface DockerNetworkInfo {
/** Docker network ID */
id: string;
/** Network name */
name: string;
/** Network driver type (e.g., "bridge", "overlay", "host") */
driver: string;
/** Network scope ("local", "swarm", or "global") */
scope: string;
/** ISO 8601 timestamp when network was created */
created?: string;
/** Whether the network is internal (isolated from external networks) */
internal?: boolean;
/** Whether manually-started containers can attach to this network */
attachable?: boolean;
/** Whether this is the cluster-wide ingress network */
ingress?: boolean;
/** Name of the host where this network exists */
hostName: string;
}
/**
* Information about a Docker volume.
* Represents persistent storage managed by Docker.
*
* @example
* ```typescript
* const volume: DockerVolumeInfo = {
* name: "postgres-data",
* driver: "local",
* scope: "local",
* mountpoint: "/var/lib/docker/volumes/postgres-data/_data",
* createdAt: "2026-02-01T10:00:00Z",
* labels: { "app": "database" },
* hostName: "homelab-main"
* };
* ```
*/
export interface DockerVolumeInfo {
/** Volume name */
name: string;
/** Volume driver (e.g., "local", "nfs") */
driver: string;
/** Volume scope ("local" or "global") */
scope: string;
/** Filesystem path where the volume is mounted on the host */
mountpoint?: string;
/** ISO 8601 timestamp when volume was created */
createdAt?: string;
/** Volume labels (key-value metadata) */
labels?: Record<string, string>;
/** Name of the host where this volume exists */
hostName: string;
}
/**
* Docker Compose project information.
* Represents a complete Compose stack with its services and configuration.
*
* @example
* ```typescript
* const project: ComposeProject = {
* name: "webapp",
* status: "running",
* configFiles: ["/home/user/webapp/docker-compose.yml"],
* services: [
* { name: "web", status: "running", health: "healthy" },
* { name: "db", status: "running" }
* ],
* host: "homelab-main"
* };
* ```
*/
export interface ComposeProject {
/** Project name (derived from directory or set in compose file) */
name: string;
/** Overall status of all services in the project */
status: "running" | "partial" | "stopped" | "unknown";
/** Paths to compose configuration files used by this project */
configFiles: string[];
/** List of services defined in this project */
services: ComposeServiceInfo[];
/** Name of the host where this project is deployed */
host?: string;
}
/**
* Information about a single service within a Docker Compose project.
* Includes runtime status and port publishing information.
*
* @example
* ```typescript
* const service: ComposeServiceInfo = {
* name: "web",
* status: "running",
* health: "healthy",
* publishers: [
* { publishedPort: 8080, targetPort: 80, protocol: "tcp" }
* ]
* };
* ```
*/
export interface ComposeServiceInfo {
/** Service name as defined in compose file */
name: string;
/** Current service status (e.g., "running", "exited", "created") */
status: string;
/** Health check status if configured */
health?: string;
/** Exit code if the service has stopped */
exitCode?: number;
/** Published port mappings for this service */
publishers?: Array<{
/** Port number exposed on the host */
publishedPort: number;
/** Port number inside the container */
targetPort: number;
/** Network protocol ("tcp" or "udp") */
protocol: string;
}>;
}
/**
* Options for listing Docker images.
* Controls filtering behavior when querying images across hosts.
*/
export interface ListImagesOptions {
/** If true, only return dangling (untagged) images */
danglingOnly?: boolean;
}
/**
* Docker system information response.
* Contains version, platform, and resource summary for a Docker host.
*
* @example
* ```typescript
* const info: DockerSystemInfo = {
* dockerVersion: "24.0.7",
* apiVersion: "1.43",
* os: "Ubuntu 22.04.3 LTS",
* arch: "x86_64",
* kernelVersion: "6.17.0-12-generic",
* cpus: 16,
* memoryBytes: 34359738368,
* storageDriver: "overlay2",
* rootDir: "/var/lib/docker",
* containersTotal: 25,
* containersRunning: 18,
* containersPaused: 0,
* containersStopped: 7,
* images: 42
* };
* ```
*/
export interface DockerSystemInfo {
/** Docker daemon version string */
dockerVersion: string;
/** Docker API version */
apiVersion: string;
/** Operating system name and version */
os: string;
/** CPU architecture (e.g., "x86_64", "aarch64") */
arch: string;
/** Linux kernel version */
kernelVersion: string;
/** Number of CPU cores available */
cpus: number;
/** Total memory in bytes */
memoryBytes: number;
/** Storage driver in use (e.g., "overlay2", "aufs") */
storageDriver: string;
/** Docker data root directory */
rootDir: string;
/** Total number of containers (all states) */
containersTotal: number;
/** Number of containers currently running */
containersRunning: number;
/** Number of containers currently paused */
containersPaused: number;
/** Number of containers currently stopped */
containersStopped: number;
/** Total number of images stored */
images: number;
}
/**
* Docker disk usage response.
* Provides detailed breakdown of disk space used by Docker resources.
*
* @example
* ```typescript
* const usage: DockerDiskUsage = {
* images: {
* total: 50,
* active: 25,
* size: 10737418240,
* reclaimable: 5368709120
* },
* containers: {
* total: 30,
* running: 20,
* size: 1073741824,
* reclaimable: 536870912
* },
* volumes: {
* total: 15,
* active: 10,
* size: 2147483648,
* reclaimable: 1073741824
* },
* buildCache: {
* total: 100,
* size: 3221225472,
* reclaimable: 2147483648
* },
* totalSize: 17179869184,
* totalReclaimable: 9126805504
* };
* ```
*/
export interface DockerDiskUsage {
/** Image storage statistics */
images: {
/** Total number of images */
total: number;
/** Number of images in use by containers */
active: number;
/** Total size of all images in bytes */
size: number;
/** Reclaimable space from unused images in bytes */
reclaimable: number;
};
/** Container storage statistics */
containers: {
/** Total number of containers */
total: number;
/** Number of running containers */
running: number;
/** Total size of container writable layers in bytes */
size: number;
/** Reclaimable space from stopped containers in bytes */
reclaimable: number;
};
/** Volume storage statistics */
volumes: {
/** Total number of volumes */
total: number;
/** Number of volumes in use by containers */
active: number;
/** Total size of all volumes in bytes */
size: number;
/** Reclaimable space from unused volumes in bytes */
reclaimable: number;
};
/** Build cache statistics */
buildCache: {
/** Total number of build cache entries */
total: number;
/** Total size of build cache in bytes */
size: number;
/** Reclaimable space from build cache in bytes */
reclaimable: number;
};
/** Total disk space used by Docker in bytes */
totalSize: number;
/** Total reclaimable disk space in bytes */
totalReclaimable: number;
}
/**
* Result of a Docker prune operation.
* Contains statistics about space reclaimed and items deleted.
*
* @example
* ```typescript
* const result: PruneResult = {
* type: "images",
* spaceReclaimed: 1073741824, // 1 GB
* itemsDeleted: 5,
* details: ["sha256:abc123...", "sha256:def456..."]
* };
* ```
*/
export interface PruneResult {
/** Type of resource that was pruned */
type: string;
/** Amount of disk space reclaimed in bytes */
spaceReclaimed: number;
/** Number of items deleted during prune */
itemsDeleted: number;
/** Optional array of deleted item identifiers */
details?: string[];
}
/**
* Raw Docker container listing info from the Docker API.
* Project-level type to avoid leaking dockerode's Docker.ContainerInfo into public interfaces.
*
* This represents the data returned by `docker.listContainers()` and is used
* in container-to-host lookups and caching.
*/
export interface DockerRawContainerInfo {
/** Full container ID hash */
Id: string;
/** Container names (with leading slash, e.g., ["/my-container"]) */
Names: string[];
/** Image name used by the container */
Image: string;
/** Image ID hash */
ImageID: string;
/** Container command */
Command: string;
/** Creation timestamp (Unix epoch) */
Created: number;
/** Container state (e.g., "running", "exited") */
State: string;
/** Human-readable status string */
Status: string;
/** Port mappings */
Ports: Array<{
IP?: string;
PrivatePort: number;
PublicPort?: number;
Type: string;
}>;
/** Container labels */
Labels: Record<string, string>;
/** Mount points */
Mounts: Array<{
Type: string;
Name?: string;
Source: string;
Destination: string;
Driver?: string;
Mode: string;
RW: boolean;
}>;
}
/**
* Raw Docker container inspection info from the Docker API.
* Project-level type to avoid leaking dockerode's Docker.ContainerInspectInfo into public interfaces.
*
* This represents the detailed data returned by `container.inspect()` and is used
* in the inspect handler and formatters.
*/
export interface DockerRawContainerInspectInfo {
/** Full container ID hash */
Id: string;
/** Container name (with leading slash) */
Name: string;
/** ISO 8601 creation timestamp */
Created: string;
/** Number of times the container has been restarted */
RestartCount: number;
/** Container state information */
State: {
Status: string;
Running: boolean;
Paused: boolean;
Restarting: boolean;
OOMKilled: boolean;
Dead: boolean;
Pid: number;
ExitCode: number;
Error: string;
StartedAt: string;
FinishedAt: string;
};
/** Container configuration */
Config: {
Image: string;
Cmd: string[] | null;
WorkingDir: string;
Env: string[] | null;
Labels: Record<string, string> | null;
};
/** Network settings */
NetworkSettings: {
Ports: Record<string, Array<{ HostIp: string; HostPort: string }> | null>;
Networks: Record<string, unknown>;
};
/** Mount points */
Mounts: Array<{
Type: string;
Source: string;
Destination: string;
Mode: string;
RW: boolean;
}>;
}
