@sirena-lwm2m/coap 0.8.0

package/docs/router.md

@@ -0,0 +1,170 @@
+# `@sirena-lwm2m/coap/router` — Router API
+
+## `createApp(opts)`
+
+Creates a `Router` wired to a `Server` instance and returns it.
+
+```ts
+import { createApp } from '@sirena-lwm2m/coap/router';
+
+const router = createApp({ server, discovery: true });
+```
+
+**Options (`AppOptions`):**
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `server` | `Server` | — | The CoAP server whose `request` events are dispatched through the router. |
+| `discovery` | `boolean` | `false` | When `true`, automatically handles `GET /.well-known/core` and returns all registered paths in CoRE Link Format (RFC 6690). |
+
+**Return value:** a `Router` instance.
+
+---
+
+## `router.use(middleware)`
+
+Appends a middleware function to the chain. Middlewares run in registration order before the matched route handler.
+
+```ts
+router.use((req, ctx, next) => {
+  if (!authorized(ctx)) {
+    ctx.abort(stringToCode('4.01'));
+    return;
+  }
+  return next();
+});
+```
+
+**Signature:**
+```ts
+use(middleware: Middleware): void
+```
+
+where `Middleware` is:
+```ts
+(req: Request, ctx: RouteContext, next: NextFn) => void | Promise<void>
+```
+
+**Execution order:** middlewares are called in the order `use()` was called, followed by the route handler. Each middleware must either call `next()` to continue, call `ctx.respond()` / `ctx.abort()` to short-circuit, or return without calling `next()` to silently drop the exchange.
+
+---
+
+## `router.add(route)` / `router.remove(route)`
+
+Hot-reload: add or remove a route without restarting the server. The routing table is rebuilt atomically; in-flight exchanges on a removed route complete normally.
+
+```ts
+const route = { path: '/3/{iid}', method: 'GET' as const, handler };
+
+router.add(route);
+// later…
+router.remove(route);
+```
+
+**`Route` interface:**
+```ts
+interface Route {
+  path:    string;      // radix-tree path, e.g. '/3/{iid}/{rid}'
+  method:  CoapMethod;  // 'GET' | 'POST' | 'PUT' | 'DELETE' | …
+  handler: Handler;     // (req, ctx) => void | Promise<void>
+}
+```
+
+Path parameters are enclosed in `{}` and exposed on `ctx.params`:
+```ts
+router.add({
+  path: '/rd/{ep}',
+  method: 'GET',
+  handler: (_req, ctx) => {
+    console.log(ctx.params.ep); // e.g. "my-device"
+  },
+});
+```
+
+---
+
+## `contentFormat(registry)`
+
+Middleware factory that negotiates `Content-Format` and `Accept` CoAP options against a registry. Calls `ctx.abort(4.06 Not Acceptable)` when negotiation fails.
+
+```ts
+import { contentFormat } from '@sirena-lwm2m/coap/router';
+import type { ContentFormatRegistry } from '@sirena-lwm2m/coap/router';
+
+const registry: ContentFormatRegistry = {
+  accepts: (cf) => cf === 110,           // application/senml+json
+  negotiate: (accepts) => accepts.includes(110) ? 110 : null,
+};
+
+router.use(contentFormat(registry));
+```
+
+**`ContentFormatRegistry` interface:**
+```ts
+interface ContentFormatRegistry {
+  accepts(contentFormat: number): boolean;
+  negotiate(accept: number[]): number | null;
+}
+```
+
+The `contentFormat` middleware is intentionally free of LwM2M-specific logic; the registry is provided by the caller, keeping codec knowledge outside this package.
+
+---
+
+## `RouterOptions.discovery`
+
+When `discovery: true` is passed to `createApp`, the router registers a built-in handler for `GET /.well-known/core`. The response body is a CoRE Link Format string assembled from all currently registered paths:
+
+```
+</3/{iid}>;rt="core.rd-lookup-res",</3/{iid}/{rid}>;rt="core.rd-lookup-res"
+```
+
+Content-Format `40` (application/link-format) is set automatically.
+
+---
+
+## End-to-end example
+
+```ts
+import { createServer, stringToCode, Response, stringToBytes } from '@sirena-lwm2m/coap';
+import { createApp } from '@sirena-lwm2m/coap/router';
+import type { Middleware } from '@sirena-lwm2m/coap/router';
+
+const OPTION_AUTHORIZATION = 65000;
+
+const server = createServer({
+  listen: [{ host: '127.0.0.1', port: 5683 }],
+});
+
+const router = createApp({ server, discovery: true });
+
+const authMiddleware: Middleware = (req, ctx, next) => {
+  const authOpt = ctx.options.find(o => o.number === OPTION_AUTHORIZATION);
+  if (authOpt === undefined) {
+    ctx.abort(stringToCode('4.01'));
+    return;
+  }
+  return next();
+};
+
+router.use(authMiddleware);
+
+router.add({
+  path: '/3/{iid}',
+  method: 'GET',
+  handler: (_req, ctx) => {
+    ctx.respond(new Response(stringToCode('2.05'), stringToBytes('device-object')));
+  },
+});
+
+router.add({
+  path: '/3/{iid}/{rid}',
+  method: 'PUT',
+  handler: (_req, ctx) => {
+    ctx.respond(new Response(stringToCode('2.04')));
+  },
+});
+
+await server.start();
+console.log('Listening on:', server.listenerSummary());
+```

