jspurefix 5.9.2 → 5.10.0

package/src/runtime/session-container.ts

@@ -20,7 +20,23 @@ import { FixmlEncoder, FiXmlParser } from '../buffer/fixml'
 import { FixEntity } from '../transport/fix-entity'
 import { IHttpAdapter } from '../transport/http/http-adapter'
 
+/**
+ * Supplies the session message factory for a description.  Return null to accept the
+ * stock factory for the protocol.
+ */
+export type SessionMsgFactoryProvider = (description: ISessionDescription) => ISessionMsgFactory | null
+
 export class SessionContainer {
+  /**
+   * @param msgFactoryProvider an application that needs its own session messages -
+   * typically a Logon carrying tags the standard message does not - can pass one
+   * here rather than subclassing to override makeSessionFactory:
+   *
+   *   new SessionContainer(d => new MyFactory(d))
+   */
+  constructor (public readonly msgFactoryProvider: SessionMsgFactoryProvider | null = null) {
+  }
+
   public reset (): void {
     container.reset()
   }
@@ -45,6 +61,10 @@ export class SessionContainer {
   }
 
   protected makeSessionFactory (description: ISessionDescription): ISessionMsgFactory {
+    const supplied = this.msgFactoryProvider?.(description)
+    if (supplied) {
+      return supplied
+    }
     const fixml = !this.isAscii(description)
     return fixml
       ? new FixmlSessionMsgFactory(description)

package/src/runtime/session-launcher.ts

@@ -1,6 +1,6 @@
 import * as path from 'path'
 import { IJsFixConfig, IJsFixLogger, JsFixLoggerFactory, JsFixWinstonLogFactory, WinstonLogger } from '../config'
-import { FixEntity, FixSession, ISessionDescription } from '../transport'
+import { FixEntity, FixSession, ISessionDescription, ISessionMsgFactory } from '../transport'
 import { DependencyContainer } from 'tsyringe'
 import { EngineFactory } from './engine-factory'
 import { SessionContainer } from './session-container'
@@ -24,7 +24,24 @@ export abstract class SessionLauncher {
     this.acceptorConfig = acceptorConfig ? this.loadConfig(acceptorConfig) : null
   }
 
-  protected sessionContainer: SessionContainer = new SessionContainer()
+  // the arrow defers to makeSessionMsgFactory at resolve time, so a subclass need
+  // only override that one method - no SessionContainer subclass required
+  protected sessionContainer: SessionContainer =
+    new SessionContainer((d: ISessionDescription) => this.makeSessionMsgFactory(d))
+
+  /**
+   * Override to supply this application's own session message factory - the place to
+   * put a Logon carrying tags the standard message does not, or a header a
+   * counterparty stamps differently.  Return null (the default) for the stock
+   * factory.
+   *
+   * For a Logon that only needs extra fields, prefer the "Logon" block in the session
+   * description - it needs no code at all.  Reach for a factory when the values are
+   * computed at run time (a signature, a nonce, a token fetched at start up).
+   */
+  protected makeSessionMsgFactory (_description: ISessionDescription): ISessionMsgFactory | null {
+    return null
+  }
 
   private async empty (): Promise<any> {
     return await new Promise((resolve, reject) => {

package/src/transport/ascii/ascii-msg-transmitter.ts

@@ -28,6 +28,26 @@ export class AsciiMsgTransmitter extends MsgTransmitter {
     const components = config.definitions.component
     this.header = components.get('StandardHeader')
     this.trailer = components.get('StandardTrailer')
+    this.reportUnknownFields(config)
+  }
+
+  /**
+   * A field the dictionary does not declare on the message being encoded has no tag,
+   * so it cannot be written and is dropped.  Say so once per offending field - the
+   * alternative, and what this library did for years, is that a bespoke Logon tag
+   * simply never appears on the wire and nothing anywhere explains why.
+   */
+  private reportUnknownFields (config: IJsFixConfig): void {
+    const name = config.description.application?.name ?? 'na'
+    const logger = config.logFactory.logger(`${name}:encoder`)
+    const reported = new Set<string>()
+    this.encoder.onUnknownField = (fieldName: string, setName: string) => {
+      const key = `${setName}.${fieldName}`
+      if (reported.has(key)) return
+      reported.add(key)
+      logger.warning(`field '${fieldName}' is not declared on ${setName} in this dictionary - it will not be sent`)
+      this.emit('unknown-field', fieldName, setName)
+    }
   }
 
   private checksum (): number {

package/src/transport/ascii/ascii-session-msg-factory.ts

@@ -23,7 +23,12 @@ export class AsciiSessionMsgFactory extends ASessionMsgFactory {
       Password: description.Password,
       HeartBtInt: description.HeartBtInt,
       ResetSeqNumFlag: description.ResetSeqNumFlag,
-      EncryptMethod: EncryptMethod.None
+      EncryptMethod: EncryptMethod.None,
+      // a counterparty demanding a tag the standard Logon does not carry needs no
+      // code at all - name it under "Logon" in the session description.  Spread last
+      // so an application can also override what the engine derived, or null out a
+      // field it does not want sent.  See issue #93.
+      ...description.Logon
     } as ILogon
     return this.mutate(o, MsgType.Logon)
   }

package/src/transport/fixml/fixml-session-msg-factory.ts

@@ -42,7 +42,9 @@ export class FixmlSessionMsgFactory extends ASessionMsgFactory {
         Username: description.Username,
         Password: description.Password,
         UserRequestID: userRequestId,
-        UserRequestType: UserRequestType.LogOnUser
+        UserRequestType: UserRequestType.LogOnUser,
+        // same escape hatch as the ascii factory - see ISessionDescription.Logon
+        ...description.Logon
       } as IUserRequest
       return this.mutate(o, MsgType.Logon)
     } else {

package/src/transport/index.ts

@@ -4,7 +4,12 @@ export * from './fix-acceptor'
 export * from './fix-initiator'
 export * from './msg-transmitter'
 export * from './msg-payload'
+export * from './send-callback'
 export * from './tick-action'
 export * from './msg-application'
 export * from './ascii/ascii-session'
+// the factory an application extends to customise its Logon or header - it belongs
+// at the root alongside ASessionMsgFactory, not behind a dist/ path
+export * from './ascii/ascii-session-msg-factory'
+export * from './fixml/fixml-session-msg-factory'
 export * from './session'

package/src/transport/msg-payload.ts

@@ -1,7 +1,11 @@
 import { ILooseObject } from '../collections/collection'
+import { SendCallback } from './send-callback'
 
 export class MsgPayload {
   public encoded: Buffer
-  constructor (public readonly msgType: string, public readonly obj: ILooseObject) {
+  constructor (public readonly msgType: string,
+    public readonly obj: ILooseObject,
+    /** invoked once this payload has been encoded, or has failed to encode */
+    public readonly callback: SendCallback | null = null) {
   }
 }

package/src/transport/msg-transmitter.ts

@@ -4,6 +4,7 @@ import { Transform } from 'stream'
 import { MsgPayload } from './msg-payload'
 import { ILooseObject } from '../collections/collection'
 import { ISessionDescription } from './session/session-description'
+import { SendCallback } from './send-callback'
 import * as events from 'events'
 
 export abstract class MsgTransmitter extends events.EventEmitter {
@@ -24,8 +25,23 @@ export abstract class MsgTransmitter extends events.EventEmitter {
   }
 
   // messages at front, byte stream at back
-  public send (msgType: string, obj: ILooseObject): void {
-    this.encodeStream.write(new MsgPayload(msgType, obj))
+  public send (msgType: string, obj: ILooseObject, callback: SendCallback | null = null): void {
+    this.encodeStream.write(new MsgPayload(msgType, obj, callback))
+  }
+
+  /**
+   * Report a send outcome to whoever asked for one, without letting their code break
+   * the encode stream - a throwing callback would otherwise surface as a transform
+   * failure and be indistinguishable from an encoding fault.
+   */
+  protected settle (payload: MsgPayload, error: Error | null, header: ILooseObject | null): void {
+    const callback = payload.callback
+    if (!callback) return
+    try {
+      callback(error, { msgType: payload.msgType, header, encoded: payload.encoded ?? null })
+    } catch (e) {
+      this.emit('error', e)
+    }
   }
 
   public abstract encodeMessage (msgType: string, obj: ILooseObject): (ILooseObject | null)
@@ -46,8 +62,21 @@ export abstract class MsgTransmitter extends events.EventEmitter {
           this.push(payload.encoded)
           const encodedTxt = transmitter.buffer.toString()
           transmitter.emit('encoded', msgType, encodedTxt, state)
+          // encodeMessage returns null when it could not build the message - an
+          // unknown msgType, or a factory that produced no header.  It reports that
+          // on the error channel and carries on, so without this the callback would
+          // announce success for a message that never formed.
+          state
+            ? transmitter.settle(payload, null, state)
+            : transmitter.settle(payload, new Error(`could not encode ${msgType}`), null)
+          // note: the second argument to a Transform callback is *pushed to the
+          // readable side*, and this readable side is piped to the socket - so a
+          // result cannot be returned that way without corrupting the byte stream.
+          // Hence the per-payload callback above.
           done()
         } catch (e) {
+          transmitter.settle(payload, e as Error, null)
+          // still fail the stream, so the session's error handling is unchanged
           done(e)
         }
       }

package/src/transport/send-callback.ts

@@ -0,0 +1,33 @@
+import { ILooseObject } from '../collections/collection'
+
+/**
+ * What a send produced.  `header` is the StandardHeader the engine stamped on the
+ * message - the sequence number it went out under, the sending time, the comp ids -
+ * which is the piece applications most often need to correlate an outbound message
+ * with an acknowledgement, a database row, or a resend.
+ */
+export interface SendResult {
+  msgType: string
+  /** the stamped StandardHeader, or null if the message never got that far */
+  header: ILooseObject | null
+  /** the bytes written to the transport */
+  encoded: Buffer | null
+}
+
+/**
+ * Called once per `send`, after the message has been encoded and pushed to the
+ * transport, or as soon as encoding fails.
+ *
+ * `send` is otherwise fire and forget: it writes into a stream and returns, so
+ * nothing tells the caller which sequence number their message went out under, and a
+ * failure surfaces on the session's error channel with no way to tell which call
+ * caused it.  See https://github.com/TimelordUK/jspurefix/issues/86
+ *
+ * Note this fires when the message has been *encoded and handed to the transport*,
+ * not when the socket has flushed it - the FIX session layer has no acknowledgement
+ * of the latter either.
+ *
+ * A callback that throws is reported on the transmitter's error channel rather than
+ * being allowed to tear down the encode stream.
+ */
+export type SendCallback = (error: Error | null, result: SendResult) => void

package/src/transport/session/fix-session.ts

@@ -4,6 +4,7 @@ import { FixSessionState } from './fix-session-state'
 import { MsgTransport } from '../factory'
 import { MsgTag } from '../../types'
 import { ILooseObject } from '../../collections/collection'
+import { SendCallback } from '../send-callback'
 
 import * as events from 'events'
 import { SessionState } from './session-state'
@@ -401,17 +402,35 @@ export abstract class FixSession extends events.EventEmitter {
     }
   }
 
-  protected send (msgType: string, obj: ILooseObject): void {
+  /**
+   * @param callback optional, invoked once the message has been encoded and handed to
+   * the transport, or as soon as that fails.  Without it a send is fire and forget:
+   * nothing tells the caller which sequence number the message went out under, and a
+   * message dropped because the session is down, or refused by the encoder, goes
+   * unanswered.  See https://github.com/TimelordUK/jspurefix/issues/86
+   */
+  protected send (msgType: string, obj: ILooseObject, callback: SendCallback | null = null): void {
     const state = this.sessionState.state
     switch (state) {
       case SessionState.Stopped: {
-        this.sessionLogger.warning(`can't send in state ${this.stateString()}`)
+        const msg = `can't send in state ${this.stateString()}`
+        this.sessionLogger.warning(msg)
+        // the message is dropped either way - but a caller that asked to be told is
+        // now told, instead of watching for a log line
+        callback?.(new Error(msg), { msgType, header: null, encoded: null })
         break
       }
 
       default: {
         this.sessionState.LastSentAt = new Date()
-        this.transport?.transmitter.send(msgType, obj)
+        const transmitter = this.transport?.transmitter
+        if (!transmitter) {
+          const msg = `no transport to send ${msgType} on`
+          this.sessionLogger.warning(msg)
+          callback?.(new Error(msg), { msgType, header: null, encoded: null })
+          break
+        }
+        transmitter.send(msgType, obj, callback)
         break
       }
     }

package/src/transport/session/session-description.ts

@@ -1,5 +1,6 @@
 import { IMsgApplication } from '../msg-application'
 import { StoreConfig } from '../../store/store-config'
+import { ILooseObject } from '../../collections/collection'
 
 export interface IDynamicSessionParams {
   readonly Name: string
@@ -15,6 +16,19 @@ export interface IDynamicSessionParams {
 
 export interface ISessionDescription extends IDynamicSessionParams {
   readonly application?: IMsgApplication
+  /**
+   * Extra fields to place on the outbound Logon, merged over the ones the engine
+   * derives from this description.  Counterparties routinely demand a tag the
+   * standard Logon does not carry - an account, a default application version, a
+   * free text token - and this is the no-code way to send it:
+   *
+   *   "Logon": { "Account": "TVKD_001", "DefaultApplVerID": "9" }
+   *
+   * A field named here still has to exist on Logon in the dictionary the session
+   * loads, otherwise the encoder has no tag to write it to.  Set a field to null to
+   * suppress one the engine would otherwise send.  See issues #93, #39, #96.
+   */
+  readonly Logon?: ILooseObject
   HeartBtInt: number
   LastSentSeqNum?: number
   readonly LastReceivedSeqNum?: number