@wtfalch/reporting 0.8.1 → 0.9.0

package/README.md

@@ -232,6 +232,33 @@ wrong token, 503 when the variable is unset. It answers `from` and `to` (ISO,
 per color and the per-day average of the 7 days before `from`. Counts only; no
 event content. Rows of `reporting_requests` are not pruned.
 
+### Count every request (0.9.0)
+
+`withRequestCount` counts one route handler. To count every request with no
+change per route, add one line to `proxy.ts` and one to `instrumentation.ts`:
+
+```ts
+// src/proxy.ts: wrap the proxy function you already export
+import { countRequests } from '@wtfalch/reporting/next';
+export const proxy = countRequests(reporting, async (request) => { /* as before */ });
+
+// src/instrumentation.ts: pass the handler you already export (Sentry's, say) as the second argument
+import { countRequestErrors } from '@wtfalch/reporting/next';
+export const onRequestError = countRequestErrors(reporting, Sentry.captureRequestError);
+```
+
+The proxy counts each request it sees with the status it answers with (a
+redirect or a 403 is a request; its own throw is a 500). A request it passes
+through is counted as a request there, and a page, route handler or Server
+Action that then throws reaches `onRequestError`, which adds the 5xx. A route
+handler that returns a 500 without throwing is not seen; use `withRequestCount`
+there. `/api/health` and `/api/reporting/release-health` are not counted
+(`skipPaths` replaces that list). Do not wrap a route in `withRequestCount`
+when the proxy matcher covers it: it would be counted twice. In Next 16
+`proxy.ts` runs on the Node runtime only, which is where the in-memory counter
+and its Postgres flush work; on the Edge runtime both functions count nothing.
+A counting failure is logged and never fails the request.
+
 ## Shutdown
 
 ```ts

package/dist/index.js

@@ -103,7 +103,10 @@ export function createReporting(options) {
             await writer.flush(opts);
             await requests.flush();
         },
-        requests: { record: (status) => requests.record(status) },
+        requests: {
+            record: (status) => requests.record(status),
+            recordError: () => requests.recordError(),
+        },
         events: { page: (opts) => eventsPage(options.db, opts) },
         settings: {
             get: () => getSettings(options.db),

package/dist/next/count.d.ts

@@ -0,0 +1,49 @@
+import type { Reporting } from '../types.js';
+/**
+ * Counting for every request, with no change per route. Two halves, because
+ * Next gives each half only part of the picture:
+ *
+ * - `countRequests` wraps the app's `proxy.ts` function. It runs on every
+ *   matched request before the page or route, so it counts the request. It
+ *   sees the status the proxy itself answers with (a redirect, a 403, a 500
+ *   from its own throw); a request it lets through is a pass-through there,
+ *   and the page's real status is not known yet.
+ * - `countRequestErrors` is `onRequestError` in `instrumentation.ts`. Next calls
+ *   it for each error a page, route handler or Server Action throws, which is
+ *   the 5xx; it adds an error to a request the proxy already counted.
+ *
+ * Runtime: in Next 16 `proxy.ts` runs on the Node runtime only (Edge is not
+ * supported there), and `onRequestError` runs in whichever runtime threw. The
+ * counter is an in-memory map flushed to Postgres, so it works in Node. In an
+ * Edge runtime the call is skipped (see `isEdge`): an Edge instance has no
+ * database and its own memory, so a count there would never be written.
+ *
+ * Do not also wrap a route in `withRequestCount` when the proxy matcher
+ * covers it: the request would be counted twice, and a throw as two errors.
+ * `withRequestCount` stays for a path the proxy matcher excludes.
+ *
+ * Neither function ever fails a request: a counting error is logged.
+ */
+/** The probe and the release-health read are not traffic; counting them would swamp the signal. */
+export declare const DEFAULT_UNCOUNTED_PATHS: readonly string[];
+export interface CountOptions {
+    /** Paths (exact, or a prefix followed by `/`) that are not counted. Replaces the default list. */
+    readonly skipPaths?: readonly string[];
+}
+/**
+ * Wraps the app's proxy function: `export const proxy = countRequests(reporting, handler)`.
+ * Counts the status the proxy answers with; a throw counts as a 500 and goes on.
+ */
+export declare function countRequests<A extends {
+    url: string;
+}, R extends {
+    status: number;
+} | undefined>(reporting: Pick<Reporting, 'requests' | 'log'>, handler: (request: A) => Promise<R> | R, options?: CountOptions): (request: A) => Promise<R>;
+type RequestErrorArgs = Parameters<import('./index.js').NextOnRequestError>;
+/**
+ * `export const onRequestError = countRequestErrors(reporting)`. Pass the
+ * handler you already export (Sentry's, `errorHandler(reporting)`) as `next`
+ * and it still runs, after the count and whatever the count does.
+ */
+export declare function countRequestErrors(reporting: Pick<Reporting, 'requests' | 'log'>, next?: (...args: RequestErrorArgs) => void | Promise<void>, options?: CountOptions): (...args: RequestErrorArgs) => void | Promise<void>;
+export {};

package/dist/next/count.js

@@ -0,0 +1,100 @@
+/**
+ * Counting for every request, with no change per route. Two halves, because
+ * Next gives each half only part of the picture:
+ *
+ * - `countRequests` wraps the app's `proxy.ts` function. It runs on every
+ *   matched request before the page or route, so it counts the request. It
+ *   sees the status the proxy itself answers with (a redirect, a 403, a 500
+ *   from its own throw); a request it lets through is a pass-through there,
+ *   and the page's real status is not known yet.
+ * - `countRequestErrors` is `onRequestError` in `instrumentation.ts`. Next calls
+ *   it for each error a page, route handler or Server Action throws, which is
+ *   the 5xx; it adds an error to a request the proxy already counted.
+ *
+ * Runtime: in Next 16 `proxy.ts` runs on the Node runtime only (Edge is not
+ * supported there), and `onRequestError` runs in whichever runtime threw. The
+ * counter is an in-memory map flushed to Postgres, so it works in Node. In an
+ * Edge runtime the call is skipped (see `isEdge`): an Edge instance has no
+ * database and its own memory, so a count there would never be written.
+ *
+ * Do not also wrap a route in `withRequestCount` when the proxy matcher
+ * covers it: the request would be counted twice, and a throw as two errors.
+ * `withRequestCount` stays for a path the proxy matcher excludes.
+ *
+ * Neither function ever fails a request: a counting error is logged.
+ */
+/** The probe and the release-health read are not traffic; counting them would swamp the signal. */
+export const DEFAULT_UNCOUNTED_PATHS = [
+    '/api/health',
+    '/api/reporting/release-health',
+];
+const isEdge = () => process.env.NEXT_RUNTIME === 'edge';
+function isSkipped(pathname, skip) {
+    return skip.some((p) => pathname === p || pathname.startsWith(`${p}/`));
+}
+function pathnameOf(url) {
+    try {
+        return new URL(url).pathname;
+    }
+    catch {
+        // A request path (`/x?y=1`) rather than a full URL, as onRequestError hands over.
+        return url.split('?')[0] ?? url;
+    }
+}
+function safely(reporting, what, fn) {
+    try {
+        fn();
+    }
+    catch (error) {
+        try {
+            reporting.log.error({ err: error instanceof Error ? error.name : 'unknown' }, `reporting: ${what} failed`);
+        }
+        catch (logError) {
+            // The logger itself threw; counting must still never fail a request.
+            console.error(`reporting: ${what} failed and so did the logger`, logError);
+        }
+    }
+}
+/**
+ * Wraps the app's proxy function: `export const proxy = countRequests(reporting, handler)`.
+ * Counts the status the proxy answers with; a throw counts as a 500 and goes on.
+ */
+export function countRequests(reporting, handler, options = {}) {
+    const skip = options.skipPaths ?? DEFAULT_UNCOUNTED_PATHS;
+    const count = (request, status) => safely(reporting, 'request count', () => {
+        if (isEdge() || isSkipped(pathnameOf(request.url), skip))
+            return;
+        reporting.requests.record(status);
+    });
+    return async (request) => {
+        let response;
+        try {
+            response = await handler(request);
+        }
+        catch (error) {
+            count(request, 500);
+            throw error;
+        }
+        count(request, response?.status ?? 200);
+        return response;
+    };
+}
+/**
+ * `export const onRequestError = countRequestErrors(reporting)`. Pass the
+ * handler you already export (Sentry's, `errorHandler(reporting)`) as `next`
+ * and it still runs, after the count and whatever the count does.
+ */
+export function countRequestErrors(reporting, next, options = {}) {
+    const skip = options.skipPaths ?? DEFAULT_UNCOUNTED_PATHS;
+    return (...args) => {
+        safely(reporting, 'request error count', () => {
+            // A throw in the proxy is already counted by `countRequests` as a 500; Next also reports it here.
+            if (args[2].routeType === 'proxy')
+                return;
+            if (isEdge() || isSkipped(pathnameOf(args[1].path), skip))
+                return;
+            reporting.requests.recordError();
+        });
+        return next?.(...args);
+    };
+}

package/dist/next/index.d.ts

@@ -4,6 +4,7 @@ import type { Reporting } from '../types.js';
 import { type ClientErrorCollectorOptions } from './client-errors.js';
 import { type EdgeErrorIngestOptions } from './edge-errors.js';
 export { releaseHealthHandler, withRequestCount, type ReleaseHealthOptions, } from './release-health.js';
+export { countRequestErrors, countRequests, DEFAULT_UNCOUNTED_PATHS, type CountOptions, } from './count.js';
 export { edgeErrorHandler, type EdgeCaptureOptions, type EdgeErrorReport } from './edge-errors.js';
 /**
  * The Next bindings: everything in the package that knows what a request is.

package/dist/next/index.js

@@ -7,6 +7,7 @@ import { countryOf, deviceOf } from '../analytics/schema.js';
 import { createClientErrorCollector } from './client-errors.js';
 import { createEdgeErrorIngestCollector } from './edge-errors.js';
 export { releaseHealthHandler, withRequestCount, } from './release-health.js';
+export { countRequestErrors, countRequests, DEFAULT_UNCOUNTED_PATHS, } from './count.js';
 export { edgeErrorHandler } from './edge-errors.js';
 /**
  * The Next bindings: everything in the package that knows what a request is.

package/dist/next/release-health.d.ts

@@ -19,4 +19,6 @@ export declare function releaseHealthHandler(options: ReleaseHealthOptions): (re
  * (`redirect()`, `notFound()` and the like) are counted as a request, not an
  * error, so they cannot push a release toward rollback.
  */
-export declare function withRequestCount<A extends unknown[]>(reporting: Pick<Reporting, 'requests'>, handler: (...args: A) => Promise<Response> | Response): (...args: A) => Promise<Response>;
+export declare function withRequestCount<A extends unknown[]>(reporting: {
+    requests: Pick<Reporting['requests'], 'record'>;
+}, handler: (...args: A) => Promise<Response> | Response): (...args: A) => Promise<Response>;

package/dist/requests.d.ts

@@ -17,6 +17,13 @@ export declare class RequestCounter {
     private readonly buckets;
     private timer;
     constructor(o: RequestCounterOptions);
+    /** Counts one response. */
     record(status: number): void;
+    /**
+     * Counts one 5xx for a request already counted by `record`, such as a page
+     * that threw after the proxy let it through. Adds no request.
+     */
+    recordError(): void;
+    private add;
     flush(): Promise<void>;
 }

package/dist/requests.js

@@ -14,12 +14,22 @@ export class RequestCounter {
     constructor(o) {
         this.o = o;
     }
+    /** Counts one response. */
     record(status) {
+        this.add(status >= 500 ? 1 : 0, 1);
+    }
+    /**
+     * Counts one 5xx for a request already counted by `record`, such as a page
+     * that threw after the proxy let it through. Adds no request.
+     */
+    recordError() {
+        this.add(1, 0);
+    }
+    add(errors, requests) {
         const minute = Math.floor(this.o.now().getTime() / 60_000) * 60_000;
         const b = this.buckets.get(minute) ?? { requests: 0, errors: 0 };
-        b.requests += 1;
-        if (status >= 500)
-            b.errors += 1;
+        b.requests += requests;
+        b.errors += errors;
         this.buckets.set(minute, b);
         if (!this.timer) {
             this.timer = setTimeout(() => {

package/dist/types.d.ts

@@ -203,6 +203,7 @@ export interface Reporting {
     /** Counts one response for the release-health read; `flush` writes the counts. Never throws. */
     readonly requests: {
         record(status: number): void;
+        recordError(): void;
     };
     stats(): Stats;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/reporting",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "The estate's operational event log and housekeeping tick: a writer that never fails a request, a claim protocol that needs no scheduler, and the readers an operator opens. Per-app Postgres, host-supplied logger, framework-neutral core with a Next entry.",
   "repository": {
     "type": "git",