@netkitty/codec 1.0.0

package/dist/headers/MarkerProtocol.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MarkerProtocol = void 0;
+const BaseHeader_1 = require("../abstracts/BaseHeader");
+const BufferToHex_1 = require("../helper/BufferToHex");
+const HexToBuffer_1 = require("../helper/HexToBuffer");
+const BufferToNumber_1 = require("../helper/BufferToNumber");
+const NumberToBuffer_1 = require("../helper/NumberToBuffer");
+const StringContentEncodingEnum_1 = require("../lib/StringContentEncodingEnum");
+/**
+ * Marker Protocol — the Link Aggregation Marker Protocol (IEEE 802.3ad / 802.1AX), the second of the
+ * Slow Protocols carried directly in an Ethernet II frame with EtherType 0x8809 (an Ethernet child — no
+ * IP/UDP). It shares the frame type with LACP and is disambiguated by byte 0, the Slow-Protocols
+ * Subtype: 1 = LACP (claimed by the LACP header), 2 = Marker (claimed here). Byte 1 is the Version.
+ * What follows is a flat sequence of TLVs — each a 1-byte Type + 1-byte Length (the Length counts the 2
+ * header octets, so the value is Length-2 bytes) + value bytes: the Marker Information TLV (type 0x01,
+ * len 0x10) or Marker Response TLV (type 0x02, len 0x10) — carrying Requester_Port (2), Requester_System
+ * (6), Requester_Transaction_ID (4) and Pad (2) — then the Terminator (type 0x00, len 0x00). After the
+ * Terminator the PDU is padded with reserved octets to fill the fixed PDU length. Marker has no length
+ * field of its own — it runs to the end of the frame.
+ *
+ * TLVs are carried generically (type + on-wire length + verbatim hex value) so every TLV round-trips
+ * byte-for-byte; per-TLV semantic decoding (requester port/system/transaction id) is a later enrichment.
+ * The Length is honored verbatim on encode when supplied (a crafted PDU may lie), else derived from the
+ * value (2 + value bytes; 0 for the Terminator). The walk stops at the Terminator (type 0) or when the
+ * frame is exhausted; any bytes after the Terminator are the reserved padding, kept verbatim in
+ * `reserved` so the frame is reproduced exactly.
+ */
+class MarkerProtocol extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'marker';
+        this.name = 'Link Aggregation Marker Protocol';
+        this.nickname = 'Marker';
+        this.matchKeys = ['ethertype:8809'];
+        //A leaf header — nothing demuxes above the Marker Protocol.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (MarkerProtocol.#schemaCache ??= MarkerProtocol.#buildSchema());
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'Marker v${version} ${tlvs.length} TLVs',
+            properties: {
+                subtype: this.fieldUInt('subtype', 0, 1, 'Subtype'),
+                version: this.fieldUInt('version', 1, 1, 'Version'),
+                tlvs: {
+                    type: 'array',
+                    label: 'TLVs',
+                    items: {
+                        type: 'object',
+                        label: 'TLV',
+                        properties: {
+                            type: { type: 'integer', label: 'Type', minimum: 0, maximum: 255 },
+                            length: { type: 'integer', label: 'Length', minimum: 0, maximum: 255 },
+                            value: { type: 'string', label: 'Value', contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX }
+                        }
+                    },
+                    decode: function () {
+                        //The Marker PDU runs to the end of the frame — there is no length field. Bound the
+                        //walk by the remaining frame bytes. Each TLV is Type(1) + Length(1) + (Length-2)
+                        //value bytes; the on-wire Length counts the 2 header octets (the Terminator is the
+                        //exception: Length 0).
+                        const available = this.packet.length - this.startPos;
+                        const tlvs = [];
+                        let offset = 2;
+                        while (offset + 2 <= available) {
+                            const type = (0, BufferToNumber_1.BufferToUInt8)(this.readBytes(offset, 1));
+                            const length = (0, BufferToNumber_1.BufferToUInt8)(this.readBytes(offset + 1, 1));
+                            //Terminator (type 0): logical end of the PDU — anything after is reserved padding.
+                            if (type === 0) {
+                                tlvs.push({ type: type, length: length, value: '' });
+                                offset += 2;
+                                break;
+                            }
+                            //Value byte count = Length - 2 (Length includes the 2 header octets). A malformed
+                            //Length < 2 yields no value; a value that overruns the frame (truncation) is not
+                            //consumed — stop and leave the remaining bytes to `reserved`, keeping round-trip exact.
+                            const valueLength = length > 2 ? length - 2 : 0;
+                            if (offset + 2 + valueLength > available)
+                                break;
+                            const value = valueLength > 0 ? (0, BufferToHex_1.BufferToHex)(this.readBytes(offset + 2, valueLength)) : '';
+                            tlvs.push({ type: type, length: length, value: value });
+                            offset += 2 + valueLength;
+                        }
+                        this.instance.tlvs.setValue(tlvs);
+                        //Trailing bytes after the Terminator (or after a truncated TLV) are the reserved padding.
+                        this.instance.reserved.setValue(offset < available ? (0, BufferToHex_1.BufferToHex)(this.readBytes(offset, available - offset)) : '');
+                    },
+                    encode: function () {
+                        const tlvs = this.instance.tlvs.getValue([]);
+                        let offset = 2;
+                        if (tlvs) {
+                            for (let i = 0; i < tlvs.length; i++) {
+                                const tlv = tlvs[i];
+                                const type = tlv.type ? tlv.type : 0;
+                                const value = (0, HexToBuffer_1.HexToBuffer)(tlv.value ? tlv.value : '');
+                                //Length is honored verbatim when supplied (a crafted PDU may lie), else derived:
+                                //value bytes + the 2 header octets (0 for the Terminator, which carries no value).
+                                let length = (tlv.length !== undefined && tlv.length !== null)
+                                    ? tlv.length
+                                    : (type === 0 ? 0 : value.length + 2);
+                                if (length > 255) {
+                                    this.recordError(`tlvs[${i}].length`, 'Maximum value is 255');
+                                    length = 255;
+                                }
+                                if (length < 0) {
+                                    this.recordError(`tlvs[${i}].length`, 'Minimum value is 0');
+                                    length = 0;
+                                }
+                                this.writeBytes(offset, (0, NumberToBuffer_1.UInt8ToBuffer)(type & 0xff));
+                                this.writeBytes(offset + 1, (0, NumberToBuffer_1.UInt8ToBuffer)(length));
+                                offset += 2;
+                                if (value.length) {
+                                    this.writeBytes(offset, value);
+                                    offset += value.length;
+                                }
+                            }
+                        }
+                        const reserved = this.instance.reserved.getValue('');
+                        if (reserved)
+                            this.writeBytes(offset, (0, HexToBuffer_1.HexToBuffer)(reserved));
+                    }
+                },
+                //Reserved padding after the Terminator TLV, kept verbatim. No codec of its own — it is
+                //set/read by the `tlvs` field (which owns the single offset walk); this entry is metadata
+                //so the editor sees the padding bytes.
+                reserved: {
+                    type: 'string',
+                    label: 'Reserved',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    hidden: true
+                }
+            }
+        };
+    }
+    match() {
+        //An Ethernet child selected by EtherType 0x8809 (Slow Protocols, stored as a lowercase 4-hex
+        //string). Only Subtype 2 (Marker) is claimed — Subtype 1 (LACP) and others fall through. Require
+        //at least the 2-byte Subtype + Version so the subtype probe is in-bounds.
+        if (!this.prevCodecModule || this.prevCodecModule.id !== 'eth')
+            return false;
+        if (this.prevCodecModule.instance.etherType.getValue() !== '8809')
+            return false;
+        if (this.packet.length - this.startPos < 2)
+            return false;
+        return (0, BufferToNumber_1.BufferToUInt8)(this.readBytes(0, 1, true)) === 2;
+    }
+}
+exports.MarkerProtocol = MarkerProtocol;

