feat(observability): per-request performance timing → Server-Timing (perf-tuning mode)

[os-zhuang]

What

Adds opt-in per-request performance timing surfaced via the W3C Server-Timing response header — so a slow request's phase breakdown renders directly in the browser DevTools Network → Timing panel, no profiler attach required.

Server-Timing: total;dur=18.7;desc="Total server time", parse;dur=0.4;desc="Body parse", handler;dur=17.9;desc="Route handler"

Why opt-in ("perf-tuning mode")

The header discloses internal phase durations, which is great for profiling but also lets a caller fingerprint the backend. So it's off by default and treated as a toggle you flip in staging (or briefly in prod behind an allowlist), consistent with how OS_CORS_* / OS_MCP_* gate other adapter behaviour.

How

@objectstack/observability (new perf-timing.ts)

• PerfTiming — tiny, dependency-free per-request collector (record / start / measure).
• Ambient API over AsyncLocalStorage: runWithPerfTiming / currentPerfTiming, plus the no-op-when-disabled free functions measureServerTiming / startServerTiming / recordServerTiming, so any code on the request's async chain can add a phase without threading a request object through every layer.
• formatServerTiming serializes to the spec grammar, coercing names to tokens and stripping " / \ / control chars from descriptions (no header injection).

@objectstack/plugin-hono-server

• Outer middleware (registered before CORS) brackets the whole request as total and establishes the ambient collector.
• The HTTP adapter contributes parse (body parse) and handler (route handler) sub-phases into whatever collector is active — no-ops when the feature is off.
• Enable via new HonoServerPlugin({ serverTiming: true }) or OS_SERVER_TIMING=true (works through the default os serve, which constructs the plugin for you). Explicit option wins over the env var.

Enabling

new HonoServerPlugin({ serverTiming: true });

OS_SERVER_TIMING=true os serve

Tests

• 17 unit (perf-timing.test.ts): serializer formatting/rounding/token-sanitization/injection-stripping, PerfTiming record/start-idempotency/measure-on-throw, ambient propagation across await.
• 4 integration (server-timing.test.ts, real Hono adapter): header absent by default, present with total+handler when serverTiming: true, enabled via OS_SERVER_TIMING=true, and explicit serverTiming: false overrides the env var.
• Full suites green: observability 51/51, plugin-hono-server 44/44. turbo build (incl. tsup DTS) and root eslint clean.

Docs

New "Server-Timing (perf-tuning mode)" section + go-live checklist item in docs/OBSERVABILITY.md.

Risk

Default behaviour is unchanged — the header only appears when explicitly enabled, and all timing call sites are zero-overhead no-ops when disabled. No existing response-header assertions are affected.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jun 28, 2026 2:31am

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/observability, @objectstack/plugin-hono-server.

5 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/implementation-status.mdx (via @objectstack/observability, @objectstack/plugin-hono-server)
• content/docs/concepts/packages.mdx (via @objectstack/plugin-hono-server)
• content/docs/guides/authentication.mdx (via @objectstack/plugin-hono-server)
• content/docs/guides/packages.mdx (via @objectstack/plugin-hono-server)
• content/docs/guides/plugins.mdx (via @objectstack/plugin-hono-server)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.