@adriangalilea/utils 9.3.0 → 9.5.0

package/README.md

@@ -77,6 +77,24 @@ Enable it only with a deletion and retention policy; no identity is inferred.
 `overlaps: [["a", "b"]]` declares unordered audience overlap, not an ordered funnel.
 Daily totals support counts and averages, not percentile latency or event ordering.
 
+## Visits
+
+A site keeps its own visits: ui's `page-sensor` posts each page's lines (the utils contract, "Web pages") to the site's own route, and `@adriangalilea/utils/visits` puts each page in a visit and keeps the rows the views read (ui's `user-flows`). No other server, no cookie, nothing kept in the browser.
+
+```typescript
+// app/api/events/route.ts
+import { libsqlDriver } from '@adriangalilea/utils/metrics/libsql'
+import { visitsRoute } from '@adriangalilea/utils/visits'
+
+export const POST = visitsRoute({ db: libsqlDriver(client), site: 'untitled.garden', services: ['garden-web'] })
+
+// a view
+const visits = await readVisits(libsqlDriver(client), { site: 'untitled.garden', days: 14 })
+// [{ id, started, places: ['studio', 'lore'], referrer: 'news.ycombinator.com', country: 'ES', … }]
+```
+
+A visit is one caller's pages, each within 30 minutes of the one before, within one UTC day. The caller is a hash of its IP and user agent with a random salt of the day, deleted when the day is over: a visitor is recognisable within a day, never across two, and once the salt is gone by no one, the site's owner included. The IP and user agent are never stored; the country (two letters, from the platform's header) is. Pages and visits are kept 180 days, a page's other lines (requests, named events, errors) 30, a probe's (an automated browser) and the staff's 7, and both are left out of `readVisits` unless `flagged`. Refused, by line: a service the site did not name, a line outside a page's trace, a field named like a person (`ip`, `user_agent`, `email`, `user`, `name`, `phone`). A crawler's batch is dropped whole. Provision `VISITS_SCHEMA` once (the tables are prefixed `visits_`); the route updates and deletes, so its credential needs both. `readVisit(db, id)` returns one visit's pages and lines, for its trace.
+
 ## Installation
 
 ```bash
@@ -160,6 +178,30 @@ Node, Bun and Deno write every event through `console.error` (stdout stays data,
 | `LOG_TIME` | `setLogTime` | `1`, `0` | off. Puts a dim local `HH:MM:SS` before human lines; json always carries `time` |
 | `LOG_LEVEL`, `{SCOPE}_LOG_LEVEL` | `setLogLevel` | the levels | `info` |
 | `LOG_SERVICE` | `setLogService` | a name | the entry script's name without extension. A Worker or browser has none: set it, or the first json event panics |
+| `LOG_SHIP` | `setLogShip` | an http(s) URL | unset. Every event that passes its threshold is also POSTed there (Shipping) |
+| `LOG_SHIP_TOKEN` | `setLogShipToken` | a token | unset. Sent as `Authorization: Bearer` with each batch; a browser sends none, and `setLogShipToken` in one panics |
+
+**Shipping.** With `LOG_SHIP` set, the logger also POSTs its events to that URL, so a process ships its stream with no code:
+
+```sh
+LOG_SHIP=https://events.untitled.garden/ingest LOG_SHIP_TOKEN=… node server.js
+```
+
+What ships is the stream's json line, byte for byte, whatever the console renders (human at a terminal included). A batch is lines joined by `\n`, `Content-Type: text/plain;charset=utf-8`, at most 64 KB and 50 events. It leaves 2s after its first event, at 50 events, when a span opened outside any local span ends (a root span, or a request joined from its caller: its whole trace leaves together), before a Node or Bun process exits on its own (`beforeExit`), and in a browser on `visibilitychange: hidden` and `pagehide`; whatever a hidden page sends goes through `sendBeacon`, the one request a browser finishes after the page is gone. `flushLog()` sends what waits and resolves when nothing is in flight: a Worker hands it to `ctx.waitUntil(flushLog())`, a serverless function to its runtime's `after`, and a process that calls `process.exit()` awaits it first (nothing else runs after `exit`). Shipping never throws and never blocks a write: a refused or lost batch is one `warnOnce` under scope `ship`, an event over 64 KB stays on the console and warns once. The wire and the collector's answers are the contract's, in [utils](https://github.com/adriangalilea/utils#shipping).
+
+**A page's trace on a Next.js server** (`@adriangalilea/utils/log/next`, `next` an optional peer). A page that writes the stream (utils README, "Web pages") puts its `traceparent` on every same-origin request; these wrappers make the server's work a child of that request, in the page's trace, and hand `flushLog` to Next's `after` so a frozen instance holds nothing unsent. A request with no `traceparent` is a root span of its own.
+
+```typescript
+import { traced, tracedAction } from '@adriangalilea/utils/log/next'
+
+export const POST = traced('POST /api/vote', async (s, request) => {
+  await s.span('turso insert vote', () => db.execute(insert))
+  return Response.json({ ok: true })
+})
+
+// in a "use server" file
+export const vote = tracedAction('vote', async (s, id: string) => { … })
+```
 
 **Reading the stream.** `LogEvent` is the wire shape as a type (a line, a span start, an ok end or a failed end, discriminated by `phase` and `status`), and `parseEvent(line)` reads one line back: an event, `null` for a line that is not one (pass it through), or a `Panic` for a JSON object with a `verb` key that breaks the shape.
 

package/dist/bot/access-control.d.ts

@@ -318,6 +318,13 @@ export declare const accessControl: (opts: AccessControlOptions) => Plugin<Recor
             $clear: () => Promise<void>;
         };
     };
+    location: {
+        session: {
+            access?: AccessRecord;
+        } & LangSession & {
+            $clear: () => Promise<void>;
+        };
+    };
     channel_post: {
         session: {
             access?: AccessRecord;
@@ -500,13 +507,6 @@ export declare const accessControl: (opts: AccessControlOptions) => Plugin<Recor
             $clear: () => Promise<void>;
         };
     };
-    location: {
-        session: {
-            access?: AccessRecord;
-        } & LangSession & {
-            $clear: () => Promise<void>;
-        };
-    };
     passport_data: {
         session: {
             access?: AccessRecord;

package/dist/bot/language.d.ts

@@ -228,6 +228,11 @@ declare const buildLanguagePlugin: <Lang extends string>(args: {
             $clear: () => Promise<void>;
         };
     };
+    location: {
+        session: SessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
     channel_post: {
         session: SessionLike & {
             $clear: () => Promise<void>;
@@ -358,11 +363,6 @@ declare const buildLanguagePlugin: <Lang extends string>(args: {
             $clear: () => Promise<void>;
         };
     };
-    location: {
-        session: SessionLike & {
-            $clear: () => Promise<void>;
-        };
-    };
     passport_data: {
         session: SessionLike & {
             $clear: () => Promise<void>;

package/dist/bot/llm.d.ts

@@ -243,6 +243,11 @@ declare const buildHistoryPlugin: (args: {
             $clear: () => Promise<void>;
         };
     };
+    location: {
+        session: LLMSessionLike & {
+            $clear: () => Promise<void>;
+        };
+    };
     channel_post: {
         session: LLMSessionLike & {
             $clear: () => Promise<void>;
@@ -373,11 +378,6 @@ declare const buildHistoryPlugin: (args: {
             $clear: () => Promise<void>;
         };
     };
-    location: {
-        session: LLMSessionLike & {
-            $clear: () => Promise<void>;
-        };
-    };
     passport_data: {
         session: LLMSessionLike & {
             $clear: () => Promise<void>;

package/dist/bot/payments/plugin.d.ts

@@ -118,6 +118,13 @@ declare const buildPlugin: (args: {
             $clear: () => Promise<void>;
         };
     };
+    location: {
+        session: {
+            pay?: import("./types.js").PaymentsSession;
+        } & import("../lang.js").LangSession & {
+            $clear: () => Promise<void>;
+        };
+    };
     channel_post: {
         session: {
             pay?: import("./types.js").PaymentsSession;
@@ -300,13 +307,6 @@ declare const buildPlugin: (args: {
             $clear: () => Promise<void>;
         };
     };
-    location: {
-        session: {
-            pay?: import("./types.js").PaymentsSession;
-        } & import("../lang.js").LangSession & {
-            $clear: () => Promise<void>;
-        };
-    };
     passport_data: {
         session: {
             pay?: import("./types.js").PaymentsSession;

package/dist/metrics/sqlite.d.ts

@@ -1,6 +1,6 @@
 import type { MetricsSchema, MetricsStore } from "./index.js";
 import { type ActiveActors, type Audience, type DailyMetric, type MetricsReport } from "./report.js";
-export type SqlValue = string | number;
+export type SqlValue = string | number | null;
 export interface SqlStatement {
     sql: string;
     args: SqlValue[];

package/dist/metrics/sqlite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/metrics/sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,aAAa,EAElB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AACvC,MAAM,WAAW,YAAY;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,QAAQ,EAAE,CAAC;CACjB;AAED,4FAA4F;AAC5F,MAAM,WAAW,aAAa;IAC7B,sCAAsC;IACtC,KAAK,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CAC3E;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAc,SAAQ,aAAa;IACnD,yFAAyF;IACzF,QAAQ,CAAC,UAAU,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACvD;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,uFAKjB,CAAC;AAEX,qEAAqE;AACrE,eAAO,MAAM,cAAc,88BAMjB,CAAC;AAsCX,gDAAgD;AAChD,wBAAgB,YAAY,CAC3B,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,MAAM,GACb,YAAY,CA0Dd;AAED,4FAA4F;AAC5F,wBAAsB,UAAU,CAC/B,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,MAAM,GACb,OAAO,CAAC,aAAa,CAAC,CA2BxB;AAED,uFAAuF;AACvF,wBAAsB,WAAW,CAChC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD,OAAO,CAAC,WAAW,EAAE,CAAC,CAmBxB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CACjC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EACpD,MAAM,EAAE,aAAa,GACnB,OAAO,CAAC,QAAQ,CAAC,CAmDnB;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAC/B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD,OAAO,CAAC,YAAY,EAAE,CAAC,CAgCzB;AAED,6FAA6F;AAC7F,wBAAsB,UAAU,CAC/B,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE;IACR,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,GAAG,CAAC,EAAE,IAAI,CAAC;CACX,GACC,OAAO,CAAC,aAAa,CAAC,CAkBxB"}
+{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/metrics/sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,aAAa,EAElB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAC9C,MAAM,WAAW,YAAY;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,QAAQ,EAAE,CAAC;CACjB;AAED,4FAA4F;AAC5F,MAAM,WAAW,aAAa;IAC7B,sCAAsC;IACtC,KAAK,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CAC3E;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAc,SAAQ,aAAa;IACnD,yFAAyF;IACzF,QAAQ,CAAC,UAAU,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACvD;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,uFAKjB,CAAC;AAEX,qEAAqE;AACrE,eAAO,MAAM,cAAc,88BAMjB,CAAC;AAsCX,gDAAgD;AAChD,wBAAgB,YAAY,CAC3B,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,MAAM,GACb,YAAY,CA0Dd;AAED,4FAA4F;AAC5F,wBAAsB,UAAU,CAC/B,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,MAAM,GACb,OAAO,CAAC,aAAa,CAAC,CA2BxB;AAED,uFAAuF;AACvF,wBAAsB,WAAW,CAChC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD,OAAO,CAAC,WAAW,EAAE,CAAC,CAmBxB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CACjC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EACpD,MAAM,EAAE,aAAa,GACnB,OAAO,CAAC,QAAQ,CAAC,CAmDnB;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAC/B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD,OAAO,CAAC,YAAY,EAAE,CAAC,CAgCzB;AAED,6FAA6F;AAC7F,wBAAsB,UAAU,CAC/B,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE;IACR,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,GAAG,CAAC,EAAE,IAAI,CAAC;CACX,GACC,OAAO,CAAC,aAAa,CAAC,CAkBxB"}

package/dist/next/log.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A Next.js server's half of a page's trace (utils README, "Web pages"). A
+ * request a page made carries the page's `traceparent` (log/web sets it on
+ * every same-origin fetch), so what the server does under these wrappers is
+ * a child of that request, in the page's trace:
+ *
+ *     export const POST = traced("POST /api/vote", async (s, request) => {
+ *       await s.span("turso insert vote", () => db.execute(...))
+ *       return Response.json({ ok: true })
+ *     })
+ *
+ *     // in a "use server" file
+ *     export const vote = tracedAction("vote", async (s, id: string) => { ... })
+ *
+ * A request with no traceparent is a root span of its own. Each wrapper hands
+ * flushLog to `after`, so a serverless instance frozen once its response is
+ * sent never holds unsent events (LOG_SHIP, set on the deployment, is where
+ * they go).
+ */
+import { type Span } from "../universal/log.js";
+/** A route handler whose work is a span, joined to the caller's trace. */
+export declare function traced<A extends unknown[], R>(name: string, handler: (s: Span, request: Request, ...rest: A) => Promise<R>): (request: Request, ...rest: A) => Promise<R>;
+/** A server action whose work is a span, joined to the trace of the page that called it. */
+export declare function tracedAction<A extends unknown[], R>(name: string, action: (s: Span, ...args: A) => Promise<R>): (...args: A) => Promise<R>;
+//# sourceMappingURL=log.d.ts.map

package/dist/next/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../src/next/log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,EAAiB,KAAK,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAE/D,0EAA0E;AAC1E,wBAAgB,MAAM,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,EAC5C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAC5D,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAO9C;AAED,4FAA4F;AAC5F,wBAAgB,YAAY,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,EAClD,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GACzC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAM5B"}

package/dist/next/log.js

@@ -0,0 +1,40 @@
+/**
+ * A Next.js server's half of a page's trace (utils README, "Web pages"). A
+ * request a page made carries the page's `traceparent` (log/web sets it on
+ * every same-origin fetch), so what the server does under these wrappers is
+ * a child of that request, in the page's trace:
+ *
+ *     export const POST = traced("POST /api/vote", async (s, request) => {
+ *       await s.span("turso insert vote", () => db.execute(...))
+ *       return Response.json({ ok: true })
+ *     })
+ *
+ *     // in a "use server" file
+ *     export const vote = tracedAction("vote", async (s, id: string) => { ... })
+ *
+ * A request with no traceparent is a root span of its own. Each wrapper hands
+ * flushLog to `after`, so a serverless instance frozen once its response is
+ * sent never holds unsent events (LOG_SHIP, set on the deployment, is where
+ * they go).
+ */
+import { headers } from "next/headers";
+import { after } from "next/server";
+import { flushLog, log } from "../universal/log.js";
+/** A route handler whose work is a span, joined to the caller's trace. */
+export function traced(name, handler) {
+    return (request, ...rest) => {
+        after(flushLog);
+        return log
+            .join(request.headers.get("traceparent"))
+            .span(name, (s) => handler(s, request, ...rest));
+    };
+}
+/** A server action whose work is a span, joined to the trace of the page that called it. */
+export function tracedAction(name, action) {
+    return async (...args) => {
+        after(flushLog);
+        const parent = (await headers()).get("traceparent");
+        return log.join(parent).span(name, (s) => action(s, ...args));
+    };
+}
+//# sourceMappingURL=log.js.map

package/dist/next/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../../src/next/log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAa,MAAM,qBAAqB,CAAC;AAE/D,0EAA0E;AAC1E,MAAM,UAAU,MAAM,CACrB,IAAY,EACZ,OAA8D;IAE9D,OAAO,CAAC,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE;QAC3B,KAAK,CAAC,QAAQ,CAAC,CAAC;QAChB,OAAO,GAAG;aACR,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;aACxC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;IACnD,CAAC,CAAC;AACH,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,YAAY,CAC3B,IAAY,EACZ,MAA2C;IAE3C,OAAO,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE;QACxB,KAAK,CAAC,QAAQ,CAAC,CAAC;QAChB,MAAM,MAAM,GAAG,CAAC,MAAM,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACpD,OAAO,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;IAC/D,CAAC,CAAC;AACH,CAAC"}

package/dist/universal/log.d.ts

@@ -76,6 +76,21 @@
  *     log, stdout stays data, and cli/live's console patch keeps lines above
  *     a live region. Browsers and Workers use the level's console method.
  *
+ * Shipping
+ *     LOG_SHIP=<url> (setLogShip) also POSTs every event that passes its
+ *     threshold there: the json line, whatever the console renders, in
+ *     batches of lines joined by "\n" (text/plain;charset=utf-8, at most
+ *     64 KB and 50 events). A batch leaves 2s after its first event, at 50,
+ *     when a span opened outside any local span ends (a request's trace
+ *     leaves together), before a Node/Bun process exits (beforeExit), and in
+ *     a browser on hidden or pagehide; whatever a hidden page sends goes
+ *     through sendBeacon, which outlives the page. LOG_SHIP_TOKEN
+ *     (setLogShipToken) is a bearer for servers; a browser sends none.
+ *     flushLog() sends what waits and resolves when nothing is in flight:
+ *     a Worker hands it to waitUntil, a process that calls process.exit()
+ *     awaits it first. Shipping never throws and never blocks a write: a
+ *     refused or lost batch is one warnOnce, scope ["ship"].
+ *
  * The wire shape is exported as LogEvent, and parseEvent(line) reads one back.
  */
 export type LogLevel = "silent" | "error" | "warn" | "info" | "debug" | "trace";
@@ -147,6 +162,16 @@ export declare function setLogFormat(format: LogFormat): void;
 export declare function setLogTime(on: boolean): void;
 /** The program's name in every event. LOG_SERVICE overrides it. */
 export declare function setLogService(name: string): void;
+/** Where events are also POSTed, in batches. LOG_SHIP overrides it. */
+export declare function setLogShip(url: string): void;
+/** The bearer sent with each batch (servers only). LOG_SHIP_TOKEN overrides it. */
+export declare function setLogShipToken(token: string): void;
+/**
+ * Send what waits to LOG_SHIP and resolve when no batch is in flight. A
+ * Worker hands it to waitUntil; a process that calls process.exit() awaits it
+ * first. Never rejects: a lost batch is a warnOnce.
+ */
+export declare function flushLog(): Promise<void>;
 export interface Logger {
     error(message: string, fields?: Fields): void;
     fail(message: string, fields?: Fields): void;

package/dist/universal/log.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../src/universal/log.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../src/universal/log.ts"],"names":[],"mappings":"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"}

package/dist/universal/log.js

@@ -76,6 +76,21 @@
  *     log, stdout stays data, and cli/live's console patch keeps lines above
  *     a live region. Browsers and Workers use the level's console method.
  *
+ * Shipping
+ *     LOG_SHIP=<url> (setLogShip) also POSTs every event that passes its
+ *     threshold there: the json line, whatever the console renders, in
+ *     batches of lines joined by "\n" (text/plain;charset=utf-8, at most
+ *     64 KB and 50 events). A batch leaves 2s after its first event, at 50,
+ *     when a span opened outside any local span ends (a request's trace
+ *     leaves together), before a Node/Bun process exits (beforeExit), and in
+ *     a browser on hidden or pagehide; whatever a hidden page sends goes
+ *     through sendBeacon, which outlives the page. LOG_SHIP_TOKEN
+ *     (setLogShipToken) is a bearer for servers; a browser sends none.
+ *     flushLog() sends what waits and resolves when nothing is in flight:
+ *     a Worker hands it to waitUntil, a process that calls process.exit()
+ *     awaits it first. Shipping never throws and never blocks a write: a
+ *     refused or lost batch is one warnOnce, scope ["ship"].
+ *
  * The wire shape is exported as LogEvent, and parseEvent(line) reads one back.
  */
 import { assert, panic, SourcedError } from "../offensive.js";
@@ -468,6 +483,7 @@ function emit(d) {
     // Every knob is read on every event, so a bad value screams whichever rendering is on.
     const format = currentFormat();
     const clock = timeEnabled();
+    const target = shipTarget();
     const text = format === "json" ? json(d, now) : human(d, now, clock);
     // Node: everything to stderr through console.error, which cli/live patches
     // to keep lines above an active region. Elsewhere the level's method, so
@@ -476,6 +492,173 @@ function emit(d) {
         console.error(text);
     else
         console[CONSOLE_METHOD[VERBS[d.verb].level]](text);
+    // What ships is the stream's json line, whatever the console renders.
+    if (target !== undefined)
+        ship(target, format === "json" ? text : json(d, now));
+}
+// --- shipping ----------------------------------------------------------------
+/** A batch's ceiling in UTF-8 bytes: navigator.sendBeacon's. */
+const SHIP_MAX_BYTES = 64 * 1024;
+const SHIP_MAX_EVENTS = 50;
+const SHIP_AFTER_MS = 2000;
+let shipSetting;
+let shipTokenSetting;
+function parseShip(raw, source) {
+    if (!URL.canParse(raw))
+        panic(`unknown ${source}:`, raw, "(want a URL)");
+    const url = new URL(raw);
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        panic(`unknown ${source}:`, raw, "(want an http(s) URL)");
+    return url.href;
+}
+/** Where events are also POSTed, in batches. LOG_SHIP overrides it. */
+export function setLogShip(url) {
+    shipSetting = parseShip(url, "log ship");
+}
+/** The bearer sent with each batch (servers only). LOG_SHIP_TOKEN overrides it. */
+export function setLogShipToken(token) {
+    assert(sink !== "browser", "a browser ships without a token: any token in a page is public");
+    if (typeof token !== "string" || token.length === 0)
+        panic("setLogShipToken wants a non-empty token, got:", token);
+    shipTokenSetting = token;
+}
+// LOG_SHIP is read live like every variable; the parse is kept per value.
+let shipParsed;
+function shipTarget() {
+    const fromEnv = env("LOG_SHIP");
+    const raw = fromEnv ?? shipSetting;
+    if (raw === undefined)
+        return undefined;
+    if (shipParsed?.raw !== raw)
+        shipParsed = {
+            raw,
+            href: fromEnv === undefined ? raw : parseShip(raw, "LOG_SHIP"),
+        };
+    return shipParsed.href;
+}
+const shipLog = () => log.scope("ship");
+const utf8 = new TextEncoder();
+let batch;
+let batchTimer;
+const inflight = new Set();
+let exitHooked = false;
+function ship(target, text) {
+    hookExit();
+    const bytes = utf8.encode(text).length;
+    if (bytes > SHIP_MAX_BYTES) {
+        shipLog().warnOnce("event too large to ship", {
+            bytes,
+            limit: SHIP_MAX_BYTES,
+        });
+        return;
+    }
+    if (batch !== undefined &&
+        (batch.target !== target || batch.bytes + 1 + bytes > SHIP_MAX_BYTES))
+        send();
+    if (batch === undefined) {
+        batch = { target, lines: [], bytes: -1 };
+        // A pending batch never keeps a process alive: beforeExit sends it.
+        const timer = setTimeout(send, SHIP_AFTER_MS);
+        timer.unref?.();
+        batchTimer = timer;
+    }
+    batch.lines.push(text);
+    batch.bytes += 1 + bytes;
+    if (batch.lines.length >= SHIP_MAX_EVENTS)
+        send();
+}
+/** Take the waiting batch, if any, and stop its timer. */
+function takeBatch() {
+    if (batchTimer !== undefined)
+        clearTimeout(batchTimer);
+    batchTimer = undefined;
+    const taken = batch;
+    batch = undefined;
+    return taken;
+}
+function send() {
+    // A hidden page may be gone before a fetch answers: the beacon outlives it.
+    if (sink === "browser" &&
+        globalThis.document.visibilityState ===
+            "hidden") {
+        beacon();
+        return;
+    }
+    const b = takeBatch();
+    if (b === undefined)
+        return;
+    const p = post(b.target, b.lines.join("\n")).finally(() => inflight.delete(p));
+    inflight.add(p);
+}
+async function post(target, body) {
+    const token = sink === "browser"
+        ? undefined
+        : (env("LOG_SHIP_TOKEN") ?? shipTokenSetting);
+    const headers = {
+        "content-type": "text/plain;charset=utf-8",
+    };
+    if (token !== undefined)
+        headers.authorization = `Bearer ${token}`;
+    try {
+        const res = await fetch(target, {
+            method: "POST",
+            headers,
+            body,
+            keepalive: sink === "browser",
+        });
+        if (res.status === 204)
+            return;
+        shipLog().warnOnce("log batch refused", {
+            status: res.status,
+            answer: (await res.text()).slice(0, 1000),
+        });
+    }
+    catch (err) {
+        shipLog().warnOnce("log batch not delivered", { err });
+    }
+}
+// Hidden is the last moment a page reliably sends anything; sendBeacon is the
+// one request the browser finishes after the page is gone.
+function beacon() {
+    const b = takeBatch();
+    if (b === undefined)
+        return;
+    const page = globalThis;
+    if (!page.navigator.sendBeacon(b.target, b.lines.join("\n")))
+        shipLog().warnOnce("log batch refused by the browser", {
+            events: b.lines.length,
+        });
+}
+// Hooked on the first shipped event, so importing the logger has no effect.
+function hookExit() {
+    if (exitHooked)
+        return;
+    exitHooked = true;
+    if (runtime.isNode || runtime.isBun) {
+        process.on("beforeExit", () => send());
+        return;
+    }
+    if (sink !== "browser")
+        return;
+    const page = globalThis;
+    page.document.addEventListener("visibilitychange", () => {
+        if (page.document.visibilityState === "hidden")
+            beacon();
+    });
+    page.addEventListener("pagehide", beacon);
+}
+/**
+ * Send what waits to LOG_SHIP and resolve when no batch is in flight. A
+ * Worker hands it to waitUntil; a process that calls process.exit() awaits it
+ * first. Never rejects: a lost batch is a warnOnce.
+ */
+export async function flushLog() {
+    send();
+    while (inflight.size > 0) {
+        await Promise.all(inflight);
+        // A refused batch's warning is an event too: it ships next.
+        send();
+    }
 }
 const BOUND = 1024;
 const warned = new Set();
@@ -531,6 +714,52 @@ function open(ctx, name, initial) {
             parent,
             fields,
         });
+    function finish(err) {
+        const dur = performance.now() - began;
+        const failed = err !== undefined && err !== null;
+        const printed = err instanceof Error && caught.has(err) ? err : undefined;
+        // What spans inside this one printed stays printed for the spans around it.
+        for (const e of caught)
+            ctx.caught?.add(e);
+        if (!shown) {
+            // The end follows the decision made at begin: no end without its
+            // start. A failure is never lost to it: one line of the nearest
+            // shown span says the span failed.
+            if (!failed || !admits(ctx.scope, "error"))
+                return;
+            if (err instanceof Error)
+                ctx.caught?.add(err);
+            emit({
+                verb: "fail",
+                msg: name,
+                scope: ctx.scope,
+                depth: inner.depth,
+                trace: inner.owner === undefined ? undefined : trace,
+                span: inner.owner,
+                fields: { ...fields, ...added, err, dur_ms: round3(dur) },
+                printed,
+            });
+            return;
+        }
+        if (failed && err instanceof Error)
+            ctx.caught?.add(err);
+        const shows = failed ? { ...added, err } : added;
+        emit({
+            verb: failed ? "fail" : "success",
+            msg: name,
+            scope: ctx.scope,
+            depth: ctx.depth,
+            phase: "end",
+            trace,
+            span: id,
+            parent,
+            status: failed ? "error" : "ok",
+            dur,
+            fields: { ...fields, ...shows },
+            shows,
+            printed,
+        });
+    }
     // A hidden span is transparent: its lines and children attach to the nearest
     // shown span, a joined remote one included (it is shown in its own process's
     // stream). With none, its lines carry no ids, as lines outside any span.
@@ -565,50 +794,11 @@ function open(ctx, name, initial) {
         end(err) {
             assert(!ended, "span", name, "ended twice");
             ended = true;
-            const dur = performance.now() - began;
-            const failed = err !== undefined && err !== null;
-            const printed = err instanceof Error && caught.has(err) ? err : undefined;
-            // What spans inside this one printed stays printed for the spans around it.
-            for (const e of caught)
-                ctx.caught?.add(e);
-            if (!shown) {
-                // The end follows the decision made at begin: no end without its
-                // start. A failure is never lost to it: one line of the nearest
-                // shown span says the span failed.
-                if (!failed || !admits(ctx.scope, "error"))
-                    return;
-                if (err instanceof Error)
-                    ctx.caught?.add(err);
-                emit({
-                    verb: "fail",
-                    msg: name,
-                    scope: ctx.scope,
-                    depth: inner.depth,
-                    trace: inner.owner === undefined ? undefined : trace,
-                    span: inner.owner,
-                    fields: { ...fields, ...added, err, dur_ms: round3(dur) },
-                    printed,
-                });
-                return;
-            }
-            if (failed && err instanceof Error)
-                ctx.caught?.add(err);
-            const shows = failed ? { ...added, err } : added;
-            emit({
-                verb: failed ? "fail" : "success",
-                msg: name,
-                scope: ctx.scope,
-                depth: ctx.depth,
-                phase: "end",
-                trace,
-                span: id,
-                parent,
-                status: failed ? "error" : "ok",
-                dur,
-                fields: { ...fields, ...shows },
-                shows,
-                printed,
-            });
+            finish(err);
+            // A span opened outside any local span (a root, or a request joined
+            // from its caller) ends its trace here: what it wrote ships together.
+            if (ctx.caught === undefined)
+                send();
         },
     });
 }