@zeroxsolutions/server 0.6.8 → 0.7.0

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 0.7.0 (2026-11-10)
+
+### 🚀 Features
+
+- ⚠️ **server:** name the request's span by its route template ([e6b922d](https://github.com/zeroxsolutions/zeroxsolutions/commit/e6b922d))
+- **server:** write the fields a resolved error logs ([6a53f5d](https://github.com/zeroxsolutions/zeroxsolutions/commit/6a53f5d))
+
+### 🩹 Fixes
+
+- **server:** name the span's route where a middleware answered ([f3cc2ed](https://github.com/zeroxsolutions/zeroxsolutions/commit/f3cc2ed))
+
+### ⚠️ Breaking Changes
+
+- **server:** name the request's span by its route template ([e6b922d](https://github.com/zeroxsolutions/zeroxsolutions/commit/e6b922d))
+  hono peer floor is now ^4.8.0 (hono/route)
+
+### ❤️ Thank You
+
+- luongvantuit
+
 ## 0.6.8 (2026-10-23)
 
 This was a version bump only for @zeroxsolutions/server to align it with other projects, there were no code changes.

package/README.md

@@ -8,6 +8,7 @@ this one holds the handler that calls it. That split is what leaves the concern
 | ------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
 | `createEnvironment`                                                       | the worker's own `bindingsSchema` - no package owns a worker's bindings |
 | `createErrorHandler`, `createValidationHook`, `jsonApiContentNegotiation` | `@zeroxsolutions/response`, `@zeroxsolutions/jsonapi`                   |
+| `traceRequest`                                                            | the runtime's own span, passed as `activeSpan`                          |
 
 ## What the split bought
 
@@ -96,7 +97,8 @@ Whichever step answers, the handler writes one `http.error.answered` line under
 document goes out, at the level the answered status class decides: a 5xx at error, anything else at
 warn. The line carries the request id, the method, the path, the answered status, the step that claimed
 the failure (`query`, `request`, `resolve`, `auth`, `validation`, `jsonapi`, `status`) and the error's type
-and message. Without it a mapped 500 or a guard's 403 reaches the client with nothing in the log for an
+and message, then the `logged` fields of the error map entry that answered, if it names any; where a
+field name appears in both, the handler's own wins. Without it a mapped 500 or a guard's 403 reaches the client with nothing in the log for an
 operator to join it to.
 
 The `requestId` option's value becomes the `id` of each error object that carries none, so a client
@@ -138,6 +140,18 @@ does not serve stays a 404.
 app.notFound(jsonApiNotFound({ namespace: 'api', routes: app.routes }));
 ```
 
+## The request's span
+
+`traceRequest({ activeSpan })` names the request's server span after the answer exists:
+`<METHOD> <route template>`, with `http.route` set to the template. A 5xx answer sets `error.type` to its
+status and the span's status to error; a 4xx answer leaves the status unset. Where no route matched, the
+name is the method alone. `activeSpan` returns the runtime's span, or nothing, and then nothing is
+written. It needs hono 4.8.0 or later for `hono/route`.
+
+```ts
+app.use('*', traceRequest({ activeSpan: () => tracing.getActiveSpan() }));
+```
+
 ## Why a binder rather than a ready middleware
 
 The schema and the log category are the package's, not the library's: the schema is what the transport

package/dist/error-handler.js

@@ -53,7 +53,7 @@ function claimError(err, c, options) {
     }
     const resolved = options.resolve?.(err, c);
     if (resolved) {
-        return { claimedBy: 'resolve', resolved };
+        return { claimedBy: 'resolve', resolved, logged: resolved.logged };
     }
     if (err instanceof Unauthenticated) {
         const error = { status: '401', code: `${options.namespace}.unauthenticated`, title: 'Unauthenticated' };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 /**
- * Every Hono handler the house ships - the bindings gate, and the three the wire spelling decides.
+ * Every Hono handler the house ships - the bindings gate, the three the wire spelling decides, and the one
+ * that names a request's span.
  */
 export { createEnvironment, type EnvironmentOptions } from './environment.js';
 export type { SurfaceVocabulary } from './surface-vocabulary.js';
@@ -9,4 +10,5 @@ export { jsonApiNotFound, type NotFoundOptions } from './not-found.js';
 export { PermissionRefused } from './permission-refused.js';
 export { Unauthenticated } from './unauthenticated.js';
 export { createValidationHook } from './validation-hook.js';
+export { traceRequest, type RequestSpan, type TraceRequestOptions } from './trace-request.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC9E,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC5F,OAAO,EAAE,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC9E,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC5F,OAAO,EAAE,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -1,5 +1,6 @@
 /**
- * Every Hono handler the house ships - the bindings gate, and the three the wire spelling decides.
+ * Every Hono handler the house ships - the bindings gate, the three the wire spelling decides, and the one
+ * that names a request's span.
  */
 export { createEnvironment } from './environment.js';
 export { jsonApiContentNegotiation, NEGOTIATION_RESPONSES } from './content-negotiation.js';
@@ -8,3 +9,4 @@ export { jsonApiNotFound } from './not-found.js';
 export { PermissionRefused } from './permission-refused.js';
 export { Unauthenticated } from './unauthenticated.js';
 export { createValidationHook } from './validation-hook.js';
+export { traceRequest } from './trace-request.js';

package/dist/trace-request.d.ts

@@ -0,0 +1,27 @@
+import type { MiddlewareHandler } from 'hono';
+/** The part of a runtime's span {@link traceRequest} writes; Workers' span satisfies it. */
+export interface RequestSpan {
+    updateName(name: string): unknown;
+    setAttribute(key: string, value: string): unknown;
+    setStatus(status: {
+        code: 'error';
+    }): unknown;
+}
+/** What {@link traceRequest} is told about the runtime it traces for. */
+export interface TraceRequestOptions {
+    /** The request's server span, read after the answer; `undefined` or `null` where the runtime has none. */
+    readonly activeSpan: () => RequestSpan | undefined | null;
+}
+/**
+ * Middleware that names the request's span `<METHOD> <route template>` once the answer exists, sets
+ * `http.route` to the template, and marks a 5xx answer as an error with its status as `error.type`. A 4xx
+ * answer leaves the span's status unset. The name is the method alone, and
+ * `http.route` is not set, only where no route matched. It does nothing where `activeSpan` returns no span.
+ *
+ * Mount it before the routes, with `app.use('*', ...)`, so a refusal rendered by `onError` is the answer it reads.
+ * The template is the path in full, mount prefix included, of the route that answered, or of the route that
+ * would have answered after the middleware that refused or threw. A middleware (method `ALL`) is never the
+ * template, so a route registered with `app.all` is read as one and its span gets the method alone. Needs hono 4.8.0 or later for `hono/route`.
+ */
+export declare function traceRequest(options: TraceRequestOptions): MiddlewareHandler;
+//# sourceMappingURL=trace-request.d.ts.map

package/dist/trace-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-request.d.ts","sourceRoot":"","sources":["../src/trace-request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAI9C,4FAA4F;AAC5F,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAClD,SAAS,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC;CAC/C;AAED,yEAAyE;AACzE,MAAM,WAAW,mBAAmB;IAClC,0GAA0G;IAC1G,QAAQ,CAAC,UAAU,EAAE,MAAM,WAAW,GAAG,SAAS,GAAG,IAAI,CAAC;CAC3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,iBAAiB,CAe5E"}

package/dist/trace-request.js

@@ -0,0 +1,31 @@
+import { createMiddleware } from 'hono/factory';
+import { matchedRoutes } from 'hono/route';
+/**
+ * Middleware that names the request's span `<METHOD> <route template>` once the answer exists, sets
+ * `http.route` to the template, and marks a 5xx answer as an error with its status as `error.type`. A 4xx
+ * answer leaves the span's status unset. The name is the method alone, and
+ * `http.route` is not set, only where no route matched. It does nothing where `activeSpan` returns no span.
+ *
+ * Mount it before the routes, with `app.use('*', ...)`, so a refusal rendered by `onError` is the answer it reads.
+ * The template is the path in full, mount prefix included, of the route that answered, or of the route that
+ * would have answered after the middleware that refused or threw. A middleware (method `ALL`) is never the
+ * template, so a route registered with `app.all` is read as one and its span gets the method alone. Needs hono 4.8.0 or later for `hono/route`.
+ */
+export function traceRequest(options) {
+    return createMiddleware(async (c, next) => {
+        await next();
+        const span = options.activeSpan();
+        if (!span)
+            return;
+        const route = matchedRoutes(c)
+            .slice(c.req.routeIndex)
+            .find((matched) => matched.method !== 'ALL')?.path;
+        span.updateName(route ? `${c.req.method} ${route}` : c.req.method);
+        if (route)
+            span.setAttribute('http.route', route);
+        if (c.res.status >= 500) {
+            span.setAttribute('error.type', String(c.res.status));
+            span.setStatus({ code: 'error' });
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroxsolutions/server",
-  "version": "0.6.8",
+  "version": "0.7.0",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -21,14 +21,14 @@
   },
   "dependencies": {
     "tslib": "^2.3.0",
-    "@zeroxsolutions/jsonapi": "0.14.0",
+    "@zeroxsolutions/jsonapi": "0.14.1",
     "@zeroxsolutions/query": "0.7.5",
-    "@zeroxsolutions/response": "0.14.7"
+    "@zeroxsolutions/response": "0.14.8"
   },
   "peerDependencies": {
     "@hono/zod-openapi": "^1.0.0",
     "@logtape/logtape": "^2.0.0",
-    "hono": "^4.0.0",
+    "hono": "^4.8.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {