Skip to content

Modern Docker Management, Designed for Everyone

14.1 KB
Raw Blame
import type { Temporal } from 'temporal-polyfill';

import { m } from '#lib/paraglide/messages.js';
import type { ContainerDetailsDto, ContainerStats, ContainerSummaryDto } from '#lib/types/docker.js';
import type { Environment, EnvironmentStatus } from '#lib/types/environment.js';
import type { VulnerabilityScanSummary } from '#lib/types/environment.js';
import type { SearchPaginationSortRequest } from '#lib/types/shared.js';
import type { ProjectUpdateInfo } from '#lib/types/swarm.js';
import type { SwarmServiceModeName, SwarmServiceModeSpec } from '#lib/types/swarm.js';
import { instantEpochMilliseconds } from '#lib/utils/formatting.js';
import { tryCatch } from '#lib/utils/try-catch.js';

// --- Compose / Swarm management labels ---

export const COMPOSE_PROJECT_LABEL = 'com.docker.compose.project';
export const COMPOSE_SERVICE_LABEL = 'com.docker.compose.service';
export const SWARM_STACK_LABEL = 'com.docker.stack.namespace';

export function getManagedByLabel(labels?: Record<string, string> | null): string | undefined {
	return labels?.[COMPOSE_PROJECT_LABEL] || labels?.[SWARM_STACK_LABEL] || undefined;
}

// --- Container stats math ---

export function calculateCPUPercent(stats: ContainerStats | null): number {
	if (!stats?.cpu_stats || !stats?.precpu_stats) return 0;

	const cpuDelta = stats.cpu_stats.cpu_usage.total_usage - (stats.precpu_stats.cpu_usage?.total_usage || 0);
	const systemDelta = stats.cpu_stats.system_cpu_usage - (stats.precpu_stats.system_cpu_usage || 0);

	if (systemDelta > 0 && cpuDelta > 0) {
		const cpuPercent = (cpuDelta / systemDelta) * 100.0;
		return Math.min(Math.max(cpuPercent, 0), 100);
	}
	return 0;
}

export function calculateMemoryPercent(stats: ContainerStats | null): number {
	if (!stats?.memory_stats) return 0;

	const usage = calculateMemoryUsage(stats);
	const limit = stats.memory_stats.limit || 0;

	if (limit > 0) {
		const percent = (usage / limit) * 100;
		return Math.min(Math.max(percent, 0), 100);
	}
	return 0;
}

export function calculateMemoryUsage(stats: ContainerStats | null): number {
	if (!stats?.memory_stats) return 0;

	const usage = stats.memory_stats.usage || 0;
	const totalInactiveFile = stats.memory_stats.stats?.total_inactive_file;
	if (totalInactiveFile !== undefined && totalInactiveFile < usage) {
		return usage - totalInactiveFile;
	}
	const inactiveFile = stats.memory_stats.stats?.inactive_file;
	if (inactiveFile !== undefined && inactiveFile < usage) {
		return usage - inactiveFile;
	}
	return usage;
}

export function getContainerIpAddresses(container: ContainerSummaryDto): string[] {
	const networks = container.networkSettings?.networks;
	if (!networks) return [];

	const seen = new Set<string>();
	const ipAddresses: string[] = [];
	for (const networkName of Object.keys(networks).sort((a, b) => a.localeCompare(b))) {
		const network = networks[networkName];
		for (const ipAddress of [network?.ipAddress?.trim(), network?.globalIPv6Address?.trim()]) {
			if (!ipAddress || seen.has(ipAddress)) continue;
			seen.add(ipAddress);
			ipAddresses.push(ipAddress);
		}
	}

	return ipAddresses;
}

// Docker falls back to the container's short ID, so only a hostname that was asked for is worth showing.
export function getCustomHostname(container: Pick<ContainerDetailsDto, 'id' | 'config'>): string | undefined {
	const hostname = container.config?.hostname?.trim();
	if (!hostname) return undefined;
	const shortId = container.id.length >= 12 ? container.id.slice(0, 12) : null;
	return hostname === shortId ? undefined : hostname;
}

