@sirena-lwm2m/coap 0.8.0

package/docs/blockwise.md

@@ -0,0 +1,117 @@
+# Block-wise transfers — RFC 7959
+
+Block-wise transfers let CoAP exchange payloads larger than a single UDP datagram. The `blockwiseMiddleware` handles all fragmentation and reassembly transparently: route handlers see a normal `req.body` stream and call `ctx.respond()` once, regardless of whether the payload is 10 bytes or 10 megabytes.
+
+## Overview
+
+```
+handler registration:          router.use(blockwiseMiddleware());
+
+PUT /firmware handler:         receives the fully-assembled body, responds 2.04
+GET /manifest handler:         returns a Buffer, chunked automatically by Block2
+```
+
+The middleware intercepts CoAP `Block1` (upload) and `Block2` (download) option headers and manages the multi-round-trip exchange before the application handler is ever called.
+
+## Block size
+
+| Parameter | Value |
+|---|---|
+| Default block size | 512 bytes (SZX=5) |
+| Hard cap | 1 024 bytes (SZX=6) |
+| Client-negotiated | Honored if ≤ hard cap; larger client SZX silently capped to 1 024 |
+
+The block size is selected by the client. If the client requests SZX=6 (1 024 bytes), the server uses 1 024-byte blocks. If the client requests SZX=3 (128 bytes), the server uses 128-byte blocks.
+
+## `ctx.continue()`
+
+For Block1 uploads the middleware calls `ctx.continue()` automatically for each non-final chunk. You do **not** need to call it yourself. Understanding what it does is useful for debugging:
+
+```
+ctx.continue() ──► sends CoAP 2.31 Continue (ACK with code 2.31)
+                   echoing the Block1 option back to the client
+```
+
+If you need to implement your own block-wise logic (e.g., partial validation mid-stream), you can call `ctx.continue()` yourself from a middleware positioned before `blockwiseMiddleware`:
+
+```ts
+// Example: log progress without blocking the transfer
+router.use(async (req, ctx, next) => {
+  const block1 = ctx.options.find(o => o.number === 27);
+  if (block1) {
+    console.log('block received, num=…');
+  }
+  return next();
+});
+
+router.use(blockwiseMiddleware());
+```
+
+## Cancellation
+
+A block transfer can be abandoned in three ways:
+
+| Mechanism | Who triggers it | Effect |
+|---|---|---|
+| Idle timeout | Server (automatic) | Aborts assembler/chunker after 60 s of silence; emits `'block-transfer-aborted'` |
+| `ctx.cancel()` | Route handler | Sends CoAP RST to the peer and frees state |
+| Client RST | Client | Transport closes the exchange; middleware cleans up on next request |
+
+The idle timeout default (60 s) can be changed:
+
+```ts
+router.use(blockwiseMiddleware({ idleTimeoutMs: 10_000 })); // 10 s
+```
+
+## Size cap
+
+The default maximum assembled body size is **16 MiB**. Exceeding it causes the middleware to respond `4.13 Request Entity Too Large` and abort the transfer.
+
+```ts
+router.use(blockwiseMiddleware({ maxBytes: 4 * 1024 * 1024 })); // 4 MiB cap
+```
+
+## Events
+
+Both `Block1Assembler` and `Block2Chunker` extend `EventEmitter` and emit:
+
+| Event | Payload | When |
+|---|---|---|
+| `'block-transfer-complete'` | — | Final block processed successfully |
+| `'block-transfer-aborted'` | `{ reason: string }` | Transfer abandoned (timeout, too-large, out-of-order, explicit) |
+
+The middleware removes assemblers/chunkers from its internal maps on both events, so memory is released promptly.
+
+## Example
+
+See [`examples/slice-5-firmware.ts`](../examples/slice-5-firmware.ts) for a full working demo:
+
+```ts
+import { createServer } from '@sirena-lwm2m/coap';
+import { createApp } from '@sirena-lwm2m/coap/router';
+import { blockwiseMiddleware } from '@sirena-lwm2m/coap/blockwise';
+
+const server = createServer({ listen: [{ host: '127.0.0.1', port: 5685 }] });
+const router = createApp({ server });
+
+router.use(blockwiseMiddleware());
+
+router.add({
+  path: '/firmware',
+  method: 'PUT',
+  handler: async (req, ctx) => {
+    // req.body is a fully-assembled ReadableStream regardless of payload size
+    let bytes = 0;
+    const reader = req.body!.getReader();
+    for (let r = await reader.read(); !r.done; r = await reader.read()) {
+      bytes += r.value.length;
+    }
+    console.log(`firmware bytes received: ${bytes}`);
+    await ctx.respond(new Response(stringToCode('2.04')));
+  },
+});
+
+await server.start();
+```
+
+The example also includes a self-test client that uploads an 8 MiB firmware image via Block1 and retrieves a manifest via Block2, asserting both transfers succeed.

