target-supabase-sdk 0.2.3 → 0.2.5

package/src/node/service-guard/register-service-guard-runner.ts

@@ -0,0 +1,64 @@
+import type { TriggerRunnerContext } from "../../trigger/trigger.interface";
+import { TriggerManager } from "../../trigger/trigger-manager";
+import { runServiceGuardTick } from "./run-service-guard-tick";
+import { type RegisterServiceGuardRunnerOptions, SERVICE_GUARD_RUNNER_KEY } from "./service-guard.interface";
+
+async function runServiceGuardRunner(
+    ctx: TriggerRunnerContext,
+    options: RegisterServiceGuardRunnerOptionsWithClock,
+): Promise<void> {
+    const { loopTraceId, nodeId, logger } = ctx;
+    const nowMs = options.now?.() ?? Date.now();
+    const checkedAt = new Date(nowMs).toISOString();
+    const serviceId = await options.getServiceId();
+
+    const result = await runServiceGuardTick({
+        serviceValue: options.serviceValue,
+        serviceId,
+        nodeId,
+        loopTraceId,
+        logger,
+        logTopic: options.logTopic,
+        checkedAt,
+        nowMs,
+        taskNodeStaleMs: options.taskNodeStaleMs,
+        workerSpawnCooldownMs: options.workerSpawnCooldownMs,
+        maxNodes: options.maxNodes,
+        spawnWorker: options.spawnWorker,
+    });
+
+    if (result.registryPatch != null) {
+        await options.onRegistryPatch(result.registryPatch);
+    }
+
+    if (!result.continueTick) {
+        return;
+    }
+
+    await options.onGuardPatch({
+        nodeId,
+        lastCheckAt: checkedAt,
+        lastDecision: result.decision,
+    });
+
+    if (options.onDecision != null) {
+        await options.onDecision(result.decision);
+    }
+}
+
+export interface RegisterServiceGuardRunnerOptionsWithClock extends RegisterServiceGuardRunnerOptions {
+    /** Test hook — defaults to Date.now(). */
+    now?: () => number;
+}
+
+/** Register the standard L3 guard runner (registry slot + TaskNode + Service runtime). */
+export function registerServiceGuardRunner(options: RegisterServiceGuardRunnerOptionsWithClock): void {
+    TriggerManager.registerRunner({
+        key: options.runnerKey ?? SERVICE_GUARD_RUNNER_KEY,
+        intervalMs: options.intervalMs,
+        initialDelayMs: options.initialDelayMs,
+        fn: (ctx) => runServiceGuardRunner(ctx, options),
+    });
+}
+
+export { SERVICE_GUARD_RUNNER_KEY };

package/src/node/service-guard/run-readiness-gate.ts

@@ -0,0 +1,34 @@
+import type { LoggerWithScope } from "../../shared/log";
+import type { ReadinessCheck, ReadinessReport } from "../readiness/readiness.types";
+import { runReadinessChecks } from "../readiness/run-readiness-checks";
+
+export interface RunReadinessGateInput {
+    checks: ReadinessCheck[];
+    onReport: (report: ReadinessReport) => Promise<void>;
+    logger: LoggerWithScope;
+    logTopic?: string;
+}
+
+/** Run readiness checks, persist report via callback, fail-fast when not ok. */
+export async function runReadinessGate(input: RunReadinessGateInput): Promise<ReadinessReport> {
+    const { checks, onReport, logger, logTopic = "guard" } = input;
+
+    logger.info("Running readiness checks", { topic: logTopic });
+    const report = await runReadinessChecks(checks);
+    await onReport(report);
+
+    if (!report.ok) {
+        logger.error("Readiness checks failed", {
+            topic: logTopic,
+            data: { message: report.message, checks: report.checks },
+        });
+        throw new Error(report.message ?? "Readiness checks failed");
+    }
+
+    logger.debug("Readiness checks passed", {
+        topic: logTopic,
+        data: { checks: report.checks.map((check) => check.name) },
+    });
+
+    return report;
+}

package/src/node/service-guard/run-service-guard-tick.ts

