@glion/mllp-client 0.16.0 → 0.19.0

package/README.md

@@ -1,322 +1,497 @@
 # @glion/mllp-client
 
-MLLP client for sending HL7v2 messages and receiving acknowledgments.
+A simple HL7v2 MLLP client for Node.js and Cloudflare Workers.
 
-## What it does
+- 📦 **MLLP built in.** Framing, message boundaries and acknowledgment matching are handled. You send a parsed message and get one back.
+- 🔄 **Predictable connection lifecycle.** Timeouts on connecting and on waiting for a reply, connection attempts retried with backoff, TCP keepalive by default, and explicit states you can read.
+- ⚡ **Thin over TCP.** One socket, one message at a time. No queue, no worker threads, no polling.
+- 🧯 **Errors you can act on.** Every failure carries a stable code and says whether the connection is still usable.
+- 🧩 **Any transport.** TCP included. TLS, Cloudflare Workers or an in-memory socket plug in behind it.
+- 🔤 **Typed end to end.** TypeScript throughout, with parsed HL7v2 going in and coming out.
 
-`@glion/mllp-client` exports an `MllpClient` class that sends HL7v2 messages over MLLP/TCP and returns the parsed acknowledgment. Each `send()` opens a one-shot TCP (or TLS) connection, MLLP-frames the message, awaits a single ACK frame, parses it, and tears the connection down — modeled after a single HTTP request/response. NAK responses (MSA-1 ∈ {AE, AR, CE, CR}) are thrown as the matching `AckException` subclass from `@glion/ack`, so callers catch the same exception types that `@glion/mllp-ack` produces on the receiver side. Each thrown exception carries the original raw ACK on its `raw` attribute, so callers can re-parse, log, or persist the wire payload without intercepting the response separately. Transport-level failures (connection refused, timeout, malformed frame) are thrown as `MllpClientError`, a subclass of `MllpError` from `@glion/mllp-transport`.
+> **Coming soon** — TLS and Cloudflare Workers adapters. Today the only bundled adapter is Node.js over TCP.
 
 ## Install
 
 ```bash
-npm install @glion/mllp-client @glion/ack
+npm install @glion/mllp-client
 ```
 
