jspurefix 5.1.0 → 5.3.0

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

@@ -390,9 +390,14 @@ export abstract class FixSession extends events.EventEmitter {
     const resetFlag = this.config.description.ResetSeqNumFlag
     const seqNum = resetFlag ? 0 : resetSeqNum ?? this.sessionState.lastPeerMsgSeqNum
     this.sessionState.reset(seqNum) // from header def ... eventually
+    this.onPrepareForReconnect()
     this.setState(SessionState.NetworkConnectionEstablished)
   }
 
+  protected onPrepareForReconnect (): void {
+    // Override in subclass to reset coordinator/transient state
+  }
+
   protected stop (error: Error | null = null): void {
     if (this.sessionState.state === SessionState.Stopped) {
       return

package/src/transport/session/index.ts

@@ -6,3 +6,7 @@ export * from './session-50-description'
 export * from './session-description'
 export * from './session-msg-factory'
 export * from './session-state'
+export * from './session-sequence-coordinator'
+export * from './session-sequence-store'
+export * from './resend-request-manager'
+export * from './fix-clock'

package/src/transport/session/resend-request-manager.ts

@@ -0,0 +1,268 @@
+export enum ResendActionType {
+  Nothing = 'Nothing',
+  SendResendRequest = 'SendResendRequest',
+  SendGapFill = 'SendGapFill',
+  Wait = 'Wait'
+}
+
+export class ResendAction {
+  private constructor (
+    public readonly type: ResendActionType,
+    public readonly begin: number | null,
+    public readonly end: number | null,
+    public readonly reason: string | null
+  ) {}
+
+  static sendResendRequest (begin: number, end: number): ResendAction {
+    return new ResendAction(ResendActionType.SendResendRequest, begin, end, null)
+  }
+
+  static gapFill (begin: number, end: number, reason: string): ResendAction {
+    return new ResendAction(ResendActionType.SendGapFill, begin, end, reason)
+  }
+
+  static wait (reason: string): ResendAction {
+    return new ResendAction(ResendActionType.Wait, null, null, reason)
+  }
+
+  static nothing (): ResendAction {
+    return new ResendAction(ResendActionType.Nothing, null, null, null)
+  }
+
+  toString (): string {
+    switch (this.type) {
+      case ResendActionType.SendResendRequest:
+        return `SendResendRequest(${this.begin}-${this.end})`
+      case ResendActionType.SendGapFill:
+        return `GapFill(${this.begin}-${this.end}): ${this.reason}`
+      case ResendActionType.Wait:
+        return `Wait: ${this.reason}`
+      case ResendActionType.Nothing:
+        return 'Nothing'
+      default:
+        return `Unknown(${this.type})`
+    }
+  }
+}
+
+export class PendingResendRange {
+  private readonly receivedSeqs: Set<number> = new Set()
+
+  constructor (
+    public readonly begin: number,
+    public readonly end: number,
+    public readonly sentAt: Date
+  ) {}
+
+  markReceived (seqNum: number): void {
+    if (seqNum >= this.begin && seqNum <= this.end) {
+      this.receivedSeqs.add(seqNum)
+    }
+  }
+
+  markRangeReceived (fromSeq: number, toSeq: number): void {
+    const start = Math.max(fromSeq, this.begin)
+    const stop = Math.min(toSeq, this.end)
+    for (let seq = start; seq <= stop; seq++) {
+      this.receivedSeqs.add(seq)
+    }
+  }
+
+  get isFullySatisfied (): boolean {
+    return this.receivedSeqs.size >= (this.end - this.begin + 1)
+  }
+
+  fullyCovers (begin: number, end: number): boolean {
+    return begin >= this.begin && end <= this.end
+  }
+
+  overlaps (begin: number, end: number): boolean {
+    return begin <= this.end && end >= this.begin
+  }
+
+  get pendingCount (): number {
+    return (this.end - this.begin + 1) - this.receivedSeqs.size
+  }
+
+  toString (): string {
+    return `Pending(${this.begin}-${this.end}, received=${this.receivedSeqs.size}/${this.end - this.begin + 1})`
+  }
+}
+
+export interface ResendRequestRecord {
+  begin: number
+  end: number
+  sentAt: Date
+  reason: string | null
+}
+
+export interface ResendManagerConfig {
+  maxPendingRequests?: number
+  maxRequestsPerWindow?: number
+  rateLimitWindowSeconds?: number
+  requestTimeoutSeconds?: number
+}
+
+/**
+ * Manages ResendRequest strategy with intelligent overlap handling and storm protection.
+ *
+ * Philosophy:
+ * 1. Stay alive — don't let resend handling crash or overwhelm the session
+ * 2. Keep receiving new messages — don't block normal message flow
+ * 3. Don't make things worse — avoid storms, handle overlaps intelligently
+ */
+export class ResendRequestManager {
+  private readonly pendingRequests: PendingResendRange[] = []
+  private readonly requestHistory: ResendRequestRecord[] = []
+  private readonly maxPendingRequests: number
+  private readonly maxRequestsPerWindow: number
+  private readonly rateLimitWindowMs: number
+  private readonly requestTimeoutMs: number
+  private readonly recentRequestTimes: Date[] = []
+
+  constructor (config?: ResendManagerConfig) {
+    this.maxPendingRequests = config?.maxPendingRequests ?? 1
+    this.maxRequestsPerWindow = config?.maxRequestsPerWindow ?? 5
+    this.rateLimitWindowMs = (config?.rateLimitWindowSeconds ?? 10) * 1000
+    this.requestTimeoutMs = (config?.requestTimeoutSeconds ?? 30) * 1000
+  }
+
+  computeAction (expectedSeq: number, receivedSeq: number, now: Date): ResendAction {
+    if (receivedSeq <= expectedSeq) {
+      return ResendAction.nothing()
+    }
+
+    const gapBegin = expectedSeq
+    const gapEnd = receivedSeq - 1
+
+    this.cleanupTimedOutRequests(now)
+
+    if (this.isStorming(now)) {
+      return ResendAction.gapFill(gapBegin, gapEnd, 'storm protection - too many requests')
+    }
+
+    for (const pending of this.pendingRequests) {
+      if (pending.fullyCovers(gapBegin, gapEnd)) {
+        return ResendAction.wait(`fully covered by pending request ${pending}`)
+      }
+    }
+
+    const uncovered = this.computeUncoveredRange(gapBegin, gapEnd)
+    if (!uncovered) {
+      return ResendAction.wait('gap partially covered, waiting for pending requests')
+    }
+
+    if (this.pendingRequests.length >= this.maxPendingRequests) {
+      return ResendAction.wait(`max pending requests (${this.maxPendingRequests}) reached`)
+    }
+
+    return ResendAction.sendResendRequest(uncovered.begin, uncovered.end)
+  }
+
+  recordRequestSent (begin: number, end: number, now: Date, reason: string | null = null): void {
+    this.pendingRequests.push(new PendingResendRange(begin, end, now))
+    this.requestHistory.push({ begin, end, sentAt: now, reason })
+    this.recentRequestTimes.push(now)
+  }
+
+  onMessageReceived (seqNum: number, possDupFlag: boolean, now: Date): void {
+    for (const pending of this.pendingRequests) {
+      pending.markReceived(seqNum)
+    }
+    this.removeFullySatisfied()
+  }
+
+  onGapFillReceived (gapFillSeq: number, newSeqNo: number, now: Date): void {
+    for (const pending of this.pendingRequests) {
+      pending.markRangeReceived(gapFillSeq, newSeqNo - 1)
+    }
+    this.removeFullySatisfied()
+  }
+
+  tick (now: Date): void {
+    this.cleanupTimedOutRequests(now)
+    this.cleanupRateLimitWindow(now)
+  }
+
+  reset (): void {
+    this.pendingRequests.length = 0
+    this.recentRequestTimes.length = 0
+    // keep requestHistory for debugging
+  }
+
+  get pending (): ReadonlyArray<PendingResendRange> {
+    return this.pendingRequests.slice()
+  }
+
+  get history (): ReadonlyArray<ResendRequestRecord> {
+    return this.requestHistory.slice()
+  }
+
+  get pendingCount (): number {
+    return this.pendingRequests.length
+  }
+
+  get hasPendingRequests (): boolean {
+    return this.pendingRequests.length > 0
+  }
+
+  private isStorming (now: Date): boolean {
+    this.cleanupRateLimitWindow(now)
+    return this.recentRequestTimes.length >= this.maxRequestsPerWindow
+  }
+
+  private cleanupRateLimitWindow (now: Date): void {
+    const cutoff = now.getTime() - this.rateLimitWindowMs
+    while (this.recentRequestTimes.length > 0 && this.recentRequestTimes[0].getTime() < cutoff) {
+      this.recentRequestTimes.shift()
+    }
+  }
+
+  private cleanupTimedOutRequests (now: Date): void {
+    const cutoff = now.getTime() - this.requestTimeoutMs
+    for (let i = this.pendingRequests.length - 1; i >= 0; i--) {
+      if (this.pendingRequests[i].sentAt.getTime() < cutoff) {
+        this.pendingRequests.splice(i, 1)
+      }
+    }
+  }
+
+  private removeFullySatisfied (): void {
+    for (let i = this.pendingRequests.length - 1; i >= 0; i--) {
+      if (this.pendingRequests[i].isFullySatisfied) {
+        this.pendingRequests.splice(i, 1)
+      }
+    }
+  }
+
+  private computeUncoveredRange (gapBegin: number, gapEnd: number): { begin: number, end: number } | null {
+    if (this.pendingRequests.length === 0) {
+      return { begin: gapBegin, end: gapEnd }
+    }
+
+    const covered: Set<number> = new Set()
+    for (const pending of this.pendingRequests) {
+      for (let seq = pending.begin; seq <= pending.end; seq++) {
+        covered.add(seq)
+      }
+    }
+
+    let uncoveredBegin: number | null = null
+    let uncoveredEnd: number | null = null
+
+    for (let seq = gapBegin; seq <= gapEnd; seq++) {
+      if (!covered.has(seq)) {
+        if (uncoveredBegin === null) uncoveredBegin = seq
+        uncoveredEnd = seq
+      } else if (uncoveredBegin !== null) {
+        break
+      }
+    }
+
+    if (uncoveredBegin !== null && uncoveredEnd !== null) {
+      return { begin: uncoveredBegin, end: uncoveredEnd }
+    }
+
+    return null
+  }
+}

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

@@ -1,4 +1,5 @@
 import { IMsgApplication } from '../msg-application'
+import { StoreConfig } from '../../store/store-config'
 
 export interface IDynamicSessionParams {
   readonly Name: string
@@ -18,4 +19,5 @@ export interface ISessionDescription extends IDynamicSessionParams {
   LastSentSeqNum?: number
   readonly LastReceivedSeqNum?: number
   readonly BodyLengthChars?: number
+  readonly store?: StoreConfig
 }

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

@@ -11,6 +11,6 @@ export interface ISessionMsgFactory {
   resendRequest: (from: number, to: number) => ILooseObject
   sequenceReset: (newSeq: number, gapFill?: boolean) => ILooseObject
   heartbeat: (testReqId: string) => ILooseObject
-  header: (msgType?: string, seqNum?: number, time?: Date, overrideData?: Partial<IStandardHeader>) => ILooseObject
+  header: (msgType: string, seqNum: number, time: Date, overrideData?: Partial<IStandardHeader>) => ILooseObject
   trailer: (checksum: number) => ILooseObject
 }

package/src/transport/session/session-sequence-coordinator.ts

@@ -0,0 +1,272 @@
+import { ISessionSequenceStore } from './session-sequence-store'
+import { IFixClock } from './fix-clock'
+import { ResendAction, ResendManagerConfig, ResendRequestManager, PendingResendRange } from './resend-request-manager'
+
+/**
+ * Coordinates all sequence-related state for a FIX session.
+ *
+ * This is the SINGLE SOURCE OF TRUTH for:
+ * - Outgoing sequence numbers (what we send)
+ * - Expected incoming sequence numbers (what we expect from peer)
+ * - Resend request tracking
+ * - Reset coordination
+ *
+ * Philosophy:
+ * 1. All sequence state lives here — no scattered state across components
+ * 2. All reset operations are coordinated through here
+ * 3. Components query this for sequence numbers, don't maintain their own
+ * 4. Fully testable without running actual sessions
+ */
+export class SessionSequenceCoordinator {
+  private readonly store: ISessionSequenceStore
+  private readonly resendManager: ResendRequestManager
+  private readonly clock: IFixClock
+
+  // THE source of truth for sequence numbers
+  private nextSenderSeqNumValue: number = 1
+  private expectedTargetSeqNumValue: number = 1
+
+  // Track the last peer sequence we actually processed
+  private lastProcessedPeerSeqNumValue: number = 0
+
+  // Transient session state (reset on reconnect)
+  private logonRetryCountValue: number = 0
+  private timeoutRecoveryAttemptsValue: number = 0
+
+  // Event callback for full session reset
+  public onSessionReset: (() => Promise<void>) | null = null
+
+  constructor (
+    store: ISessionSequenceStore,
+    clock: IFixClock,
+    resendManagerConfig?: ResendManagerConfig
+  ) {
+    this.store = store
+    this.clock = clock
+    this.resendManager = new ResendRequestManager(resendManagerConfig)
+  }
+
+  // ── Initialization ──
+
+  initializeFromStore (): void {
+    this.nextSenderSeqNumValue = this.store.senderSeqNum
+    this.expectedTargetSeqNumValue = this.store.targetSeqNum
+    this.lastProcessedPeerSeqNumValue = this.expectedTargetSeqNumValue - 1
+  }
+
+  initializeFromConfig (senderSeqNum?: number, targetSeqNum?: number): void {
+    if (senderSeqNum !== undefined) {
+      this.nextSenderSeqNumValue = senderSeqNum
+    }
+    if (targetSeqNum !== undefined) {
+      this.expectedTargetSeqNumValue = targetSeqNum
+      this.lastProcessedPeerSeqNumValue = targetSeqNum - 1
+    }
+  }
+
+  // ── Sequence Access (Read) ──
+
+  get nextSenderSeqNum (): number {
+    return this.nextSenderSeqNumValue
+  }
+
+  get expectedTargetSeqNum (): number {
+    return this.expectedTargetSeqNumValue
+  }
+
+  get lastProcessedPeerSeqNum (): number {
+    return this.lastProcessedPeerSeqNumValue
+  }
+
+  // ── Sequence Mutations (Controlled) ──
+
+  /**
+   * Consumes and returns the next sender sequence number.
+   * Call when encoding a message (not for PossDup resends).
+   */
+  getNextSenderSeqNum (isPossDup: boolean = false): number {
+    const seq = this.nextSenderSeqNumValue
+    if (!isPossDup) {
+      this.nextSenderSeqNumValue++
+    }
+    return seq
+  }
+
+  /**
+   * Records that a message was successfully encoded and will be sent.
+   * Updates the store's sender sequence number.
+   */
+  async onMessageEncoded (seqNum: number, isPossDup: boolean): Promise<void> {
+    if (isPossDup) return
+    await this.store.setSenderSeqNum(seqNum + 1)
+  }
+
+  /**
+   * Called when a message is received from the peer.
+   * Updates expected sequence and resend tracking.
+   * Returns true if message should be processed, false if duplicate/old.
+   */
+  async onMessageReceived (seqNum: number, possDupFlag: boolean): Promise<boolean> {
+    const now = this.clock.now()
+
+    this.resendManager.onMessageReceived(seqNum, possDupFlag, now)
+
+    if (possDupFlag) {
+      return true
+    }
+
+    if (seqNum < this.expectedTargetSeqNumValue) {
+      return false
+    }
+
+    if (seqNum === this.expectedTargetSeqNumValue) {
+      this.lastProcessedPeerSeqNumValue = seqNum
+      this.expectedTargetSeqNumValue = seqNum + 1
+    } else if (seqNum > this.expectedTargetSeqNumValue) {
+      // Gap detected — session accepts this message and moves on
+      this.lastProcessedPeerSeqNumValue = seqNum
+      this.expectedTargetSeqNumValue = seqNum + 1
+    }
+
+    await this.store.setTargetSeqNum(this.expectedTargetSeqNumValue)
+    return true
+  }
+
+  /**
+   * Called when a SequenceReset-GapFill is received.
+   */
+  async onGapFillReceived (gapFillSeq: number, newSeqNo: number): Promise<void> {
+    const now = this.clock.now()
+    this.resendManager.onGapFillReceived(gapFillSeq, newSeqNo, now)
+
+    // GapFill says "skip from gapFillSeq to newSeqNo" — never rewind
+    if (newSeqNo > this.expectedTargetSeqNumValue) {
+      this.expectedTargetSeqNumValue = newSeqNo
+      this.lastProcessedPeerSeqNumValue = Math.max(this.lastProcessedPeerSeqNumValue, newSeqNo - 1)
+    }
+
+    await this.store.setTargetSeqNum(this.expectedTargetSeqNumValue)
+  }
+
+  // ── Gap Detection and Resend Requests ──
+
+  onGapDetected (expectedSeq: number, receivedSeq: number): ResendAction {
+    const now = this.clock.now()
+    return this.resendManager.computeAction(expectedSeq, receivedSeq, now)
+  }
+
+  recordResendRequestSent (begin: number, end: number): void {
+    const now = this.clock.now()
+    this.resendManager.recordRequestSent(begin, end, now)
+  }
+
+  get pendingResendRequests (): ReadonlyArray<PendingResendRange> {
+    return this.resendManager.pending
+  }
+
+  // ── Logon Retry Logic ──
+
+  onLogonRejectedForSequence (maxRetries: number = 10): boolean {
+    this.logonRetryCountValue++
+    if (this.logonRetryCountValue <= maxRetries) {
+      this.nextSenderSeqNumValue++
+      return true
+    }
+    return false
+  }
+
+  resetLogonRetryCount (): void {
+    this.logonRetryCountValue = 0
+  }
+
+  get logonRetryCount (): number {
+    return this.logonRetryCountValue
+  }
+
+  // ── Timeout Recovery ──
+
+  incrementTimeoutRecovery (maxAttempts: number = 3): boolean {
+    this.timeoutRecoveryAttemptsValue++
+    return this.timeoutRecoveryAttemptsValue <= maxAttempts
+  }
+
+  resetTimeoutRecovery (): void {
+    this.timeoutRecoveryAttemptsValue = 0
+  }
+
+  get timeoutRecoveryAttempts (): number {
+    return this.timeoutRecoveryAttemptsValue
+  }
+
+  // ── Reset Operations ──
+
+  /**
+   * Prepares for reconnection on the same session.
+   * Resets transient state but preserves sequence numbers.
+   */
+  prepareForReconnect (): void {
+    this.logonRetryCountValue = 0
+    this.timeoutRecoveryAttemptsValue = 0
+    this.resendManager.reset()
+  }
+
+  /**
+   * Full session reset — clears store, resets sequences to 1.
+   * Call when ResetSeqNumFlag=Y is being used.
+   */
+  async resetSession (reason: string): Promise<void> {
+    this.nextSenderSeqNumValue = 1
+    this.expectedTargetSeqNumValue = 1
+    this.lastProcessedPeerSeqNumValue = 0
+    this.logonRetryCountValue = 0
+    this.timeoutRecoveryAttemptsValue = 0
+    this.resendManager.reset()
+
+    await this.store.reset()
+
+    if (this.onSessionReset) {
+      await this.onSessionReset()
+    }
+  }
+
+  /**
+   * Handles peer's ResetSeqNumFlag=Y in their Logon.
+   */
+  async handlePeerReset (peerSeqNum: number, weAlsoReset: boolean): Promise<void> {
+    const savedSenderSeq = weAlsoReset ? this.nextSenderSeqNumValue : null
+
+    await this.store.reset()
+
+    this.nextSenderSeqNumValue = savedSenderSeq ?? this.store.senderSeqNum
+    this.expectedTargetSeqNumValue = peerSeqNum + 1
+    this.lastProcessedPeerSeqNumValue = peerSeqNum
+    this.resendManager.reset()
+
+    await this.store.setTargetSeqNum(this.expectedTargetSeqNumValue)
+
+    if (this.onSessionReset) {
+      await this.onSessionReset()
+    }
+  }
+
+  /**
+   * Handles acceptor responding with ResetSeqNumFlag=Y when peer didn't request it.
+   */
+  async resetAsAcceptor (): Promise<void> {
+    this.nextSenderSeqNumValue = 1
+    this.expectedTargetSeqNumValue = 1
+    this.lastProcessedPeerSeqNumValue = 0
+    this.resendManager.reset()
+
+    await this.store.reset()
+    await this.store.setTargetSeqNum(1)
+  }
+
+  /**
+   * Periodic tick — cleans up stale resend requests.
+   */
+  tick (): void {
+    const now = this.clock.now()
+    this.resendManager.tick(now)
+  }
+}

package/src/transport/session/session-sequence-store.ts

@@ -0,0 +1,33 @@
+/**
+ * Minimal store interface for the SessionSequenceCoordinator.
+ * Both the existing FixMsgMemoryStore (adapted) and the future
+ * IFixSessionStore will implement this.
+ */
+export interface ISessionSequenceStore {
+  senderSeqNum: number
+  targetSeqNum: number
+  setSenderSeqNum (value: number): Promise<void>
+  setTargetSeqNum (value: number): Promise<void>
+  reset (): Promise<void>
+}
+
+/**
+ * Simple in-memory implementation for testing and as default.
+ */
+export class MemorySequenceStore implements ISessionSequenceStore {
+  public senderSeqNum: number = 1
+  public targetSeqNum: number = 1
+
+  async setSenderSeqNum (value: number): Promise<void> {
+    this.senderSeqNum = value
+  }
+
+  async setTargetSeqNum (value: number): Promise<void> {
+    this.targetSeqNum = value
+  }
+
+  async reset (): Promise<void> {
+    this.senderSeqNum = 1
+    this.targetSeqNum = 1
+  }
+}

package/src/transport/tcp/tcp-acceptor.ts

@@ -55,7 +55,7 @@ export class TcpAcceptor extends FixAcceptor {
         }
       })
     } catch (e) {
-      this.logger.error(e)
+      this.logger.error(e as Error)
       throw e
     }
   }
@@ -71,7 +71,7 @@ export class TcpAcceptor extends FixAcceptor {
         this.onSocket(id, socket, config)
       })
     } catch (e) {
-      this.logger.error(e)
+      this.logger.error(e as Error)
       throw e
     }
   }