@chidchanun/bcp 0.2.17 → 0.2.18

package/packages/server/src/deployment.ts

@@ -0,0 +1,936 @@
+import {
+    randomUUID,
+} from "node:crypto";
+
+import {
+    registerShutdownHook,
+} from "./production-hardening.js";
+
+export type DeploymentRuntimeState =
+    | "idle"
+    | "starting"
+    | "ready"
+    | "draining"
+    | "stopped"
+    | "failed";
+
+export interface DeploymentMetadata {
+    serviceName: string;
+    version?: string;
+    deploymentId: string;
+    instanceId?: string;
+    release?: string;
+    environment?: string;
+    startedAt: string;
+    pid: number;
+    nodeVersion: string;
+    platform: NodeJS.Platform;
+    arch: string;
+}
+
+export interface DeploymentResourceContext {
+    readonly metadata: DeploymentMetadata;
+    readonly signal: AbortSignal;
+}
+
+export type DeploymentReadinessResult =
+    | boolean
+    | {
+        ok: boolean;
+        detail?: string;
+    };
+
+export interface DeploymentResource {
+    name: string;
+    start?: (
+        context: DeploymentResourceContext
+    ) => void | Promise<void>;
+    ready?: (
+        context: DeploymentResourceContext
+    ) =>
+        | DeploymentReadinessResult
+        | Promise<DeploymentReadinessResult>;
+    stop?: (
+        context: DeploymentResourceContext
+    ) => void | Promise<void>;
+    diagnostics?: (
+        context: DeploymentResourceContext
+    ) =>
+        | Readonly<Record<string, unknown>>
+        | Promise<Readonly<Record<string, unknown>>>;
+}
+
+export interface DeploymentResourceStatus {
+    name: string;
+    state:
+        | "registered"
+        | "starting"
+        | "started"
+        | "stopping"
+        | "stopped"
+        | "failed";
+    startedAt?: string;
+    stoppedAt?: string;
+    error?: string;
+}
+
+export interface DeploymentReadinessItem {
+    name: string;
+    ok: boolean;
+    durationMs: number;
+    detail?: string;
+}
+
+export interface DeploymentReadinessReport {
+    ok: boolean;
+    state: DeploymentRuntimeState;
+    checkedAt: string;
+    resources: DeploymentReadinessItem[];
+}
+
+export interface DeploymentDiagnosticsResource {
+    name: string;
+    lifecycle: DeploymentResourceStatus;
+    details?: Readonly<Record<string, unknown>>;
+    error?: string;
+}
+
+export interface DeploymentDiagnosticsReport {
+    metadata: DeploymentMetadata;
+    state: DeploymentRuntimeState;
+    uptimeSeconds: number;
+    resources: DeploymentDiagnosticsResource[];
+}
+
+export interface DeploymentRuntimeOptions {
+    serviceName: string;
+    version?: string;
+    deploymentId?: string;
+    instanceId?: string;
+    release?: string;
+    environmentName?: string;
+    environment?: NodeJS.ProcessEnv;
+    shutdownTimeoutMs?: number;
+    readinessTimeoutMs?: number;
+    now?: () => number;
+    idFactory?: () => string;
+    resources?: readonly DeploymentResource[];
+}
+
+export interface DeploymentShutdownOptions {
+    reason?: string;
+}
+
+export interface DeploymentSignalOptions {
+    signals?: readonly NodeJS.Signals[];
+    setExitCode?: boolean;
+}
+
+export interface DeploymentRuntime {
+    readonly metadata: DeploymentMetadata;
+    readonly state: DeploymentRuntimeState;
+    addResource(resource: DeploymentResource): () => void;
+    resources(): DeploymentResourceStatus[];
+    start(): Promise<void>;
+    readiness(): Promise<DeploymentReadinessReport>;
+    diagnostics(): Promise<DeploymentDiagnosticsReport>;
+    shutdown(options?: DeploymentShutdownOptions): Promise<void>;
+    installSignalHandlers(options?: DeploymentSignalOptions): () => void;
+    registerShutdownHook(name?: string): () => void;
+}
+
+const DEFAULT_SHUTDOWN_TIMEOUT_MS =
+    10_000;
+const DEFAULT_READINESS_TIMEOUT_MS =
+    5_000;
+const DEFAULT_SIGNALS:
+    readonly NodeJS.Signals[] = [
+        "SIGTERM",
+        "SIGINT",
+    ];
+
+export function createDeploymentRuntime(
+    options: DeploymentRuntimeOptions
+): DeploymentRuntime {
+    const environment =
+        options.environment ?? process.env;
+    const now =
+        options.now ?? Date.now;
+    const idFactory =
+        options.idFactory ?? randomUUID;
+    const shutdownTimeoutMs =
+        positiveInteger(
+            options.shutdownTimeoutMs ??
+            parseOptionalPositiveInteger(
+                environment.BCP_SHUTDOWN_TIMEOUT_MS
+            ) ??
+            DEFAULT_SHUTDOWN_TIMEOUT_MS,
+            "shutdownTimeoutMs"
+        );
+    const readinessTimeoutMs =
+        positiveInteger(
+            options.readinessTimeoutMs ??
+            DEFAULT_READINESS_TIMEOUT_MS,
+            "readinessTimeoutMs"
+        );
+    const startedAtMs = now();
+    assertTimestamp(
+        startedAtMs,
+        "runtime start timestamp"
+    );
+    const metadata:
+        DeploymentMetadata = {
+        serviceName:
+            normalizeName(
+                options.serviceName,
+                "serviceName"
+            ),
+        ...(normalizeOptionalText(
+            options.version
+        )
+            ? {
+                version:
+                    normalizeOptionalText(
+                        options.version
+                    ),
+            }
+            : {}),
+        deploymentId:
+            normalizeName(
+                options.deploymentId ??
+                environment.BCP_DEPLOYMENT_ID ??
+                idFactory(),
+                "deploymentId"
+            ),
+        ...(normalizeOptionalText(
+            options.instanceId ??
+            environment.BCP_INSTANCE_ID
+        )
+            ? {
+                instanceId:
+                    normalizeOptionalText(
+                        options.instanceId ??
+                        environment.BCP_INSTANCE_ID
+                    ),
+            }
+            : {}),
+        ...(normalizeOptionalText(
+            options.release ??
+            environment.BCP_RELEASE
+        )
+            ? {
+                release:
+                    normalizeOptionalText(
+                        options.release ??
+                        environment.BCP_RELEASE
+                    ),
+            }
+            : {}),
+        ...(normalizeOptionalText(
+            options.environmentName ??
+            environment.NODE_ENV
+        )
+            ? {
+                environment:
+                    normalizeOptionalText(
+                        options.environmentName ??
+                        environment.NODE_ENV
+                    ),
+            }
+            : {}),
+        startedAt:
+            new Date(startedAtMs)
+                .toISOString(),
+        pid: process.pid,
+        nodeVersion:
+            process.version,
+        platform:
+            process.platform,
+        arch:
+            process.arch,
+    };
+    const abortController =
+        new AbortController();
+    const resourceEntries:
+        Array<{
+            resource: DeploymentResource;
+            status: DeploymentResourceStatus;
+        }> = [];
+    const names =
+        new Set<string>();
+    let state:
+        DeploymentRuntimeState =
+        "idle";
+    let startPromise:
+        Promise<void> | undefined;
+    let shutdownPromise:
+        Promise<void> | undefined;
+
+    const runtime:
+        DeploymentRuntime = {
+        metadata,
+        get state(): DeploymentRuntimeState {
+            return state;
+        },
+        addResource(
+            resource: DeploymentResource
+        ): () => void {
+            if (
+                state !== "idle"
+            ) {
+                throw new Error(
+                    "BCP Deployment: resources can only be registered before runtime start."
+                );
+            }
+            const name =
+                normalizeName(
+                    resource.name,
+                    "resource name"
+                );
+            if (names.has(name)) {
+                throw new Error(
+                    `BCP Deployment: resource "${name}" is already registered.`
+                );
+            }
+            const normalized:
+                DeploymentResource = {
+                ...resource,
+                name,
+            };
+            const entry = {
+                resource: normalized,
+                status: {
+                    name,
+                    state:
+                        "registered" as const,
+                },
+            };
+            names.add(name);
+            resourceEntries.push(entry);
+            return () => {
+                if (state !== "idle") {
+                    return;
+                }
+                const index =
+                    resourceEntries.indexOf(
+                        entry
+                    );
+                if (index >= 0) {
+                    resourceEntries.splice(
+                        index,
+                        1
+                    );
+                    names.delete(name);
+                }
+            };
+        },
+        resources(): DeploymentResourceStatus[] {
+            return resourceEntries.map(
+                entry => ({
+                    ...entry.status,
+                })
+            );
+        },
+        async start(): Promise<void> {
+            if (state === "ready") {
+                return;
+            }
+            if (startPromise) {
+                return startPromise;
+            }
+            if (
+                state === "draining" ||
+                state === "stopped"
+            ) {
+                throw new Error(
+                    "BCP Deployment: stopped runtime cannot be started again."
+                );
+            }
+            if (state === "failed") {
+                throw new Error(
+                    "BCP Deployment: failed runtime cannot be started again."
+                );
+            }
+
+            startPromise =
+                startResources();
+            return startPromise;
+        },
+        async readiness(): Promise<DeploymentReadinessReport> {
+            const checkedAtMs = now();
+            assertTimestamp(
+                checkedAtMs,
+                "readiness timestamp"
+            );
+            const results:
+                DeploymentReadinessItem[] = [];
+
+            for (const entry of resourceEntries) {
+                if (
+                    entry.status.state !==
+                    "started"
+                ) {
+                    results.push({
+                        name:
+                            entry.resource.name,
+                        ok: false,
+                        durationMs: 0,
+                        detail:
+                            `Resource state is ${entry.status.state}.`,
+                    });
+                    continue;
+                }
+
+                if (!entry.resource.ready) {
+                    results.push({
+                        name:
+                            entry.resource.name,
+                        ok: true,
+                        durationMs: 0,
+                    });
+                    continue;
+                }
+
+                const checkStarted =
+                    performance.now();
+                try {
+                    const value =
+                        await withTimeout(
+                            Promise.resolve(
+                                entry.resource.ready(
+                                    createContext()
+                                )
+                            ),
+                            readinessTimeoutMs,
+                            `readiness check for ${entry.resource.name}`
+                        );
+                    const normalized =
+                        typeof value ===
+                        "boolean"
+                            ? {
+                                ok: value,
+                            }
+                            : value;
+                    results.push({
+                        name:
+                            entry.resource.name,
+                        ok:
+                            normalized.ok ===
+                            true,
+                        durationMs:
+                            elapsedMilliseconds(
+                                checkStarted
+                            ),
+                        ...(normalized.detail
+                            ? {
+                                detail:
+                                    normalized.detail,
+                            }
+                            : {}),
+                    });
+                } catch (error) {
+                    results.push({
+                        name:
+                            entry.resource.name,
+                        ok: false,
+                        durationMs:
+                            elapsedMilliseconds(
+                                checkStarted
+                            ),
+                        detail:
+                            errorMessage(error),
+                    });
+                }
+            }
+
+            return {
+                ok:
+                    state === "ready" &&
+                    results.every(
+                        item => item.ok
+                    ),
+                state,
+                checkedAt:
+                    new Date(
+                        checkedAtMs
+                    ).toISOString(),
+                resources:
+                    results,
+            };
+        },
+        async diagnostics(): Promise<DeploymentDiagnosticsReport> {
+            const resources:
+                DeploymentDiagnosticsResource[] = [];
+
+            for (const entry of resourceEntries) {
+                let details:
+                    Readonly<Record<string, unknown>> |
+                    undefined;
+                let error:
+                    string | undefined;
+                if (entry.resource.diagnostics) {
+                    try {
+                        details =
+                            await entry.resource.diagnostics(
+                                createContext()
+                            );
+                    } catch (diagnosticError) {
+                        error =
+                            errorMessage(
+                                diagnosticError
+                            );
+                    }
+                }
+                resources.push({
+                    name:
+                        entry.resource.name,
+                    lifecycle: {
+                        ...entry.status,
+                    },
+                    ...(details
+                        ? {
+                            details,
+                        }
+                        : {}),
+                    ...(error
+                        ? {
+                            error,
+                        }
+                        : {}),
+                });
+            }
+
+            return {
+                metadata: {
+                    ...metadata,
+                },
+                state,
+                uptimeSeconds:
+                    Math.max(
+                        0,
+                        (
+                            now() -
+                            startedAtMs
+                        ) /
+                        1000
+                    ),
+                resources,
+            };
+        },
+        async shutdown(
+            _options: DeploymentShutdownOptions = {}
+        ): Promise<void> {
+            if (shutdownPromise) {
+                return shutdownPromise;
+            }
+            if (state === "stopped") {
+                return;
+            }
+            shutdownPromise =
+                stopResources();
+            return shutdownPromise;
+        },
+        installSignalHandlers(
+            signalOptions:
+                DeploymentSignalOptions = {}
+        ): () => void {
+            const signals =
+                normalizeSignals(
+                    signalOptions.signals ??
+                    DEFAULT_SIGNALS
+                );
+            const handlers =
+                new Map<
+                    NodeJS.Signals,
+                    () => void
+                >();
+
+            for (const signal of signals) {
+                const handler = () => {
+                    void runtime.shutdown({
+                        reason: signal,
+                    }).then(
+                        () => {
+                            if (
+                                signalOptions.setExitCode !==
+                                false
+                            ) {
+                                process.exitCode = 0;
+                            }
+                        },
+                        () => {
+                            process.exitCode = 1;
+                        }
+                    );
+                };
+                handlers.set(
+                    signal,
+                    handler
+                );
+                process.on(
+                    signal,
+                    handler
+                );
+            }
+
+            return () => {
+                for (
+                    const [
+                        signal,
+                        handler,
+                    ]
+                    of handlers
+                ) {
+                    process.off(
+                        signal,
+                        handler
+                    );
+                }
+                handlers.clear();
+            };
+        },
+        registerShutdownHook(
+            name =
+                `deployment:${metadata.serviceName}`
+        ): () => void {
+            return registerShutdownHook(
+                () =>
+                    runtime.shutdown({
+                        reason:
+                            "framework-shutdown",
+                    }),
+                {
+                    name,
+                }
+            );
+        },
+    };
+
+    for (
+        const resource
+        of options.resources ?? []
+    ) {
+        runtime.addResource(resource);
+    }
+
+    return runtime;
+
+    async function startResources(): Promise<void> {
+        state = "starting";
+        try {
+            for (const entry of resourceEntries) {
+                entry.status = {
+                    name:
+                        entry.resource.name,
+                    state: "starting",
+                };
+                try {
+                    await entry.resource.start?.(
+                        createContext()
+                    );
+                    entry.status = {
+                        name:
+                            entry.resource.name,
+                        state: "started",
+                        startedAt:
+                            new Date(
+                                now()
+                            ).toISOString(),
+                    };
+                } catch (error) {
+                    entry.status = {
+                        name:
+                            entry.resource.name,
+                        state: "failed",
+                        error:
+                            errorMessage(error),
+                    };
+                    throw new Error(
+                        `BCP Deployment: resource "${entry.resource.name}" failed to start. ${errorMessage(error)}`
+                    );
+                }
+            }
+            state = "ready";
+        } catch (error) {
+            state = "failed";
+            abortController.abort(error);
+            await stopStartedResources(
+                shutdownTimeoutMs
+            );
+            throw error;
+        }
+    }
+
+    async function stopResources(): Promise<void> {
+        state = "draining";
+        if (!abortController.signal.aborted) {
+            abortController.abort(
+                new Error(
+                    "BCP Deployment: runtime is shutting down."
+                )
+            );
+        }
+        const failures =
+            await stopStartedResources(
+                shutdownTimeoutMs
+            );
+        state =
+            failures.length > 0
+                ? "failed"
+                : "stopped";
+        if (failures.length > 0) {
+            throw new AggregateError(
+                failures,
+                "BCP Deployment: one or more resources failed to stop."
+            );
+        }
+    }
+
+    async function stopStartedResources(
+        timeoutMs: number
+    ): Promise<Error[]> {
+        const failures:
+            Error[] = [];
+        const deadline =
+            Date.now() + timeoutMs;
+
+        for (
+            const entry
+            of [...resourceEntries].reverse()
+        ) {
+            if (
+                entry.status.state !==
+                "started"
+            ) {
+                continue;
+            }
+            entry.status = {
+                ...entry.status,
+                state: "stopping",
+            };
+            try {
+                const remaining =
+                    Math.max(
+                        1,
+                        deadline -
+                        Date.now()
+                    );
+                await withTimeout(
+                    Promise.resolve(
+                        entry.resource.stop?.(
+                            createContext()
+                        )
+                    ),
+                    remaining,
+                    `shutdown of ${entry.resource.name}`
+                );
+                entry.status = {
+                    ...entry.status,
+                    state: "stopped",
+                    stoppedAt:
+                        new Date(
+                            now()
+                        ).toISOString(),
+                };
+            } catch (error) {
+                const message =
+                    errorMessage(error);
+                entry.status = {
+                    ...entry.status,
+                    state: "failed",
+                    error: message,
+                };
+                failures.push(
+                    new Error(
+                        `BCP Deployment: resource "${entry.resource.name}" failed to stop. ${message}`
+                    )
+                );
+            }
+        }
+
+        return failures;
+    }
+
+    function createContext(): DeploymentResourceContext {
+        return {
+            metadata,
+            signal:
+                abortController.signal,
+        };
+    }
+}
+
+export function createDeploymentReadinessResponse(
+    runtime: DeploymentRuntime
+): Promise<Response> {
+    return runtime.readiness()
+        .then(
+            report =>
+                Response.json(
+                    report,
+                    {
+                        status:
+                            report.ok
+                                ? 200
+                                : 503,
+                        headers: {
+                            "cache-control":
+                                "no-store",
+                        },
+                    }
+                )
+        );
+}
+
+export async function createDeploymentDiagnosticsResponse(
+    runtime: DeploymentRuntime
+): Promise<Response> {
+    return Response.json(
+        await runtime.diagnostics(),
+        {
+            status: 200,
+            headers: {
+                "cache-control":
+                    "no-store",
+            },
+        }
+    );
+}
+
+function normalizeSignals(
+    signals: readonly NodeJS.Signals[]
+): NodeJS.Signals[] {
+    return Array.from(
+        new Set(signals)
+    );
+}
+
+function normalizeName(
+    value: string,
+    field: string
+): string {
+    const normalized =
+        String(value ?? "").trim();
+    if (!normalized) {
+        throw new TypeError(
+            `BCP Deployment: ${field} must be a non-empty string.`
+        );
+    }
+    if (
+        normalized.length > 256 ||
+        /[\r\n]/.test(normalized)
+    ) {
+        throw new TypeError(
+            `BCP Deployment: ${field} must be at most 256 characters without line breaks.`
+        );
+    }
+    return normalized;
+}
+
+function normalizeOptionalText(
+    value: string | undefined
+): string | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+    const normalized =
+        value.trim();
+    return normalized || undefined;
+}
+
+function positiveInteger(
+    value: number,
+    field: string
+): number {
+    if (
+        !Number.isSafeInteger(value) ||
+        value <= 0
+    ) {
+        throw new TypeError(
+            `BCP Deployment: ${field} must be a positive safe integer.`
+        );
+    }
+    return value;
+}
+
+function parseOptionalPositiveInteger(
+    value: string | undefined
+): number | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed =
+        Number(value.trim());
+    if (
+        !Number.isSafeInteger(parsed) ||
+        parsed <= 0
+    ) {
+        throw new TypeError(
+            "BCP Deployment: BCP_SHUTDOWN_TIMEOUT_MS must be a positive safe integer."
+        );
+    }
+    return parsed;
+}
+
+function assertTimestamp(
+    value: number,
+    field: string
+): void {
+    if (!Number.isFinite(value)) {
+        throw new TypeError(
+            `BCP Deployment: ${field} must be a finite number.`
+        );
+    }
+}
+
+function errorMessage(
+    error: unknown
+): string {
+    return error instanceof Error
+        ? error.message
+        : String(error);
+}
+
+function elapsedMilliseconds(
+    startedAt: number
+): number {
+    return Math.max(
+        0,
+        performance.now() - startedAt
+    );
+}
+
+function withTimeout<T>(
+    promise: Promise<T>,
+    timeoutMs: number,
+    label: string
+): Promise<T> {
+    return new Promise<T>(
+        (
+            resolve,
+            reject
+        ) => {
+            const timer =
+                setTimeout(
+                    () =>
+                        reject(
+                            new Error(
+                                `BCP Deployment: ${label} timed out after ${timeoutMs}ms.`
+                            )
+                        ),
+                    timeoutMs
+                );
+            timer.unref?.();
+            promise.then(
+                value => {
+                    clearTimeout(timer);
+                    resolve(value);
+                },
+                error => {
+                    clearTimeout(timer);
+                    reject(error);
+                }
+            );
+        }
+    );
+}