jspurefix 5.8.5 → 5.9.2

package/dist/transport/tcp/tls-diagnostics.d.ts

@@ -0,0 +1,5 @@
+import { ConnectionOptions, TLSSocket, TlsOptions } from 'tls';
+export declare function describeConnectionOptions(options: ConnectionOptions): string;
+export declare function describeServerOptions(options: TlsOptions): string;
+export declare function describeNegotiated(socket: TLSSocket): string;
+export declare function describePeerCertificate(socket: TLSSocket): string;

package/dist/transport/tcp/tls-diagnostics.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeConnectionOptions = describeConnectionOptions;
+exports.describeServerOptions = describeServerOptions;
+exports.describeNegotiated = describeNegotiated;
+exports.describePeerCertificate = describePeerCertificate;
+function describeCommonOptions(options) {
+    var _a, _b;
+    const parts = [];
+    parts.push(`key ${options.key ? 'supplied' : 'none'}`);
+    parts.push(`cert ${options.cert ? 'supplied' : 'none'}`);
+    const ca = options.ca;
+    const caCount = Array.isArray(ca) ? ca.length : (ca ? 1 : 0);
+    parts.push(`ca ${caCount}`);
+    parts.push(`rejectUnauthorized ${String((_a = options.rejectUnauthorized) !== null && _a !== void 0 ? _a : '(default true)')}`);
+    parts.push(`requestCert ${String((_b = options.requestCert) !== null && _b !== void 0 ? _b : '(default false)')}`);
+    if (options.minVersion)
+        parts.push(`minVersion ${options.minVersion}`);
+    if (options.maxVersion)
+        parts.push(`maxVersion ${options.maxVersion}`);
+    return parts;
+}
+function describeConnectionOptions(options) {
+    var _a, _b;
+    const parts = [`host ${(_a = options.host) !== null && _a !== void 0 ? _a : '?'}`, `port ${(_b = options.port) !== null && _b !== void 0 ? _b : '?'}`];
+    if (options.servername)
+        parts.push(`servername ${options.servername}`);
+    return parts.concat(describeCommonOptions(options)).join(', ');
+}
+function describeServerOptions(options) {
+    return describeCommonOptions(options).join(', ');
+}
+function describeNegotiated(socket) {
+    var _a;
+    const parts = [];
+    parts.push(`protocol ${(_a = socket.getProtocol()) !== null && _a !== void 0 ? _a : 'none'}`);
+    const cipher = socket.getCipher();
+    parts.push(`cipher ${cipher ? `${cipher.name} (${cipher.version})` : 'none'}`);
+    parts.push(`authorized ${socket.authorized}`);
+    if (!socket.authorized && socket.authorizationError) {
+        parts.push(`authorizationError ${String(socket.authorizationError)}`);
+    }
+    return parts.join(', ');
+}
+function describePeerCertificate(socket) {
+    var _a, _b, _c, _d;
+    const cert = socket.getPeerCertificate(false);
+    if (!cert || Object.keys(cert).length === 0) {
+        return 'peer presented no certificate';
+    }
+    const subject = cert.subject ? ((_a = cert.subject.CN) !== null && _a !== void 0 ? _a : JSON.stringify(cert.subject)) : '?';
+    const issuer = cert.issuer ? ((_b = cert.issuer.CN) !== null && _b !== void 0 ? _b : JSON.stringify(cert.issuer)) : '?';
+    const parts = [
+        `subject ${subject}`,
+        `issuer ${issuer}`,
+        `valid ${(_c = cert.valid_from) !== null && _c !== void 0 ? _c : '?'} to ${(_d = cert.valid_to) !== null && _d !== void 0 ? _d : '?'}`
+    ];
+    if (cert.subjectaltname)
+        parts.push(`san ${cert.subjectaltname}`);
+    if (cert.fingerprint256)
+        parts.push(`sha256 ${cert.fingerprint256}`);
+    return parts.join(', ');
+}
+//# sourceMappingURL=tls-diagnostics.js.map

