target-supabase-sdk 0.2.11 → 0.2.13

package/src/shared/log/enable-log-persist.ts

@@ -1,225 +0,0 @@
-import { resolve } from "node:path";
-import { envBool } from "../../node/env/env-parsers";
-import { readEnv, requireEnv } from "../../node/env/require-env";
-import { pollUntil } from "../../node/readiness";
-import { createLogger } from "./create-logger";
-import { LogPersist } from "./log-persist";
-import {
-    logPersistConfigFromEnv,
-    logPersistEnabledFromEnv,
-    logPersistProcessFromEnv,
-    logPersistRegistryDirFromEnv,
-    logPersistServiceFromEnv,
-    resolveLogPersistConfig,
-} from "./log-persist.config";
-import type {
-    EnableLogPersistOptions,
-    EnsureLogPersistFromEnvOptions,
-    LogPersistReadySnapshot,
-    LogPersistStats,
-    WaitForLogPersistReadyOptions,
-} from "./log-persist.interface";
-import { registerLogPersistOffer } from "./log-persist-hook";
-import { LOG_PERSIST_TOPIC, persistLogger } from "./log-persist-logger";
-import { defaultLogPersistRegistryPath, readLogPersistRegistry } from "./log-persist-registry";
-
-export { logPersistEnabledFromEnv };
-
-function resolveRegistryFilePath(explicit?: string): string {
-    if (explicit != null && explicit.trim() !== "") {
-        return resolve(explicit);
-    }
-    const dir = logPersistRegistryDirFromEnv();
-    if (dir == null) {
-        throw new Error(
-            "[LogPersist] registry path required: set registryFilePath option or LOG_PERSIST_REGISTRY_DIR / RUNTIME_DATA_DIR",
-        );
-    }
-    return defaultLogPersistRegistryPath(resolve(dir));
-}
-
-export async function enableLogPersist(options: EnableLogPersistOptions): Promise<void> {
-    const registryFilePath = options.registryFilePath != null ? resolve(options.registryFilePath) : undefined;
-    const resolvedRegistry = registryFilePath ?? resolveRegistryFilePath();
-
-    const envConfig = logPersistConfigFromEnv();
-    await LogPersist.getInstance().enable({
-        ...options,
-        registryFilePath: resolvedRegistry,
-        config: resolveLogPersistConfig({
-            fast: { ...envConfig.fast, ...options.config?.fast },
-            medium: { ...envConfig.medium, ...options.config?.medium },
-            slow: { ...envConfig.slow, ...options.config?.slow },
-            postTimeoutMs: options.config?.postTimeoutMs ?? envConfig.postTimeoutMs,
-            shutdownDrainTimeoutMs: options.config?.shutdownDrainTimeoutMs ?? envConfig.shutdownDrainTimeoutMs,
-        }),
-    });
-}
-
-export async function disableLogPersist(): Promise<void> {
-    await LogPersist.getInstance().disable();
-}
-
-export function getLogPersistStats(): LogPersistStats {
-    return LogPersist.getInstance().getStats();
-}
-
-/**
- * Enable log persistence when LOG_PERSIST_ENABLED=true.
- * `process` / `service` can be passed explicitly or via LOG_PERSIST_PROCESS / LOG_PERSIST_SERVICE.
- */
-export async function ensureLogPersistFromEnv(options: EnsureLogPersistFromEnvOptions = {}): Promise<boolean> {
-    if (!logPersistEnabledFromEnv()) {
-        registerLogPersistOffer(null);
-        return false;
-    }
-
-    const service = options.service ?? logPersistServiceFromEnv();
-    const processName = options.process ?? logPersistProcessFromEnv();
-    if (service == null || service === "") {
-        throw new Error("[LogPersist] LOG_PERSIST_SERVICE is required when LOG_PERSIST_ENABLED=true");
-    }
-    if (processName == null || processName === "") {
-        throw new Error(
-            "[LogPersist] LOG_PERSIST_PROCESS is required when LOG_PERSIST_ENABLED=true (or pass process option)",
-        );
-    }
-
-    const registryFilePath =
-        options.registryFilePath != null ? resolve(options.registryFilePath) : resolveRegistryFilePath();
-
-    await enableLogPersist({
-        service,
-        process: processName,
-        registryFilePath,
-        config: options.config,
-    });
-
-    const lifecycleLogger = createLogger({ module: "log-persist" });
-    lifecycleLogger.info("log persist enabled from env", {
-        topic: LOG_PERSIST_TOPIC,
-        data: { service, process: processName, registryFilePath },
-    });
-
-    return true;
-}
-
-/**
- * Preload guard: when persistence is enabled, required env must be present before app code runs.
- */
-export function validateLogPersistPreloadEnv(env: NodeJS.ProcessEnv = process.env): void {
-    if (!envBool("LOG_PERSIST_ENABLED", false, env)) {
-        return;
-    }
-
-    const missing: string[] = [];
-    if (readEnv("LOG_PERSIST_SERVICE", env) == null) {
-        missing.push("LOG_PERSIST_SERVICE");
-    }
-    const registryDir = logPersistRegistryDirFromEnv(env);
-    if (registryDir == null) {
-        missing.push("LOG_PERSIST_REGISTRY_DIR or RUNTIME_DATA_DIR");
-    }
-
-    if (missing.length > 0) {
-        throw new Error(`[LogPersist] preload env incomplete: ${missing.join(", ")}`);
-    }
-}
-
-function evaluateLogPersistReady(
-    state: Awaited<ReturnType<typeof readLogPersistRegistry>>,
-    expectedProcesses: string[],
-    staleMs: number,
-    now: number,
-): LogPersistReadySnapshot {
-    const missing: string[] = [];
-    const stale: string[] = [];
-    const registered: string[] = [];
-
-    for (const processName of expectedProcesses) {
-        const record = state.processes[processName];
-        if (record == null) {
-            missing.push(processName);
-            continue;
-        }
-
-        const heartbeatAt = Date.parse(record.lastHeartbeatAt);
-        if (!Number.isFinite(heartbeatAt) || now - heartbeatAt > staleMs) {
-            stale.push(processName);
-            continue;
-        }
-
-        registered.push(processName);
-    }
-
-    return {
-        ok: missing.length === 0 && stale.length === 0,
-        missing,
-        stale,
-        registered,
-    };
-}
-
-/**
- * Wait until every expected process has registered in the shared registry with a fresh heartbeat.
- * Call from the service main process after spawning children.
- */
-export async function waitForLogPersistReady(options: WaitForLogPersistReadyOptions): Promise<LogPersistReadySnapshot> {
-    const timeoutMs = options.timeoutMs ?? 60_000;
-    const pollIntervalMs = options.pollIntervalMs ?? 500;
-    const staleMs = options.staleMs ?? 90_000;
-
-    let last: LogPersistReadySnapshot = {
-        ok: false,
-        missing: [...options.expectedProcesses],
-        stale: [],
-        registered: [],
-    };
-
-    try {
-        await pollUntil({
-            intervalMs: pollIntervalMs,
-            timeoutMs,
-            until: async () => {
-                const state = await readLogPersistRegistry(options.registryFilePath);
-                if (state.service !== options.service) {
-                    last = {
-                        ok: false,
-                        missing: options.expectedProcesses,
-                        stale: [],
-                        registered: [],
-                    };
-                    return false;
-                }
-                last = evaluateLogPersistReady(state, options.expectedProcesses, staleMs, Date.now());
-                return last.ok;
-            },
-        });
-    } catch {
-        persistLogger.warn("waitForLogPersistReady timed out", {
-            timeoutMs,
-            expectedProcesses: options.expectedProcesses,
-            ...last,
-        });
-    }
-
-    return last;
-}
-
-export async function snapshotLogPersistReady(options: {
-    registryFilePath: string;
-    service: string;
-    expectedProcesses: string[];
-    staleMs?: number;
-}): Promise<LogPersistReadySnapshot> {
-    const state = await readLogPersistRegistry(options.registryFilePath);
-    return evaluateLogPersistReady(state, options.expectedProcesses, options.staleMs ?? 90_000, Date.now());
-}
-
-export function resolveLogPersistRegistryPath(registryDir?: string): string {
-    const dir = registryDir ?? logPersistRegistryDirFromEnv();
-    if (dir == null) {
-        requireEnv("LOG_PERSIST_REGISTRY_DIR");
-    }
-    return defaultLogPersistRegistryPath(resolve(dir ?? ""));
-}