-`@glion/ack` is required because `client.send()` throws its `AckException` subclasses on NAK responses; install it alongside the client so application code can `import { AckApplicationError } from "@glion/ack"` directly.
-
-## Runtime support
-
-`@glion/mllp-client` runs on every JavaScript runtime that can open a raw TCP socket. Pick the import path that matches your runtime — the client API is identical in every case.
-
-| Runtime                | Import path                  | Connector                          | Status                  |
-| ---------------------- | ---------------------------- | ---------------------------------- | ----------------------- |
-| **Node.js**            | `@glion/mllp-client/node`    | `node:net` / `node:tls`            | shipped                 |
-| **Bun**                | `@glion/mllp-client/node`    | `node:net` / `node:tls` (compat)   | core verified[^2]       |
-| **Deno**               | —                            | `Deno.connect` / `Deno.connectTls` | in progress (PR [#615]) |
-| **Cloudflare Workers** | `@glion/mllp-client/workers` | `cloudflare:sockets`               | shipped                 |
-
-[^2]: The runtime-free core (`@glion/mllp-client/core`) is exercised under Bun in CI via `pnpm test:bun`. The Node adapter is not currently part of the Bun test matrix; Bun's `node:net`/`node:tls` compatibility means it works in practice, but regressions are caught by Node CI rather than Bun CI.
-
-Always import from the runtime-specific subpath (`@glion/mllp-client/workers`, `@glion/mllp-client/node`). Some bundlers honour the `workerd` key in this package's `exports` map and will resolve the bare specifier `@glion/mllp-client` to the Workers entry on a Workers target — but bundler support for `exports` conditions varies, so the subpath is the only path the package guarantees.
-
-> **Heads-up.** The Deno adapter is being reviewed in a separate pull request and is not yet part of a release. The runtime-agnostic core is stable; you can wire your own `MllpConnect` against any transport (or a custom test harness) by importing from `@glion/mllp-client/core` until that adapter lands.
-
-[#615]: https://github.com/rethinkhealth/glion/pull/615
-
-**Browsers cannot run this client directly** — they have no API for raw TCP sockets.
+Node.js 22 or later. ESM only.
 
 ## Use
 
+### Send a message
+
 ```ts
+import { parseHL7v2 } from "@glion/parser";
 import { MllpClient } from "@glion/mllp-client";
+import { nodeSocket } from "@glion/mllp-client/node";
 
-// TLS-on by default — see "Plain TCP" below for opt-out
-const client = new MllpClient({ host: "mllp.example.com", port: 6661 });
+await using client = new MllpClient({
+  socket: nodeSocket({ host: "hl7.example.org", port: 2575 }),
+});
 
-const ack = await client.send(
+const adt = parseHL7v2(
   [
-    "MSH|^~\\&|SendApp|SendFac|RecvApp|RecvFac|20240101120000||ADT^A01^ADT_A01|MSG001|P|2.5.1",
-    "EVN|A01|20240101120000",
-    "PID|1||12345^^^MRN||Doe^John",
+    "MSH|^~\\&|SENDER|FAC|RECV|FAC|20260101120000||ADT^A01|MSG00001|P|2.5",
+    "EVN|A01|20260101120000",
+    "PID|1||12345^^^MRN||DOE^JOHN||19800101|M",
   ].join("\r")
 );
 
-console.log(ack.code); // "AA"
-console.log(ack.controlId); // "MSG001"
+const ack = await client.send(adt);
+ack.code; //=> "AA" or "CA"
+ack.raw; //=> the acknowledgment as text
+ack.tree; //=> the acknowledgment as a tree
 ```
 
-Catch a NAK from the receiver as a typed exception. The original raw ACK is available on `error.raw`:
+`send()` connects on first use, so `connect()` is optional. `await using` closes the client at the end of the block; without it, call `close()`.
 
-```ts
-import { AckApplicationError, AckApplicationReject } from "@glion/ack";
-import { MllpClient, MllpClientError } from "@glion/mllp-client";
+### Handle a rejection
 
-const client = new MllpClient({ host: "127.0.0.1", port: 2575 });
+A NAK means the receiver read your message and refused it — a bad field, a patient it does not know, a message type it does not handle. `send()` throws, and the connection stays open for the next message.
+
+```ts
+import { AckException } from "@glion/ack";
+import { MllpClientError } from "@glion/mllp-client";
 
 try {
-  await client.send(rawMessage);
+  await client.send(adt);
 } catch (error) {
-  if (error instanceof AckApplicationError) {
-    // MSA-1 = AE — receiver returned an application-level error.
-    // error.message holds MSA-3; error.errorCode holds ERR-3; error.severity holds ERR-4.
-    // error.raw holds the wire-format ACK message.
-  } else if (error instanceof AckApplicationReject) {
-    // MSA-1 = AR — receiver rejected the message.
+  if (error instanceof AckException) {
+    error.code; //=> "AE", "AR", "CE", or "CR"
+    error.text; //=> the receiver's reason, when it gave one
   } else if (error instanceof MllpClientError) {
-    // Transport-level failure: error.code is one of CONNECTION_REFUSED,
-    // TIMEOUT, CONNECTION_CLOSED, MALFORMED_FRAME, or MALFORMED_ACK.
+    error.code; //=> e.g. "SEND_TIMEOUT" — see Errors
   }
 }
 ```
 
-Send over plain TCP — opt out of the secure default. Use only when the wire is already protected (trusted hospital intranet, VPN tunnel, or a TLS terminator hop in front of the receiver):
+### Connect at startup
+
+`connect()` opens the connection without sending anything. Call it at startup to find out immediately that a host, port, or firewall is wrong, instead of on your first real message.
 
 ```ts
 const client = new MllpClient({
-  host: "127.0.0.1",
-  port: 2575,
-  tls: false,
+  socket: nodeSocket({ host: "hl7.example.org", port: 2575 }),
 });
-
-const ack = await client.send(rawMessage);
+await client.connect();
 ```
 
-Send over TLS with explicit configuration (mutual TLS, custom CA, etc.):
+Calling it twice is safe. On a connected client it returns immediately; while a connection is still opening, it waits for that attempt and shares its result.
 
-```ts
-import { readFileSync } from "node:fs";
+### Reconnect
+
+A connection that cannot be opened is dialed again. By default the client makes five further attempts, waiting a random time before each: up to 1 s, then 2 s, 4 s, 8 s, and 16 s, so it gives up about 30 seconds after the first failure and closes with the last attempt's error. `attempts: Infinity` keeps dialing; `close()` stops it. A `send()` that arrives while the client is connecting waits for the outcome.
 
+A connection that is lost is not restored. The client closes with the failure, and the message in flight is **not sent again**: its `send()` rejects, and whether the receiver got it is the caller's to decide. A client is as disposable as a socket: construct a new one to send again.
+
+```ts
 const client = new MllpClient({
-  host: "mllp.example.com",
-  port: 6661,
-  tls: {
-    ca: readFileSync("ca.pem"),
-    cert: readFileSync("client-cert.pem"),
-    key: readFileSync("client-key.pem"),
+  socket: nodeSocket({ host: "hl7.example.org", port: 2575 }),
+  reconnect: {
+    attempts: 20,
+    delay: (attempt) => {
+      logger.warn({ attempt }, "mllp reconnecting");
+      return Math.min(30_000, 500 * 2 ** attempt);
+    },
   },
 });
-
-const ack = await client.send(rawMessage);
 ```
 
-The same code on **Cloudflare Workers**:
+`reconnect: false` turns it off: the client dials once.
 
-```ts
-import { MllpClient } from "@glion/mllp-client/workers";
+## Options
+
+| Option             | Type                            | Default   | Description                                                                                            |
+| ------------------ | ------------------------------- | --------- | ------------------------------------------------------------------------------------------------------ |
+| `socket`           | `MllpSocket`                    | required  | Runtime adapter, such as `nodeSocket({ host, port })`.                                                 |
+| `connectTimeoutMs` | `number`                        | `10000`   | Time allowed to open the connection. Exceeded: `MllpConnectionTimeoutError`.                           |
+| `sendTimeoutMs`    | `number`                        | `30000`   | Time allowed from writing a message to receiving its acknowledgment. Exceeded: `MllpSendTimeoutError`. |
+| `maxBufferedBytes` | `number`                        | 16 MiB    | Largest reply the client buffers. Exceeded: `MllpInvalidResponseError`.                                |
+| `reconnect`        | `MllpReconnectOptions \| false` | see below | How the client dials again after a failed attempt. `false` dials once.                                 |
+
+`send(message, { timeoutMs })` overrides `sendTimeoutMs` for one message.
+
+`MllpReconnectOptions`:
+
+| Option     | Type                          | Default                                      | Description                                                                        |
+| ---------- | ----------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `attempts` | `number`                      | `5`                                          | Attempts after a failed one before the client closes. `Infinity` for no limit.     |
+| `delay`    | `(attempt: number) => number` | full-jitter backoff from 1 s, capped at 30 s | Milliseconds to wait before `attempt` (from 1). Called only while attempts remain. |
 
-const client = new MllpClient({ host: "127.0.0.1", port: 2575 });
-const ack = await client.send(rawMessage);
+## API
+
+### `new MllpClient(options)`
+
+```ts
+new MllpClient(options: MllpClientOptions): MllpClient
 ```
 
-The Workers runtime cannot honour programmatic TLS material. Passing any of `tls.ca`, `tls.cert`, `tls.key`, `tls.passphrase`, `tls.servername`, or `tls.insecure: true` to the Workers adapter throws `MllpClientError` with `code: "INVALID_INPUT"` **before any socket is opened**. Configure TLS material via the Cloudflare platform — Hyperdrive, Worker bindings, or terminate TLS upstream of the receiver. The error path:
+Creates a client for one remote system. Nothing is opened until the first `connect()` or `send()`.
+
+**Parameters** — see [Options](#options).
+
+**Throws** `MllpInvalidOptionError` when a timeout is not a positive number of milliseconds, `maxBufferedBytes` is not a positive integer, or `reconnect.attempts` is not a non-negative integer.
 
 ```ts
-import { MllpClient, MllpClientError } from "@glion/mllp-client/workers";
+const client = new MllpClient({
+  socket: nodeSocket({ host: "hl7.example.org", port: 2575 }),
+  sendTimeoutMs: 10_000,
+});
+```
 
-try {
-  const client = new MllpClient({
-    host: "mllp.example.com",
-    port: 6661,
-    tls: { ca: caPem }, // rejected on Workers
-  });
-  await client.send(rawMessage);
-} catch (error) {
-  if (error instanceof MllpClientError && error.code === "INVALID_INPUT") {
-    // error.message names the rejected fields and points at the docs.
-  }
-}
+### `client.send(message, options?)`
+
+```ts
+send(message: Root, options?: { timeoutMs?: number }): Promise<MllpClientResponse>
 ```
 
-## Options
+Sends one message and resolves with the acknowledgment that answers it. Connects first if the client is not connected.
 
-`MllpClientOptions`:
+| Parameter           | Type     | Description                                              |
+| ------------------- | -------- | -------------------------------------------------------- |
+| `message`           | `Root`   | A parsed HL7v2 message. Must carry an MSH-10 control ID. |
+| `options.timeoutMs` | `number` | Overrides `sendTimeoutMs` for this message only.         |
 
-| Option       | Type                              | Default | Description                                                                                                                                                                |
-| ------------ | --------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `host`       | `string`                          | —       | Hostname or IP of the MLLP server.                                                                                                                                         |
-| `port`       | `number`                          | —       | TCP port of the MLLP server.                                                                                                                                               |
-| `timeout`    | `number`                          | `30000` | Maximum total milliseconds for connect → send → ACK.                                                                                                                       |
-| `maxAckSize` | `number`                          | —       | Maximum bytes accepted for an inbound ACK frame. No limit when omitted.                                                                                                    |
-| `tls`        | `boolean \| MllpClientTlsOptions` | `true`  | TLS configuration. Defaults to `true` (TLS-on, system trust store, hostname verification). Pass an options object for custom config, or `false` to opt out into plain TCP. |
+**Returns** an `MllpClientResponse`:
 
-`MllpClientTlsOptions`:
+| Field       | Type             | Description                                         |
+| ----------- | ---------------- | --------------------------------------------------- |
+| `code`      | `AckSuccessCode` | MSA-1, `AA` or `CA`.                                |
+| `controlId` | `string`         | MSA-2: the control ID of the message this answers.  |
+| `id`        | `string`         | The acknowledgment's own MSH-10.                    |
+| `text`      | `string?`        | MSA-3, the receiver's diagnostic, when it gave one. |
+| `tree`      | `Root`           | The acknowledgment, parsed.                         |
+| `raw`       | `string`         | The acknowledgment as text.                         |
 
-| Option       | Type               | Description                                                                                                                                                                 |
-| ------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ca`         | `string \| Buffer` | Trusted CA certificate(s) for verifying the server.                                                                                                                         |
-| `cert`       | `string \| Buffer` | Client certificate for mutual TLS.                                                                                                                                          |
-| `key`        | `string \| Buffer` | Client private key for mutual TLS.                                                                                                                                          |
-| `passphrase` | `string`           | Passphrase for the private key.                                                                                                                                             |
-| `servername` | `string`           | Server name for SNI and certificate verification. Defaults to `host`. Setting this to anything other than the real hostname disables strict hostname verification.          |
-| `insecure`   | `true`             | **Test/dev only.** Disable server-certificate verification. Only the literal value `true` opts out — there is no `false` form because the secure default is non-negotiable. |
+**Throws**
 
-## API
+- `AckException` — the receiver refused the message. The connection stays open.
+- `MllpInvalidMessageError` — no MSH-10, or the message could not be serialized. Nothing was sent.
+- `MllpInvalidOptionError` — `timeoutMs` is out of range. Nothing was sent.
+- `MllpAlreadySendingError` — another send is in flight.
+- `MllpClientClosedError` — the client is closed.
+- `MllpConnectionFailedError`, `MllpConnectionTimeoutError` — the connection could not be opened.
+- `MllpSendTimeoutError`, `MllpConnectionLostError`, `MllpInvalidResponseError` — the exchange failed. These close the connection; see [Errors](#errors).
 
-### `new MllpClient(options)`
+Every error carries `delivery`, `not-sent` or `unknown`, the one fact a retry needs; see [Errors](#errors).
 
-Construct a client bound to a host/port. The constructor does not open a connection — every `send()` call opens its own.
+One message at a time. To send several, await each in turn:
 
 ```ts
-import { MllpClient } from "@glion/mllp-client";
+for (const message of batch) {
+  const ack = await client.send(message);
+  record(ack.controlId, ack.code);
+}
+```
+
+### `client.connect()`
 
-const client = new MllpClient({ host: "127.0.0.1", port: 2575 });
-client.host; // "127.0.0.1"
-client.port; // 2575
+```ts
+connect(): Promise<void>
 ```
 
-### `client.send(message, options?)`
+Opens the connection without sending anything, dialing again under the [reconnect](#reconnect) policy when an attempt fails. Optional — `send()` connects on first use — but calling it at startup surfaces a wrong host, port, or firewall rule as soon as the policy gives up.
 
-Send a single HL7v2 message and resolve with the resolving accept ACK. Returns a `Promise<Acknowledgment>`. Accepts a `string` or `Uint8Array` payload. Opens a TCP/TLS connection, writes the MLLP-framed bytes, reads acknowledgment frames according to `options.mode`, and closes the connection when the resolving frame arrives.
+Idempotent. On a connected client it resolves at once; while an attempt is in flight it waits for the outcome and shares it.
 
-On NAK (MSA-1 ∈ {AE, AR, CE, CR}) throws the matching `AckException` subclass with the original wire-format ACK on `error.raw`.
+**Throws** the last attempt's `MllpConnectionFailedError` or `MllpConnectionTimeoutError`, or `MllpClientClosedError` when the client is already closed or `close()` cancelled the attempt.
 
-To observe each accept ACK as it arrives (e.g. seeing the intermediate `CA` frame in HL7v2 enhanced mode), use [`client.stream()`](#clientstreammessage-options) instead.
+### `client.close()`
 
 ```ts
-const ack = await client.send(rawHl7Message);
+close(): Promise<void>
 ```
 
-`options` is optional:
+Closes the connection once the message in flight has been acknowledged. New sends are refused from the moment it is called, so an in-flight message is never cut off. An attempt to connect stops at once.
 
-| Field    | Type                            | Default           | Description                                                                                                    |
-| -------- | ------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------- |
-| `signal` | `AbortSignal`                   | —                 | Cancel the in-flight send. Composed with the client's `timeout` via `AbortSignal.any` so either source aborts. |
-| `mode`   | `"OnApplication" \| "OnCommit"` | `"OnApplication"` | Which HL7v2 acknowledgment level resolves the send. See [Acknowledgment modes](#acknowledgment-modes).         |
+Resolves when the connection is down, from any phase. Never throws. Idempotent. The wait is bounded by the in-flight send's own deadline.
 
-### `client.stream(message, options?)`
+```ts
+process.on("SIGTERM", async () => {
+  await client.close();
+  process.exit(0);
+});
+```
+
+### `client.destroy()`
+
+```ts
+destroy(): Promise<void>
+```
 
-Send a single HL7v2 message and yield each accept ACK as it arrives. Returns an `AsyncIterable<Acknowledgment>`. Accepts the same `message` and `options` as `client.send()`.
+Closes the connection now, without waiting for anything in flight. A message in flight rejects with `MllpSendAbortedError`. An attempt to connect stops at once.
 
-The iterable completes after the resolving accept frame: in HL7v2 enhanced mode it yields `CA` then the application-level ACK; in basic mode it yields a single application-level ACK. NAK codes (`AE`/`AR`/`CE`/`CR`) throw the matching `AckException` from the iterator, exactly as they would from `await client.send(...)`. Breaking out of the loop closes the underlying socket.
+Resolves when the connection is down, from any phase. Never throws. Idempotent.
+
+### `client[Symbol.asyncDispose]()`
+
+Calls `close()`. Lets a client be scoped with `await using`:
 
 ```ts
-for await (const ack of client.stream(rawHl7Message)) {
-  log.info({ code: ack.code }, "ack received");
-}
+{
+  await using client = new MllpClient({ socket });
+  await client.send(message);
+} // closed here, even if send() threw
+```
+
+### `client.state`
+
+```ts
+readonly state: MllpClientState
 ```
 
-### `Acknowledgment`
+| Value        | Meaning                                                                     |
+| ------------ | --------------------------------------------------------------------------- |
+| `idle`       | Nothing opened yet. The first `send()` or `connect()` opens the connection. |
+| `connecting` | The connection is being opened, further attempts included.                  |
+| `connected`  | Open, with no message in flight.                                            |
+| `sending`    | A message is on the wire, waiting for its acknowledgment.                   |
+| `closing`    | `close()` is waiting out the message in flight.                             |
+| `closed`     | Done.                                                                       |
+
+A client closes once. After `close()`, `destroy()`, a connection the reconnect policy could not open, or a connection that was lost, every call throws `MllpClientClosedError`; construct a new client to send again.
 
-The HL7v2 acknowledgment returned by `client.send()`.
+### `client.connected`
 
-| Field         | Type                  | Description                                                           |
-| ------------- | --------------------- | --------------------------------------------------------------------- |
-| `raw`         | `string`              | The raw HL7v2 ACK message as received from the wire.                  |
-| `tree`        | `Root`                | The ACK message AST.                                                  |
-| `code`        | `string`              | MSA-1 acknowledgment code (`AA`, `AE`, `AR`, `CA`, `CE`, or `CR`).    |
-| `controlId`   | `string`              | MSA-2 message control ID — references the original message's MSH-10.  |
-| `textMessage` | `string \| undefined` | MSA-3 text message. Present on NAK; optional on ACK.                  |
-| `errorCode`   | `string \| undefined` | ERR-3 HL7 error condition code (Table 0357). Present when ERR is set. |
-| `severity`    | `string \| undefined` | ERR-4 severity (Table 0516). Present when ERR is set.                 |
+```ts
+readonly connected: boolean
+```
 
-### `MllpClientError`
+`true` in `connected` and `sending`, `false` everywhere else.
 
-A subclass of `MllpError` from `@glion/mllp-transport`, thrown for transport-level failures. The `code` property identifies the failure mode:
+### `client.on(event, listener)` / `client.off(event, listener)`
 
-| `code`                 | Meaning                                                                                       |
-| ---------------------- | --------------------------------------------------------------------------------------------- |
-| `INVALID_INPUT`        | A constructor option or send payload was rejected before any socket was opened.               |
-| `CONNECTION_REFUSED`   | The TCP connection could not be established (refused, DNS, routing).                          |
-| `TLS_HANDSHAKE_FAILED` | TLS handshake failed (certificate, protocol, or trust-store mismatch). Node adapter only.[^1] |
-| `CONNECTION_CLOSED`    | The peer closed the connection before a complete ACK arrived.                                 |
-| `TIMEOUT`              | No ACK arrived within `timeout`.                                                              |
-| `MALFORMED_FRAME`      | Bytes received did not form a valid MLLP frame.                                               |
-| `MALFORMED_ACK`        | The ACK frame was received but could not be parsed as HL7v2.                                  |
+```ts
+on<E>(event: E, listener: MllpClientListener<E>): this
+off<E>(event: E, listener: MllpClientListener<E>): this
+```
 
-[^1]: The Workers adapter cannot distinguish a TLS handshake failure from a TCP connect failure; both surface as `CONNECTION_REFUSED`. Cross-runtime callers switching on `error.code` should treat `CONNECTION_REFUSED` as the supertype.
+Adds or removes a listener. Both return the client, so calls chain.
 
-### Application-level NAK exceptions
+| Event     | Listener                                   | Fires when                                                                                                                                                  |
+| --------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `connect` | `() => void`                               | The connection opened.                                                                                                                                      |
+| `close`   | `(error: MllpClientError \| null) => void` | The client is done. Fires once, from any phase, even if it never connected. `error` is the failure it could not recover from, or `null` when you closed it. |
 
-`MllpClient.send()` throws the same `AckException` subclasses that `@glion/mllp-ack` produces on the receiver side: `AckApplicationError` (AE), `AckApplicationReject` (AR), `AckCommitError` (CE), `AckCommitReject` (CR), and the abstract base `AckException`. They are not re-exported from this package — install `@glion/ack` and import them directly:
+A lost connection is not an event of its own: it closes the client, so `close` fires with the failure. Listeners are synchronous, and one that throws propagates to whatever triggered the event.
 
 ```ts
-import { AckApplicationError, AckException } from "@glion/ack";
+client
+  .on("connect", () => metrics.increment("mllp.connected"))
+  .on("close", (error) => {
+    logger.warn({ code: error?.code ?? "closed_by_owner" }, "mllp closed");
+  });
 ```
 
-Keeping a single import path keeps `@glion/ack` as the authoritative source for the exception hierarchy across both client and server code paths.
+## Runtimes
 
-## Behavior
+The client speaks MLLP over a pair of byte streams and knows nothing else about the transport. That whole dependency is [`MllpSocket`](#custom-socket) — two methods — so supporting a new runtime means writing an adapter, not forking the client.
 
-### NAK to exception mapping
+Node.js is the only adapter that ships today.
 
-| MSA-1 | Thrown class           | Source fields                                                                |
-| ----- | ---------------------- | ---------------------------------------------------------------------------- |
-| `AA`  | — (resolves)           | —                                                                            |
-| `CA`  | — (resolves)           | —                                                                            |
-| `AE`  | `AckApplicationError`  | `message` ← MSA-3, `errorCode` ← ERR-3, `severity` ← ERR-4, `raw` ← wire ACK |
-| `AR`  | `AckApplicationReject` | same                                                                         |
-| `CE`  | `AckCommitError`       | same                                                                         |
-| `CR`  | `AckCommitReject`      | same                                                                         |
+### Node.js
 
-Every thrown `AckException` carries the original raw ACK message on its `raw` attribute. When MSA-3 is empty, the thrown error's `message` defaults to `Acknowledgment <code> from receiver`. When ERR-3 is missing, `errorCode` defaults to `Hl7ErrorCode.ApplicationInternalError` (`207`). When ERR-4 is missing, `severity` defaults to `Severity.Error` (`E`).
+```ts
+import { nodeSocket } from "@glion/mllp-client/node";
+
+nodeSocket(options: NodeSocketOptions): MllpSocket
+```
 
-### Acknowledgment modes
+Plain TCP over `net.Socket`.
 
-HL7v2 §2.9.2 defines two acknowledgment levels — the same wire protocol carries both. Each `send()` picks which one to wait for via the `mode` option:
+| Option            | Type     | Default  | Description                                                                                                 |
+| ----------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------- |
+| `host`            | `string` | required | Host name or address of the receiver.                                                                       |
+| `port`            | `number` | required | TCP port of the receiver.                                                                                   |
+| `gracefulCloseMs` | `number` | `1000`   | How long a socket gets to end cleanly before it is destroyed.                                               |
+| `keepAliveIdleMs` | `number` | `30000`  | Idle time before the first keepalive probe, so a silent NAT or firewall drop surfaces before the next send. |
 
-- `mode: "OnApplication"` (default) — return when the application-level ACK arrives (`AA`/`AE`/`AR`). Intermediate `CA` (Commit Accept) frames sent by enhanced-mode receivers are surfaced via iteration but do not resolve the send. Use this when you need to know that the receiver successfully processed the message.
-- `mode: "OnCommit"` — return on the first frame regardless of code, typically a commit-level ACK (`CA`). The send resolves as soon as the receiver confirms receipt; later application-level frames are not observed because the connection is closed. Use this for receivers that only send commit-level ACKs (basic mode) or when the commit confirmation is what you need.
+`TCP_NODELAY` is set, so a message goes out immediately rather than waiting on Nagle's algorithm.
 
 ```ts
-// Default — wait for application-level processing to complete.
-const ack = await client.send(message); // resolves with AA, throws AckException on AE/AR
+const client = new MllpClient({
+  socket: nodeSocket({ host: "hl7.example.org", port: 2575 }),
+});
+```
+
+### Custom Socket
+
+You can expand `MllpSocket` to build a custom socket to one remote system, which the client opens, uses, and ends.
 
-// Resolve as soon as the receiver acknowledges receipt.
-const commit = await client.send(message, { mode: "OnCommit" }); // resolves with CA
+```ts
+interface MllpSocket {
+  connect(signal: AbortSignal): Promise<MllpStreams>;
+  close(): Promise<void>;
+}
+
+interface MllpStreams {
+  readonly readable: ReadableStream<Uint8Array>;
+  readonly writable: WritableStream<Uint8Array>;
+}
 ```
 
-### Streaming acknowledgments
+An implementation must satisfy four rules:
 
-`client.send()` resolves with the resolving accept ACK — the simple "give me the answer" path. `client.stream()` is the sibling method for real-time observation: it yields each accept ACK as it arrives and completes after the resolving frame. The intermediate `CA` is visible before the application-level frame in enhanced mode.
+1. `connect()` rejects with `signal.reason` when the signal aborts, and a rejection leaves nothing open.
+2. `close()` never rejects, may be called more than once, and always finishes within a bounded time, even when the receiver never answers.
+3. When the socket ends, a pending read on `readable` ends or errors. Bytes sent before a clean close arrive first.
+4. The client owns the streams while connected, and releases them before calling `close()`.
+
+An implementation never sees an MLLP frame — framing belongs to the layer above.
+
+## Errors
+
+Every failure the client raises extends `MllpClientError` and carries three fixed things: a `code`, one word per class for a `switch` or a log field; a `delivery`, what became of the message; and a message that never changes. Errors from the layers below arrive on `cause`, never as the thrown type.
+
+A rejection from the receiver is **not** an `MllpClientError` — see [`AckException`](#ackexception).
+
+`delivery` is the one fact a retry decision needs:
+
+| `delivery` | Meaning                                                                           | Codes                                                                                                       |
+| ---------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `not-sent` | Nothing reached the wire. The message may be sent again as it is.                 | `INVALID_OPTION`, `INVALID_MESSAGE`, `ALREADY_SENDING`, `CLOSED`, `CONNECTION_FAILED`, `CONNECTION_TIMEOUT` |
+| `unknown`  | The message may have reached the receiver. Sending it again may deliver it twice. | `SEND_TIMEOUT`, `CONNECTION_LOST`, `SEND_ABORTED`, `INVALID_RESPONSE`                                       |
 
 ```ts
-for await (const ack of client.stream(message)) {
-  log.info({ code: ack.code }, "ack received");
-  // stream completes itself after the resolving frame
+import { MllpClientError, MllpErrorCode } from "@glion/mllp-client";
+
+try {
+  await client.send(message);
+} catch (error) {
+  if (error instanceof MllpClientError) {
+    if (error.delivery === "not-sent") {
+      return requeue(message); // safe to send again
+    }
+    switch (error.code) {
+      case MllpErrorCode.INVALID_RESPONSE:
+        return quarantine(message); // the receiver answered, unreadably
+      default:
+        return holdForReview(message); // it may already have been processed
+    }
+  }
 }
 ```
 
-NAK codes (`AE`/`AR`/`CE`/`CR`) throw the matching `AckException` from both `send()` and `stream()` — same exception, same `error.raw`. Streams that want to inspect a NAK can wrap the loop in `try/catch`.
+The four failures of the wire — `CONNECTION_FAILED`, `CONNECTION_TIMEOUT`, `SEND_TIMEOUT`, `CONNECTION_LOST` — also extend `MllpConnectionError`, one `instanceof` for "the link, not the message".
+
+### `INVALID_OPTION`
+
+`MllpInvalidOptionError` · delivery `not-sent`
+
+A constructor option or a per-send `timeoutMs` is out of range — a timeout that is not a positive number of milliseconds, a `maxBufferedBytes` that is not a positive integer, or a `reconnect.attempts` that is not a non-negative integer or `Infinity`. The message names which one.
+
+Thrown before anything is opened or sent. A configuration bug, not a runtime condition.
+
+### `INVALID_MESSAGE`
+
+`MllpInvalidMessageError` · delivery `not-sent` · field: `cause`
+
+The message cannot be sent as it stands: no MSH-10 control ID, or it could not be serialized, or its content contains a byte MLLP reserves as a frame marker.
+
+**Nothing reached the wire and the connection is still in step**, so the next message can go out on it. Fix or quarantine the message; do not reconnect.
+
+### `ALREADY_SENDING`
+
+`MllpAlreadySendingError` · delivery `not-sent` · field: `controlId`
+
+`send()` was called while another send was in flight. `controlId` identifies the message already on the wire.
+
+The client is lockstep by design. Await each send before starting the next, or give each concurrent stream its own client.
+
+### `CLOSED`
+
+`MllpClientClosedError` · delivery `not-sent` · field: `cause`
+
+The client is closed, so the call cannot be served. Also the error a `connect()` gets when `close()` cancelled the attempt it was waiting for.
+
+A client closes once. Construct a new one to send again. When the client closed because the reconnect policy gave up, `cause` is the last attempt's failure.
+
+### `CONNECTION_FAILED`
+
+`MllpConnectionFailedError` · delivery `not-sent` · field: `cause`
+
+The socket could not be opened. `cause` carries the underlying error — `ECONNREFUSED`, `ENOTFOUND`, `EHOSTUNREACH` and the like.
+
+Check host, port, and whether a firewall allows the route. Nothing was opened, so there is nothing to close.
+
+### `CONNECTION_TIMEOUT`
+
+`MllpConnectionTimeoutError` · delivery `not-sent` · field: `timeoutMs`
+
+The receiver did not accept the connection within `connectTimeoutMs`.
+
+Typically a packet-dropping firewall rather than a refused connection — a refusal arrives fast and surfaces as `CONNECTION_FAILED`.
+
+### `SEND_TIMEOUT`
+
+`MllpSendTimeoutError` · delivery `unknown` · field: `timeoutMs` — **closes the connection**
+
+No acknowledgment arrived within the send timeout.
+
+Whether the receiver got the message is unknown: it may be slow, or it may have processed the message and failed to reply. The connection closes because a late acknowledgment can no longer be told apart from the next message's — see [Why does a failed send close the connection?](#why-does-a-failed-send-close-the-connection). The client closes with this error; the message is not sent again.
+
+### `CONNECTION_LOST`
+
+`MllpConnectionLostError` · delivery `unknown` · field: `cause` — **closes the connection**
+
+The link went away mid-send: the receiver hung up, or the network broke. `cause` carries the stream error when there was one.
+
+Whether the message was received is unknown. The client closes with this error; the message is not sent again.
+
+### `SEND_ABORTED`
+
+`MllpSendAbortedError` · delivery `unknown`
+
+`destroy()` cut off the message in flight. `close()` never raises this: it waits the message out.
+
+### `INVALID_RESPONSE`
+
+`MllpInvalidResponseError` · delivery `unknown` · fields: `controlId?`, `cause` — **closes the connection**
+
+The reply was not a usable acknowledgment of the message that was waiting. Causes, in the order they are checked:
+
+- the bytes were not valid UTF-8 or not parseable HL7v2;
+- MSA-2 names a different message — usually a late acknowledgment from an earlier timed-out send;
+- MSA-1 is empty or is not one of the six codes of Table 0008;
+- the reply passed `maxBufferedBytes` before it was complete;
+- the connection closed partway through the reply.
+
+The connection closes because the client can no longer tell which reply answers which message. The client closes with this error.
+
+### `AckException`
 
-Each call (whether `send` or `stream`) opens its own connection. There's no shared state between methods; pick the one that matches the consumption pattern you need at the call site.
+From `@glion/ack` · fields: `code`, `controlId`, `text`, `errorCode`, `severity`
 
-### Connection lifecycle
+Not an `MllpClientError`. The receiver read the message and refused it, which is an answer rather than a fault — **the connection stays open** and the next message can go out on it.
 
-`MllpClient` does not pool or reuse connections. Each `send()` opens a fresh TCP/TLS connection and closes it after the ACK frame is read. This trades TCP and TLS handshake overhead for a simpler API and isolates each request from the failure modes of the others. Receivers that require long-lived connections may need a different client.
+| Field       | Source | Description                                   |
+| ----------- | ------ | --------------------------------------------- |
+| `code`      | MSA-1  | `AE`, `AR`, `CE`, or `CR`.                    |
+| `controlId` | MSA-2  | The message being refused.                    |
+| `text`      | MSA-3  | The receiver's reason, when it gave one.      |
+| `errorCode` | ERR-3  | HL7v2 Table 0357 error condition, when given. |
+| `severity`  | ERR-4  | `E`, `W`, or `I`, when given.                 |
 
-### Concurrency
+The class is the MSA-1 code: `AckApplicationError` (`AE`), `AckApplicationReject` (`AR`), `AckCommitError` (`CE`), `AckCommitReject` (`CR`). An MLLP server built on Glion raises the same types, so both ends of an integration catch the same thing.
 
-Each `send()` is independent. Concurrent calls open independent connections; there is no shared state between in-flight requests.
+## FAQs
 
-## Limitations
+### Why does a failed send close the connection?
 
-Things `@glion/mllp-client` deliberately does **not** do — call them out explicitly so callers can decide whether the client fits their integration:
+MLLP has no correlation of its own. The only thing tying a reply to a message is the receiver echoing your MSH-10 back in MSA-2 — and the only reason that can be trusted is that one message is outstanding at a time.
 
-- **No connection pooling or reuse.** Every `send()` opens a fresh socket. High-volume integrations that need to amortise the TCP/TLS handshake should layer their own pool above `send()` (or wait for a future opt-in `Connection` handle).
-- **No retry or backoff.** A failed `send()` rejects once. Retry policy is the caller's responsibility — semantics vary too much across HL7v2 deployments to bake one in.
-- **No outbound queueing.** The client sends what it is given, immediately. Callers that need rate-limiting or queueing should compose those above `send()`.
-- **No streaming beyond the resolving frame.** Both `send()` and `stream()` read frames until the one selected by `mode` arrives (a `CA` frame followed by an application-level ACK is the most you will ever see); any further bytes from the receiver are discarded when the socket is closed. `stream()` surfaces every accept frame in real time, but the connection still closes after the resolving frame.
-- **No outbound message-size limit.** The encoder will frame whatever you pass in. Use `maxAckSize` to cap inbound frames; cap outbound size in your application code if that matters.
+Once a send times out, that no longer holds. A wrong guess here reports one message's outcome under another message's identity, which in a clinical feed is worse than an error.
 
-## Errors and PHI
+Clients that pipeline can survive a timeout, because they keep a table of outstanding control IDs and a background reader to match against it. A lockstep client has no table to fall back on.
 
-Thrown errors carry the full diagnostic context so callers can debug without reaching for additional state. **That context can include HL7v2 message content**:
+The client closes with the failure, and never sends the failed message again — only you know whether the receiver already has it. Construct a new client to go on, as you would open a new socket.
 
-- `AckException.raw` (from `@glion/ack`) holds the full wire-format ACK that triggered the exception. ACKs typically do not contain protected health information (PHI), but a NAK whose MSA-3 echoes input data can.
-- `error.message` on a NAK exception is MSA-3 verbatim, which a misbehaving receiver may populate with patient identifiers, dates of birth, or free-text notes.
-- `error.cause` on `MllpClientError(MALFORMED_ACK)` chains the underlying parser error, whose message may include a slice of the unparseable input.
+### Why a socket rather than a host and port?
 
-If you log thrown errors to a destination that is not approved for PHI (general-purpose log aggregators, third-party error trackers, terminals shared with non-clinical staff), redact `error.raw`, `error.message`, and `error.cause` first. The package never logs these fields itself — propagation is entirely the caller's choice.
+The client handles MLLP and deliberately handles no transport. Putting the whole runtime dependency behind two methods means the same client runs over TCP, TLS, a Unix socket, or a pair of in-memory streams — and the test suite covers every lifecycle path without opening a port.
 
 ## Part of Glion