@homaiohq/napi-quickfix 0.1.0 → 0.3.0

package/CMakeLists.txt

@@ -85,7 +85,11 @@ string(REPLACE "\n" "" NODE_ADDON_API_DIR ${NODE_ADDON_API_DIR})
 # ---------------------------------------------------------------------------
 # The native addon.
 # ---------------------------------------------------------------------------
-file(GLOB ADDON_SOURCES "${CMAKE_SOURCE_DIR}/cpp/*.cpp")
+# CONFIGURE_DEPENDS re-globs on every build, so adding or deleting a cpp/*.cpp
+# file is picked up by an already-configured tree. cmake-js only re-runs the
+# configure step when CMakeCache.txt is missing, so without it a deleted source
+# stays in the build graph until `yarn clean`.
+file(GLOB ADDON_SOURCES CONFIGURE_DEPENDS "${CMAKE_SOURCE_DIR}/cpp/*.cpp")
 
 add_library(napi_quickfix SHARED ${ADDON_SOURCES} ${CMAKE_JS_SRC})
 set_target_properties(napi_quickfix PROPERTIES PREFIX "" SUFFIX ".node")

package/README.md

@@ -23,11 +23,20 @@ included.
   points.
 - **TypeScript types included** — hand-written `.d.ts` for the full public API.
 - **Full FIX surface** — the session engine (`Initiator`/`Acceptor` +
-  synchronous application handlers) *and* the pure layer (`Message`,
-  `SessionSettings`, `DataDictionary`, `SessionID`).
+  synchronous application handlers), per-session control (`Session`: sequence
+  numbers, logon/logout, runtime options) *and* the pure layer (`Message` with
+  repeating `Group`s and dictionary-aware parsing, `SessionSettings`,
+  `DataDictionary`, `SessionID`).
 - **Ergonomic, safe API** — chainable message building with automatic
   header/trailer field routing, typed rejections, and C++ exceptions surfaced as
   JavaScript `Error`s.
