@thru/indexer 0.2.32 → 0.2.33

package/dist/index.cjs

@@ -301,6 +301,54 @@ function getSchemaExports(config) {
   return exports;
 }
 
+// src/runtime/logger.ts
+var LEVELS = ["debug", "info", "warn", "error"];
+function shouldLog(level, minimum) {
+  return LEVELS.indexOf(level) >= LEVELS.indexOf(minimum);
+}
+function writeConsole(prefix, level, message, meta) {
+  const text3 = `[${prefix}] ${message}`;
+  if (meta && Object.keys(meta).length > 0) {
+    if (level === "error") {
+      console.error(text3, meta);
+    } else if (level === "warn") {
+      console.warn(text3, meta);
+    } else {
+      console.log(text3, meta);
+    }
+    return;
+  }
+  if (level === "error") {
+    console.error(text3);
+  } else if (level === "warn") {
+    console.warn(text3);
+  } else {
+    console.log(text3);
+  }
+}
+function createScopedLogger(options) {
+  const minimum = options.level ?? "info";
+  const bindings = options.bindings ?? {};
+  const log = (level, message, meta) => {
+    if (!shouldLog(level, minimum)) {
+      return;
+    }
+    const hasMeta = meta !== void 0 && Object.keys(meta).length > 0;
+    const fields = { ...bindings, ...meta ?? {} };
+    if (options.logger) {
+      options.logger[level](message, fields);
+    } else {
+      writeConsole(options.prefix, level, message, hasMeta ? fields : void 0);
+    }
+  };
+  return {
+    debug: (message, meta) => log("debug", message, meta),
+    info: (message, meta) => log("info", message, meta),
+    warn: (message, meta) => log("warn", message, meta),
+    error: (message, meta) => log("error", message, meta)
+  };
+}
+
 // src/streams/processor.ts
 var StreamBatcher = class {
   currentSlot = null;
@@ -360,14 +408,21 @@ async function runEventStreamProcessor(stream, options, abortSignal) {
     safetyMargin = 64,
     pageSize = 512,
     logLevel = "info",
+    logger: baseLogger,
     validateParse = false,
     observer
   } = options;
-  const log = (level, msg) => {
-    if (logLevel === "debug" || level !== "debug") {
-      console.log(`[${stream.name}] ${msg}`);
+  const logger = createScopedLogger({
+    logger: baseLogger,
+    level: logLevel,
+    prefix: stream.name,
+    bindings: {
+      component: "indexer-stream",
+      stream: stream.name,
+      kind: "event"
     }
-  };
+  });
+  const log = (level, msg, meta) => logger[level](msg, meta);
   log("info", `Starting stream processor: ${stream.description}`);
   const checkpoint = await getCheckpoint(db, stream.name);
   const startSlot = checkpoint ? checkpoint.slot : defaultStartSlot;
@@ -379,13 +434,6 @@ async function runEventStreamProcessor(stream, options, abortSignal) {
     "info",
     `Starting from slot ${startSlot}${checkpoint ? " (resuming)" : " (fresh start)"}`
   );
-  const logger = logLevel === "debug" ? replay.createConsoleLogger(stream.name) : {
-    debug: () => {
-    },
-    info: (msg) => log("info", msg),
-    warn: (msg) => log("warn", msg),
-    error: (msg) => log("error", msg)
-  };
   const replay$1 = replay.createEventReplay({
     clientFactory,
     startSlot,
@@ -394,7 +442,8 @@ async function runEventStreamProcessor(stream, options, abortSignal) {
     pageSize,
     filter: stream.getFilter(),
     logger,
-    resubscribeOnEnd: true
+    resubscribeOnEnd: true,
+    signal: abortSignal
   });
   const batcher = new StreamBatcher();
   const stats = {
@@ -612,20 +661,21 @@ function defineAccountStream(definition) {
     api: definition.api
   };
 }
-function shouldLog(level, minLevel) {
-  const levels = ["debug", "info", "warn", "error"];
-  return levels.indexOf(level) >= levels.indexOf(minLevel);
-}
 async function runAccountStreamProcessor(stream, options, abortSignal) {
-  const { clientFactory, db, logLevel = "info", validateParse = false, observer } = options;
+  const { clientFactory, db, logLevel = "info", logger: baseLogger, validateParse = false, observer } = options;
   const checkpointName = `account:${stream.name}`;
-  const log = (level, msg, meta) => {
-    if (shouldLog(level, logLevel)) {
-      {
-        console.log(`[account-stream:${stream.name}] ${msg}`);
-      }
+  const logger = createScopedLogger({
+    logger: baseLogger,
+    level: logLevel,
+    prefix: `account-stream:${stream.name}`,
+    bindings: {
+      component: "indexer-stream",
+      stream: stream.name,
+      kind: "account",
+      checkpoint_name: checkpointName
     }
-  };
+  });
+  const log = (level, msg, meta) => logger[level](msg, meta);
   const stats = {
     accountsProcessed: 0,
     accountsUpdated: 0,
@@ -644,18 +694,6 @@ async function runAccountStreamProcessor(stream, options, abortSignal) {
   if (stream.expectedSize) {
     log("info", `Expected data size: ${stream.expectedSize} bytes`);
   }
-  const replayLogger = logLevel === "debug" ? {
-    debug: (msg) => log("debug", msg),
-    info: (msg) => log("info", msg),
-    warn: (msg) => log("warn", msg),
-    error: (msg) => log("error", msg)
-  } : {
-    debug: () => {
-    },
-    info: (msg) => log("info", msg),
-    warn: (msg) => log("warn", msg),
-    error: (msg) => log("error", msg)
-  };
   let lastProcessedSlot = minUpdatedSlot ?? 0n;
   try {
     const replay$1 = replay.createAccountsByOwnerReplay({
@@ -664,7 +702,8 @@ async function runAccountStreamProcessor(stream, options, abortSignal) {
       view: replay.AccountView.FULL,
       dataSizes: stream.dataSizes ?? (stream.expectedSize ? [stream.expectedSize] : void 0),
       minUpdatedSlot,
-      logger: replayLogger,
+      logger,
+      signal: abortSignal,
       onBackfillComplete: (highestSlot) => {
         log(
           "info",
@@ -870,11 +909,13 @@ function isRetryablePhase(phase) {
 // src/runtime/indexer.ts
 var Indexer = class {
   config;
+  logger;
   abortController = null;
   running = false;
   shutdownRequested = false;
   startedAtMs = null;
   streamStatuses = /* @__PURE__ */ new Map();
+  streamHealthStates = /* @__PURE__ */ new Map();
   constructor(config) {
     this.config = {
       defaultStartSlot: 0n,
@@ -886,6 +927,12 @@ var Indexer = class {
       streamStaleMs: 3e5,
       ...config
     };
+    this.logger = createScopedLogger({
+      logger: this.config.logger,
+      level: this.config.logLevel,
+      prefix: "indexer",
+      bindings: { component: "indexer-runtime" }
+    });
     this.initializeStreamStatuses();
   }
   /**
@@ -900,14 +947,14 @@ var Indexer = class {
     } catch (err) {
       const message = err instanceof Error ? err.cause instanceof Error ? err.cause.message : err.message : String(err);
       if (message.includes("does not exist") || message.includes("relation")) {
-        console.warn(
-          `[indexer] WARNING: Checkpoint table "indexer_checkpoints" not found.
-[indexer] Make sure to export checkpointTable from your Drizzle schema:
+        this.logger.warn(
+          `Checkpoint table "indexer_checkpoints" not found.
+Make sure to export checkpointTable from your Drizzle schema:
 
   // db/schema.ts
   export { checkpointTable } from "@thru/indexer";
 
-[indexer] Then run: pnpm drizzle-kit push (or generate + migrate)
+Then run: pnpm drizzle-kit push (or generate + migrate)
 `
         );
       }
@@ -944,15 +991,14 @@ var Indexer = class {
       validateParse,
       endpointLabel,
       supervisorInitialBackoffMs = 1e3,
-      supervisorMaxBackoffMs = 3e4
+      supervisorMaxBackoffMs = 3e4,
+      logger
     } = this.config;
-    console.log("[indexer] Starting indexer...");
-    console.log(
-      `[indexer] Running ${eventStreams.length} event stream(s): ${eventStreams.map((s) => s.name).join(", ") || "none"}`
-    );
-    console.log(
-      `[indexer] Running ${accountStreams.length} account stream(s): ${accountStreams.map((s) => s.name).join(", ") || "none"}`
-    );
+    this.logger.info("Starting indexer", {
+      event: "indexer.started",
+      event_streams: eventStreams.map((stream) => stream.name),
+      account_streams: accountStreams.map((stream) => stream.name)
+    });
     try {
       const supervisorOptions = {
         endpointLabel,
@@ -967,6 +1013,7 @@ var Indexer = class {
           safetyMargin,
           pageSize,
           logLevel,
+          logger,
           validateParse
         }, supervisorOptions)
       );
@@ -975,6 +1022,7 @@ var Indexer = class {
           clientFactory,
           db,
           logLevel,
+          logger,
           validateParse
         }, supervisorOptions)
       );
@@ -983,7 +1031,9 @@ var Indexer = class {
         eventStreams: eventStreams.map((stream) => this.resultForStream(stream.name)),
         accountStreams: accountStreams.map((stream) => this.resultForStream(stream.name))
       };
-      console.log("[indexer] All streams stopped.");
+      this.logger.info("All indexer streams stopped", {
+        event: "indexer.stopped"
+      });
       return result;
     } finally {
       this.running = false;
@@ -999,14 +1049,20 @@ var Indexer = class {
    */
   stop() {
     if (!this.running || !this.abortController) {
-      console.log("[indexer] Not running");
+      this.logger.info("Indexer is not running", {
+        event: "indexer.stop.noop"
+      });
       return;
     }
     if (this.shutdownRequested) {
-      console.log("[indexer] Force shutdown...");
+      this.logger.warn("Force shutting down indexer", {
+        event: "indexer.force_shutdown"
+      });
       process.exit(1);
     }
-    console.log("[indexer] Shutdown requested, finishing current batches...");
+    this.logger.info("Indexer shutdown requested", {
+      event: "indexer.shutdown_requested"
+    });
     this.shutdownRequested = true;
     this.abortController.abort();
   }
@@ -1027,6 +1083,7 @@ var Indexer = class {
       return stream;
     });
     const healthy = this.running && !this.shutdownRequested && streams.length > 0 && streams.every((stream) => stream.state === "running" && !stream.stale);
+    this.emitHealthTransitions(streams, now);
     return {
       running: this.running,
       shutdownRequested: this.shutdownRequested,
@@ -1038,6 +1095,7 @@ var Indexer = class {
   }
   initializeStreamStatuses() {
     this.streamStatuses = /* @__PURE__ */ new Map();
+    this.streamHealthStates = /* @__PURE__ */ new Map();
     for (const stream of this.config.eventStreams ?? []) {
       this.streamStatuses.set(this.statusKey("event", stream.name), this.createInitialStreamStatus("event", stream.name));
     }
@@ -1079,6 +1137,84 @@ var Indexer = class {
       status: "fulfilled"
     };
   }
+  setStreamState(status, nextState, meta = {}) {
+    const previousState = status.state;
+    status.state = nextState;
+    if (previousState === nextState) {
+      return;
+    }
+    this.logger.info("Indexer stream state changed", {
+      event: "indexer.stream.state_changed",
+      stream: status.name,
+      kind: status.kind,
+      previous_state: previousState,
+      next_state: nextState,
+      restart_count: status.restartCount,
+      ...meta
+    });
+  }
+  streamLogFields(stream) {
+    return {
+      stream: stream.name,
+      kind: stream.kind,
+      state: stream.state,
+      stale: stream.stale,
+      checkpoint_slot: stream.checkpointSlot,
+      last_processed_slot: stream.lastProcessedSlot,
+      last_event_at: stream.lastEventAt,
+      restart_count: stream.restartCount,
+      last_error_at: stream.lastErrorAt,
+      last_error: stream.lastError
+    };
+  }
+  emitHealthTransitions(streams, nowMs) {
+    if (!this.running || this.shutdownRequested) {
+      return;
+    }
+    for (const stream of streams) {
+      const key = this.statusKey(stream.kind, stream.name);
+      const unhealthy = stream.state !== "running" || stream.stale;
+      const previous = this.streamHealthStates.get(key);
+      const initialStarting = !previous && stream.state === "starting" && stream.restartCount === 0 && !stream.lastError;
+      if (initialStarting) {
+        this.streamHealthStates.set(key, {
+          unhealthy: false,
+          unhealthySinceMs: null
+        });
+        continue;
+      }
+      if (unhealthy && previous?.unhealthy !== true) {
+        this.streamHealthStates.set(key, {
+          unhealthy: true,
+          unhealthySinceMs: nowMs
+        });
+        this.logger.warn("Indexer stream unhealthy", {
+          event: "indexer.stream.unhealthy",
+          reason: stream.stale ? "stale" : "state",
+          ...this.streamLogFields(stream)
+        });
+        continue;
+      }
+      if (!unhealthy && previous?.unhealthy === true) {
+        this.streamHealthStates.set(key, {
+          unhealthy: false,
+          unhealthySinceMs: null
+        });
+        this.logger.info("Indexer stream recovered", {
+          event: "indexer.stream.recovered",
+          unhealthy_duration_ms: previous.unhealthySinceMs === null ? null : nowMs - previous.unhealthySinceMs,
+          ...this.streamLogFields(stream)
+        });
+        continue;
+      }
+      if (!previous) {
+        this.streamHealthStates.set(key, {
+          unhealthy,
+          unhealthySinceMs: unhealthy ? nowMs : null
+        });
+      }
+    }
+  }
   createObserver(kind, name, endpointLabel) {
     const status = this.statusFor(kind, name);
     let startSlot = null;
@@ -1087,7 +1223,10 @@ var Indexer = class {
       onStart: (info) => {
         startSlot = info.startSlot ?? null;
         checkpointSlot = info.checkpointSlot ?? null;
-        status.state = "running";
+        this.setStreamState(status, "running", {
+          start_slot: startSlot?.toString(),
+          checkpoint_slot: checkpointSlot?.toString() ?? null
+        });
         status.checkpointSlot = checkpointSlot === null ? null : checkpointSlot.toString();
         status.lastStartedAt = (/* @__PURE__ */ new Date()).toISOString();
       },
@@ -1159,23 +1298,26 @@ var Indexer = class {
     const status = this.statusFor(kind, name);
     while (!this.abortController?.signal.aborted) {
       const observer = this.createObserver(kind, name, options.endpointLabel);
-      status.state = attempt === 0 ? "starting" : "retrying";
+      this.setStreamState(status, attempt === 0 ? "starting" : "retrying", {
+        attempt
+      });
       status.lastStartedAt = (/* @__PURE__ */ new Date()).toISOString();
       try {
         const summary = await runOnce(observer);
         if (this.abortController?.signal.aborted) {
-          status.state = "stopped";
-          console.log(`[indexer] ${kind} stream "${name}" stopped: ${summary}`);
+          this.setStreamState(status, "stopped", { summary });
           return;
         }
         throw new Error(`${kind} stream "${name}" completed unexpectedly: ${summary}`);
       } catch (error) {
         if (this.abortController?.signal.aborted) {
-          status.state = "stopped";
+          this.setStreamState(status, "stopped");
           return;
         }
         status.restartCount++;
-        status.state = "retrying";
+        this.setStreamState(status, "retrying", {
+          restart_count: status.restartCount
+        });
         status.lastErrorAt = (/* @__PURE__ */ new Date()).toISOString();
         if (!status.lastError || status.lastError.phase === "supervisor") {
           status.lastError = normalizeIndexerError({
@@ -1187,15 +1329,21 @@ var Indexer = class {
           });
         }
         const backoffMs = this.supervisorBackoffMs(attempt, options.initialBackoffMs, options.maxBackoffMs);
-        console.error(
-          `[indexer] ${kind} stream "${name}" failed; restarting in ${backoffMs}ms:`,
-          error
-        );
+        this.logger.warn("Indexer stream supervisor restarting", {
+          event: "indexer.stream.supervisor_restart",
+          stream: name,
+          kind,
+          backoff_ms: backoffMs,
+          attempt: attempt + 1,
+          restart_count: status.restartCount,
+          error,
+          last_error: status.lastError
+        });
         attempt++;
         await this.delay(backoffMs, this.abortController.signal);
       }
     }
-    status.state = "stopped";
+    this.setStreamState(status, "stopped");
   }
   supervisorBackoffMs(attempt, initialMs, maxMs) {
     const base = Math.min(maxMs, initialMs * Math.pow(2, attempt));