jspurefix 5.2.0 → 5.5.0

package/src/dictionary/parser/quickfix/x-element.ts

@@ -0,0 +1,115 @@
+/**
+ * Lightweight in-memory XML element tree — provides DOM-like random access
+ * over XML parsed by SAX. Mirrors the C# XDocument/XElement API surface
+ * used by QuickFixXmlFileParser and DictionaryValidator.
+ */
+export interface XElement {
+  readonly name: string
+  readonly attributes: Record<string, string>
+  readonly children: XElement[]
+  readonly line?: number
+}
+
+/**
+ * Query helper wrapping an XElement tree with C#-style traversal methods.
+ * Mirrors XDocument/XElement LINQ-to-XML API used in cspurefix.
+ */
+export class XNode {
+  constructor (public readonly element: XElement) {}
+
+  /** Attribute value by name, or undefined if not present. */
+  attribute (name: string): string | undefined {
+    return this.element.attributes[name]
+  }
+
+  /** Direct children with the given tag name. */
+  elements (name?: string): XNode[] {
+    const children = name
+      ? this.element.children.filter(c => c.name === name)
+      : this.element.children
+    return children.map(c => new XNode(c))
+  }
+
+  /** First direct child with the given tag name, or undefined. */
+  firstElement (name: string): XNode | undefined {
+    const child = this.element.children.find(c => c.name === name)
+    return child ? new XNode(child) : undefined
+  }
+
+  /** All descendants (recursive) with the given tag name. */
+  descendants (name: string): XNode[] {
+    const result: XNode[] = []
+    this.collectDescendants(this.element, name, result)
+    return result
+  }
+
+  /** First descendant with the given tag name, or undefined. */
+  firstDescendant (name: string): XNode | undefined {
+    return this.findDescendant(this.element, name)
+  }
+
+  /** Shorthand: attribute value, throwing if missing. */
+  requiredAttribute (name: string): string {
+    const val = this.element.attributes[name]
+    if (val === undefined) {
+      throw new Error(`missing required attribute '${name}' on <${this.element.name}> at line ${this.element.line ?? '?'}`)
+    }
+    return val
+  }
+
+  /** The element's tag name. */
+  get name (): string {
+    return this.element.name
+  }
+
+  /** The element's source line number, if available. */
+  get line (): number | undefined {
+    return this.element.line
+  }
+
+  private collectDescendants (el: XElement, name: string, result: XNode[]): void {
+    for (const child of el.children) {
+      if (child.name === name) {
+        result.push(new XNode(child))
+      }
+      this.collectDescendants(child, name, result)
+    }
+  }
+
+  private findDescendant (el: XElement, name: string): XNode | undefined {
+    for (const child of el.children) {
+      if (child.name === name) {
+        return new XNode(child)
+      }
+      const found = this.findDescendant(child, name)
+      if (found) return found
+    }
+    return undefined
+  }
+}
+
+/**
+ * Parsed XML document — wraps the root element with query methods.
+ * Equivalent to C# XDocument.
+ */
+export class XDocument {
+  public readonly root: XNode
+
+  constructor (rootElement: XElement) {
+    this.root = new XNode(rootElement)
+  }
+
+  /** All descendants of the root with the given tag name (including the root itself if it matches). */
+  descendants (name: string): XNode[] {
+    const result: XNode[] = []
+    if (this.root.name === name) result.push(this.root)
+    result.push(...this.root.descendants(name))
+    return result
+  }
+
+  /** First descendant of the root with the given tag name (including the root itself if it matches). */
+  firstDescendant (name: string): XNode | undefined {
+    if (this.root.name === name) return this.root
+    return this.root.firstDescendant(name)
+  }
+}

package/src/store/file-session-store.ts

