@netkitty/codec 1.0.0

package/dist/abstracts/BaseHeader.js

@@ -0,0 +1,734 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseHeader = void 0;
+const SortPostHandlers_1 = require("../lib/SortPostHandlers");
+const FlexibleObject_1 = require("../lib/FlexibleObject");
+const ajv_1 = require("ajv");
+const CodecSchemaValidateError_1 = require("../errors/CodecSchemaValidateError");
+const BufferToNumber_1 = require("../helper/BufferToNumber");
+const NumberToBuffer_1 = require("../helper/NumberToBuffer");
+const BufferToHex_1 = require("../helper/BufferToHex");
+const HexToBuffer_1 = require("../helper/HexToBuffer");
+const BufferToIP_1 = require("../helper/BufferToIP");
+const IPToBuffer_1 = require("../helper/IPToBuffer");
+const StringContentEncodingEnum_1 = require("../lib/StringContentEncodingEnum");
+const CONSTRUCTOR_VALIDATE_KEY = '__validate';
+//Per-codec-class cached MATCH probe. Content-heuristic selection calls MATCH() on many candidates
+//per layer; each used to build a whole fresh instance (rebuilding the SCHEMA) just to run match().
+//Since match() only inspects the previous layer and the raw buffer, one reusable probe per class
+//suffices — see BaseHeader.MATCH / bindContext.
+const MATCH_PROBE_KEY = '__matchProbe';
+/**
+ * The base class every protocol header extends, and the surface a custom-codec author works against.
+ *
+ * A subclass declares a `SCHEMA` (an executable JSON Schema whose fields carry per-field
+ * `decode`/`encode` closures), a stable `id`/`name`/`nickname`, and a `match()` that decides —
+ * by inspecting the previously decoded layers (`prevCodecModule`/`prevCodecModules`) — whether
+ * this header applies at the current offset. Optional `matchKeys`/`demuxProducers` wire the
+ * header into the codec's O(1) dispatch table instead of the content-heuristic chain.
+ *
+ * Field closures read and write the shared packet buffer through the header-relative helpers
+ * `readBytes`/`writeBytes` (whole octets) and `readBits`/`writeBits` (bit fields), which
+ * auto-expand the buffer on write, and store values on the path-tracking `instance`. Malformed
+ * input is reported via `recordError()` rather than thrown, so decode/encode never crash. Headers
+ * register cross-field/cross-layer fixups (lengths, checksums) with the post-handler methods
+ * (`addPostSelfEncodeHandler`/`addPostSelfDecodeHandler` for layer-internal, `addPostPacketEncodeHandler`/
+ * `addPostPacketDecodeHandler` for packet-level).
+ */
+class BaseHeader {
+    static get CODEC_INSTANCE() {
+        return new this();
+    }
+    static CREATE_CODEC_INSTANCE_WITCH_CODEC_MODULES(codecData, codecModules) {
+        return this.CREATE_INSTANCE(codecData, codecModules);
+    }
+    static get PROTOCOL_ID() {
+        return this.CODEC_INSTANCE.id;
+    }
+    static get PROTOCOL_NAME() {
+        return this.CODEC_INSTANCE.name;
+    }
+    /**
+     * Demux keys this header registers in the codec dispatch table.
+     * Empty (the default) means the header is matched by its content-heuristic
+     * match() instead of by an upper-layer demultiplexing value.
+     */
+    static get MATCH_KEYS() {
+        return this.CODEC_INSTANCE.matchKeys;
+    }
+    /**
+     * Demux keys this header produces for its child layer (from its own field values). Reversed by the
+     * codec to route the next layer, and read by the editor projection. Empty (the default) means this
+     * header is a leaf — nothing demuxes off it.
+     */
+    static get DEMUX_PRODUCERS() {
+        return this.CODEC_INSTANCE.demuxProducers;
+    }
+    /**
+     * When true, this header is also placed in the content-heuristic fallback list even though it has
+     * demux matchKeys. Lets a protocol with a reliable content signature (TLS, IEC104) take the O(1)
+     * bucket on its well-known port yet still be recognized on any other port via its match(). Default
+     * false: matchKeys → bucket only; no matchKeys → heuristic only.
+     */
+    static get HEURISTIC_FALLBACK() {
+        return this.CODEC_INSTANCE.heuristicFallback;
+    }
+    /** Higher is tried first within a demux bucket and within the heuristic chain; ties keep registration order. */
+    static get MATCH_PRIORITY() {
+        return this.CODEC_INSTANCE.matchPriority;
+    }
+    static get PROTOCOL_SCHEMA() {
+        const schema = JSON.parse(JSON.stringify(this.CODEC_INSTANCE.SCHEMA));
+        if (!Object.hasOwn(this, CONSTRUCTOR_VALIDATE_KEY)) {
+            const validate = new ajv_1.Ajv({
+                strict: false,
+                useDefaults: true,
+                coerceTypes: true
+            }).compile(schema);
+            Object.defineProperty(this, CONSTRUCTOR_VALIDATE_KEY, {
+                enumerable: false,
+                configurable: false,
+                value: validate
+            });
+        }
+        return schema;
+    }
+    static MATCH(codecData, codecModules) {
+        //Reuse one cached probe instance per codec class instead of rebuilding a full instance (and its
+        //SCHEMA) for every candidate. match() only reads the previous layer and the raw buffer, never
+        //this header's SCHEMA/instance, so rebinding context is enough. selectCodec runs synchronously,
+        //so the shared probe never overlaps across concurrent decodes.
+        let probe = Object.hasOwn(this, MATCH_PROBE_KEY) ? this[MATCH_PROBE_KEY] : undefined;
+        if (!probe) {
+            probe = new this();
+            Object.defineProperty(this, MATCH_PROBE_KEY, { enumerable: false, configurable: false, value: probe });
+        }
+        probe.bindContext(codecData, codecModules ? codecModules : []);
+        return probe.match();
+    }
+    static CREATE_INSTANCE(codecData, codecModules) {
+        return new this(codecData, codecModules);
+    }
+    //Dissect-only instrumentation: when #byteRanges is non-null, each field read records the packet
+    //span it covered (keyed by the field being decoded). Off (null) during normal decode/encode, so
+    //the hot path is untouched. See enableByteRangeTracking() / getByteRanges().
+    #byteRanges;
+    #currentFieldPath;
+    /**
+     * Turn on byte-range collection for a dissect pass (call before decode()). Additive and
+     * read-only: it changes nothing about the decoded values, only records where each field lives.
+     */
+    enableByteRangeTracking() {
+        this.#byteRanges = new Map();
+    }
+    /** The byte span each field occupied, or null if this header was not dissected. */
+    getByteRanges() {
+        return this.#byteRanges;
+    }
+    /**
+     * Entire packet buffer data getter
+     */
+    get packet() {
+        //Expose only the logical bytes. When physical === logical (the decode path never grows the
+        //buffer) return it directly with zero allocation; only slice a view when encode left headroom.
+        const buffer = this.codecData.packet;
+        const length = this.codecData.packetLength;
+        return (length === undefined || length === buffer.length) ? buffer : buffer.subarray(0, length);
+    }
+    /**
+     * Entire packet buffer data setter
+     * @param packet
+     */
+    set packet(packet) {
+        this.codecData.packet = packet;
+        this.codecData.packetLength = packet.length;
+    }
+    /**
+     * The end position of this header in the entire packet's buffer
+     */
+    get endPos() {
+        return this.startPos + this.headerLength;
+    }
+    /**
+     * Readonly Header length
+     */
+    get length() {
+        return this.headerLength;
+    }
+    /**
+     * Post packet handlers
+     * @protected
+     */
+    get postPacketHandlers() {
+        if (this.codecData.postHandlers[this.headerIndex] === undefined)
+            this.codecData.postHandlers[this.headerIndex] = [];
+        return this.codecData.postHandlers[this.headerIndex];
+    }
+    constructor(codecData, codecModules) {
+        /**
+         * Current header is a protocol or not
+         */
+        this.isProtocol = true;
+        /**
+         * Upper-layer demultiplexing keys that select this header, e.g.
+         * ['ethertype:0800'] or ['ipproto:6']. Registered in the codec dispatch
+         * table for O(1) selection during decode. Leave empty for headers that
+         * must inspect their own bytes to match (TLS, IEC104, tunnels); those fall
+         * back to the content-heuristic match() list.
+         */
+        this.matchKeys = [];
+        /**
+         * Demux keys this header produces for its child (see DemuxProducer). Declared per-schema so a new
+         * demux dimension (port, GUID, …) is a per-protocol declaration, not a core change. Default: none
+         * (a leaf header). Example: Ethernet declares `[{field:'etherType', namespace:'ethertype',
+         * kind:'string'}]`; IPv4 declares `[{field:'protocol', namespace:'ipproto', kind:'uint'}]`.
+         */
+        this.demuxProducers = [];
+        /**
+         * Also register in the content-heuristic fallback list despite having matchKeys — so a
+         * content-signed protocol keeps working off its well-known port. See static HEURISTIC_FALLBACK.
+         */
+        this.heuristicFallback = false;
+        /** Selection priority within a bucket / the heuristic chain (higher first; ties keep registration order). */
+        this.matchPriority = 0;
+        /**
+         * Encode/Decode error info objects
+         */
+        this.errors = [];
+        /**
+         * Header schema instance
+         */
+        this.instance = new FlexibleObject_1.FlexibleObject();
+        //Dissect-only instrumentation: when #byteRanges is non-null, each field read records the packet
+        //span it covered (keyed by the field being decoded). Off (null) during normal decode/encode, so
+        //the hot path is untouched. See enableByteRangeTracking() / getByteRanges().
+        this.#byteRanges = null;
+        this.#currentFieldPath = '';
+        /**
+         * The start position of this header in the entire packet's buffer
+         */
+        this.startPos = 0;
+        /**
+         * Header length
+         * @protected
+         */
+        this.headerLength = 0;
+        /**
+         * Current header index in packet headers
+         * @protected
+         */
+        this.headerIndex = 0;
+        /**
+         * Registered post encode handlers (CodecModule)
+         * @protected
+         */
+        this.postSelfEncodeHandlers = [];
+        /**
+         * Registered post decode handlers (CodecModule)
+         * @protected
+         */
+        this.postSelfDecodeHandlers = [];
+        this.bindContext(codecData, codecModules);
+    }
+    /**
+     * (Re)bind this instance's decode/match context. Extracted from the constructor so the static
+     * MATCH probe can reuse a single cached instance across heuristic candidates instead of rebuilding
+     * the whole SCHEMA for each — match() only reads the previous layer and the raw buffer.
+     */
+    bindContext(codecData, codecModules) {
+        this.codecData = codecData;
+        this.startPos = codecData?.startPos ? codecData.startPos : 0;
+        codecModules = codecModules ? codecModules : [];
+        this.codecModules = codecModules;
+        this.prevCodecModules = [...codecModules];
+        const prevCodecModuleIndex = this.prevCodecModules.length - 1;
+        this.prevCodecModule = this.prevCodecModules[prevCodecModuleIndex > -1 ? prevCodecModuleIndex : 0];
+        this.headerIndex = this.prevCodecModules.length;
+    }
+    /**
+     * Get packet data offset
+     * @param offset
+     * @protected
+     */
+    getPacketOffset(offset) {
+        return this.startPos + offset;
+    }
+    /**
+     * Internal read bytes from buffer
+     * @param offset
+     * @param length
+     * @param expandBufferLength
+     * @param changeHeaderLength
+     * @private
+     */
+    #readBytes(offset, length, expandBufferLength, changeHeaderLength) {
+        const packetOffset = this.getPacketOffset(offset);
+        let readEndPos = packetOffset + length;
+        const codecData = this.codecData;
+        const logicalLength = codecData.packetLength ?? codecData.packet.length;
+        if (logicalLength < readEndPos) {
+            if (expandBufferLength) {
+                if (codecData.packet.length < readEndPos) {
+                    //Amortized doubling: a run of small field writes grows the buffer O(log n) times
+                    //instead of reallocating + copying the whole packet on every write (O(n^2)). Only the
+                    //logical bytes are copied forward; the headroom stays zero-filled from Buffer.alloc.
+                    const capacity = Math.max(readEndPos, codecData.packet.length * 2);
+                    const grown = Buffer.alloc(capacity, 0);
+                    codecData.packet.copy(grown, 0, 0, logicalLength);
+                    codecData.packet = grown;
+                }
+                codecData.packetLength = readEndPos;
+            }
+            else {
+                readEndPos = logicalLength;
+            }
+        }
+        const headerLength = readEndPos - this.startPos;
+        if (changeHeaderLength)
+            this.headerLength = this.headerLength < headerLength ? headerLength : this.headerLength;
+        //Dissect instrumentation: attribute this read's absolute span to the field being decoded,
+        //extending the field's range if it reads more than once (e.g. an address + its value).
+        if (this.#byteRanges && this.#currentFieldPath) {
+            const existing = this.#byteRanges.get(this.#currentFieldPath);
+            if (existing) {
+                const start = Math.min(existing.offset, packetOffset);
+                const end = Math.max(existing.offset + existing.length, packetOffset + length);
+                this.#byteRanges.set(this.#currentFieldPath, { offset: start, length: end - start });
+            }
+            else {
+                this.#byteRanges.set(this.#currentFieldPath, { offset: packetOffset, length: length });
+            }
+        }
+        //Clamp the returned view to readEndPos (which the branches above already clamped to the logical
+        //length on a non-expanding out-of-range read), so encode-time forward reads past the write
+        //high-water mark stay truncated exactly as before rather than exposing zero-filled headroom.
+        return this.codecData.packet.subarray(packetOffset, readEndPos);
+    }
+    /**
+     * Read bytes from buffer
+     * @param offset
+     * @param length
+     * @param dryRun
+     * @protected
+     */
+    readBytes(offset, length, dryRun = false) {
+        return this.#readBytes(offset, length, false, !dryRun);
+    }
+    /**
+     * Write bytes to buffer
+     * @param offset
+     * @param buffer
+     * @protected
+     */
+    writeBytes(offset, buffer) {
+        const packetOffset = this.getPacketOffset(offset);
+        const writeEndPos = packetOffset + buffer.length;
+        this.#readBytes(offset, buffer.length, true, true);
+        this.codecData.packet.fill(buffer, packetOffset, writeEndPos);
+    }
+    /**
+     * Read bits from buffer
+     * @param offset
+     * @param length
+     * @param bitOffset
+     * @param bitLength
+     * @protected
+     */
+    readBits(offset, length, bitOffset, bitLength) {
+        const buffer = this.#readBytes(offset, length, false, true);
+        //MSB-first bit extraction over a `length`-octet window. Available bytes occupy the low end;
+        //missing (truncated) high bits read as 0.
+        const shift = length * 8 - bitOffset - bitLength;
+        if (shift < 0)
+            return 0;
+        if (length <= 4) {
+            //A window of ≤4 octets (≤32 bits) fits a JS number exactly — skip BigInt boxing. Use
+            //arithmetic (not <</>>, which are 32-bit-signed in JS) so 32-bit widths stay correct.
+            let narrow = 0;
+            for (const byte of buffer)
+                narrow = narrow * 256 + byte;
+            return Math.floor(narrow / 2 ** shift) % (2 ** bitLength);
+        }
+        //Wider windows (48/64-bit GOOSE/SV fields) keep full precision via BigInt.
+        let value = 0n;
+        for (const byte of buffer)
+            value = (value << 8n) | BigInt(byte);
+        const mask = (1n << BigInt(bitLength)) - 1n;
+        return Number((value >> BigInt(shift)) & mask);
+    }
+    /**
+     * Write bits to buffer
+     * @param offset
+     * @param length
+     * @param bitOffset
+     * @param bitLength
+     * @param value
+     * @protected
+     */
+    writeBits(offset, length, bitOffset, bitLength, value) {
+        const buffer = this.#readBytes(offset, length, true, true);
+        //Overlay `bitLength` bits of `value` at `bitOffset` (MSB-first) into the octet window. Only
+        //the low `bitLength` bits of value are written (out-of-range values wrap, matching a
+        //fixed-width field), and encode never crashes.
+        const out = Buffer.alloc(buffer.length);
+        if (length <= 4) {
+            //≤32-bit window: plain number arithmetic, no BigInt boxing. Split the window into the
+            //untouched high part, the target field, and the low part, then reassemble — all via
+            //multiply/divide/modulo to stay correct at 32-bit widths (JS bit-ops are 32-bit-signed).
+            let current = 0;
+            for (const byte of buffer)
+                current = current * 256 + byte;
+            const shift = buffer.length * 8 - bitOffset - bitLength;
+            const modulo = 2 ** bitLength;
+            const divisor = 2 ** shift;
+            const field = (((Math.trunc(Number(value)) || 0) % modulo) + modulo) % modulo;
+            const blockSize = modulo * divisor;
+            let written = Math.floor(current / blockSize) * blockSize + field * divisor + current % divisor;
+            for (let i = buffer.length - 1; i >= 0; i--) {
+                out[i] = written % 256;
+                written = Math.floor(written / 256);
+            }
+            this.writeBytes(offset, out);
+            return;
+        }
+        //Wider windows keep exact via BigInt.
+        let current = 0n;
+        for (const byte of buffer)
+            current = (current << 8n) | BigInt(byte);
+        const shift = BigInt(buffer.length * 8 - bitOffset - bitLength);
+        const fieldMask = (1n << BigInt(bitLength)) - 1n;
+        const field = (BigInt(Math.trunc(Number(value)) || 0) & fieldMask) << shift;
+        const written = (current & ~(fieldMask << shift)) | field;
+        let v = written;
+        for (let i = buffer.length - 1; i >= 0; i--) {
+            out[i] = Number(v & 0xffn);
+            v >>= 8n;
+        }
+        this.writeBytes(offset, out);
+    }
+    // ===== Field building blocks =====
+    // Declarative field factories: one call yields the whole {type,label,min,max,decode,encode}
+    // schema field, generating the decode/encode twin from a single declaration so the byte offset
+    // and width live in one place (not duplicated across two hand-mirrored closures — the source of
+    // the historical decode≠encode bugs). Closures re-resolve this.instance[name] at run time because
+    // encode swaps in a fresh instance. Irregular fields keep their hand-written closures (escape hatch).
+    /**
+     * An unsigned big-endian integer field of `byteLength` octets at `offset`. Decode reads it into
+     * `name`; encode clamps to the field's range (recording an error, never throwing) and writes it —
+     * byte-for-byte identical to the hand-written pattern it replaces.
+     * @protected
+     */
+    static fieldUInt(name, offset, byteLength, label) {
+        const maximum = byteLength === 1 ? 255 : byteLength === 2 ? 65535 : 4294967295;
+        const read = byteLength === 1 ? BufferToNumber_1.BufferToUInt8 : byteLength === 2 ? BufferToNumber_1.BufferToUInt16 : BufferToNumber_1.BufferToUInt32;
+        const write = byteLength === 1 ? NumberToBuffer_1.UInt8ToBuffer : byteLength === 2 ? NumberToBuffer_1.UInt16ToBuffer : NumberToBuffer_1.UInt32ToBuffer;
+        return {
+            type: 'integer',
+            label: label,
+            minimum: 0,
+            maximum: maximum,
+            decode: function () {
+                this.instance[name].setValue(read(this.readBytes(offset, byteLength)));
+            },
+            encode: function () {
+                const node = this.instance[name];
+                let value = node.getValue(0, (nodePath) => this.recordError(nodePath, 'Not Found'));
+                if (value > maximum) {
+                    this.recordError(node.getPath(), `Maximum value is ${maximum}`);
+                    value = maximum;
+                }
+                if (value < 0) {
+                    this.recordError(node.getPath(), 'Minimum value is 0');
+                    value = 0;
+                }
+                node.setValue(value);
+                this.writeBytes(offset, write(value));
+            }
+        };
+    }
+    /**
+     * A signed 8-bit integer field at `offset` (e.g. NTP poll/precision — power-of-two exponents).
+     * Decode reads it as int8 into `name`; encode clamps to [-128, 127] (recording an error, never
+     * throwing) and writes it — byte-for-byte identical to a hand-written int8 field for in-range values.
+     * @protected
+     */
+    static fieldInt8(name, offset, label) {
+        return {
+            type: 'integer',
+            label: label,
+            minimum: -128,
+            maximum: 127,
+            decode: function () {
+                this.instance[name].setValue((0, BufferToNumber_1.BufferToInt8)(this.readBytes(offset, 1)));
+            },
+            encode: function () {
+                const node = this.instance[name];
+                let value = node.getValue(0, (nodePath) => this.recordError(nodePath, 'Not Found'));
+                if (value > 127) {
+                    this.recordError(node.getPath(), 'Maximum value is 127');
+                    value = 127;
+                }
+                if (value < -128) {
+                    this.recordError(node.getPath(), 'Minimum value is -128');
+                    value = -128;
+                }
+                node.setValue(value);
+                this.writeBytes(offset, (0, NumberToBuffer_1.Int8ToBuffer)(value));
+            }
+        };
+    }
+    /**
+     * A raw byte field of `byteLength` octets at `offset`, kept verbatim as a lower-case hex string
+     * (e.g. NTP timestamps / reference id — bytes an editor should see and round-trip untouched).
+     * Decode reads the bytes to hex; encode writes the hex back (default: all-zero). Byte-for-byte
+     * identical to the hand-written pattern it replaces.
+     * @protected
+     */
+    static fieldHex(name, offset, byteLength, label) {
+        const zero = '00'.repeat(byteLength);
+        return {
+            type: 'string',
+            label: label,
+            contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.HEX,
+            decode: function () {
+                this.instance[name].setValue((0, BufferToHex_1.BufferToHex)(this.readBytes(offset, byteLength)));
+            },
+            encode: function () {
+                this.writeBytes(offset, (0, HexToBuffer_1.HexToBuffer)(this.instance[name].getValue(zero)));
+            }
+        };
+    }
+    /**
+     * A 4-octet IPv4 address field at `offset`, stored as a dotted-quad string (e.g. DHCP
+     * ciaddr/yiaddr/siaddr/giaddr). Decode reads it to `a.b.c.d`; encode writes it back (default
+     * '0.0.0.0', recording a Not Found error if the value is missing). Byte-for-byte identical to the
+     * hand-written IPv4-address pattern (see IPv4.sip/dip).
+     * @protected
+     */
+    static fieldIPv4(name, offset, label) {
+        return {
+            type: 'string',
+            label: label,
+            //Match IPv4.sip/dip exactly: the same length bounds + ipv4 content encoding, so Ajv
+            //validation and the editor's field metadata are identical to the hand-written pattern.
+            minLength: 7,
+            maxLength: 15,
+            contentEncoding: StringContentEncodingEnum_1.StringContentEncodingEnum.IPv4,
+            decode: function () {
+                this.instance[name].setValue((0, BufferToIP_1.BufferToIPv4)(this.readBytes(offset, 4)));
+            },
+            encode: function () {
+                const node = this.instance[name];
+                const value = node.getValue('0.0.0.0', (nodePath) => this.recordError(nodePath, 'Not Found'));
+                node.setValue(value);
+                this.writeBytes(offset, (0, IPToBuffer_1.IPv4ToBuffer)(value));
+            }
+        };
+    }
+    /**
+     * Get field codecs from schema tree
+     * @param schema
+     * @param codecName
+     * @param execBeforeSubCodecs
+     * @param codecs
+     * @protected
+     */
+    getFieldCodecs(schema, codecName, execBeforeSubCodecs, codecs = [], paths = null, pathPrefix = '') {
+        if (!schema.properties)
+            return codecs;
+        for (const propertyName of Object.keys(schema.properties)) {
+            const fieldSchema = schema.properties[propertyName];
+            const codec = fieldSchema[codecName];
+            //Push the raw closure (no async double-wrap) and skip fields with no codec entirely, so
+            //decode/encode call each synchronously and only await genuine Promises. When `paths` is
+            //provided (dissect only) a dotted field path is collected in parallel; otherwise there is
+            //zero extra cost on the hot path (no per-field object, no string concat).
+            const path = paths ? (pathPrefix ? `${pathPrefix}.${propertyName}` : propertyName) : '';
+            if (execBeforeSubCodecs && codec) {
+                codecs.push(codec);
+                if (paths)
+                    paths.push(path);
+            }
+            if (fieldSchema.properties)
+                this.getFieldCodecs(fieldSchema, codecName, execBeforeSubCodecs, codecs, paths, path);
+            if (!execBeforeSubCodecs && codec) {
+                codecs.push(codec);
+                if (paths)
+                    paths.push(path);
+            }
+        }
+        return codecs;
+    }
+    /**
+     * Record encode/decode error
+     * @param path
+     * @param message
+     * @protected
+     */
+    recordError(path, message) {
+        this.errors.push({
+            id: this.id,
+            path: path,
+            message: message
+        });
+    }
+    /**
+     * Register post encode handler for current codec
+     * @param handler
+     * @param priority
+     * @protected
+     */
+    addPostSelfEncodeHandler(handler, priority = 0) {
+        this.postSelfEncodeHandlers.push({
+            priority: priority,
+            handler: handler
+        });
+    }
+    /**
+     * Register post decode handler for current codec
+     * @param handler
+     * @param priority
+     * @protected
+     */
+    addPostSelfDecodeHandler(handler, priority = 0) {
+        this.postSelfDecodeHandlers.push({
+            priority: priority,
+            handler: handler
+        });
+    }
+    /**
+     * Register post encode handler for packet
+     * @description Registered handler call sequence: LIFO (Last In First Out)
+     * @param handler
+     * @param priority
+     * @protected
+     */
+    addPostPacketEncodeHandler(handler, priority = 0) {
+        this.postPacketHandlers.push({
+            priority: priority,
+            handler: handler
+        });
+    }
+    /**
+     * Register post decode handler for packet
+     * @description Registered handler call sequence: FIFO (First In First Out)
+     * @param handler
+     * @param priority
+     * @protected
+     */
+    addPostPacketDecodeHandler(handler, priority = 0) {
+        this.postPacketHandlers.push({
+            priority: priority,
+            handler: handler
+        });
+    }
+    /**
+     * Validate input json node is valid
+     * @param headerTreeNode
+     */
+    validate(headerTreeNode) {
+        let validate = this.constructor[CONSTRUCTOR_VALIDATE_KEY];
+        if (!validate) {
+            validate = new ajv_1.Ajv({
+                strict: false,
+                useDefaults: true,
+                coerceTypes: true
+            }).compile(this.SCHEMA);
+            this.constructor[CONSTRUCTOR_VALIDATE_KEY] = validate;
+        }
+        const isValid = validate(headerTreeNode);
+        if (!isValid) {
+            let errorObject;
+            if (validate.errors)
+                errorObject = validate.errors[0];
+            const errorMessage = errorObject?.message ? errorObject.message : 'Unknown Error';
+            throw new CodecSchemaValidateError_1.CodecSchemaValidateError(errorMessage);
+        }
+        return headerTreeNode;
+    }
+    /**
+     * Decode packet header field by field
+     */
+    async decode() {
+        const paths = this.#byteRanges ? [] : null;
+        const decodes = this.getFieldCodecs(this.SCHEMA, 'decode', true, [], paths);
+        for (let i = 0; i < decodes.length; i++) {
+            //Decode must never throw (error-accumulation contract): a truncated/corrupt packet can
+            //make a field's byte read run past the buffer or hit an invalid value. Contain that to a
+            //recorded error so the remaining fields and layers still decode best-effort.
+            //Call synchronously and only await genuine Promises — the vast majority of field
+            //closures are synchronous, so this avoids a promise allocation + scheduler turn per field.
+            if (paths)
+                this.#currentFieldPath = paths[i];
+            try {
+                //Invoke with the current instance as `this`. Arrow closures (headers not yet migrated)
+                //ignore the binding and use their captured lexical this — the same instance — so this is
+                //behaviour-neutral for them; migrated headers use plain functions whose dynamic `this`
+                //this provides, letting their SCHEMA be class-cached instead of rebuilt per packet.
+                const result = decodes[i].call(this);
+                if (result && typeof result.then === 'function')
+                    await result;
+            }
+            catch (e) {
+                this.recordError('', `Decode error: ${e.message}`);
+            }
+        }
+        //Post-handler reads (cross-field/cross-layer fixups) are not a single field's bytes — clear
+        //the tracked path so they are not attributed to whichever field decoded last.
+        this.#currentFieldPath = '';
+        const postSelfDecodeHandlers = (0, SortPostHandlers_1.SortPostHandlers)(this.postSelfDecodeHandlers);
+        let postDecodeHandler = postSelfDecodeHandlers.shift();
+        while (postDecodeHandler) {
+            try {
+                await postDecodeHandler.handler();
+            }
+            catch (e) {
+                this.recordError('', `Decode error: ${e.message}`);
+            }
+            postDecodeHandler = postSelfDecodeHandlers.shift();
+        }
+    }
+    /**
+     * Encode packet header field by field
+     */
+    async encode() {
+        const encodes = this.getFieldCodecs(this.SCHEMA, 'encode', false);
+        for (const encode of encodes) {
+            //Shape validation is the deliberate fast-fail at the encode entry point (Ajv, in
+            //Codec.#encode); it runs before we get here. Past that, a field's encode closure must
+            //not crash the whole encode on an edge-case value — contain it to a recorded error so
+            //the packet still assembles best-effort (matches the decode contract).
+            //Synchronous fast-path (see decode): only await a genuinely returned Promise.
+            try {
+                //See decode: .call(this) is neutral for arrow closures, dynamic-`this` for migrated ones.
+                const result = encode.call(this);
+                if (result && typeof result.then === 'function')
+                    await result;
+            }
+            catch (e) {
+                this.recordError('', `Encode error: ${e.message}`);
+            }
+        }
+        const postSelfEncodeHandlers = (0, SortPostHandlers_1.SortPostHandlers)(this.postSelfEncodeHandlers);
+        let postEncodeHandler = postSelfEncodeHandlers.shift();
+        while (postEncodeHandler) {
+            try {
+                await postEncodeHandler.handler();
+            }
+            catch (e) {
+                this.recordError('', `Encode error: ${e.message}`);
+            }
+            postEncodeHandler = postSelfEncodeHandlers.shift();
+        }
+        //Encode grows `packet` with headroom (amortized doubling). Restore it to the exact logical
+        //length so every reader of codecData.packet — packet-level post handlers, the encode result,
+        //and single-layer callers — sees no trailing headroom. subarray is a view (no copy); a
+        //following layer simply re-grows from here.
+        const encodedLength = this.codecData.packetLength;
+        if (encodedLength !== undefined && encodedLength < this.codecData.packet.length) {
+            this.codecData.packet = this.codecData.packet.subarray(0, encodedLength);
+        }
+        this.codecData.packetLength = undefined;
+    }
+}
+exports.BaseHeader = BaseHeader;