package/dist/headers/Megaco.d.ts

@@ -0,0 +1,32 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * Megaco / H.248 (RFC 3525) — the Media Gateway Control protocol by which a Media Gateway Controller
+ * commands Media Gateways for VoIP, the ITU-T/IETF successor to MGCP. This codec handles the text
+ * (ABNF) encoding carried over UDP (well-known ports 2944 text / 2945 secure-text); the alternative
+ * binary ASN.1/BER encoding is a separate wire format and out of scope here.
+ *
+ * A text message begins with a header line `MEGACO/version SP mId` (the start token "MEGACO" or its
+ * short form "!", a slash, the protocol version, then the message identifier — an [ip]:port, domain
+ * name, device name or MTP address), followed by one or more Transaction blocks (`Transaction = id {
+ * Context = ... { commands } }`).
+ *
+ * Like SIP, MGCP and HTTP, the message body is text whose full internal structure (nested
+ * transaction/context/command/descriptor blocks, significant whitespace and token ordering) is far
+ * richer than a form needs. So the ENTIRE raw message is kept verbatim as the authoritative `message`
+ * field (hex) and re-emitted untouched; only the header line is parsed on decode into display-only
+ * metadata (start token / version / message identifier). Encode never reconstructs the message from
+ * the parsed fields — it writes `message` back byte-for-byte — so any conformant (or even malformed)
+ * Megaco message round-trips exactly.
+ */
+export declare class Megaco extends BaseHeader {
+    #private;
+    get SCHEMA(): ProtocolJSONSchema;
+    readonly id: string;
+    readonly name: string;
+    readonly nickname: string;
+    readonly matchKeys: string[];
+    match(): boolean;
+    readonly demuxProducers: DemuxProducer[];
+}

