@sirena-lwm2m/coap 0.8.0

package/dist/transport/udp.js

@@ -0,0 +1,994 @@
+import dgram from 'node:dgram';
+import net from 'node:net';
+import tls from 'node:tls';
+import { EventEmitter } from 'node:events';
+import { decodeMessage, encodeMessage, stringToCode } from '../message/index.js';
+import { createInMemoryStore, EXCHANGE_LIFETIME } from '../store/index.js';
+import { Request } from '../api/index.js';
+import { TcpConnectionManager } from './tcp-connection.js';
+import { TcpFrameStream } from './tcp-stream.js';
+import { encodeTcpFrame } from './tcp-frame.js';
+import { createDtlsSocket } from './dtls.js';
+import { OptionNumber, bytesToUint, uintToBytes, bytesToString } from '../option-parser/index.js';
+import { startNotificationLoop } from '../observe-notification.js';
+import { Block2Chunker, encodeBlockOption, decodeBlockOption } from '../blockwise/index.js';
+import { createNoopMetrics } from '../observability.js';
+// RFC 8323 §5.3 — signaling codes (7.xx class, bits: 0xe0..0xff)
+const TCP_SIGNALING_CLASS = 0xe0;
+const CODE_CSM = 0xe1; // 7.01 Capabilities and Settings
+const CODE_PING = 0xe2; // 7.02 Ping
+const CODE_PONG = 0xe3; // 7.03 Pong
+const CODE_RELEASE = 0xe4; // 7.04 Release
+const CODE_ABORT = 0xe5; // 7.05 Abort
+// Minimal CSM frame: Len=0, TKL=0, Code=7.01
+const CSM_FRAME = new Uint8Array([0x00, CODE_CSM]);
+const noopLogger = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};
+export function parseListenAddress(addr) {
+    if (typeof addr === 'object') {
+        return { host: addr.host, port: addr.port, transport: 'udp' };
+    }
+    const url = new URL(addr);
+    if (url.protocol === 'coap:') {
+        return { host: url.hostname, port: Number(url.port), transport: 'udp' };
+    }
+    if (url.protocol === 'coap+tcp:') {
+        return { host: url.hostname, port: Number(url.port), transport: 'tcp' };
+    }
+    if (url.protocol === 'coaps:') {
+        return { host: url.hostname, port: Number(url.port), transport: 'dtls' };
+    }
+    if (url.protocol === 'coaps+tcp:') {
+        return { host: url.hostname, port: Number(url.port), transport: 'tls' };
+    }
+    throw new Error(`Unsupported listen address scheme: ${url.protocol}`);
+}
+class UdpServer extends EventEmitter {
+    options;
+    isDefaultUdpStore;
+    tcpStore;
+    log;
+    metrics;
+    sockets = [];
+    dtlsSockets = [];
+    tcpServers = [];
+    tlsServers = [];
+    ready = false;
+    inflight = 0;
+    warningEmitted = false;
+    endpointState = new Map();
+    tcpConnectionManager;
+    tlsPskIdentityBySocket = new WeakMap();
+    pendingTlsUpdate = null;
+    observeRegistrations = new Map();
+    activeLoops = new Map();
+    activeNotifChunkers = new Map();
+    notifMidCounter = 0x1000; // message ID counter for server-initiated CON notifications
+    constructor(options) {
+        super();
+        const resolved = options.listen.map(addr => parseListenAddress(addr));
+        const needsSecurity = resolved.some(a => a.transport === 'dtls' || a.transport === 'tls');
+        if (needsSecurity && options.security === undefined) {
+            throw new Error('security option is required when using coaps:// (DTLS) or coaps+tcp:// (TLS) listen addresses');
+        }
+        if (options.security?.mode === 'x509' && options.security.requestClientCert && options.security.ca === undefined) {
+            throw new Error('ca is required when requestClientCert is true (x509 mode)');
+        }
+        this.isDefaultUdpStore = options.store === undefined;
+        this.log = options.logger ?? noopLogger;
+        this.metrics = options.metrics ?? createNoopMetrics();
+        this.options = {
+            listen: options.listen,
+            security: options.security,
+            store: options.store ?? createInMemoryStore(),
+            logger: this.log,
+            metrics: this.metrics,
+            queueSize: options.queueSize ?? 1024,
+            drainTimeoutMs: options.drainTimeoutMs ?? 5000,
+            ackTimeoutMs: options.ackTimeoutMs ?? 2000,
+            ackRandomFactor: options.ackRandomFactor ?? 1.5,
+            maxRetransmit: options.maxRetransmit ?? 4,
+            nonTimeoutMs: options.nonTimeoutMs ?? 145_000,
+            nstart: options.nstart ?? 1,
+            perEndpointLruCap: options.perEndpointLruCap ?? 64,
+        };
+        this.tcpStore = createInMemoryStore();
+        this.tcpConnectionManager = new TcpConnectionManager({
+            idleTimeoutMs: this.options.drainTimeoutMs,
+            logger: this.log,
+        });
+    }
+    async start() {
+        const resolved = this.options.listen.map(addr => parseListenAddress(addr));
+        const udpAddrs = resolved.filter(a => a.transport === 'udp');
+        const dtlsAddrs = resolved.filter(a => a.transport === 'dtls');
+        const tcpAddrs = resolved.filter(a => a.transport === 'tcp');
+        const tlsAddrs = resolved.filter(a => a.transport === 'tls');
+        const udpBindings = udpAddrs.map(addr => this._bindSocket(addr));
+        const dtlsBindings = dtlsAddrs.map(addr => this._bindDtlsSocket(addr));
+        const tcpBindings = tcpAddrs.map(addr => this._bindTcpServer(addr));
+        const tlsBindings = tlsAddrs.map(addr => this._bindTlsServer(addr));
+        let boundSockets;
+        let boundDtlsSockets;
+        let boundTcpServers;
+        let boundTlsServers;
+        try {
+            [boundSockets, boundDtlsSockets, boundTcpServers, boundTlsServers] = await Promise.all([
+                Promise.all(udpBindings),
+                Promise.all(dtlsBindings),
+                Promise.all(tcpBindings),
+                Promise.all(tlsBindings),
+            ]);
+        }
+        catch (err) {
+            await Promise.allSettled([
+                ...this.sockets.map(s => this._closeSocket(s.socket)),
+                ...this.dtlsSockets.map(s => s.dtlsSocket.close()),
+                ...this.tcpServers.map(s => this._closeTcpServer(s.server)),
+                ...this.tlsServers.map(s => this._closeTlsServer(s.server)),
+            ]);
+            this.sockets = [];
+            this.dtlsSockets = [];
+            this.tcpServers = [];
+            this.tlsServers = [];
+            throw err;
+        }
+        this.sockets = boundSockets;
+        this.dtlsSockets = boundDtlsSockets;
+        this.tcpServers = boundTcpServers;
+        this.tlsServers = boundTlsServers;
+        this.ready = true;
+        this.log.debug('server started', { listeners: this.listenerSummary() });
+        if (!this.warningEmitted && this.isDefaultUdpStore) {
+            const allAddrs = [
+                ...this.sockets.map(s => s.address),
+                ...this.dtlsSockets.map(s => s.address),
+                ...this.tcpServers.map(s => s.address),
+                ...this.tlsServers.map(s => s.address),
+            ];
+            for (const addr of allAddrs) {
+                if (!this._isLoopback(addr.host)) {
+                    process.emitWarning('CoAP server bound to non-loopback address with default in-memory store — not suitable for production', { code: 'SIRENA_COAP_DEFAULT_STORE' });
+                    this.warningEmitted = true;
+                    break;
+                }
+            }
+        }
+    }
+    async stop(opts) {
+        this.ready = false;
+        const deadline = opts?.drainTimeoutMs ?? this.options.drainTimeoutMs;
+        this.log.debug('server stopping', { drainTimeoutMs: deadline });
+        if (this.inflight > 0) {
+            await Promise.race([
+                this._waitForDrain(),
+                new Promise(res => setTimeout(res, deadline)),
+            ]);
+        }
+        await Promise.allSettled([
+            ...this.sockets.map(s => this._closeSocket(s.socket)),
+            ...this.dtlsSockets.map(s => s.dtlsSocket.close()),
+            ...this.tcpServers.map(s => this._closeTcpServer(s.server)),
+            ...this.tlsServers.map(s => this._closeTlsServer(s.server)),
+        ]);
+        this.sockets = [];
+        this.dtlsSockets = [];
+        this.tcpServers = [];
+        this.tlsServers = [];
+        this.endpointState.clear();
+        for (const entry of this.activeLoops.values()) {
+            entry.loop.cancel();
+        }
+        this.activeLoops.clear();
+        this.activeNotifChunkers.clear();
+        this.observeRegistrations.clear();
+        this.log.debug('server stopped');
+    }
+    isReady() {
+        return this.ready;
+    }
+    activeExchanges() {
+        return this.inflight;
+    }
+    listenerSummary() {
+        return [
+            ...this.sockets.map(s => ({ ...s.address })),
+            ...this.dtlsSockets.map(s => ({ ...s.address })),
+            ...this.tcpServers.map(s => ({ ...s.address })),
+            ...this.tlsServers.map(s => ({ ...s.address })),
+        ];
+    }
+    storeSummary() {
+        const resolved = this.options.listen.map(a => parseListenAddress(a));
+        const hasUdp = resolved.some(a => a.transport === 'udp');
+        const hasTcp = resolved.some(a => a.transport === 'tcp');
+        const result = [];
+        if (hasUdp)
+            result.push({ transport: 'udp', isDefault: this.isDefaultUdpStore });
+        if (hasTcp)
+            result.push({ transport: 'tcp', isDefault: true });
+        return result;
+    }
+    _bindSocket(addr) {
+        return new Promise((resolve, reject) => {
+            const sock = dgram.createSocket('udp4');
+            sock.once('error', reject);
+            sock.bind(addr.port, addr.host, () => {
+                sock.removeListener('error', reject);
+                const actual = sock.address();
+                const bound = {
+                    socket: sock,
+                    address: { host: actual.address, port: actual.port, transport: 'udp' },
+                };
+                this.sockets.push(bound);
+                sock.on('message', (msg, rinfo) => this._handleDatagram(sock, bound.address, msg, rinfo));
+                sock.on('error', err => {
+                    this.log.error('socket error', { err: err.message });
+                    this.emit('exchange-error', err);
+                });
+                resolve(bound);
+            });
+        });
+    }
+    async _bindDtlsSocket(addr) {
+        const security = this.options.security;
+        if (!security) {
+            throw new Error('security option required for DTLS transport');
+        }
+        const dtlsSocket = createDtlsSocket(addr, security, { logger: this.log });
+        dtlsSocket.on('exchange-error', (err) => {
+            this.log.warn('dtls exchange error', { err: err.message });
+            this.emit('exchange-error', err);
+        });
+        dtlsSocket.on('dtls-handshake', (payload) => {
+            this.emit('dtls-handshake', { peer: payload.peer, durationMs: payload.durationMs });
+        });
+        dtlsSocket.on('message', (msg, rinfo, dtlsPeer) => {
+            this._handleDtlsDatagram(dtlsSocket, addr, msg, rinfo, dtlsPeer);
+        });
+        dtlsSocket.on('error', (err) => {
+            this.log.error('dtls socket error', { err: err.message });
+            this.emit('exchange-error', err);
+        });
+        const actual = await dtlsSocket.bind();
+        const state = {
+            dtlsSocket,
+            address: { host: actual.host, port: actual.port, transport: 'dtls' },
+        };
+        this.dtlsSockets.push(state);
+        return state;
+    }
+    _handleDtlsDatagram(dtlsSocket, local, msg, rinfo, dtlsPeer) {
+        if (!this.ready)
+            return;
+        const remote = `${rinfo.address}:${rinfo.port}`;
+        let decoded;
+        try {
+            decoded = decodeMessage(new Uint8Array(msg));
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            this.log.warn('dtls decode error', { remote, err: error.message });
+            this.metrics.transportErrors.add(1);
+            this.emit('exchange-error', error);
+            return;
+        }
+        const { store } = this.options;
+        const isCon = decoded.type === 'CON';
+        const key = isCon
+            ? { remote, discriminant: 'mid', mid: decoded.messageId }
+            : { remote, discriminant: 'token', token: Buffer.from(decoded.token).toString('hex') };
+        const existing = store.get(key);
+        if (existing) {
+            this.metrics.dedupHits.add(1);
+            if (existing.responsePayload) {
+                dtlsSocket.send(existing.responsePayload, rinfo.address, rinfo.port);
+            }
+            return;
+        }
+        if (this.inflight >= this.options.queueSize) {
+            const reason = `queue full (size=${this.options.queueSize})`;
+            this.log.warn('dtls message dropped', { remote, reason });
+            this.emit('message-dropped', reason);
+            return;
+        }
+        const ep = this._getEndpointState(remote);
+        const epTotal = ep.inflight + ep.queue.length;
+        if (epTotal >= this.options.perEndpointLruCap) {
+            const reason = `per-endpoint cap exceeded (cap=${this.options.perEndpointLruCap}, remote=${remote})`;
+            this.log.warn('dtls message dropped', { remote, reason });
+            this.emit('message-dropped', reason);
+            return;
+        }
+        const lifetime = isCon ? EXCHANGE_LIFETIME : 250_000;
+        store.set(key, { expiresAt: Date.now() + lifetime });
+        this.metrics.requestRate.add(1);
+        this.metrics.activeExchanges.add(1);
+        this.inflight++;
+        const req = new Request(decoded);
+        const ctx = {
+            remote,
+            local: `${local.host}:${local.port}`,
+            transport: 'udp',
+            token: decoded.token,
+            messageId: decoded.messageId,
+            options: decoded.options,
+            peer: dtlsPeer,
+            respond: async (res) => {
+                const responseMsg = encodeMessage({
+                    version: 1,
+                    type: isCon ? 'ACK' : 'NON',
+                    token: decoded.token,
+                    code: res.statusCode,
+                    messageId: decoded.messageId,
+                    options: res.headers.toOptions(),
+                    payload: res.body ?? new Uint8Array(0),
+                });
+                store.set(key, { expiresAt: Date.now() + lifetime, responsePayload: responseMsg });
+                dtlsSocket.send(responseMsg, rinfo.address, rinfo.port);
+                this.emit('response', ctx);
+            },
+            continue: async () => {
+                const continueMsg = encodeMessage({
+                    version: 1,
+                    type: isCon ? 'ACK' : 'NON',
+                    token: decoded.token,
+                    code: 0x5f, // 2.31 Continue
+                    messageId: decoded.messageId,
+                    options: decoded.options.filter(o => o.number === 27), // echo Block1
+                    payload: new Uint8Array(0),
+                });
+                dtlsSocket.send(continueMsg, rinfo.address, rinfo.port);
+            },
+            cancel: () => { },
+            abort: (_code) => { },
+            observeSeq: 0,
+            observe: (_obs) => { },
+        };
+        const runHandler = () => {
+            ep.inflight++;
+            return Promise.resolve().then(async () => {
+                this.log.debug('dispatching dtls request', { remote, messageId: decoded.messageId });
+                const listeners = this.rawListeners('request');
+                const results = listeners.map(fn => fn(req, ctx));
+                await Promise.allSettled(results.map(r => r instanceof Promise ? r : Promise.resolve(r)));
+            }).catch(err => {
+                this.log.error('dtls exchange error', { remote, err: err.message });
+                this.emit('exchange-error', err instanceof Error ? err : new Error(String(err)));
+            }).finally(() => {
+                this.inflight--;
+                ep.inflight--;
+                this.metrics.activeExchanges.add(-1);
+                const next = ep.queue.shift();
+                if (next) {
+                    void next();
+                }
+                else if (ep.inflight === 0 && ep.queue.length === 0) {
+                    this.endpointState.delete(remote);
+                }
+                this.emit('_drain');
+            });
+        };
+        if (ep.inflight >= this.options.nstart) {
+            ep.queue.push(runHandler);
+        }
+        else {
+            void runHandler();
+        }
+    }
+    _bindTcpServer(addr) {
+        return new Promise((resolve, reject) => {
+            const srv = net.createServer();
+            srv.once('error', reject);
+            srv.listen(addr.port, addr.host, () => {
+                srv.removeListener('error', reject);
+                const actual = srv.address();
+                const state = {
+                    server: srv,
+                    address: { host: actual.address, port: actual.port, transport: 'tcp' },
+                };
+                this.tcpServers.push(state);
+                srv.on('connection', (socket) => this._handleTcpConnection(socket, state.address));
+                srv.on('error', err => {
+                    this.log.error('tcp server error', { err: err.message });
+                    this.emit('exchange-error', err);
+                });
+                resolve(state);
+            });
+        });
+    }
+    _buildTlsOptions() {
+        const security = this.options.security;
+        if (!security) {
+            throw new Error('security option required for TLS transport');
+        }
+        const tlsOpts = {
+            sessionTimeout: 300,
+        };
+        if (security.mode === 'psk') {
+            const pskFn = security.psk;
+            tlsOpts.pskCallback = (socket, identity) => {
+                const psk = pskFn(identity);
+                if (psk)
+                    this.tlsPskIdentityBySocket.set(socket, identity);
+                return psk;
+            };
+        }
+        else {
+            const pending = this.pendingTlsUpdate;
+            tlsOpts.key = pending ? pending.key : security.key;
+            tlsOpts.cert = pending ? pending.cert : security.cert;
+            if (security.ca)
+                tlsOpts.ca = security.ca;
+            if (security.requestClientCert) {
+                tlsOpts.requestCert = true;
+                tlsOpts.rejectUnauthorized = true;
+            }
+        }
+        return tlsOpts;
+    }
+    updateTls(opts) {
+        this.pendingTlsUpdate = opts;
+        for (const state of this.tlsServers) {
+            state.server.setSecureContext({ cert: opts.cert, key: opts.key });
+        }
+    }
+    _bindTlsServer(addr) {
+        return new Promise((resolve, reject) => {
+            const tlsOpts = this._buildTlsOptions();
+            const srv = tls.createServer(tlsOpts);
+            srv.once('error', reject);
+            srv.on('tlsClientError', (err) => {
+                this.log.warn('tls handshake failure', { err: err.message });
+                this.emit('exchange-error', new Error(`TLS handshake failed: ${err.message}`));
+            });
+            srv.listen(addr.port, addr.host, () => {
+                srv.removeListener('error', reject);
+                const actual = srv.address();
+                const state = {
+                    server: srv,
+                    address: { host: actual.address, port: actual.port, transport: 'tls' },
+                };
+                this.tlsServers.push(state);
+                srv.on('secureConnection', (tlsSock) => {
+                    const handshakeStart = Date.now();
+                    const durationMs = Date.now() - handshakeStart;
+                    let peer;
+                    const security = this.options.security;
+                    if (security?.mode === 'psk') {
+                        peer = { mode: 'psk', identity: this.tlsPskIdentityBySocket.get(tlsSock) ?? 'unknown' };
+                    }
+                    else if (security?.mode === 'x509') {
+                        const certChain = [];
+                        let cert = tlsSock.getPeerX509Certificate();
+                        while (cert) {
+                            certChain.push(cert);
+                            cert = cert.issuerCertificate;
+                        }
+                        peer = { mode: 'x509', certChain };
+                    }
+                    else {
+                        peer = { mode: 'anonymous' };
+                    }
+                    this.log.debug('tls handshake complete', { remote: `${tlsSock.remoteAddress}:${tlsSock.remotePort}`, durationMs });
+                    this.emit('tls-handshake', { peer, durationMs });
+                    this._handleTcpConnection(tlsSock, state.address, peer);
+                });
+                srv.on('error', err => {
+                    this.log.error('tls server error', { err: err.message });
+                    this.emit('exchange-error', err);
+                });
+                resolve(state);
+            });
+        });
+    }
+    _closeTlsServer(srv) {
+        return new Promise(res => {
+            try {
+                srv.close(() => res());
+            }
+            catch {
+                res();
+            }
+        });
+    }
+    _handleTcpConnection(socket, localAddr, connectionPeer = { mode: 'anonymous' }) {
+        if (!this.ready) {
+            socket.destroy();
+            return;
+        }
+        this.tcpConnectionManager.track(socket);
+        const remote = `${socket.remoteAddress}:${socket.remotePort}`;
+        const local = `${localAddr.host}:${localAddr.port}`;
+        const frameStream = new TcpFrameStream({ socket, logger: this.log });
+        socket.once('close', () => {
+            this.tcpConnectionManager.untrack(socket);
+        });
+        frameStream.on('frame', (frame) => {
+            if (!this.ready)
+                return;
+            // RFC 8323 §5 — handle signaling codes without dispatching to application
+            if ((frame.code & TCP_SIGNALING_CLASS) === TCP_SIGNALING_CLASS) {
+                if (frame.code === CODE_CSM) {
+                    // Respond with our own minimal CSM
+                    socket.write(Buffer.from(CSM_FRAME));
+                }
+                else if (frame.code === CODE_PING) {
+                    // Respond with Pong (same token)
+                    socket.write(Buffer.from(encodeTcpFrame({ code: CODE_PONG, token: frame.token, options: [], payload: new Uint8Array(0) })));
+                }
+                else if (frame.code === CODE_RELEASE || frame.code === CODE_ABORT) {
+                    socket.destroy();
+                }
+                return;
+            }
+            const tokenKey = {
+                remote,
+                discriminant: 'token',
+                token: Buffer.from(frame.token).toString('hex'),
+            };
+            const existing = this.tcpStore.get(tokenKey);
+            if (existing) {
+                if (existing.responsePayload) {
+                    socket.write(existing.responsePayload);
+                }
+                return;
+            }
+            this.tcpStore.set(tokenKey, { expiresAt: Date.now() + EXCHANGE_LIFETIME });
+            frameStream.registerExchange(frame.token);
+            const syntheticMsg = {
+                version: 1,
+                type: 'CON',
+                token: frame.token,
+                code: frame.code,
+                messageId: 0,
+                options: frame.options,
+                payload: frame.payload,
+            };
+            const req = new Request(syntheticMsg);
+            const ctx = {
+                remote,
+                local,
+                transport: 'tcp',
+                token: frame.token,
+                messageId: 0,
+                options: frame.options,
+                peer: connectionPeer,
+                respond: async (res) => {
+                    const responseFrame = encodeTcpFrame({
+                        code: res.statusCode,
+                        token: frame.token,
+                        options: res.headers.toOptions(),
+                        payload: res.body ?? new Uint8Array(0),
+                    });
+                    const responseBytes = Buffer.from(responseFrame);
+                    this.tcpStore.set(tokenKey, { expiresAt: Date.now() + EXCHANGE_LIFETIME, responsePayload: responseBytes });
+                    socket.write(responseBytes);
+                    frameStream.resolveExchange(frame.token);
+                    this.inflight--;
+                    this.emit('response', ctx);
+                    this.emit('_drain');
+                },
+                continue: async () => {
+                    const continueFrame = encodeTcpFrame({
+                        code: 0x5f, // 2.31 Continue
+                        token: frame.token,
+                        options: frame.options.filter(o => o.number === 27), // echo Block1
+                        payload: new Uint8Array(0),
+                    });
+                    socket.write(Buffer.from(continueFrame));
+                },
+                cancel: () => { },
+                abort: (_code) => { },
+                observeSeq: 0,
+                observe: (_obs) => { },
+            };
+            this.inflight++;
+            Promise.resolve()
+                .then(async () => {
+                this.log.debug('dispatching tcp request', { remote });
+                const listeners = this.rawListeners('request');
+                const results = listeners.map(fn => fn(req, ctx));
+                const settled = await Promise.allSettled(results.map(r => r instanceof Promise ? r : Promise.resolve(r)));
+                const rejected = settled.find(s => s.status === 'rejected');
+                if (rejected) {
+                    throw rejected.reason;
+                }
+            })
+                .catch((err) => {
+                this.inflight--;
+                this.tcpStore.delete(tokenKey);
+                frameStream.resolveExchange(frame.token);
+                const error = err instanceof Error ? err : new Error(String(err));
+                this.log.error('tcp exchange error', { remote, err: error.message });
+                this.emit('exchange-error', error);
+                this.emit('_drain');
+            });
+        });
+        frameStream.on('frame-error', (err) => {
+            this.log.error('tcp frame error', { remote, err: err.message });
+            this.emit('exchange-error', err);
+        });
+    }
+    _closeTcpServer(srv) {
+        return new Promise(res => {
+            try {
+                srv.close(() => res());
+            }
+            catch {
+                res();
+            }
+        });
+    }
+    _closeSocket(sock) {
+        return new Promise(res => {
+            try {
+                sock.close(() => res());
+            }
+            catch {
+                res();
+            }
+        });
+    }
+    _getEndpointState(remote) {
+        let state = this.endpointState.get(remote);
+        if (!state) {
+            state = { inflight: 0, queue: [] };
+            this.endpointState.set(remote, state);
+        }
+        return state;
+    }
+    _nextNotifMid() {
+        this.notifMidCounter = (this.notifMidCounter + 1) & 0xffff;
+        return this.notifMidCounter;
+    }
+    _handleDatagram(sock, local, msg, rinfo) {
+        if (!this.ready)
+            return;
+        const remote = `${rinfo.address}:${rinfo.port}`;
+        let decoded;
+        try {
+            decoded = decodeMessage(new Uint8Array(msg));
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            this.log.warn('decode error', { remote, err: error.message });
+            this.metrics.transportErrors.add(1);
+            this.emit('exchange-error', error);
+            return;
+        }
+        // ACK for an outstanding notification CON: advance the loop
+        if (decoded.type === 'ACK' && decoded.code === 0x00) {
+            const tokenHex = Buffer.from(decoded.token).toString('hex');
+            const regKey = `${remote}:${tokenHex}`;
+            const entry = this.activeLoops.get(regKey);
+            if (entry && entry.lastMid === decoded.messageId) {
+                entry.lastMid = null;
+                entry.loop.ackReceived();
+            }
+            return;
+        }
+        // RST for an outstanding notification CON: cancel the Observe registration (RFC 7641 §4.2)
+        if (decoded.type === 'RST') {
+            const tokenHex = Buffer.from(decoded.token).toString('hex');
+            const regKey = `${remote}:${tokenHex}`;
+            const entry = this.activeLoops.get(regKey);
+            if (entry && entry.lastMid === decoded.messageId) {
+                entry.loop.cancel();
+                this.activeLoops.delete(regKey);
+                const reg = this.observeRegistrations.get(regKey);
+                if (reg) {
+                    this.observeRegistrations.delete(regKey);
+                    this.metrics.observeRegistrations.add(-1);
+                    this.emit('observe-cancelled', reg);
+                }
+            }
+            return;
+        }
+        // Block2 continuation GET for an active notification chunker
+        const isGetReq = decoded.code === 0x01;
+        if (isGetReq && (decoded.type === 'CON' || decoded.type === 'NON')) {
+            const block2ContinueOpt = decoded.options.find(o => o.number === OptionNumber.Block2);
+            const hasNoObserveOpt = !decoded.options.find(o => o.number === OptionNumber.Observe);
+            if (block2ContinueOpt && hasNoObserveOpt) {
+                const tokenHexC = Buffer.from(decoded.token).toString('hex');
+                const regKeyC = `${remote}:${tokenHexC}`;
+                // Fall back to URI-path key for clients (e.g. libcoap) that use a different token
+                // on continuation GETs than the original observe registration.
+                const contPathParts = decoded.options
+                    .filter(o => o.number === OptionNumber.UriPath)
+                    .map(o => bytesToString(o.value));
+                const contUriPath = '/' + contPathParts.join('/');
+                const pathKeyC = `${remote}:path:${contUriPath}`;
+                const chunker = this.activeNotifChunkers.get(regKeyC) ?? this.activeNotifChunkers.get(pathKeyC);
+                const chunkerKey = this.activeNotifChunkers.has(regKeyC) ? regKeyC : pathKeyC;
+                if (chunker) {
+                    const block = decodeBlockOption(block2ContinueOpt.value);
+                    void chunker.getBlock(block.num).then(({ payload, m, etag }) => {
+                        const responseMsg = encodeMessage({
+                            version: 1,
+                            type: decoded.type === 'CON' ? 'ACK' : 'NON',
+                            token: decoded.token,
+                            code: stringToCode('2.05'),
+                            messageId: decoded.messageId,
+                            options: [
+                                { number: 4 /* ETag */, value: etag },
+                                { number: OptionNumber.Block2, value: encodeBlockOption({ num: block.num, szx: block.szx, m }) },
+                            ],
+                            payload,
+                        });
+                        sock.send(responseMsg, rinfo.port, rinfo.address);
+                        if (!m) {
+                            this.activeNotifChunkers.delete(chunkerKey);
+                        }
+                    });
+                    return;
+                }
+            }
+        }
+        const { store } = this.options;
+        const isCon = decoded.type === 'CON';
+        const key = isCon
+            ? { remote, discriminant: 'mid', mid: decoded.messageId }
+            : { remote, discriminant: 'token', token: Buffer.from(decoded.token).toString('hex') };
+        const existing = store.get(key);
+        if (existing) {
+            this.metrics.dedupHits.add(1);
+            if (existing.responsePayload) {
+                sock.send(existing.responsePayload, rinfo.port, rinfo.address);
+            }
+            return;
+        }
+        if (this.inflight >= this.options.queueSize) {
+            const reason = `queue full (size=${this.options.queueSize})`;
+            this.log.warn('message dropped', { remote, reason });
+            this.emit('message-dropped', reason);
+            return;
+        }
+        const ep = this._getEndpointState(remote);
+        // Per-endpoint LRU cap check (counts inflight + queued)
+        const epTotal = ep.inflight + ep.queue.length;
+        if (epTotal >= this.options.perEndpointLruCap) {
+            const reason = `per-endpoint cap exceeded (cap=${this.options.perEndpointLruCap}, remote=${remote})`;
+            this.log.warn('message dropped', { remote, reason });
+            this.emit('message-dropped', reason);
+            return;
+        }
+        // Store a placeholder immediately so concurrent duplicates don't slip through
+        const lifetime = isCon ? EXCHANGE_LIFETIME : 250_000;
+        store.set(key, { expiresAt: Date.now() + lifetime });
+        this.metrics.requestRate.add(1);
+        this.metrics.activeExchanges.add(1);
+        // Global inflight covers both running and queued exchanges (so drain-on-stop works)
+        this.inflight++;
+        // RFC 7641 §3.1 / §3.6 — Observe registration tracking
+        const isGet = decoded.code === 0x01; // 0.01 GET
+        const tokenHex = Buffer.from(decoded.token).toString('hex');
+        const observeOpt = decoded.options.find(o => o.number === OptionNumber.Observe);
+        const isObserveRegister = isGet && observeOpt !== undefined && bytesToUint(observeOpt.value) === 0;
+        const regKey = `${remote}:${tokenHex}`;
+        // RFC 7641 §3.6: deregister via Observe:1 or plain GET (no Observe option)
+        const isObserveDeregister = isGet && observeOpt !== undefined && bytesToUint(observeOpt.value) === 1;
+        if (isObserveRegister) {
+            // Cancel any existing loop for this (remote, token) before replacing
+            const prevLoop = this.activeLoops.get(regKey);
+            if (prevLoop) {
+                prevLoop.loop.cancel();
+                this.activeLoops.delete(regKey);
+            }
+            const reg = { remote, token: decoded.token };
+            this.observeRegistrations.set(regKey, reg);
+            this.metrics.observeRegistrations.add(1);
+            this.emit('observe-registered', reg);
+        }
+        else if (isObserveDeregister || (isGet && observeOpt === undefined)) {
+            const existingLoop = this.activeLoops.get(regKey);
+            if (existingLoop) {
+                // loop.cancel() triggers onCancel, which deletes the registration and emits observe-cancelled
+                existingLoop.loop.cancel();
+                this.activeLoops.delete(regKey);
+            }
+            else {
+                // No active loop — cancel any lingering registration directly
+                const existingReg = this.observeRegistrations.get(regKey);
+                if (existingReg) {
+                    this.observeRegistrations.delete(regKey);
+                    this.metrics.observeRegistrations.add(-1);
+                    this.emit('observe-cancelled', existingReg);
+                }
+            }
+        }
+        const req = new Request(decoded);
+        const ctx = {
+            remote,
+            local: `${local.host}:${local.port}`,
+            transport: 'udp',
+            token: decoded.token,
+            messageId: decoded.messageId,
+            options: decoded.options,
+            peer: { mode: 'anonymous' },
+            respond: async (res) => {
+                const responseOptions = res.headers.toOptions();
+                // Echo Observe:0 in initial registration response (RFC 7641 §3.1)
+                if (isObserveRegister) {
+                    const insertIdx = responseOptions.findIndex(o => o.number >= OptionNumber.Observe);
+                    const observeEntry = { number: OptionNumber.Observe, value: new Uint8Array(0) };
+                    if (insertIdx === -1) {
+                        responseOptions.push(observeEntry);
+                    }
+                    else {
+                        responseOptions.splice(insertIdx, 0, observeEntry);
+                    }
+                }
+                const responseMsg = encodeMessage({
+                    version: 1,
+                    type: isCon ? 'ACK' : 'NON',
+                    token: decoded.token,
+                    code: res.statusCode,
+                    messageId: decoded.messageId,
+                    options: responseOptions,
+                    payload: res.body ?? new Uint8Array(0),
+                });
+                store.set(key, { expiresAt: Date.now() + lifetime, responsePayload: responseMsg });
+                sock.send(responseMsg, rinfo.port, rinfo.address);
+                this.emit('response', ctx);
+            },
+            continue: async () => {
+                const continueMsg = encodeMessage({
+                    version: 1,
+                    type: isCon ? 'ACK' : 'NON',
+                    token: decoded.token,
+                    code: 0x5f, // 2.31 Continue
+                    messageId: decoded.messageId,
+                    options: decoded.options.filter(o => o.number === 27), // echo Block1
+                    payload: new Uint8Array(0),
+                });
+                sock.send(continueMsg, rinfo.port, rinfo.address);
+            },
+            cancel: () => { },
+            abort: (code) => {
+                const errorMsg = encodeMessage({
+                    version: 1,
+                    type: isCon ? 'ACK' : 'NON',
+                    token: decoded.token,
+                    code,
+                    messageId: decoded.messageId,
+                    options: [],
+                    payload: new Uint8Array(0),
+                });
+                store.set(key, { expiresAt: Date.now() + lifetime, responsePayload: errorMsg });
+                sock.send(errorMsg, rinfo.port, rinfo.address);
+                this.emit('response', ctx);
+            },
+            observeSeq: 0,
+            observe: (obs, opts) => {
+                if (!isObserveRegister)
+                    return; // only valid on Observe-register requests
+                // Negotiate block size from the observe GET's Block2 option, defaulting to 1024
+                const block2Opt = decoded.options.find(o => o.number === OptionNumber.Block2);
+                const notifBlockSzx = block2Opt ? decodeBlockOption(block2Opt.value).szx : 6;
+                const notifBlockSize = 1 << (notifBlockSzx + 4);
+                // Path-based key for clients that use a different token on Block2 continuation GETs
+                const regPathParts = decoded.options
+                    .filter(o => o.number === OptionNumber.UriPath)
+                    .map(o => bytesToString(o.value));
+                const regUriPath = '/' + regPathParts.join('/');
+                const regPathKey = `${remote}:path:${regUriPath}`;
+                const entry = { loop: null, lastMid: null };
+                const loop = startNotificationLoop(obs, (value) => value instanceof Uint8Array ? value : new Uint8Array(0), (seq, payload) => {
+                    const mid = this._nextNotifMid();
+                    entry.lastMid = mid;
+                    if (payload.length > notifBlockSize) {
+                        // Replace any previous chunker for this registration with a fresh one
+                        const chunker = new Block2Chunker(Buffer.from(payload), { blockSize: notifBlockSize });
+                        this.activeNotifChunkers.set(regKey, chunker);
+                        this.activeNotifChunkers.set(regPathKey, chunker);
+                        chunker.once('block-transfer-complete', () => {
+                            this.emit('block-transfer-complete', { remote, token: decoded.token });
+                        });
+                        chunker.once('block-transfer-aborted', (ev) => {
+                            this.emit('block-transfer-aborted', { remote, token: decoded.token, reason: ev.reason });
+                        });
+                        // Send block 0 — carries the Observe sequence number
+                        // Options must be in ascending numeric order per RFC 7252
+                        void chunker.getBlock(0).then(({ payload: block0, m, etag }) => {
+                            const notifMsg = encodeMessage({
+                                version: 1,
+                                type: 'CON',
+                                token: decoded.token,
+                                code: stringToCode('2.05'),
+                                messageId: mid,
+                                options: [
+                                    { number: 4 /* ETag */, value: etag },
+                                    { number: OptionNumber.Observe, value: uintToBytes(seq) },
+                                    { number: OptionNumber.Block2, value: encodeBlockOption({ num: 0, szx: notifBlockSzx, m }) },
+                                ],
+                                payload: block0,
+                            });
+                            sock.send(notifMsg, rinfo.port, rinfo.address);
+                        });
+                    }
+                    else {
+                        const notifMsg = encodeMessage({
+                            version: 1,
+                            type: 'CON',
+                            token: decoded.token,
+                            code: stringToCode('2.05'),
+                            messageId: mid,
+                            options: [{ number: OptionNumber.Observe, value: uintToBytes(seq) }],
+                            payload,
+                        });
+                        sock.send(notifMsg, rinfo.port, rinfo.address);
+                    }
+                }, () => {
+                    // Observable completed/errored — tear down registration
+                    const existingReg = this.observeRegistrations.get(regKey);
+                    if (existingReg) {
+                        this.observeRegistrations.delete(regKey);
+                        this.activeLoops.delete(regKey);
+                        this.activeNotifChunkers.delete(regKey);
+                        this.activeNotifChunkers.delete(regPathKey);
+                        this.metrics.observeRegistrations.add(-1);
+                        this.emit('observe-cancelled', existingReg);
+                    }
+                }, opts);
+                entry.loop = loop;
+                this.activeLoops.set(regKey, entry);
+            },
+        };
+        const runHandler = () => {
+            ep.inflight++;
+            return Promise.resolve().then(async () => {
+                this.log.debug('dispatching request', { remote, messageId: decoded.messageId });
+                const listeners = this.rawListeners('request');
+                const results = listeners.map(fn => fn(req, ctx));
+                await Promise.allSettled(results.map(r => r instanceof Promise ? r : Promise.resolve(r)));
+            }).catch(err => {
+                this.log.error('exchange error', { remote, err: err.message });
+                this.emit('exchange-error', err instanceof Error ? err : new Error(String(err)));
+            }).finally(() => {
+                this.inflight--;
+                ep.inflight--;
+                this.metrics.activeExchanges.add(-1);
+                // NSTART: dispatch next queued request for this endpoint
+                const next = ep.queue.shift();
+                if (next) {
+                    void next();
+                }
+                else if (ep.inflight === 0 && ep.queue.length === 0) {
+                    this.endpointState.delete(remote);
+                }
+                this.emit('_drain');
+            });
+        };
+        // NSTART enforcement: if this endpoint is already running nstart handlers, queue
+        if (ep.inflight >= this.options.nstart) {
+            ep.queue.push(runHandler);
+        }
+        else {
+            void runHandler();
+        }
+    }
+    _waitForDrain() {
+        return new Promise(res => {
+            const check = () => {
+                if (this.inflight === 0) {
+                    this.removeListener('_drain', check);
+                    res();
+                }
+            };
+            this.on('_drain', check);
+        });
+    }
+    _isLoopback(host) {
+        return host === '127.0.0.1' || host === '::1' || host === 'localhost';
+    }
+}
+export function createServer(options) {
+    return new UdpServer(options);
+}
+//# sourceMappingURL=udp.js.map