target-supabase-sdk 0.2.10 → 0.2.12

package/src/shared/log/log-min-level.ts

@@ -0,0 +1,46 @@
+import { isDevEnvironment } from "../../core.utils";
+import { LogLevel } from "./log-manager";
+
+/** Env key for global {@link LogManager} min level (console + log-persist when enabled). */
+export const LOG_MIN_LEVEL_ENV_KEY = "LOG_MIN_LEVEL";
+
+const LOG_LEVEL_BY_NAME: Record<string, LogLevel> = {
+    DEBUG: LogLevel.DEBUG,
+    INFO: LogLevel.INFO,
+    SUCCESS: LogLevel.SUCCESS,
+    WARN: LogLevel.WARN,
+    ERROR: LogLevel.ERROR,
+    CRITICAL: LogLevel.CRITICAL,
+};
+
+export interface ResolveLogMinLevelOptions {
+    env?: NodeJS.ProcessEnv;
+    /** When {@link LOG_MIN_LEVEL_ENV_KEY} unset; defaults to LogManager convention (DEBUG in dev, INFO in prod). */
+    defaultLevel?: LogLevel;
+}
+
+function sdkDefaultLogMinLevel(): LogLevel {
+    return isDevEnvironment() ? LogLevel.DEBUG : LogLevel.INFO;
+}
+
+/**
+ * Parse `LOG_MIN_LEVEL` after `.env` load. Invalid values throw (same style as `envInt`).
+ */
+export function resolveLogMinLevel(options?: ResolveLogMinLevelOptions): LogLevel {
+    const env = options?.env ?? process.env;
+    const raw = env[LOG_MIN_LEVEL_ENV_KEY]?.trim().toUpperCase();
+    if (raw == null || raw === "") {
+        return options?.defaultLevel ?? sdkDefaultLogMinLevel();
+    }
+
+    const level = LOG_LEVEL_BY_NAME[raw];
+    if (level == null) {
+        throw new Error(`Invalid ${LOG_MIN_LEVEL_ENV_KEY}: ${raw}`);
+    }
+    return level;
+}
+
+/** Alias for {@link resolveLogMinLevel}. */
+export function logMinLevelFromEnv(options?: ResolveLogMinLevelOptions): LogLevel {
+    return resolveLogMinLevel(options);
+}

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

@@ -0,0 +1,16 @@
+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

@@ -8,13 +8,41 @@ 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 } : {}),

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

@@ -19,6 +19,9 @@ export const DEFAULT_LOG_PERSIST_CONFIG: LogPersistConfig = {
     },
     postTimeoutMs: 30_000,
     shutdownDrainTimeoutMs: 15_000,
+    laneRetryIntervalMs: 5_000,
+    errorLogRateLimitMs: 5_000,
+    circuitBreakerPermanentFailureThreshold: 3,
 };
 
 export function resolveLogPersistConfig(partial?: Partial<LogPersistConfig>): LogPersistConfig {
@@ -29,6 +32,10 @@ export function resolveLogPersistConfig(partial?: Partial<LogPersistConfig>): Lo
         slow: { ...defaults.slow, ...partial?.slow },
         postTimeoutMs: partial?.postTimeoutMs ?? defaults.postTimeoutMs,
         shutdownDrainTimeoutMs: partial?.shutdownDrainTimeoutMs ?? defaults.shutdownDrainTimeoutMs,
+        laneRetryIntervalMs: partial?.laneRetryIntervalMs ?? defaults.laneRetryIntervalMs,
+        errorLogRateLimitMs: partial?.errorLogRateLimitMs ?? defaults.errorLogRateLimitMs,
+        circuitBreakerPermanentFailureThreshold:
+            partial?.circuitBreakerPermanentFailureThreshold ?? defaults.circuitBreakerPermanentFailureThreshold,
     };
 }
 
@@ -91,5 +98,18 @@ export function logPersistConfigFromEnv(env: NodeJS.ProcessEnv = process.env): L
             DEFAULT_LOG_PERSIST_CONFIG.shutdownDrainTimeoutMs,
             { env },
         ),