package/src/shared/log/log-persist-coordinator.ts

@@ -1,107 +0,0 @@
-import {
-    disableLogPersist,
-    ensureLogPersistFromEnv,
-    getLogPersistStats,
-    logPersistEnabledFromEnv,
-    snapshotLogPersistReady,
-    waitForLogPersistReady,
-} from "./enable-log-persist";
-import type { LogPersistReadySnapshot, LogPersistStats } from "./log-persist.interface";
-
-export interface LogPersistCoordinatorOptions {
-    /** Service identity written into each registry shard (e.g. `log-service`). */
-    service: string;
-    /** Directory holding one JSON shard per process (`main.json`, `guard.json`, …). */
-    registryFilePath: string;
-    /** Process labels main waits for before accepting traffic (must match `LOG_PERSIST_PROCESS` per child). */
-    expectedProcesses: readonly string[];
-    /** Max wait for {@link LogPersistCoordinator.waitForAllProcessesReady} (default 60_000 ms). */
-    readyTimeoutMs?: number;
-}
-
-/** Service-bound facade over env-driven log-persist registration and readiness gates. */
-export interface LogPersistCoordinator {
-    /** Whether `LOG_PERSIST_ENABLED` is active in this process. */
-    isEnabled(): boolean;
-
-    /** Absolute path to the multi-process registry directory configured at construction. */
-    getRegistryFilePath(): string;
-
-    /**
-     * Enable log-persist for this process and write/update its registry shard.
-     * @param process Optional label; defaults to `LOG_PERSIST_PROCESS` env.
-     */
-    registerProcess(process?: string): Promise<boolean>;
-
-    /** Block until every {@link LogPersistCoordinatorOptions.expectedProcesses} entry is registered and fresh. */
-    waitForAllProcessesReady(): Promise<LogPersistReadySnapshot>;
-
-    /** Immediate readiness snapshot without blocking; `null` when log-persist is disabled. */
-    snapshotProcessesReady(): Promise<LogPersistReadySnapshot | null>;
-
-    /** Flush-queue stats for observability; `null` when log-persist is disabled. */
-    getPersistStats(): LogPersistStats | null;
-
-    /** Flush pending logs and tear down log-persist (call from process shutdown hooks). */
-    shutdownLogPersist(): Promise<void>;
-}
-
-/**
- * Bind service-specific log-persist registry settings (process list, paths, timeouts).
- * Each L3 service exports one instance from `src/startup/log-persist.ts`.
- */
-export function createLogPersistCoordinator(options: LogPersistCoordinatorOptions): LogPersistCoordinator {
-    const { service, registryFilePath, expectedProcesses, readyTimeoutMs } = options;
-
-    return {
-        isEnabled() {
-            return logPersistEnabledFromEnv();
-        },
-
-        getRegistryFilePath() {
-            return registryFilePath;
-        },
-
-        registerProcess(process?: string) {
-            return ensureLogPersistFromEnv({
-                process,
-                service,
-                registryFilePath,
-            });
-        },
-
-        waitForAllProcessesReady() {
-            return waitForLogPersistReady({
-                registryFilePath,
-                service,
-                expectedProcesses: [...expectedProcesses],
-                timeoutMs: readyTimeoutMs,
-            });
-        },
-
-        async snapshotProcessesReady() {
-            if (!logPersistEnabledFromEnv()) {
-                return null;
-            }
-            return snapshotLogPersistReady({
-                registryFilePath,
-                service,
-                expectedProcesses: [...expectedProcesses],
-            });
-        },
-
-        getPersistStats() {
-            if (!logPersistEnabledFromEnv()) {
-                return null;
-            }
-            return getLogPersistStats();
-        },
-
-        async shutdownLogPersist() {
-            if (!logPersistEnabledFromEnv()) {
-                return;
-            }
-            await disableLogPersist();
-        },
-    };
-}