@@ -0,0 +1,106 @@
+import { CategoryNode, evaluateBusyNodeLiveness, type Node, patchServiceRuntime, scanTargetList } from "../../browser";
+import { applyRegistrySlotGuardStep } from "../service-host/registry-slot-guard-step";
+import type { ServiceGuardTickInput, ServiceGuardTickResult } from "./service-guard.interface";
+import { getWorkerSpawnCooldownLastAt, markWorkerSpawned } from "./worker-spawn-cooldown";
+
+/**
+ * One guard-runner tick: registry slot check, TaskNode liveness, optional worker
+ * respawn, Service runtime heartbeat rollup.
+ */
+export async function runServiceGuardTick(input: ServiceGuardTickInput): Promise<ServiceGuardTickResult> {
+    const {
+        serviceValue,
+        serviceId,
+        nodeId,
+        loopTraceId,
+        logger,
+        logTopic = "guard",
+        checkedAt,
+        nowMs,
+        taskNodeStaleMs,
+        workerSpawnCooldownMs,
+        maxNodes = 200,
+        spawnWorker,
+        getLastWorkerSpawnAt = getWorkerSpawnCooldownLastAt,
+        markWorkerSpawned: markWorkerSpawnedAt = markWorkerSpawned,
+    } = input;
+
+    const continueTick = true;
+    let registryPatch: ServiceGuardTickResult["registryPatch"];
+    let decision = "idle";
+
+    if (serviceId != null) {
+        const guard = await applyRegistrySlotGuardStep({
+            serviceValue,
+            serviceId,
+            checkedAt,
+            logger,
+            logTopic,
+            traceId: loopTraceId,
+        });
+        registryPatch = guard.registryPatch;
+        if (!guard.continueTick) {
+            return { continueTick: false, decision: "slot_lost", nodes: [], registryPatch };
+        }
+        decision = "slot_ok";
+    }
+
+    const { data: nodes = [] } = await scanTargetList<Node>({
+        category: CategoryNode.NODE,
+        maxRows: maxNodes,
+    });
+
+    const liveness = evaluateBusyNodeLiveness(nodes, {
+        staleMs: taskNodeStaleMs,
+        now: nowMs,
+        excludeNodeId: nodeId,
+        onlyFreshCandidates: true,
+    });
+
+    const ageMs = liveness.freshest?.ageMs ?? Number.POSITIVE_INFINITY;
+
+    if (liveness.healthy) {
+        decision = "healthy";
+    } else if (nowMs - getLastWorkerSpawnAt() < workerSpawnCooldownMs) {
+        decision = "spawn_cooldown";
+        logger.warn("TaskNode unavailable but spawn cooldown active", {
+            topic: logTopic,
+            data: {
+                traceId: loopTraceId,
+                ageMs,
+                staleMs: taskNodeStaleMs,
+                cooldownMs: workerSpawnCooldownMs,
+            },
+        });
+    } else {
+        decision = "spawn_worker";
+        logger.warn("TaskNode stale — restarting worker", {
+            topic: logTopic,
+            data: {
+                traceId: loopTraceId,
+                peerWorkerCount: liveness.busyWorkerCount,
+                freshPeerCount: liveness.freshWorkerCount,
+                staleMs: taskNodeStaleMs,
+            },
+        });
+        await spawnWorker("guard:restart-unhealthy-tasknode");
+        markWorkerSpawnedAt(nowMs);
+    }
+
+    try {
+        await patchServiceRuntime({
+            serviceValue,
+            serviceId: serviceId ?? undefined,
+            nodes,
+            lastHeartBeat: nowMs,
+        });
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.warn("Failed to patch Service runtime rollup", {
+            topic: logTopic,
+            data: { traceId: loopTraceId, message },
+        });
+    }
+
+    return { continueTick, decision, nodes, registryPatch };
+}

package/src/node/service-guard/service-guard-node.ts

