Skip to main content

of_fix/
session.rs

1//! Deterministic, transport-independent FIX session coordination.
2
3use std::error::Error;
4use std::fmt;
5
6use crate::{
7    encode_heartbeat, encode_logon, encode_logout, encode_resend_request, encode_test_request,
8    FixEncodeError, FixMessageView, FixMsgType, FixOwnedSessionId, FixResendRange,
9    FixSequenceAction, FixSequenceError, FixSequenceTracker, FixSessionHeader, FixSessionState,
10    FixTag,
11};
12
13const NANOS_PER_SECOND: u64 = 1_000_000_000;
14const TEST_REQUEST_ID_CAPACITY: usize = 32;
15const TEST_REQUEST_PREFIX: &[u8] = b"OF-TEST-";
16
17/// Configuration for a deterministic FIX session engine.
18///
19/// The engine owns protocol state but not a socket, TLS implementation, clock,
20/// scheduler, or persistence backend. Hosts inject timestamps and transmit the
21/// caller-owned output buffer returned by each action.
22#[derive(Debug, Clone, Copy, PartialEq, Eq)]
23#[non_exhaustive]
24pub struct FixSessionEngineConfig {
25    heartbeat_interval_secs: u32,
26    heartbeat_interval_ns: u64,
27    test_request_after_ns: u64,
28    disconnect_after_test_request_ns: u64,
29    logout_timeout_ns: u64,
30    reset_seq_num_on_logon: bool,
31    validate_comp_ids: bool,
32}
33
34impl FixSessionEngineConfig {
35    /// Creates a session configuration from the negotiated heartbeat interval.
36    ///
37    /// By default the engine sends a TestRequest after 1.5 heartbeat intervals
38    /// without inbound traffic and requests disconnect one heartbeat interval
39    /// after an unanswered TestRequest. Logout uses the same one-heartbeat
40    /// timeout.
41    ///
42    /// # Errors
43    ///
44    /// Returns [`FixSessionConfigError`] when the interval is zero or cannot be
45    /// represented in nanoseconds.
46    pub fn new(heartbeat_interval_secs: u32) -> Result<Self, FixSessionConfigError> {
47        let heartbeat_interval_ns = u64::from(heartbeat_interval_secs)
48            .checked_mul(NANOS_PER_SECOND)
49            .ok_or(FixSessionConfigError::DurationOverflow)?;
50        if heartbeat_interval_ns == 0 {
51            return Err(FixSessionConfigError::ZeroHeartbeatInterval);
52        }
53        let half = heartbeat_interval_ns / 2;
54        let test_request_after_ns = heartbeat_interval_ns
55            .checked_add(half)
56            .ok_or(FixSessionConfigError::DurationOverflow)?;
57        let disconnect_after_test_request_ns = heartbeat_interval_ns;
58        Ok(Self {
59            heartbeat_interval_secs,
60            heartbeat_interval_ns,
61            test_request_after_ns,
62            disconnect_after_test_request_ns,
63            logout_timeout_ns: heartbeat_interval_ns,
64            reset_seq_num_on_logon: false,
65            validate_comp_ids: true,
66        })
67    }
68
69    /// Overrides liveness and logout durations in nanoseconds.
70    ///
71    /// `test_request_after_ns` is measured from the latest inbound frame.
72    /// `disconnect_after_test_request_ns` is measured from the TestRequest send
73    /// time. All durations must be non-zero.
74    ///
75    /// # Errors
76    ///
77    /// Returns [`FixSessionConfigError`] when any duration is zero.
78    pub fn with_timeouts(
79        mut self,
80        test_request_after_ns: u64,
81        disconnect_after_test_request_ns: u64,
82        logout_timeout_ns: u64,
83    ) -> Result<Self, FixSessionConfigError> {
84        if test_request_after_ns == 0 {
85            return Err(FixSessionConfigError::ZeroTestRequestTimeout);
86        }
87        if disconnect_after_test_request_ns == 0 {
88            return Err(FixSessionConfigError::ZeroDisconnectTimeout);
89        }
90        if logout_timeout_ns == 0 {
91            return Err(FixSessionConfigError::ZeroLogoutTimeout);
92        }
93        self.test_request_after_ns = test_request_after_ns;
94        self.disconnect_after_test_request_ns = disconnect_after_test_request_ns;
95        self.logout_timeout_ns = logout_timeout_ns;
96        Ok(self)
97    }
98
99    /// Configures whether the next connection sends `ResetSeqNumFlag(141)=Y`.
100    ///
101    /// When enabled, both local counters are reset to one immediately before
102    /// the Logon sequence is assigned. This must only be enabled under an
103    /// explicit bilateral session-reset agreement.
104    pub const fn with_reset_seq_num_on_logon(mut self, enabled: bool) -> Self {
105        self.reset_seq_num_on_logon = enabled;
106        self
107    }
108
109    /// Configures strict sender/target component-id validation.
110    ///
111    /// Validation is enabled by default. Disabling it is intended only for
112    /// gateways whose authenticated transport rewrites component identifiers.
113    pub const fn with_comp_id_validation(mut self, enabled: bool) -> Self {
114        self.validate_comp_ids = enabled;
115        self
116    }
117
118    /// Returns the negotiated `HeartBtInt(108)` value in seconds.
119    pub const fn heartbeat_interval_secs(&self) -> u32 {
120        self.heartbeat_interval_secs
121    }
122
123    /// Returns the outbound-heartbeat idle duration in nanoseconds.
124    pub const fn heartbeat_interval_ns(&self) -> u64 {
125        self.heartbeat_interval_ns
126    }
127
128    /// Returns the inbound-idle duration before a TestRequest is sent.
129    pub const fn test_request_after_ns(&self) -> u64 {
130        self.test_request_after_ns
131    }
132
133    /// Returns the unanswered-TestRequest duration before disconnect is
134    /// requested.
135    pub const fn disconnect_after_test_request_ns(&self) -> u64 {
136        self.disconnect_after_test_request_ns
137    }
138
139    /// Returns the Logout response timeout in nanoseconds.
140    pub const fn logout_timeout_ns(&self) -> u64 {
141        self.logout_timeout_ns
142    }
143
144    /// Returns whether Logon requests a bilateral sequence reset.
145    pub const fn reset_seq_num_on_logon(&self) -> bool {
146        self.reset_seq_num_on_logon
147    }
148
149    /// Returns whether inbound component identifiers are validated.
150    pub const fn validate_comp_ids(&self) -> bool {
151        self.validate_comp_ids
152    }
153}
154
155/// Invalid FIX session-engine configuration.
156#[derive(Debug, Clone, Copy, PartialEq, Eq)]
157#[non_exhaustive]
158pub enum FixSessionConfigError {
159    /// `HeartBtInt` was zero.
160    ZeroHeartbeatInterval,
161    /// The TestRequest idle timeout was zero.
162    ZeroTestRequestTimeout,
163    /// The unanswered-TestRequest timeout was zero.
164    ZeroDisconnectTimeout,
165    /// The Logout timeout was zero.
166    ZeroLogoutTimeout,
167    /// A seconds-to-nanoseconds conversion overflowed.
168    DurationOverflow,
169}
170
171impl fmt::Display for FixSessionConfigError {
172    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
173        match self {
174            Self::ZeroHeartbeatInterval => f.write_str("FIX heartbeat interval must be non-zero"),
175            Self::ZeroTestRequestTimeout => {
176                f.write_str("FIX TestRequest idle timeout must be non-zero")
177            }
178            Self::ZeroDisconnectTimeout => {
179                f.write_str("FIX TestRequest disconnect timeout must be non-zero")
180            }
181            Self::ZeroLogoutTimeout => f.write_str("FIX Logout timeout must be non-zero"),
182            Self::DurationOverflow => f.write_str("FIX session duration overflow"),
183        }
184    }
185}
186
187impl Error for FixSessionConfigError {}
188
189/// Administrative message kind emitted into the caller-owned output buffer.
190#[derive(Debug, Clone, Copy, PartialEq, Eq)]
191#[non_exhaustive]
192pub enum FixSessionSendKind {
193    /// Logon `<A>`.
194    Logon,
195    /// Heartbeat `<0>`.
196    Heartbeat,
197    /// TestRequest `<1>`.
198    TestRequest,
199    /// ResendRequest `<2>`.
200    ResendRequest,
201    /// Logout `<5>`.
202    Logout,
203}
204
205/// Reason the session asks its host to close the transport.
206#[derive(Debug, Clone, Copy, PartialEq, Eq)]
207#[non_exhaustive]
208pub enum FixSessionDisconnectReason {
209    /// A TestRequest was not answered within the configured timeout.
210    HeartbeatTimeout,
211    /// A Logout handshake did not complete before its timeout.
212    LogoutTimeout,
213    /// The peer acknowledged a locally initiated Logout.
214    PeerLogout,
215}
216
217/// Deterministic action produced by a FIX session-engine call.
218///
219/// `Send` and `GapDetected` actions populate the mutable output buffer supplied
220/// to the call. The host must persist/transmit those bytes before invoking the
221/// next mutating session operation.
222#[derive(Debug, Clone, Copy, PartialEq, Eq)]
223#[non_exhaustive]
224pub enum FixSessionAction {
225    /// No protocol action is currently due.
226    None,
227    /// An administrative frame was encoded for transmission.
228    Send {
229        /// Encoded administrative message kind.
230        kind: FixSessionSendKind,
231        /// Outbound FIX sequence number in the encoded frame.
232        sequence: u64,
233    },
234    /// Peer Logon was accepted and application flow may begin.
235    Ready {
236        /// Inbound Logon sequence number.
237        sequence: u64,
238    },
239    /// An application message passed session validation.
240    Application {
241        /// Accepted inbound sequence number.
242        sequence: u64,
243    },
244    /// A possible duplicate was observed below the current inbound horizon.
245    Duplicate {
246        /// Duplicate sequence number.
247        sequence: u64,
248        /// Next inbound sequence expected by the session.
249        expected: u64,
250    },
251    /// An inbound gap caused a ResendRequest to be encoded.
252    GapDetected {
253        /// Out-of-order inbound sequence that exposed the gap.
254        received: u64,
255        /// Missing inbound range requested from the peer.
256        range: FixResendRange,
257        /// Sequence number assigned to the outbound ResendRequest.
258        request_sequence: u64,
259    },
260    /// The peer requested replay or gap-fill for an outbound range.
261    PeerResendRequested {
262        /// Inbound ResendRequest sequence number.
263        sequence: u64,
264        /// Requested outbound sequence range. `end_seq_no == 0` means current
265        /// end of retained history.
266        range: FixResendRange,
267    },
268    /// A SequenceReset was applied to the inbound horizon.
269    SequenceReset {
270        /// Inbound SequenceReset message sequence number.
271        sequence: u64,
272        /// New next inbound sequence number.
273        next_inbound: u64,
274    },
275    /// A non-flow administrative message was accepted.
276    Administrative {
277        /// Accepted inbound sequence number.
278        sequence: u64,
279        /// Known administrative message kind.
280        message_type: FixMsgType,
281    },
282    /// The host should close the transport.
283    Disconnect {
284        /// Protocol reason for the disconnect request.
285        reason: FixSessionDisconnectReason,
286    },
287}
288
289/// Allocation-free FIX session counters and timing snapshot.
290#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
291#[non_exhaustive]
292pub struct FixSessionMetrics {
293    /// Transport connections that reached Logon emission.
294    pub connections: u64,
295    /// Transport disconnect notifications.
296    pub disconnects: u64,
297    /// Accepted inbound frames, including administrative frames.
298    pub inbound_messages: u64,
299    /// Newly sequenced outbound frames.
300    pub outbound_messages: u64,
301    /// Accepted inbound application frames.
302    pub inbound_application_messages: u64,
303    /// Assigned outbound application frames.
304    pub outbound_application_messages: u64,
305    /// Inbound sequence gaps.
306    pub sequence_gaps: u64,
307    /// Possible-duplicate inbound frames.
308    pub duplicate_messages: u64,
309    /// Unflagged inbound sequence regressions.
310    pub sequence_too_low: u64,
311    /// ResendRequests sent after inbound gaps.
312    pub resend_requests_sent: u64,
313    /// ResendRequests accepted from the peer.
314    pub resend_requests_received: u64,
315    /// Heartbeats sent, including TestRequest responses.
316    pub heartbeats_sent: u64,
317    /// Heartbeats accepted from the peer.
318    pub heartbeats_received: u64,
319    /// TestRequests sent by the liveness timer.
320    pub test_requests_sent: u64,
321    /// TestRequests accepted from the peer.
322    pub test_requests_received: u64,
323    /// Logon messages sent.
324    pub logons_sent: u64,
325    /// Logon messages accepted.
326    pub logons_received: u64,
327    /// Logout messages sent.
328    pub logouts_sent: u64,
329    /// Logout messages accepted.
330    pub logouts_received: u64,
331    /// Liveness or Logout timeout disconnect requests.
332    pub timeout_disconnects: u64,
333    /// Latest accepted/observed inbound timestamp.
334    pub last_inbound_ns: Option<u64>,
335    /// Latest newly sequenced outbound timestamp.
336    pub last_outbound_ns: Option<u64>,
337}
338
339/// FIX session protocol and state-machine errors.
340#[derive(Debug, Clone, PartialEq, Eq)]
341#[non_exhaustive]
342pub enum FixSessionError {
343    /// Operation is invalid in the current lifecycle state.
344    InvalidState {
345        /// Attempted operation name.
346        operation: &'static str,
347        /// Current state.
348        state: FixSessionState,
349    },
350    /// A caller-supplied timestamp moved backwards.
351    TimestampRegression {
352        /// Latest timestamp previously observed.
353        previous_ns: u64,
354        /// Regressing timestamp.
355        observed_ns: u64,
356    },
357    /// A required session tag was absent.
358    MissingTag(FixTag),
359    /// A required numeric session tag was malformed or overflowed.
360    MalformedNumericTag(FixTag),
361    /// Inbound begin string did not match the configured session.
362    VersionMismatch,
363    /// Inbound sender component id did not match the configured target.
364    SenderCompIdMismatch,
365    /// Inbound target component id did not match the configured sender.
366    TargetCompIdMismatch,
367    /// Peer Logon used a different heartbeat interval.
368    HeartbeatIntervalMismatch {
369        /// Locally configured interval in seconds.
370        expected: u32,
371        /// Peer-provided interval in seconds.
372        received: u64,
373    },
374    /// Peer requested a sequence reset without a bilateral reset policy.
375    UnexpectedResetSeqNumFlag,
376    /// An inbound sequence regressed without `PossDupFlag(43)=Y`.
377    SequenceTooLow {
378        /// Current expected inbound sequence.
379        expected: u64,
380        /// Received sequence.
381        received: u64,
382    },
383    /// A ResendRequest range was malformed.
384    InvalidResendRange {
385        /// Requested beginning sequence.
386        begin_seq_no: u64,
387        /// Requested ending sequence.
388        end_seq_no: u64,
389    },
390    /// A heartbeat did not echo the outstanding TestReqID.
391    TestRequestIdMismatch,
392    /// Application flow arrived outside a ready/recovery state.
393    UnexpectedApplicationMessage,
394    /// FIX message encoding failed.
395    Encode(FixEncodeError),
396    /// FIX sequence validation failed.
397    Sequence(FixSequenceError),
398}
399
400impl fmt::Display for FixSessionError {
401    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
402        match self {
403            Self::InvalidState { operation, state } => {
404                write!(
405                    f,
406                    "FIX session operation {operation} is invalid in state {state:?}"
407                )
408            }
409            Self::TimestampRegression {
410                previous_ns,
411                observed_ns,
412            } => write!(
413                f,
414                "FIX session timestamp regressed from {previous_ns} to {observed_ns}"
415            ),
416            Self::MissingTag(tag) => write!(f, "FIX session message is missing tag {tag}"),
417            Self::MalformedNumericTag(tag) => {
418                write!(f, "FIX session tag {tag} is not a valid unsigned integer")
419            }
420            Self::VersionMismatch => f.write_str("FIX session begin string mismatch"),
421            Self::SenderCompIdMismatch => f.write_str("FIX session SenderCompID mismatch"),
422            Self::TargetCompIdMismatch => f.write_str("FIX session TargetCompID mismatch"),
423            Self::HeartbeatIntervalMismatch { expected, received } => write!(
424                f,
425                "FIX HeartBtInt mismatch: expected {expected}, received {received}"
426            ),
427            Self::UnexpectedResetSeqNumFlag => {
428                f.write_str("FIX peer requested an unconfigured sequence reset")
429            }
430            Self::SequenceTooLow { expected, received } => write!(
431                f,
432                "FIX inbound sequence {received} is below expected {expected} without PossDupFlag"
433            ),
434            Self::InvalidResendRange {
435                begin_seq_no,
436                end_seq_no,
437            } => write!(f, "invalid FIX resend range {begin_seq_no}..={end_seq_no}"),
438            Self::TestRequestIdMismatch => f.write_str("FIX Heartbeat TestReqID mismatch"),
439            Self::UnexpectedApplicationMessage => {
440                f.write_str("FIX application message arrived before session readiness")
441            }
442            Self::Encode(error) => write!(f, "FIX session encode error: {error}"),
443            Self::Sequence(error) => write!(f, "FIX session sequence error: {error}"),
444        }
445    }
446}
447
448impl Error for FixSessionError {
449    fn source(&self) -> Option<&(dyn Error + 'static)> {
450        match self {
451            Self::Encode(error) => Some(error),
452            Self::Sequence(error) => Some(error),
453            _ => None,
454        }
455    }
456}
457
458impl From<FixEncodeError> for FixSessionError {
459    fn from(value: FixEncodeError) -> Self {
460        Self::Encode(value)
461    }
462}
463
464impl From<FixSequenceError> for FixSessionError {
465    fn from(value: FixSequenceError) -> Self {
466        Self::Sequence(value)
467    }
468}
469
470#[derive(Debug, Clone, Copy, PartialEq, Eq)]
471struct PendingTestRequest {
472    bytes: [u8; TEST_REQUEST_ID_CAPACITY],
473    len: u8,
474    sent_ns: u64,
475}
476
477impl PendingTestRequest {
478    fn id(&self) -> &[u8] {
479        &self.bytes[..usize::from(self.len)]
480    }
481}
482
483/// Single-owner deterministic FIX session state machine.
484///
485/// The engine performs no network, filesystem, wall-clock, thread, or async
486/// operations. It reuses caller-owned output buffers and stores its outstanding
487/// TestReqID inline. External synchronization is required if multiple threads
488/// access one instance.
489#[derive(Debug, Clone)]
490pub struct FixSessionEngine {
491    config: FixSessionEngineConfig,
492    session_id: FixOwnedSessionId,
493    sequences: FixSequenceTracker,
494    state: FixSessionState,
495    metrics: FixSessionMetrics,
496    last_observed_ns: Option<u64>,
497    pending_test_request: Option<PendingTestRequest>,
498    next_test_request_id: u64,
499    logout_sent_ns: Option<u64>,
500    recovery_target: Option<u64>,
501    disconnect_requested: bool,
502}
503
504impl FixSessionEngine {
505    /// Creates a disconnected session with sequence numbers starting at one.
506    pub fn new(config: FixSessionEngineConfig, session_id: FixOwnedSessionId) -> Self {
507        Self::with_sequences(config, session_id, FixSequenceTracker::new())
508    }
509
510    /// Creates a disconnected session from restored sequence counters.
511    pub fn with_sequences(
512        config: FixSessionEngineConfig,
513        session_id: FixOwnedSessionId,
514        sequences: FixSequenceTracker,
515    ) -> Self {
516        Self {
517            config,
518            session_id,
519            sequences,
520            state: FixSessionState::Disconnected,
521            metrics: FixSessionMetrics::default(),
522            last_observed_ns: None,
523            pending_test_request: None,
524            next_test_request_id: 1,
525            logout_sent_ns: None,
526            recovery_target: None,
527            disconnect_requested: false,
528        }
529    }
530
531    /// Returns immutable session configuration.
532    pub const fn config(&self) -> &FixSessionEngineConfig {
533        &self.config
534    }
535
536    /// Returns the owned session identity.
537    pub const fn session_id(&self) -> &FixOwnedSessionId {
538        &self.session_id
539    }
540
541    /// Returns current lifecycle state.
542    pub const fn state(&self) -> FixSessionState {
543        self.state
544    }
545
546    /// Returns current sequence counters.
547    pub const fn sequences(&self) -> &FixSequenceTracker {
548        &self.sequences
549    }
550
551    /// Returns an allocation-free metrics snapshot.
552    pub const fn metrics(&self) -> FixSessionMetrics {
553        self.metrics
554    }
555
556    /// Marks the beginning of a transport connection attempt.
557    ///
558    /// # Errors
559    ///
560    /// Returns [`FixSessionError::InvalidState`] unless currently disconnected
561    /// or stopped.
562    pub fn on_transport_connecting(&mut self) -> Result<(), FixSessionError> {
563        match self.state {
564            FixSessionState::Disconnected | FixSessionState::Stopped => {
565                self.state = FixSessionState::Connecting;
566                self.disconnect_requested = false;
567                Ok(())
568            }
569            state => Err(FixSessionError::InvalidState {
570                operation: "transport_connecting",
571                state,
572            }),
573        }
574    }
575
576    /// Encodes Logon after the transport has connected.
577    ///
578    /// `sending_time` is the caller-formatted FIX UTC timestamp. `out` is
579    /// cleared and reused.
580    ///
581    /// # Errors
582    ///
583    /// Returns [`FixSessionError`] for invalid lifecycle/timestamp state or
584    /// encoding failure.
585    pub fn on_transport_connected(
586        &mut self,
587        now_ns: u64,
588        sending_time: &[u8],
589        out: &mut Vec<u8>,
590    ) -> Result<FixSessionAction, FixSessionError> {
591        match self.state {
592            FixSessionState::Disconnected
593            | FixSessionState::Connecting
594            | FixSessionState::Stopped => {}
595            state => {
596                return Err(FixSessionError::InvalidState {
597                    operation: "transport_connected",
598                    state,
599                })
600            }
601        }
602        validate_wire_value(FixTag::SENDING_TIME, sending_time)?;
603        self.observe_time(now_ns)?;
604        if self.config.reset_seq_num_on_logon {
605            self.sequences.reset_to_one();
606        }
607        let sequence = self.sequences.assign_outbound();
608        let header = self.header(sequence, sending_time);
609        encode_logon(
610            out,
611            self.session_id.version(),
612            header,
613            u64::from(self.config.heartbeat_interval_secs),
614            self.config.reset_seq_num_on_logon,
615        )?;
616        self.state = FixSessionState::LogonSent;
617        self.pending_test_request = None;
618        self.logout_sent_ns = None;
619        self.recovery_target = None;
620        self.disconnect_requested = false;
621        self.metrics.connections = self.metrics.connections.saturating_add(1);
622        self.metrics.logons_sent = self.metrics.logons_sent.saturating_add(1);
623        self.mark_outbound(now_ns, false);
624        Ok(FixSessionAction::Send {
625            kind: FixSessionSendKind::Logon,
626            sequence,
627        })
628    }
629
630    /// Records that the transport closed.
631    ///
632    /// This call never rewinds sequence numbers.
633    ///
634    /// # Errors
635    ///
636    /// Returns [`FixSessionError`] if `now_ns` regresses.
637    pub fn on_transport_disconnected(&mut self, now_ns: u64) -> Result<(), FixSessionError> {
638        self.observe_time(now_ns)?;
639        if !matches!(self.state, FixSessionState::Disconnected) {
640            self.metrics.disconnects = self.metrics.disconnects.saturating_add(1);
641        }
642        self.state = FixSessionState::Disconnected;
643        self.pending_test_request = None;
644        self.logout_sent_ns = None;
645        self.recovery_target = None;
646        self.disconnect_requested = false;
647        Ok(())
648    }
649
650    /// Stops the session without emitting Logout.
651    ///
652    /// Use [`FixSessionEngine::request_logout`] for a graceful protocol close.
653    pub fn stop(&mut self) {
654        self.state = FixSessionState::Stopped;
655        self.pending_test_request = None;
656        self.logout_sent_ns = None;
657        self.recovery_target = None;
658        self.disconnect_requested = false;
659    }
660
661    /// Encodes a graceful Logout request.
662    ///
663    /// # Errors
664    ///
665    /// Returns [`FixSessionError`] unless session flow is active, when the
666    /// timestamp regresses, or when text cannot be encoded.
667    pub fn request_logout(
668        &mut self,
669        now_ns: u64,
670        sending_time: &[u8],
671        text: Option<&[u8]>,
672        out: &mut Vec<u8>,
673    ) -> Result<FixSessionAction, FixSessionError> {
674        if !matches!(
675            self.state,
676            FixSessionState::Ready
677                | FixSessionState::ResendRequested
678                | FixSessionState::Recovering
679                | FixSessionState::Degraded
680        ) {
681            return Err(FixSessionError::InvalidState {
682                operation: "request_logout",
683                state: self.state,
684            });
685        }
686        validate_wire_value(FixTag::SENDING_TIME, sending_time)?;
687        if let Some(text) = text {
688            validate_wire_value(FixTag::TEXT, text)?;
689        }
690        self.observe_time(now_ns)?;
691        let sequence = self.sequences.assign_outbound();
692        encode_logout(
693            out,
694            self.session_id.version(),
695            self.header(sequence, sending_time),
696            text,
697        )?;
698        self.state = FixSessionState::LogoutSent;
699        self.logout_sent_ns = Some(now_ns);
700        self.metrics.logouts_sent = self.metrics.logouts_sent.saturating_add(1);
701        self.mark_outbound(now_ns, false);
702        Ok(FixSessionAction::Send {
703            kind: FixSessionSendKind::Logout,
704            sequence,
705        })
706    }
707
708    /// Runs deterministic heartbeat, TestRequest, and Logout timers.
709    ///
710    /// The method reads no clock. The host supplies a monotonic timestamp and a
711    /// separately formatted FIX sending time. At most one frame/action is
712    /// produced per call.
713    ///
714    /// # Errors
715    ///
716    /// Returns [`FixSessionError`] for timestamp regression or encoding failure.
717    pub fn on_timer(
718        &mut self,
719        now_ns: u64,
720        sending_time: &[u8],
721        out: &mut Vec<u8>,
722    ) -> Result<FixSessionAction, FixSessionError> {
723        validate_wire_value(FixTag::SENDING_TIME, sending_time)?;
724        self.observe_time(now_ns)?;
725        if self.disconnect_requested {
726            return Ok(FixSessionAction::None);
727        }
728        if self.state == FixSessionState::LogoutSent {
729            if elapsed_at_least(self.logout_sent_ns, now_ns, self.config.logout_timeout_ns) {
730                self.state = FixSessionState::Degraded;
731                self.disconnect_requested = true;
732                self.metrics.timeout_disconnects =
733                    self.metrics.timeout_disconnects.saturating_add(1);
734                return Ok(FixSessionAction::Disconnect {
735                    reason: FixSessionDisconnectReason::LogoutTimeout,
736                });
737            }
738            return Ok(FixSessionAction::None);
739        }
740        if !matches!(
741            self.state,
742            FixSessionState::Ready | FixSessionState::ResendRequested | FixSessionState::Recovering
743        ) {
744            return Ok(FixSessionAction::None);
745        }
746        if let Some(pending) = self.pending_test_request {
747            if now_ns.saturating_sub(pending.sent_ns)
748                >= self.config.disconnect_after_test_request_ns
749            {
750                self.state = FixSessionState::Degraded;
751                self.disconnect_requested = true;
752                self.metrics.timeout_disconnects =
753                    self.metrics.timeout_disconnects.saturating_add(1);
754                return Ok(FixSessionAction::Disconnect {
755                    reason: FixSessionDisconnectReason::HeartbeatTimeout,
756                });
757            }
758            return Ok(FixSessionAction::None);
759        }
760        if elapsed_at_least(
761            self.metrics.last_inbound_ns,
762            now_ns,
763            self.config.test_request_after_ns,
764        ) {
765            return self.encode_liveness_test(now_ns, sending_time, out);
766        }
767        if elapsed_at_least(
768            self.metrics.last_outbound_ns,
769            now_ns,
770            self.config.heartbeat_interval_ns,
771        ) {
772            let sequence = self.sequences.assign_outbound();
773            encode_heartbeat(
774                out,
775                self.session_id.version(),
776                self.header(sequence, sending_time),
777                None,
778            )?;
779            self.metrics.heartbeats_sent = self.metrics.heartbeats_sent.saturating_add(1);
780            self.mark_outbound(now_ns, false);
781            return Ok(FixSessionAction::Send {
782                kind: FixSessionSendKind::Heartbeat,
783                sequence,
784            });
785        }
786        Ok(FixSessionAction::None)
787    }
788
789    /// Processes one already-decoded inbound FIX frame.
790    ///
791    /// The method validates session identity and sequence before dispatching
792    /// administrative behavior. It never buffers out-of-order application
793    /// messages; on [`FixSessionAction::GapDetected`] the host should hold or
794    /// redeliver the triggering frame after the missing range is recovered.
795    ///
796    /// # Errors
797    ///
798    /// Returns [`FixSessionError`] for identity, sequence, state, required-tag,
799    /// timer, or encoding failures.
800    pub fn on_inbound(
801        &mut self,
802        message: &FixMessageView<'_>,
803        now_ns: u64,
804        sending_time: &[u8],
805        out: &mut Vec<u8>,
806    ) -> Result<FixSessionAction, FixSessionError> {
807        if matches!(
808            self.state,
809            FixSessionState::Disconnected | FixSessionState::Connecting | FixSessionState::Stopped
810        ) {
811            return Err(FixSessionError::InvalidState {
812                operation: "inbound",
813                state: self.state,
814            });
815        }
816        validate_wire_value(FixTag::SENDING_TIME, sending_time)?;
817        self.observe_time(now_ns)?;
818        self.validate_identity(message)?;
819        self.metrics.inbound_messages = self.metrics.inbound_messages.saturating_add(1);
820        self.metrics.last_inbound_ns = Some(now_ns);
821
822        let sequence_action = self.sequences.observe_message(message)?;
823        let sequence = match sequence_action {
824            FixSequenceAction::Accept { seq_no } => seq_no,
825            FixSequenceAction::Duplicate { seq_no, expected } => {
826                self.metrics.duplicate_messages = self.metrics.duplicate_messages.saturating_add(1);
827                return Ok(FixSessionAction::Duplicate {
828                    sequence: seq_no,
829                    expected,
830                });
831            }
832            FixSequenceAction::Gap {
833                received, resend, ..
834            } => {
835                self.metrics.sequence_gaps = self.metrics.sequence_gaps.saturating_add(1);
836                self.metrics.resend_requests_sent =
837                    self.metrics.resend_requests_sent.saturating_add(1);
838                self.recovery_target = Some(received);
839                self.state = FixSessionState::ResendRequested;
840                let request_sequence = self.sequences.assign_outbound();
841                encode_resend_request(
842                    out,
843                    self.session_id.version(),
844                    self.header(request_sequence, sending_time),
845                    resend,
846                )?;
847                self.mark_outbound(now_ns, false);
848                return Ok(FixSessionAction::GapDetected {
849                    received,
850                    range: resend,
851                    request_sequence,
852                });
853            }
854            FixSequenceAction::TooLow { expected, received } => {
855                self.metrics.sequence_too_low = self.metrics.sequence_too_low.saturating_add(1);
856                self.state = FixSessionState::Degraded;
857                return Err(FixSessionError::SequenceTooLow { expected, received });
858            }
859        };
860
861        let msg_type = message
862            .msg_type()
863            .ok_or(FixSessionError::MissingTag(FixTag::MSG_TYPE))?;
864        match FixMsgType::from_bytes(msg_type) {
865            Some(FixMsgType::LOGON) => self.accept_logon(message, sequence),
866            Some(FixMsgType::HEARTBEAT) => self.accept_heartbeat(message, sequence),
867            Some(FixMsgType::TEST_REQUEST) => {
868                self.respond_to_test_request(message, sequence, now_ns, sending_time, out)
869            }
870            Some(FixMsgType::RESEND_REQUEST) => self.accept_resend_request(message, sequence),
871            Some(FixMsgType::SEQUENCE_RESET) => self.accept_sequence_reset(message, sequence),
872            Some(FixMsgType::LOGOUT) => self.accept_logout(
873                sequence,
874                now_ns,
875                sending_time,
876                message.get(FixTag::TEXT),
877                out,
878            ),
879            Some(msg_type @ (FixMsgType::REJECT | FixMsgType::BUSINESS_MESSAGE_REJECT)) => {
880                Ok(FixSessionAction::Administrative {
881                    sequence,
882                    message_type: msg_type,
883                })
884            }
885            _ => self.accept_application(sequence),
886        }
887    }
888
889    /// Assigns the next outbound application sequence number.
890    ///
891    /// The caller should fully validate its order request before calling this
892    /// method, then encode, durably retain, and transmit the resulting frame.
893    /// Sequence numbers are never rolled back after assignment; an encode or
894    /// send failure must be represented through retry/resend or gap-fill policy.
895    ///
896    /// # Errors
897    ///
898    /// Returns [`FixSessionError`] unless the session is ready or the timestamp
899    /// regresses.
900    pub fn assign_application_sequence(&mut self, now_ns: u64) -> Result<u64, FixSessionError> {
901        if self.state != FixSessionState::Ready {
902            return Err(FixSessionError::InvalidState {
903                operation: "assign_application_sequence",
904                state: self.state,
905            });
906        }
907        self.observe_time(now_ns)?;
908        let sequence = self.sequences.assign_outbound();
909        self.mark_outbound(now_ns, true);
910        Ok(sequence)
911    }
912
913    /// Records transmission of a possible-duplicate replay frame.
914    ///
915    /// Replays retain their original FIX sequence and therefore do not advance
916    /// the outbound counter.
917    ///
918    /// # Errors
919    ///
920    /// Returns [`FixSessionError`] if the timestamp regresses.
921    pub fn record_replay_sent(&mut self, now_ns: u64) -> Result<(), FixSessionError> {
922        self.observe_time(now_ns)?;
923        self.metrics.outbound_messages = self.metrics.outbound_messages.saturating_add(1);
924        self.metrics.last_outbound_ns = Some(now_ns);
925        Ok(())
926    }
927
928    fn accept_logon(
929        &mut self,
930        message: &FixMessageView<'_>,
931        sequence: u64,
932    ) -> Result<FixSessionAction, FixSessionError> {
933        if self.state != FixSessionState::LogonSent {
934            return Err(FixSessionError::InvalidState {
935                operation: "accept_logon",
936                state: self.state,
937            });
938        }
939        let heartbeat = parse_required_u64(message, FixTag::HEART_BT_INT)?;
940        if heartbeat != u64::from(self.config.heartbeat_interval_secs) {
941            self.state = FixSessionState::Degraded;
942            return Err(FixSessionError::HeartbeatIntervalMismatch {
943                expected: self.config.heartbeat_interval_secs,
944                received: heartbeat,
945            });
946        }
947        let peer_reset = message.get(FixTag::RESET_SEQ_NUM_FLAG) == Some(b"Y".as_slice());
948        if peer_reset != self.config.reset_seq_num_on_logon {
949            self.state = FixSessionState::Degraded;
950            return Err(FixSessionError::UnexpectedResetSeqNumFlag);
951        }
952        self.state = FixSessionState::Ready;
953        self.metrics.logons_received = self.metrics.logons_received.saturating_add(1);
954        Ok(FixSessionAction::Ready { sequence })
955    }
956
957    fn accept_heartbeat(
958        &mut self,
959        message: &FixMessageView<'_>,
960        sequence: u64,
961    ) -> Result<FixSessionAction, FixSessionError> {
962        self.metrics.heartbeats_received = self.metrics.heartbeats_received.saturating_add(1);
963        if let Some(pending) = self.pending_test_request {
964            if let Some(test_req_id) = message.get(FixTag::TEST_REQ_ID) {
965                if test_req_id != pending.id() {
966                    self.state = FixSessionState::Degraded;
967                    return Err(FixSessionError::TestRequestIdMismatch);
968                }
969                self.pending_test_request = None;
970            }
971        }
972        self.finish_recovery_if_ready();
973        Ok(FixSessionAction::Administrative {
974            sequence,
975            message_type: FixMsgType::HEARTBEAT,
976        })
977    }
978
979    fn respond_to_test_request(
980        &mut self,
981        message: &FixMessageView<'_>,
982        _inbound_sequence: u64,
983        now_ns: u64,
984        sending_time: &[u8],
985        out: &mut Vec<u8>,
986    ) -> Result<FixSessionAction, FixSessionError> {
987        let test_req_id = message
988            .get(FixTag::TEST_REQ_ID)
989            .ok_or(FixSessionError::MissingTag(FixTag::TEST_REQ_ID))?;
990        self.metrics.test_requests_received = self.metrics.test_requests_received.saturating_add(1);
991        let sequence = self.sequences.assign_outbound();
992        encode_heartbeat(
993            out,
994            self.session_id.version(),
995            self.header(sequence, sending_time),
996            Some(test_req_id),
997        )?;
998        self.metrics.heartbeats_sent = self.metrics.heartbeats_sent.saturating_add(1);
999        self.mark_outbound(now_ns, false);
1000        self.finish_recovery_if_ready();
1001        Ok(FixSessionAction::Send {
1002            kind: FixSessionSendKind::Heartbeat,
1003            sequence,
1004        })
1005    }
1006
1007    fn accept_resend_request(
1008        &mut self,
1009        message: &FixMessageView<'_>,
1010        sequence: u64,
1011    ) -> Result<FixSessionAction, FixSessionError> {
1012        let begin_seq_no = parse_required_u64(message, FixTag::BEGIN_SEQ_NO)?;
1013        let end_seq_no = parse_required_u64(message, FixTag::END_SEQ_NO)?;
1014        if begin_seq_no == 0 || (end_seq_no != 0 && end_seq_no < begin_seq_no) {
1015            return Err(FixSessionError::InvalidResendRange {
1016                begin_seq_no,
1017                end_seq_no,
1018            });
1019        }
1020        self.metrics.resend_requests_received =
1021            self.metrics.resend_requests_received.saturating_add(1);
1022        self.finish_recovery_if_ready();
1023        Ok(FixSessionAction::PeerResendRequested {
1024            sequence,
1025            range: FixResendRange {
1026                begin_seq_no,
1027                end_seq_no,
1028            },
1029        })
1030    }
1031
1032    fn accept_sequence_reset(
1033        &mut self,
1034        message: &FixMessageView<'_>,
1035        sequence: u64,
1036    ) -> Result<FixSessionAction, FixSessionError> {
1037        let next_inbound = parse_required_u64(message, FixTag::NEW_SEQ_NO)?;
1038        self.sequences.apply_sequence_reset(next_inbound)?;
1039        self.finish_recovery_if_ready();
1040        Ok(FixSessionAction::SequenceReset {
1041            sequence,
1042            next_inbound,
1043        })
1044    }
1045
1046    fn accept_logout(
1047        &mut self,
1048        _inbound_sequence: u64,
1049        now_ns: u64,
1050        sending_time: &[u8],
1051        text: Option<&[u8]>,
1052        out: &mut Vec<u8>,
1053    ) -> Result<FixSessionAction, FixSessionError> {
1054        self.metrics.logouts_received = self.metrics.logouts_received.saturating_add(1);
1055        if self.state == FixSessionState::LogoutSent {
1056            self.state = FixSessionState::Stopped;
1057            self.logout_sent_ns = None;
1058            self.disconnect_requested = true;
1059            return Ok(FixSessionAction::Disconnect {
1060                reason: FixSessionDisconnectReason::PeerLogout,
1061            });
1062        }
1063        let sequence = self.sequences.assign_outbound();
1064        encode_logout(
1065            out,
1066            self.session_id.version(),
1067            self.header(sequence, sending_time),
1068            text,
1069        )?;
1070        self.state = FixSessionState::LogoutSent;
1071        self.logout_sent_ns = Some(now_ns);
1072        self.metrics.logouts_sent = self.metrics.logouts_sent.saturating_add(1);
1073        self.mark_outbound(now_ns, false);
1074        Ok(FixSessionAction::Send {
1075            kind: FixSessionSendKind::Logout,
1076            sequence,
1077        })
1078    }
1079
1080    fn accept_application(&mut self, sequence: u64) -> Result<FixSessionAction, FixSessionError> {
1081        if !matches!(
1082            self.state,
1083            FixSessionState::Ready | FixSessionState::ResendRequested | FixSessionState::Recovering
1084        ) {
1085            return Err(FixSessionError::UnexpectedApplicationMessage);
1086        }
1087        self.metrics.inbound_application_messages =
1088            self.metrics.inbound_application_messages.saturating_add(1);
1089        self.finish_recovery_if_ready();
1090        Ok(FixSessionAction::Application { sequence })
1091    }
1092
1093    fn encode_liveness_test(
1094        &mut self,
1095        now_ns: u64,
1096        sending_time: &[u8],
1097        out: &mut Vec<u8>,
1098    ) -> Result<FixSessionAction, FixSessionError> {
1099        let mut bytes = [0u8; TEST_REQUEST_ID_CAPACITY];
1100        bytes[..TEST_REQUEST_PREFIX.len()].copy_from_slice(TEST_REQUEST_PREFIX);
1101        let digits = write_decimal(
1102            &mut bytes[TEST_REQUEST_PREFIX.len()..],
1103            self.next_test_request_id,
1104        );
1105        let len = TEST_REQUEST_PREFIX.len().saturating_add(digits);
1106        let sequence = self.sequences.assign_outbound();
1107        encode_test_request(
1108            out,
1109            self.session_id.version(),
1110            self.header(sequence, sending_time),
1111            &bytes[..len],
1112        )?;
1113        self.pending_test_request = Some(PendingTestRequest {
1114            bytes,
1115            len: u8::try_from(len).unwrap_or(u8::MAX),
1116            sent_ns: now_ns,
1117        });
1118        self.next_test_request_id = self.next_test_request_id.saturating_add(1);
1119        self.metrics.test_requests_sent = self.metrics.test_requests_sent.saturating_add(1);
1120        self.mark_outbound(now_ns, false);
1121        Ok(FixSessionAction::Send {
1122            kind: FixSessionSendKind::TestRequest,
1123            sequence,
1124        })
1125    }
1126
1127    fn validate_identity(&self, message: &FixMessageView<'_>) -> Result<(), FixSessionError> {
1128        if message.begin_string() != Some(self.session_id.version().as_bytes()) {
1129            return Err(FixSessionError::VersionMismatch);
1130        }
1131        if !self.config.validate_comp_ids {
1132            return Ok(());
1133        }
1134        if message.get(FixTag::SENDER_COMP_ID) != Some(self.session_id.target_comp_id()) {
1135            return Err(FixSessionError::SenderCompIdMismatch);
1136        }
1137        if message.get(FixTag::TARGET_COMP_ID) != Some(self.session_id.sender_comp_id()) {
1138            return Err(FixSessionError::TargetCompIdMismatch);
1139        }
1140        Ok(())
1141    }
1142
1143    fn header<'a>(&'a self, sequence: u64, sending_time: &'a [u8]) -> FixSessionHeader<'a> {
1144        FixSessionHeader::new(
1145            self.session_id.sender_comp_id(),
1146            self.session_id.target_comp_id(),
1147            sequence,
1148            sending_time,
1149        )
1150    }
1151
1152    fn observe_time(&mut self, now_ns: u64) -> Result<(), FixSessionError> {
1153        if let Some(previous_ns) = self.last_observed_ns {
1154            if now_ns < previous_ns {
1155                return Err(FixSessionError::TimestampRegression {
1156                    previous_ns,
1157                    observed_ns: now_ns,
1158                });
1159            }
1160        }
1161        self.last_observed_ns = Some(now_ns);
1162        Ok(())
1163    }
1164
1165    fn mark_outbound(&mut self, now_ns: u64, application: bool) {
1166        self.metrics.outbound_messages = self.metrics.outbound_messages.saturating_add(1);
1167        if application {
1168            self.metrics.outbound_application_messages =
1169                self.metrics.outbound_application_messages.saturating_add(1);
1170        }
1171        self.metrics.last_outbound_ns = Some(now_ns);
1172    }
1173
1174    fn finish_recovery_if_ready(&mut self) {
1175        if let Some(target) = self.recovery_target {
1176            if self.sequences.next_inbound() >= target {
1177                self.recovery_target = None;
1178                if matches!(
1179                    self.state,
1180                    FixSessionState::ResendRequested | FixSessionState::Recovering
1181                ) {
1182                    self.state = FixSessionState::Ready;
1183                }
1184            } else if self.state == FixSessionState::ResendRequested {
1185                self.state = FixSessionState::Recovering;
1186            }
1187        }
1188    }
1189}
1190
1191fn elapsed_at_least(start_ns: Option<u64>, now_ns: u64, duration_ns: u64) -> bool {
1192    start_ns.is_some_and(|start| now_ns.saturating_sub(start) >= duration_ns)
1193}
1194
1195fn parse_required_u64(message: &FixMessageView<'_>, tag: FixTag) -> Result<u64, FixSessionError> {
1196    let value = message.get(tag).ok_or(FixSessionError::MissingTag(tag))?;
1197    parse_decimal(value).ok_or(FixSessionError::MalformedNumericTag(tag))
1198}
1199
1200fn validate_wire_value(tag: FixTag, value: &[u8]) -> Result<(), FixSessionError> {
1201    if value.contains(&crate::SOH) {
1202        return Err(FixEncodeError::ValueContainsSoh(tag).into());
1203    }
1204    Ok(())
1205}
1206
1207fn parse_decimal(value: &[u8]) -> Option<u64> {
1208    if value.is_empty() {
1209        return None;
1210    }
1211    let mut parsed = 0u64;
1212    for byte in value {
1213        if !byte.is_ascii_digit() {
1214            return None;
1215        }
1216        parsed = parsed
1217            .checked_mul(10)?
1218            .checked_add(u64::from(byte - b'0'))?;
1219    }
1220    Some(parsed)
1221}
1222
1223fn write_decimal(out: &mut [u8], mut value: u64) -> usize {
1224    let mut reversed = [0u8; 20];
1225    let mut len = 0usize;
1226    loop {
1227        reversed[len] = b'0' + (value % 10) as u8;
1228        len += 1;
1229        value /= 10;
1230        if value == 0 {
1231            break;
1232        }
1233    }
1234    for index in 0..len {
1235        out[index] = reversed[len - index - 1];
1236    }
1237    len
1238}
1239
1240#[cfg(test)]
1241mod tests {
1242    use super::*;
1243    use crate::{encode_message, parse_message, FixFieldView, FixVersion};
1244
1245    const SEND_TIME: &[u8] = b"20260810-12:00:00.000";
1246    const HEARTBEAT_DUE_NS: u64 = 10_000_000_002;
1247    const TEST_REQUEST_DUE_NS: u64 = 15_000_000_002;
1248    const DISCONNECT_DUE_NS: u64 = 25_000_000_002;
1249
1250    fn engine() -> FixSessionEngine {
1251        FixSessionEngine::new(
1252            FixSessionEngineConfig::new(10)
1253                .unwrap()
1254                .with_timeouts(15_000_000_000, 10_000_000_000, 10_000_000_000)
1255                .unwrap(),
1256            FixOwnedSessionId::new(FixVersion::Fix44, b"CLIENT".to_vec(), b"VENUE".to_vec())
1257                .unwrap(),
1258        )
1259    }
1260
1261    fn inbound(
1262        msg_type: FixMsgType,
1263        sequence: u64,
1264        extra: &[(FixTag, &[u8])],
1265    ) -> (Vec<u8>, Vec<FixFieldView<'static>>) {
1266        let mut sequence_bytes = [0u8; 20];
1267        let sequence_len = write_decimal(&mut sequence_bytes, sequence);
1268        let mut fields = vec![
1269            (FixTag::SENDER_COMP_ID, b"VENUE".as_slice()),
1270            (FixTag::TARGET_COMP_ID, b"CLIENT".as_slice()),
1271            (FixTag::MSG_SEQ_NUM, &sequence_bytes[..sequence_len]),
1272            (FixTag::SENDING_TIME, SEND_TIME),
1273        ];
1274        fields.extend_from_slice(extra);
1275        let mut raw = Vec::new();
1276        encode_message(&mut raw, b"FIX.4.4", msg_type.as_bytes(), &fields).unwrap();
1277        let scratch = vec![FixFieldView::empty(); 64];
1278        (raw, scratch)
1279    }
1280
1281    fn with_message<T>(
1282        msg_type: FixMsgType,
1283        sequence: u64,
1284        extra: &[(FixTag, &[u8])],
1285        apply: impl FnOnce(&FixMessageView<'_>) -> T,
1286    ) -> T {
1287        let (raw, mut scratch) = inbound(msg_type, sequence, extra);
1288        let message = parse_message(&raw, &mut scratch).unwrap();
1289        apply(&message)
1290    }
1291
1292    fn connect_and_logon(engine: &mut FixSessionEngine, out: &mut Vec<u8>) {
1293        engine.on_transport_connecting().unwrap();
1294        let action = engine.on_transport_connected(1, SEND_TIME, out).unwrap();
1295        assert_eq!(
1296            action,
1297            FixSessionAction::Send {
1298                kind: FixSessionSendKind::Logon,
1299                sequence: 1
1300            }
1301        );
1302        with_message(
1303            FixMsgType::LOGON,
1304            1,
1305            &[(FixTag::HEART_BT_INT, b"10")],
1306            |message| {
1307                assert_eq!(
1308                    engine.on_inbound(message, 2, SEND_TIME, out).unwrap(),
1309                    FixSessionAction::Ready { sequence: 1 }
1310                );
1311            },
1312        );
1313    }
1314
1315    #[test]
1316    fn connect_and_logon_establish_ready_session() {
1317        let mut engine = engine();
1318        let mut out = Vec::with_capacity(512);
1319        connect_and_logon(&mut engine, &mut out);
1320        assert_eq!(engine.state(), FixSessionState::Ready);
1321        assert_eq!(engine.sequences().next_inbound(), 2);
1322        assert_eq!(engine.sequences().next_outbound(), 2);
1323        assert_eq!(engine.metrics().connections, 1);
1324        assert_eq!(engine.metrics().logons_received, 1);
1325    }
1326
1327    #[test]
1328    fn timer_sends_heartbeat_test_request_and_disconnects() {
1329        let mut engine = engine();
1330        let mut out = Vec::with_capacity(512);
1331        connect_and_logon(&mut engine, &mut out);
1332
1333        assert_eq!(
1334            engine
1335                .on_timer(HEARTBEAT_DUE_NS, SEND_TIME, &mut out)
1336                .unwrap(),
1337            FixSessionAction::Send {
1338                kind: FixSessionSendKind::Heartbeat,
1339                sequence: 2
1340            }
1341        );
1342        assert_eq!(
1343            engine
1344                .on_timer(TEST_REQUEST_DUE_NS, SEND_TIME, &mut out)
1345                .unwrap(),
1346            FixSessionAction::Send {
1347                kind: FixSessionSendKind::TestRequest,
1348                sequence: 3
1349            }
1350        );
1351        assert_eq!(
1352            engine
1353                .on_timer(DISCONNECT_DUE_NS, SEND_TIME, &mut out)
1354                .unwrap(),
1355            FixSessionAction::Disconnect {
1356                reason: FixSessionDisconnectReason::HeartbeatTimeout
1357            }
1358        );
1359        assert_eq!(engine.state(), FixSessionState::Degraded);
1360        assert_eq!(engine.metrics().timeout_disconnects, 1);
1361    }
1362
1363    #[test]
1364    fn heartbeat_must_echo_pending_test_request_id() {
1365        let mut engine = engine();
1366        let mut out = Vec::with_capacity(512);
1367        connect_and_logon(&mut engine, &mut out);
1368        engine
1369            .on_timer(TEST_REQUEST_DUE_NS, SEND_TIME, &mut out)
1370            .unwrap();
1371
1372        with_message(
1373            FixMsgType::HEARTBEAT,
1374            2,
1375            &[(FixTag::TEST_REQ_ID, b"wrong")],
1376            |message| {
1377                assert_eq!(
1378                    engine.on_inbound(message, TEST_REQUEST_DUE_NS + 1, SEND_TIME, &mut out),
1379                    Err(FixSessionError::TestRequestIdMismatch)
1380                );
1381            },
1382        );
1383        assert_eq!(engine.state(), FixSessionState::Degraded);
1384    }
1385
1386    #[test]
1387    fn peer_test_request_encodes_correlated_heartbeat() {
1388        let mut engine = engine();
1389        let mut out = Vec::with_capacity(512);
1390        connect_and_logon(&mut engine, &mut out);
1391        with_message(
1392            FixMsgType::TEST_REQUEST,
1393            2,
1394            &[(FixTag::TEST_REQ_ID, b"peer-1")],
1395            |message| {
1396                assert_eq!(
1397                    engine.on_inbound(message, 3, SEND_TIME, &mut out).unwrap(),
1398                    FixSessionAction::Send {
1399                        kind: FixSessionSendKind::Heartbeat,
1400                        sequence: 2
1401                    }
1402                );
1403            },
1404        );
1405        let mut scratch = [FixFieldView::empty(); 32];
1406        let response = parse_message(&out, &mut scratch).unwrap();
1407        assert_eq!(response.msg_type(), Some(b"0".as_slice()));
1408        assert_eq!(
1409            response.get(FixTag::TEST_REQ_ID),
1410            Some(b"peer-1".as_slice())
1411        );
1412    }
1413
1414    #[test]
1415    fn gap_recovery_requests_missing_range_and_applies_reset() {
1416        let mut engine = engine();
1417        let mut out = Vec::with_capacity(512);
1418        connect_and_logon(&mut engine, &mut out);
1419        with_message(FixMsgType::EXECUTION_REPORT, 4, &[], |message| {
1420            assert_eq!(
1421                engine.on_inbound(message, 3, SEND_TIME, &mut out).unwrap(),
1422                FixSessionAction::GapDetected {
1423                    received: 4,
1424                    range: FixResendRange {
1425                        begin_seq_no: 2,
1426                        end_seq_no: 3
1427                    },
1428                    request_sequence: 2
1429                }
1430            );
1431        });
1432        assert_eq!(engine.state(), FixSessionState::ResendRequested);
1433
1434        with_message(
1435            FixMsgType::SEQUENCE_RESET,
1436            2,
1437            &[(FixTag::NEW_SEQ_NO, b"4"), (FixTag::GAP_FILL_FLAG, b"Y")],
1438            |message| {
1439                assert_eq!(
1440                    engine.on_inbound(message, 4, SEND_TIME, &mut out).unwrap(),
1441                    FixSessionAction::SequenceReset {
1442                        sequence: 2,
1443                        next_inbound: 4
1444                    }
1445                );
1446            },
1447        );
1448        assert_eq!(engine.state(), FixSessionState::Ready);
1449        with_message(FixMsgType::EXECUTION_REPORT, 4, &[], |message| {
1450            assert_eq!(
1451                engine.on_inbound(message, 5, SEND_TIME, &mut out).unwrap(),
1452                FixSessionAction::Application { sequence: 4 }
1453            );
1454        });
1455    }
1456
1457    #[test]
1458    fn gap_recovery_accepts_replayed_application_messages_in_order() {
1459        let mut engine = engine();
1460        let mut out = Vec::with_capacity(512);
1461        connect_and_logon(&mut engine, &mut out);
1462        with_message(FixMsgType::EXECUTION_REPORT, 3, &[], |message| {
1463            assert!(matches!(
1464                engine.on_inbound(message, 3, SEND_TIME, &mut out).unwrap(),
1465                FixSessionAction::GapDetected { received: 3, .. }
1466            ));
1467        });
1468        assert_eq!(engine.state(), FixSessionState::ResendRequested);
1469
1470        with_message(FixMsgType::EXECUTION_REPORT, 2, &[], |message| {
1471            assert_eq!(
1472                engine.on_inbound(message, 4, SEND_TIME, &mut out).unwrap(),
1473                FixSessionAction::Application { sequence: 2 }
1474            );
1475        });
1476        assert_eq!(engine.state(), FixSessionState::Ready);
1477    }
1478
1479    #[test]
1480    fn peer_resend_request_is_exposed_without_store_coupling() {
1481        let mut engine = engine();
1482        let mut out = Vec::with_capacity(512);
1483        connect_and_logon(&mut engine, &mut out);
1484        with_message(
1485            FixMsgType::RESEND_REQUEST,
1486            2,
1487            &[(FixTag::BEGIN_SEQ_NO, b"1"), (FixTag::END_SEQ_NO, b"0")],
1488            |message| {
1489                assert_eq!(
1490                    engine.on_inbound(message, 3, SEND_TIME, &mut out).unwrap(),
1491                    FixSessionAction::PeerResendRequested {
1492                        sequence: 2,
1493                        range: FixResendRange {
1494                            begin_seq_no: 1,
1495                            end_seq_no: 0
1496                        }
1497                    }
1498                );
1499            },
1500        );
1501    }
1502
1503    #[test]
1504    fn duplicate_is_ignored_and_unflagged_regression_fails_closed() {
1505        let mut engine = engine();
1506        let mut out = Vec::with_capacity(512);
1507        connect_and_logon(&mut engine, &mut out);
1508        with_message(
1509            FixMsgType::HEARTBEAT,
1510            1,
1511            &[(FixTag::POSS_DUP_FLAG, b"Y")],
1512            |message| {
1513                assert_eq!(
1514                    engine.on_inbound(message, 3, SEND_TIME, &mut out).unwrap(),
1515                    FixSessionAction::Duplicate {
1516                        sequence: 1,
1517                        expected: 2
1518                    }
1519                );
1520            },
1521        );
1522        with_message(FixMsgType::HEARTBEAT, 1, &[], |message| {
1523            assert_eq!(
1524                engine.on_inbound(message, 4, SEND_TIME, &mut out),
1525                Err(FixSessionError::SequenceTooLow {
1526                    expected: 2,
1527                    received: 1
1528                })
1529            );
1530        });
1531    }
1532
1533    #[test]
1534    fn graceful_logout_waits_for_peer_then_requests_disconnect() {
1535        let mut engine = engine();
1536        let mut out = Vec::with_capacity(512);
1537        connect_and_logon(&mut engine, &mut out);
1538        assert_eq!(
1539            engine
1540                .request_logout(3, SEND_TIME, Some(b"shutdown"), &mut out)
1541                .unwrap(),
1542            FixSessionAction::Send {
1543                kind: FixSessionSendKind::Logout,
1544                sequence: 2
1545            }
1546        );
1547        with_message(FixMsgType::LOGOUT, 2, &[], |message| {
1548            assert_eq!(
1549                engine.on_inbound(message, 4, SEND_TIME, &mut out).unwrap(),
1550                FixSessionAction::Disconnect {
1551                    reason: FixSessionDisconnectReason::PeerLogout
1552                }
1553            );
1554        });
1555        assert_eq!(engine.state(), FixSessionState::Stopped);
1556    }
1557
1558    #[test]
1559    fn identity_and_timestamp_regressions_fail_closed() {
1560        let mut engine = engine();
1561        let mut out = Vec::with_capacity(512);
1562        engine
1563            .on_transport_connected(10, SEND_TIME, &mut out)
1564            .unwrap();
1565        assert_eq!(
1566            engine.on_timer(9, SEND_TIME, &mut out),
1567            Err(FixSessionError::TimestampRegression {
1568                previous_ns: 10,
1569                observed_ns: 9
1570            })
1571        );
1572
1573        let mut sequence_bytes = [0u8; 20];
1574        let len = write_decimal(&mut sequence_bytes, 1);
1575        let mut raw = Vec::new();
1576        encode_message(
1577            &mut raw,
1578            b"FIX.4.4",
1579            b"A",
1580            &[
1581                (FixTag::SENDER_COMP_ID, b"WRONG"),
1582                (FixTag::TARGET_COMP_ID, b"CLIENT"),
1583                (FixTag::MSG_SEQ_NUM, &sequence_bytes[..len]),
1584                (FixTag::SENDING_TIME, SEND_TIME),
1585                (FixTag::HEART_BT_INT, b"10"),
1586            ],
1587        )
1588        .unwrap();
1589        let mut scratch = [FixFieldView::empty(); 32];
1590        let message = parse_message(&raw, &mut scratch).unwrap();
1591        assert_eq!(
1592            engine.on_inbound(&message, 11, SEND_TIME, &mut out),
1593            Err(FixSessionError::SenderCompIdMismatch)
1594        );
1595    }
1596
1597    #[test]
1598    fn application_sequence_assignment_requires_ready_state() {
1599        let mut engine = engine();
1600        assert!(matches!(
1601            engine.assign_application_sequence(1),
1602            Err(FixSessionError::InvalidState { .. })
1603        ));
1604        let mut out = Vec::with_capacity(512);
1605        connect_and_logon(&mut engine, &mut out);
1606        assert_eq!(engine.assign_application_sequence(3).unwrap(), 2);
1607        assert_eq!(engine.metrics().outbound_application_messages, 1);
1608    }
1609
1610    #[test]
1611    fn custom_profile_message_is_accepted_as_application_flow() {
1612        let mut engine = engine();
1613        let mut out = Vec::with_capacity(512);
1614        connect_and_logon(&mut engine, &mut out);
1615        with_message(FixMsgType::from_static(b"U99"), 2, &[], |message| {
1616            assert_eq!(
1617                engine.on_inbound(message, 3, SEND_TIME, &mut out).unwrap(),
1618                FixSessionAction::Application { sequence: 2 }
1619            );
1620        });
1621    }
1622
1623    #[test]
1624    fn invalid_sending_time_does_not_consume_outbound_sequence() {
1625        let mut engine = engine();
1626        let mut out = Vec::with_capacity(512);
1627        engine.on_transport_connecting().unwrap();
1628        assert_eq!(
1629            engine.on_transport_connected(1, b"bad\x01time", &mut out),
1630            Err(FixSessionError::Encode(FixEncodeError::ValueContainsSoh(
1631                FixTag::SENDING_TIME
1632            )))
1633        );
1634        assert_eq!(engine.sequences().next_outbound(), 1);
1635        assert_eq!(engine.state(), FixSessionState::Connecting);
1636    }
1637}