@apibara/indexer 2.1.0-beta.5 → 2.1.0-beta.51

package/src/indexer.ts

@@ -1,11 +1,13 @@
 import {
   type Client,
   ClientError,
+  type CreateClientOptions,
   type Cursor,
   type DataFinality,
+  type DataProduction,
   type Finalize,
-  type Heartbeat,
   type Invalidate,
+  ServerError,
   Status,
   type StreamConfig,
   type StreamDataOptions,
@@ -28,39 +30,66 @@ import {
   indexerAsyncContext,
   useIndexerContext,
 } from "./context";
-import { tracer } from "./otel";
+import { createIndexerMetrics, createTracer } from "./otel";
 import type { IndexerPlugin } from "./plugins";
+import { useInternalContext } from "./plugins/context";
+import { reloadIfNeeded } from "./utils";
 
 export type UseMiddlewareFunction = (
   fn: MiddlewareFunction<IndexerContext>,
 ) => void;
 
 export interface IndexerHooks<TFilter, TBlock> {
-  "run:before": () => void;
-  "run:after": () => void;
+  "plugins:init": ({ abortSignal }: { abortSignal?: AbortSignal }) => void;
+  "run:before": ({ abortSignal }: { abortSignal?: AbortSignal }) => void;
+  "run:after": ({ abortSignal }: { abortSignal?: AbortSignal }) => void;
   "connect:before": ({
     request,
     options,
   }: {
     request: StreamDataRequest<TFilter>;
     options: StreamDataOptions;
+    abortSignal?: AbortSignal;
   }) => void;
   "connect:after": ({
     request,
-  }: { request: StreamDataRequest<TFilter> }) => void;
+  }: {
+    request: StreamDataRequest<TFilter>;
+    abortSignal?: AbortSignal;
+  }) => void;
   "connect:factory": ({
     request,
     endCursor,
+    abortSignal,
   }: {
     request: StreamDataRequest<TFilter>;
     endCursor?: Cursor;
+    abortSignal?: AbortSignal;
   }) => void;
-  "handler:middleware": ({ use }: { use: UseMiddlewareFunction }) => void;
-  message: ({ message }: { message: StreamDataResponse<TBlock> }) => void;
-  "message:invalidate": ({ message }: { message: Invalidate }) => void;
-  "message:finalize": ({ message }: { message: Finalize }) => void;
-  "message:heartbeat": ({ message }: { message: Heartbeat }) => void;
-  "message:systemMessage": ({ message }: { message: SystemMessage }) => void;
+  "handler:middleware": ({
+    use,
+    abortSignal,
+  }: { use: UseMiddlewareFunction; abortSignal?: AbortSignal }) => void;
+  message: ({
+    message,
+    abortSignal,
+  }: {
+    message: StreamDataResponse<TBlock>;
+    abortSignal?: AbortSignal;
+  }) => void;
+  "message:invalidate": ({
+    message,
+    abortSignal,
+  }: { message: Invalidate; abortSignal?: AbortSignal }) => void;
+  "message:finalize": ({
+    message,
+    abortSignal,
+  }: { message: Finalize; abortSignal?: AbortSignal }) => void;
+  "message:heartbeat": ({ abortSignal }: { abortSignal?: AbortSignal }) => void;
+  "message:systemMessage": ({
+    message,
+    abortSignal,
+  }: { message: SystemMessage; abortSignal?: AbortSignal }) => void;
 }
 
 export type IndexerStartingCursor =
@@ -77,23 +106,25 @@ export type IndexerStartingCursor =
       startingBlock?: never;
     };
 