package/src/shared/log/log-persist-errors.ts

@@ -1,16 +0,0 @@
-const PERMANENT_LOG_PERSIST_ERROR_PATTERNS = [
-    /not initialized/i,
-    /call initialize\(\) first/i,
-    /missing required supabase environment/i,
-    /preload env incomplete/i,
-];
-
-export function formatLogPersistError(error: unknown): string {
-    return error instanceof Error ? error.message : String(error);
-}
-
-/** Errors that will not succeed on retry without fixing process configuration. */
-export function isPermanentLogPersistError(error: unknown): boolean {
-    const message = formatLogPersistError(error);
-    return PERMANENT_LOG_PERSIST_ERROR_PATTERNS.some((pattern) => pattern.test(message));
-}

package/src/shared/log/log-persist-logger.ts

@@ -1,61 +0,0 @@
-import { createLogger } from "./create-logger";
-
-/** User-facing / lifecycle logs — may be persisted like normal app logs. */
-export const LOG_PERSIST_TOPIC = "log-persist";
-
-/** Operational logs from the persist pipeline — never re-offered to avoid feedback loops. */
-export const LOG_PERSIST_INTERNAL_TOPIC = "log-persist-internal";
-
-const logger = createLogger({ module: "log-persist" });
-
-let errorLogRateLimitMs = 5_000;
-const lastLoggedAt = new Map<string, number>();
-
-export function configurePersistLoggerRateLimit(ms: number): void {
-    errorLogRateLimitMs = Math.max(0, ms);
-}
-
-export function isLogPersistInternalTopic(topic: string | undefined): boolean {
-    return topic === LOG_PERSIST_INTERNAL_TOPIC;
-}
-
-type PersistLogData = Record<string, unknown>;
-
-function shouldEmit(level: "debug" | "info" | "warn" | "error", message: string): boolean {
-    if (level !== "error" && level !== "warn") {
-        return true;
-    }
-    if (errorLogRateLimitMs <= 0) {
-        return true;
-    }
-
-    const key = `${level}:${message}`;
-    const now = Date.now();
-    const last = lastLoggedAt.get(key);
-    if (last != null && now - last < errorLogRateLimitMs) {
-        return false;
-    }
-    lastLoggedAt.set(key, now);
-    return true;
-}
-
-function write(level: "debug" | "info" | "warn" | "error", message: string, data?: PersistLogData): void {
-    if (!shouldEmit(level, message)) {
-        return;
-    }
-    logger[level](message, {
-        topic: LOG_PERSIST_INTERNAL_TOPIC,
-        ...(data != null ? { data } : {}),
-    });
-}
-
-export const persistLogger = {
-    debug: (message: string, data?: PersistLogData) => write("debug", message, data),
-    info: (message: string, data?: PersistLogData) => write("info", message, data),
-    warn: (message: string, data?: PersistLogData) => write("warn", message, data),
-    error: (message: string, data?: PersistLogData) => write("error", message, data),
-};
-
-export function patchPersistLoggerScope(labels: Record<string, string>): void {
-    logger.resetScope({ labels });
-}

