Modern Docker Management, Designed for Everyone
Go composecontainer-managementcontainersdockerdocker-composedocker-managementgoself-hostedsveltekittypescriptweb-ui
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';
}
}