@mnemonik/shared 7.148.0 → 7.149.0

package/dist/hookTimeouts.d.ts

@@ -93,4 +93,66 @@ export declare function withHookTimeout(ms: number): {
     signal: AbortSignal;
     cleanup: () => void;
 };
+/**
+ * One second attempt on the main hook call (POST /api/v1/hooks/injections).
+ *
+ * Why it exists: on 24 October 2026 about a third of one machine's hook calls
+ * were lost for 50 minutes to a stall between Cloudflare and one load-balancer
+ * node. The server had accepted those requests and was waiting for a body that
+ * never finished arriving. A second request opens a new connection and
+ * normally lands on a healthy path. The call is idempotent by design (the
+ * injection bus dedups on the server), so repeating it is safe.
+ *
+ * Shape: the whole call, both attempts included, still ends inside `budgetMs`,
+ * so the budget every hook event is checked against (tests/HookEventBudgets
+ * .test.ts) and the host's kill limit do not move. The first attempt gets
+ * HOOK_FIRST_ATTEMPT_SHARE of the budget; the second gets whatever is left.
+ * A first attempt that fails fast leaves the second nearly the whole budget.
+ *
+ * What is retried: a timeout, a connection error, and the gateway statuses
+ * that mean the request never reached the application (408, 502, 503, 504 and
+ * Cloudflare's 52x). Nothing else is: a 4xx or a 500 repeats exactly, and a
+ * response that arrives is final.
+ *
+ * Nothing is queued or stored on the client. A call that fails twice is dropped,
+ * as before. The server keeps an answer for 15 s so the second attempt can have
+ * it when the first attempt gave up on an answer that was already decided.
+ */
+export declare const HOOK_FIRST_ATTEMPT_SHARE = 0.65;
+/** Below this much budget left, a second attempt cannot complete a round trip. */
+export declare const HOOK_SECOND_ATTEMPT_MIN_MS = 300;
+/** Sent on every attempt so the server can count how many calls needed a second one. */
+export declare const HOOK_ATTEMPT_HEADER = "x-mnemonik-hook-attempt";
+/**
+ * Sent on both attempts with the same value. The server keeps the first
+ * attempt's answer for a few seconds under this id and hands it to the second
+ * attempt, so an answer decided after the first attempt gave up is delivered
+ * rather than lost, and nothing is counted twice (src/server/hookReplay.ts).
+ */
+export declare const HOOK_REQUEST_ID_HEADER = "x-mnemonik-hook-request-id";
+/**
+ * Sent on every attempt: how many milliseconds this attempt may still take.
+ * The server never waits for a first attempt's answer longer than this less a
+ * margin for the return trip, so it does not hold a request for a client that
+ * has already given up.
+ */
+export declare const HOOK_BUDGET_HEADER = "x-mnemonik-hook-budget-ms";
+/** Statuses that mean the request did not reach, or was not served by, the application. */
+export declare function isRetryableHookStatus(status: number): boolean;
+/** Timeouts and connection failures. A parse error or a bug in the caller is not transient. */
+export declare function isTransientHookFetchError(error: unknown): boolean;
+export type HookAttemptResult<T> = {
+    done: true;
+    value: T;
+} | {
+    done: false;
+};
+/**
+ * Run `attempt` and, when it ends in a transient failure, run it once more
+ * inside the rest of `budgetMs`. Returns the value of the attempt that
+ * finished, or null when neither did. `attempt` returns `{ done: false }` for
+ * a retryable response and throws for a transport failure; anything else it
+ * returns is final.
+ */
+export declare function withSecondAttempt<T>(budgetMs: number, attempt: (signal: AbortSignal, attemptNumber: 1 | 2, requestId: string, budgetMs: number) => Promise<HookAttemptResult<T>>, clock?: () => number): Promise<T | null>;
 //# sourceMappingURL=hookTimeouts.d.ts.map