package/docs/observability.md

@@ -0,0 +1,206 @@
+# Observability — @sirena-lwm2m/coap
+
+The library emits OpenTelemetry metrics with zero cost when the `@opentelemetry/api` package is absent. No OTel SDK dependency is bundled; metrics are wired up lazily at runtime.
+
+## Import path
+
+```ts
+import { bindOtel, tryBindOtel, createNoopMetrics } from '@sirena-lwm2m/coap/observability';
+import type { CoapMetrics, Counter, UpDownCounter, Histogram } from '@sirena-lwm2m/coap/observability';
+```
+
+---
+
+## Available instruments
+
+All instruments use the `coap.*` namespace per the OpenTelemetry semantic conventions draft for CoAP.
+
+| Instrument | Type | Unit | Description |
+|---|---|---|---|
+| `coap.requests` | Counter | `{request}` | Incremented on every incoming request (CON or NON). |
+| `coap.exchanges.active` | UpDownCounter | `{exchange}` | Number of currently in-flight exchanges (running + queued handlers). |
+| `coap.observe.registrations` | UpDownCounter | `{registration}` | Number of active Observe registrations. |
+| `coap.block.complete` | Counter | `{transfer}` | Number of block-wise transfers that completed successfully. |
+| `coap.block.aborted` | Counter | `{transfer}` | Number of block-wise transfers that were aborted (timeout, size cap, out-of-order). |
+| `coap.dedup.hits` | Counter | `{hit}` | Number of CON retransmissions served from the dedup store. |
+| `coap.transport.errors` | Counter | `{error}` | Number of transport-level errors (decode failures, socket errors). |
+
+---
+
+## `CoapMetrics`
+
+```ts
+interface CoapMetrics {
+  requestRate:           Counter;
+  activeExchanges:       UpDownCounter;
+  observeRegistrations:  UpDownCounter;
+  blockTransferComplete: Counter;
+  blockTransferAborted:  Counter;
+  dedupHits:             Counter;
+  transportErrors:       Counter;
+}
+```
+
+Pass a `CoapMetrics` instance to `createServer()` via `ServerOptions.metrics`:
+
+```ts
+const server = createServer({
+  listen: [{ host: '0.0.0.0', port: 5683 }],
+  metrics: myMetrics,
+});
+```
+
+When `metrics` is omitted the server uses no-op implementations automatically — no null checks needed anywhere in your code.
+
+---
+
+## Instrument types
+
+```ts
+interface Counter {
+  add(value: number, attributes?: Record<string, string | number | boolean>): void;
+}
+
+interface UpDownCounter {
+  add(value: number, attributes?: Record<string, string | number | boolean>): void;
+}
+
+interface Histogram {
+  record(value: number, attributes?: Record<string, string | number | boolean>): void;
+}
+```
+
+These are intentionally a minimal subset of `@opentelemetry/api` — any OTel-compliant SDK will satisfy them. The library never imports from `@opentelemetry/api` at module load time.
+
+---
+
+## Setup options
+
+### Option A — caller supplies the Meter (`bindOtel`)
+
+Use this when your application already bootstraps an OTel SDK and has a `Meter` instance:
+
+```ts
+import { bindOtel } from '@sirena-lwm2m/coap/observability';
+
+// Obtain a Meter from your OTel SDK setup
+const meter = otelSdk.getMeter('my-coap-service');
+
+const metrics = bindOtel(meter);
+
+const server = createServer({
+  listen: [{ host: '0.0.0.0', port: 5683 }],
+  metrics,
+});
+```
+
+`bindOtel` is synchronous. It calls the standard OTel Meter factory methods and returns a `CoapMetrics` object wired to the provided `Meter`.
+
+### Option B — auto-detect OTel (`tryBindOtel`)
+
+Use this when you want metrics if the SDK is present, but zero-cost no-ops otherwise:
+
+```ts
+import { tryBindOtel } from '@sirena-lwm2m/coap/observability';
+
+const metrics = await tryBindOtel('my-coap-service');
+
+const server = createServer({
+  listen: [{ host: '0.0.0.0', port: 5683 }],
+  metrics,
+});
+```
+
+`tryBindOtel` dynamically imports `@opentelemetry/api`. If the package is not installed it silently returns no-op metrics. The `meterName` parameter is passed to `api.metrics.getMeter()`.
+
+### Option C — explicit no-ops (`createNoopMetrics`)
+
+Use this in tests or when you want to be explicit that metrics are disabled:
+
+```ts
+import { createNoopMetrics } from '@sirena-lwm2m/coap/observability';
+
+const server = createServer({
+  listen: [{ host: '0.0.0.0', port: 5683 }],
+  metrics: createNoopMetrics(),
+});
+```
+
+---
+
+## Full example with `@opentelemetry/sdk-node`
+
+```ts
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
+import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
+import { createServer, Response, stringToBytes } from '@sirena-lwm2m/coap';
+import { bindOtel } from '@sirena-lwm2m/coap/observability';
+import { metrics } from '@opentelemetry/api';
+
+// 1. Bootstrap OTel SDK
+const sdk = new NodeSDK({
+  metricReader: new PeriodicExportingMetricReader({
+    exporter: new OTLPMetricExporter({
+      url: 'http://localhost:4318/v1/metrics',
+    }),
+    exportIntervalMillis: 10_000,
+  }),
+});
+sdk.start();
+
+// 2. Bind metrics to the CoAP server
+const meter = metrics.getMeter('my-coap-service', '0.7.0');
+const coapMetrics = bindOtel(meter);
+
+const server = createServer({
+  listen: [{ host: '0.0.0.0', port: 5683 }],
+  metrics: coapMetrics,
+});
+
+server.on('request', async (req, ctx) => {
+  await ctx.respond(Response.ok(stringToBytes('hello')));
+});
+
+await server.start();
+
+// 3. Graceful shutdown
+process.on('SIGTERM', async () => {
+  await server.stop();
+  await sdk.shutdown();
+});
+```
+
+### Required packages
+
+```bash
+npm install @opentelemetry/sdk-node \
+            @opentelemetry/sdk-metrics \
+            @opentelemetry/exporter-metrics-otlp-http \
+            @opentelemetry/api
+```
+
+`@opentelemetry/api` is declared as an optional peer dependency in `@sirena-lwm2m/coap`. Install it explicitly alongside the SDK.
+
+---
+
+## Peer dependency
+
+```json
+"peerDependencies": {
+  "@opentelemetry/api": "*"
+},
+"peerDependenciesMeta": {
+  "@opentelemetry/api": {
+    "optional": true
+  }
+}
+```
+
+The library is tested against all current major versions of `@opentelemetry/api` (1.x). No other OTel package is required at runtime.
+
+---
+
+## Zero-cost guarantee
+
+When neither `bindOtel` nor `tryBindOtel` is called, the server uses `createNoopMetrics()` internally. No-op methods are empty arrow functions — they compile to a single unconditional branch prediction miss at most. There is no dynamic dispatch, no weak-ref check, and no import of `@opentelemetry/api` at module load time.