@@ -0,0 +1,52 @@
+import type { LoggerWithScope } from "../../shared/log";
+import { TriggerNode } from "../../trigger/trigger-node";
+import { registerServiceGuardRunner } from "./register-service-guard-runner";
+import { runReadinessGate } from "./run-readiness-gate";
+import type { ServiceGuardNodeOptions } from "./service-guard.interface";
+
+/**
+ * L3 guard process TriggerNode: readiness gate, TaskNode worker spawn owner,
+ * and {@link registerServiceGuardRunner} tick (registry slot + liveness + runtime).
+ *
+ * Use {@link ServiceGuardNode.create} so the guard runner is registered before `start()`.
+ */
+class ServiceGuardNode extends TriggerNode {
+    private readonly options: ServiceGuardNodeOptions;
+
+    private constructor(options: ServiceGuardNodeOptions) {
+        super({
+            requireRunners: true,
+            beforeProcessExit: options.beforeProcessExit,
+        });
+        this.options = options;
+    }
+
+    /** Register the guard runner and return a ready-to-start node. */
+    static create(options: ServiceGuardNodeOptions): ServiceGuardNode {
+        registerServiceGuardRunner({
+            serviceValue: options.serviceValue,
+            logTopic: options.logTopic,
+            ...options.guardRunner,
+        });
+        return new ServiceGuardNode(options);
+    }
+
+    protected async onBeforeRegisterNode(nodeLogger: LoggerWithScope): Promise<void> {
+        await runReadinessGate({
+            checks: this.options.readinessChecks,
+            onReport: this.options.onReadinessReport,
+            logger: nodeLogger,
+            logTopic: this.options.logTopic,
+        });
+
+        await super.onBeforeRegisterNode(nodeLogger);
+
+        nodeLogger.info("Spawning TaskNode worker (single spawn owner)", {
+            topic: this.options.logTopic ?? "guard",
+        });
+        await this.options.spawnWorker("guard:readiness-passed");
+        this.options.onWorkerSpawned?.();
+    }
+}
+
+export { ServiceGuardNode };

package/src/node/service-guard/service-guard.interface.ts

@@ -0,0 +1,64 @@
+import type { Node } from "../../node/node.interface";
+import type { RegistrySlotRuntimeState } from "../../service/registry-lifecycle";
+import type { LoggerWithScope } from "../../shared/log";
+import type { TriggerNodeOptions } from "../../trigger/trigger.interface";
+import type { ReadinessCheck, ReadinessReport } from "../readiness/readiness.types";
+
+/** Default TriggerManager runner key for {@link registerServiceGuardRunner}. */
+export const SERVICE_GUARD_RUNNER_KEY = "service-guard";
+
+export interface ServiceGuardTickInput {
+    serviceValue: string;
+    serviceId: string | null;
+    nodeId: string;
+    loopTraceId: string;
+    logger: LoggerWithScope;
+    logTopic?: string;
+    checkedAt: string;
+    nowMs: number;
+    taskNodeStaleMs: number;
+    workerSpawnCooldownMs: number;
+    maxNodes?: number;
+    spawnWorker: (reason: string) => Promise<void>;
+    getLastWorkerSpawnAt?: () => number;
+    markWorkerSpawned?: (at: number) => void;
+}
+
+export interface ServiceGuardTickResult {
+    continueTick: boolean;
+    decision: string;
+    nodes: Node[];
+    registryPatch?: Pick<RegistrySlotRuntimeState, "slotOwned" | "lastSlotCheckAt" | "lastSlotCheckError">;
+}
+
+export interface RegisterServiceGuardRunnerOptions {
+    serviceValue: string;
+    getServiceId: () => Promise<string | null>;
+    logTopic?: string;
+    runnerKey?: string;
+    intervalMs: number;
+    initialDelayMs?: number;
+    taskNodeStaleMs: number;
+    workerSpawnCooldownMs: number;
+    maxNodes?: number;
+    spawnWorker: (reason: string) => Promise<void>;
+    onRegistryPatch: (
+        patch: Pick<RegistrySlotRuntimeState, "slotOwned" | "lastSlotCheckAt" | "lastSlotCheckError">,
+    ) => Promise<void>;
+    onGuardPatch: (patch: { nodeId: string; lastCheckAt: string; lastDecision?: string }) => Promise<void>;
+    onDecision?: (decision: string) => Promise<void>;
+}
+
+export interface ServiceGuardNodeOptions extends TriggerNodeOptions {
+    serviceValue: string;
+    logTopic?: string;
+    readinessChecks: ReadinessCheck[];
+    onReadinessReport: (report: ReadinessReport) => Promise<void>;
+    guardRunner: Omit<
+        RegisterServiceGuardRunnerOptions,
+        "serviceValue" | "logTopic" | "runnerKey" | "intervalMs" | "initialDelayMs"
+    > &
+        Pick<RegisterServiceGuardRunnerOptions, "intervalMs" | "initialDelayMs">;
+    spawnWorker: (reason: string) => Promise<void>;
+    onWorkerSpawned?: () => void;
+}