package/docs/store.md

@@ -0,0 +1,212 @@
+# Transaction Store — @sirena-lwm2m/coap
+
+The transaction store is the deduplication layer for CoAP exchanges. RFC 7252 requires servers to detect and replay responses for retransmitted CON messages. The store also suppresses duplicate NON messages within their lifetime.
+
+## Import path
+
+```ts
+import { createInMemoryStore, createSqliteStore } from '@sirena-lwm2m/coap/store';
+import type { TransactionStore, StoreKey, StoreEntry, SqliteStore, SqliteStoreOptions } from '@sirena-lwm2m/coap/store';
+```
+
+The `createServer()` function accepts any `TransactionStore` implementation via `ServerOptions.store`. When no store is provided, an `InMemoryStore` with default settings is created automatically.
+
+---
+
+## `TransactionStore` interface
+
+```ts
+interface TransactionStore {
+  set(key: StoreKey, entry: StoreEntry): void;
+  get(key: StoreKey): StoreEntry | undefined;
+  delete(key: StoreKey): void;
+  prune(): void;
+}
+```
+
+| Method | Description |
+|--------|-------------|
+| `set(key, entry)` | Insert or update an entry. Must be idempotent — calling it twice with the same key replaces the entry. |
+| `get(key)` | Look up an entry. Returns `undefined` if the key is not present or has been evicted. |
+| `delete(key)` | Remove an entry immediately. Called after a reliable response is delivered and acknowledged. |
+| `prune()` | Evict all entries whose `expiresAt` timestamp is in the past. Called periodically by the server. |
+
+---
+
+## `StoreKey`
+
+```ts
+type StoreKey =
+  | { remote: string; discriminant: 'mid'; mid: number }
+  | { remote: string; discriminant: 'token'; token: string };
+```
+
+Two discriminants cover the two deduplication strategies:
+
+| Discriminant | Used for | Key fields |
+|---|---|---|
+| `'mid'` | CON message deduplication (RFC 7252 §4.5) | `remote` + `mid` |
+| `'token'` | NON message deduplication (RFC 7252 §4.6) | `remote` + `token` |
+
+`remote` is the peer address string in `"ip:port"` form.
+
+---
+
+## `StoreEntry`
+
+```ts
+interface StoreEntry {
+  responsePayload?: Uint8Array;
+  expiresAt: number;         // Unix timestamp in milliseconds
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `responsePayload` | The encoded response to replay on retransmission. `undefined` for NON entries where no response is cached. |
+| `expiresAt` | When this entry should be swept by `prune()`. Typically `Date.now() + EXCHANGE_LIFETIME` for CON or `Date.now() + NON_LIFETIME` for NON. |
+
+### Lifetime constants
+
+```ts
+const EXCHANGE_LIFETIME: number;  // 247 000 ms — RFC 7252 §4.8.2
+const NON_LIFETIME: number;       // 250 000 ms — RFC 7252 §4.8.2
+```
+
+---
+
+## `InMemoryStore`
+
+A per-remote LRU map backed by a plain `Map`. Entries are evicted either by TTL (`prune()`) or by per-remote LRU cap when a single remote endpoint exceeds the cap.
+
+```ts
+function createInMemoryStore(options?: InMemoryStoreOptions): TransactionStore
+
+interface InMemoryStoreOptions {
+  lruCap?: number;   // Max entries per remote endpoint. Default: 64.
+}
+```
+
+### Characteristics
+
+| Property | Value |
+|----------|-------|
+| Persistence | None — lost on process restart |
+| Concurrency | Single-process, synchronous |
+| Memory | O(n) where n is total live entries across all remotes |
+| Sweep | Caller-driven — the server calls `prune()` periodically |
+| LRU eviction | Oldest-first per remote when `lruCap` is exceeded |
+
+### Example
+
+```ts
+import { createServer } from '@sirena-lwm2m/coap';
+import { createInMemoryStore } from '@sirena-lwm2m/coap/store';
+
+const server = createServer({
+  listen: [{ host: '0.0.0.0', port: 5683 }],
+  store: createInMemoryStore({ lruCap: 128 }),
+});
+```
+
+---
+
+## `SqliteStore`
+
+A WAL-mode SQLite-backed store for persistence across restarts and multi-process deployments.
+
+```ts
+function createSqliteStore(options?: SqliteStoreOptions): Promise<SqliteStore>
+
+interface SqliteStoreOptions {
+  path?: string;            // File path. Default: ':memory:' (in-process, no persistence).
+  sweepIntervalMs?: number; // Background sweep interval. Default: 5 000 ms.
+}
+
+interface SqliteStore extends TransactionStore {
+  close(): void;  // Stop the background sweep timer and close the database.
+}
+```
+
+`createSqliteStore` is `async` because it dynamically imports `better-sqlite3`, which is an optional peer dependency. If `better-sqlite3` is not installed the promise rejects with an actionable error message.
+
+### Peer dependency
+
+```bash
+npm install better-sqlite3
+```
+
+`better-sqlite3` is declared as an optional peer dependency. It is only required if you use `SqliteStore`.
+
+### Characteristics
+
+| Property | Value |
+|----------|-------|
+| Persistence | Durable — survives process restarts when `path` points to a file |
+| Concurrency | Safe for multiple readers, single writer (WAL mode) |
+| Sweep | Background timer (default 5 s), plus caller-driven `prune()` |
+| `close()` | Required — stops the timer and releases the SQLite connection |
+
+### Schema
+
+```sql
+CREATE TABLE IF NOT EXISTS dedup (
+  key     TEXT PRIMARY KEY,
+  expires INTEGER NOT NULL,
+  payload BLOB
+);
+```
+
+One row per store entry. The `key` column is a `\x00`-separated composite of discriminant, remote address, and MID or token.
+
+### Example
+
+```ts
+import { createServer } from '@sirena-lwm2m/coap';
+import { createSqliteStore } from '@sirena-lwm2m/coap/store';
+
+const store = await createSqliteStore({
+  path: '/var/lib/myapp/coap-dedup.db',
+  sweepIntervalMs: 10_000,
+});
+
+const server = createServer({
+  listen: [{ host: '0.0.0.0', port: 5683 }],
+  store,
+});
+
+await server.start();
+
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  await server.stop();
+  store.close();
+});
+```
+
+### In-memory SQLite (testing)
+
+```ts
+const store = await createSqliteStore(); // path defaults to ':memory:'
+```
+
+This is useful in tests where you want the SQLite code path exercised without a filesystem dependency.
+
+---
+
+## Custom store
+
+Implement `TransactionStore` directly to integrate with any backend:
+
+```ts
+import type { TransactionStore, StoreKey, StoreEntry } from '@sirena-lwm2m/coap/store';
+
+class RedisStore implements TransactionStore {
+  set(key: StoreKey, entry: StoreEntry): void { /* … */ }
+  get(key: StoreKey): StoreEntry | undefined { /* … */ }
+  delete(key: StoreKey): void { /* … */ }
+  prune(): void { /* … */ }
+}
+```
+
+The server calls `prune()` on a regular interval derived from `EXCHANGE_LIFETIME`. Custom stores should expire entries lazily in `get()` as well to avoid serving stale cached responses after a restart.

package/docs/tcp-transport.md

@@ -0,0 +1,89 @@
+# TCP Transport (RFC 8323)
+
+`@sirena-lwm2m/coap` supports CoAP over TCP as specified in [RFC 8323](https://www.rfc-editor.org/rfc/rfc8323). Bind a TCP listener alongside UDP by including a `coap+tcp://` URI in the `listen` array.
+
+## RFC 8323 framing
+
+CoAP over TCP replaces the fixed 4-byte UDP header with a variable-length framing scheme:
+
+```
+ 0                   1                   2                   3
+ 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|  Len  |  TKL  |      Code     |    Token (TKL bytes) ...      |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|   Options (if any) ...                                        |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|1 1 1 1 1 1 1 1|    Payload (if any) ...                       |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+```
+
+- **Len** — 4-bit length indicator. Values 0–12 encode the remaining message length directly. Values 13, 14, and 15 signal 1-byte, 2-byte, and 4-byte extended length fields respectively.
+- There is no `Version` or `Type` field — TCP's reliability removes the need for ACK/RST message types.
+- The `messageId` field is absent; deduplication uses the token.
+
+## Connection multiplexing
+
+A single TCP connection can carry concurrent CoAP exchanges. Each exchange is identified by its token. The server maintains a per-connection token-keyed map; a response is written back on the same socket that delivered the request.
+
+Connection management lifecycle:
+1. Client connects.
+2. Server sends a CSM (Capabilities and Settings Message, code 7.01) immediately on accept.
+3. Client may send its own CSM; the server logs and ignores unknown options.
+4. Exchanges proceed. Multiple requests may be in flight simultaneously on the same connection.
+5. Either side may close the connection; the server treats a closed socket as exchange cancellation.
+
+## Idle timeout
+
+There is currently no configurable idle-connection timeout. Connections remain open until the client closes them or a network error is detected. A future release will expose an `idleTimeoutMs` option on `ServerOptions`.
+
+## Per-transport transaction store
+
+UDP and TCP exchanges use separate deduplication stores. This prevents a retransmitted UDP CON message from being confused with a TCP exchange carrying the same token, and vice versa.
+
+By default, both stores are in-memory. Pass a custom `store` to `createServer` to replace the default UDP store; the TCP store is always a separate in-memory instance.
+
+```ts
+const server = createServer({
+  listen: [
+    'coap://0.0.0.0:5683',
+    'coap+tcp://0.0.0.0:5684',
+  ],
+  // optional: custom UDP deduplication store
+  store: myCustomStore,
+});
+```
+
+`server.storeSummary()` returns an entry for each active store:
+
+```ts
+[
+  { transport: 'udp', isDefault: true },
+  { transport: 'tcp', isDefault: true },
+]
+```
+
+## ExchangeContext.transport
+
+Every request handler receives `ctx.transport` set to `'udp'` or `'tcp'`, allowing the handler to branch on the transport that delivered the request:
+
+```ts
+server.on('request', async (req, ctx) => {
+  console.log(`[${ctx.transport}] ${req.url}`);
+  await ctx.respond(Response.ok(stringToBytes(`received via ${ctx.transport}`)));
+});
+```
+
+## Signaling messages
+
+The server handles the following RFC 8323 §5.3 signaling codes internally:
+
+| Code | Name    | Behaviour |
+|------|---------|-----------|
+| 7.01 | CSM     | Sent on accept; received CSM is parsed and ignored |
+| 7.02 | Ping    | Replied with Pong (7.03) |
+| 7.03 | Pong    | Silently dropped |
+| 7.04 | Release | Connection closed gracefully |
+| 7.05 | Abort   | Connection destroyed |
+
+Application handlers never see signaling messages — they are consumed before the `'request'` event is emitted.