// --- Swarm service mode helpers ---

export type SwarmServiceModeBadgeVariant = 'green' | 'blue' | 'amber' | 'purple' | 'gray';

export function getSwarmServiceModeFromSpec(mode: SwarmServiceModeSpec | undefined): SwarmServiceModeName {
	if (mode?.Replicated) return 'replicated';
	if (mode?.Global !== undefined) return 'global';
	if (mode?.ReplicatedJob) return 'replicated-job';
	if (mode?.GlobalJob !== undefined) return 'global-job';
	return 'unknown';
}

const swarmModeDisplay = new Map<string, { label: () => string; variant: SwarmServiceModeBadgeVariant }>([
	['replicated', { label: m.swarm_service_mode_replicated, variant: 'blue' }],
	['global', { label: m.global, variant: 'green' }],
	['replicated-job', { label: m.swarm_service_mode_replicated_job, variant: 'amber' }],
	['global-job', { label: m.swarm_service_mode_global_job, variant: 'purple' }]
]);

export function getSwarmServiceModeLabel(mode: string): string {
	return (swarmModeDisplay.get(mode)?.label ?? m.common_unknown)();
}

export function getSwarmServiceModeVariant(mode: string): SwarmServiceModeBadgeVariant {
	return swarmModeDisplay.get(mode)?.variant ?? 'gray';
}

export function isSwarmServiceModeScalable(mode: string): boolean {
	return mode === 'replicated' || mode === 'replicated-job';
}

export function parseImageRef(imageRef: string): { repo: string; tag: string } {
	const namedRef = imageRef.split('@', 1)[0] ?? imageRef;
	const lastColon = namedRef.lastIndexOf(':');
	// Check if colon is part of a tag (not a port in registry URL)
	const hasTag = lastColon > 0 && !namedRef.substring(lastColon).includes('/');

	if (hasTag) {
		return {
			repo: namedRef.substring(0, lastColon),
			tag: namedRef.substring(lastColon + 1)
		};
	}
	return { repo: namedRef, tag: 'latest' };
}

// --- Project update status display ---

type ProjectUpdateStatus = ProjectUpdateInfo['status'];
export type ProjectUpdateBadgeVariant = 'blue' | 'green' | 'gray' | 'red';

export function getProjectUpdateStatus(updateInfo?: ProjectUpdateInfo): ProjectUpdateStatus {
	return updateInfo?.status ?? 'unknown';
}

const projectUpdateDisplay = new Map<ProjectUpdateStatus, { label: () => string; variant: ProjectUpdateBadgeVariant }>([
	['has_update', { label: m.images_has_updates, variant: 'blue' }],
	['up_to_date', { label: m.image_update_up_to_date_title, variant: 'green' }],
	['not_pulled', { label: m.image_update_not_pulled_title, variant: 'blue' }],
	['error', { label: m.common_error, variant: 'red' }]
]);

export function getProjectUpdateText(updateInfo?: ProjectUpdateInfo): string {
	return (projectUpdateDisplay.get(getProjectUpdateStatus(updateInfo))?.label ?? m.image_update_status_unknown)();
}

export function getProjectUpdateVariant(updateInfo?: ProjectUpdateInfo): ProjectUpdateBadgeVariant {
	return projectUpdateDisplay.get(getProjectUpdateStatus(updateInfo))?.variant ?? 'gray';
}

export function getProjectUpdateTooltip(updateInfo?: ProjectUpdateInfo): string | undefined {
	switch (getProjectUpdateStatus(updateInfo)) {
		case 'not_pulled':
			return m.image_update_not_pulled_desc();
		case 'error':
			return m.image_update_check_failed_title();
		case 'unknown':
			return m.image_update_click_to_check();
		default:
			return undefined;
	}
}

// --- Updates filter transforms ---

const updatesFilter = 'has_update';

export function ensureUpdatesFilter<T extends SearchPaginationSortRequest>(options: T): T {
	return {
		...options,
		filters: {
			...options.filters,
			updates: updatesFilter
		}
	};
}