package/src/node/service-guard/worker-spawn-cooldown.ts

@@ -0,0 +1,13 @@
+let lastWorkerSpawnAt = 0;
+
+export function getWorkerSpawnCooldownLastAt(): number {
+    return lastWorkerSpawnAt;
+}
+
+export function markWorkerSpawned(at = Date.now()): void {
+    lastWorkerSpawnAt = at;
+}
+
+export function resetWorkerSpawnCooldownForTests(): void {
+    lastWorkerSpawnAt = 0;
+}

package/src/node/service-host/index.ts

@@ -0,0 +1,30 @@
+export type {
+    RegisterServiceGuardRunnerOptions,
+    RunReadinessGateInput,
+    ServiceGuardNodeOptions,
+    ServiceGuardTickInput,
+    ServiceGuardTickResult,
+} from "../service-guard";
+export {
+    getWorkerSpawnCooldownLastAt,
+    markWorkerSpawned,
+    registerServiceGuardRunner,
+    runReadinessGate,
+    runServiceGuardTick,
+    SERVICE_GUARD_RUNNER_KEY,
+    ServiceGuardNode,
+} from "../service-guard";
+export type {
+    ApplyRegistrySlotGuardInput,
+    ApplyRegistrySlotGuardResult,
+} from "./registry-slot-guard-step";
+export { applyRegistrySlotGuardStep } from "./registry-slot-guard-step";
+export type {
+    ServiceHost,
+    ServiceHostClosable,
+    ServiceHostContext,
+    ServiceHostOptions,
+} from "./service-host";
+export { createServiceHost } from "./service-host";
+export type { SingleProcessServiceContext, SingleProcessServiceOptions } from "./single-process-service";
+export { runSingleProcessService } from "./single-process-service";

package/src/node/service-host/registry-slot-guard-step.ts

@@ -0,0 +1,57 @@
+import { registrySlotRuntimePatchFromGuardResult, runRegistrySlotGuardCheck } from "../../service/registry-lifecycle";
+import type { LoggerWithScope } from "../../shared/log";
+
+export interface ApplyRegistrySlotGuardInput {
+    serviceValue: string;
+    serviceId: string;
+    checkedAt: string;
+    logger: Pick<LoggerWithScope, "critical" | "warn">;
+    logTopic?: string;
+    traceId?: string;
+}
+
+export interface ApplyRegistrySlotGuardResult {
+    /** When false, caller should abort the supervisor tick (slot lost shutdown initiated). */
+    continueTick: boolean;
+    registryPatch: ReturnType<typeof registrySlotRuntimePatchFromGuardResult>;
+}
+
+/**
+ * Run registry slot ownership check and optionally SIGTERM the parent main process.
+ * Used by guard / supervisor TriggerNode runners across L3 services.
+ */
+export async function applyRegistrySlotGuardStep(
+    input: ApplyRegistrySlotGuardInput,
+): Promise<ApplyRegistrySlotGuardResult> {
+    const result = await runRegistrySlotGuardCheck({
+        serviceValue: input.serviceValue,
+        serviceId: input.serviceId,
+    });
+    const registryPatch = registrySlotRuntimePatchFromGuardResult(result, input.checkedAt);
+
+    if (result.shouldShutdown) {
+        input.logger.critical("Registry slot lost — shutting down service", {
+            topic: input.logTopic ?? "guard",
+            data: {
+                traceId: input.traceId,
+                serviceId: input.serviceId,
+                serviceValue: input.serviceValue,
+            },
+        });
+        process.kill(process.ppid, "SIGTERM");
+        return { continueTick: false, registryPatch };
+    }
+
+    if (result.error != null) {
+        input.logger.warn("Registry slot check failed (transient) — skipping enforcement this tick", {
+            topic: input.logTopic ?? "guard",
+            data: {
+                traceId: input.traceId,
+                serviceId: input.serviceId,
+                message: result.error,
+            },
+        });
+    }
+
+    return { continueTick: true, registryPatch };
+}

