@segmentstream-cloud/app 0.17.0 → 0.17.1

package/README.md

@@ -698,6 +698,34 @@ Replace segmentstream.semantic with typed warehouse-backed entity aggregates. Se
   deployed with `@segmentstream-cloud/ontology` 0.17.0 or later. Requests that use none of
   them work as before.
 
+## Request timing
+
+Wrap app Route Handlers to add `Server-Timing: app;dur=…`, `x-request-id` and safe
+structured `app.request` runtime logs:
+
+```ts
+import { withRequestTiming } from "@segmentstream-cloud/app";
+
+export const GET = withRequestTiming(async (request: Request) => {
+  return Response.json({ ok: true });
+});
+```
+
+The wrapper passes handler arguments through and preserves response headers and
+streaming bodies. It logs duration, method, HTTP status and a generated request ID,
+excluding URLs, cookies, bodies and error details. Errors propagate unchanged.
+Next.js redirects and `notFound()` log their HTTP status and propagate unchanged;
+other Next.js control-flow exceptions log `status: null` because Next owns their eventual response.
+Those exceptions cannot receive timing headers here;
+return an explicit response when the wrapper needs to decorate its headers.
+Read these logs with `segmentstream logs --service app` (deployment permission required).
+Duration ends when the handler returns response headers; it excludes later stream
+work and browser rendering. It is opt-in for Route Handlers, not a page renderer
+or a web vitals collector. A Next.js proxy cannot time the downstream page render.
+
+Ontology SDK 0.31.2 adds request timing for ontology calls automatically. Timings
+are available in hosted logs; retained diagnostics are tracked in issue #520.
+
 ## Upgrading to 0.14
 
 - `segmentstream.ontology.aggregate()` accepts the measures of the model by their bare names, typed

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export declare function createSegmentStreamApp<O = unknown>(config: SegmentStrea
 export { NOT_INVITED, SIGN_IN_LINK_INVALID, SegmentStreamApiError } from "./errors.js";
 export { grants, isAllowed } from "./permissions.js";
 export { sql } from "./parameters.js";
+export { withRequestTiming } from "./request-timing.js";
 export type { AuthenticationMethod, SegmentStreamApp } from "./app.js";
 export { CONSENT_PAGE } from "./oauth.js";
 export { AGENT_CONNECT_HANDLER, AGENT_CONNECT_PAGE } from "./agent.js";

package/dist/index.js

@@ -19,6 +19,7 @@ export function createSegmentStreamApp(config) {
 export { NOT_INVITED, SIGN_IN_LINK_INVALID, SegmentStreamApiError } from "./errors.js";
 export { grants, isAllowed } from "./permissions.js";
 export { sql } from "./parameters.js";
+export { withRequestTiming } from "./request-timing.js";
 export { CONSENT_PAGE } from "./oauth.js";
 export { AGENT_CONNECT_HANDLER, AGENT_CONNECT_PAGE } from "./agent.js";
 export { createBlobStorageClient, } from "./storage.js";

package/dist/request-timing.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Time an app Route Handler until it returns response headers. Streaming/rendering after that
+ * point is excluded. Logs contain no URL, cookies, body or error text. Server Components need
+ * framework instrumentation for complete page timing; a Next.js proxy only times authentication.
+ */
+export declare function withRequestTiming<R extends Request, A extends unknown[]>(handler: (request: R, ...args: A) => Promise<Response>): (request: R, ...args: A) => Promise<Response>;

package/dist/request-timing.js

@@ -0,0 +1,53 @@
+import { unstable_rethrow } from "next/navigation";
+import { getRedirectStatusCodeFromError } from "next/dist/client/components/redirect.js";
+import { isRedirectError } from "next/dist/client/components/redirect-error.js";
+import { getAccessFallbackHTTPStatus, isHTTPAccessFallbackError, } from "next/dist/client/components/http-access-fallback/http-access-fallback.js";
+/**
+ * Time an app Route Handler until it returns response headers. Streaming/rendering after that
+ * point is excluded. Logs contain no URL, cookies, body or error text. Server Components need
+ * framework instrumentation for complete page timing; a Next.js proxy only times authentication.
+ */
+export function withRequestTiming(handler) {
+    return async (request, ...args) => {
+        const started = performance.now();
+        const requestId = crypto.randomUUID();
+        let status = 500;
+        let durationMs;
+        try {
+            const response = await handler(request, ...args);
+            const headers = new Headers(response.headers);
+            durationMs = Math.round((performance.now() - started) * 100) / 100;
+            status = response.status;
+            headers.append("server-timing", `app;dur=${durationMs}`);
+            headers.set("x-request-id", requestId);
+            return new Response(response.body, {
+                status,
+                statusText: response.statusText,
+                headers,
+            });
+        }
+        catch (error) {
+            try {
+                unstable_rethrow(error);
+            }
+            catch {
+                // Next owns the eventual response for control-flow exceptions, outside this wrapper.
+                status = isRedirectError(error)
+                    ? getRedirectStatusCodeFromError(error)
+                    : isHTTPAccessFallbackError(error)
+                        ? getAccessFallbackHTTPStatus(error)
+                        : null;
+            }
+            throw error;
+        }
+        finally {
+            console.info(JSON.stringify({
+                event: "app.request",
+                requestId,
+                method: request.method,
+                status,
+                durationMs: durationMs ?? Math.round((performance.now() - started) * 100) / 100,
+            }));
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/app",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "description": "Sign-in, users, permissions, the ontology client and warehouse data access for SegmentStream workspace apps built with Next.js.",
   "license": "Apache-2.0",
   "author": "SegmentStream",