@glion/mllp 0.15.3 → 0.19.0

package/README.md

@@ -57,33 +57,46 @@ The server class. Built with a fluent chainable API:
 
 Start a Node.js or Bun TCP server that dispatches incoming MLLP frames through the `Mllp` instance.
 
-- `port` (`number`) — TCP port to listen on.
-- `hostname` (`string`, optional) — interface to bind. Defaults to all interfaces.
-- `tls` (`{ cert, key }`, optional) — enable MLLP over TLS.
-
-### Primitives
-
-| Function                        | Description                                            |
-| ------------------------------- | ------------------------------------------------------ |
-| `encode(message)`               | Encode a message string into an MLLP frame.            |
-| `decode(frame)`                 | Decode a single MLLP frame to its message.             |
-| `encodeMultiple(messages)`      | Encode an array of messages in one pass.               |
-| `createDecoderStream(options?)` | TransformStream for streaming decode from chunked TCP. |
+| Option                  | Type                                        | Description                                                                                    |
+| ----------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `port`                  | `number`                                    | TCP port to listen on.                                                                         |
+| `hostname`              | `string`, optional                          | Interface to bind. Defaults to all interfaces.                                                 |
+| `tls`                   | `{ cert, key, ca?, passphrase? }`, optional | Enable MLLP over TLS.                                                                          |
+| `keepAlive`             | `boolean`, optional                         | Enable TCP keep-alive on accepted sockets. Defaults to `true`.                                 |
+| `keepAliveInitialDelay` | `number`, optional                          | Delay in ms before the first keep-alive probe on an idle socket. Defaults to `60000`.          |
+| `socketTimeout`         | `number`, optional                          | Socket inactivity timeout in ms — an idle socket past it is destroyed. `0` (default) disables. |
+| `onConnect`             | `ConnectionCallback`, optional              | Called when a new TCP connection is accepted.                                                  |
+| `onDisconnect`          | `ConnectionCallback`, optional              | Called when a connection closes — always fires, even if `onConnect` threw.                     |
+| `onError`               | `ErrorCallback`, optional                   | Called when a handler error goes unhandled or a lifecycle callback throws.                     |
+
+### Wire framing
+
+MLLP framing lives in [`@glion/mllp-codec`](https://github.com/rethinkhealth/glion/tree/main/packages/mllp-codec) — `frame()` wraps outbound messages, `unframe()` streams inbound bytes back into them. `@glion/mllp` consumes it internally and re-exports nothing from it; import it directly when you need the codec.
 
 ### Types
 
-| Type               | Description                                                         |
-| ------------------ | ------------------------------------------------------------------- |
-| `Context`          | Request context with message data and routing fields.               |
-| `Response`         | Response object `{ raw: string }`.                                  |
-| `Hl7v2Processor`   | Unified `Processor` type for HL7v2 (`Processor<Root, Root, Root>`). |
-| `Middleware`       | Middleware function `(ctx, next) => ...`.                           |
-| `Handler`          | Terminal route handler `(ctx) => Response`.                         |
-| `ErrorHandler`     | Error handler `(err, ctx) => Response`.                             |
-| `RouteFilter`      | Filter function `(ctx) => boolean` used for routing.                |
-| `MiddlewareReturn` | Return type of middleware functions.                                |
-| `ConnectionInfo`   | Connection metadata (remote/local address, TLS flag).               |
-| `RoutePattern`     | Parsed route pattern.                                               |
+| Type               | Description                                                                                                                                                                                 |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Context`          | Request context with message data and routing fields.                                                                                                                                       |
+| `Response`         | Response object `{ raw: string }`.                                                                                                                                                          |
+| `Hl7v2Processor`   | Unified `Processor` type for HL7v2 (`Processor<Root, Root \| undefined, Root \| undefined>` — head/tail admit `undefined` so the bare `unified().use(hl7v2Parser).freeze()` is assignable). |
+| `Middleware`       | Middleware function `(ctx, next) => ...`.                                                                                                                                                   |
+| `Handler`          | Terminal route handler `(ctx) => Response`.                                                                                                                                                 |
+| `ErrorHandler`     | Error handler `(err, ctx) => Response`.                                                                                                                                                     |
+| `RouteFilter`      | Filter function `(ctx) => boolean` used for routing.                                                                                                                                        |
+| `MiddlewareReturn` | Return type of middleware functions.                                                                                                                                                        |
+| `ConnectionInfo`   | Connection metadata (remote/local address, TLS flag).                                                                                                                                       |
+| `RoutePattern`     | Parsed route pattern.                                                                                                                                                                       |
+
+### Errors
+
+Server-side failures are raised (or passed to `onError`) as `MllpServerError` — branch on its stable `code`; the underlying codec or charset error rides on `cause`:
+
+| Code                   | Meaning                                                                                           |
+| ---------------------- | ------------------------------------------------------------------------------------------------- |
+| `NO_PARSER`            | `app.handle()` ran before a parser was registered via `app.parser()`.                             |
+| `INCOMPATIBLE_CHARSET` | An inbound message could not be decoded as UTF-8 (the `CharsetError` is on `cause`).              |
+| `PROTOCOL_VIOLATION`   | The MLLP byte stream was violated and the connection closed (the `MllpCodecError` is on `cause`). |
 
 ## Routing
 
@@ -256,39 +269,6 @@ const server = serve(app, {
 });
 ```
 
-## Primitives
-
-### Simple API
-
-```ts
-import { encode, decode, encodeMultiple } from "@glion/mllp";
-
-const mllpFrame = encode(hl7Message);
-const decoded = decode(mllpFrame);
-console.log(decoded.text);
-
-const frames = encodeMultiple(["MSH|1", "MSH|2"]);
-```
-
-### Streaming API
-
-```ts
-import { createDecoderStream } from "@glion/mllp";
-
-const decoder = createDecoderStream({
-  maxMessageSize: 1024 * 1024,
-  onError: (error) => console.warn(`[${error.code}] ${error.message}`),
-});
-
-tcpSocket.readable.pipeThrough(decoder).pipeTo(
-  new WritableStream({
-    write(message) {
-      console.log("Received:", message.text);
-    },
-  })
-);
-```
-
 ## Design notes
 
 ### Why no default error response?
@@ -299,14 +279,13 @@ Instead, the `Mllp` engine is middleware-first:
 
 - **Default behaviour** — no response is sent; the sending system times out and retries, which is valid MLLP behaviour.
 - **Logging** — add a logger middleware to make errors observable.
-- **ACK/NAK** — add an acknowledgment middleware to translate errors into proper NAK responses. `@glion/mllp-ack` provides this out of the box.
+- **ACK/NAK** — register your own acknowledgment middleware to translate outcomes into ACK/NAK responses. Built-in acknowledgment translation at the framework's error boundary is landing next (see ADR-0019).
 - **Custom error responses** — use `app.onError()` for application-specific handling.
 
 ```ts
 const app = new Mllp().parser(parseHL7v2);
 
 app.use(logger()); // observability — provided by middleware
-app.use(ackMiddleware()); // error → NAK translation — @glion/mllp-ack
 
 app.on("ADT^A01", handler);
 ```

package/dist/errors.d.ts

@@ -1,22 +1,42 @@
 /**
- * Options for constructing an MllpError.
- */
-export interface MllpErrorOptions extends ErrorOptions {
-    /** Error condition string (e.g., for ERR segment in ACK) */
-    errorCondition?: string;
-}
-/**
- * Base error class for all MLLP errors.
+ * Errors raised by the `@glion/mllp` server itself.
+ *
+ * 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.
  *
- * 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).
+ * @module
  */
-export declare class MllpError extends Error {
-    /** Machine-readable error code identifying the error type */
-    readonly code: string;
-    /** Error condition string (e.g., for ERR segment in ACK) */
-    readonly errorCondition?: string;
-    constructor(code: string, message: string, options?: MllpErrorOptions);
+export declare const MllpServerErrorCode: {
+    /**
+     * 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.
+     */
+    readonly INCOMPATIBLE_CHARSET: "INCOMPATIBLE_CHARSET";
+    /**
+     * `app.handle()` was called before a parser was registered via
+     * `app.parser()`.
+     */
+    readonly NO_PARSER: "NO_PARSER";
+    /**
+     * 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.
+     */
+    readonly PROTOCOL_VIOLATION: "PROTOCOL_VIOLATION";
+};
+export type MllpServerErrorCode = (typeof MllpServerErrorCode)[keyof typeof MllpServerErrorCode];
+/** The one error class the `@glion/mllp` server raises. Branch on `code`. */
+export declare class MllpServerError extends Error {
+    readonly code: MllpServerErrorCode;
+    constructor(code: MllpServerErrorCode, message: string, opts?: {
+        cause?: unknown;
+    });
 }
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;gBAErB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB;CAMtE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,eAAO,MAAM,mBAAmB;IAC9B;;;;;OAKG;;IAEH;;;OAGG;;IAEH;;;;;;;OAOG;;CAEK,CAAC;AACX,MAAM,MAAM,mBAAmB,GAC7B,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AAEjE,6EAA6E;AAC7E,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;gBAEjC,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAM7B"}

package/dist/index.d.ts

@@ -1,7 +1,4 @@
-export { createDecoderStream, decode, encode, encodeMultiple, TransportError, ErrorCode, MLLP_END_BYTE_1, MLLP_END_BYTE_2, MLLP_HEADER, MLLP_START_BYTE, MLLP_TRAILER, MLLPDecoderStream, } from "./transport";
-export type { DecodedMessage, DecoderOptions, EncoderInput, EncoderOptions, } from "./transport";
-export { MllpError } from "./errors";
-export type { MllpErrorOptions } from "./errors";
+export { MllpServerError, MllpServerErrorCode } from "./errors";
 export { getMessageInfo, Mllp } from "./server/mllp";
 export type { MessageInfo } from "./server/mllp";
 export type { ConnectionInfo, Context, ErrorHandler, Handler, Hl7v2Processor, Middleware, MiddlewareReturn, Response, RouteFilter, RoutePattern, } from "./server/types";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,mBAAmB,EACnB,MAAM,EACN,MAAM,EACN,cAAc,EACd,cAAc,EACd,SAAS,EACT,eAAe,EACf,eAAe,EACf,WAAW,EACX,eAAe,EACf,YAAY,EACZ,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,cAAc,EACd,cAAc,EACd,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAC;AAKrB,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAKjD,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrD,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,YAAY,EACV,cAAc,EACd,OAAO,EACP,YAAY,EACZ,OAAO,EACP,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrD,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,YAAY,EACV,cAAc,EACd,OAAO,EACP,YAAY,EACZ,OAAO,EACP,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -1,38 +1,2 @@
-import { a as encode, c as createDecoderStream, d as MllpError, f as MLLP_END_BYTE_1, g as MLLP_TRAILER, h as MLLP_START_BYTE, i as parsePattern, l as TransportErrorCode, m as MLLP_HEADER, n as getMessageInfo, o as encodeMultiple, p as MLLP_END_BYTE_2, r as matchPattern, s as MLLPDecoderStream, t as Mllp, u as TransportError } from "./mllp.js";
-//#region src/transport/decoder.ts
-/**
-* Decode a single MLLP frame (VT ... FS CR) into a message.
-*
-* Validates framing, strips the envelope, and returns the payload as
-* both raw bytes and decoded text. Throws {@link TransportError} on
-* any structural issue.
-*
-* For streaming / chunked TCP data, use {@link createDecoderStream} instead.
-*
-* @throws TransportError with `INVALID_START_BYTE` if byte 0 is not 0x0B
-* @throws TransportError with `INVALID_END_SEQUENCE` if frame doesn't end with
-*   0x1C 0x0D
-* @throws TransportError with `MESSAGE_TOO_LARGE` if payload exceeds
-*   `maxMessageSize`
-*/
-function decode(frame, options) {
-	if (frame.length < 3) throw new TransportError(TransportErrorCode.INVALID_END_SEQUENCE, "Frame too short to contain valid MLLP structure", 0);
-	const startByte = frame[0];
-	if (startByte !== 11) throw new TransportError(TransportErrorCode.INVALID_START_BYTE, `Invalid start byte: expected 0x0B, got 0x${(startByte ?? 0).toString(16).padStart(2, "0")}`, 0);
-	const len = frame.length;
-	const endByte1 = frame[len - 2];
-	const endByte2 = frame[len - 1];
-	if (endByte1 !== 28 || endByte2 !== 13) throw new TransportError(TransportErrorCode.INVALID_END_SEQUENCE, `Invalid end sequence: expected 0x1C 0x0D, got 0x${(endByte1 ?? 0).toString(16).padStart(2, "0")} 0x${(endByte2 ?? 0).toString(16).padStart(2, "0")}`, len - 2);
-	const messageLength = len - 3;
-	if (options?.maxMessageSize !== void 0 && messageLength > options.maxMessageSize) throw new TransportError(TransportErrorCode.MESSAGE_TOO_LARGE, `Message size ${messageLength} exceeds maximum ${options.maxMessageSize}`, 0);
-	const data = frame.subarray(1, len - 2);
-	return {
-		byteLength: messageLength,
-		data,
-		text: new TextDecoder(options?.encoding ?? "utf8").decode(data)
-	};
-}
-//#endregion
-export { TransportErrorCode as ErrorCode, MLLPDecoderStream, MLLP_END_BYTE_1, MLLP_END_BYTE_2, MLLP_HEADER, MLLP_START_BYTE, MLLP_TRAILER, Mllp, MllpError, TransportError, createDecoderStream, decode, encode, encodeMultiple, getMessageInfo, matchPattern, parsePattern };
-
-//# sourceMappingURL=index.js.map
+import { a as MllpServerError, i as parsePattern, n as getMessageInfo, o as MllpServerErrorCode, r as matchPattern, t as Mllp } from "./mllp.js";
+export { Mllp, MllpServerError, MllpServerErrorCode, getMessageInfo, matchPattern, parsePattern };