+- **Every FIX constant, typed** — `FIELD` (tag numbers) and one value group per
+  field (`MsgType`, `Side`, `ExecType`, `OrdStatus`, ...) are
+  generated from the bundled QuickFIX headers with literal types, frozen, and
+  importable without loading the native addon.
+- **TLS for initiators** — `createTlsTunnel` is a built-in, stunnel-style TLS
+  tunnel (mTLS, SNI, certificate verification via Node's `tls`), so you don't need
+  a separate stunnel process.
 
 ## Install
 
@@ -206,20 +215,41 @@ come from `@homaiohq/napi-quickfix`.
 ### Message
 
 ```ts
-new Message(raw?: string, opts?: { validate?: boolean });
-Message.parse(raw: string, opts?: { validate?: boolean }): Message;
+new Message(raw?: string, opts?: MessageParseOptions);
+Message.parse(raw: string, opts?: MessageParseOptions): Message;
+// MessageParseOptions: { validate?: boolean; dictionary?: DataDictionary;
+//                        sessionDictionary?: DataDictionary; applicationDictionary?: DataDictionary }
 
 message.setField(tag: number, value: string | number): this; // chainable, auto-routes header/trailer fields
-message.getField(tag: number): string;
+message.getField(tag: number): string;           // throws QuickFixError (FieldNotFound) if absent
+// Standard header/trailer tags route to their section. Any other tag is a body field, unless the
+// header or trailer already holds it (a field a dictionary declares there): then it is read and
+// edited in place. A new dictionary-declared header field goes in with setHeaderField.
+message.getFieldIfSet(tag: number): string | undefined;
+message.isSetField(tag: number): boolean;
+message.removeField(tag: number): this;
 message.setHeaderField(tag, value): this;   message.getHeaderField(tag): string;
 message.setTrailerField(tag, value): this;  message.getTrailerField(tag): string;
+message.fields(): [tag: number, value: string][];   // body fields in wire order (also iterable)
+message.headerFields(); message.trailerFields();    // same shape
+message.isEmpty(): boolean;  message.totalFields(): number;  message.clear(): this;
+
+// Tags must be integers (positive for setters) and group indices integers: anything else throws a TypeError.
+// Repeating groups (indices are 1-based, as in QuickFIX)
+message.addGroup(group: Group): this;               // appends a copy, maintains the count field; TypeError if group.delim differs from the stored entries'
+message.getGroup(index: number, tag: number): Group; // snapshot copy; throws FieldNotFound if absent
+message.replaceGroup(index: number, group: Group): this; // throws FieldNotFound if absent, TypeError if group.delim differs
+message.removeGroup(tag: number): this;  message.removeGroup(index: number, tag: number): this; // (index, tag) throws FieldNotFound if absent
+message.hasGroup(tag: number): boolean;  message.hasGroup(index: number, tag: number): boolean;
+message.groupCount(tag: number): number;
+
 message.getMsgType(): string;
 message.toString(): string;   // raw SOH-delimited wire string
 message.toPretty(): string;   // human-readable
 message.toJSON(): { msgType?: string; raw: string };
 
 createMessage(fields?: Record<number, string | number>): Message;
-parseMessage(raw: string, opts?: { validate?: boolean }): Message;
+parseMessage(raw: string, opts?: MessageParseOptions): Message;
 ```
 
 Field values are accepted as `string | number` (numbers are stringified) and
@@ -228,6 +258,62 @@ always returned as `string`. Header/trailer fields such as `MsgType`,
 section by `setField`, so you rarely need `setHeaderField`/`setTrailerField`
 directly.
 
+**Parsing and repeating groups.** A parse without a dictionary is *flat*: the
+fields of a repeating group are kept as plain repeated body fields and
+`getGroup` throws. Pass a `dictionary` (or a `sessionDictionary` /
+`applicationDictionary` pair for FIXT/FIX 5) to parse groups structurally.
+With `UseDataDictionary=Y` (the default), messages delivered to engine handlers
+are already parsed with the session's dictionary, so `getGroup` works on them
+directly; with `UseDataDictionary=N` they arrive flat.
+
+```ts
+import { DataDictionary, Group, Message, FIELD, MsgType } from '@homaiohq/napi-quickfix';
+
+const dd = DataDictionary.fromFile('./spec/FIX44.xml');
+
+const order = new Message()
+  .setField(FIELD.MsgType, MsgType.NewOrderSingle)
+  .setField(FIELD.ClOrdID, 'order-1')
+  .addGroup(new Group(FIELD.NoPartyIDs, FIELD.PartyID).setField(FIELD.PartyID, 'TRADER-1').setField(FIELD.PartyRole, 11))
+  .addGroup(new Group(FIELD.NoPartyIDs, FIELD.PartyID).setField(FIELD.PartyID, 'FIRM-7').setField(FIELD.PartyRole, 1));
+// 453=2|448=TRADER-1|452=11|448=FIRM-7|452=1 on the wire
+
+const parsed = Message.parse(order.toString(), { dictionary: dd });
+parsed.groupCount(FIELD.NoPartyIDs);                           // 2
+parsed.getGroup(2, FIELD.NoPartyIDs).getField(FIELD.PartyID);  // 'FIRM-7'
+
+// getGroup returns a snapshot: write changes back with replaceGroup.
+const first = parsed.getGroup(1, FIELD.NoPartyIDs).setField(FIELD.PartyRole, 12);
+parsed.replaceGroup(1, first);
+```
+
+### Group
+
+One entry of a repeating group, identified by its **count tag** (`field`, e.g.
+`453 NoPartyIDs`) and its **delimiter** (`delim`, the first tag of every entry,
+e.g. `448 PartyID`). Groups nest through the same `addGroup`/`getGroup` API.
+
+```ts
+new Group(field: number, delim: number, order?: number[]); // order: full entry field order, delimiter first, no tag twice
+                                                          // delim and order tags are capped at 2^20 (RangeError beyond that)
+group.field;  group.delim;                                  // read-only
+
+group.setField(tag, value: string | number): this;  group.getField(tag): string;
+group.getFieldIfSet(tag): string | undefined;       group.isSetField(tag): boolean;
+group.removeField(tag): this;  group.isEmpty();  group.totalFields();  group.clear(): this;
+group.fields(): [tag, value][];                     // in wire order (also iterable)
+group.toString(): string;                           // the entry's fields, SOH-delimited, in wire order
+
+// Nested groups — same contract as on Message
+group.addGroup(g: Group): this;  group.getGroup(index, tag): Group;  group.replaceGroup(index, g): this;
+group.removeGroup(tag): this;    group.removeGroup(index, tag): this;
+group.hasGroup(tag): boolean;    group.hasGroup(index, tag): boolean;  group.groupCount(tag): number;
+```
+
+Without an explicit `order`, an entry's fields are emitted delimiter-first and
+then by ascending tag number, which matches the standard dictionaries for most
+groups; pass `order` (e.g. `[448, 447, 452]`) when a group's spec order differs.
+
 ### SessionID
 
 ```ts
@@ -250,9 +336,18 @@ settings.getSessions(): SessionID[];
 ```ts
 DataDictionary.fromString(xml: string): DataDictionary;
 DataDictionary.fromFile(xmlPath: string): DataDictionary;
-dictionary.validate(msg: Message): void; // throws QuickFixError if invalid
+dictionary.validate(msg: Message, bodyOnly?: boolean): void; // throws QuickFixError if invalid
+dictionary.getVersion(): string;                       // e.g. 'FIX.4.4'
+dictionary.getFieldName(tag: number): string | undefined;
+dictionary.getFieldTag(name: string): number | undefined;
+dictionary.isField(tag: number): boolean;
+dictionary.isMsgType(msgType: string): boolean;
 ```
 
+`validate(msg, true)` validates as the *application* dictionary only: the
+BeginString version check and header/trailer validation are skipped. A
+dictionary also drives structural parsing — see `Message.parse` above.
+
 ### Initiator / Acceptor (the session engine)
 
 Both extend Node's `EventEmitter` and share the same options and lifecycle:
@@ -261,13 +356,214 @@ Both extend Node's `EventEmitter` and share the same options and lifecycle:
 new Initiator({ settings, handlers?, store?: 'file' | 'memory', log?: 'screen' | 'file' | 'none' });
 new Acceptor({ settings, handlers?, store?, log? });
 
-engine.start(): void;
-engine.stop(force?: boolean): void;   // graceful drain by default; force to abort
-engine.isLoggedOn(): boolean;
+engine.start(): Promise<void>;
+engine.stop(force?: boolean): Promise<void>;   // graceful drain by default; force to abort
+engine.isLoggedOn(sessionID?: SessionID): boolean; // any session, or just that one
+engine.getSessions(): SessionID[];                 // the [SESSION]s it was configured with
+engine.getSession(sessionID: SessionID): Session | undefined;
 engine.ref(): void;    // keep the event loop alive while running (default)
 engine.unref(): void;  // let a short script / test exit
 ```
 
+`start`/`stop` resolve once the engine has finished starting up / shutting down;
+they run off the main thread so your handlers can fire meanwhile. Once `stop()`
+settles the engine's sessions are destroyed: `getSession` returns `undefined` and
+any `Session` handle you still hold throws `SessionNotFound`. Until then they are
+still live: a graceful `stop()` settles only after the `'logout'` events it
+triggered have been delivered, so a `'logout'` listener can still read the
+session, and a `sendToTarget()` that has already reached its session completes
+before the sessions go away. One that has not reached it by then is refused
+with `SessionNotFound` rather than run against the engine that is gone; a send
+is bound to the engine that owns the session when it is called, never to one
+created later with the same id.
+`stop(true)` discards the events still queued and destroys the sessions right
+away. A `stop()` called while another is still in flight (from that `'logout'`
+listener, say) returns the same Promise, so it too settles only once the
+sessions are gone; the first call's `force` applies to both.
+
+Two live engines cannot share a `SessionID`: constructing one whose session
+already exists in the process throws a `ConfigError` ("Duplicate Session") until
+the engine owning it has been stopped. A constructor that fails on a later
+`[SESSION]` (any `ConfigError`) cleans up the sessions it had already created
+(so the ids are not locked out by the failed attempt) and the engine-level log
+QuickFIX had already opened for it.
+
+### TLS (stunnel-style) for initiators
+
+QuickFIX's own `SSLSocketInitiator` needs OpenSSL compiled into the engine, and
+this package's prebuilds are built without it. Instead, `createTlsTunnel` does
+what a stunnel client does, inside your process. It listens on a loopback port,
+you point the initiator's `SocketConnectHost`/`SocketConnectPort` at it, and it
+carries each connection to the counterparty over Node's
+[`tls.connect`](https://nodejs.org/api/tls.html#tlsconnectoptions-callback):
+
+```text
+Initiator --plain TCP--> 127.0.0.1:<tunnel.port> --TLS--> fix.broker.com:9443
+```
+
+```ts
+import { readFileSync } from 'node:fs';
+import { createTlsTunnel, Initiator, SessionSettings } from '@homaiohq/napi-quickfix';
+
+const tunnel = await createTlsTunnel({
+  host: 'fix.broker.com',
+  port: 9443,
+  tls: {
+    ca: readFileSync('broker-ca.pem'),   // omit to trust Node's default CAs
+    cert: readFileSync('client.pem'),    // mTLS, if the venue requires it
+    key: readFileSync('client.key'),
+    minVersion: 'TLSv1.2',
+  },
+});
+tunnel.on('secureConnect', (info) => console.log('TLS up', info.protocol, info.peerCertificate.subject));
+tunnel.on('tlsError', (err) => console.error('TLS failed:', err.message));
+
+const settings = SessionSettings.fromString(`
+[DEFAULT]
+ConnectionType=initiator
+SocketConnectHost=${tunnel.host}
+SocketConnectPort=${tunnel.port}
+...
+`);
+const initiator = new Initiator({ settings, handlers });
+await initiator.start();
+
+// Shutdown: the engine first, so its Logout still crosses the tunnel.
+await initiator.stop();
+await tunnel.close();
+```
+
+- **Options.** `tls` accepts any `tls.ConnectionOptions` except
+  `host`/`port`/`socket`/`path`. `servername` (SNI, and the name the server
+  certificate is checked against) defaults to `host`, unless `host` is an IP
+  address.
+- **Fixed port.** Pass `localPort` to listen on a fixed port, for example to
+  keep `SocketConnectPort=9001` in a static `.cfg` file. A port that is already
+  in use makes `createTlsTunnel` reject with `EADDRINUSE`.
+- **Failover.** Open one tunnel per `SocketConnectHost<n>`, and set
+  `SocketConnectHost<n>=127.0.0.1` with `SocketConnectPort<n>=${tunnelN.port}`.
+- **Failures.** If the TLS connection fails or breaks (DNS, TCP, handshake,
+  certificate, or `tls` options that `tls.connect` rejects such as an
+  unreadable key), the tunnel emits `'tlsError'` and drops the initiator's
+  loopback connection. QuickFIX then reconnects after its `ReconnectInterval`.
+  The tunnel never emits `'error'`, so a tunnel with no listeners cannot crash
+  the process.
+- **Shutdown of a connection.** When either side closes, the other is ended
+  rather than reset, so data still in the tunnel (a Logout, TLS's
+  `close_notify`) is delivered. A connection that has not fully closed 5 seconds
+  after the first side closed is destroyed.
+- **Lifecycle.** The tunnel's handles are unref'd, so the tunnel alone never
+  keeps the process alive (a started engine does). `close()` destroys live
+  connections at once. It is idempotent, and
+  `await using tunnel = await createTlsTunnel(...)` closes the tunnel at the end
+  of the block.
+
+**Security notes**
+
+- The plain-text hop listens on `127.0.0.1` only. As with stunnel, other
+  processes on the same host can still connect to that port, so treat the host
+  as trusted.
+- QuickFIX's own logs show the loopback address (`Connecting to 127.0.0.1 on
+  port ...`). Use the `'secureConnect'` event to see the real peer and its
+  certificate.
+- Tunnel traffic runs on the JS event loop, which the application handlers
+  already depend on. A blocked loop stalls both in the same way.
+
+**Acceptor side.** There is no in-process equivalent for acceptors. QuickFIX
+1.16's acceptor always listens on every interface, and it checks
+`AllowedRemoteAddresses` only after processing the Logon. A tunnel in front of
+it could therefore be bypassed by connecting to the plain port directly. To
+accept TLS, terminate it outside the process (stunnel in server mode, a load
+balancer, a service mesh) and firewall the acceptor's port.
+
+If you'd rather run stunnel as a sidecar on the initiator side, this config is
+equivalent to the example above:
+
+```ini
+[fix-broker]
+client = yes
+accept = 127.0.0.1:9001
+connect = fix.broker.com:9443
+CAfile = broker-ca.pem
+cert = client.pem
+key = client.key
+verifyChain = yes
+checkHost = fix.broker.com
+sslVersionMin = TLSv1.2
+```
+
+### Session
+
+A handle on one **live** session, obtained from `engine.getSession(id)` or the
+module-level `lookupSession(id)`. It stores only the `SessionID` and the identity
+of the engine it came from, and re-resolves the engine-owned `FIX::Session` on
+every call, so it never dangles — once the session is gone (its engine was
+stopped) every method throws a `QuickFixError` whose `fixErrorName` is
+`'SessionNotFound'`, even after a new engine has been created with the same id.
+A handle never crosses over to another engine's session; get a new one from the
+new engine.
+
+```ts
+session.sessionID: SessionID;
+
+// State (sync)
+session.isLoggedOn(): boolean;   session.isEnabled(): boolean;
+session.sentLogon(): boolean;    session.sentLogout(): boolean;   session.receivedLogon(): boolean;
+session.isInitiator(): boolean;  session.isAcceptor(): boolean;
+session.isSessionTime(now?: Date): boolean;   session.isLogonTime(now?: Date): boolean;
+
+// Sequence numbers (sync; setters write to the message store -- on a quiet session, see below)
+session.getExpectedSenderNum(): number;         session.getExpectedTargetNum(): number;
+session.setNextSenderMsgSeqNum(n: number): void; session.setNextTargetMsgSeqNum(n: number): void;
+
+// Runtime options (sync; change the live session, not its SessionSettings)
+session.getResetOnLogon() / setResetOnLogon(v: boolean)        // likewise: ResetOnLogout,
+session.getLogonTimeout() / setLogonTimeout(seconds: number)   //   ResetOnDisconnect, RefreshOnLogon,
+session.getTimestampPrecision() / setTimestampPrecision(0..9)  //   CheckCompId, CheckLatency, MaxLatency,
+                                                               //   LogoutTimeout, PersistMessages,
+                                                               //   SendRedundantResendRequests,
+                                                               //   ValidateLengthAndChecksum,
+                                                               //   SendNextExpectedMsgSeqNum, IsNonStopSession
+
+// Control
+session.logon(): void;                   // enable; an initiator reconnects + logs on
+session.logout(reason?: string): void;   // disable + graceful Logout; stays down until logon()
+session.refresh(): void;                 // re-read state from the message store
+```
+
+Everything is synchronous: none of these members takes the mutex QuickFIX holds
+while it runs your handlers, so they cannot deadlock the main thread — and
+because they run inline, `session.logout('x'); session.logon();` takes effect in
+that order. (`logon()`/`logout()` flip a plain flag the engine's network thread
+reads without a lock, exactly as QuickFIX's own `Initiator::stop()` does from
+the stopping thread; the engine picks the change up on its next pass.) The
+sequence-number setters are likewise not serialised against a message the
+engine is sending or receiving on that session at the same moment: QuickFIX
+reads the number, runs your handler, then increments from the store under a
+lock the setters do not take, so a value set in that window — from a handler,
+or while a `sendToTarget()` or a heartbeat is in flight — is overwritten and the
+session ends up one off from its counterparty. Renumber a **quiet** session:
+before `start()`, from a `'logout'` event, or when you know nothing is in
+flight. QuickFIX's `Session::disconnect()` and `reset()` are deliberately **not**
+exposed: they drop the transport through the engine's socket monitor, which is
+only safe from the engine's own network thread (QuickFIX itself never calls them
+from anywhere else). Bring a session down with `logout()` and renumber it with
+the sequence-number setters. Observe the outcome through the engine's
+`'logon'` / `'logout'` events:
+
+```ts
+initiator.on('logon', (id) => {
+  console.log('next outbound seq', initiator.getSession(id)!.getExpectedSenderNum());
+});
+initiator.on('logout', (id) => {
+  // The session is quiet now: renumber it, e.g. after the counterparty reset.
+  initiator.getSession(id)?.setNextTargetMsgSeqNum(1);
+});
+
+lookupSession(id)?.logout('maintenance');   // -> 'logout' event, isLoggedOn() === false
+lookupSession(id)?.logon();                 // -> reconnects, 'logon' event
+```
+
 ### Handlers vs. events
 
 This is the key distinction to understand:
@@ -304,13 +600,25 @@ Recognized kinds: `'DoNotSend'`, `'RejectLogon'`, `'UnsupportedMessageType'`,
 ### Module functions and constants
 
 ```ts
-sendToTarget(message: Message, sessionID: SessionID): boolean;
+sendToTarget(message: Message, sessionID: SessionID): Promise<boolean>;
+sendToTarget(message: Message, qualifier?: string): Promise<boolean>; // session from the message header (8/49/56)
+
+lookupSession(sessionID: SessionID): Session | undefined; // any engine in this process
+doesSessionExist(sessionID: SessionID): boolean;
+getSessions(): SessionID[];      // every session in this process, across all engines
+numSessions(): number;
+
 version(): string;               // engine / addon version string
 
-FIELD    // field-name -> tag number, e.g. FIELD.MsgType === 35, FIELD.Password === 554
-MsgType  // MsgType values, e.g. MsgType.Logon === 'A'
-Side     // Side values, e.g. Side.Buy === '1'
-enums    // the full frozen tree of FIX constants
+createTlsTunnel(options: TlsTunnelOptions): Promise<TlsTunnel>; // see "TLS (stunnel-style) for initiators"
+
+FIELD        // field-name -> tag number, e.g. FIELD.MsgType === 35, FIELD.Password === 554
+MsgType      // MsgType values, e.g. MsgType.Logon === 'A'
+Side         // Side values, e.g. Side.Buy === '1'
+OrdType      // e.g. OrdType.Limit === '2'
+TimeInForce  // e.g. TimeInForce.Day === '0'
+VALUES       // every value group keyed by field name, e.g. VALUES.ExecType.Fill === '2'
+enums        // the full frozen tree: every value group plus FIELD
 ```
 
 `FIELD` is generated from the bundled QuickFIX's `FixFieldNumbers.h`, so it has every
@@ -318,12 +626,30 @@ enums    // the full frozen tree of FIX constants
 is typed `554`, and a misspelt field name is a compile error. `FieldName` is the union of
 all field names.
 
-The table is also exposed as a subpath export that does **not** load the native addon,
-for tooling that only needs tag numbers (log parsers, test helpers, bundles for platforms
-without a prebuild):
+The value groups are generated the same way from `FixValues.h`: one frozen object per
+field (690 groups, 5700+ values), each value a string because FIX is string-on-the-wire
+(`EncryptMethod.None === '0'`, not `0`). Names derive from QuickFIX's
+`FIX::<Field>_<VALUE>` constants with the SCREAMING_SNAKE suffix turned into PascalCase —
+`Side_SELL_SHORT` → `Side.SellShort`, `ExecType_DONE_FOR_DAY` → `ExecType.DoneForDay` —
+while `MsgType`, whose upstream names already mirror message names, is kept verbatim
+(`MsgType.NewOrderSingle`, `MsgType.IOI`). Every word is lower-cased, acronyms included
+(`SecurityIDSource_ISIN_NUMBER` → `SecurityIDSource.IsinNumber`, `MDEntryType_VWAP` →
+`MDEntryType.Vwap`): the upstream names carry no acronym information, so there is no
+allowlist to maintain and the keys are stable. The exact rule is documented in
+`scripts/gen-values.mjs`. Values are literal types too (`Side.Buy` is typed `'1'`), and
+`ValueGroupName` is the union of all group names.
+
+The root entry exports `MsgType`, `Side`, `OrdType` and `TimeInForce` by name and every
+group through `VALUES` / `enums`. Both tables are also exposed as subpath exports that
+do **not** load the native addon, for tooling that only needs the constants (log
+parsers, test helpers, bundles for platforms without a prebuild); each group is a named
+export there, so bundlers resolving the ESM build keep only the groups you import (the
+CJS build is not tree-shakeable: tsc drops the `@__PURE__` annotations when it emits
+CommonJS):
 
 ```ts
 import { FIELD } from '@homaiohq/napi-quickfix/fields';
+import { ExecType, OrdStatus, SecurityType } from '@homaiohq/napi-quickfix/values';
 ```
 
 ### Errors