@eclesia/indexer-engine 2.14.5 → 2.16.0

package/dist/indexer/index.d.mts

@@ -1,5 +1,5 @@
 import { IndexerMetrics } from "../metrics/index.mjs";
-import { EcleciaIndexerConfig, EmitFunc, WithHeightAndUUID } from "../types/index.mjs";
+import { EclesiaIndexerConfig, EmitFunc, WithHeightAndUUID } from "../types/index.mjs";
 import { EclesiaEmitter } from "../emitter/index.mjs";
 import { CometClient } from "@cosmjs/tendermint-rpc";
 import * as winston from "winston";
@@ -11,7 +11,7 @@ declare const defaultIndexerConfig: {
   batchSize: number;
   modules: never[];
   getNextHeight: () => number;
-  logLevel: EcleciaIndexerConfig["logLevel"];
+  logLevel: EclesiaIndexerConfig["logLevel"];
   usePolling: boolean;
   pollingInterval: number;
   shouldProcessGenesis: () => boolean;
@@ -28,9 +28,9 @@ declare const defaultIndexerConfig: {
  * Core blockchain indexer that connects to Tendermint RPC and processes blocks
  * Extends EclesiaEmitter to provide event-driven architecture for modules
  */
-declare class EcleciaIndexer extends EclesiaEmitter {
+declare class EclesiaIndexer extends EclesiaEmitter {
   /** Indexer configuration settings */
-  config: EcleciaIndexerConfig;
+  config: EclesiaIndexerConfig;
   /** Fastify HTTP server for health checks */
   private fastify;
   /** Prometheus HTTP server instance */
@@ -63,31 +63,135 @@ declare class EcleciaIndexer extends EclesiaEmitter {
   private subscription;
   /** Timeout handler for block reception */
   private blockTimeout;
+  /** Timer for the next poll in polling mode */
+  private pollTimer;
+  /** Bumped on every (re)start and stop so a polling chain from a previous run exits */
+  private pollGeneration;
+  /** Bumped on every start() so callbacks left over from a previous run cannot trigger recovery in this one */
+  private runGeneration;
+  /**
+   * Rejecters of waits parked in waitForBlockData(). Each entry is removed as soon as its block
+   * arrives, so a healthy run keeps this empty instead of accumulating one entry per block.
+   */
+  private blockWaiters;
+  /** Pending restart timer */
+  private retryTimer;
+  /** Resolves when the indexer has stopped for good: stop() was called, endHeight was reached, or it gave up */
+  private stopped;
+  private resolveStopped;
+  /** Next height the fetcher will request; advances as fetches are enqueued */
+  private nextFetchHeight;
+  /** Whether a fetcher loop is active, and for which run */
+  private fetcherRunning;
+  private fetcherGeneration;
+  private fetcherToken;
+  /** Height of the block whose processing failed most recently, and how many times in a row */
+  private lastFailedHeight;
+  private sameHeightFailures;
   /**
    * Creates a new Eclesia indexer instance
    * @param config - Indexer configuration options
    */
-  constructor(config: EcleciaIndexerConfig);
+  constructor(config: EclesiaIndexerConfig);
   private setStatus;
+  /**
+   * Marks the current run for recovery and wakes the main loop if it is parked waiting for a
+   * block. Callbacks left over from a previous run pass their generation and are ignored.
+   */
+  private requestRecovery;
+  /** Rejects every wait parked in waitForBlockData() */
+  private wakeBlockWaiters;
+  /**
+   * Refuses to index a chain other than the configured one. An RPC pool that mixes networks, or
+   * a wrong URL, would otherwise write a different chain's blocks into the database.
+   */
+  private assertChainId;
+  /** Counts consecutive processing failures per block height */
+  private noteBlockFailure;
+  /** True once one block has failed maxFailuresPerBlock times in a row */
+  private isStuck;
+  /**
+   * Waits for the next dequeued block but wakes early when recovery or stop is requested, so a
+   * loop parked on an empty queue never waits for a block that will not come.
+   */
+  private waitForBlockData;
+  /** (Re)arms the idle check that runs when no block has been announced for a while */
+  private armIdleCheck;
+  /**
+   * Runs when no block has been announced for IDLE_CHECK_INTERVAL_MS. A chain that has stopped
+   * producing blocks (halt, upgrade, slow chain) is not an error: the indexer reports WAITING and
+   * checks again later. Recovery is requested only when the chain has moved on without us, which
+   * means the subscription is dead, or when the RPC cannot be reached at all.
+   */
+  private checkLiveness;
   private blockListener;
   private isMinimal;
   connect(): Promise<boolean>;
+  /**
+   * Opens one CometBFT client with its own timeout. If the timeout wins, the client
+   * that may still arrive is disconnected so a slow RPC never leaks a socket.
+   */
+  private connectWithTimeout;
   private initialize;
-  stop(): void;
+  /**
+   * Stops the indexer and releases everything that would keep the process alive:
+   * the block subscription, polling and inactivity timers, both RPC clients and the
+   * health and metrics servers. Safe to call more than once.
+   */
+  stop(): Promise<void>;
   private clearBlockQueue;
   private setupBlockListening;
+  /**
+   * Resolves once the indexer has stopped for good: stop() was called, endHeight was reached, or
+   * a fatal-error was emitted. Restarts with backoff do not resolve it. Use it to keep a caller
+   * waiting for the whole run rather than for the first loop exit.
+   */
+  whenStopped(): Promise<void>;
   start(): Promise<void>;
+  /**
+   * Emits an event and waits for its handlers. Handlers run one after another in registration
+   * order: they share one database connection and one transaction, so interleaving them at
+   * await points would let two handlers read and write the same rows in an unpredictable order,
+   * and a failure in one would leave the others mid-flight while the block is rolled back. The
+   * first rejection propagates and stops the remaining handlers.
+   */
   asyncEmit: EmitFunc<keyof WithHeightAndUUID<EventMap>>;
   private processBlock;
+  /**
+   * Fetches every height from nextFetchHeight up to latestHeight, waiting for queue space
+   * before each fetch. Serves the initial catch-up and live blocks alike: a new announcement
+   * only moves latestHeight and starts this loop if it is not already running, so bursts and
+   * skipped announcements are handled by the same code and the queue can never overflow.
+   */
   private fetcher;
+  /**
+   * Runs an ABCI query. A transport failure (RPC down, timeout, empty reply) requests a recovery.
+   * A reply with a non-zero code is the chain answering "no" (pruned height, unknown path, bad
+   * key): it is thrown as an RPCError with the code and log, and no recovery is requested for
+   * ad-hoc queries, so modules can catch it. Block-pipeline queries reject into the fetcher,
+   * which requests recovery itself.
+   */
   callABCI(path: string, data: Uint8Array, height?: number, adHoc?: boolean): Promise<Uint8Array>;
+  /**
+   * Fetches the complete validator set at a height, following pagination, and returns it
+   * re-encoded as a single QueryValidatorsResponse so the block queue payload keeps its shape.
+   * Chains with more validators than one page (1000) were silently truncated before.
+   */
+  private fetchValidatorSet;
   private newBlockReceived;
+  /** Starts a single polling chain, retiring any chain left over from a previous run */
+  private startPolling;
+  private stopPolling;
   private pollForBlock;
   private readGenesis;
   private setArrayReader;
   private setValueReader;
   private parseGenesis;
 }
+/** @deprecated Misspelling kept for compatibility, use EclesiaIndexer. Removed in 3.0. */
+declare const EcleciaIndexer: typeof EclesiaIndexer;
+/** @deprecated Misspelling kept for compatibility, use EclesiaIndexer. Removed in 3.0. */
+type EcleciaIndexer = EclesiaIndexer;
 //#endregion
-export { EcleciaIndexer, defaultIndexerConfig };
+export { EcleciaIndexer, EclesiaIndexer, defaultIndexerConfig };
 //# sourceMappingURL=index.d.mts.map

package/dist/indexer/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/indexer/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;cAuEa;EAAA,WAAA,EAAA,MAAA;EAKS,SAAA,EAAA,MAAA;;;EAWa,QAAA,EAXb,oBAWa,CAAA,UAAA,CAAA;EAAA,UAAA,EAAA,OAAA;EAOtB,eAAA,EAAe,MAAA;EAEX,oBAAA,EAAA,GAAA,GAAA,OAAA;EAwBI,OAAA,EAAA,OAAA;EAMH,iBAAA,EAAA,OAAA;EAGK,eAAA,EAAA,MAAA;EAGT,gBAAQ,EAAA,OAAA;EAoBA,cAAA,EAAA,MAAA;EAoLA,IAAA,EAAA,GAAA,UAAA,CAAA,IAAA,CAAA;EA+HF,gBAAA,EAAA,GAAA,UAAA,CAAA,IAAA,CAAA;EAoJiC,cAAA,EAAA,CAAA,OAAA,EAAA,OAAA,EAAA,GAxgBlB,OAwgBkB,CAAA,IAAA,CAAA;CAAlB;;;;;AAjgBC,cAAvB,cAAA,SAAuB,cAAA,CAAA;EAAc;UAEjC;;;;;;;;;;;;;;;;cAwBI;;;;UAMH;;eAGK;;OAGT,OAAA,CAAQ;;;;;;;;;;;;;sBAoBA;;;;aAoLA;;;;;WA+HF;aAoJA,eAAe,kBAAkB;;;+BAoST,+CAAqD,QAAQ"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/indexer/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;cAmEa;EAAA,WAAA,EAAA,MAAA;EAKS,SAAA,EAAA,MAAA;;;EAWa,QAAA,EAXb,oBAWa,CAAA,UAAA,CAAA;EAAA,UAAA,EAAA,OAAA;EAOtB,eAAA,EAAe,MAAA;EAEX,oBAAA,EAAA,GAAA,GAAA,OAAA;EAwBI,OAAA,EAAA,OAAA;EAMH,iBAAA,EAAA,OAAA;EAGK,eAAA,EAAA,MAAA;EAGT,gBAAQ,EAAA,OAAA;EA0DA,cAAA,EAAA,MAAA;EA0VA,IAAA,EAAA,GAAA,UAAA,CAAA,IAAA,CAAA;EAsGC,gBAAA,EAAA,GAAA,UAAA,CAAA,IAAA,CAAA;EAmGC,cAAA,EAAA,CAAA,OAAA,EAAA,OAAA,EAAA,GA1oBW,OA0oBX,CAAA,IAAA,CAAA;CAIJ;;;;;AAifqF,cAxnC5F,cAAA,SAAuB,cAAA,CAwnCqE;EAAR;EAxnC7D,MAAA,EAEnB,oBAFmB;EAAc;EA+7CrC,QAAA,OAAA;EAED;;;;;;;;;;;;;cAv6CS;;;;UAMH;;eAGK;;OAGT,OAAA,CAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBA0DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aA0VA;;;;;;;;;;;;UAsGC;;;;;;;;iBAmGC;WAIJ;;;;;;;;aAkNA,eAAe,kBAAkB;;;;;;;;;;;;;;;;+BA+RT,+CAAqD,QAAQ;;;;;;;;;;;;;;;;;;cAuU5F,uBAAc;;KAEf,cAAA,GAAiB"}