+        laneRetryIntervalMs: envMs("LOG_PERSIST_LANE_RETRY_MS", DEFAULT_LOG_PERSIST_CONFIG.laneRetryIntervalMs, {
+            env,
+        }),
+        errorLogRateLimitMs: envMs(
+            "LOG_PERSIST_ERROR_LOG_RATE_LIMIT_MS",
+            DEFAULT_LOG_PERSIST_CONFIG.errorLogRateLimitMs,
+            { env },
+        ),
+        circuitBreakerPermanentFailureThreshold: envInt(
+            "LOG_PERSIST_CIRCUIT_BREAKER_THRESHOLD",
+            DEFAULT_LOG_PERSIST_CONFIG.circuitBreakerPermanentFailureThreshold,
+            { env, min: 1 },
+        ),
     });
 }

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

@@ -41,6 +41,12 @@ export interface LogPersistConfig {
     postTimeoutMs: number;
     /** Graceful shutdown drain ceiling */
     shutdownDrainTimeoutMs: number;
+    /** Delay before medium/slow lane flush retries after failure (fast lane uses the same interval). */
+    laneRetryIntervalMs: number;
+    /** Suppress duplicate persistLogger warn/error lines with the same message within this window. */
+    errorLogRateLimitMs: number;
+    /** Disable log-persist after this many consecutive permanent flush errors. */
+    circuitBreakerPermanentFailureThreshold: number;
 }
 
 export interface EnableLogPersistOptions {
@@ -89,6 +95,8 @@ export interface LogPersistQueueBytesStats {
 export interface LogPersistStats {
     enabled: boolean;
     draining: boolean;
+    circuitBreakerTripped: boolean;
+    permanentFailureCount: number;
     service: string | null;
     process: string | null;
     queues: LogPersistQueueStats;

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

@@ -7,12 +7,17 @@ import type {
     LogPersistStats,
 } from "./log-persist.interface";
 import { computeLogBatchIdempotencyKey } from "./log-persist-batch-id";
+import { formatLogPersistError, isPermanentLogPersistError } from "./log-persist-errors";
 import { buildLogListDraft, estimateEntriesBytes, postLogBatch, takeEntriesWithinBytes } from "./log-persist-flush";
 import { registerLogPersistOffer } from "./log-persist-hook";
-import { isLogPersistInternalTopic, patchPersistLoggerScope, persistLogger } from "./log-persist-logger";
+import {
+    configurePersistLoggerRateLimit,
+    isLogPersistInternalTopic,
+    patchPersistLoggerScope,
+    persistLogger,
+} from "./log-persist-logger";
 import { heartbeatLogPersistProcess } from "./log-persist-registry";
 
-const FAST_RETRY_INTERVAL_MS = 5_000;
 const HEARTBEAT_INTERVAL_MS = 30_000;
 
 function routeLane(level: LogLevel): LogPersistLane {
@@ -43,8 +48,12 @@ class LogPersist {
     private mediumDebounceTimer: ReturnType<typeof setTimeout> | null = null;
     private slowQueueStartedAt: number | null = null;
     private fastRetryTimer: ReturnType<typeof setTimeout> | null = null;
+    private mediumRetryTimer: ReturnType<typeof setTimeout> | null = null;
+    private slowRetryTimer: ReturnType<typeof setTimeout> | null = null;
     private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
     private lastHeartbeatAt = 0;
+    private permanentFailureCount = 0;
+    private circuitBreakerTripped = false;
 
     private laneFlushing: Record<LogPersistLane, boolean> = {
         fast: false,
@@ -87,9 +96,12 @@ class LogPersist {
         this.processName = options.process;
         this.registryFilePath = options.registryFilePath ?? null;
         this.config = resolveLogPersistConfig(options.config);
+        configurePersistLoggerRateLimit(this.config.errorLogRateLimitMs);
         this.draining = false;
         this.shutdownPromise = null;
         this.consecutiveFailures = { fast: 0, medium: 0, slow: 0 };
+        this.permanentFailureCount = 0;
+        this.circuitBreakerTripped = false;
         this.lastError = null;
         this.lastErrorAt = null;
         this.enabled = true;
@@ -132,6 +144,7 @@ class LogPersist {
 
         persistLogger.info("log persist core disabling", this.queueSnapshot());
         this.cancelMediumDebounce();
+        this.cancelLaneRetryTimers();
         this.stopHeartbeat();
         await this.shutdown();
         persistLogger.info("log persist core disabled");
@@ -176,6 +189,8 @@ class LogPersist {
         return {
             enabled: this.enabled,
             draining: this.draining,
+            circuitBreakerTripped: this.circuitBreakerTripped,
+            permanentFailureCount: this.permanentFailureCount,
             service: this.service,
             process: this.processName,
             queues: {
@@ -274,6 +289,108 @@ class LogPersist {
     private recordLaneSuccess(lane: LogPersistLane): void {
         this.lastError = null;
         this.consecutiveFailures[lane] = 0;
+        this.permanentFailureCount = 0;
+    }
+
+    private handleLaneFlushFailure(
+        lane: LogPersistLane,
+        error: unknown,
+        scheduleRetry: () => void,
+        logMessage: string,
+        context: Record<string, unknown>,
+    ): void {
+        this.recordLaneError(lane, error);
+        const message = this.lastError ?? formatLogPersistError(error);
+
+        if (isPermanentLogPersistError(error)) {
+            this.permanentFailureCount += 1;
+            if (this.permanentFailureCount >= this.config.circuitBreakerPermanentFailureThreshold) {
+                this.tripCircuitBreaker(message);
+                return;
+            }
+        }
+
+        persistLogger.error(logMessage, {
+            ...context,
+            error: message,
+            retryInMs: this.config.laneRetryIntervalMs,
+            permanentFailureCount: this.permanentFailureCount,
+        });
+        scheduleRetry();
+    }
+
+    private tripCircuitBreaker(reason: string): void {
+        if (this.circuitBreakerTripped) {
+            return;
+        }
+        this.circuitBreakerTripped = true;
+
+        this.cancelMediumDebounce();
+        this.cancelLaneRetryTimers();
+        this.stopHeartbeat();
+
+        const dropped = this.queueSnapshot();
+        this.fastQueue = [];
+        this.fastRetryQueue = [];
+        this.mediumQueue = [];
+        this.slowQueue = [];
+        this.slowQueueStartedAt = null;
+
+        this.enabled = false;
+        registerLogPersistOffer(null);
+
+        persistLogger.error("circuit breaker tripped — log persist disabled", {
+            reason,
+            permanentFailureCount: this.permanentFailureCount,
+            threshold: this.config.circuitBreakerPermanentFailureThreshold,
+            dropped,
+        });
+    }
+
+    private cancelLaneRetryTimers(): void {
+        if (this.fastRetryTimer != null) {
+            clearTimeout(this.fastRetryTimer);
+            this.fastRetryTimer = null;
+        }
+        if (this.mediumRetryTimer != null) {
+            clearTimeout(this.mediumRetryTimer);
+            this.mediumRetryTimer = null;
+        }
+        if (this.slowRetryTimer != null) {
+            clearTimeout(this.slowRetryTimer);
+            this.slowRetryTimer = null;
+        }
+    }
+
+    private scheduleLaneRetry(lane: "fast" | "medium" | "slow", flush: () => void): void {
+        const retryMs = this.config.laneRetryIntervalMs;
+        const existing =
+            lane === "fast" ? this.fastRetryTimer : lane === "medium" ? this.mediumRetryTimer : this.slowRetryTimer;
+        if (existing != null) {
+            return;
+        }
+
+        persistLogger.warn(`${lane} flush retry scheduled`, { retryInMs: retryMs });
+        const timer = setTimeout(() => {
+            if (lane === "fast") {
+                this.fastRetryTimer = null;
+            } else if (lane === "medium") {
+                this.mediumRetryTimer = null;
+            } else {
+                this.slowRetryTimer = null;
+            }
+            persistLogger.debug(`${lane} flush retry timer fired`);
+            flush();
+        }, retryMs);
+        timer.unref?.();
+
+        if (lane === "fast") {
+            this.fastRetryTimer = timer;
+        } else if (lane === "medium") {
+            this.mediumRetryTimer = timer;
+        } else {
+            this.slowRetryTimer = timer;
+        }
     }
 
     private queueSnapshot(): Record<string, unknown> {
@@ -341,6 +458,9 @@ class LogPersist {
     }
 
     private scheduleMediumFlush(): void {
+        if (this.mediumRetryTimer != null) {
+            return;
+        }
         const { debounceMs, maxEntries, maxBytes } = this.config.medium;
         const queueBytes = estimateEntriesBytes(this.mediumQueue);
         if (this.mediumQueue.length >= maxEntries || queueBytes >= maxBytes) {
@@ -380,6 +500,9 @@ class LogPersist {
     }
 
     private scheduleSlowFlush(): void {
+        if (this.slowRetryTimer != null) {
+            return;
+        }
         const { maxEntries, maxBytes, maxAgeMs } = this.config.slow;
         const queueBytes = estimateEntriesBytes(this.slowQueue);
         const ageMs = this.slowQueueStartedAt != null ? Date.now() - this.slowQueueStartedAt : 0;
@@ -518,15 +641,17 @@ class LogPersist {
                         fastRetryRemaining: this.fastRetryQueue.length,
                     });
                 } catch (error) {
-                    this.recordLaneError("fast", error);
                     this.fastRetryQueue.push(entry);
-                    persistLogger.error("fast flush failed — queued for retry", {
-                        idempotencyKey,
-                        error: this.lastError,
-                        retryInMs: FAST_RETRY_INTERVAL_MS,
-                        fastRetryQueue: this.fastRetryQueue.length,
-                    });
-                    this.scheduleFastRetry();
+                    this.handleLaneFlushFailure(
+                        "fast",
+                        error,
+                        () => this.scheduleLaneRetry("fast", () => void this.flushFast()),
+                        "fast flush failed — queued for retry",
+                        {
+                            idempotencyKey,
+                            fastRetryQueue: this.fastRetryQueue.length,
+                        },
+                    );
                     break;
                 }
             }
@@ -535,19 +660,6 @@ class LogPersist {
         }
     }
 
-    private scheduleFastRetry(): void {
-        if (this.fastRetryTimer != null) {
-            return;
-        }
-        persistLogger.warn("fast flush retry scheduled", { retryInMs: FAST_RETRY_INTERVAL_MS });
-        this.fastRetryTimer = setTimeout(() => {
-            this.fastRetryTimer = null;
-            persistLogger.debug("fast flush retry timer fired");
-            void this.flushFast();
-        }, FAST_RETRY_INTERVAL_MS);
-        this.fastRetryTimer.unref?.();
-    }
-
     private async flushMedium(): Promise<void> {
         if (this.laneFlushing.medium) {
             persistLogger.debug("medium flush skipped — already flushing");
@@ -601,15 +713,18 @@ class LogPersist {
                         queueRemaining: this.mediumQueue.length,
                     });
                 } catch (error) {
-                    this.recordLaneError("medium", error);
-                    persistLogger.error("medium flush failed — entries retained", {
-                        idempotencyKey,
-                        batchSize: batch.length,
-                        batchBytes,
-                        error: this.lastError,
-                        queueRemaining: this.mediumQueue.length,
-                    });
-                    this.scheduleMediumFlush();
+                    this.handleLaneFlushFailure(
+                        "medium",
+                        error,
+                        () => this.scheduleLaneRetry("medium", () => void this.flushMedium()),
+                        "medium flush failed — entries retained",
+                        {
+                            idempotencyKey,
+                            batchSize: batch.length,
+                            batchBytes,
+                            queueRemaining: this.mediumQueue.length,
+                        },
+                    );
                     break;
                 }
             }
@@ -617,7 +732,7 @@ class LogPersist {
             this.laneFlushing.medium = false;
         }
 
-        if (this.mediumQueue.length > 0 && !this.laneFlushing.medium) {
+        if (this.mediumQueue.length > 0 && !this.laneFlushing.medium && this.mediumRetryTimer == null) {
             this.scheduleMediumFlush();
         }
     }
@@ -675,15 +790,18 @@ class LogPersist {
                         queueRemaining: this.slowQueue.length,
                     });
                 } catch (error) {
-                    this.recordLaneError("slow", error);
-                    persistLogger.error("slow flush failed — entries retained", {
-                        idempotencyKey,
-                        batchSize: batch.length,
-                        batchBytes,
-                        error: this.lastError,
-                        queueRemaining: this.slowQueue.length,
-                    });
-                    this.scheduleSlowFlush();
+                    this.handleLaneFlushFailure(
+                        "slow",
+                        error,
+                        () => this.scheduleLaneRetry("slow", () => void this.flushSlow()),
+                        "slow flush failed — entries retained",
+                        {
+                            idempotencyKey,
+                            batchSize: batch.length,
+                            batchBytes,
+                            queueRemaining: this.slowQueue.length,
+                        },
+                    );
                     break;
                 }
             }
@@ -695,7 +813,7 @@ class LogPersist {
             this.laneFlushing.slow = false;
         }
 
-        if (this.slowQueue.length > 0 && !this.laneFlushing.slow) {
+        if (this.slowQueue.length > 0 && !this.laneFlushing.slow && this.slowRetryTimer == null) {
             this.scheduleSlowFlush();
         }
     }