matterbridge/dist/dgram/coap.d.ts

Matterbridge plugin manager for Matter

/**
 * @description This file contains the class Coap.
 * @file src/dgram/coap.ts
 * @author Luca Liguori
 * @created 2025-03-22
 * @version 1.0.0
 * @license Apache-2.0
 *
 * Copyright 2025, 2026, 2027 Luca Liguori.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
import dgram from 'node:dgram';
import { Multicast } from './multicast.js';
/**
 * Represents a CoAP message.
 *
 * A CoAP message is structured with a fixed header, an optional token, a series of options,
 * and an optional payload. The header consists of version, type, token length, code, and message ID.
 * The token is used to match responses with requests, options provide additional metadata, and
 * the payload carries the message content.
 */
export interface CoapMessage {
    /**
     * The CoAP protocol version.
     * Typically, this is 1.
     * (Stored in the top 2 bits of the first header byte.)
     */
    version: number;
    /**
     * The message type.
     * It indicates whether the message is Confirmable, Non-confirmable, Acknowledgement, or Reset.
     * (Stored in bits 5-4 of the first header byte.)
     * 0: Confirmable (CON)
     * 1: Non-confirmable (NON)
     * 2: Acknowledgement (ACK)
     * 3: Reset (RST)
     */
    type: number;
    /**
     * The token length.
     * This value (0-8) specifies the length of the token field.
     * (Stored in the lower 4 bits of the first header byte.)
     */
    tokenLength: number;
    /**
     * The message code.
     * It indicates the method or response code, e.g., GET, POST, or a success/error response.
     * (Stored in the second header byte.)
     * CoAP uses an 8‑bit Code field divided into a 3‑bit class and a 5‑bit detail. The code can be represented as X.XX (e.g. 0.01) and is defined in RFC 7252. Here are the standard CoAP codes:
     * Request Codes (Class 0)
     * 0.01 – 1-GET
     * Retrieve a resource.
     * 0.02 – 2-POST
     * Create a resource or trigger an action.
     * 0.03 – 3-PUT
     * Update or create a resource.
     * 0.04 – 4-DELETE
     * Remove a resource.
     * Success Response Codes (Class 2)
     * 2.00 – Empty / Success
     * Indicates an empty message or a successful request with no payload.
     * 2.01 – Created
     * The request resulted in a new resource being created.
     * 2.02 – Deleted
     * The resource was successfully deleted.
     * 2.03 – Valid
     * The response indicates that the resource is still valid (used with caching).
     * 2.04 – Changed
     * The resource was successfully modified.
     * 2.05 – Content
     * The response contains the requested content.
     * Client Error Response Codes (Class 4)
     * 4.00 – Bad Request
     * The request was malformed.
     * 4.01 – Unauthorized
     * The request requires authentication.
     * 4.02 – Bad Option
     * An option in the request was not understood or is unacceptable.
     * 4.03 – Forbidden
     * The server refuses to fulfill the request.
     * 4.04 – Not Found
     * The requested resource was not found.
     * 4.05 – Method Not Allowed
     * The request method is not supported for the target resource.
     * 4.06 – Not Acceptable
     * The server cannot generate a response matching the list of acceptable values.
     * 4.12 – Precondition Failed
     * A precondition given in the request evaluated to false.
     * 4.13 – Request Entity Too Large
     * The request payload is too large.
     * 4.15 – Unsupported Content-Format
     * The server does not support the content format of the request payload.
     * Server Error Response Codes (Class 5)
     * 5.00 – Internal Server Error
     * The server encountered an unexpected condition.
     * 5.01 – Not Implemented
     * The server does not support the requested method.
     * 5.02 – Bad Gateway
     * The server, while acting as a gateway or proxy, received an invalid response.
     * 5.03 – Service Unavailable
     * The server is currently unable to handle the request.
     * 5.04 – Gateway Timeout
     * The server did not receive a timely response from an upstream server.
     * 5.05 – Proxying Not Supported
     * The server does not support proxying for the requested resource.
     */
    code: number;
    /**
     * The message identifier.
     * This 16-bit field is used to match messages of type Acknowledgement/Reset with their corresponding requests.
     * (Stored in bytes 2-3 of the header.)
     */
    messageId: number;
    /**
     * The token.
     * A variable-length sequence (0-8 bytes) that helps match a request with its response.
     */
    token: Buffer;
    /**
     * An array of options.
     * Options carry additional information such as URI path, content format, etc., and are encoded using a delta mechanism.
     */
    options: CoapOption[];
    /**
     * The payload.
     * The actual content of the message, if present. It follows a payload marker (0xFF) if non-empty.
     */
    payload?: Buffer;
}
interface CoapOption {
    number: number;
    value: Buffer;
}
export declare const COAP_OPTION_URI_PATH = 11;
export declare const COIOT_OPTION_DEVID = 3332;
export declare const COIOT_OPTION_VALIDITY = 3412;
export declare const COIOT_OPTION_SERIAL = 3420;
export declare const COIOT_REQUEST_STATUS_ID = 56831;
export declare const COIOT_REQUEST_DESCRIPTION_ID = 56832;
export declare class Coap extends Multicast {
    constructor(name: string, multicastAddress: string, multicastPort: number, socketType: 'udp4' | 'udp6', reuseAddr?: boolean | undefined, interfaceName?: string, interfaceAddress?: string);
    onCoapMessage(message: CoapMessage, rinfo: dgram.RemoteInfo): void;
    onMessage(msg: Buffer, rinfo: dgram.RemoteInfo): void;
    /**
     * Decodes a CoAP message from a Buffer.
     *
     * @param {Buffer} msg - The Buffer containing the raw CoAP message.
     * @returns {CoapMessage} A parsed CoAP message object.
     * @throws Error if the message is malformed.
     */
    decodeCoapMessage(msg: Buffer): CoapMessage;
    /**
     * Encodes a CoAP message into a Buffer.
     *
     * @param {CoapMessage} msg - The CoAP message to encode.
     * @returns {Buffer} A Buffer representing the encoded CoAP message.
     * @throws Error if the message is malformed.
     */
    encodeCoapMessage(msg: CoapMessage): Buffer;
    /**
     * Converts a CoAP message type numeric value to its string representation.
     *
     * CoAP message types are:
     *  - 0: Confirmable (CON)
     *  - 1: Non-confirmable (NON)
     *  - 2: Acknowledgement (ACK)
     *  - 3: Reset (RST)
     *
     * @param {number} type - The numeric CoAP message type.
     * @returns {string} The string representation of the message type.
     */
    coapTypeToString(type: number): string;
    /**
     * Converts a CoAP code numeric value to its string representation.
     *
     * The CoAP code is split into a 3-bit class and a 5-bit detail.
     * For example:
     *   - 0.01: GET
     *   - 0.02: POST
     *   - 0.03: PUT
     *   - 0.04: DELETE
     *   - 2.05: Content (success response)
     *   - 4.04: Not Found (client error)
     *   - 5.00: Internal Server Error (server error)
     *
     * @param {number} code - The numeric CoAP code.
     * @returns {string} The string representation of the code.
     */
    coapCodeToString(code: number): string;
    sendRequest(messageId: number, options: CoapOption[], payload: Record<string, any> | undefined, token: string | undefined, address: string | undefined, port: number | undefined): void;
    logCoapMessage(msg: CoapMessage): void;
}
export {};
//# sourceMappingURL=coap.d.ts.map