package/dist/headers/Megaco.js

@@ -0,0 +1,144 @@
+"use strict";
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Megaco = void 0;
+const BaseHeader_1 = require("../abstracts/BaseHeader");
+const BufferToHex_1 = require("../helper/BufferToHex");
+const HexToBuffer_1 = require("../helper/HexToBuffer");
+const StringContentEncodingEnum_1 = require("../lib/StringContentEncodingEnum");
+/**
+ * Megaco / H.248 (RFC 3525) — the Media Gateway Control protocol by which a Media Gateway Controller
+ * commands Media Gateways for VoIP, the ITU-T/IETF successor to MGCP. This codec handles the text
+ * (ABNF) encoding carried over UDP (well-known ports 2944 text / 2945 secure-text); the alternative
+ * binary ASN.1/BER encoding is a separate wire format and out of scope here.
+ *
+ * A text message begins with a header line `MEGACO/version SP mId` (the start token "MEGACO" or its
+ * short form "!", a slash, the protocol version, then the message identifier — an [ip]:port, domain
+ * name, device name or MTP address), followed by one or more Transaction blocks (`Transaction = id {
+ * Context = ... { commands } }`).
+ *
+ * Like SIP, MGCP and HTTP, the message body is text whose full internal structure (nested
+ * transaction/context/command/descriptor blocks, significant whitespace and token ordering) is far
+ * richer than a form needs. So the ENTIRE raw message is kept verbatim as the authoritative `message`
+ * field (hex) and re-emitted untouched; only the header line is parsed on decode into display-only
+ * metadata (start token / version / message identifier). Encode never reconstructs the message from
+ * the parsed fields — it writes `message` back byte-for-byte — so any conformant (or even malformed)
+ * Megaco message round-trips exactly.
+ */
+class Megaco extends BaseHeader_1.BaseHeader {
+    constructor() {
+        super(...arguments);
+        this.id = 'megaco';
+        this.name = 'Media Gateway Control Protocol (H.248/Megaco)';
+        this.nickname = 'Megaco';
+        this.matchKeys = ['udpport:2944', 'udpport:2945'];
+        //A leaf header — the nested transaction/context/command/descriptor structure and the transaction it
+        //belongs to are a higher-layer concern; the verbatim message preserves it byte-for-byte.
+        this.demuxProducers = [];
+    }
+    static #schemaCache;
+    get SCHEMA() {
+        return (_a.#schemaCache ??= _a.#buildSchema());
+    }
+    /**
+     * Bytes of this header: for UDP, bounded by the datagram length (so a retained FCS/padding is not
+     * absorbed); otherwise take the rest of the packet. Never negative.
+     */
+    #payloadLength() {
+        let available = this.packet.length - this.startPos;
+        if (this.prevCodecModule && this.prevCodecModule.id === 'udp') {
+            const udpLength = this.prevCodecModule.instance.length.getValue(0);
+            if (udpLength >= 8 && udpLength - 8 < available)
+                available = udpLength - 8;
+        }
+        return available < 0 ? 0 : available;
+    }
+    /** The first line of the message (up to the first CR or LF, or the whole payload if neither). */
+    static #firstLine(text) {
+        let end = text.length;
+        for (let i = 0; i < text.length; i++) {
+            const code = text.charCodeAt(i);
+            if (code === 0x0d || code === 0x0a) {
+                end = i;
+                break;
+            }
+        }
+        return text.slice(0, end);
+    }
+    /**
+     * Parse the header line into the display-only metadata fields. The line is
+     * `startToken/version SP mId` (e.g. "MEGACO/1 [123.123.123.4]:55555"). Populated on decode only —
+     * these fields have no encode, so they never affect the re-emitted bytes. Never throws: a missing
+     * token yields an empty string, a non-numeric version yields 0.
+     */
+    #parseHeaderLine(text) {
+        const line = _a.#firstLine(text).trim();
+        //Split the leading "startToken/version" token from the message identifier on the first space.
+        const spaceIdx = line.indexOf(' ');
+        const head = spaceIdx >= 0 ? line.slice(0, spaceIdx) : line;
+        const mId = spaceIdx >= 0 ? line.slice(spaceIdx + 1).trim() : '';
+        const slashIdx = head.indexOf('/');
+        const token = slashIdx >= 0 ? head.slice(0, slashIdx) : head;
+        const versionText = slashIdx >= 0 ? head.slice(slashIdx + 1) : '';
+        this.instance.startToken.setValue(token);
+        //Kept as the raw digit string (display-only), not a bounded integer: RFC 3525 versions are an
+        //unbounded 1*DIGIT, so a large value like "9999999999" must round-trip (the message hex is the
+        //authoritative source; encode never reads this field) without Ajv rejecting it on re-encode.
+        this.instance.version.setValue(versionText);
+        this.instance.messageId.setValue(mId);
+    }
+    static #buildSchema() {
+        return {
+            type: 'object',
+            summary: 'Megaco/${version} ${messageId}',
+            properties: {
+                //The whole raw message is the single source of truth: decoded verbatim to hex and
+                //re-emitted untouched (byte-perfect for any Megaco message). The header line is parsed
+                //into the display-only metadata below, which carry no codec of their own.
+                message: {
+                    type: 'string',
+                    label: 'Message',
+                    contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+                    decode: function () {
+                        const available = this.#payloadLength();
+                        if (available <= 0) {
+                            this.instance.message.setValue('');
+                            this.#parseHeaderLine('');
+                            return;
+                        }
+                        const raw = this.readBytes(0, available);
+                        this.instance.message.setValue((0, BufferToHex_1.BufferToHex)(raw));
+                        this.#parseHeaderLine(raw.toString('latin1'));
+                    },
+                    encode: function () {
+                        //Re-emit the authoritative message verbatim — never reconstruct from metadata.
+                        this.writeBytes(0, (0, HexToBuffer_1.HexToBuffer)(this.instance.message.getValue('')));
+                    }
+                },
+                //Display-only metadata parsed from the header line on decode (no encode — populated by the
+                //message field above, never read back). startToken is "MEGACO" (or "!" short form),
+                //version is the protocol version, messageId is the message identifier (mId).
+                startToken: { type: 'string', label: 'Start Token' },
+                version: { type: 'string', label: 'Version' },
+                messageId: { type: 'string', label: 'Message Identifier' }
+            }
+        };
+    }
+    match() {
+        //Megaco text encoding rides on UDP ports 2944 (text) / 2945 (secure text) as text. Recognize it
+        //by the header-line signature: the start token "MEGACO/" or its short form "!/" (case-insensitive
+        //start token) — so non-Megaco traffic on these ports falls through to raw rather than claiming an
+        //un-decodable text layer. Leading whitespace (LWSP) before the token is tolerated.
+        if (!this.prevCodecModule)
+            return false;
+        if (this.prevCodecModule.id !== 'udp')
+            return false;
+        if (this.#payloadLength() < 3)
+            return false;
+        const lead = this.readBytes(0, 16, true).toString('latin1').replace(/^[\s]+/, '');
+        const upper = lead.toUpperCase();
+        return upper.startsWith('MEGACO/') || lead.startsWith('!/');
+    }
+}
+exports.Megaco = Megaco;
+_a = Megaco;