@@ -0,0 +1,294 @@
+import { IFixSessionStore } from './fix-session-store'
+import { SessionId } from './session-id'
+import { IFixMsgStoreRecord, FixMsgStoreRecord } from './fix-msg-store-record'
+import { ISessionStreamProvider } from './session-stream-provider'
+import { FileSessionStreamProvider } from './file-session-stream-provider'
+
+/**
+ * QuickFix-compatible file-based session store.
+ *
+ * File format:
+ * - .seqnums: "SSSSSSSSSSSSSSSSSSSS : TTTTTTTTTTTTTTTTTTTT" (20-char right-justified sender : target)
+ * - .session: "YYYYMMDD-HH:MM:SS.ffffff" (session creation time)
+ * - .header: "seqnum,offset,length" per line (index into body)
+ * - .body: concatenated raw FIX messages (no delimiters)
+ */
+export class FileSessionStore implements IFixSessionStore {
+  private readonly streamProvider: ISessionStreamProvider
+  private readonly ownsProvider: boolean
+
+  private senderSeqNumValue: number = 1
+  private targetSeqNumValue: number = 1
+  private creationTimeValue: Date = new Date()
+
+  // In-memory index: seqnum -> { offset, length }
+  private readonly headerIndex: Map<number, { offset: number, length: number }> = new Map()
+
+  /**
+   * Creates a FileSessionStore with the default file-based stream provider.
+   */
+  static createWithFiles (sessionId: SessionId, directory: string): FileSessionStore {
+    return new FileSessionStore(sessionId, new FileSessionStreamProvider(sessionId, directory), true)
+  }
+
+  /**
+   * Creates a FileSessionStore with a custom stream provider.
+   * Useful for testing with in-memory streams.
+   */
+  constructor (
+    public readonly sessionId: SessionId,
+    streamProvider: ISessionStreamProvider,
+    ownsProvider: boolean = false
+  ) {
+    this.streamProvider = streamProvider
+    this.ownsProvider = ownsProvider
+  }
+
+  /**
+   * Gets the stream provider for direct access (useful for testing).
+   */
+  getStreamProvider (): ISessionStreamProvider {
+    return this.streamProvider
+  }
+
+  // Sequence Numbers
+
+  get senderSeqNum (): number {
+    return this.senderSeqNumValue
+  }
+
+  set senderSeqNum (value: number) {
+    this.senderSeqNumValue = value
+  }
+
+  get targetSeqNum (): number {
+    return this.targetSeqNumValue
+  }
+
+  set targetSeqNum (value: number) {
+    this.targetSeqNumValue = value
+  }
+
+  async setSenderSeqNum (value: number): Promise<void> {
+    this.senderSeqNumValue = value
+    await this.persistSeqNums()
+  }
+
+  async setTargetSeqNum (value: number): Promise<void> {
+    this.targetSeqNumValue = value
+    await this.persistSeqNums()
+  }
+
+  async nextSenderSeqNum (): Promise<number> {
+    const next = ++this.senderSeqNumValue
+    await this.persistSeqNums()
+    return next
+  }
+
+  async nextTargetSeqNum (): Promise<number> {
+    const next = ++this.targetSeqNumValue
+    await this.persistSeqNums()
+    return next
+  }
+
+  // Session
+
+  get creationTime (): Date {
+    return this.creationTimeValue
+  }
+
+  async reset (): Promise<void> {
+    this.senderSeqNumValue = 1
+    this.targetSeqNumValue = 1
+    this.creationTimeValue = new Date()
+    this.headerIndex.clear()
+
+    await this.streamProvider.reset()
+    await this.persistSeqNums()
+    await this.persistSessionTime()
+    this.streamProvider.openBody()
+  }
+
+  // Message Operations
+
+  async put (record: IFixMsgStoreRecord): Promise<void> {
+    if (record.encoded == null) {
+      throw new Error('Record must have encoded content')
+    }
+
+    const bytes = Buffer.from(record.encoded, 'utf8')
+    const length = bytes.length
+    const offset = await this.streamProvider.appendBody(bytes)
+    this.headerIndex.set(record.seqNum, { offset, length })
+    await this.streamProvider.appendHeaderLine(`${record.seqNum},${offset},${length}`)
+  }
+
+  async get (seqNum: number): Promise<IFixMsgStoreRecord | null> {
+    const entry = this.headerIndex.get(seqNum)
+    if (!entry) return null
+    return await this.readMessage(seqNum, entry.offset, entry.length)
+  }
+
+  async getRange (fromSeqNum: number, toSeqNum: number): Promise<IFixMsgStoreRecord[]> {
+    const results: IFixMsgStoreRecord[] = []
+    for (let seq = fromSeqNum; seq <= toSeqNum; seq++) {
+      const record = await this.get(seq)
+      if (record) {
+        results.push(record)
+      }
+    }
+    return results
+  }
+
+  // Lifecycle
+
+  async initialize (): Promise<void> {
+    await this.loadSeqNums()
+    await this.loadSessionTime()
+    await this.loadHeaderIndex()
+    this.streamProvider.openBody()
+  }
+
+  async flush (): Promise<void> {
+    await this.streamProvider.flush()
+  }
+
+  async dispose (): Promise<void> {
+    await this.streamProvider.flush()
+    if (this.ownsProvider) {
+      await this.streamProvider.dispose()
+    }
+  }
+
+  // Private - persistence
+
+  private async persistSeqNums (): Promise<void> {
+    const sender = this.senderSeqNumValue.toString().padStart(20, ' ')
+    const target = this.targetSeqNumValue.toString().padStart(20, ' ')
+    await this.streamProvider.writeSeqNums(`${sender} : ${target}`)
+  }
+
+  private async loadSeqNums (): Promise<void> {
+    const content = await this.streamProvider.readSeqNums()
+    if (content == null) {
+      this.senderSeqNumValue = 1
+      this.targetSeqNumValue = 1
+      return
+    }
+    const parts = content.split(':')
+    if (parts.length === 2) {
+      this.senderSeqNumValue = parseInt(parts[0].trim(), 10) || 1
+      this.targetSeqNumValue = parseInt(parts[1].trim(), 10) || 1
+    }
+  }
+
+  private async persistSessionTime (): Promise<void> {
+    await this.streamProvider.writeSessionTime(FileSessionStore.formatSessionTime(this.creationTimeValue))
+  }
+
+  private async loadSessionTime (): Promise<void> {
+    const content = await this.streamProvider.readSessionTime()
+    if (content == null) {
+      this.creationTimeValue = new Date()
+      await this.persistSessionTime()
+      return
+    }
+    const parsed = FileSessionStore.parseSessionTime(content.trim())
+    this.creationTimeValue = parsed ?? new Date()
+  }
+
+  private async loadHeaderIndex (): Promise<void> {
+    const lines = await this.streamProvider.readHeaderLines()
+    for (const line of lines) {
+      if (!line.trim()) continue
+      const parts = line.split(',')
+      if (parts.length === 3) {
+        const seqNum = parseInt(parts[0], 10)
+        const offset = parseInt(parts[1], 10)
+        const length = parseInt(parts[2], 10)
+        if (!isNaN(seqNum) && !isNaN(offset) && !isNaN(length)) {
+          this.headerIndex.set(seqNum, { offset, length })
+        }
+      }
+    }
+  }
+
+  // Private - message reading
+
+  private async readMessage (seqNum: number, offset: number, length: number): Promise<IFixMsgStoreRecord | null> {
+    const buffer = await this.streamProvider.readBody(offset, length)
+    if (buffer.length !== length) return null
+
+    const encoded = buffer.toString('utf8')
+    const msgType = FileSessionStore.extractTag(encoded, '35')
+    const sendingTimeStr = FileSessionStore.extractTag(encoded, '52')
+    let timestamp = new Date(0)
+    if (sendingTimeStr) {
+      const parsed = FileSessionStore.parseSessionTime(sendingTimeStr)
+      if (parsed) timestamp = parsed
+    }
+
+    return new FixMsgStoreRecord(msgType ?? '', timestamp, seqNum, undefined, encoded)
+  }
+
+  /**
+   * Extract a FIX tag value from a raw message string.
+   * Tags are delimited by SOH (0x01) or pipe (|).
+   */
+  static extractTag (message: string, tag: string): string | null {
+    const tagPrefix = `${tag}=`
+
+    // Check if tag is at the start
+    if (message.startsWith(tagPrefix)) {
+      const endIndex = FileSessionStore.findDelimiter(message, tagPrefix.length)
+      return message.substring(tagPrefix.length, endIndex)
+    }
+
+    // Search for SOH + tag= or | + tag=
+    for (const delim of ['\x01', '|']) {
+      const search = `${delim}${tagPrefix}`
+      const idx = message.indexOf(search)
+      if (idx >= 0) {
+        const startIndex = idx + search.length
+        const endIndex = FileSessionStore.findDelimiter(message, startIndex)
+        return message.substring(startIndex, endIndex)
+      }
+    }
+
+    return null
+  }
+
+  private static findDelimiter (message: string, fromIndex: number): number {
+    for (let i = fromIndex; i < message.length; i++) {
+      const ch = message.charAt(i)
+      if (ch === '\x01' || ch === '|') return i
+    }
+    return message.length
+  }
+
+  /**
+   * Format a date as QuickFix session time: YYYYMMDD-HH:MM:SS.ffffff
+   */
+  static formatSessionTime (date: Date): string {
+    const y = date.getUTCFullYear()
+    const M = (date.getUTCMonth() + 1).toString().padStart(2, '0')
+    const d = date.getUTCDate().toString().padStart(2, '0')
+    const h = date.getUTCHours().toString().padStart(2, '0')
+    const m = date.getUTCMinutes().toString().padStart(2, '0')
+    const s = date.getUTCSeconds().toString().padStart(2, '0')
+    const ms = date.getUTCMilliseconds().toString().padStart(3, '0')
+    return `${y}${M}${d}-${h}:${m}:${s}.${ms}000`
+  }
+
+  /**
+   * Parse a QuickFix session time string: YYYYMMDD-HH:MM:SS.fff[fff]
+   */
+  static parseSessionTime (str: string): Date | null {
+    // Format: YYYYMMDD-HH:MM:SS.ffffff
+    const match = str.match(/^(\d{4})(\d{2})(\d{2})-(\d{2}):(\d{2}):(\d{2})\.(\d{3,6})$/)
+    if (!match) return null
+    const [, y, M, d, h, m, s, frac] = match
+    const ms = parseInt(frac.substring(0, 3), 10)
+    return new Date(Date.UTC(parseInt(y), parseInt(M) - 1, parseInt(d), parseInt(h), parseInt(m), parseInt(s), ms))
+  }
+}