package/dist/hookTimeouts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hookTimeouts.d.ts","sourceRoot":"","sources":["../src/hookTimeouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,2EAA2E;AAC3E,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,2FAA2F;AAC3F,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;aAC/B,WAAW,EAAE,IAAI;aACjB,OAAO,EAAE,IAAI;aACb,KAAK,EAAE,IAAI;aACX,IAAI,EAAE,IAAI;aACV,MAAM,EAAE,KAAM;CACN,CAAC;AACX,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,oBAAoB,CAAC;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAErD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAIxF"}
+{"version":3,"file":"hookTimeouts.d.ts","sourceRoot":"","sources":["../src/hookTimeouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,2EAA2E;AAC3E,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,2FAA2F;AAC3F,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;aAC/B,WAAW,EAAE,IAAI;aACjB,OAAO,EAAE,IAAI;aACb,KAAK,EAAE,IAAI;aACX,IAAI,EAAE,IAAI;aACV,MAAM,EAAE,KAAM;CACN,CAAC;AACX,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,oBAAoB,CAAC;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAErD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAIxF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,kFAAkF;AAClF,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,4BAA4B,CAAC;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,+BAA+B,CAAC;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAE9D,2FAA2F;AAC3F,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAS7D;AAED,+FAA+F;AAC/F,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CASjE;AAED,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAE9E;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,CACP,MAAM,EAAE,WAAW,EACnB,aAAa,EAAE,CAAC,GAAG,CAAC,EACpB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAClC,KAAK,GAAE,MAAM,MAAiB,GAC7B,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAsBnB"}

package/dist/hookTimeouts.js

@@ -95,4 +95,101 @@ export function withHookTimeout(ms) {
     const timer = setTimeout(() => ac.abort(), ms);
     return { signal: ac.signal, cleanup: () => clearTimeout(timer) };
 }
+/**
+ * One second attempt on the main hook call (POST /api/v1/hooks/injections).
+ *
+ * Why it exists: on 24 October 2026 about a third of one machine's hook calls
+ * were lost for 50 minutes to a stall between Cloudflare and one load-balancer
+ * node. The server had accepted those requests and was waiting for a body that
+ * never finished arriving. A second request opens a new connection and
+ * normally lands on a healthy path. The call is idempotent by design (the
+ * injection bus dedups on the server), so repeating it is safe.
+ *
+ * Shape: the whole call, both attempts included, still ends inside `budgetMs`,
+ * so the budget every hook event is checked against (tests/HookEventBudgets
+ * .test.ts) and the host's kill limit do not move. The first attempt gets
+ * HOOK_FIRST_ATTEMPT_SHARE of the budget; the second gets whatever is left.
+ * A first attempt that fails fast leaves the second nearly the whole budget.
+ *
+ * What is retried: a timeout, a connection error, and the gateway statuses
+ * that mean the request never reached the application (408, 502, 503, 504 and
+ * Cloudflare's 52x). Nothing else is: a 4xx or a 500 repeats exactly, and a
+ * response that arrives is final.
+ *
+ * Nothing is queued or stored on the client. A call that fails twice is dropped,
+ * as before. The server keeps an answer for 15 s so the second attempt can have
+ * it when the first attempt gave up on an answer that was already decided.
+ */
+export const HOOK_FIRST_ATTEMPT_SHARE = 0.65;
+/** Below this much budget left, a second attempt cannot complete a round trip. */
+export const HOOK_SECOND_ATTEMPT_MIN_MS = 300;
+/** Sent on every attempt so the server can count how many calls needed a second one. */
+export const HOOK_ATTEMPT_HEADER = 'x-mnemonik-hook-attempt';
+/**
+ * Sent on both attempts with the same value. The server keeps the first
+ * attempt's answer for a few seconds under this id and hands it to the second
+ * attempt, so an answer decided after the first attempt gave up is delivered
+ * rather than lost, and nothing is counted twice (src/server/hookReplay.ts).
+ */
+export const HOOK_REQUEST_ID_HEADER = 'x-mnemonik-hook-request-id';
+/**
+ * Sent on every attempt: how many milliseconds this attempt may still take.
+ * The server never waits for a first attempt's answer longer than this less a
+ * margin for the return trip, so it does not hold a request for a client that
+ * has already given up.
+ */
+export const HOOK_BUDGET_HEADER = 'x-mnemonik-hook-budget-ms';
+/** Statuses that mean the request did not reach, or was not served by, the application. */
+export function isRetryableHookStatus(status) {
+    return (status === 408 ||
+        status === 502 ||
+        status === 503 ||
+        status === 504 ||
+        (status >= 520 && status <= 527) ||
+        status === 530);
+}
+/** Timeouts and connection failures. A parse error or a bug in the caller is not transient. */
+export function isTransientHookFetchError(error) {
+    if (!(error instanceof Error))
+        return false;
+    if (error.name === 'AbortError' || error.name === 'TimeoutError')
+        return true;
+    // undici reports a connection failure as TypeError('fetch failed') and a body
+    // cut off mid-transfer as TypeError('terminated'). Any other TypeError is a bug.
+    return (error instanceof TypeError &&
+        (error.message === 'fetch failed' || error.message === 'terminated'));
+}
+/**
+ * Run `attempt` and, when it ends in a transient failure, run it once more
+ * inside the rest of `budgetMs`. Returns the value of the attempt that
+ * finished, or null when neither did. `attempt` returns `{ done: false }` for
+ * a retryable response and throws for a transport failure; anything else it
+ * returns is final.
+ */
+export async function withSecondAttempt(budgetMs, attempt, clock = Date.now) {
+    const startedAt = clock();
+    const requestId = globalThis.crypto.randomUUID();
+    const run = async (attemptNumber, timeoutMs) => {
+        const { signal, cleanup } = withHookTimeout(timeoutMs);
+        try {
+            return await attempt(signal, attemptNumber, requestId, timeoutMs);
+        }
+        catch (error) {
+            if (!isTransientHookFetchError(error))
+                throw error;
+            return { done: false };
+        }
+        finally {
+            cleanup();
+        }
+    };
+    const first = await run(1, Math.floor(budgetMs * HOOK_FIRST_ATTEMPT_SHARE));
+    if (first.done)
+        return first.value;
+    const remainingMs = budgetMs - (clock() - startedAt);
+    if (remainingMs < HOOK_SECOND_ATTEMPT_MIN_MS)
+        return null;
+    const second = await run(2, Math.floor(remainingMs));
+    return second.done ? second.value : null;
+}
 //# sourceMappingURL=hookTimeouts.js.map

package/dist/hookTimeouts.js.map

@@ -1 +1 @@
-{"version":3,"file":"hookTimeouts.js","sourceRoot":"","sources":["../src/hookTimeouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAErC,2EAA2E;AAC3E,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAExC,2FAA2F;AAC3F,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,WAAW,EAAE,IAAI;IACjB,OAAO,EAAE,IAAI;IACb,KAAK,EAAE,IAAI;IACX,IAAI,EAAE,IAAI;IACV,MAAM,EAAE,MAAM;CACN,CAAC;AAGX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAEzC,8EAA8E;AAC9E,MAAM,UAAU,cAAc,CAAC,IAAc;IAC3C,OAAO,oBAAoB,CAAC,IAAI,CAAC,GAAG,sBAAsB,GAAG,qBAAqB,CAAC;AACrF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,EAAU;IACxC,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;AACnE,CAAC"}
+{"version":3,"file":"hookTimeouts.js","sourceRoot":"","sources":["../src/hookTimeouts.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemonik/shared",
-  "version": "7.148.0",
+  "version": "7.149.0",
   "description": "Shared constants and utilities for Mnemonik packages",
   "repository": {
     "type": "git",

package/src/hookTimeouts.ts

@@ -106,3 +106,118 @@ export function withHookTimeout(ms: number): { signal: AbortSignal; cleanup: ()
   const timer = setTimeout(() => ac.abort(), ms);
   return { signal: ac.signal, cleanup: () => clearTimeout(timer) };
 }
+
+/**
+ * One second attempt on the main hook call (POST /api/v1/hooks/injections).
+ *
+ * Why it exists: on 24 October 2026 about a third of one machine's hook calls
+ * were lost for 50 minutes to a stall between Cloudflare and one load-balancer
+ * node. The server had accepted those requests and was waiting for a body that
+ * never finished arriving. A second request opens a new connection and
+ * normally lands on a healthy path. The call is idempotent by design (the
+ * injection bus dedups on the server), so repeating it is safe.
+ *
+ * Shape: the whole call, both attempts included, still ends inside `budgetMs`,
+ * so the budget every hook event is checked against (tests/HookEventBudgets
+ * .test.ts) and the host's kill limit do not move. The first attempt gets
+ * HOOK_FIRST_ATTEMPT_SHARE of the budget; the second gets whatever is left.
+ * A first attempt that fails fast leaves the second nearly the whole budget.
+ *
+ * What is retried: a timeout, a connection error, and the gateway statuses
+ * that mean the request never reached the application (408, 502, 503, 504 and
+ * Cloudflare's 52x). Nothing else is: a 4xx or a 500 repeats exactly, and a
+ * response that arrives is final.
+ *
+ * Nothing is queued or stored on the client. A call that fails twice is dropped,
+ * as before. The server keeps an answer for 15 s so the second attempt can have
+ * it when the first attempt gave up on an answer that was already decided.
+ */
+export const HOOK_FIRST_ATTEMPT_SHARE = 0.65;
+
+/** Below this much budget left, a second attempt cannot complete a round trip. */
+export const HOOK_SECOND_ATTEMPT_MIN_MS = 300;
+
+/** Sent on every attempt so the server can count how many calls needed a second one. */
+export const HOOK_ATTEMPT_HEADER = 'x-mnemonik-hook-attempt';
+
+/**
+ * Sent on both attempts with the same value. The server keeps the first
+ * attempt's answer for a few seconds under this id and hands it to the second
+ * attempt, so an answer decided after the first attempt gave up is delivered
+ * rather than lost, and nothing is counted twice (src/server/hookReplay.ts).
+ */
+export const HOOK_REQUEST_ID_HEADER = 'x-mnemonik-hook-request-id';
+
+/**
+ * Sent on every attempt: how many milliseconds this attempt may still take.
+ * The server never waits for a first attempt's answer longer than this less a
+ * margin for the return trip, so it does not hold a request for a client that
+ * has already given up.
+ */
+export const HOOK_BUDGET_HEADER = 'x-mnemonik-hook-budget-ms';
+
+/** Statuses that mean the request did not reach, or was not served by, the application. */
+export function isRetryableHookStatus(status: number): boolean {
+  return (
+    status === 408 ||
+    status === 502 ||
+    status === 503 ||
+    status === 504 ||
+    (status >= 520 && status <= 527) ||
+    status === 530
+  );
+}
+
+/** Timeouts and connection failures. A parse error or a bug in the caller is not transient. */
+export function isTransientHookFetchError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  if (error.name === 'AbortError' || error.name === 'TimeoutError') return true;
+  // undici reports a connection failure as TypeError('fetch failed') and a body
+  // cut off mid-transfer as TypeError('terminated'). Any other TypeError is a bug.
+  return (
+    error instanceof TypeError &&
+    (error.message === 'fetch failed' || error.message === 'terminated')
+  );
+}
+
+export type HookAttemptResult<T> = { done: true; value: T } | { done: false };
+
+/**
+ * Run `attempt` and, when it ends in a transient failure, run it once more
+ * inside the rest of `budgetMs`. Returns the value of the attempt that
+ * finished, or null when neither did. `attempt` returns `{ done: false }` for
+ * a retryable response and throws for a transport failure; anything else it
+ * returns is final.
+ */
+export async function withSecondAttempt<T>(
+  budgetMs: number,
+  attempt: (
+    signal: AbortSignal,
+    attemptNumber: 1 | 2,
+    requestId: string,
+    budgetMs: number
+  ) => Promise<HookAttemptResult<T>>,
+  clock: () => number = Date.now
+): Promise<T | null> {
+  const startedAt = clock();
+  const requestId = globalThis.crypto.randomUUID();
+  const run = async (attemptNumber: 1 | 2, timeoutMs: number): Promise<HookAttemptResult<T>> => {
+    const { signal, cleanup } = withHookTimeout(timeoutMs);
+    try {
+      return await attempt(signal, attemptNumber, requestId, timeoutMs);
+    } catch (error) {
+      if (!isTransientHookFetchError(error)) throw error;
+      return { done: false };
+    } finally {
+      cleanup();
+    }
+  };
+
+  const first = await run(1, Math.floor(budgetMs * HOOK_FIRST_ATTEMPT_SHARE));
+  if (first.done) return first.value;
+
+  const remainingMs = budgetMs - (clock() - startedAt);
+  if (remainingMs < HOOK_SECOND_ATTEMPT_MIN_MS) return null;
+  const second = await run(2, Math.floor(remainingMs));
+  return second.done ? second.value : null;
+}