package/docs/observe.md

@@ -0,0 +1,203 @@
+# Observe — RFC 7641
+
+The Observe extension lets a CoAP server push notifications to a registered client whenever a resource changes, replacing polling with a reactive push model. The library implements the full RFC 7641 lifecycle: registration, notification delivery with CON/ACK flow control, conflation, block-wise chunking for large payloads, and RST-triggered or explicit cancellation.
+
+## Overview
+
+```
+client                              server
+  |                                   |
+  |--- GET /temperature + Observe:0 ->|  register
+  |<-- 2.05 Content + Observe:0 ------|  initial response (seq 0)
+  |                                   |
+  |<-- CON 2.05 + Observe:1 ---------|  notification seq 1
+  |--- ACK ----------------------->|  |
+  |<-- CON 2.05 + Observe:2 ---------|  notification seq 2
+  |--- ACK ----------------------->|  |
+  |                                   |
+  |--- GET /temperature + Observe:1 ->|  deregister
+  |<-- 2.05 Content ------------------|  final response (no Observe option)
+```
+
+## `ctx.observe()`
+
+```ts
+ctx.observe(observable: Observable<unknown>, opts?: ObserveOptions): void
+```
+
+Called from a route handler (or the `server.on('request', …)` listener) to attach an `Observable` to the current exchange. The server will subscribe to it and deliver each emitted value as a CON notification to the registered client.
+
+- Only takes effect when the incoming request carries `Observe: 0` (a registration request). Calling it on a plain GET is a no-op.
+- Must be called after `ctx.respond()` returns so the initial 2.05 response is sent first.
+- Ownership of the subscription is held by the server; the application does not manage the lifecycle.
+
+```ts
+router.add({
+  path: '/temperature',
+  method: 'GET',
+  handler: async (_req, ctx) => {
+    await ctx.respond(Response.ok(encodeTemperature(currentTemp)));
+    ctx.observe(temperatureObservable);
+  },
+});
+```
+
+### ObserveOptions
+
+```ts
+interface ObserveOptions {
+  notifyEveryValue?: boolean;
+}
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `notifyEveryValue` | `false` | When `false`, conflation is enabled (see below). When `true`, every emitted value is delivered as a separate notification, even if a previous CON is still awaiting ACK. |
+
+## Types
+
+### `Observable<T>`
+
+```ts
+interface Observable<T> {
+  subscribe(observer: Observer<T>): Unsubscribe;
+}
+```
+
+Any object with a `subscribe` method that matches this shape can be passed to `ctx.observe()`. This is intentionally compatible with RxJS `Observable` and the TC39 Observable proposal, but the library has no runtime dependency on either.
+
+### `Observer<T>`
+
+```ts
+interface Observer<T> {
+  next(value: T): void;
+  error?(err: unknown): void;
+  complete?(): void;
+}
+```
+
+The server creates an observer internally and subscribes to the provided observable. Calling `complete()` or `error()` on the subject tears down the registration cleanly.
+
+### `Unsubscribe`
+
+```ts
+type Unsubscribe = () => void;
+```
+
+The return value of `Observable.subscribe()`. The server calls this when the registration is cancelled to release resources.
+
+## Conflation
+
+When `notifyEveryValue` is `false` (the default), the notification loop uses conflation to avoid unbounded queuing under fast sources:
+
+- Each notification is sent as a CON message. The loop waits for an ACK before sending the next one.
+- If the observable emits while the previous CON is still awaiting ACK, the new value is held in a single-slot queue, replacing any earlier queued value.
+- When the ACK arrives, the queued value (if any) is sent immediately.
+
+This means a slow client never receives more packets than it ACKs, and a fast source never causes unbounded memory growth — only the latest value is retained.
+
+```
+observable: ─── v1 ─── v2 ─── v3 ─── v4 ───
+                                              (v1 in-flight waiting for ACK)
+delivered:  ─── v1 ─────────────── v4 ───    (v2, v3 conflated away)
+```
+
+Set `notifyEveryValue: true` to disable conflation and deliver every value regardless of ACK state. Use this only when every intermediate value is meaningful (e.g., event logs, counters).
+
+## Sequence numbers
+
+Each notification carries a 24-bit Observe sequence number (RFC 7641 §4.4):
+
+- The initial 2.05 registration response carries sequence number `0`.
+- Subsequent notifications carry `1`, `2`, …, wrapping at `0xFFFFFF` back to `0`.
+- Clients use the sequence number to detect out-of-order delivery and discard stale notifications.
+
+The library manages sequence numbers automatically; applications do not need to handle them.
+
+## Cancellation triggers
+
+A registration is cancelled when any of the following occurs:
+
+| Trigger | Description |
+|---|---|
+| Client sends `GET + Observe:1` | Explicit deregistration per RFC 7641 §3.6 |
+| Client sends a plain `GET` (no Observe option) | Implicit deregistration per RFC 7641 §3.6 |
+| Client sends RST to a CON notification | RST-triggered cancellation per RFC 7641 §4.2 |
+| `Observable` calls `complete()` or `error()` | Application-driven teardown |
+
+On cancellation the server unsubscribes from the observable and emits `'observe-cancelled'` on the server event emitter. Memory is released immediately.
+
+## Server events
+
+```ts
+server.on('observe-registered', (reg: ObserveRegistration) => { … });
+server.on('observe-cancelled', (reg: ObserveRegistration) => { … });
+```
+
+```ts
+interface ObserveRegistration {
+  remote: string;       // peer address, e.g. "127.0.0.1:12345"
+  token: Uint8Array;    // CoAP token identifying the registration
+}
+```
+
+## Block-wise notifications
+
+When a notification payload exceeds the negotiated block size (default 1 024 bytes), the server chunks it automatically using `Block2`. The client receives the full payload across multiple CON/ACK round-trips.
+
+The block size is negotiated from the `Block2` option the client sends with its registration GET:
+- If the client includes `Block2: NUM=0, SZX=N`, the server uses block size `2^(N+4)` (capped at 1 024 bytes).
+- If the client sends no `Block2` option, the server defaults to 1 024-byte blocks.
+
+Each block in a block-wise notification carries the same Observe sequence number, so the client can correlate blocks to the same notification event.
+
+Applications do not need to do anything special to enable block-wise notifications — passing a large payload via `Observable.next()` is sufficient.
+
+## Example
+
+See [`examples/slice-6-temperature.ts`](../examples/slice-6-temperature.ts) for a complete working demo.
+
+The example runs a server that publishes `/temperature` as an observable resource, with a fake sensor emitting a new reading every 500 ms. The in-process client registers, logs 5 notifications, then deregisters cleanly via `GET + Observe:1`.
+
+```ts
+import { createServer, Response } from '@sirena-lwm2m/coap';
+import { createApp } from '@sirena-lwm2m/coap/router';
+import type { Observable, Observer, Unsubscribe } from '@sirena-lwm2m/coap';
+
+// Minimal observable subject — works with any push source
+function makeSubject<T>() {
+  const subscribers = new Set<Observer<T>>();
+  return {
+    observable: {
+      subscribe(o: Observer<T>): Unsubscribe {
+        subscribers.add(o);
+        return () => { subscribers.delete(o); };
+      },
+    } satisfies Observable<T>,
+    next(v: T) { for (const obs of subscribers) obs.next(v); },
+    complete() { for (const obs of subscribers) obs.complete?.(); subscribers.clear(); },
+  };
+}
+
+const server = createServer({ listen: [{ host: '127.0.0.1', port: 5686 }] });
+const router = createApp({ server });
+const tempSubject = makeSubject<Uint8Array>();
+
+router.add({
+  path: '/temperature',
+  method: 'GET',
+  handler: async (_req, ctx) => {
+    await ctx.respond(Response.ok(currentReading()));
+    ctx.observe(tempSubject.observable);
+  },
+});
+
+await server.start();
+
+// Push a new reading whenever the sensor fires
+sensorEmitter.on('reading', (celsius: number) => {
+  const buf = Buffer.alloc(4);
+  buf.writeFloatBE(celsius, 0);
+  tempSubject.next(buf);
+});
+```

package/docs/releasing.md

@@ -0,0 +1,106 @@
+# Releasing `@sirena-lwm2m/coap`
+
+## Prerequisites
+
+- Node.js ≥ 24
+- npm account with write access to the `@sirena-lwm2m` org
+- Authenticated npm session: `npm login` (prompts for username, password, OTP)
+
+## Pre-publish checklist
+
+### 1. Confirm `package.json` is correct
+
+The `exports` map must point to built artefacts:
+
+```json
+"exports": {
+  ".": {
+    "import": "./dist/index.js",
+    "types":  "./dist/index.d.ts"
+  },
+  ...
+}
+```
+
+The `"files"` array must be explicit so that `src/`, `test/`, `tsconfig.json`, and any stale `.tgz` files are never shipped:
+
+```json
+"files": [
+  "dist",
+  "docs",
+  "examples",
+  "LICENSE"
+]
+```
+
+> **Note:** without a `"files"` array, npm falls back to `.gitignore` for exclusion. This is fragile — always keep `"files"` explicit.
+
+### 2. Dry-run pack inspection
+
+Run from the package root (`packages/coap/`):
+
+```sh
+npm pack --dry-run
+```
+
+Verify the tarball contents:
+
+| Must be present | Must NOT be present |
+|-----------------|---------------------|
+| `dist/index.js` | `src/` |
+| `dist/index.d.ts` | `test/` |
+| `docs/` | `node_modules/` |
+| `examples/` | `tsconfig.json` |
+| `LICENSE` | `*.tgz` |
+
+### 3. Final build and tests
+
+From the package root:
+
+```sh
+npm run build
+npm test
+```
+
+Both must exit 0 on a clean checkout (`git clone` + `npm install`).
+
+## Tagging and publishing
+
+### Tag the release
+
+```sh
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+Use annotated tags for production releases:
+
+```sh
+git tag -a v0.1.0 -m "chore: release 0.1.0"
+git push origin v0.1.0
+```
+
+### Publish to npm
+
+This step is **manual and human-gated**. Run it only after reviewing the dry-run output above.
+
+```sh
+cd packages/coap
+npm publish --access public
+```
+
+Confirm the package is live:
+
+```
+https://www.npmjs.com/package/@sirena-lwm2m/coap
+```
+
+## Version bumping for future releases
+
+1. Update `"version"` in `packages/coap/package.json` following semver
+2. Repeat the checklist above
+3. Tag as `vX.Y.Z` and publish
+
+## No automated CI publish
+
+There is intentionally no automated publish step in CI. All releases go through this manual process to keep a human in the loop before anything lands on the public registry.