feat: enhance error handling and metrics in MQTT application

- Update error handling tests to ensure validation errors propagate correctly with payloads.
- Introduce timeout and concurrency features in the router configuration to manage handler execution limits.
- Add metrics tracking for dispatch and publish events, capturing success and error states.
- Implement shared subscription parsing for MQTT 5, allowing for group and topic filter extraction.
- Add publish hook context to allow mutation of publish options before sending.
- Enhance TypeBox and Zod documentation to clarify usage and integration with AsyncAPI.

Author: keyp-dev

CHANGELOG.md

@@ -7,7 +7,53 @@ together stay readable.
 
 The format is loosely based on [Keep a Changelog](https://keepachangelog.com/).
 
-## 2026-06-22
+## 2026-06-22 — 0.2.1
+
+`@mqttkit/core@0.2.1`
+
+### Added — `@mqttkit/core` 0.2.1
+
+- **MQTT 5 shared subscriptions** (`$share/<group>/<filter>`).
+  `parseSharedSubscription()` follows §4.8.2; `canSubscribe()` strips the
+  prefix before route matching and exposes `shared.group` to the subscribe
+  policy. Lets you deploy multiple consumer instances behind one broker
+  without custom load-balancing.
+- **Per-route `timeout` and `concurrency`**. `topic({ timeout, concurrency })`
+  guards handler execution. Timeout surfaces as `phase: 'timeout'`; concurrency
+  rejection surfaces as `phase: 'overload'`. Inflight count is tracked on the
+  route for use by metrics and graceful shutdown.
+- **`app.onMetric(handler)`**. Emits a structured `MqttMetricEvent` once per
+  dispatch and once per publish — `{ type, topic, route?, durationMs, result,
+  errorPhase? }`. Designed to feed Prometheus / OpenTelemetry / statsd without
+  middleware around every route.
+- **Graceful shutdown**. `app.stop({ drain: true, timeout: 30_000 })` is now
+  the default behaviour: the dispatcher refuses new inbound dispatches, polls
+  every route's `inflight` count to zero (or until the timeout), then runs
+  `onStop` hooks, cancels in-flight RPC, and stops the broker adapter.
+  `app.activeCount()` reports the current sum of in-flight handlers for health
+  checks. Pass `{ drain: false }` for the legacy immediate shutdown.
+- **MQTT 5 user properties on `ctx`**. `ctx.userProperties` exposes inbound
+  `packet.properties.userProperties` as a flat read view, so middleware can
+  extract `traceparent`, correlation IDs, or any side-band metadata without
+  touching adapter-specific packet shape.
+- **Outbound publish hooks**. `app.onBeforePublish(hook)` runs immediately
+  before every outbound publish (both `app.publish()` and `ctx.publish()` /
+  `ctx.reply()` / `app.request()`, which all funnel through the same path).
+  Hooks receive a mutable `{ topic, payload, options }` view and can mutate
+  `options` — typical use is merging `traceparent` into
+  `options.properties.userProperties` so OTel context propagates across
+  brokers. A throw aborts the publish and surfaces through `onError` with
+  `phase: 'publish'`.
+- **Raw payload on `onError`**. `MqttErrorPayload.payload` carries the raw
+  buffer for inbound phases (`validation` / `policy` / `middleware` / `handler` /
+  `timeout` / `overload`) and the original `MqttPayload` for `publish`. Lets
+  exporters (Sentry, structured logs) capture the offending message body, not
+  just the topic.
+- **New docs pages** under the Production section: `Shared Subscriptions`,
+  `Handler Timeout & Concurrency`, `Metrics`, `Graceful Shutdown`,
+  `Tracing & User Properties` (with full OpenTelemetry wiring example).
+
+## 2026-06-22 — 0.2.0
 
 `@mqttkit/core@0.2.0`, `@mqttkit/aedes@0.2.0`, `@mqttkit/asyncapi@0.2.0`,
 `@mqttkit/typebox@0.1.0` (initial), `@mqttkit/zod@0.1.0` (initial).

README.md

@@ -14,6 +14,9 @@ Full documentation: **<https://mqttkit.keyp.dev>** ([简体中文](https://mqttk
 - `router().topic()` declares MQTT topic routes with publish / subscribe policies.
 - Topic params (`devices/:uid/events`), payload validation via any [Standard Schema](https://standardschema.dev/) validator, and injected services on `ctx`.
 - MQTT 5 RPC with `app.request()` and `ctx.reply()`.
+- MQTT 5 shared subscriptions (`$share/<group>/<filter>`) for multi-instance fan-out.
+- Per-route `timeout` and `concurrency` guards surface as `onError` phases.
+- `app.onMetric()` emits structured per-dispatch / per-publish events for Prometheus / OpenTelemetry.
 - `app.on()` observes broker lifecycle events; `app.publish()` lets workers push messages.
 - Adapters: `@mqttkit/aedes` (TCP + WebSocket) and `@mqttkit/asyncapi` (AsyncAPI 3.0 docs).
 - In-memory `TestBroker` for unit tests. Built for Bun and TypeScript.

README.zh-CN.md

@@ -14,6 +14,9 @@ mqttkit 不重新实现 MQTT 协议。CONNECT、SUBSCRIBE、PUBLISH、QoS、reta
 - `router().topic()` 声明 MQTT topic route 及发布 / 订阅策略。
 - topic 参数（`devices/:uid/events`），payload 校验支持任意 [Standard Schema](https://standardschema.dev/) 校验器，`ctx` 上可注入业务服务。
 - MQTT 5 RPC：`app.request()` + `ctx.reply()`。
+- MQTT 5 共享订阅（`$share/<group>/<filter>`），原生支持多实例扇出。
+- 路由级 `timeout` / `concurrency` 护栏，触发后通过 `onError` 阶段上报。
+- `app.onMetric()` 在每次 dispatch / publish 完成时发结构化事件，方便接 Prometheus / OpenTelemetry。
 - `app.on()` 监听 broker lifecycle events；`app.publish()` 让 worker 主动推送消息。
 - 适配器：`@mqttkit/aedes`（TCP + WebSocket）与 `@mqttkit/asyncapi`（AsyncAPI 3.0 文档）。
 - 内存版 `TestBroker` 用于单测。面向 Bun 与 TypeScript。