package/docs/udp-transport.md

@@ -0,0 +1,81 @@
+# UDP Transport
+
+`createServer(options)` creates a CoAP server over plain UDP (RFC 7252).
+
+## ServerOptions
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `listen` | `ListenAddress[]` | required | One or more `{ host, port }` pairs to bind |
+| `store` | `TransactionStore` | in-memory | Custom deduplication store |
+| `logger` | `Logger` | no-op | Structured logger (`debug`, `info`, `warn`, `error`) |
+| `queueSize` | `number` | `1024` | Max global in-flight + queued exchanges before dropping |
+| `drainTimeoutMs` | `number` | `5000` | How long `stop()` waits for in-flight exchanges |
+| `ackTimeoutMs` | `number` | `2000` | RFC 7252 ACK_TIMEOUT (ms) |
+| `ackRandomFactor` | `number` | `1.5` | RFC 7252 ACK_RANDOM_FACTOR |
+| `maxRetransmit` | `number` | `4` | RFC 7252 MAX_RETRANSMIT |
+| `nonTimeoutMs` | `number` | `145000` | NON_LIFETIME (ms) |
+| `nstart` | `number` | `1` | Max concurrent exchanges per endpoint |
+| `perEndpointLruCap` | `number` | `64` | Max in-flight + queued per remote endpoint |
+
+## Server interface
+
+```ts
+interface Server extends EventEmitter {
+  start(): Promise<void>;
+  stop(opts?: { drainTimeoutMs?: number }): Promise<void>;
+  isReady(): boolean;
+  activeExchanges(): number;
+  listenerSummary(): Array<{ host: string; port: number }>;
+}
+```
+
+## ExchangeContext
+
+Passed as the second argument to every `'request'` handler:
+
+```ts
+interface ExchangeContext {
+  remote: string;          // "ip:port" of the sender
+  local: string;           // "ip:port" of the receiving socket
+  token: Uint8Array;       // CoAP token bytes
+  messageId: number;       // CoAP message ID
+  options: CoapOption[];   // raw parsed options
+  peer: Peer;              // { mode: 'anonymous' } in Slice 1
+  respond(res: Response): Promise<void>;
+  cancel(): void;
+  abort(code: CoapCode): void;
+}
+```
+
+## Events
+
+| Event | Payload | Emitted when |
+|---|---|---|
+| `'request'` | `(req: Request, ctx: ExchangeContext)` | A new CoAP request arrives |
+| `'response'` | `(ctx: ExchangeContext)` | A response is sent |
+| `'exchange-error'` | `(err: Error)` | Decode error or handler exception |
+| `'message-dropped'` | `(reason: string)` | Queue or per-endpoint cap exceeded |
+
+## Lifecycle
+
+```
+createServer(options)
+  │
+  ▼
+server.start()        ← binds all sockets; rejects if any bind fails
+  │
+  ▼
+[handling 'request' events]
+  │
+  ▼
+server.stop({ drainTimeoutMs })
+  ├── waits up to drainTimeoutMs for in-flight exchanges
+  └── closes all sockets
+```
+
+`isReady()` returns `true` between `start()` and `stop()`.
+
+`activeExchanges()` returns the count of in-flight (running + queued) exchanges.
+
+`listenerSummary()` returns the bound address of each socket.