+export type HandlerArgs<TBlock> = {
+  block: TBlock;
+  cursor?: Cursor | undefined;
+  endCursor?: Cursor | undefined;
+  finality: DataFinality;
+  production: DataProduction;
+  context: IndexerContext;
+  abortSignal?: AbortSignal;
+};
+
 export type IndexerConfig<TFilter, TBlock> = {
   streamUrl: string;
   filter: TFilter;
   finality?: DataFinality;
-  factory?: ({
-    block,
-    context,
-  }: { block: TBlock; context: IndexerContext }) => Promise<{
+  clientOptions?: CreateClientOptions;
+  factory?: (args: HandlerArgs<TBlock>) => Promise<{
     filter?: TFilter;
   }>;
-  transform: (args: {
-    block: TBlock;
-    cursor?: Cursor | undefined;
-    endCursor?: Cursor | undefined;
-    finality: DataFinality;
-    context: IndexerContext;
-  }) => Promise<void>;
+  transform: (args: HandlerArgs<TBlock>) => Promise<void>;
   hooks?: NestedHooks<IndexerHooks<TFilter, TBlock>>;
   plugins?: ReadonlyArray<IndexerPlugin<TFilter, TBlock>>;
   debug?: boolean;
@@ -163,15 +194,19 @@ export async function runWithReconnect<TFilter, TBlock>(
   const retryDelay = options.retryDelay ?? 1_000;
   const maxWait = options.maxWait ?? 30_000;
 
-  const runOptions: RunOptions = {
-    onConnect() {
-      retryCount = 0;
-    },
-  };
-
   while (true) {
+    const abortController = new AbortController();
+
+    const runOptions: RunOptions = {
+      onConnect() {
+        retryCount = 0;
+      },
+      abortSignal: abortController.signal,
+    };
+
     try {
       await run(client, indexer, runOptions);
+      abortController.abort();
       return;
     } catch (error) {
       // Only reconnect on internal/server errors.
@@ -179,13 +214,20 @@ export async function runWithReconnect<TFilter, TBlock>(
 
       retryCount++;
 
-      if (error instanceof ClientError) {
+      abortController.abort();
+
+      if (error instanceof ClientError || error instanceof ServerError) {
+        const isServerError = error instanceof ServerError;
+
         if (error.code === Status.INTERNAL) {
           if (retryCount < maxRetries) {
             consola.error(
-              "Internal server error, reconnecting...",
-              error.message,
+              `Internal ${isServerError ? "server" : "client"} error: ${
+                error.message
+              }`,
             );
+            consola.start("Reconnecting...");
+            console.log();
 
             // Add jitter to the retry delay to avoid all clients retrying at the same time.
             const delay = Math.random() * (retryDelay * 0.2) + retryDelay;
@@ -197,7 +239,6 @@ export async function runWithReconnect<TFilter, TBlock>(
           }
         }
       }
-
       throw error;
     }
   }
@@ -205,6 +246,7 @@ export async function runWithReconnect<TFilter, TBlock>(
 
 export interface RunOptions {
   onConnect?: () => void | Promise<void>;
+  abortSignal?: AbortSignal;
 }
 
 export async function run<TFilter, TBlock>(
@@ -214,9 +256,23 @@ export async function run<TFilter, TBlock>(
 ) {
   await indexerAsyncContext.callAsync({}, async () => {
     const context = useIndexerContext();
-    const middleware = await registerMiddleware(indexer);
 
-    await indexer.hooks.callHook("run:before");
+    if (indexer.options.debug) {
+      context.debug = true;
+    }
+
+    const { abortSignal } = runOptions;
+
+    await indexer.hooks.callHook("plugins:init", { abortSignal });
+
+    const middleware = await registerMiddleware(indexer, abortSignal);
+
+    const indexerMetrics = createIndexerMetrics();
+    const tracer = createTracer();
+
+    await indexer.hooks.callHook("run:before", { abortSignal });
+
+    const { indexerName: indexerId } = useInternalContext();
 
     const isFactoryMode = indexer.options.factory !== undefined;
 
@@ -235,17 +291,21 @@ export async function run<TFilter, TBlock>(
     }
 
     // if factory mode we add a empty filter at the end of the filter array.
-    const request = indexer.streamConfig.Request.make({
+    const request = {
       filter: isFactoryMode
         ? [indexer.options.filter, {} as TFilter]
         : [indexer.options.filter],
       finality: indexer.options.finality,
       startingCursor,
-    });
+    } as StreamDataRequest<TFilter>;
 
     const options: StreamDataOptions = {};
 
-    await indexer.hooks.callHook("connect:before", { request, options });
+    await indexer.hooks.callHook("connect:before", {
+      request,
+      options,
+      abortSignal,
+    });
 
     // store main filter, so later it can be merged
     let mainFilter: TFilter;
@@ -258,7 +318,7 @@ export async function run<TFilter, TBlock>(
       StreamDataResponse<TBlock>
     > = client.streamData(request, options)[Symbol.asyncIterator]();
 
-    await indexer.hooks.callHook("connect:after", { request });
+    await indexer.hooks.callHook("connect:after", { request, abortSignal });
 
     let onConnectCalled = false;
 
@@ -276,23 +336,33 @@ export async function run<TFilter, TBlock>(
         }
       }
 
-      await indexer.hooks.callHook("message", { message });
+      await indexer.hooks.callHook("message", { message, abortSignal });
 
       switch (message._tag) {
         case "data": {
           await tracer.startActiveSpan("message data", async (span) => {
             const blocks = message.data.data;
-            const { cursor, endCursor, finality } = message.data;
+            const { cursor, endCursor, finality, production } = message.data;
 
             context.cursor = cursor;
             context.endCursor = endCursor;
             context.finality = finality;
 
+            // Record current block number being processed
+            indexerMetrics.currentBlockGauge.record(
+              Number(endCursor?.orderKey),
+              {
+                indexer_id: indexerId,
+              },
+            );
+
+            reloadIfNeeded();
+
             await middleware(context, async () => {
               let block: TBlock | null;
 
               // when factory mode
-              if (isFactoryMode) {
+              if (isFactoryMode && finality !== "pending") {
                 assert(indexer.options.factory !== undefined);
 
                 const [factoryBlock, mainBlock] = blocks;
@@ -302,7 +372,12 @@ export async function run<TFilter, TBlock>(
                 if (factoryBlock !== null) {
                   const { filter } = await indexer.options.factory({
                     block: factoryBlock,
+                    cursor,
+                    endCursor,
+                    finality,
+                    production,
                     context,
+                    abortSignal,
                   });
 
                   // write returned data from factory function if filter is not defined
@@ -315,15 +390,16 @@ export async function run<TFilter, TBlock>(
                     );
 
                     // create request with new filters
-                    const request = indexer.streamConfig.Request.make({
+                    const request = {
                       filter: [indexer.options.filter, mainFilter],
                       finality: indexer.options.finality,
                       startingCursor: cursor,
-                    });
+                    } as StreamDataRequest<TFilter>;
 
                     await indexer.hooks.callHook("connect:factory", {
                       request,
                       endCursor,
+                      abortSignal,
                     });
 
                     // create new stream with new request
@@ -353,7 +429,9 @@ export async function run<TFilter, TBlock>(
                     cursor,
                     endCursor,
                     finality,
+                    production,
                     context,
+                    abortSignal,
                   });
 
                   span.end();
@@ -361,9 +439,16 @@ export async function run<TFilter, TBlock>(
               }
             });
 
+            reloadIfNeeded();
+
             span.end();
           });
 
+          // Record processed block metric
+          indexerMetrics.processedBlockCounter.add(1, {
+            indexer_id: indexerId,
+          });
+
           context.cursor = undefined;
           context.endCursor = undefined;
           context.finality = undefined;
@@ -372,21 +457,35 @@ export async function run<TFilter, TBlock>(
         }
         case "invalidate": {
           await tracer.startActiveSpan("message invalidate", async (span) => {
-            await indexer.hooks.callHook("message:invalidate", { message });
+            // Record reorg metric
+            indexerMetrics.reorgCounter.add(1, {
+              indexer_id: indexerId,
+            });
+            await indexer.hooks.callHook("message:invalidate", {
+              message: message.invalidate,
+              abortSignal,
+            });
             span.end();
           });
           break;
         }
         case "finalize": {
           await tracer.startActiveSpan("message finalize", async (span) => {
-            await indexer.hooks.callHook("message:finalize", { message });
+            await indexer.hooks.callHook("message:finalize", {
+              message: message.finalize,
+              abortSignal,
+            });
             span.end();
           });
           break;
         }
         case "heartbeat": {
           await tracer.startActiveSpan("message heartbeat", async (span) => {
-            await indexer.hooks.callHook("message:heartbeat", { message });
+            reloadIfNeeded();
+
+            await indexer.hooks.callHook("message:heartbeat", { abortSignal });
+            reloadIfNeeded();
+
             span.end();
           });
           break;
@@ -409,7 +508,8 @@ export async function run<TFilter, TBlock>(
               }
 
               await indexer.hooks.callHook("message:systemMessage", {
-                message,
+                message: message.systemMessage,
+                abortSignal,
               });
               span.end();
             },
@@ -421,21 +521,22 @@ export async function run<TFilter, TBlock>(
           throw new Error("not implemented");
         }
       }
-
-      await indexer.hooks.callHook("run:after");
     }
+
+    await indexer.hooks.callHook("run:after", { abortSignal });
   });
 }
 
 async function registerMiddleware<TFilter, TBlock>(
   indexer: Indexer<TFilter, TBlock>,
+  abortSignal?: AbortSignal,
 ): Promise<MiddlewareFunction<IndexerContext>> {
   const middleware: MiddlewareFunction<IndexerContext>[] = [];
   const use = (fn: MiddlewareFunction<IndexerContext>) => {
     middleware.push(fn);
   };
 
-  await indexer.hooks.callHook("handler:middleware", { use });
+  await indexer.hooks.callHook("handler:middleware", { use, abortSignal });
 
   const composed = compose(middleware);
 

package/src/internal/testing.ts

@@ -5,58 +5,97 @@ import {
   MockStream,
   type MockStreamResponse,
 } from "@apibara/protocol/testing";
-
 import { useIndexerContext } from "../context";
 import { type IndexerConfig, createIndexer, defineIndexer } from "../indexer";
-import { defineIndexerPlugin } from "../plugins";
+import { defineIndexerPlugin, logger } from "../plugins";
 import { type InternalContext, internalContext } from "./plugins";
 
+export type InvalidateConfig = {
+  invalidateFromIndex: number;
+  invalidateTriggerIndex: number;
+};
+
+export type FinalizeConfig = {
+  finalizeToIndex: number;
+  finalizeTriggerIndex: number;
+};
+
 export type MockMessagesOptions = {
-  invalidate?: {
-    invalidateFromIndex: number;
-    invalidateTriggerIndex: number;
-  };
-  finalize?: {
-    finalizeToIndex: number;
-    finalizeTriggerIndex: number;
-  };
+  invalidate?: InvalidateConfig | InvalidateConfig[];
+  finalize?: FinalizeConfig | FinalizeConfig[];
+  uniqueKey?: boolean;
+  baseBlockNumber?: bigint;
 };
 
 export function generateMockMessages(
   count = 10,
   options?: MockMessagesOptions,
 ): MockStreamResponse[] {
-  const invalidateAt = options?.invalidate;
-  const finalizeAt = options?.finalize;
   const messages: MockStreamResponse[] = [];
+  const baseBlockNumber = options?.baseBlockNumber ?? BigInt(5_000_000);
+
+  const invalidateConfigs = options?.invalidate
+    ? Array.isArray(options.invalidate)
+      ? options.invalidate
+      : [options.invalidate]
+    : [];
+
+  const finalizeConfigs = options?.finalize
+    ? Array.isArray(options.finalize)
+      ? options.finalize
+      : [options.finalize]
+    : [];
 
   for (let i = 0; i < count; i++) {
-    if (invalidateAt && i === invalidateAt.invalidateTriggerIndex) {
+    const currentBlockNumber = baseBlockNumber + BigInt(i);
+    const uniqueKey = uniqueKeyFromOrderKey(currentBlockNumber);
+
+    const invalidateConfig = invalidateConfigs.find(
+      (cfg) => cfg.invalidateTriggerIndex === i,
+    );
+    const finalizeConfig = finalizeConfigs.find(
+      (cfg) => cfg.finalizeTriggerIndex === i,
+    );
+
+    if (invalidateConfig) {
+      const invalidateToBlock =
+        baseBlockNumber + BigInt(invalidateConfig.invalidateFromIndex);
       messages.push({
         _tag: "invalidate",
         invalidate: {
           cursor: {
-            orderKey: BigInt(5_000_000 + invalidateAt.invalidateFromIndex),
+            orderKey: invalidateToBlock,
+            uniqueKey: options?.uniqueKey
+              ? uniqueKeyFromOrderKey(invalidateToBlock)
+              : undefined,
           },
-        },
-      } as Invalidate);
-    } else if (finalizeAt && i === finalizeAt.finalizeTriggerIndex) {
+        } as Invalidate,
+      });
+    } else if (finalizeConfig) {
+      const finalizedToBlock =
+        baseBlockNumber + BigInt(finalizeConfig.finalizeToIndex);
       messages.push({
         _tag: "finalize",
         finalize: {
           cursor: {
-            orderKey: BigInt(5_000_000 + finalizeAt.finalizeToIndex),
+            orderKey: finalizedToBlock,
+            uniqueKey: options?.uniqueKey
+              ? uniqueKeyFromOrderKey(finalizedToBlock)
+              : undefined,
           },
-        },
-      } as Finalize);
+        } as Finalize,
+      });
     } else {
       messages.push({
         _tag: "data",
         data: {
-          cursor: { orderKey: BigInt(5_000_000 + i - 1) },
+          cursor: { orderKey: currentBlockNumber - 1n },
           finality: "accepted",
-          data: [{ data: `${5_000_000 + i}` }],
-          endCursor: { orderKey: BigInt(5_000_000 + i) },
+          data: [{ data: `${baseBlockNumber + BigInt(i)}` }],
+          endCursor: {
+            orderKey: currentBlockNumber,
+            uniqueKey: options?.uniqueKey ? uniqueKey : undefined,
+          },
           production: "backfill",
         },
       });
@@ -66,6 +105,10 @@ export function generateMockMessages(
   return messages;
 }
 
+function uniqueKeyFromOrderKey(orderKey: bigint): `0x${string}` {
+  return `0xff00${orderKey.toString()}`;
+}
+
 type MockIndexerParams = {
   internalContext?: InternalContext;
   override?: Partial<IndexerConfig<MockFilter, MockBlock>>;
@@ -82,6 +125,7 @@ export function getMockIndexer(params?: MockIndexerParams) {
       filter: {},
       async transform() {},
       plugins: [
+        logger(),
         internalContext(
           contextParams ??
             ({

package/src/otel.ts

@@ -1,3 +1,30 @@
-import { trace } from "@opentelemetry/api";
+import { metrics, trace } from "@opentelemetry/api";
 
-export const tracer = trace.getTracer("@apibara/indexer");
+export function createTracer() {
+  return trace.getTracer("@apibara/indexer");
+}
+
+export function createIndexerMetrics() {
+  const meter = metrics.getMeter("@apibara/indexer");
+
+  const currentBlockGauge = meter.createGauge("current_block", {
+    description: "Current block number being processed",
+    unit: "{block}",
+  });
+
+  const processedBlockCounter = meter.createCounter("processed_blocks", {
+    description: "Number of blocks processed",
+    unit: "{blocks}",
+  });
+
+  const reorgCounter = meter.createCounter("reorgs", {
+    description: "Number of reorgs (invalidate messages) received",
+    unit: "{reorgs}",
+  });
+
+  return {
+    currentBlockGauge,
+    processedBlockCounter,
+    reorgCounter,
+  };
+}

package/src/plugins/context.ts

@@ -7,7 +7,7 @@ export function internalContext<TFilter, TBlock, TTxnParams>(
   values: Record<string, unknown>,
 ) {
   return defineIndexerPlugin<TFilter, TBlock>((indexer) => {
-    indexer.hooks.hook("run:before", () => {
+    indexer.hooks.hook("plugins:init", () => {
       try {
         const ctx = useIndexerContext();
         ctx[INTERNAL_CONTEXT_PROPERTY] = {

package/src/plugins/logger.ts

@@ -1,4 +1,9 @@
-import { type ConsolaInstance, type ConsolaReporter, consola } from "consola";
+import {
+  type ConsolaInstance,
+  type ConsolaReporter,
+  LogLevels,
+  consola,
+} from "consola";
 import { useIndexerContext } from "../context";
 import { defineIndexerPlugin } from "./config";
 
@@ -8,7 +13,7 @@ export function logger<TFilter, TBlock, TTxnParams>({
   logger,
 }: { logger?: ConsolaReporter } = {}) {
   return defineIndexerPlugin<TFilter, TBlock>((indexer) => {
-    indexer.hooks.hook("run:before", () => {
+    indexer.hooks.hook("plugins:init", () => {
       const ctx = useIndexerContext();
 
       if (logger) {
@@ -16,6 +21,10 @@ export function logger<TFilter, TBlock, TTxnParams>({
       } else {
         ctx.logger = consola.create({});
       }
+
+      if (ctx.debug) {
+        ctx.logger.level = LogLevels.debug;
+      }
     });
   });
 }