@columenlabs/lumen-ops 0.1.88 → 0.1.89

package/README.md

@@ -126,6 +126,21 @@ app.use('*', requestMeter({
 
 A path no route matched is written as `*`, so a scanner's junk never lands. Without Hono, wrap the handler in `withRequest(scope, route, fn)` and call `meterRequest(point)` yourself.
 
+## Bindings and outbound calls
+
+Wrap the env once at the entry and patch `fetch` once, and every Durable Object RPC method, Workers AI, Vectorize, KV, R2, service or VPC call and every outbound `fetch` is timed and charged to the request in scope:
+
+```ts
+import { meterFetch, meteredBindings } from '@columenlabs/lumen-ops';
+import { requestMeter } from '@columenlabs/lumen-ops/hono';
+
+meterFetch();
+app.use('*', requestMeter({ app: 'myapp', serverTiming: true }));
+export default { fetch: (req, env, ctx) => app.fetch(req, meteredBindings(env, { kinds: { AI: 'ai', INDEX: 'vectorize' }, skip: ['METRICS'] }), ctx) };
+```
+
+A call is named by its binding and method (`DIRECTORY.seen`, `AI.run`, `fetch.api.example.com`), never its arguments. The request point's `upstream ms` and `subrequests` add them up; `serverTiming: true` sends the split back as `Server-Timing` (`do`, `ai`, `fetch`, ..., `app`, `total`), and when the request ends each call code is one `call` event (`code` the call, `ref` its kind, `ms` the total, counts: calls, failed). Outside a request (an alarm) each call is its own event. `app` may be a function and `route` names the route when one Worker hands requests on to other apps by path.
+
 ## Events
 
 `@columenlabs/lumen-ops/events` writes what an app does that isn't a request it answers: a call to another service, a webhook in or out, a sync's start and end, a sign-in. With the request points they show whether what came in was acted on.

package/dist/bindings.d.ts

@@ -0,0 +1,22 @@
+export interface BindingMeterOptions {
+    /** The kind each binding counts as (`{ AI: 'ai', CAREER_INDEX: 'vectorize' }`); a Durable Object
+     * namespace is `do` and a binding with only `fetch` is `fetch` without saying. */
+    kinds?: Record<string, string>;
+    /** Bindings left as they are (an Analytics Engine dataset, a Secrets Store secret). */
+    skip?: string[];
+}
+/**
+ * The env with every object binding metered. Strings (vars) and skipped bindings pass through as
+ * they are. Wrap once per request at the entry and hand the result to the app.
+ */
+export declare function meteredBindings<E extends object>(env: E, opts?: BindingMeterOptions): E;
+/**
+ * Patches the global `fetch` once per isolate: every outbound request is a `fetch` call coded by
+ * its host (`fetch.api.example.com`), never its path or query.
+ */
+export declare function meterFetch(): void;
+/**
+ * Writes one `call` event per call code the request in scope made (counts: calls, failed; ms:
+ * their total). The request meter's Hono middleware calls this itself after the answer.
+ */
+export declare function flushCalls(): void;

package/dist/bindings.js

@@ -0,0 +1,131 @@
+/**
+ * The binding meter: every call a Worker makes to its bindings (a Durable Object's RPC method,
+ * Workers AI, Vectorize, KV, R2, a service or VPC binding) and every outbound `fetch` is timed and
+ * charged to the request in scope, without touching a call site. Wrap the env once at the entry
+ * (`meteredBindings`), patch `fetch` once (`meterFetch`), and the request meter then has, per
+ * request, how many calls of each kind ran and how long they took (`Server-Timing`, and one `call`
+ * event per call code when the request ends: `flushCalls`).
+ *
+ * A call is named by its binding and method only (`DIRECTORY.seen`, `AI.run`, `fetch.api.x.com`),
+ * never its arguments, so no id, key or person's data is ever written.
+ */
+import { meterEvent } from './events.js';
+import { addCall, requestCalls } from './requests.js';
+const isThenable = (v) => !!v &&
+    (typeof v === 'object' || typeof v === 'function') &&
+    typeof v.then === 'function';
+/** Times one call: charged to the request in scope, else written as its own event. */
+function charge(kind, code, t0, ok) {
+    const ms = performance.now() - t0;
+    if (!addCall(kind, code, ms, ok))
+        meterEvent({ event: 'call', code, ok, ms, counts: [1, ok ? 0 : 1] });
+}
+function timed(kind, code, run) {
+    const t0 = performance.now();
+    let out;
+    try {
+        out = run();
+    }
+    catch (err) {
+        charge(kind, code, t0, false);
+        throw err;
+    }
+    if (!isThenable(out))
+        return out;
+    return Promise.resolve(out).then((v) => {
+        charge(kind, code, t0, true);
+        return v;
+    }, (err) => {
+        charge(kind, code, t0, false);
+        throw err;
+    });
+}
+/** Methods that hand back another handle rather than doing work: their result is wrapped too. */
+const HANDLES = new Set(['get', 'getByName']);
+/** Methods that only build ids: left alone, since the runtime checks what it gets back. */
+const PLAIN = new Set(['idFromName', 'idFromString', 'newUniqueId']);
+const isNamespace = (v) => typeof v.idFromName === 'function';
+function meterObject(target, name, kind, stub) {
+    return new Proxy(target, {
+        get(t, prop, receiver) {
+            const v = Reflect.get(t, prop, receiver);
+            if (typeof prop !== 'string' || prop === 'then' || PLAIN.has(prop)) {
+                return typeof v === 'function' ? v.bind(t) : v;
+            }
+            // A stub's property is an RPC call whether or not it reads as a function.
+            if (typeof v !== 'function' && !stub)
+                return v;
+            const code = `${name}.${prop}`;
+            return (...args) => {
+                if (!stub && HANDLES.has(prop) && isNamespace(t)) {
+                    const handle = t[prop]?.(...args);
+                    return handle ? meterObject(handle, name, kind, true) : handle;
+                }
+                return timed(kind, code, () => t[prop]?.(...args));
+            };
+        },
+    });
+}
+/**
+ * The env with every object binding metered. Strings (vars) and skipped bindings pass through as
+ * they are. Wrap once per request at the entry and hand the result to the app.
+ */
+export function meteredBindings(env, opts = {}) {
+    const skip = new Set(opts.skip ?? []);
+    const cache = new Map();
+    return new Proxy(env, {
+        get(t, prop, receiver) {
+            const v = Reflect.get(t, prop, receiver);
+            if (typeof prop !== 'string' || !v || typeof v !== 'object' || skip.has(prop))
+                return v;
+            const hit = cache.get(prop);
+            if (hit)
+                return hit;
+            const keys = Object.keys(v);
+            const kind = opts.kinds?.[prop] ??
+                (isNamespace(v)
+                    ? 'do'
+                    : typeof v.fetch === 'function' && keys.length <= 1
+                        ? 'fetch'
+                        : prop.toLowerCase());
+            const wrapped = meterObject(v, prop, kind, false);
+            cache.set(prop, wrapped);
+            return wrapped;
+        },
+    });
+}
+let fetchPatched = false;
+/**
+ * Patches the global `fetch` once per isolate: every outbound request is a `fetch` call coded by
+ * its host (`fetch.api.example.com`), never its path or query.
+ */
+export function meterFetch() {
+    if (fetchPatched)
+        return;
+    fetchPatched = true;
+    const native = globalThis.fetch;
+    globalThis.fetch = ((input, init) => {
+        let host = 'other';
+        try {
+            host = new URL(input instanceof Request ? input.url : String(input)).hostname;
+        }
+        catch { }
+        return timed('fetch', `fetch.${host}`, () => native(input, init));
+    });
+}
+/**
+ * Writes one `call` event per call code the request in scope made (counts: calls, failed; ms:
+ * their total). The request meter's Hono middleware calls this itself after the answer.
+ */
+export function flushCalls() {
+    for (const [code, c] of requestCalls()) {
+        meterEvent({
+            event: 'call',
+            code,
+            ok: c.errors === 0,
+            ms: c.ms,
+            counts: [c.n, c.errors],
+            ref: c.kind,
+        });
+    }
+}

package/dist/hono.d.ts

@@ -7,8 +7,13 @@
 import type { Context, MiddlewareHandler } from 'hono';
 import { type RequestPoint } from './requests.js';
 export interface RequestMeterOptions {
-    /** The app, or the part of it, answering. */
-    app: string;
+    /** The app, or the part of it, answering; a function when one Worker serves several apps. */
+    app: string | ((c: Context) => string);
+    /** The route template, when Hono's own can't name it (a Worker that hands requests on to other
+     * apps by path sees only its catch-all); fold ids out of it with `foldRoute`. */
+    route?: (c: Context) => string | undefined;
+    /** Send the request's time per kind of call back as `Server-Timing` (do, ai, fetch, app, total). */
+    serverTiming?: boolean;
     env?: (c: Context) => string | undefined;
     version?: (c: Context) => string | undefined;
     /** Which part was asked and who called, read after the answer (auth has run by then). */

package/dist/hono.js

@@ -1,7 +1,8 @@
 import { routePath } from 'hono/route';
+import { flushCalls } from './bindings.js';
 import { codeOf } from './fields.js';
 import { foldRoute } from './queries.js';
-import { meterRequest, withRequest } from './requests.js';
+import { meterRequest, serverTiming, withRequest } from './requests.js';
 const newId = () => crypto.randomUUID().replace(/-/g, '').slice(0, 16);
 const size = (h) => (h ? Number(h) || 0 : 0);
 /** The `error` field of a JSON error answer under 4 KB, if it reads as a code. */
@@ -23,17 +24,31 @@ export function requestMeter(opts) {
     return async (c, next) => {
         const t0 = performance.now();
         const requestId = codeOf(c.var.requestId) || newId();
-        const scope = { app: opts.app, requestId, env: opts.env?.(c), version: opts.version?.(c) };
+        const app = typeof opts.app === 'function' ? opts.app(c) : opts.app;
+        const scope = { app, requestId, env: opts.env?.(c), version: opts.version?.(c) };
         await withRequest(scope, foldRoute(c.req.path), async () => {
             await next();
             try {
                 // The template of the deepest route that ran (Hono leaves its index set once the chain
                 // unwinds); `-1` would name the last route that merely matched, a catch-all say. A path
                 // only this middleware matched is `/*`, so junk never lands.
-                const route = routePath(c) || '*';
+                const hono = routePath(c);
+                const route = opts.route?.(c) || (hono && hono !== '*' && hono !== '/*' ? hono : '') || hono || '*';
                 const outcome = c.error
                     ? 'exception'
                     : await (opts.outcome ? opts.outcome(c) : errorCode(c));
+                const ms = performance.now() - t0;
+                if (opts.serverTiming && c.res.status !== 101) {
+                    try {
+                        c.res.headers.set('server-timing', serverTiming(ms));
+                    }
+                    catch {
+                        // A response with frozen headers (a passed-through fetch): copy it once.
+                        c.res = new Response(c.res.body, c.res);
+                        c.res.headers.set('server-timing', serverTiming(ms));
+                    }
+                }
+                flushCalls();
                 const cf = c.req.raw.cf;
                 meterRequest({
                     surface: 'other',
@@ -41,7 +56,7 @@ export function requestMeter(opts) {
                     method: c.req.method,
                     route,
                     status: c.res.status,
-                    ms: performance.now() - t0,
+                    ms,
                     outcome,
                     colo: cf?.colo,
                     country: cf?.country,

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from './bindings.js';
 export * from './events.js';
 export * from './points.js';
 export * from './queries.js';

package/dist/index.js

@@ -1,3 +1,4 @@
+export * from './bindings.js';
 export * from './events.js';
 export * from './points.js';
 export * from './queries.js';

package/dist/requests.d.ts

@@ -36,6 +36,12 @@ export interface RequestPoint {
     /** Defaults to the request in scope. */
     scope?: RequestScope;
 }
+/** What the request spent, per kind (`do`, `ai`, `fetch`) and per call (`DIRECTORY.seen`). */
+export interface CallTally {
+    n: number;
+    ms: number;
+    errors: number;
+}
 /** The entry point sets the dataset once per isolate; `log` also prints one JSON line a point. */
 export declare function setRequestSink(s: PointSink | undefined, opts?: {
     log?: boolean;
@@ -46,6 +52,22 @@ export declare function withRequest<T>(r: RequestScope, route: string, fn: () =>
 export declare function currentRequest(): RequestScope | undefined;
 /** Adds a call to another service to the request in scope (the event meter does this itself). */
 export declare function addUpstream(ms: number): void;
+/**
+ * Adds one binding or outbound call to the request in scope: its kind (`do`, `ai`, `vectorize`,
+ * `kv`, `fetch`) and its code (`DIRECTORY.seen`, `fetch.api.example.com`). The binding meter does
+ * this itself. Returns false when no request is in scope (an alarm, a job).
+ */
+export declare function addCall(kind: string, code: string, ms: number, ok: boolean): boolean;
+/** The calls of the request in scope, by code; empty outside a request. */
+export declare function requestCalls(): [string, CallTally & {
+    kind: string;
+}][];
+/**
+ * A `Server-Timing` header value for the request in scope: one entry per kind with its count, then
+ * `app` for the time outside them (`total` minus calls run one after another, so it can go to 0
+ * when calls ran side by side). Names and counts only, never a path or an id.
+ */
+export declare function serverTiming(totalMs: number): string;
 /** Prints the point as one JSON line for the platform's logs, when the sink was set with `log`. */
 export declare function logLine(kind: string, fields: Record<string, unknown>): void;
 /**

package/dist/requests.js

@@ -22,7 +22,7 @@ export function setRequestSink(s, opts = {}) {
 }
 /** Runs `fn` as request `r`: points written inside carry its id, and queries its route. */
 export function withRequest(r, route, fn) {
-    return scope.run({ ...r, upstreamMs: 0, subrequests: 0 }, () => withQueryCaller({ app: r.app, kind: 'fetch', route }, fn));
+    return scope.run({ ...r, upstreamMs: 0, subrequests: 0, kinds: new Map(), calls: new Map() }, () => withQueryCaller({ app: r.app, kind: 'fetch', route }, fn));
 }
 /** The request in scope, if any. */
 export function currentRequest() {
@@ -36,6 +36,52 @@ export function addUpstream(ms) {
     s.upstreamMs += ms;
     s.subrequests += 1;
 }
+/**
+ * Adds one binding or outbound call to the request in scope: its kind (`do`, `ai`, `vectorize`,
+ * `kv`, `fetch`) and its code (`DIRECTORY.seen`, `fetch.api.example.com`). The binding meter does
+ * this itself. Returns false when no request is in scope (an alarm, a job).
+ */
+export function addCall(kind, code, ms, ok) {
+    const s = scope.getStore();
+    if (!s)
+        return false;
+    s.upstreamMs += ms;
+    s.subrequests += 1;
+    const k = s.kinds.get(kind) ?? { n: 0, ms: 0, errors: 0 };
+    k.n += 1;
+    k.ms += ms;
+    if (!ok)
+        k.errors += 1;
+    s.kinds.set(kind, k);
+    const c = s.calls.get(code) ?? { kind, n: 0, ms: 0, errors: 0 };
+    c.n += 1;
+    c.ms += ms;
+    if (!ok)
+        c.errors += 1;
+    s.calls.set(code, c);
+    return true;
+}
+/** The calls of the request in scope, by code; empty outside a request. */
+export function requestCalls() {
+    return [...(scope.getStore()?.calls ?? new Map())];
+}
+/**
+ * A `Server-Timing` header value for the request in scope: one entry per kind with its count, then
+ * `app` for the time outside them (`total` minus calls run one after another, so it can go to 0
+ * when calls ran side by side). Names and counts only, never a path or an id.
+ */
+export function serverTiming(totalMs) {
+    const s = scope.getStore();
+    const parts = [];
+    let spent = 0;
+    for (const [kind, t] of s?.kinds ?? []) {
+        spent += t.ms;
+        parts.push(`${kind};dur=${t.ms.toFixed(1)};desc="${t.n}${t.errors ? ` ${t.errors} failed` : ''}"`);
+    }
+    parts.push(`app;dur=${Math.max(0, totalMs - spent).toFixed(1)}`);
+    parts.push(`total;dur=${totalMs.toFixed(1)}`);
+    return parts.join(', ');
+}
 /** Prints the point as one JSON line for the platform's logs, when the sink was set with `log`. */
 export function logLine(kind, fields) {
     if (!logLines)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@columenlabs/lumen-ops",
-  "version": "0.1.88",
+  "version": "0.1.89",
   "description": "Lumen's ops parts: every request, event, data query and tool call an app runs as one Analytics Engine point (templates, codes, shapes and hashes only), and signed webhooks out.",
   "license": "MIT",
   "type": "module",