package/src/node/service-host/service-host.ts

@@ -0,0 +1,168 @@
+import { createLogger, type Service, ServiceRegistryError } from "../../browser";
+import { claimServiceRegistrySlot, type ServiceRegistrySession } from "../../service/registry-lifecycle";
+import type { LoggerWithScope } from "../../shared/log";
+import type { ManagedChildProcesses } from "../process/managed-child-processes";
+
+export interface ServiceHostClosable {
+    close: () => Promise<void>;
+}
+
+export interface ServiceHostContext {
+    service: Service;
+    session: ServiceRegistrySession;
+}
+
+export interface ServiceHostOptions {
+    serviceValue: string;
+    logger?: LoggerWithScope;
+    logTopic?: string;
+    childProcesses?: ManagedChildProcesses;
+    /** Labels that trigger host shutdown when the child exits unexpectedly. */
+    criticalSupervisors?: readonly string[];
+
+    prepare?: () => Promise<void>;
+    createInstance: () => Promise<Service | { service: Service; baseUrl?: string }>;
+    onRegistryClaimed?: (ctx: ServiceHostContext) => Promise<void>;
+    startSupervisors?: () => void | Promise<void>;
+    waitUntilReady?: () => Promise<void>;
+    startServer?: () => Promise<ServiceHostClosable>;
+    /** Stop child processes and other local resources (not registry release). */
+    onShutdown?: (signal: string) => Promise<void>;
+}
+
+const DEFAULT_CRITICAL_SUPERVISORS = ["guard", "supervisor"] as const;
+
+export interface ServiceHost {
+    run: () => Promise<void>;
+    requestShutdown: (signal: string, exitCode?: number) => void;
+}
+
+function unwrapService(created: Service | { service: Service; baseUrl?: string }): Service {
+    return typeof created === "object" && created != null && "service" in created ? created.service : created;
+}
+
+export function createServiceHost(options: ServiceHostOptions): ServiceHost {
+    const logger = options.logger ?? createLogger({ module: "service-host" });
+    const logTopic = options.logTopic ?? "startup";
+    const criticalSupervisors = options.criticalSupervisors ?? DEFAULT_CRITICAL_SUPERVISORS;
+
+    let session: ServiceRegistrySession | null = null;
+    let httpServer: ServiceHostClosable | null = null;
+    let shuttingDown = false;
+
+    async function shutdown(signal: string, exitCode = 0): Promise<void> {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
+
+        logger.info("shutting down", { topic: logTopic, data: { signal, exitCode } });
+
+        if (httpServer != null) {
+            await httpServer.close().catch(() => undefined);
+            httpServer = null;
+        }
+
+        if (options.onShutdown != null) {
+            await options.onShutdown(signal).catch(() => undefined);
+        }
+
+        if (session != null) {
+            await session.release();
+            session = null;
+        }
+
+        process.exit(exitCode);
+    }
+
+    function requestShutdown(signal: string, exitCode = 0): void {
+        void shutdown(signal, exitCode);
+    }
+
+    function installProcessHandlers(): void {
+        process.on("SIGINT", () => void shutdown("SIGINT"));
+        process.on("SIGTERM", () => void shutdown("SIGTERM"));
+
+        options.childProcesses?.setCriticalExitHandler({
+            labels: criticalSupervisors,
+            onCriticalExit: (label, code, signal) => {
+                if (shuttingDown) {
+                    return;
+                }
+                logger.critical("Critical supervisor exited — shutting down service", {
+                    topic: logTopic,
+                    data: { label, code, signal },
+                });
+                void shutdown("supervisor-exit", 1);
+            },
+        });
+    }
+
+    async function run(): Promise<void> {
+        installProcessHandlers();
+
+        if (options.prepare != null) {
+            await options.prepare();
+        }
+
+        try {
+            session = await claimServiceRegistrySlot({
+                serviceValue: options.serviceValue,
+                createInstance: async () => unwrapService(await options.createInstance()),
+            });
+        } catch (error) {
+            if (error instanceof ServiceRegistryError && error.code === "SERVICE_SLOTS_FULL") {
+                logger.critical("No EMPTY registry slot — refusing to start", {
+                    topic: logTopic,
+                    data: { serviceValue: options.serviceValue, code: error.code },
+                });
+                process.exit(1);
+            }
+            throw error;
+        }
+
+        if (options.onRegistryClaimed != null) {
+            await options.onRegistryClaimed({ service: session.service, session });
+        }
+
+        if (options.startSupervisors != null) {
+            await options.startSupervisors();
+        }
+
+        if (options.waitUntilReady != null) {
+            await options.waitUntilReady();
+        }
+
+        if (options.startServer != null) {
+            httpServer = await options.startServer();
+        }
+    }
+
+    async function runWithFatalHandling(): Promise<void> {
+        try {
+            await run();
+        } catch (error: unknown) {
+            const message = error instanceof Error ? error.message : String(error);
+            const code = error instanceof ServiceRegistryError ? error.code : undefined;
+            logger.error("fatal", { topic: logTopic, data: { message, code } });
+
+            if (httpServer != null) {
+                await httpServer.close().catch(() => undefined);
+                httpServer = null;
+            }
+
+            if (options.onShutdown != null) {
+                await options.onShutdown("fatal").catch(() => undefined);
+            }
+
+            if (session != null) {
+                await session.release().catch(() => undefined);
+                session = null;
+            }
+
+            process.exit(1);
+        }
+    }
+
+    return { run: runWithFatalHandling, requestShutdown };
+}