package/src/store/file-session-stream-provider.ts

@@ -0,0 +1,123 @@
+import * as fs from 'fs'
+import { ISessionStreamProvider } from './session-stream-provider'
+import { SessionId } from './session-id'
+
+/**
+ * File-based implementation of ISessionStreamProvider.
+ * Creates QuickFix-compatible files in the specified directory.
+ *
+ * Files created:
+ * - {prefix}.body   — concatenated raw FIX messages
+ * - {prefix}.header — index lines: "seqnum,offset,length"
+ * - {prefix}.seqnums — sender/target sequence numbers
+ * - {prefix}.session — session creation time
+ */
+export class FileSessionStreamProvider implements ISessionStreamProvider {
+  private readonly bodyPath: string
+  private readonly headerPath: string
+  private readonly seqNumsPath: string
+  private readonly sessionPath: string
+  private bodyFd: number | null = null
+  private bodySize: number = 0
+
+  constructor (
+    sessionId: SessionId,
+    directory: string
+  ) {
+    fs.mkdirSync(directory, { recursive: true })
+    this.bodyPath = sessionId.getFilePath(directory, 'body')
+    this.headerPath = sessionId.getFilePath(directory, 'header')
+    this.seqNumsPath = sessionId.getFilePath(directory, 'seqnums')
+    this.sessionPath = sessionId.getFilePath(directory, 'session')
+  }
+
+  openBody (): void {
+    if (this.bodyFd !== null) return
+    this.bodyFd = fs.openSync(this.bodyPath, 'a+')
+    const stat = fs.fstatSync(this.bodyFd)
+    this.bodySize = stat.size
+  }
+
+  async appendBody (data: Buffer): Promise<number> {
+    if (this.bodyFd === null) {
+      this.openBody()
+    }
+    const offset = this.bodySize
+    fs.writeSync(this.bodyFd!, data, 0, data.length, offset)
+    this.bodySize += data.length
+    return offset
+  }
+
+  async readBody (offset: number, length: number): Promise<Buffer> {
+    if (this.bodyFd === null) {
+      this.openBody()
+    }
+    const buf = Buffer.alloc(length)
+    fs.readSync(this.bodyFd!, buf, 0, length, offset)
+    return buf
+  }
+
+  getBodySize (): number {
+    return this.bodySize
+  }
+
+  async appendHeaderLine (line: string): Promise<void> {
+    await fs.promises.appendFile(this.headerPath, line + '\n', 'utf8')
+  }
+
+  async readHeaderLines (): Promise<string[]> {
+    if (!fs.existsSync(this.headerPath)) return []
+    const content = await fs.promises.readFile(this.headerPath, 'utf8')
+    if (!content.trim()) return []
+    return content.split('\n').filter(l => l.trim().length > 0)
+  }
+
+  async readSeqNums (): Promise<string | null> {
+    if (!fs.existsSync(this.seqNumsPath)) return null
+    return await fs.promises.readFile(this.seqNumsPath, 'utf8')
+  }
+
+  async writeSeqNums (content: string): Promise<void> {
+    await fs.promises.writeFile(this.seqNumsPath, content, 'utf8')
+  }
+
+  async readSessionTime (): Promise<string | null> {
+    if (!fs.existsSync(this.sessionPath)) return null
+    return await fs.promises.readFile(this.sessionPath, 'utf8')
+  }
+
+  async writeSessionTime (content: string): Promise<void> {
+    await fs.promises.writeFile(this.sessionPath, content, 'utf8')
+  }
+
+  async reset (): Promise<void> {
+    if (this.bodyFd !== null) {
+      fs.closeSync(this.bodyFd)
+      this.bodyFd = null
+    }
+    this.bodySize = 0
+    this.deleteIfExists(this.bodyPath)
+    this.deleteIfExists(this.headerPath)
+    this.deleteIfExists(this.seqNumsPath)
+    this.deleteIfExists(this.sessionPath)
+  }
+
+  async flush (): Promise<void> {
+    if (this.bodyFd !== null) {
+      fs.fsyncSync(this.bodyFd)
+    }
+  }
+
+  async dispose (): Promise<void> {
+    if (this.bodyFd !== null) {
+      fs.closeSync(this.bodyFd)
+      this.bodyFd = null
+    }
+  }
+
+  private deleteIfExists (filePath: string): void {
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath)
+    }
+  }
+}

