pipework 0.203.1 → 0.204.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.204.0
+
+- **Fixed: a read cut off by the page leaving was reported as a client fault** (#779). A link, reload or `location.href` cuts off the page's in-flight fetches, and their rejections reached `reportClientFault` as faults. `reportClientFault` now holds a report made after `beforeunload`: it is dropped if `pagehide` follows, and sent if the page stays (10 s with no `pagehide`, `LEAVING_HOLD_MS`, or a bfcache restore). A report made after `pagehide` is dropped. This covers every kind (`request`, `error`, `rejection`, `render`). Pass `{ whileLeaving: 'send' }` as the third argument to send at once, for a failure that matters even while leaving (a save cut off by leaving). `pageLeaving()` says whether the page is leaving. A failure while the page stays is reported as before.
+
 ## 0.203.1
 
 - **Fixed: two `alerts.source.deadLetter` sources on different tables shared one position** (#777). The second to evaluate started from where the first had moved, so a dead letter in its table could be missed. Each table now keeps its own position, as each filter already did: state key `job-dead-letter@<table>` (with the `:only:`/`:except:` suffix as before). A source on the default `pipework_jobs` table keeps the key `job-dead-letter`, so its position carries over. A source on another table starts a new position from its first evaluation after the upgrade, so dead letters committed between its last evaluation before the upgrade and that first one are not raised. Condition keys are unchanged.

package/REFERENCE.md

@@ -1918,7 +1918,7 @@ await ops.resolve('engine-unavailable')
 - Body, strict (an unknown field is 400, and nothing is raised): `app`, `where` (1-100 of `A-Za-z0-9._:/-`), `kind` (`error | rejection | render | request`), `severity?` (`warning | error`, default `error`), `code?` (100), `message` (1-500), `stack?` (4096), `route?` (200, starts with `/`, no `?`, `#` or `://`: a route pattern, never a page URL), `release?` (100), `traceId?` (a uuid: the `x-pipework-trace-id` of an answer), `requestId?` (1-100 of `A-Za-z0-9._:-`: the `x-request-id` of an answer).
 - Each report is a trace step `pipework/alerts:client-fault` capturing the report, and raises the key with severity as sent, the app's `owner` and `runbook` (or the report's from `assign`), and context `{ app, where, kind, code?, route?, release?, traceId?, requestId? }`. The stack is in the step's capture only. A raise that fails is logged; the answer is still 204.
 
-`reportClientFault(url, report)` from `pipework/client` sends a report with `keepalive` and `credentials: 'include'`, cuts `message` and `stack` to their caps, and never throws.
+`reportClientFault(url, report)` from `pipework/client` sends a report with `keepalive` and `credentials: 'include'`, cuts `message` and `stack` to their caps, and never throws. A report made while the page is leaving (after `beforeunload`) is held: dropped if `pagehide` follows, sent if the page stays (10 s with no `pagehide`, or a bfcache restore), so a read cut off by a link or reload raises nothing. Pass `{ whileLeaving: 'send' }` as the third argument to send at once (a save cut off by leaving); `pageLeaving()` says whether the page is leaving.
 
 ```ts
 import { reportClientFault } from 'pipework/client'

package/dist/client/index.d.ts

@@ -1,3 +1,3 @@
-export { reportClientFault, CLIENT_FAULT_MESSAGE_MAX, CLIENT_FAULT_STACK_MAX } from './report-fault.js';
-export type { ClientFaultReport } from './report-fault.js';
+export { reportClientFault, pageLeaving, LEAVING_HOLD_MS, CLIENT_FAULT_MESSAGE_MAX, CLIENT_FAULT_STACK_MAX } from './report-fault.js';
+export type { ClientFaultReport, ReportClientFaultOptions } from './report-fault.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AACvG,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,eAAe,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AACrI,YAAY,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/client/index.js

@@ -1,2 +1,2 @@
-export { reportClientFault, CLIENT_FAULT_MESSAGE_MAX, CLIENT_FAULT_STACK_MAX } from './report-fault.js';
+export { reportClientFault, pageLeaving, LEAVING_HOLD_MS, CLIENT_FAULT_MESSAGE_MAX, CLIENT_FAULT_STACK_MAX } from './report-fault.js';
 //# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,eAAe,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/client/report-fault.d.ts

@@ -24,9 +24,18 @@ export interface ClientFaultReport {
 }
 export declare const CLIENT_FAULT_MESSAGE_MAX = 500;
 export declare const CLIENT_FAULT_STACK_MAX = 4096;
+/** How long a report made after `beforeunload` is held waiting for `pagehide` before the page is taken to be staying. */
+export declare const LEAVING_HOLD_MS = 10000;
+export interface ReportClientFaultOptions {
+    /** Default `hold`: a report made while the page is leaving waits, and is dropped if the page goes. `send` sends at once (a save cut off by leaving). */
+    whileLeaving?: 'hold' | 'send';
+}
+/** True from `beforeunload` until the page stays again (the hold timer ran out or a bfcache restore); stays true after `pagehide`. */
+export declare function pageLeaving(): boolean;
 /**
  * Sends a failure to the intake route at `url` with `keepalive`, so it survives a page unload.
- * Cuts `message` and `stack` to their caps. Never throws and never rejects: a report that cannot be sent is dropped.
+ * Cuts `message` and `stack` to their caps. A report made while the page is leaving is held and dropped on `pagehide`,
+ * unless `options.whileLeaving` is `send`. Never throws and never rejects: a report that cannot be sent is dropped.
  */
-export declare function reportClientFault(url: string, report: ClientFaultReport): void;
+export declare function reportClientFault(url: string, report: ClientFaultReport, options?: ReportClientFaultOptions): void;
 //# sourceMappingURL=report-fault.d.ts.map

package/dist/client/report-fault.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"report-fault.d.ts","sourceRoot":"","sources":["../../src/client/report-fault.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAA;IACX,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,OAAO,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAA;IAClD,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,CAAA;IAC9B,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAA;IACf,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8GAA8G;IAC9G,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4HAA4H;IAC5H,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qGAAqG;IACrG,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,eAAO,MAAM,wBAAwB,MAAM,CAAA;AAC3C,eAAO,MAAM,sBAAsB,OAAO,CAAA;AAE1C;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAe9E"}
+{"version":3,"file":"report-fault.d.ts","sourceRoot":"","sources":["../../src/client/report-fault.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAA;IACX,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,OAAO,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAA;IAClD,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,CAAA;IAC9B,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAA;IACf,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8GAA8G;IAC9G,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4HAA4H;IAC5H,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qGAAqG;IACrG,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,eAAO,MAAM,wBAAwB,MAAM,CAAA;AAC3C,eAAO,MAAM,sBAAsB,OAAO,CAAA;AAE1C,yHAAyH;AACzH,eAAO,MAAM,eAAe,QAAS,CAAA;AAErC,MAAM,WAAW,wBAAwB;IACvC,wJAAwJ;IACxJ,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAC/B;AA2CD,sIAAsI;AACtI,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,IAAI,CA6BlH"}

package/dist/client/report-fault.js

@@ -1,23 +1,85 @@
 // Browser-safe: no node imports, no runtime dependencies.
 export const CLIENT_FAULT_MESSAGE_MAX = 500;
 export const CLIENT_FAULT_STACK_MAX = 4096;
+/** How long a report made after `beforeunload` is held waiting for `pagehide` before the page is taken to be staying. */
+export const LEAVING_HOLD_MS = 10_000;
+let leaving = false;
+let left = false;
+let timer;
+let held = [];
+function clearHold() {
+    if (timer !== undefined)
+        clearTimeout(timer);
+    timer = undefined;
+    held = [];
+}
+function stay() {
+    const pending = held;
+    leaving = false;
+    left = false;
+    if (timer !== undefined)
+        clearTimeout(timer);
+    timer = undefined;
+    held = [];
+    for (const send of pending)
+        send();
+}
+const win = globalThis;
+if (typeof win.addEventListener === 'function') {
+    win.addEventListener('beforeunload', () => {
+        leaving = true;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = setTimeout(stay, LEAVING_HOLD_MS);
+    }, { passive: true });
+    win.addEventListener('pagehide', () => {
+        leaving = true;
+        left = true;
+        clearHold();
+    }, { passive: true });
+    win.addEventListener('pageshow', (event) => {
+        if (event.persisted === true)
+            stay();
+    }, { passive: true });
+}
+/** True from `beforeunload` until the page stays again (the hold timer ran out or a bfcache restore); stays true after `pagehide`. */
+export function pageLeaving() {
+    return leaving;
+}
 /**
  * Sends a failure to the intake route at `url` with `keepalive`, so it survives a page unload.
- * Cuts `message` and `stack` to their caps. Never throws and never rejects: a report that cannot be sent is dropped.
+ * Cuts `message` and `stack` to their caps. A report made while the page is leaving is held and dropped on `pagehide`,
+ * unless `options.whileLeaving` is `send`. Never throws and never rejects: a report that cannot be sent is dropped.
  */
-export function reportClientFault(url, report) {
+export function reportClientFault(url, report, options) {
     try {
         const body = { ...report, message: report.message.slice(0, CLIENT_FAULT_MESSAGE_MAX) };
         if (body.stack !== undefined)
             body.stack = body.stack.slice(0, CLIENT_FAULT_STACK_MAX);
-        const sent = fetch(url, {
-            method: 'POST',
-            keepalive: true,
-            credentials: 'include',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify(body),
-        });
-        Promise.resolve(sent).catch(() => undefined);
+        const send = () => {
+            try {
+                const sent = fetch(url, {
+                    method: 'POST',
+                    keepalive: true,
+                    credentials: 'include',
+                    headers: { 'content-type': 'application/json' },
+                    body: JSON.stringify(body),
+                });
+                Promise.resolve(sent).catch(() => undefined);
+            }
+            catch {
+                // dropped
+            }
+        };
+        if (options?.whileLeaving !== 'send') {
+            if (left)
+                return;
+            if (leaving) {
+                held.push(send);
+                return;
+            }
+        }
+        send();
     }
     catch {
         // dropped

package/dist/client/report-fault.js.map

@@ -1 +1 @@
-{"version":3,"file":"report-fault.js","sourceRoot":"","sources":["../../src/client/report-fault.ts"],"names":[],"mappings":"AAAA,0DAA0D;AA2B1D,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,CAAA;AAC3C,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAA;AAE1C;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,MAAyB;IACtE,IAAI,CAAC;QACH,MAAM,IAAI,GAAsB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,wBAAwB,CAAC,EAAE,CAAA;QACzG,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,sBAAsB,CAAC,CAAA;QACtF,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE;YACtB,MAAM,EAAE,MAAM;YACd,SAAS,EAAE,IAAI;YACf,WAAW,EAAE,SAAS;YACtB,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CAAC,CAAA;QACF,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,UAAU;IACZ,CAAC;AACH,CAAC"}
+{"version":3,"file":"report-fault.js","sourceRoot":"","sources":["../../src/client/report-fault.ts"],"names":[],"mappings":"AAAA,0DAA0D;AA2B1D,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,CAAA;AAC3C,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAA;AAE1C,yHAAyH;AACzH,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAA;AAOrC,IAAI,OAAO,GAAG,KAAK,CAAA;AACnB,IAAI,IAAI,GAAG,KAAK,CAAA;AAChB,IAAI,KAAgD,CAAA;AACpD,IAAI,IAAI,GAAsB,EAAE,CAAA;AAEhC,SAAS,SAAS;IAChB,IAAI,KAAK,KAAK,SAAS;QAAE,YAAY,CAAC,KAAK,CAAC,CAAA;IAC5C,KAAK,GAAG,SAAS,CAAA;IACjB,IAAI,GAAG,EAAE,CAAA;AACX,CAAC;AAED,SAAS,IAAI;IACX,MAAM,OAAO,GAAG,IAAI,CAAA;IACpB,OAAO,GAAG,KAAK,CAAA;IACf,IAAI,GAAG,KAAK,CAAA;IACZ,IAAI,KAAK,KAAK,SAAS;QAAE,YAAY,CAAC,KAAK,CAAC,CAAA;IAC5C,KAAK,GAAG,SAAS,CAAA;IACjB,IAAI,GAAG,EAAE,CAAA;IACT,KAAK,MAAM,IAAI,IAAI,OAAO;QAAE,IAAI,EAAE,CAAA;AACpC,CAAC;AAED,MAAM,GAAG,GAAG,UAEX,CAAA;AAED,IAAI,OAAO,GAAG,CAAC,gBAAgB,KAAK,UAAU,EAAE,CAAC;IAC/C,GAAG,CAAC,gBAAgB,CAAC,cAAc,EAAE,GAAG,EAAE;QACxC,OAAO,GAAG,IAAI,CAAA;QACd,IAAI,KAAK,KAAK,SAAS;YAAE,YAAY,CAAC,KAAK,CAAC,CAAA;QAC5C,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,eAAe,CAAC,CAAA;IAC3C,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAA;IACrB,GAAG,CAAC,gBAAgB,CAAC,UAAU,EAAE,GAAG,EAAE;QACpC,OAAO,GAAG,IAAI,CAAA;QACd,IAAI,GAAG,IAAI,CAAA;QACX,SAAS,EAAE,CAAA;IACb,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAA;IACrB,GAAG,CAAC,gBAAgB,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,EAAE;QACzC,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI;YAAE,IAAI,EAAE,CAAA;IACtC,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAA;AACvB,CAAC;AAED,sIAAsI;AACtI,MAAM,UAAU,WAAW;IACzB,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,MAAyB,EAAE,OAAkC;IAC1G,IAAI,CAAC;QACH,MAAM,IAAI,GAAsB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,wBAAwB,CAAC,EAAE,CAAA;QACzG,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,sBAAsB,CAAC,CAAA;QACtF,MAAM,IAAI,GAAG,GAAS,EAAE;YACtB,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE;oBACtB,MAAM,EAAE,MAAM;oBACd,SAAS,EAAE,IAAI;oBACf,WAAW,EAAE,SAAS;oBACtB,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;oBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;iBAC3B,CAAC,CAAA;gBACF,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;YAC9C,CAAC;YAAC,MAAM,CAAC;gBACP,UAAU;YACZ,CAAC;QACH,CAAC,CAAA;QACD,IAAI,OAAO,EAAE,YAAY,KAAK,MAAM,EAAE,CAAC;YACrC,IAAI,IAAI;gBAAE,OAAM;YAChB,IAAI,OAAO,EAAE,CAAC;gBACZ,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;gBACf,OAAM;YACR,CAAC;QACH,CAAC;QACD,IAAI,EAAE,CAAA;IACR,CAAC;IAAC,MAAM,CAAC;QACP,UAAU;IACZ,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pipework",
-  "version": "0.203.1",
+  "version": "0.204.0",
   "description": "TypeScript framework for multi-tenant SaaS applications. PostgreSQL-only.",
   "type": "module",
   "license": "MIT",