package/src/shared/log/log-persist-registry.ts

@@ -1,252 +0,0 @@
-import { mkdir, readdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
-import { createJsonFileStateStore } from "../../node/fs/json-state-store";
-import type { LogPersistProcessRecord, LogPersistRegistryState } from "./log-persist.interface";
-import { persistLogger } from "./log-persist-logger";
-
-const DEFAULT_REGISTRY: LogPersistRegistryState = {
-    updatedAt: new Date(0).toISOString(),
-    service: "",
-    processes: {},
-};
-
-/** Per-process shard — each process owns one file; no cross-process RMW. */
-interface LogPersistProcessShard extends LogPersistProcessRecord {
-    service: string;
-    updatedAt: string;
-}
-
-const DEFAULT_SHARD: LogPersistProcessShard = {
-    service: "",
-    updatedAt: new Date(0).toISOString(),
-    pid: 0,
-    enabledAt: new Date(0).toISOString(),
-    lastHeartbeatAt: new Date(0).toISOString(),
-};
-
-const legacyStores = new Map<
-    string,
-    ReturnType<typeof createJsonFileStateStore<LogPersistRegistryState, "processes">>
->();
-
-const shardStores = new Map<string, ReturnType<typeof createJsonFileStateStore<LogPersistProcessShard>>>();
-
-function isLegacyRegistryFile(registryPath: string): boolean {
-    return registryPath.endsWith(".json");
-}
-
-function legacyStoreFor(filePath: string) {
-    let store = legacyStores.get(filePath);
-    if (store == null) {
-        store = createJsonFileStateStore<LogPersistRegistryState, "processes">({
-            filePath,
-            defaultState: DEFAULT_REGISTRY,
-            nestedKeys: ["processes"],
-            updatedAtKey: "updatedAt",
-        });
-        legacyStores.set(filePath, store);
-    }
-    return store;
-}
-
-function shardStoreFor(shardFilePath: string) {
-    let store = shardStores.get(shardFilePath);
-    if (store == null) {
-        store = createJsonFileStateStore<LogPersistProcessShard>({
-            filePath: shardFilePath,
-            defaultState: DEFAULT_SHARD,
-            updatedAtKey: "updatedAt",
-        });
-        shardStores.set(shardFilePath, store);
-    }
-    return store;
-}
-
-function shardFilePath(registryDir: string, process: string): string {
-    return join(registryDir, `${process}.json`);
-}
-
-/** Registry root directory — one shard file per process under this path. */
-export function defaultLogPersistRegistryPath(registryDir: string): string {
-    return join(registryDir, "log-persist-registry");
-}
-
-async function readShardedLogPersistRegistry(registryDir: string): Promise<LogPersistRegistryState> {
-    await mkdir(registryDir, { recursive: true });
-
-    let entries: string[];
-    try {
-        entries = await readdir(registryDir);
-    } catch {
-        return { ...DEFAULT_REGISTRY };
-    }
-
-    const processes: Record<string, LogPersistProcessRecord> = {};
-    let service = "";
-    let updatedAt = new Date(0).toISOString();
-
-    for (const name of entries) {
-        if (!name.endsWith(".json")) {
-            continue;
-        }
-
-        const processName = name.slice(0, -".json".length);
-        if (processName === "" || processName.startsWith("_")) {
-            continue;
-        }
-
-        try {
-            const raw = await readFile(join(registryDir, name), "utf8");
-            const shard = JSON.parse(raw) as Partial<LogPersistProcessShard>;
-            if (shard.service != null && shard.service !== "") {
-                service = shard.service;
-            }
-            if (shard.updatedAt != null && shard.updatedAt > updatedAt) {
-                updatedAt = shard.updatedAt;
-            }
-            processes[processName] = {
-                pid: shard.pid ?? 0,
-                enabledAt: shard.enabledAt ?? new Date(0).toISOString(),
-                lastHeartbeatAt: shard.lastHeartbeatAt ?? new Date(0).toISOString(),
-            };
-        } catch {
-            persistLogger.warn("registry shard read skipped — corrupt or missing", {
-                registryDir,
-                shard: name,
-            });
-        }
-    }
-
-    return { updatedAt, service, processes };
-}
-
-export async function registerLogPersistProcess(input: {
-    registryFilePath: string;
-    service: string;
-    process: string;
-}): Promise<void> {
-    const now = new Date().toISOString();
-    const record: LogPersistProcessRecord = {
-        pid: process.pid,
-        enabledAt: now,
-        lastHeartbeatAt: now,
-    };
-
-    if (isLegacyRegistryFile(input.registryFilePath)) {
-        await legacyStoreFor(input.registryFilePath).write({
-            service: input.service,
-            processes: {
-                [input.process]: record,
-            },
-        });
-    } else {
-        await shardStoreFor(shardFilePath(input.registryFilePath, input.process)).write({
-            service: input.service,
-            pid: record.pid,
-            enabledAt: record.enabledAt,
-            lastHeartbeatAt: record.lastHeartbeatAt,
-        });
-    }
-
-    persistLogger.info("registry process registered", {
-        registryFilePath: input.registryFilePath,
-        service: input.service,
-        process: input.process,
-        pid: record.pid,
-    });
-}
-
-export async function heartbeatLogPersistProcess(input: { registryFilePath: string; process: string }): Promise<void> {
-    if (isLegacyRegistryFile(input.registryFilePath)) {
-        const current = await legacyStoreFor(input.registryFilePath).read();
-        const existing = current.processes[input.process];
-        if (existing == null) {
-            persistLogger.warn("registry heartbeat skipped — process not registered", {
-                registryFilePath: input.registryFilePath,
-                process: input.process,
-            });
-            return;
-        }
-
-        await legacyStoreFor(input.registryFilePath).write({
-            processes: {
-                [input.process]: {
-                    ...existing,
-                    lastHeartbeatAt: new Date().toISOString(),
-                },
-            },
-        });
-        return;
-    }
-
-    const store = shardStoreFor(shardFilePath(input.registryFilePath, input.process));
-    const current = await store.read();
-    if (current.pid === 0) {
-        persistLogger.warn("registry heartbeat skipped — process not registered", {
-            registryFilePath: input.registryFilePath,
-            process: input.process,
-        });
-        return;
-    }
-
-    await store.write({
-        lastHeartbeatAt: new Date().toISOString(),
-    });
-}
-
-export async function unregisterLogPersistProcess(input: { registryFilePath: string; process: string }): Promise<void> {
-    if (isLegacyRegistryFile(input.registryFilePath)) {
-        const current = await legacyStoreFor(input.registryFilePath).read();
-        const existing = current.processes[input.process];
-        if (existing == null) {
-            persistLogger.warn("registry unregister skipped — process not found", {
-                registryFilePath: input.registryFilePath,
-                process: input.process,
-            });
-            return;
-        }
-
-        await legacyStoreFor(input.registryFilePath).write({
-            processes: {
-                [input.process]: {
-                    ...existing,
-                    pid: 0,
-                    lastHeartbeatAt: new Date(0).toISOString(),
-                },
-            },
-        });
-
-        persistLogger.info("registry process unregistered", {
-            registryFilePath: input.registryFilePath,
-            process: input.process,
-        });
-        return;
-    }
-
-    const store = shardStoreFor(shardFilePath(input.registryFilePath, input.process));
-    const current = await store.read();
-    if (current.pid === 0) {
-        persistLogger.warn("registry unregister skipped — process not found", {
-            registryFilePath: input.registryFilePath,
-            process: input.process,
-        });
-        return;
-    }
-
-    await store.write({
-        pid: 0,
-        lastHeartbeatAt: new Date(0).toISOString(),
-    });
-
-    persistLogger.info("registry process unregistered", {
-        registryFilePath: input.registryFilePath,
-        process: input.process,
-    });
-}
-
-export async function readLogPersistRegistry(registryFilePath: string): Promise<LogPersistRegistryState> {
-    if (isLegacyRegistryFile(registryFilePath)) {
-        return legacyStoreFor(registryFilePath).read();
-    }
-    return readShardedLogPersistRegistry(registryFilePath);
-}