export function ensureStandaloneContainerUpdatesFilter<T extends SearchPaginationSortRequest>(options: T): T {
	const next = ensureUpdatesFilter(options);
	return {
		...next,
		filters: {
			...next.filters,
			standalone: true
		}
	};
}

export function extractErrorMessage(data: unknown, fallbackMessage: string): string {
	if (!data || typeof data !== 'object') return fallbackMessage;

	const obj = data as Record<string, unknown>;
	if (!obj['error']) return '';

	if (typeof obj['error'] === 'string') return obj['error'];
	if (typeof obj['error'] === 'object' && obj['error'] !== null) {
		const errObj = obj['error'] as Record<string, unknown>;
		if (typeof errObj['message'] === 'string') return errObj['message'];
	}

	return fallbackMessage;
}

// --- Vulnerability scan polling ---

const SCAN_IN_PROGRESS_STATUSES = new Set(['pending', 'scanning']);

export type VulnerabilityScanPollOptions = {
	intervalMs?: number;
	maxAttempts?: number;
	onUpdate?: (summary: VulnerabilityScanSummary) => void;
	onComplete?: (summary: VulnerabilityScanSummary) => void;
	onError?: (error: unknown) => void;
};

export type VulnerabilityScanStabilizeOptions = {
	scanRequestedAt?: string | number | Temporal.Instant | null;
	failedRecheckDelayMs?: number;
	maxFailedRechecks?: number;
	staleFailureGraceMs?: number;
};

function delay(ms: number): Promise<void> {
	return new Promise((resolve) => {
		setTimeout(resolve, ms);
	});
}

function toTimestampMs(value?: string | number | Temporal.Instant | null): number {
	if (value == null) return 0;
	if (typeof value === 'number') {
		return Number.isFinite(value) ? value : 0;
	}
	return instantEpochMilliseconds(value) ?? 0;
}

export function isVulnerabilityScanInProgress(status?: string | null): boolean {
	if (!status) return false;
	return SCAN_IN_PROGRESS_STATUSES.has(status);
}

export function isLikelyStaleFailedSummary(
	summary: VulnerabilityScanSummary,
	scanRequestedAt?: string | number | Temporal.Instant | null,
	staleFailureGraceMs = 1500
): boolean {
	if (summary.status !== 'failed') return false;

	const requestedAtMs = toTimestampMs(scanRequestedAt);
	if (requestedAtMs <= 0) return false;

	const summaryTimeMs = toTimestampMs(summary.scanTime);
	const scanTimeLooksOld = summaryTimeMs <= 0 || summaryTimeMs + staleFailureGraceMs < requestedAtMs;
	const missingErrorDetails = !summary.error || summary.error.trim() === '';

	return scanTimeLooksOld || missingErrorDetails;
}

export async function stabilizeFailedVulnerabilitySummary(
	imageId: string,
	initialSummary: VulnerabilityScanSummary,
	fetchSummary: (imageId: string) => Promise<VulnerabilityScanSummary>,
	options: VulnerabilityScanStabilizeOptions = {}
): Promise<VulnerabilityScanSummary> {
	const { scanRequestedAt, failedRecheckDelayMs = 1000, maxFailedRechecks = 2, staleFailureGraceMs = 1500 } = options;

	let summary = initialSummary;
	if (!isLikelyStaleFailedSummary(summary, scanRequestedAt, staleFailureGraceMs)) {
		return summary;
	}

	const retries = Math.max(0, maxFailedRechecks);
	for (let attempt = 0; attempt < retries; attempt++) {
		await delay(failedRecheckDelayMs);
		summary = await fetchSummary(imageId);
		if (summary.status !== 'failed') {
			return summary;
		}
	}

	return summary;
}

