@cosyte/mllp 0.0.1

package/README.md

@@ -0,0 +1,113 @@
+# @cosyte/mllp
+
+> Send and receive HL7 v2 over a production-grade MLLP connection in a few lines — with framing, ACK correlation, auto-reconnect, and backpressure handled for you.
+
+[![npm version](https://img.shields.io/npm/v/@cosyte/mllp.svg)](https://www.npmjs.com/package/@cosyte/mllp)
+[![CI](https://img.shields.io/github/actions/workflow/status/cosyte/mllp/ci.yml?branch=main&label=CI)](https://github.com/cosyte/mllp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org)
+
+A developer-focused MLLP (Minimal Lower Layer Protocol) client and server for Node.js and TypeScript. Transport-only sibling to [`@cosyte/hl7`](https://github.com/cosyte/hl7) (the parser): `@cosyte/mllp` moves the bytes, `@cosyte/hl7` reads them.
+
+**Status: under active development. API not yet stable (`0.0.x`).**
+
+---
+
+## Quickstart
+
+```bash
+# pnpm (recommended) — also works with: npm install @cosyte/mllp  |  yarn add @cosyte/mllp
+pnpm add @cosyte/mllp
+```
+
+```ts
+import { createStarterServer } from "@cosyte/mllp";
+
+// Echoes every received frame straight back as the ACK.
+const server = await createStarterServer({ port: 2575, onMessage: (buf) => buf });
+```
+
+```ts
+import { createStarterClient } from "@cosyte/mllp";
+
+const client = await createStarterClient({ host: "localhost", port: 2575 });
+const ack = await client.send(Buffer.from("MSH|^~\\&|..."));
+```
+
+The payload API is **Buffer-first** everywhere — HL7 v2 messages are raw bytes with caller-managed charset decoding.
+
+## MLLPS / TLS
+
+TLS is built on `node:tls` — no bundled TLS, no extra dependency. Certificate verification is **on
+by default**; the server binds `127.0.0.1` by default and requires an explicit opt-in
+(`allowWildcardBind: true`) to bind all interfaces.
+
+```ts
+// Server — plain TLS
+const server = createServer({ tls: { cert: certPem, key: keyPem } });
+await server.listen(2575, "127.0.0.1");
+
+// Server — mutual TLS (ATNA ITI-19)
+const server = createServer({
+  tls: { cert: certPem, key: keyPem, ca: clientCaPem, clientAuth: "MUST" },
+});
+```
+
+```ts
+// Client
+const client = createClient({ host: "mllp.example.com", port: 2575, tls: { ca: caPem } });
+
+// Client — mutual TLS
+const client = createClient({
+  host: "mllp.example.com",
+  port: 2575,
+  tls: { ca: caPem, cert: clientCertPem, key: clientKeyPem },
+});
+```
+
+See the **MLLPS / TLS** doc for the `ClientAuth` table, the TLS 1.2 floor (IHE ATNA ITI-19), typed
+failure modes (`tls-verify` vs `tls-handshake`), and bind-safety details.
+
+## Fail-safe ACKs — the commit contract
+
+A positive acknowledgement (`AA`) tells the sender *"you may forget this message — I have it."* So a
+receiver must never send one before the message is durably handled, or the message is silently lost.
+`@cosyte/mllp` makes that structural: pair `autoAck: 'AA'` with an `onMessage` handler and the server
+**awaits your handler (the durable-commit step) and only then ACKs**.
+
+```ts
+const server = createServer({
+  autoAck: "AA",
+  onMessage: async (payload) => {
+    await db.commit(payload); // throw here ⇒ AE (resend may succeed), never AA
+  },
+});
+```
+
+Handler resolves ⇒ `AA`. Handler throws ⇒ `AE` (or `AR` via `MllpAckError`). **A positive ACK cannot
+precede a successful commit.** `autoAck: 'AA'` *without* a handler is documented as a
+transport-accept — "received and framed", not "processed".
+
+## What's in the box
+
+- **Client + server** with strict MLLP framing (`VT + payload + FS + CR`), ACK correlation, auto-reconnect with backoff, and backpressure.
+- **The commit contract** — a positive ACK can never precede a durable commit; an unparseable inbound can never yield a positive ACK.
+- **Explicit 6-state connection machine** (`CONNECTING | CONNECTED | DRAINING | RECONNECTING | DISCONNECTED | CLOSED`) with `stateChange` events — never socket flags.
+- **Lenient decoder, strict encoder** (Postel's Law) with **11 stable warning codes** carrying byte offsets. Tolerance is opt-in per flag; the server ships tolerant defaults.
+- **TLS (MLLPS)** — verification on by default, mutual TLS (`clientAuth: 'NONE' | 'WANT' | 'MUST'`), a TLS 1.2 floor per IHE ATNA ITI-19, and bind-safety guardrails (`127.0.0.1` default, wildcard binds require opt-in). `AbortSignal` on every awaitable and `Symbol.asyncDispose` on every closeable.
+- **PHI-safe diagnostics** — no error, warning, event payload, or stats object ever echoes a *run* of message content; a framing error carries at most the single byte at the structural violation.
+- **In-memory transport** (`@cosyte/mllp/testing`) — a deterministic, socket-free test double for fast, reliable tests.
+- **`@cosyte/hl7` as an optional peer** — the `@cosyte/mllp/ack-from-hl7` subpath builds ACKs from parsed messages when it's installed.
+- **Zero runtime dependencies.** Node stdlib only.
+
+## What it deliberately does not do
+
+MLLP + ACK is **at-least-once at best** — your application owns idempotency and de-duplication
+(`MSH-10` + `MSH-7`). This package does not parse HL7 (use `@cosyte/hl7`), does not queue or replay
+unacked messages, does not decide clinical acceptance, does not speak MLLP **Release 2**, and ships
+no PKI. The full list is in the **Known limitations & non-goals** doc — read it before you depend on
+this.
+
+## License
+
+MIT

package/dist/ack-from-hl7/index.cjs

@@ -0,0 +1,417 @@
+'use strict';
+
+var module$1 = require('module');
+
+// node_modules/.pnpm/tsup@8.5.1_postcss@8.5.10_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+
+// src/framing/constants.ts
+var VT = 11;
+var FS = 28;
+var CR = 13;
+
+// src/framing/error.ts
+var MAX_SNIPPET_BYTES = 64;
+var MllpFramingError = class _MllpFramingError extends Error {
+  name = "MllpFramingError";
+  /** Stable warning code identifying the violation type. */
+  code;
+  /** Absolute byte offset in the stream where the error was detected. */
+  byteOffset;
+  /**
+   * Up to 64 bytes copied from around the anomaly.
+   *
+   * This is a **copied** Buffer — isolated from the source buffer so it remains
+   * valid after the underlying buffer is reused or overwritten.
+   *
+   * **PHI contract (MLLP-9):** the decoder only ever populates this with the single
+   * framing-boundary byte that violated the frame structure (whose hex value the
+   * `message` already discloses) — never a run of payload content bytes. For anomalies
+   * whose fault is not a specific byte (`MLLP_FRAME_TOO_LARGE` — the accumulated size),
+   * the snippet is **empty**: a payload slice on a public error field would leak a
+   * field-body slice of clinical content. Callers constructing this directly are
+   * responsible for the same discipline.
+   */
+  snippet;
+  /**
+   * Construct an MLLP framing error.
+   *
+   * @param code - The stable warning code classifying the violation.
+   * @param byteOffset - Absolute stream byte offset where the violation was detected.
+   * @param snippet - Raw bytes copied from around the anomaly (capped to 64 bytes).
+   * @param message - Optional human-readable override message.
+   */
+  constructor(code, byteOffset, snippet, message) {
+    super(message ?? `MLLP framing error: ${code} at byte offset ${byteOffset}`);
+    this.code = code;
+    this.byteOffset = byteOffset;
+    this.snippet = Buffer.from(snippet.subarray(0, MAX_SNIPPET_BYTES));
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _MllpFramingError);
+    }
+  }
+};
+
+// src/framing/registry.ts
+function createWarning(code, byteOffset, message) {
+  return Object.freeze({
+    code,
+    message,
+    byteOffset,
+    connectionId: void 0,
+    timestamp: /* @__PURE__ */ new Date()
+  });
+}
+
+// src/framing/encoder.ts
+function encodeFrame(payload, opts) {
+  const allow = opts?.allowDelimiterBytesInPayload === true;
+  const onWarning = opts?.onWarning;
+  for (let i = 0; i < payload.length; i++) {
+    const byte = payload[i];
+    if (byte === void 0) break;
+    if (byte === VT || byte === FS) {
+      const code = byte === VT ? "MLLP_PAYLOAD_CONTAINS_VT" : "MLLP_PAYLOAD_CONTAINS_FS";
+      if (!allow) {
+        throw new MllpFramingError(code, i, Buffer.from([byte]));
+      }
+      if (onWarning !== void 0) {
+        const byteHex = byte === VT ? "0x0B" : "0x1C";
+        const warning = createWarning(
+          code,
+          i,
+          `Payload contains ${byte === VT ? "VT" : "FS"} byte (${byteHex}) at offset ${i}; frame will be ambiguous`
+        );
+        try {
+          onWarning(warning);
+        } catch {
+        }
+      }
+    }
+  }
+  const frame = Buffer.allocUnsafe(payload.length + 3);
+  frame[0] = VT;
+  payload.copy(frame, 1);
+  frame[payload.length + 1] = FS;
+  frame[payload.length + 2] = CR;
+  return frame;
+}
+
+// src/internal/control-id.ts
+var ASCII_M = 77;
+var ASCII_S = 83;
+var ASCII_H = 72;
+var ASCII_A = 65;
+var SEGMENT_SEPARATOR_CR = 13;
+var SEGMENT_SEPARATOR_LF = 10;
+var CONTROL_ID_ENCODING = "latin1";
+var UNSAFE_FIELD_SEPARATORS = /* @__PURE__ */ new Set([
+  SEGMENT_SEPARATOR_CR,
+  SEGMENT_SEPARATOR_LF,
+  11,
+  // VT — MLLP start block
+  28
+  // FS — MLLP end block
+]);
+function isMshSegmentAt(buf, i) {
+  return i + 3 < buf.length && buf[i] === ASCII_M && buf[i + 1] === ASCII_S && buf[i + 2] === ASCII_H && !UNSAFE_FIELD_SEPARATORS.has(buf[i + 3]);
+}
+function segmentEnd(buf, i) {
+  let end = i;
+  while (end < buf.length && buf[end] !== SEGMENT_SEPARATOR_CR && buf[end] !== SEGMENT_SEPARATOR_LF) {
+    end++;
+  }
+  return end;
+}
+function findMshSegment(buf) {
+  let segStart = 0;
+  while (segStart < buf.length) {
+    const end = segmentEnd(buf, segStart);
+    if (isMshSegmentAt(buf, segStart)) return { start: segStart, end };
+    let next = end;
+    while (next < buf.length && (buf[next] === SEGMENT_SEPARATOR_CR || buf[next] === SEGMENT_SEPARATOR_LF)) {
+      next++;
+    }
+    if (next === segStart) return null;
+    segStart = next;
+  }
+  return null;
+}
+function readMshSegment(buf) {
+  const at = findMshSegment(buf);
+  if (at === null) return null;
+  const fieldSep = String.fromCharCode(buf[at.start + 3]);
+  const fields = buf.subarray(at.start, at.end).toString(CONTROL_ID_ENCODING).split(fieldSep);
+  return { fieldSep, fields };
+}
+function stripLeadingSegmentTerminators(buf) {
+  let i = 0;
+  while (i < buf.length && (buf[i] === SEGMENT_SEPARATOR_CR || buf[i] === SEGMENT_SEPARATOR_LF)) {
+    i++;
+  }
+  return i === 0 ? buf : buf.subarray(i);
+}
+function extractMshControlId(buf) {
+  const msh = readMshSegment(buf);
+  if (msh === null) return null;
+  const id = msh.fields[9];
+  return id === void 0 || id === "" ? null : id;
+}
+function extractMsaControlId(buf) {
+  const msh = readMshSegment(buf);
+  if (msh === null) return null;
+  const fieldSep = msh.fieldSep.charCodeAt(0);
+  const end = buf.length;
+  let segStart = 0;
+  while (segStart < end) {
+    let segEnd = segStart;
+    while (segEnd < end && buf[segEnd] !== SEGMENT_SEPARATOR_CR && buf[segEnd] !== SEGMENT_SEPARATOR_LF) {
+      segEnd++;
+    }
+    if (segEnd - segStart >= 4 && buf[segStart] === ASCII_M && buf[segStart + 1] === ASCII_S && buf[segStart + 2] === ASCII_A && buf[segStart + 3] === fieldSep) {
+      let fieldIndex = 0;
+      let fieldStart = 0;
+      for (let i = segStart + 3; i <= segEnd; i++) {
+        const b = i < segEnd ? buf[i] : fieldSep;
+        if (b === fieldSep || b === SEGMENT_SEPARATOR_CR || b === SEGMENT_SEPARATOR_LF) {
+          fieldIndex++;
+          if (fieldIndex === 2) {
+            fieldStart = i + 1;
+          } else if (fieldIndex === 3) {
+            if (fieldStart >= i) return null;
+            return buf.subarray(fieldStart, i).toString(CONTROL_ID_ENCODING);
+          }
+        }
+      }
+      return null;
+    }
+    while (segEnd < end && (buf[segEnd] === SEGMENT_SEPARATOR_CR || buf[segEnd] === SEGMENT_SEPARATOR_LF)) {
+      segEnd++;
+    }
+    if (segEnd === segStart) return null;
+    segStart = segEnd;
+  }
+  return null;
+}
+var SUBPATH_NAME = "@cosyte/mllp/ack-from-hl7";
+var PEER_PACKAGE_NAME = "@cosyte/hl7";
+var MODULE_NOT_FOUND_CODES = /* @__PURE__ */ new Set([
+  "ERR_MODULE_NOT_FOUND",
+  "MODULE_NOT_FOUND"
+]);
+var MllpPeerMissingError = class _MllpPeerMissingError extends Error {
+  name = "MllpPeerMissingError";
+  /** Stable machine-readable code identifying this error class. */
+  code = "MLLP_PEER_MISSING";
+  /**
+   * Construct an `MllpPeerMissingError`.
+   *
+   * @param cause - The original module-resolution error, preserved for debugging.
+   */
+  constructor(cause) {
+    super(
+      `${PEER_PACKAGE_NAME} is required by ${SUBPATH_NAME} but is not installed. ${PEER_PACKAGE_NAME} is an optional peer dependency of @cosyte/mllp \u2014 install it alongside @cosyte/mllp to use ${SUBPATH_NAME}: \`npm install ${PEER_PACKAGE_NAME}\` (or the equivalent for your package manager).`,
+      { cause }
+    );
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _MllpPeerMissingError);
+    }
+  }
+};
+var cachedPeer;
+var PEER_UNRESOLVABLE_RE = /Cannot find (?:module|package) '@cosyte\/hl7'/;
+function isPeerModuleNotFound(err) {
+  if (typeof err !== "object" || err === null) return false;
+  const code = err.code;
+  if (typeof code !== "string" || !MODULE_NOT_FOUND_CODES.has(code)) return false;
+  const message = err.message;
+  return typeof message === "string" && PEER_UNRESOLVABLE_RE.test(message);
+}
+function loadHl7Peer(requireFn) {
+  if (cachedPeer !== void 0 && requireFn === void 0) {
+    return cachedPeer;
+  }
+  const doRequire = requireFn ?? module$1.createRequire(importMetaUrl);
+  let mod;
+  try {
+    mod = doRequire(PEER_PACKAGE_NAME);
+  } catch (err) {
+    if (isPeerModuleNotFound(err)) {
+      throw new MllpPeerMissingError(err);
+    }
+    throw err;
+  }
+  const peer = mod;
+  if (requireFn === void 0) {
+    cachedPeer = peer;
+  }
+  return peer;
+}
+
+// src/ack-from-hl7/build.ts
+var MLLP_ACK_INBOUND_UNPARSEABLE = "MLLP_ACK_INBOUND_UNPARSEABLE";
+var MLLP_ACK_CONTROL_ID_NOT_VERBATIM = "MLLP_ACK_CONTROL_ID_NOT_VERBATIM";
+var BYTES_INBOUND_ENCODING = "latin1";
+var TEXT_INBOUND_ENCODING = "utf8";
+function assertKnownAckCode(peer, code) {
+  const known = Object.values(peer.ACK_CODES);
+  if (typeof code !== "string" || !known.includes(code)) {
+    throw new TypeError(
+      `buildMllpAck: \`code\` must be a known HL7 Table 0008 acknowledgment code (AA/AE/AR/CA/CE/CR). Received: ${JSON.stringify(code)}.`
+    );
+  }
+}
+function resolveEncoding(inbound, options) {
+  if (options.encoding !== void 0) return options.encoding;
+  return Buffer.isBuffer(inbound) ? BYTES_INBOUND_ENCODING : TEXT_INBOUND_ENCODING;
+}
+function inboundBytes(inbound, encoding) {
+  if (Buffer.isBuffer(inbound)) return inbound;
+  if (typeof inbound === "string") return Buffer.from(inbound, encoding);
+  return void 0;
+}
+function verifyVerbatimEcho(ackPayload, inboundRaw) {
+  if (inboundRaw === void 0) return null;
+  const inboundId = extractMshControlId(inboundRaw);
+  if (inboundId === null) return null;
+  const echoedId = extractMsaControlId(ackPayload);
+  if (echoedId === inboundId) return null;
+  const inboundLen = String(inboundId.length);
+  const echoed = echoedId === null ? "absent" : `${String(echoedId.length)} bytes`;
+  return {
+    code: MLLP_ACK_CONTROL_ID_NOT_VERBATIM,
+    message: `ACK does not echo the inbound MSH-10 verbatim (HL7 v2.5.1 \xA72.9.2.2): inbound MSH-10 is ${inboundLen} bytes, emitted MSA-2 is ${echoed}, and they differ. The sender keys its in-flight store on the inbound bytes, so it will NOT match this ACK (ACK timeout -> resend -> duplicate message). Field values are withheld \u2014 MSH-10 is inbound payload content and this warning goes to a log; compare your inbound payload against MllpAck.payload to see the bytes.`
+  };
+}
+function toMllpAck(params) {
+  const { ack, requestedCode, code, correlationId, mode, warnings, options, encoding } = params;
+  const payload = Buffer.from(ack.toString(), encoding);
+  const frame = encodeFrame(payload, {
+    allowDelimiterBytesInPayload: options.allowDelimiterBytesInPayload ?? false
+  });
+  const echoWarning = verifyVerbatimEcho(payload, params.verifyAgainst);
+  const allWarnings = echoWarning === null ? warnings : [...warnings, echoWarning];
+  const result = {
+    frame,
+    payload,
+    ack,
+    requestedCode,
+    code,
+    correlationId,
+    mode,
+    warnings: Object.freeze([...allWarnings])
+  };
+  return Object.freeze(result);
+}
+function buildUnparseableFallback(peer, requestedCode, fatalCode, options, encoding) {
+  const code = peer.downgradePositiveAck(requestedCode);
+  const ack = peer.buildMessage({ type: "ACK" }).addSegment("MSA", [code, ""]);
+  const warnings = [
+    {
+      code: MLLP_ACK_INBOUND_UNPARSEABLE,
+      message: `Inbound message unparseable (${fatalCode}); emitted ${code} with no correlation id.`
+    }
+  ];
+  return toMllpAck({
+    ack,
+    requestedCode,
+    code,
+    correlationId: void 0,
+    mode: void 0,
+    warnings,
+    options,
+    encoding,
+    // MSA-2 is INTENTIONALLY empty here — the inbound could not be parsed, so there is no
+    // control id to echo and we refuse to fabricate one. Running the verbatim check would
+    // report that deliberate choice as a violation; `MLLP_ACK_INBOUND_UNPARSEABLE` (above)
+    // is the accurate warning for this case, and it is already attached.
+    verifyAgainst: void 0
+  });
+}
+function resolveInbound(peer, inbound, encoding) {
+  if (Buffer.isBuffer(inbound)) {
+    return peer.parseHL7(stripLeadingSegmentTerminators(inbound).toString(encoding));
+  }
+  if (typeof inbound === "string") {
+    return peer.parseHL7(inbound.replace(/^[\r\n]+/, ""));
+  }
+  const isPeerNative = inbound instanceof peer.Hl7Message;
+  return isPeerNative ? inbound : peer.parseHL7(inbound.toString());
+}
+function buildMllpAck(inbound, options) {
+  const peer = loadHl7Peer();
+  assertKnownAckCode(peer, options.code);
+  const encoding = resolveEncoding(inbound, options);
+  let msg;
+  try {
+    msg = resolveInbound(peer, inbound, encoding);
+  } catch (err) {
+    if (err instanceof peer.Hl7ParseError) {
+      return buildUnparseableFallback(peer, options.code, err.code, options, encoding);
+    }
+    throw err;
+  }
+  const mode = peer.detectAckMode(msg);
+  const ack = peer.buildAck(
+    msg,
+    options.error === void 0 ? { code: options.code, mode } : { code: options.code, error: options.error, mode }
+  );
+  const emittedCode = ack.get("MSA.1");
+  assertKnownAckCode(peer, emittedCode);
+  const msa2 = ack.segments("MSA")[0]?.field(2).text ?? "";
+  const correlationId = msa2 !== "" ? msa2 : void 0;
+  const warnings = ack.warnings.map((w) => ({
+    code: w.code,
+    message: w.message
+  }));
+  return toMllpAck({
+    ack,
+    requestedCode: options.code,
+    code: emittedCode,
+    correlationId,
+    mode,
+    warnings,
+    options,
+    encoding,
+    verifyAgainst: inboundBytes(inbound, encoding)
+  });
+}
+function buildAckAA(inbound, options) {
+  return buildMllpAck(inbound, { ...options, code: "AA" });
+}
+function buildAckAE(inbound, options) {
+  return buildMllpAck(inbound, { ...options, code: "AE" });
+}
+function buildAckAR(inbound, options) {
+  return buildMllpAck(inbound, { ...options, code: "AR" });
+}
+function buildAckCA(inbound, options) {
+  return buildMllpAck(inbound, { ...options, code: "CA" });
+}
+function buildAckCE(inbound, options) {
+  return buildMllpAck(inbound, { ...options, code: "CE" });
+}
+function buildAckCR(inbound, options) {
+  return buildMllpAck(inbound, { ...options, code: "CR" });
+}
+function detectMode(inbound) {
+  const peer = loadHl7Peer();
+  const msg = resolveInbound(peer, inbound, BYTES_INBOUND_ENCODING);
+  return peer.detectAckMode(msg);
+}
+
+exports.MLLP_ACK_CONTROL_ID_NOT_VERBATIM = MLLP_ACK_CONTROL_ID_NOT_VERBATIM;
+exports.MLLP_ACK_INBOUND_UNPARSEABLE = MLLP_ACK_INBOUND_UNPARSEABLE;
+exports.MllpPeerMissingError = MllpPeerMissingError;
+exports.buildAckAA = buildAckAA;
+exports.buildAckAE = buildAckAE;
+exports.buildAckAR = buildAckAR;
+exports.buildAckCA = buildAckCA;
+exports.buildAckCE = buildAckCE;
+exports.buildAckCR = buildAckCR;
+exports.buildMllpAck = buildMllpAck;
+exports.detectMode = detectMode;
+exports.loadHl7Peer = loadHl7Peer;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map