@totemsdk/edge-coap 0.1.0 → 0.3.0

package/dist/cjs/codec.js

@@ -0,0 +1,349 @@
+"use strict";
+/**
+ * CoAP wire codec (RFC 7252 §3).
+ *
+ * Kept independent of the transport so the encoding can be exercised against
+ * RFC vectors without a socket. Only Uri-Path (option 11) is emitted; Uri-Host
+ * and Uri-Port default to the destination address, so they are not sent.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.URI_QUERY_OPTION = exports.ACCEPT_OPTION = exports.CONTENT_FORMAT_OPTION = exports.URI_PATH_OPTION = exports.SIZE1_OPTION = exports.SIZE2_OPTION = exports.BLOCK1_OPTION = exports.BLOCK2_OPTION = exports.OSCORE_OPTION = exports.URI_PORT_OPTION = exports.OBSERVE_OPTION = exports.URI_HOST_OPTION = void 0;
+exports.tokenToKey = tokenToKey;
+exports.encodeCoap = encodeCoap;
+exports.decodeCoap = decodeCoap;
+exports.encodeBlock = encodeBlock;
+exports.decodeBlock = decodeBlock;
+exports.formatResponseCode = formatResponseCode;
+exports.parseResponseCode = parseResponseCode;
+exports.URI_HOST_OPTION = 3;
+exports.OBSERVE_OPTION = 6;
+exports.URI_PORT_OPTION = 7;
+exports.OSCORE_OPTION = 9;
+exports.BLOCK2_OPTION = 23;
+exports.BLOCK1_OPTION = 27;
+exports.SIZE2_OPTION = 28;
+exports.SIZE1_OPTION = 60;
+exports.URI_PATH_OPTION = 11;
+exports.CONTENT_FORMAT_OPTION = 12;
+exports.ACCEPT_OPTION = 17;
+exports.URI_QUERY_OPTION = 15;
+const PAYLOAD_MARKER = 0xff;
+const MAX_TOKEN_LENGTH = 8;
+const MAX_OPTION_VALUE = 65804; // 269 + 0xffff
+const METHOD_CODES = { GET: 1, POST: 2, PUT: 3, DELETE: 4, FETCH: 5 };
+const CODE_METHODS = { 1: 'GET', 2: 'POST', 3: 'PUT', 4: 'DELETE', 5: 'FETCH' };
+function tokenToKey(token) {
+    return Array.from(token).map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+function encodeCoap(msg) {
+    const tokenLen = msg.token.length;
+    if (tokenLen > MAX_TOKEN_LENGTH)
+        throw new Error('CoAP token exceeds 8 bytes');
+    if (msg.messageId < 0 || msg.messageId > 0xffff)
+        throw new Error('CoAP message id out of range');
+    const entries = [];
+    if (msg.uriHost !== undefined)
+        entries.push({ number: exports.URI_HOST_OPTION, value: new TextEncoder().encode(msg.uriHost) });
+    if (msg.observe !== undefined)
+        entries.push({ number: exports.OBSERVE_OPTION, value: uintToBytes(msg.observe) });
+    if (msg.uriPort !== undefined)
+        entries.push({ number: exports.URI_PORT_OPTION, value: uintToBytes(msg.uriPort) });
+    if (msg.oscore)
+        entries.push({ number: exports.OSCORE_OPTION, value: msg.oscore });
+    for (const segment of msg.path) {
+        if (segment.length === 0)
+            throw new Error('CoAP Uri-Path segment cannot be empty');
+        entries.push({ number: exports.URI_PATH_OPTION, value: new TextEncoder().encode(segment) });
+    }
+    for (const query of msg.uriQuery ?? []) {
+        entries.push({ number: exports.URI_QUERY_OPTION, value: new TextEncoder().encode(query) });
+    }
+    if (msg.contentFormat !== undefined)
+        entries.push({ number: exports.CONTENT_FORMAT_OPTION, value: uintToBytes(msg.contentFormat) });
+    if (msg.accept !== undefined)
+        entries.push({ number: exports.ACCEPT_OPTION, value: uintToBytes(msg.accept) });
+    if (msg.block2)
+        entries.push({ number: exports.BLOCK2_OPTION, value: uintToBytes(encodeBlock(msg.block2)) });
+    if (msg.block1)
+        entries.push({ number: exports.BLOCK1_OPTION, value: uintToBytes(encodeBlock(msg.block1)) });
+    if (msg.size2 !== undefined)
+        entries.push({ number: exports.SIZE2_OPTION, value: uintToBytes(msg.size2) });
+    if (msg.size1 !== undefined)
+        entries.push({ number: exports.SIZE1_OPTION, value: uintToBytes(msg.size1) });
+    // Stable sort keeps repeated Uri-Path segments in path order.
+    entries.sort((a, b) => a.number - b.number);
+    const options = [];
+    let previousOption = 0;
+    for (const entry of entries) {
+        const delta = optionDeltaNibble(entry.number - previousOption);
+        const length = optionLengthNibble(entry.value.length);
+        options.push((delta.nibble << 4) | length.nibble, ...delta.extended, ...length.extended, ...entry.value);
+        previousOption = entry.number;
+    }
+    let code = 0;
+    if (msg.type === 'CON' || msg.type === 'NON') {
+        if (msg.method) {
+            if (METHOD_CODES[msg.method] === undefined)
+                throw new Error('CoAP request requires a method');
+            code = METHOD_CODES[msg.method];
+        }
+        else if (msg.responseCode !== undefined) {
+            code = parseResponseCode(msg.responseCode);
+        }
+        else {
+            throw new Error('CoAP CON/NON message requires a method or response code');
+        }
+    }
+    else if (msg.responseCode !== undefined) {
+        code = parseResponseCode(msg.responseCode);
+    }
+    const marker = msg.payload.length > 0 ? [PAYLOAD_MARKER] : [];
+    const out = new Uint8Array(4 + tokenLen + options.length + marker.length + msg.payload.length);
+    out[0] = 0x40 | ((msgTypeCode(msg.type) & 0x03) << 4) | tokenLen;
+    out[1] = code;
+    out[2] = (msg.messageId >> 8) & 0xff;
+    out[3] = msg.messageId & 0xff;
+    out.set(msg.token, 4);
+    out.set(options, 4 + tokenLen);
+    const payloadOffset = 4 + tokenLen + options.length;
+    if (marker.length)
+        out[payloadOffset] = PAYLOAD_MARKER;
+    out.set(msg.payload, payloadOffset + marker.length);
+    return out;
+}
+function decodeCoap(raw, remote) {
+    if (raw.length < 4)
+        throw new Error('Truncated CoAP header');
+    const version = (raw[0] >> 6) & 0x03;
+    if (version !== 1)
+        throw new Error(`Unsupported CoAP version ${version}`);
+    const tokenLen = raw[0] & 0x0f;
+    if (tokenLen > MAX_TOKEN_LENGTH)
+        throw new Error('Invalid CoAP token length');
+    if (raw.length < 4 + tokenLen)
+        throw new Error('Truncated CoAP token');
+    const type = typeFromCode((raw[0] >> 4) & 0x03);
+    const code = raw[1];
+    const messageId = ((raw[2] << 8) | raw[3]) & 0xffff;
+    const token = raw.slice(4, 4 + tokenLen);
+    const path = [];
+    const uriQuery = [];
+    let uriHost;
+    let uriPort;
+    let optionNumber = 0;
+    let offset = 4 + tokenLen;
+    let payload = new Uint8Array(0);
+    let contentFormat;
+    let accept;
+    let observe;
+    let oscore;
+    let block1;
+    let block2;
+    let size1;
+    let size2;
+    const seen = new Set();
+    while (offset < raw.length) {
+        if (raw[offset] === PAYLOAD_MARKER) {
+            offset++;
+            if (offset === raw.length)
+                throw new Error('CoAP payload marker without payload');
+            payload = raw.slice(offset);
+            offset = raw.length;
+            break;
+        }
+        const delta = (raw[offset] >> 4) & 0x0f;
+        const length = raw[offset] & 0x0f;
+        offset++;
+        const deltaValue = readExtendedOptionValue(delta, raw, offset);
+        offset = deltaValue.offset;
+        const lengthValue = readExtendedOptionValue(length, raw, offset);
+        offset = lengthValue.offset;
+        optionNumber += deltaValue.value;
+        if (optionNumber > 0xffff)
+            throw new Error('CoAP option number out of range');
+        if (offset + lengthValue.value > raw.length)
+            throw new Error('Truncated CoAP option value');
+        const value = raw.slice(offset, offset + lengthValue.value);
+        if (optionNumber !== exports.URI_PATH_OPTION && optionNumber !== exports.URI_QUERY_OPTION && seen.has(optionNumber)) {
+            throw new Error(`Duplicate CoAP option ${optionNumber}`);
+        }
+        if (optionNumber === exports.URI_HOST_OPTION) {
+            uriHost = new TextDecoder().decode(value);
+        }
+        else if (optionNumber === exports.URI_PORT_OPTION) {
+            uriPort = uintFromBytes(value);
+        }
+        else if (optionNumber === exports.URI_PATH_OPTION) {
+            const segment = new TextDecoder().decode(value);
+            if (segment.length === 0)
+                throw new Error('Empty CoAP Uri-Path segment');
+            path.push(segment);
+        }
+        else if (optionNumber === exports.URI_QUERY_OPTION) {
+            uriQuery.push(new TextDecoder().decode(value));
+        }
+        else if (optionNumber === exports.CONTENT_FORMAT_OPTION) {
+            contentFormat = uintFromBytes(value);
+        }
+        else if (optionNumber === exports.ACCEPT_OPTION) {
+            accept = uintFromBytes(value);
+        }
+        else if (optionNumber === exports.OBSERVE_OPTION) {
+            observe = uintFromBytes(value);
+        }
+        else if (optionNumber === exports.OSCORE_OPTION) {
+            oscore = value.slice();
+        }
+        else if (optionNumber === exports.BLOCK1_OPTION) {
+            block1 = decodeBlock(value);
+        }
+        else if (optionNumber === exports.BLOCK2_OPTION) {
+            block2 = decodeBlock(value);
+        }
+        else if (optionNumber === exports.SIZE1_OPTION) {
+            size1 = uintFromBytes(value);
+        }
+        else if (optionNumber === exports.SIZE2_OPTION) {
+            size2 = uintFromBytes(value);
+        }
+        seen.add(optionNumber);
+        offset += lengthValue.value;
+    }
+    const message = {
+        type,
+        messageId,
+        token,
+        path,
+        payload,
+        remote,
+        receivedAt: Date.now(),
+    };
+    if (uriHost !== undefined)
+        message.uriHost = uriHost;
+    if (uriPort !== undefined)
+        message.uriPort = uriPort;
+    if (uriQuery.length > 0)
+        message.uriQuery = uriQuery;
+    if (contentFormat !== undefined)
+        message.contentFormat = contentFormat;
+    if (accept !== undefined)
+        message.accept = accept;
+    if (observe !== undefined)
+        message.observe = observe;
+    if (oscore !== undefined)
+        message.oscore = oscore;
+    if (block1 !== undefined)
+        message.block1 = block1;
+    if (block2 !== undefined)
+        message.block2 = block2;
+    if (size1 !== undefined)
+        message.size1 = size1;
+    if (size2 !== undefined)
+        message.size2 = size2;
+    const codeClass = code >> 5;
+    if (codeClass === 0) {
+        const method = CODE_METHODS[code];
+        if (method)
+            message.method = method;
+    }
+    else {
+        message.responseCode = formatResponseCode(code);
+    }
+    return message;
+}
+function msgTypeCode(type) {
+    switch (type) {
+        case 'CON': return 0;
+        case 'NON': return 1;
+        case 'ACK': return 2;
+        case 'RST': return 3;
+    }
+}
+function typeFromCode(code) {
+    switch (code & 0x03) {
+        case 0: return 'CON';
+        case 1: return 'NON';
+        case 2: return 'ACK';
+        default: return 'RST';
+    }
+}
+function optionDeltaNibble(value) {
+    if (value <= 12)
+        return { nibble: value, extended: [] };
+    if (value <= 268)
+        return { nibble: 13, extended: [value - 13] };
+    return { nibble: 14, extended: [(value - 269) >> 8, (value - 269) & 0xff] };
+}
+function optionLengthNibble(value) {
+    if (value > MAX_OPTION_VALUE)
+        throw new Error('CoAP option value exceeds 65804 bytes');
+    if (value <= 12)
+        return { nibble: value, extended: [] };
+    if (value <= 268)
+        return { nibble: 13, extended: [value - 13] };
+    return { nibble: 14, extended: [(value - 269) >> 8, (value - 269) & 0xff] };
+}
+function readExtendedOptionValue(nibble, raw, offset) {
+    if (nibble <= 12)
+        return { value: nibble, offset };
+    if (nibble === 13) {
+        if (offset >= raw.length)
+            throw new Error('Truncated CoAP option delta/length');
+        return { value: raw[offset] + 13, offset: offset + 1 };
+    }
+    if (nibble === 14) {
+        if (offset + 1 >= raw.length)
+            throw new Error('Truncated CoAP option delta/length');
+        return { value: ((raw[offset] << 8) | raw[offset + 1]) + 269, offset: offset + 2 };
+    }
+    throw new Error('Invalid CoAP option delta/length nibble');
+}
+function encodeBlock(block) {
+    if (!Number.isInteger(block.num) || block.num < 0 || block.num > 0xfffff)
+        throw new Error(`Invalid CoAP block number ${block.num}`);
+    if (!Number.isInteger(block.sizeExponent) || block.sizeExponent < 0 || block.sizeExponent > 6) {
+        throw new Error(`Invalid CoAP block size exponent ${block.sizeExponent}`);
+    }
+    return ((block.num & 0xfffff) << 4) | (block.more ? 0x08 : 0) | block.sizeExponent;
+}
+function decodeBlock(value) {
+    const encoded = uintFromBytes(value);
+    const sizeExponent = encoded & 0x07;
+    if (sizeExponent === 7)
+        throw new Error('Reserved CoAP block size exponent');
+    return { num: encoded >>> 4, more: (encoded & 0x08) !== 0, sizeExponent };
+}
+function uintToBytes(value) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffffffff) {
+        throw new Error(`Invalid CoAP uint option value ${value}`);
+    }
+    if (value === 0)
+        return new Uint8Array(0);
+    const bytes = [];
+    let remaining = value;
+    while (remaining > 0) {
+        bytes.unshift(remaining & 0xff);
+        remaining = Math.floor(remaining / 256);
+    }
+    return Uint8Array.from(bytes);
+}
+function uintFromBytes(value) {
+    if (value.length > 4)
+        throw new Error('CoAP uint option exceeds 4 bytes');
+    let result = 0;
+    for (const byte of value)
+        result = result * 256 + byte;
+    return result;
+}
+function formatResponseCode(code) {
+    return `${(code >> 5) & 0x07}.${String(code & 0x1f).padStart(2, '0')}`;
+}
+function parseResponseCode(code) {
+    const match = /^([1-5])\.(\d{2})$/.exec(code);
+    if (!match)
+        throw new Error(`Invalid CoAP response code '${code}'`);
+    const detail = Number(match[2]);
+    if (detail > 31)
+        throw new Error(`Invalid CoAP response code '${code}'`);
+    return (Number(match[1]) << 5) | detail;
+}

package/dist/cjs/gateway.d.ts

@@ -0,0 +1,76 @@
+/**
+ * CoAP Edge Gateway — wires a CoapTransportPort into an EdgeRuntime.
+ *
+ * Requests are CON messages matched to responses by token and remote endpoint
+ * (RFC 7252 §5.3). Confirmable requests are retransmitted with exponential
+ * backoff until acknowledged or until the request deadline expires. An empty
+ * ACK keeps the request pending for a separate response, which is acknowledged
+ * before being handed to the caller.
+ *
+ * RFC 7641 observations keep a token registered after the initial response;
+ * later notifications with a fresh 24-bit Observe sequence are delivered to the
+ * caller and confirmable notifications are acknowledged.
+ */
+import type { EdgeRuntime, EdgeOperationResult } from '@totemsdk/edge';
+import type { CoapTransportPort, CoapBlockOption } from './transport.js';
+import type { CoapSecurityPort } from './security.js';
+export interface CoapGatewayTiming {
+    /** Overall request deadline in milliseconds. Default 10_000. */
+    requestTimeoutMs?: number;
+    /** Initial retransmission interval in milliseconds. Default 2_000. */
+    ackTimeoutMs?: number;
+    /** Maximum retransmissions before waiting for the deadline. Default 4. */
+    maxRetransmits?: number;
+}
+export interface CoapGatewayConfig {
+    runtime: EdgeRuntime;
+    transport: CoapTransportPort;
+    localPort: number;
+    timing?: CoapGatewayTiming;
+    /** Optional OSCORE boundary; protected endpoints fail closed without it. */
+    security?: CoapSecurityPort;
+    /** Transparent RFC 7959 blockwise transfer for large payloads. */
+    blockwise?: CoapBlockwiseOptions;
+}
+export interface CoapBlockwiseOptions {
+    /** Enable transparent blockwise transfer. Default true. */
+    enabled?: boolean;
+    /** Preferred block size in bytes (power of two, 16-1024). Default 1024. */
+    blockSize?: number;
+    /** Maximum assembled response body. Default 1 MiB. */
+    maxBodySize?: number;
+}
+export interface CoapResponseData {
+    payload: Uint8Array;
+    /** Content-Format option value, e.g. 0 text/plain or 60 application/cbor. */
+    contentFormat?: number;
+    /** Observe option value (notifications only). */
+    observe?: number;
+    /** Block1 option echoed by the server. */
+    block1?: CoapBlockOption;
+    /** Block2 option describing this response block. */
+    block2?: CoapBlockOption;
+    /** Size1 hint from the server. */
+    size1?: number;
+    /** Size2 hint (total response body size). */
+    size2?: number;
+}
+export interface CoapObservationData extends CoapResponseData {
+    observe: number;
+    receivedAt: number;
+}
+export interface CoapObservation {
+    /** Correlation token as lowercase hex. */
+    readonly token: string;
+    /** Deregister and stop delivering notifications. */
+    cancel(): Promise<void>;
+}
+export interface CoapGateway {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    readonly status: 'stopped' | 'running' | 'error';
+    get(path: string[], host: string, port: number): Promise<EdgeOperationResult<CoapResponseData>>;
+    post(path: string[], payload: Uint8Array, host: string, port: number): Promise<EdgeOperationResult<CoapResponseData>>;
+    observe(path: string[], host: string, port: number, handler: (notification: CoapObservationData) => void): Promise<EdgeOperationResult<CoapObservation>>;
+}
+export declare function createCoapGateway(config: CoapGatewayConfig): CoapGateway;