package/examples/slice-1.ts

@@ -0,0 +1,12 @@
+import { createServer, Response, stringToBytes } from '@sirena-lwm2m/coap';
+
+const server = createServer({
+  listen: [{ host: '127.0.0.1', port: 5683 }],
+});
+
+server.on('request', async (req, ctx) => {
+  await ctx.respond(Response.ok(stringToBytes(req.url)));
+});
+
+await server.start();
+console.log('CoAP server listening on:', server.listenerSummary());

package/examples/slice-2.ts

@@ -0,0 +1,96 @@
+import dgram from 'node:dgram';
+import net from 'node:net';
+import { createServer } from '@sirena-lwm2m/coap/transport';
+import { encodeTcpFrame, decodeTcpFrame } from '../dist/transport/index.js';
+import { encodeMessage, decodeMessage, stringToCode } from '@sirena-lwm2m/coap';
+import { Response, stringToBytes } from '@sirena-lwm2m/coap';
+
+// --- Server: listens on both UDP (5683) and TCP (5684) ---
+
+const server = createServer({
+  listen: ['coap://127.0.0.1:5683', 'coap+tcp://127.0.0.1:5684'],
+});
+
+server.on('request', async (req, ctx) => {
+  console.log(`[${ctx.transport}] ${req.url}`);
+  await ctx.respond(Response.ok(stringToBytes(`[${ctx.transport}] ${req.url}`)));
+});
+
+await server.start();
+console.log('Server listening on:', server.listenerSummary());
+
+// --- UDP client request ---
+
+async function udpGet(host: string, port: number, path: string): Promise<string> {
+  const token = new Uint8Array([0x01]);
+  const packet = encodeMessage({
+    version: 1,
+    type: 'CON',
+    token,
+    code: stringToCode('0.01'),
+    messageId: 1,
+    options: [],
+    payload: new Uint8Array(0),
+  });
+
+  return new Promise((resolve, reject) => {
+    const sock = dgram.createSocket('udp4');
+    const timer = setTimeout(() => { sock.close(); reject(new Error('UDP timeout')); }, 3000);
+
+    sock.once('message', (msg) => {
+      clearTimeout(timer);
+      sock.close();
+      const decoded = decodeMessage(msg);
+      resolve(Buffer.from(decoded.payload).toString('utf8'));
+    });
+
+    sock.bind(0, '127.0.0.1', () => {
+      sock.send(packet, port, host);
+    });
+
+    sock.once('error', (err) => { clearTimeout(timer); sock.close(); reject(err); });
+  });
+}
+
+// --- TCP client request ---
+
+async function tcpGet(host: string, port: number, path: string): Promise<string> {
+  const token = new Uint8Array([0x02]);
+  const frame = encodeTcpFrame({
+    code: stringToCode('0.01'),
+    token,
+    options: [],
+    payload: new Uint8Array(0),
+  });
+
+  return new Promise((resolve, reject) => {
+    const sock = net.createConnection({ host, port }, () => {
+      sock.write(Buffer.from(frame));
+    });
+
+    const timer = setTimeout(() => { sock.destroy(); reject(new Error('TCP timeout')); }, 3000);
+
+    let buf = Buffer.alloc(0);
+    sock.on('data', (chunk: Buffer) => {
+      buf = Buffer.concat([buf, chunk]);
+      const result = decodeTcpFrame(buf);
+      if (result !== null && result.frame.payload.length > 0) {
+        clearTimeout(timer);
+        sock.destroy();
+        resolve(Buffer.from(result.frame.payload).toString('utf8'));
+      }
+    });
+
+    sock.once('error', (err) => { clearTimeout(timer); reject(err); });
+  });
+}
+
+// --- Make one request over each transport ---
+
+const udpReply = await udpGet('127.0.0.1', 5683, '/hello');
+console.log('UDP reply:', udpReply);
+
+const tcpReply = await tcpGet('127.0.0.1', 5684, '/hello');
+console.log('TCP reply:', tcpReply);
+
+await server.stop();