@glion/mllp 0.15.3 → 0.19.0

package/dist/mllp.js

@@ -1,421 +1,48 @@
 import { value } from "@glion/util-query";
 import { VFile } from "vfile";
-//#region src/transport/constants.ts
-/**
-* MLLP Start Byte - Vertical Tab (VT)
-* Marks the beginning of an MLLP frame
-*/
-const MLLP_START_BYTE = 11;
-/**
-* MLLP End Byte 1 - File Separator (FS)
-* First byte of the end sequence
-*/
-const MLLP_END_BYTE_1 = 28;
-/**
-* MLLP End Byte 2 - Carriage Return (CR)
-* Second byte of the end sequence
-*/
-const MLLP_END_BYTE_2 = 13;
-/**
-* MLLP header as a Uint8Array containing the start byte
-*/
-const MLLP_HEADER = new Uint8Array([11]);
-/**
-* MLLP trailer as a Uint8Array containing the end sequence
-*/
-const MLLP_TRAILER = new Uint8Array([28, 13]);
-//#endregion
 //#region src/errors.ts
 /**
-* Base error class for all MLLP errors.
-*
-* All error types in the MLLP package extend this class.
-* Provides a common `code` field so that any MLLP error can be
-* programmatically identified and translated (e.g., into ACK/NAK responses).
-*/
-var MllpError = class extends Error {
-	/** Machine-readable error code identifying the error type */
-	code;
-	/** Error condition string (e.g., for ERR segment in ACK) */
-	errorCondition;
-	constructor(code, message, options) {
-		super(message, options);
-		this.name = "MllpError";
-		this.code = code;
-		this.errorCondition = options?.errorCondition;
-	}
-};
-//#endregion
-//#region src/transport/errors.ts
-/**
-* Transport-level error for MLLP framing issues (invalid framing, incomplete
-* messages, etc.)
-*/
-var TransportError = class extends MllpError {
-	/** Position in the data where the error occurred (if applicable) */
-	position;
-	constructor(code, message, position) {
-		super(code, message);
-		this.name = "TransportError";
-		this.position = position;
-	}
-};
-//#endregion
-//#region src/transport/types.ts
-/**
-* Error codes for MLLP frame-level errors
-*/
-const TransportErrorCode = {
-	INCOMPLETE_MESSAGE: "INCOMPLETE_MESSAGE",
-	INVALID_END_SEQUENCE: "INVALID_END_SEQUENCE",
-	INVALID_START_BYTE: "INVALID_START_BYTE",
-	MESSAGE_TOO_LARGE: "MESSAGE_TOO_LARGE"
-};
-//#endregion
-//#region src/transport/dynamic-buffer.ts
-/**
-* A growable byte buffer with geometric capacity doubling.
-*
-* Designed for protocol decoders that accumulate bytes from arbitrarily
-* chunked TCP streams. Amortizes copy cost to O(n) total — the same
-* strategy used by pg-protocol, NATS.js, and Java's ArrayList.
-*
-* The buffer maintains a read offset so consumed bytes can be skipped
-* without shifting data. When the wasted prefix exceeds half the
-* capacity, the buffer auto-compacts by shifting remaining bytes to
-* the front.
-*
-* @internal
-*/
-var DynamicBuffer = class {
-	_buffer;
-	_length = 0;
-	_offset = 0;
-	constructor(initialCapacity = 4096) {
-		this._buffer = new Uint8Array(initialCapacity);
-	}
-	get capacity() {
-		return this._buffer.length;
-	}
-	get available() {
-		return this._length - this._offset;
-	}
-	append(chunk) {
-		const needed = this._length + chunk.length;
-		if (needed > this._buffer.length) {
-			const newCapacity = Math.max(this._buffer.length * 2, needed);
-			const newBuffer = new Uint8Array(newCapacity);
-			newBuffer.set(this._buffer.subarray(0, this._length));
-			this._buffer = newBuffer;
-		}
-		this._buffer.set(chunk, this._length);
-		this._length += chunk.length;
-	}
-	view() {
-		return this._buffer.subarray(this._offset, this._length);
-	}
-	consume(n) {
-		this._offset += n;
-		if (this._offset >= this._length) {
-			this._offset = 0;
-			this._length = 0;
-			return;
-		}
-		if (this._offset > this._buffer.length / 2) this._compact();
-	}
-	reset() {
-		this._offset = 0;
-		this._length = 0;
-	}
-	_compact() {
-		const remaining = this._length - this._offset;
-		this._buffer.copyWithin(0, this._offset, this._length);
-		this._offset = 0;
-		this._length = remaining;
-	}
-};
-//#endregion
-//#region src/transport/decoder-stream.ts
-function defaultOnError(error) {
-	console.warn(`MLLP decode error: [${error.code}] ${error.message}`);
-}
-/**
-* Default decoder options, merged with user-provided values via spread.
-*
-* - `encoding` — `"utf8"`, the standard encoding for HL7v2.
-* - `onError` — logs to `console.warn`; the stream continues processing.
-*/
-const defaultDecoderOptions = {
-	encoding: "utf8",
-	onError: defaultOnError
-};
-/**
-* Build the {@link Transformer} that powers both {@link createDecoderStream}
-* and {@link MLLPDecoderStream}.
-*
-* ## How MLLP framing works
-*
-* Every HL7v2 message on the wire is wrapped in a minimal envelope:
-*
-*     <VT> message-payload <FS><CR>
-*     0x0B                 0x1C 0x0D
-*
-* Multiple frames can arrive back-to-back within the same TCP stream.
-* The decoder's job is to find each `<VT>…<FS><CR>` envelope, strip
-* the framing bytes, and emit the inner payload as a {@link DecodedMessage}.
-*
-* ## State machine
-*
-* The decoder alternates between two states:
-*
-*     ┌──────────────┐   VT found    ┌────────────┐
-*     │ WAITING_START │──────────────▶│ IN_MESSAGE │
-*     └──────┬───────┘               └─────┬──────┘
-*            ▲  garbage → onError          │
-*            │                             │ FS CR found → emit message
-*            └─────────────────────────────┘
-*
-* 1. **WAITING_START** — Scans byte-by-byte for a VT start byte. Any bytes
-*    encountered before the VT are garbage (e.g. noise on the line or a partial
-*    connection reset); they are reported via `onError` and discarded.
-* 2. **IN_MESSAGE** — Scans for the two-byte FS CR end sequence. Once found, the
-*    bytes between VT and FS CR are the message payload. The decoder emits the
-*    message and transitions back to WAITING_START.
-*
-* ## Chunk boundaries
+* Errors raised by the `@glion/mllp` server itself.
 *
-* TCP delivers data in arbitrarily-sized chunks that rarely align with
-* MLLP frame boundaries. A single chunk may contain:
+* Per ADR 0018: one base error class discriminated by a stable `code` string.
+* A NAK the server *builds* in response to a message is an `@glion/ack`
+* `AckException` — a different concern from a server-lifecycle/config failure,
+* which is what `MllpServerError` represents.
 *
-* - A fraction of one frame (the rest arrives in the next chunk)
-* - Exactly one frame
-* - Multiple complete frames
-* - A mix of complete frames and a trailing partial frame
-*
-* The transformer handles all of these by appending every incoming
-* chunk to an internal `buffer`, then running `processBuffer()` to
-* extract as many complete frames as possible. Any leftover bytes
-* (a partial frame) stay in the buffer until the next chunk arrives.
-*
-* ## Error recovery
-*
-* The stream is **resilient** — it never throws. All framing errors
-* are reported via the `onError` callback, and the decoder continues
-* scanning for the next valid frame. Error scenarios:
-*
-* - **Garbage before VT** — bytes are skipped, `INVALID_START_BYTE` reported.
-* - **Oversized message** — frame is abandoned, `MESSAGE_TOO_LARGE` reported,
-*   scanning resumes.
-* - **Incomplete frame at stream end** — `INCOMPLETE_MESSAGE` reported during
-*   `flush()`. This is the only error that can't be recovered from, since there
-*   is no more data coming.
-*
-* ## Size enforcement
-*
-* When `maxMessageSize` is set, the decoder checks the payload length
-* in two places to bound memory usage:
-*
-* 1. **Mid-accumulation** — while waiting for the end sequence, if the buffered
-*    payload already exceeds the limit, the frame is abandoned immediately.
-*    This prevents a missing end sequence from causing unbounded buffer
-*    growth.
-* 2. **On completion** — once the end sequence is found, the final payload length
-*    is checked before the message is enqueued.
+* @module
 */