package/dist/transport/tcp/tls-diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tls-diagnostics.js","sourceRoot":"","sources":["../../../src/transport/tcp/tls-diagnostics.ts"],"names":[],"mappings":"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","sourcesContent":["import { ConnectionOptions, TLSSocket, TlsOptions } from 'tls'\n\n/*\n   tls failures are routinely reported as \"it just times out\" - see issues #94 and #151.  the\n   session either connects or it does not, and nothing in the log says which options were\n   actually applied or what the peer presented.  enableTrace exists but is node's raw handshake\n   trace: all or nothing, written to stderr rather than through IJsFixLogger.\n\n   these helpers render the small number of facts needed to diagnose a handshake, and are\n   deliberately conservative about what they include - never key material, never a full\n   certificate, only the identifying fields of one.\n */\n\nfunction describeCommonOptions (options: ConnectionOptions | TlsOptions): string[] {\n  const parts: string[] = []\n  // presence only - the values are private keys and certificate bodies.\n  parts.push(`key ${options.key ? 'supplied' : 'none'}`)\n  parts.push(`cert ${options.cert ? 'supplied' : 'none'}`)\n  const ca = options.ca\n  const caCount = Array.isArray(ca) ? ca.length : (ca ? 1 : 0)\n  parts.push(`ca ${caCount}`)\n  // the whole point of #94/#151 - make it unambiguous which value won.\n  parts.push(`rejectUnauthorized ${String(options.rejectUnauthorized ?? '(default true)')}`)\n  parts.push(`requestCert ${String(options.requestCert ?? '(default false)')}`)\n  if (options.minVersion) parts.push(`minVersion ${options.minVersion}`)\n  if (options.maxVersion) parts.push(`maxVersion ${options.maxVersion}`)\n  return parts\n}\n\nexport function describeConnectionOptions (options: ConnectionOptions): string {\n  const parts: string[] = [`host ${options.host ?? '?'}`, `port ${options.port ?? '?'}`]\n  if (options.servername) parts.push(`servername ${options.servername}`)\n  return parts.concat(describeCommonOptions(options)).join(', ')\n}\n\nexport function describeServerOptions (options: TlsOptions): string {\n  return describeCommonOptions(options).join(', ')\n}\n\n/*\n   what the handshake actually negotiated.  the maintainer's suggestion in #94 was to reproduce\n   the connection in powershell to see the negotiated suite - this puts the same facts in our\n   own log instead.\n */\nexport function describeNegotiated (socket: TLSSocket): string {\n  const parts: string[] = []\n  parts.push(`protocol ${socket.getProtocol() ?? 'none'}`)\n  const cipher = socket.getCipher()\n  parts.push(`cipher ${cipher ? `${cipher.name} (${cipher.version})` : 'none'}`)\n  parts.push(`authorized ${socket.authorized}`)\n  if (!socket.authorized && socket.authorizationError) {\n    parts.push(`authorizationError ${String(socket.authorizationError)}`)\n  }\n  return parts.join(', ')\n}\n\n/*\n   identifying fields of the peer certificate only.  getPeerCertificate() returns the full DER\n   in .raw plus the public key - none of that belongs in a log, so pick fields explicitly.\n */\nexport function describePeerCertificate (socket: TLSSocket): string {\n  const cert = socket.getPeerCertificate(false)\n  if (!cert || Object.keys(cert).length === 0) {\n    return 'peer presented no certificate'\n  }\n  const subject = cert.subject ? (cert.subject.CN ?? JSON.stringify(cert.subject)) : '?'\n  const issuer = cert.issuer ? (cert.issuer.CN ?? JSON.stringify(cert.issuer)) : '?'\n  const parts: string[] = [\n    `subject ${subject}`,\n    `issuer ${issuer}`,\n    `valid ${cert.valid_from ?? '?'} to ${cert.valid_to ?? '?'}`\n  ]\n  if (cert.subjectaltname) parts.push(`san ${cert.subjectaltname}`)\n  if (cert.fingerprint256) parts.push(`sha256 ${cert.fingerprint256}`)\n  return parts.join(', ')\n}\n"]}

package/dist/transport/tcp/tls-options-factory.d.ts

@@ -2,6 +2,7 @@ import { ConnectionOptions, TlsOptions } from 'tls';
 import { ITlsOptions } from './tls-options';
 import { ITcpTransportDescription } from './tcp-transport-description';
 export declare class TlsOptionsFactory {
+    static asBoolean(value: any): any;
     static read(filePath: string): string;
     static getTlsOptions(tls: ITlsOptions): TlsOptions | null;
     static getTlsConnectionOptions(tcp: ITcpTransportDescription): ConnectionOptions | null;

package/dist/transport/tcp/tls-options-factory.js

@@ -4,6 +4,16 @@ exports.TlsOptionsFactory = void 0;
 const path = require('path');
 const fs = require('fs');
 class TlsOptionsFactory {
+    static asBoolean(value) {
+        if (typeof value === 'string') {
+            const lowered = value.toLowerCase();
+            if (lowered === 'true')
+                return true;
+            if (lowered === 'false')
+                return false;
+        }
+        return value;
+    }
     static read(filePath) {
         const root = path.join(__dirname, '../../../');
         const fullPath = path.join(root, filePath);
@@ -15,8 +25,8 @@ class TlsOptionsFactory {
         let tlsOptions = null;
         if (tls) {
             tlsOptions = {
-                requestCert: tls.requestCert,
-                rejectUnauthorized: tls.rejectUnauthorized
+                requestCert: TlsOptionsFactory.asBoolean(tls.requestCert),
+                rejectUnauthorized: TlsOptionsFactory.asBoolean(tls.rejectUnauthorized)
             };
             if (tls.key) {
                 tlsOptions.key = TlsOptionsFactory.read(tls.key);
@@ -53,8 +63,20 @@ class TlsOptionsFactory {
             if (tcp.tls.sessionTimeout) {
                 connectionOptions.sessionTimeout = tcp.tls.sessionTimeout;
             }
+            if (tls.requestCert !== undefined) {
+                connectionOptions.requestCert = TlsOptionsFactory.asBoolean(tls.requestCert);
+            }
+            if (tls.rejectUnauthorized !== undefined) {
+                connectionOptions.rejectUnauthorized = TlsOptionsFactory.asBoolean(tls.rejectUnauthorized);
+            }
             if (tls.nodeTlsConnectionOptions) {
                 connectionOptions = Object.assign(Object.assign({}, connectionOptions), tls.nodeTlsConnectionOptions);
+                if (connectionOptions.rejectUnauthorized !== undefined) {
+                    connectionOptions.rejectUnauthorized = TlsOptionsFactory.asBoolean(connectionOptions.rejectUnauthorized);
+                }
+                if (connectionOptions.requestCert !== undefined) {
+                    connectionOptions.requestCert = TlsOptionsFactory.asBoolean(connectionOptions.requestCert);
+                }
             }
         }
         return connectionOptions;

package/dist/transport/tcp/tls-options-factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"tls-options-factory.js","sourceRoot":"","sources":["../../../src/transport/tcp/tls-options-factory.ts"],"names":[],"mappings":"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","sourcesContent":["import { ConnectionOptions, TlsOptions } from 'tls'\nimport { ITlsOptions } from './tls-options'\nimport { ITcpTransportDescription } from './tcp-transport-description'\nconst path = require('path')\nconst fs = require('fs')\n\nexport class TlsOptionsFactory {\n  static read (filePath: string): string {\n    const root: string = path.join(__dirname, '../../../')\n    const fullPath = path.join(root, filePath)\n    return fs.readFileSync(fullPath,\n      {\n        encoding: 'utf8', flag: 'r'\n      })\n  }\n\n  static getTlsOptions (tls: ITlsOptions): TlsOptions | null {\n    let tlsOptions: TlsOptions | null = null\n    if (tls) {\n      tlsOptions = {\n        requestCert: tls.requestCert,\n        rejectUnauthorized: tls.rejectUnauthorized\n      } as TlsOptions\n\n      if (tls.key) {\n        tlsOptions.key = TlsOptionsFactory.read(tls.key)\n        tlsOptions.cert = tls?.cert ? TlsOptionsFactory.read(tls?.cert) : undefined\n      }\n\n      if (tls.ca && tls.ca.length > 0) {\n        tlsOptions.ca = tls.ca.map(i => TlsOptionsFactory.read(i))\n      }\n\n      if (tls.nodeTlsServerOptions) {\n        tlsOptions = {\n          ...tlsOptions,\n          ...tls.nodeTlsServerOptions\n        }\n      }\n    }\n    return tlsOptions\n  }\n\n  static getTlsConnectionOptions (tcp: ITcpTransportDescription): ConnectionOptions | null {\n    let connectionOptions: ConnectionOptions | null = null\n    const tls = tcp.tls\n    if (tls) {\n      connectionOptions = {\n        port: tcp.port,\n        host: tcp.host\n      } as ConnectionOptions\n      if (tls.key) {\n        connectionOptions.key = TlsOptionsFactory.read(tcp.tls?.key ?? '')\n        connectionOptions.cert = tcp.tls?.cert ? TlsOptionsFactory.read(tcp?.tls?.cert) : undefined\n      }\n      if (tcp.tls.ca && tcp.tls.ca.length > 0) {\n        connectionOptions.ca = tcp.tls.ca.map(i => TlsOptionsFactory.read(i))\n      }\n      if (tcp.tls.timeout) {\n        connectionOptions.timeout = tcp.tls.timeout\n      }\n      if (tcp.tls.sessionTimeout) {\n        connectionOptions.sessionTimeout = tcp.tls.sessionTimeout\n      }\n      if (tls.nodeTlsConnectionOptions) {\n        connectionOptions = {\n          ...connectionOptions,\n          ...tls.nodeTlsConnectionOptions\n        }\n      }\n    }\n    return connectionOptions\n  }\n}\n"]}
+{"version":3,"file":"tls-options-factory.js","sourceRoot":"","sources":["../../../src/transport/tcp/tls-options-factory.ts"],"names":[],"mappings":"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","sourcesContent":["import { ConnectionOptions, TlsOptions } from 'tls'\nimport { ITlsOptions } from './tls-options'\nimport { ITcpTransportDescription } from './tcp-transport-description'\nconst path = require('path')\nconst fs = require('fs')\n\nexport class TlsOptionsFactory {\n  /*\n     session descriptions are routinely hand written json, where a boolean flag is easily\n     quoted by mistake i.e. \"rejectUnauthorized\": \"false\".  node treats that string as truthy\n     and so does exactly the opposite of what was intended, silently.  accept the two string\n     spellings rather than inverting the caller's meaning - anything else is left alone so it\n     shows up as an obviously wrong value rather than being guessed at.\n   */\n  static asBoolean (value: any): any {\n    if (typeof value === 'string') {\n      const lowered = value.toLowerCase()\n      if (lowered === 'true') return true\n      if (lowered === 'false') return false\n    }\n    return value\n  }\n\n  static read (filePath: string): string {\n    const root: string = path.join(__dirname, '../../../')\n    const fullPath = path.join(root, filePath)\n    return fs.readFileSync(fullPath,\n      {\n        encoding: 'utf8', flag: 'r'\n      })\n  }\n\n  static getTlsOptions (tls: ITlsOptions): TlsOptions | null {\n    let tlsOptions: TlsOptions | null = null\n    if (tls) {\n      tlsOptions = {\n        requestCert: TlsOptionsFactory.asBoolean(tls.requestCert),\n        rejectUnauthorized: TlsOptionsFactory.asBoolean(tls.rejectUnauthorized)\n      } as TlsOptions\n\n      if (tls.key) {\n        tlsOptions.key = TlsOptionsFactory.read(tls.key)\n        tlsOptions.cert = tls?.cert ? TlsOptionsFactory.read(tls?.cert) : undefined\n      }\n\n      if (tls.ca && tls.ca.length > 0) {\n        tlsOptions.ca = tls.ca.map(i => TlsOptionsFactory.read(i))\n      }\n\n      if (tls.nodeTlsServerOptions) {\n        tlsOptions = {\n          ...tlsOptions,\n          ...tls.nodeTlsServerOptions\n        }\n      }\n    }\n    return tlsOptions\n  }\n\n  static getTlsConnectionOptions (tcp: ITcpTransportDescription): ConnectionOptions | null {\n    let connectionOptions: ConnectionOptions | null = null\n    const tls = tcp.tls\n    if (tls) {\n      connectionOptions = {\n        port: tcp.port,\n        host: tcp.host\n      } as ConnectionOptions\n      if (tls.key) {\n        connectionOptions.key = TlsOptionsFactory.read(tcp.tls?.key ?? '')\n        connectionOptions.cert = tcp.tls?.cert ? TlsOptionsFactory.read(tcp?.tls?.cert) : undefined\n      }\n      if (tcp.tls.ca && tcp.tls.ca.length > 0) {\n        connectionOptions.ca = tcp.tls.ca.map(i => TlsOptionsFactory.read(i))\n      }\n      if (tcp.tls.timeout) {\n        connectionOptions.timeout = tcp.tls.timeout\n      }\n      if (tcp.tls.sessionTimeout) {\n        connectionOptions.sessionTimeout = tcp.tls.sessionTimeout\n      }\n      // https://github.com/TimelordUK/jspurefix/issues/151 - ITlsOptions declares these and\n      // getTlsOptions honours them on the server path, so map them here too rather than making\n      // nodeTlsConnectionOptions the only spelling that works for an initiator.  Applied before\n      // the spread below so an explicit nodeTlsConnectionOptions value still wins.\n      if (tls.requestCert !== undefined) {\n        connectionOptions.requestCert = TlsOptionsFactory.asBoolean(tls.requestCert)\n      }\n      if (tls.rejectUnauthorized !== undefined) {\n        connectionOptions.rejectUnauthorized = TlsOptionsFactory.asBoolean(tls.rejectUnauthorized)\n      }\n      if (tls.nodeTlsConnectionOptions) {\n        connectionOptions = {\n          ...connectionOptions,\n          ...tls.nodeTlsConnectionOptions\n        }\n        if (connectionOptions.rejectUnauthorized !== undefined) {\n          connectionOptions.rejectUnauthorized = TlsOptionsFactory.asBoolean(connectionOptions.rejectUnauthorized)\n        }\n        if (connectionOptions.requestCert !== undefined) {\n          connectionOptions.requestCert = TlsOptionsFactory.asBoolean(connectionOptions.requestCert)\n        }\n      }\n    }\n    return connectionOptions\n  }\n}\n"]}

package/docs/acceptor.md

@@ -0,0 +1,207 @@
+# Running a FIX acceptor
+
+The acceptor in jspurefix began as a smoke-test harness for the initiator — enough
+to answer a Logon so the client side could be exercised. It is now used to host real
+counterparties, and this document describes the model it follows, what it guarantees,
+and what the log tells you.
+
+Much of this is a back-port of
+[cspurefix](https://github.com/TimelordUK/cspurefix), where the acceptor was hardened
+against real brokers.
+
+## Transports and sessions are not the same thing
+
+A **transport** is one TCP connection. A **session** is one FIX conversation,
+identified by `SessionId` = `BeginString`-`SenderCompID`-`TargetCompID`, and owning
+the sequence numbers and the message store behind that conversation.
+
+The relationship is one session per transport, but a session **outlives** the
+connection it started on: a counterparty that drops and reconnects is resuming the
+same FIX session, from the same persisted sequence state, on a new transport.
+
+```
+listener (TcpAcceptorListener)
+ └── acceptor (TcpAcceptor)          one net/tls Server, one SessionRegistry
+      ├── transport 1 ──► session scope ──► FixSession ──► SessionId A ──► store A
+      ├── transport 2 ──► session scope ──► FixSession ──► SessionId B ──► store B
+      └── transport 3 ──► session scope ──► FixSession ──► SessionId A ──► store A
+                                                              (replaces the first)
+```
+
+## Session scopes
+
+Every accepted connection gets its own DI child container — a *session scope* —
+carrying its own:
+
+- parse buffer and transmit buffer (`ElasticBuffer`)
+- `ISessionDescription`, and therefore its own `SessionId` and message store
+- session message factory, so outbound headers carry that session's comp ids
+- `IJsFixConfig`, which is what the application's session receives
+
+This matters because those are otherwise process-wide singletons on the session
+container. Two clients on one listener would parse into the same buffer and compute
+the same `SessionId`.
+
+Applications opt in by using the config they are **handed**, not the one they
+captured:
+
+```ts
+protected override makeFactory (config: IJsFixConfig): EngineFactory {
+  const isInitiator = this.isInitiator(config.description)
+  return {
+    // sessionConfig is this connection's own scope
+    makeSession: (sessionConfig: IJsFixConfig) => isInitiator
+      ? new MyClient(sessionConfig)
+      : new MyServer(sessionConfig)
+  } as EngineFactory
+}
+```
+
+Writing `makeSession: () => new MyServer(config)` closes over the launcher's config
+and opts the application out of per-session isolation. It still works for a single
+counterparty; it does not work for several.
+
+### Custom session message factories
+
+If you supply your own `ISessionMsgFactory` — usually by overriding
+`SessionContainer.makeSessionFactory` to stamp extra header fields — the scope needs
+a copy of *your* factory bound to that session's description, not a stock one.
+
+Extending `ASessionMsgFactory` (or `AsciiSessionMsgFactory` / `FixmlSessionMsgFactory`)
+gets this for free: the default `cloneFor` reconstructs through the concrete
+constructor, so a subclass taking `(description, mutator)` needs no extra work.
+Override `cloneFor` if your constructor takes anything else:
+
+```ts
+class BrokerMsgFactory extends AsciiSessionMsgFactory {
+  constructor (description: ISessionDescription, private readonly desk: string) {
+    super(description)
+  }
+
+  // the default clone would not know about `desk`
+  public override cloneFor (description: ISessionDescription): ISessionMsgFactory {
+    return new BrokerMsgFactory(description, this.desk)
+  }
+}
+```
+
+## The session registry
+
+FIX permits exactly one active session per `SessionId`. `SessionRegistry` enforces
+that: a session claims its `SessionId` once its store is initialised, and any
+*different* session already holding it is stopped first.
+
+This is what answers the half-open socket problem. A counterparty whose network path
+disappears without FIN or RST leaves the acceptor holding a socket it believes is
+alive. When that counterparty reconnects and logs on, the registry stops the stale
+session before the new one proceeds — otherwise two sessions write to one store and
+the sequence numbers diverge beyond recovery.
+
+```
+[SessionRegistry] FOUND EXISTING SESSION for FIX4.4-accept-comp-init-comp - this is a reconnection scenario
+[SessionRegistry] stopping old session to prevent stale transport writes
+[...FixSession]   requestStop: replaced by new connection - stopping old session with stale transport
+[SessionRegistry] session NOT unregistered (already replaced by new connection or not found): ...
+```
+
+That last line is expected, not an error: the displaced session unregisters on its
+way out, and the identity check stops it evicting its successor.
+
+The listener creates a registry per listener. Supply your own via
+`config.sessionRegistry` if you want to inspect it — `count`, `keys()` and `get()`
+are read-only views over the live population.
+
+An application can stop a session itself with `session.requestStop(reason)`.
+
+## Wildcard TargetCompID
+
+An acceptor that sets `"TargetCompID": "*"` does not need to know its counterparties
+in advance. On the first Logon the session adopts the peer's `SenderCompID` as its
+target and only then builds the identity-derived state: `SessionId`, message store,
+sequence coordinator, registry claim, and its logger name.
+
+```json
+{
+  "SenderCompId": "accept-comp",
+  "TargetCompID": "*",
+  "store": { "type": "file", "directory": "store/acceptor" }
+}
+```
+
+Binding is deferred rather than done at construction so that each counterparty gets
+its **own** store file — `FIX4.4-accept-comp-<peer>.seqnums` — which is what makes
+persisted recovery work for a multi-client acceptor. (cspurefix binds in the
+constructor and so keys a wildcard store on the literal `*`; that is fine for
+in-memory stores only.)
+
+Messages that arrive while the bind is in flight are queued and replayed in order.
+`*` on an initiator is rejected at construction — an initiator has to know who it is
+calling.
+
+## Detecting a peer that has gone
+
+Three independent mechanisms, because no single one is sufficient:
+
+| Level | Mechanism | Detects |
+|-------|-----------|---------|
+| Transport | TCP keep-alive (`tcp.keepAliveMs`, default 30s, `0` disables) | a peer whose host or network path has vanished |
+| Protocol | `TestRequest` on heartbeat timeout, then terminate | a peer that is connected but not responding |
+| Session | `SessionRegistry` replacing on the next Logon | a peer that has already reconnected |
+
+`MsgTransport.end()` performs a graceful close and then destroys the socket after
+`MsgTransport.lingerMs` (default 5s), so an unanswered FIN cannot pin the handle
+indefinitely. `TcpAcceptor.close()` releases live connections rather than waiting on
+them — `net.Server.close` otherwise blocks on whoever happens to be connected.
+
+## Reading the log
+
+The lifecycle of one connection, in order:
+
+```
+[TcpAcceptor] net creates session 2
+[TcpAcceptor] transport 2 keep-alive enabled, initial delay 30000ms
+[TcpAcceptor] transport 2 from ::1:55642 given its own session scope
+[TcpAcceptor] new transport id = 2 from ::1:55642 created total transports = 2
+[acceptor]    transport 2: creating session via DI token FixSession [accept-comp -> *]
+[acceptor]    acceptor census: transports=2 [...] sessions=1 [...]
+[...]         wildcard acceptor: awaiting peer Logon to establish session identity
+[...]         wildcard acceptor: binding session identity to peer SenderCompID 'init-comp_2'
+[...]         session identity bound: FIX4.4-accept-comp-init-comp_2 nextSender=1, expectedTarget=1
+[SessionRegistry] no existing session found - registering new session: FIX4.4-accept-comp-init-comp_2
+...
+[SessionRegistry] successfully unregistered session: ..., remainingActiveSessions=1
+[TcpAcceptor] transport 2 from ::1:55642 harvested after 18s (socket closed) total transports = 1
+[acceptor]    acceptor census: transports=1 [...] sessions=1 [...]
+```
+
+The **census** line is emitted whenever the population changes and answers "how many
+counterparties are connected, and which sessions are claimed" from the log alone.
+Transports and sessions can legitimately differ for a moment: a connection that has
+not logged on yet has a transport and no session; a session being replaced has both
+counted until its socket is released.
+
+Once a wildcard session has bound, its log prefix carries the counterparty
+(`[my_server:init-comp_2:FixSession]`), so a multi-client server log can be read one
+counterparty at a time.
+
+## Server-side recovery from a persisted store
+
+With `"store": { "type": "file", "directory": "..." }` the acceptor persists, per
+`SessionId`, the next sender sequence and the last processed peer sequence, plus the
+sent message bodies for replay.
+
+On a reconnect the session reads that store before responding to the Logon, so it
+knows what it last sent and what it last received. If the peer's Logon sequence is
+ahead of what the store expects, the acceptor issues a `ResendRequest`; if the peer
+asks for a resend, the stored bodies are replayed with `PossDupFlag=Y`.
+`ResetSeqNumFlag=Y` from either side clears the store and restarts at 1.
+
+Because the store is keyed on `SessionId`, a wildcard acceptor recovers each
+counterparty independently.
+
+## See also
+
+- [`src/transport/tcp/tcp-acceptor.ts`](../src/transport/tcp/tcp-acceptor.ts) — listener, transport lifecycle
+- [`src/transport/session/session-registry.ts`](../src/transport/session/session-registry.ts) — one session per SessionId
+- [`src/runtime/session-scope.ts`](../src/runtime/session-scope.ts) — per-connection DI scope
+- [jspf-demo](https://github.com/TimelordUK/jspf-demo) — `multi-client` and `stale-transport` scenarios

package/docs/benchmarking.md

@@ -0,0 +1,117 @@
+# Benchmarking
+
+`jsfix-bench` drives fix bytes through the real parser and reports what the work
+costs in time and in garbage. It exists so a change to a hot path can be argued
+about with a number rather than an opinion.
+
+```
+npm run build
+npm run bench
+```
+
+Always under `--expose-gc`, which the npm scripts do for you. Without it rounds
+cannot be isolated from one another and the retained heap figures mean very
+little; the report says so at the top when it is missing.
+
+## What it measures
+
+Two cases by default, over the same input:
+
+| case | what it covers |
+| --- | --- |
+| `parse:view` | tokenise, discover the structure, build the `MsgView` |
+| `parse:object` | the above, then `toObject()` to materialise the object graph |
+
+Both matter. `parse:view` is the engine's own cost. `parse:object` is what a
+drop copy consumer actually pays, and the gap between them is the price of
+materialising a message rather than reading fields out of the view.
+
+## Reading the report
+
+```
+parse:object
+  rounds        8 x 4000 msgs (warmup 4000)
+  per msg       median 239.922us   min 231.305us   p95 242.623us   max 242.623us
+  throughput    4,168 msg/sec
+  noise         1.80% of median (a change smaller than this means nothing)
+  gc pass       4000 msgs uninterrupted: 25 minor  0 major  5.8ms paused
+  gc rate       6250.0 minor/M msgs   0.0 major/M msgs   1445ms paused/M msgs
+  retained      -0.00MB   -0.6 bytes/msg   heap at end of pass 116.08MB
+```
+
+- **rounds** each contribute one timing sample. One long run cannot tell you
+  whether a number repeats.
+- **min** is the closest reading to the true cost of the work - a round can only
+  be made slower by interference, never faster - while **median** is what to
+  expect in practice.
+- **noise** is the run to run spread. Treat it as the resolution of the
+  instrument: a change smaller than this is not evidence of anything.
+- **gc rate** is collections per million messages. Node will not tell you how
+  many bytes a stretch of code allocated, so scavenge frequency is the stand in.
+  In practice it is far more repeatable than the timings - the same build tends
+  to reproduce it exactly - which makes it the more sensitive of the two signals
+  for spotting an allocation change.
+- **retained** is what the pass left behind after a forced collection, not what
+  it churned through. A steady state parser should sit near zero. Churn is what
+  the gc figures are for.
+
+## Why timing and memory are measured separately
+
+Isolating a timed round means forcing a collection between rounds, and a forced
+collection is itself a gc event - counting those would report the harness rather
+than the engine. So the timed rounds collect between them and report no gc
+figures, and a separate uninterrupted pass runs with the probe attached and
+reports no timings. BenchmarkDotNet splits its memory diagnoser out of the
+timed iterations for the same reason.
+
+Node also dispatches a gc entry on the turn *after* the collection, and the
+benchmark loop is synchronous, so the runner yields until delivery goes quiet
+before reading the totals. A single yield loses most of them.
+
+## Comparing against a baseline
+
+```
+npm run build
+node --expose-gc dist/jsfix-bench --save=benchmarks/baseline.json --label="before"
+# ... make a change, rebuild ...
+node --expose-gc dist/jsfix-bench --baseline=benchmarks/baseline.json
+```
+
+```
+parse:object
+  per msg   239.922us -> 243.523us   +1.50%   noise   (noise floor +/-2.75%)
+  minor gc  6250.0 -> 6250.0 per M msgs   +0.00%
+```
+
+A difference is only called `FASTER` or `SLOWER` when it is larger than the
+spread both runs displayed. Anything else is reported as `noise`, because that
+is what it is. Baselines are specific to the machine and node build that took
+them - the report warns when they differ - so `benchmarks/` is not committed.
+
+## Options
+
+| flag | meaning |
+| --- | --- |
+| `--fix=<path>` | fix log to parse |
+| `--dict=<name>` | dictionary, e.g. `qf44`, `repo44`, `qf50sp2` |
+| `--delimiter=<char>` | field delimiter in the log, defaults to `\|` |
+| `--depth=view,object` | which stages to measure |
+| `--rounds=<n>` | measured rounds, one sample each |
+| `--msgs=<n>` | messages per round |
+| `--warmup=<n>` | messages discarded before measuring |
+| `--save=<path>` | write the suite to json |
+| `--baseline=<path>` | compare against a saved suite |
+| `--json` | print the suite as json instead of a report |
+
+Ready made suites: `bench:er`, `bench:er2`, `bench:nos`, `bench:md`, `bench:tc`.
+
+Message counts are rounded up to a whole number of passes over the input file,
+since a pass cannot be stopped part way. A log holding one message gives the
+finest control.
+
+## Warmup
+
+The default warmup is 20,000 messages. V8 needs to see a function run several
+thousand times before it stops interpreting it, so an unwarmed first round
+measures the wrong code. If you lower it, check the noise figure has not risen -
+that is what an under-warmed run looks like.

package/eslint.config.mjs

@@ -106,6 +106,8 @@ export default [
       'prefer-template': 'off',
       'radix': 'off',
       'require-unicode-regexp': 'off',
+      // named capture groups need a target of es2018, this package emits es6
+      'prefer-named-capture-group': 'off',
       'promise/avoid-new': 'off',
       'promise/no-multiple-resolved': 'off',
       'import/enforce-node-protocol-usage': 'off',
@@ -114,6 +116,18 @@ export default [
     }
   },
   {
-    ignores: ['dist/**', 'node_modules/**']
+    files: ['src/test/**/*.ts'],
+    rules: {
+      // tests assert a value is present with expect(x).toBeDefined() and then use x!.
+      // the compiler cannot follow that, and rewriting each site as an explicit throw
+      // buries the assertion the test is actually about.
+      '@typescript-eslint/no-non-null-assertion': 'off',
+      // save/restore of a static around an awaited body is not a race in a jest file,
+      // which runs its tests serially.
+      'require-atomic-updates': 'off'
+    }
+  },
+  {
+    ignores: ['dist/**', 'node_modules/**', 'coverage/**']
   }
 ]