export function startVulnerabilityScanPolling(
	imageId: string,
	fetchSummary: (imageId: string) => Promise<VulnerabilityScanSummary>,
	options: VulnerabilityScanPollOptions = {}
): () => void {
	const { intervalMs = 2000, maxAttempts = 0, onUpdate, onComplete, onError } = options;
	let attempts = 0;
	let cancelled = false;
	let timeoutId: ReturnType<typeof setTimeout> | null = null;

	const schedule = () => {
		if (cancelled) return;
		timeoutId = setTimeout(run, intervalMs);
	};

	const run = async () => {
		if (cancelled) return;
		attempts += 1;
		const result = await tryCatch(
			(async () => {
				const summary = await fetchSummary(imageId);
				onUpdate?.(summary);
				const isScanning = isVulnerabilityScanInProgress(summary?.status);
				if (!isScanning) onComplete?.(summary);
				return isScanning;
			})()
		);
		if (result.error !== null) {
			onError?.(result.error);
		} else if (!result.data) {
			return;
		}

		if (maxAttempts > 0 && attempts >= maxAttempts) {
			onError?.(new Error('Scan polling exceeded max attempts.'));
			return;
		}

		schedule();
	};

	void run();

	return () => {
		cancelled = true;
		if (timeoutId) {
			clearTimeout(timeoutId);
		}
	};
}

export type ThemedIconSource = {
	iconLightUrl?: string | null;
	iconDarkUrl?: string | null;
};

export function getThemedIconUrl(source?: ThemedIconSource | null, themeMode?: string | null): string | null {
	if (!source) return null;
	if (themeMode === 'light') {
		return source.iconDarkUrl?.trim() || null;
	}
	return source.iconLightUrl?.trim() || null;
}

// --- App image URLs ---

export function getApplicationLogo(
	full = false,
	colorOverride?: string,
	version?: string,
	opts?: { animated?: boolean; loop?: boolean; development?: boolean }
): string {
	const params = new URLSearchParams();

	if (full) {
		params.set('full', 'true');
	}

	if (colorOverride) {
		params.set('color', colorOverride);
	}

	if (opts?.animated) {
		params.set('animated', 'true');
	}

	if (opts?.loop) {
		params.set('loop', 'true');
	}

	// Cache-busts open pages when development branding is toggled.
	if (opts?.development) {
		params.set('branding', 'development');
	}

	if (version) {
		params.set('v', version);
	}

	const query = params.toString();
	return query ? `/api/app-images/logo?${query}` : '/api/app-images/logo';
}

export function getDefaultProfilePicture(): string {
	return '/api/app-images/profile';
}

// --- Status variants ---

export type StatusVariant = 'red' | 'purple' | 'green' | 'blue' | 'gray' | 'amber';

const STATUS_VARIANT_MAP: Record<string, StatusVariant> = {
	running: 'green',
	deployed: 'green',
	stopped: 'red',
	failed: 'red',
	pending: 'amber',
	creating: 'blue',
	updating: 'blue',
	deleting: 'purple',
	exited: 'red'
};

export function getStatusVariant(status?: string | null): StatusVariant {
	if (!status) return 'gray';
	return STATUS_VARIANT_MAP[String(status).toLowerCase()] ?? 'gray';
}

// --- Environment status resolution ---

type RuntimeEnvironmentState = Pick<Environment, 'isEdge' | 'connected' | 'status' | 'lastPollAt'>;

export function resolveEnvironmentStatus(
	environment: RuntimeEnvironmentState,
	overrideStatus?: EnvironmentStatus | null
): EnvironmentStatus {
	const status = overrideStatus ?? environment.status;

	if (!environment.isEdge) {
		return status;
	}

	if (environment.connected === true) {
		return 'online';
	}

	if (environment.lastPollAt) {
		return 'standby';
	}

	if (status === 'pending') {
		return 'pending';
	}

	if (status === 'standby') {
		return 'standby';
	}

	if (environment.connected === false) {
		return 'offline';
	}

	return status;
}

export function isEnvironmentOnline(environment: RuntimeEnvironmentState, overrideStatus?: EnvironmentStatus | null): boolean {
	const resolved = resolveEnvironmentStatus(environment, overrideStatus);
	return resolved === 'online' || resolved === 'standby';
}

export function getEnvironmentStatusVariant(status: EnvironmentStatus): 'green' | 'blue' | 'amber' | 'red' {
	switch (status) {
		case 'online':
			return 'green';
		case 'standby':
			return 'blue';
		case 'pending':
			return 'amber';
		default:
			return 'red';
	}
}