package/src/store/fix-msg-ascii-store-resend.ts

@@ -13,6 +13,14 @@ export class FixMsgAsciiStoreResend {
   }
 
   public async getResendRequest (startSeq: number, endSeq: number): Promise<IFixMsgStoreRecord[]> {
+    // Safety feature: If ResendGapFillOnly is enabled, ALWAYS send GapFill instead of
+    // replaying stored messages. This prevents accidental duplicate order execution.
+    if (this.config.description.store?.resendGapFillOnly === true) {
+      const gapFillOnly: IFixMsgStoreRecord[] = []
+      this.gap(startSeq, endSeq + 1, gapFillOnly)
+      return gapFillOnly
+    }
+
     // need to cover request from start to end where any missing numbers are
     // included as gaps to allow vector of messages to be sent by the session
     // on a request

package/src/store/fix-session-store-factory.ts

@@ -0,0 +1,31 @@
+import { IFixSessionStore } from './fix-session-store'
+import { SessionId } from './session-id'
+import { MemorySessionStore } from './memory-session-store'
+import { FileSessionStore } from './file-session-store'
+
+/**
+ * Factory for creating session stores.
+ */
+export interface IFixSessionStoreFactory {
+  create (sessionId: SessionId): IFixSessionStore
+}
+
+/**
+ * Factory for creating in-memory session stores.
+ */
+export class MemorySessionStoreFactory implements IFixSessionStoreFactory {
+  create (sessionId: SessionId): IFixSessionStore {
+    return new MemorySessionStore(sessionId)
+  }
+}
+
+/**
+ * Factory for creating file-based session stores.
+ */
+export class FileSessionStoreFactory implements IFixSessionStoreFactory {
+  constructor (private readonly directory: string) {}
+
+  create (sessionId: SessionId): IFixSessionStore {
+    return FileSessionStore.createWithFiles(sessionId, this.directory)
+  }
+}

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

@@ -0,0 +1,37 @@
+import { SessionId } from './session-id'
+import { IFixMsgStoreRecord } from './fix-msg-store-record'
+
+/**
+ * Unified session store interface for FIX message persistence and sequence number management.
+ * Coordinates all persistence for a single FIX session:
+ * - Message storage (.body + .header files)
+ * - Sequence numbers (.seqnums file)
+ * - Session metadata (.session file)
+ *
+ * QuickFix-compatible file format for interoperability.
+ */
+export interface IFixSessionStore {
+  readonly sessionId: SessionId
+
+  // Message Operations
+  put (record: IFixMsgStoreRecord): Promise<void>
+  get (seqNum: number): Promise<IFixMsgStoreRecord | null>
+  getRange (fromSeqNum: number, toSeqNum: number): Promise<IFixMsgStoreRecord[]>
+
+  // Sequence Number Operations
+  senderSeqNum: number
+  targetSeqNum: number
+  setSenderSeqNum (value: number): Promise<void>
+  setTargetSeqNum (value: number): Promise<void>
+  nextSenderSeqNum (): Promise<number>
+  nextTargetSeqNum (): Promise<number>
+
+  // Session Operations
+  readonly creationTime: Date
+  reset (): Promise<void>
+
+  // Lifecycle
+  initialize (): Promise<void>
+  flush (): Promise<void>
+  dispose (): Promise<void>
+}

package/src/store/index.ts

@@ -2,3 +2,12 @@ export * from './fix-msg-memory-store'
 export * from './fix-msg-store'
 export * from './fix-msg-store-record'
 export * from './fix-msg-ascii-store-resend'
+export * from './session-id'
+export * from './fix-session-store'
+export * from './memory-session-store'
+export * from './fix-session-store-factory'
+export * from './session-stream-provider'
+export * from './memory-session-stream-provider'
+export * from './file-session-stream-provider'
+export * from './file-session-store'
+export * from './store-config'