@secondlayer/subgraphs 3.26.0 → 3.26.2

package/dist/src/runtime/catchup.d.ts

@@ -348,6 +348,39 @@ interface SubgraphDefinition {
 /** Run `fn` (a single block's write, or a reorg's whole rewind) holding the
 *  per-subgraph block lock. Exported for reorg.ts. */
 declare function withSubgraphBlockLock<T>(name: string, fn: () => Promise<T>): Promise<T>;
+/**
+* Cross-process half of the block lock: a transaction-scoped Postgres advisory
+* lock keyed `subgraph-block:<name>`, held for the duration of `fn`.
+*
+* Held, not merely acquired: each block's own write transaction is opened
+* INSIDE `processBlock` (block-processor.ts — `targetDb.transaction()` for
+* managed subgraphs, `route.dataDb.transaction()` for BYO), and that boundary
+* is load-bearing for the f069 replay guard, so the lock cannot be taken on
+* the writing connection. Instead this wraps the write in a separate
+* lock-holding transaction on the target DB, exactly as the reorg lock does
+* (reorg.ts): `pg_advisory_xact_lock` releases only when THIS transaction
+* commits, regardless of which other connections `fn` awaits meanwhile.
+* Transaction-scoped rather than session-scoped so a crashed walk can never
+* strand the lock.
+*
+* The lock lives on the target DB even for BYO subgraphs — same as the reorg
+* lock — because it coordinates control-plane walkers, not data-plane rows.
+*
+* Connection budget: this holds one pooled target-DB connection while `fn`
+* takes another for the write, so an in-flight block costs 2 of
+* `DATABASE_POOL_MAX` (default 20). Concurrent block writes are bounded by
+* catch-up fan-out (5 subgraphs) plus operation concurrency (1) = 6 blocks =
+* 12 connections. Raising either concurrency knob must be checked against the
+* pool, or the wrapping transactions can starve the writes they wrap.
+*/
+declare function withSubgraphBlockAdvisoryLock<T>(name: string, fn: () => Promise<T>): Promise<T>;
+/**
+* One block's write, holding BOTH halves of the block lock in the documented
+* order: the in-process mutex, then the cross-process advisory lock. Every
+* walk that writes a subgraph's schema — live catch-up, reindex, backfill —
+* must go through this, or it serializes against nothing.
+*/
+declare function withSubgraphBlockWriteLock<T>(name: string, fn: () => Promise<T>): Promise<T>;
 /** Bump a subgraph's reorg epoch. Call BEFORE acquiring the block lock so the
 *  bump is visible to any concurrent catch-up immediately. Exported for
 *  reorg.ts. */
@@ -371,4 +404,4 @@ declare function resolveCatchupBatchConfig(env?: CatchupBatchEnv): CatchupBatchC
 * plan-aware pipeline prefetching.
 */
 declare function catchUpSubgraph(subgraph: SubgraphDefinition, subgraphName: string): Promise<number>;
-export { withSubgraphBlockLock, resolveCatchupBatchConfig, catchUpSubgraph, bumpReorgEpoch };
+export { withSubgraphBlockWriteLock, withSubgraphBlockLock, withSubgraphBlockAdvisoryLock, resolveCatchupBatchConfig, catchUpSubgraph, bumpReorgEpoch };

package/dist/src/runtime/catchup.js

@@ -605,14 +605,10 @@ class SubgraphContext {
     this.ops.length = 0;
     const statements = this.buildStatements(opsToFlush);
     if ("isTransaction" in this.db) {
-      for (const stmt of statements) {
-        await sql.raw(stmt).execute(this.db);
-      }
+      await this.execStatements(this.db, statements);
     } else {
       await this.db.transaction().execute(async (tx) => {
-        for (const stmt of statements) {
-          await sql.raw(stmt).execute(tx);
-        }
+        await this.execStatements(tx, statements);
       });
     }
     const writes = opsToFlush.map((op, rowIndex) => {
@@ -631,6 +627,25 @@ class SubgraphContext {
     });
     return { count: opsToFlush.length, writes };
   }
+  async execStatements(executor, statements) {
+    const affected = (r) => r.numAffectedRows ?? 0n;
+    for (const stmt of statements) {
+      if (typeof stmt === "string") {
+        await sql.raw(stmt).execute(executor);
+        continue;
+      }
+      const updated = await sql.raw(stmt.update).execute(executor);
+      if (affected(updated) > 0n)
+        continue;
+      const inserted = await sql.raw(stmt.insert).execute(executor);
+      if (affected(inserted) > 0n)
+        continue;
+      const retried = await sql.raw(stmt.update).execute(executor);
+      if (affected(retried) === 0n) {
+        throw new Error(`increment could not be applied to ${this.pgSchemaName}.${stmt.table} where ${stmt.keyPred}: row neither updated nor inserted`);
+      }
+    }
+  }
   prepareInsert(op) {
     const upsertKeys = op.data._upsert_keys;
     const data = { ...op.data };
@@ -710,7 +725,6 @@ class SubgraphContext {
       for (const r of batch.rows.values()) {
         const keyPred = batch.keyCols.map((k) => `"${k}" = ${escapeLiteral(r.keys[k])}`).join(" AND ");
         const updSet = batch.deltaCols.map((c) => `"${c}" = COALESCE("${c}", 0) + (${String(r.deltas[c] ?? 0n)})`).join(", ");
-        statements.push(`UPDATE ${qualifiedTable} SET ${updSet} WHERE ${keyPred}`);
         const insertVals = [
           ...batch.keyCols.map((k) => escapeLiteral(r.keys[k])),
           ...batch.deltaCols.map((c) => String(r.deltas[c] ?? 0n)),
@@ -718,7 +732,13 @@ class SubgraphContext {
           escapeLiteral(r.meta.txId),
           "NOW()"
         ];
-        statements.push(`INSERT INTO ${qualifiedTable} (${cols.map((c) => `"${c}"`).join(", ")}) ` + `SELECT ${insertVals.join(", ")} ` + `WHERE NOT EXISTS (SELECT 1 FROM ${qualifiedTable} WHERE ${keyPred})`);
+        statements.push({
+          kind: "increment",
+          table: batch.table,
+          keyPred,
+          update: `UPDATE ${qualifiedTable} SET ${updSet} WHERE ${keyPred}`,
+          insert: `INSERT INTO ${qualifiedTable} (${cols.map((c) => `"${c}"`).join(", ")}) ` + `SELECT ${insertVals.join(", ")} ` + `WHERE NOT EXISTS (SELECT 1 FROM ${qualifiedTable} WHERE ${keyPred})`
+        });
       }
       incBatch = null;
       incBatchKey = "";
@@ -3025,7 +3045,7 @@ class StatsAccumulator {
 }
 
 // src/runtime/catchup.ts
-import { getTargetDb as getTargetDb2 } from "@secondlayer/shared/db";
+import { getTargetDb as getTargetDb2, sql as sql4 } from "@secondlayer/shared/db";
 import { getSubgraph } from "@secondlayer/shared/db/queries/subgraphs";
 import { logger as logger8 } from "@secondlayer/shared/logger";
 
@@ -3096,6 +3116,15 @@ async function withSubgraphBlockLock(name, fn) {
     release();
   }
 }
+async function withSubgraphBlockAdvisoryLock(name, fn) {
+  return getTargetDb2().transaction().execute(async (lockTx) => {
+    await sql4`SELECT pg_advisory_xact_lock(hashtext(${`subgraph-block:${name}`}))`.execute(lockTx);
+    return fn();
+  });
+}
+async function withSubgraphBlockWriteLock(name, fn) {
+  return withSubgraphBlockLock(name, () => withSubgraphBlockAdvisoryLock(name, fn));
+}
 function bumpReorgEpoch(name) {
   reorgEpoch.set(name, (reorgEpoch.get(name) ?? 0) + 1);
 }
@@ -3224,7 +3253,7 @@ async function catchUpSubgraph(subgraph, subgraphName) {
         const preloaded = blockData;
         let result;
         try {
-          result = await withSubgraphBlockLock(subgraphName, async () => {
+          result = await withSubgraphBlockWriteLock(subgraphName, async () => {
             if (getReorgEpoch(subgraphName) !== walkEpoch) {
               throw new ReorgEpochChangedError(subgraphName);
             }
@@ -3284,11 +3313,13 @@ async function catchUpSubgraph(subgraph, subgraphName) {
   }
 }
 export {
+  withSubgraphBlockWriteLock,
   withSubgraphBlockLock,
+  withSubgraphBlockAdvisoryLock,
   resolveCatchupBatchConfig,
   catchUpSubgraph,
   bumpReorgEpoch
 };
 
-//# debugId=8CB91249FBEDCD6B64756E2164756E21
+//# debugId=376967D5C07D633664756E2164756E21
 //# sourceMappingURL=catchup.js.map