-function createDecoderTransformer(options) {
-	const opts = {
-		...defaultDecoderOptions,
-		...options
-	};
-	const textDecoder = new TextDecoder(opts.encoding);
+const MllpServerErrorCode = {
 	/**
-	* Accumulation buffer — grows as chunks arrive, shrinks as frames are
-	* consumed.
+	* An inbound message could not be decoded as UTF-8 — the only character set
+	* supported for now. The underlying `@glion/util-charset` `CharsetError` is
+	* kept on `cause`; callers branch on this code without importing that
+	* package.
 	*/
-	const dynBuffer = new DynamicBuffer();
-	/** Current state machine position. */
-	let state = "WAITING_START";
+	INCOMPATIBLE_CHARSET: "INCOMPATIBLE_CHARSET",
 	/**
-	* Byte offset within the buffer view where the current frame's VT start byte
-	* lives. Only meaningful when `state === "IN_MESSAGE"`.
-	*/
-	let messageStartPos = 0;
-	/**
-	* Scan `view` for the next VT (0x0B) at or after `startPos`.
-	*
-	* @returns The index of the VT byte, or -1 if not found.
-	*/
-	function findStartByte(view, startPos) {
-		for (let i = startPos; i < view.length; i++) if (view[i] === 11) return i;
-		return -1;
-	}
-	/**
-	* Scan `view` for the two-byte FS CR (0x1C 0x0D) end sequence
-	* at or after `startPos`.
-	*
-	* @returns The index of the FS byte (first byte of the pair), or -1 if not
-	*   found.
+	* `app.handle()` was called before a parser was registered via
+	* `app.parser()`.
 	*/
-	function findEndSequence(view, startPos) {
-		for (let i = startPos; i < view.length - 1; i++) if (view[i] === 28 && view[i + 1] === 13) return i;
-		return -1;
-	}
+	NO_PARSER: "NO_PARSER",
 	/**
-	* Drain as many complete frames from the buffer as possible, enqueuing
-	* each decoded message into `controller`.
-	*
-	* Returns when the buffer contains only an incomplete frame (or is
-	* empty). The incomplete bytes are kept for the next `transform()` call.
-	*
-	* The loop uses a local `position` cursor that always resets to 0
-	* after a `consume()` call, since consumption shifts the view.
+	* The MLLP byte stream itself was violated and the connection closed:
+	* the remote system sent bytes outside a message, glued or unterminated
+	* messages, an over-cap message — or a handler's response contained a
+	* reserved VT/FS byte and could not be framed. The underlying
+	* `@glion/mllp-codec` `MllpCodecError` is kept on `cause`; branch on this
+	* code without importing that package.
 	*/
-	function processBuffer(controller) {
-		let position = 0;
-		while (true) {
-			const view = dynBuffer.view();
-			if (position >= view.length) break;
-			if (state === "WAITING_START") {
-				const startPos = findStartByte(view, position);
-				if (startPos === -1) {
-					if (view.length > 0) opts.onError(new TransportError(TransportErrorCode.INVALID_START_BYTE, `Skipped ${view.length - position} bytes before finding start byte`, position));
-					dynBuffer.reset();
-					return;
-				}
-				if (startPos > position) opts.onError(new TransportError(TransportErrorCode.INVALID_START_BYTE, `Skipped ${startPos - position} bytes before start byte`, position));
-				state = "IN_MESSAGE";
-				messageStartPos = startPos;
-				position = startPos + 1;
-			}
-			if (state === "IN_MESSAGE") {
-				const endPos = findEndSequence(view, position);
-				if (endPos === -1) {
-					const currentSize = view.length - messageStartPos - 1;
-					if (opts.maxMessageSize !== void 0 && currentSize > opts.maxMessageSize) {
-						opts.onError(new TransportError(TransportErrorCode.MESSAGE_TOO_LARGE, `Message size ${currentSize} exceeds maximum ${opts.maxMessageSize}`, messageStartPos));
-						state = "WAITING_START";
-						position = messageStartPos + 1;
-						dynBuffer.consume(position);
-						position = 0;
-						continue;
-					}
-					if (messageStartPos > 0) {
-						dynBuffer.consume(messageStartPos);
-						messageStartPos = 0;
-					}
-					return;
-				}
-				const messageData = view.slice(messageStartPos + 1, endPos);
-				const messageLength = messageData.length;
-				if (opts.maxMessageSize !== void 0 && messageLength > opts.maxMessageSize) opts.onError(new TransportError(TransportErrorCode.MESSAGE_TOO_LARGE, `Message size ${messageLength} exceeds maximum ${opts.maxMessageSize}`, messageStartPos));
-				else controller.enqueue({
-					byteLength: messageLength,
-					data: messageData,
-					text: textDecoder.decode(messageData)
-				});
-				position = endPos + 2;
-				state = "WAITING_START";
-				dynBuffer.consume(position);
-				position = 0;
-			}
-		}
-	}
-	return {
-		flush(_controller) {
-			if (state === "IN_MESSAGE" && dynBuffer.available > 0) opts.onError(new TransportError(TransportErrorCode.INCOMPLETE_MESSAGE, "Stream ended with incomplete MLLP message", messageStartPos));
-		},
-		transform(chunk, controller) {
-			dynBuffer.append(chunk);
-			processBuffer(controller);
-		}
-	};
-}
-/**
-* Create a `TransformStream` that extracts MLLP messages from a raw
-* byte stream.
-*
-* Pipe a TCP socket's `ReadableStream<Uint8Array>` through this stream
-* to receive one {@link DecodedMessage} per MLLP frame, regardless of
-* how the bytes are chunked on the wire.
-*
-* @example
-*   ```typescript
-*   import { createDecoderStream } from "@glion/mllp";
-*
-*   const decoder = createDecoderStream({
-*     maxMessageSize: 1024 * 1024, // 1 MB limit
-*     onError: (err) => log.warn(err), // custom error handler
-*   });
-*
-*   const messages = socket.readable.pipeThrough(decoder).getReader();
-*
-*   while (true) {
-*     const { done, value } = await messages.read();
-*     if (done) break;
-*     console.log(value.text); // HL7v2 message string
-*   }
-*   ```;
-*
-* @param options - Optional decoder settings (max size, encoding, error
-*   handler).
-* @returns A `TransformStream<Uint8Array, DecodedMessage>`.
-*/
-function createDecoderStream(options) {
-	return new TransformStream(createDecoderTransformer(options));
-}
-/**
-* Class-based variant of {@link createDecoderStream} for cases where
-* a reusable instance is preferred over the factory function.
-*
-* Functionally identical — both delegate to the same internal
-* transformer.
-*
-* @example
-*   ```typescript
-*   const decoder = new MLLPDecoderStream({ maxMessageSize: 512_000 });
-*   socket.readable.pipeThrough(decoder);
-*   ```;
-*/
-var MLLPDecoderStream = class extends TransformStream {
-	constructor(options) {
-		super(createDecoderTransformer(options));
-	}
+	PROTOCOL_VIOLATION: "PROTOCOL_VIOLATION"
 };
-//#endregion
-//#region src/transport/encoder.ts
-/** Module-level singleton — avoids allocation per encode() call. */
-const textEncoder = new TextEncoder();
-/**
-* Encode a single HL7v2 message into an MLLP frame.
-*
-* Wraps the message with MLLP framing:
-* - Start byte: 0x0B (VT)
-* - End sequence: 0x1C 0x0D (FS + CR)
-*/
-function encode(message, _options) {
-	const messageBytes = typeof message === "string" ? textEncoder.encode(message) : message;
-	const frame = new Uint8Array(messageBytes.length + 3);
-	frame[0] = 11;
-	frame.set(messageBytes, 1);
-	frame[frame.length - 2] = 28;
-	frame[frame.length - 1] = 13;
-	return frame;
-}
-/**
-* Encode multiple HL7v2 messages into concatenated MLLP frames.
-*/
-function encodeMultiple(messages, options) {
-	const frames = messages.map((msg) => encode(msg, options));
-	let totalLength = 0;
-	for (const frame of frames) totalLength += frame.length;
-	const result = new Uint8Array(totalLength);
-	let offset = 0;
-	for (const frame of frames) {
-		result.set(frame, offset);
-		offset += frame.length;
+/** The one error class the `@glion/mllp` server raises. Branch on `code`. */
+var MllpServerError = class extends Error {
+	code;
+	constructor(code, message, opts) {
+		super(message, opts);
+		this.name = "MllpServerError";
+		this.code = code;
 	}
-	return result;
-}
+};
 //#endregion
 //#region src/server/compose.ts
 /**
@@ -724,15 +351,17 @@ var Mllp = class {
 	* This is the integration point — analogous to Hono's `fetch()`.
 	*
 	* The pipeline is lazy (see ADR-0013):
+	*
 	* 1. Parse (sync, fast) — always runs, extracts routing fields
 	* 2. Route match — uses pre-transform routing fields
 	* 3. If no match → return undefined (no transform/compile cost)
 	* 4. Transform/compile — only when handlers access ctx.tree()/ctx.result()
 	*
-	* Throws `MllpError` if no processor has been registered via `app.parser()`.
+	* Throws `MllpServerError` (`NO_PARSER`) if no processor has been registered
+	* via `app.parser()`.
 	*/
 	async handle(raw, bytes, connection) {
-		if (!this.#processor) throw new MllpError("ERR_NO_PARSER", "No parser registered. Call app.parser() before handling messages.");
+		if (!this.#processor) throw new MllpServerError(MllpServerErrorCode.NO_PARSER, "No parser registered. Call app.parser() before handling messages.");
 		const ctx = createContext({
 			bytes,
 			connection,
@@ -786,6 +415,6 @@ var Mllp = class {
 	}
 };
 //#endregion
-export { encode as a, createDecoderStream as c, MllpError as d, MLLP_END_BYTE_1 as f, MLLP_TRAILER as g, MLLP_START_BYTE as h, parsePattern as i, TransportErrorCode as l, MLLP_HEADER as m, getMessageInfo as n, encodeMultiple as o, MLLP_END_BYTE_2 as p, matchPattern as r, MLLPDecoderStream as s, Mllp as t, TransportError as u };
+export { MllpServerError as a, parsePattern as i, getMessageInfo as n, MllpServerErrorCode as o, matchPattern as r, Mllp as t };
 
 //# sourceMappingURL=mllp.js.map