package/dist/headers/Memcached.d.ts

@@ -0,0 +1,44 @@
+import { BaseHeader } from '../abstracts/BaseHeader';
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { DemuxProducer } from '../types/DemuxProducer';
+/**
+ * Memcached — the cache daemon's wire protocol, carried over TCP well-known port 11211. Memcached speaks
+ * TWO protocols on the same port, and this codec handles BOTH by branching on the first payload byte
+ * (the exact model of the SSH codec, which branches identification-vs-binary on a signature):
+ *
+ *  1. TEXT protocol (the classic, default). Line-based US-ASCII commands and replies terminated by CR LF:
+ *     `get <key>\r\n`, `set <key> <flags> <exptime> <bytes>\r\n<data>\r\n`, and replies such as
+ *     `VALUE <key> <flags> <bytes>\r\n<data>\r\nEND\r\n`, `STORED\r\n`, `END\r\n`, … Like the other
+ *     US-ASCII line protocols in this codec (POP3/FTP/SIP/HTTP), the exact bytes a peer sees are richer
+ *     than any structure a form needs (arbitrary keys, inline data blocks, pipelined commands), so the
+ *     ENTIRE payload is kept verbatim as the authoritative `message` field (hex) and re-emitted untouched;
+ *     only the leading token is parsed on decode into the display-only `command` field (get/set/VALUE/
+ *     STORED/…). Encode never reconstructs the payload from `command` — it writes `message` back
+ *     byte-for-byte, so any conformant (or malformed) text exchange round-trips exactly.
+ *
+ *  2. BINARY protocol (RFC-less, memcached's binary framing). A fixed 24-byte header —
+ *     magic(1: 0x80 request / 0x81 response) · opcode(1) · keyLength(2, BE) · extrasLength(1) ·
+ *     dataType(1) · vbucket-id/status(2, BE) · totalBodyLength(4, BE) · opaque(4) · cas(8) — followed by
+ *     `totalBodyLength` bytes of body (extras + key + value). This codec structures the 24-byte header as
+ *     editable fields and keeps the body verbatim as `body` hex, bounded by totalBodyLength (a trailing /
+ *     pipelined next message is left to the codec's recursion / RawData). The `cas` field is 8 bytes, so
+ *     it is kept as a HEX string (never a JS Number — 8 bytes exceeds 2^53 and would lose precision). A
+ *     well-formed binary message round-trips byte-for-byte.
+ *
+ * Matching rationale (NO heuristicFallback): Memcached is claimed ONLY on the tcp:11211 bucket. The binary
+ * header's magic (0x80/0x81) is a weak one-byte signature and the text protocol shares generic verbs
+ * (get/set/…) with countless other line protocols, so neither shape carries a signature strong enough to
+ * survive the global content-heuristic chain without mislabeling unrelated TCP traffic. Confining
+ * Memcached to its well-known port keeps recognition unambiguous; alt-port memcached is rare and falls
+ * losslessly to raw.
+ */
+export declare class Memcached extends BaseHeader {
+    #private;
+    get SCHEMA(): ProtocolJSONSchema;
+    readonly id: string;
+    readonly name: string;
+    readonly nickname: string;
+    readonly matchKeys: string[];
+    match(): boolean;
+    readonly demuxProducers: DemuxProducer[];
+}