package/src/node/service-host/single-process-service.ts

@@ -0,0 +1,58 @@
+import { createLogger, type Service, ServiceRegistryError } from "../../browser";
+import { claimServiceRegistrySlot, type ServiceRegistrySession } from "../../service/registry-lifecycle";
+import type { LoggerWithScope } from "../../shared/log";
+
+export interface SingleProcessServiceContext {
+    service: Service;
+    session: ServiceRegistrySession;
+}
+
+export interface SingleProcessServiceOptions {
+    serviceValue: string;
+    logger?: LoggerWithScope;
+    logTopic?: string;
+
+    prepare?: () => Promise<void>;
+    createInstance: () => Promise<Service>;
+    run: (ctx: SingleProcessServiceContext) => Promise<void>;
+}
+
+/**
+ * Single-process L3 entry (e.g. log-service): claim registry slot then run the service body.
+ * Registry release is the caller's responsibility inside `run` (e.g. TriggerNode `beforeProcessExit`).
+ */
+export async function runSingleProcessService(options: SingleProcessServiceOptions): Promise<void> {
+    const logger = options.logger ?? createLogger({ module: "single-process-service" });
+    const logTopic = options.logTopic ?? "startup";
+
+    if (options.prepare != null) {
+        await options.prepare();
+    }
+
+    let session: ServiceRegistrySession | null = null;
+
+    try {
+        session = await claimServiceRegistrySlot({
+            serviceValue: options.serviceValue,
+            createInstance: options.createInstance,
+        });
+    } catch (error) {
+        if (error instanceof ServiceRegistryError && error.code === "SERVICE_SLOTS_FULL") {
+            logger.critical("No EMPTY registry slot — refusing to start", {
+                topic: logTopic,
+                data: { serviceValue: options.serviceValue, code: error.code },
+            });
+            process.exit(1);
+        }
+        throw error;
+    }
+
+    try {
+        await options.run({ service: session.service, session });
+    } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error("fatal", { topic: logTopic, data: { message } });
+        await session.release().catch(() => undefined);
+        process.exit(1);
+    }
+}