@netkitty/codec 1.0.0

package/dist/abstracts/BaseHeader.d.ts

@@ -0,0 +1,325 @@
+import { ProtocolJSONSchema } from '../schema/ProtocolJSONSchema';
+import { CodecModule } from '../types/CodecModule';
+import { ProtocolFieldJSONSchema } from '../schema/ProtocolFieldJSONSchema';
+import { CodecErrorInfo } from '../types/CodecErrorInfo';
+import { PostHandlerItem } from '../types/PostHandlerItem';
+import { CodecData } from '../types/CodecData';
+import { DemuxProducer } from '../types/DemuxProducer';
+import { FlexibleObject } from '../lib/FlexibleObject';
+import { HeaderTreeNode } from '../types/HeaderTreeNode';
+/** Absolute byte span a field occupies in the packet, collected during a dissect pass. */
+export type FieldByteRange = {
+    offset: number;
+    length: number;
+};
+/**
+ * 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).
+ */
+export declare abstract class BaseHeader {
+    #private;
+    protected static get CODEC_INSTANCE(): CodecModule;
+    protected static CREATE_CODEC_INSTANCE_WITCH_CODEC_MODULES(codecData: CodecData, codecModules: CodecModule[]): CodecModule;
+    static get PROTOCOL_ID(): string;
+    static get PROTOCOL_NAME(): string;
+    /**
+     * 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(): string[];
+    /**
+     * 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(): DemuxProducer[];
+    /**
+     * 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(): boolean;
+    /** Higher is tried first within a demux bucket and within the heuristic chain; ties keep registration order. */
+    static get MATCH_PRIORITY(): number;
+    static get PROTOCOL_SCHEMA(): ProtocolJSONSchema;
+    static MATCH(codecData: CodecData, codecModules: CodecModule[]): boolean;
+    static CREATE_INSTANCE(codecData: CodecData, codecModules: CodecModule[]): CodecModule;
+    /**
+     * Protocol schema definition
+     */
+    abstract readonly SCHEMA: ProtocolJSONSchema;
+    /**
+     * Program used header id
+     */
+    abstract readonly id: string;
+    /**
+     * Human-readable header name
+     */
+    abstract readonly name: string;
+    /**
+     * Human-readable header nickname
+     */
+    abstract readonly nickname: string;
+    /**
+     * Current header is a protocol or not
+     */
+    readonly isProtocol: boolean;
+    /**
+     * 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.
+     */
+    readonly matchKeys: string[];
+    /**
+     * 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'}]`.
+     */
+    readonly demuxProducers: DemuxProducer[];
+    /**
+     * 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.
+     */
+    readonly heuristicFallback: boolean;
+    /** Selection priority within a bucket / the heuristic chain (higher first; ties keep registration order). */
+    readonly matchPriority: number;
+    /**
+     * Encode/Decode error info objects
+     */
+    errors: CodecErrorInfo[];
+    /**
+     * Header schema instance
+     */
+    instance: FlexibleObject;
+    /**
+     * 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(): void;
+    /** The byte span each field occupied, or null if this header was not dissected. */
+    getByteRanges(): Map<string, FieldByteRange> | null;
+    /**
+     * Entire packet buffer data getter
+     */
+    get packet(): Buffer;
+    /**
+     * Entire packet buffer data setter
+     * @param packet
+     */
+    set packet(packet: Buffer);
+    /**
+     * The start position of this header in the entire packet's buffer
+     */
+    startPos: number;
+    /**
+     * The end position of this header in the entire packet's buffer
+     */
+    get endPos(): number;
+    /**
+     * Readonly Header length
+     */
+    get length(): number;
+    /**
+     * Header length
+     * @protected
+     */
+    protected headerLength: number;
+    /**
+     * Previous Codec module
+     * @protected
+     */
+    protected prevCodecModule: CodecModule;
+    /**
+     * Codec modules
+     * @protected
+     */
+    protected codecModules: CodecModule[];
+    /**
+     * Previous codec modules
+     * @protected
+     */
+    protected prevCodecModules: CodecModule[];
+    /**
+     * Current header index in packet headers
+     * @protected
+     */
+    protected headerIndex: number;
+    /**
+     * Post packet handlers
+     * @protected
+     */
+    protected get postPacketHandlers(): PostHandlerItem[];
+    /**
+     * Registered post encode handlers (CodecModule)
+     * @protected
+     */
+    protected readonly postSelfEncodeHandlers: PostHandlerItem[];
+    /**
+     * Registered post decode handlers (CodecModule)
+     * @protected
+     */
+    protected readonly postSelfDecodeHandlers: PostHandlerItem[];
+    /**
+     * Codec data
+     * @protected
+     */
+    protected codecData: CodecData;
+    constructor(codecData: CodecData, codecModules: CodecModule[]);
+    /**
+     * (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.
+     */
+    protected bindContext(codecData: CodecData, codecModules: CodecModule[]): void;
+    /**
+     * Get packet data offset
+     * @param offset
+     * @protected
+     */
+    protected getPacketOffset(offset: number): number;
+    /**
+     * Is data buffer fits current header codec
+     */
+    abstract match(): boolean;
+    /**
+     * Read bytes from buffer
+     * @param offset
+     * @param length
+     * @param dryRun
+     * @protected
+     */
+    protected readBytes(offset: number, length: number, dryRun?: boolean): Buffer;
+    /**
+     * Write bytes to buffer
+     * @param offset
+     * @param buffer
+     * @protected
+     */
+    protected writeBytes(offset: number, buffer: Buffer): void;
+    /**
+     * Read bits from buffer
+     * @param offset
+     * @param length
+     * @param bitOffset
+     * @param bitLength
+     * @protected
+     */
+    protected readBits(offset: number, length: number, bitOffset: number, bitLength: number): number;
+    /**
+     * Write bits to buffer
+     * @param offset
+     * @param length
+     * @param bitOffset
+     * @param bitLength
+     * @param value
+     * @protected
+     */
+    protected writeBits(offset: number, length: number, bitOffset: number, bitLength: number, value: number): void;
+    /**
+     * 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
+     */
+    protected static fieldUInt(name: string, offset: number, byteLength: number, label: string): ProtocolFieldJSONSchema;
+    /**
+     * 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
+     */
+    protected static fieldInt8(name: string, offset: number, label: string): ProtocolFieldJSONSchema;
+    /**
+     * 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
+     */
+    protected static fieldHex(name: string, offset: number, byteLength: number, label: string): ProtocolFieldJSONSchema;
+    /**
+     * 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
+     */
+    protected static fieldIPv4(name: string, offset: number, label: string): ProtocolFieldJSONSchema;
+    /**
+     * Get field codecs from schema tree
+     * @param schema
+     * @param codecName
+     * @param execBeforeSubCodecs
+     * @param codecs
+     * @protected
+     */
+    protected getFieldCodecs(schema: ProtocolFieldJSONSchema, codecName: string, execBeforeSubCodecs: boolean, codecs?: (() => void | Promise<void>)[], paths?: string[] | null, pathPrefix?: string): (() => void | Promise<void>)[];
+    /**
+     * Record encode/decode error
+     * @param path
+     * @param message
+     * @protected
+     */
+    protected recordError(path: string, message: string): void;
+    /**
+     * Register post encode handler for current codec
+     * @param handler
+     * @param priority
+     * @protected
+     */
+    protected addPostSelfEncodeHandler(handler: () => void | Promise<void>, priority?: number): void;
+    /**
+     * Register post decode handler for current codec
+     * @param handler
+     * @param priority
+     * @protected
+     */
+    protected addPostSelfDecodeHandler(handler: () => void | Promise<void>, priority?: number): void;
+    /**
+     * Register post encode handler for packet
+     * @description Registered handler call sequence: LIFO (Last In First Out)
+     * @param handler
+     * @param priority
+     * @protected
+     */
+    protected addPostPacketEncodeHandler(handler: () => void | Promise<void>, priority?: number): void;
+    /**
+     * Register post decode handler for packet
+     * @description Registered handler call sequence: FIFO (First In First Out)
+     * @param handler
+     * @param priority
+     * @protected
+     */
+    protected addPostPacketDecodeHandler(handler: () => void | Promise<void>, priority?: number): void;
+    /**
+     * Validate input json node is valid
+     * @param headerTreeNode
+     */
+    validate(headerTreeNode: HeaderTreeNode): HeaderTreeNode;
+    /**
+     * Decode packet header field by field
+     */
+    decode(): Promise<void>;
+    /**
+     * Encode packet header field by field
+     */
+    encode(): Promise<void>;
+}