fixcore-engine 0.1.0__py3-none-any.whl

fixcore/session/session.py

@@ -0,0 +1,532 @@
+"""FIX Session — state machine, sequence number management, admin message handling."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from datetime import datetime, timezone
+from typing import Awaitable, Callable
+
+from fixcore.application import Application
+from fixcore.log.base import Log
+from fixcore.message.message import Message
+from fixcore.session.session_id import SessionID
+from fixcore.session.session_settings import SessionSettings
+from fixcore.session.state import (
+    ADMIN_MSG_TYPES,
+    MSG_HEARTBEAT,
+    MSG_LOGON,
+    MSG_LOGOUT,
+    MSG_REJECT,
+    MSG_RESEND_REQUEST,
+    MSG_SEQUENCE_RESET,
+    MSG_TEST_REQUEST,
+    TAG_BEGIN_SEQ_NO,
+    TAG_BEGIN_STRING,
+    TAG_ENCRYPT_METHOD,
+    TAG_END_SEQ_NO,
+    TAG_GAP_FILL_FLAG,
+    TAG_HEART_BT_INT,
+    TAG_MSG_SEQ_NUM,
+    TAG_MSG_TYPE,
+    TAG_NEW_SEQ_NO,
+    TAG_ORIG_SENDING_TIME,
+    TAG_POSS_DUP_FLAG,
+    TAG_REF_MSG_TYPE,
+    TAG_REF_SEQ_NUM,
+    TAG_REF_TAG_ID,
+    TAG_RESET_SEQ_NUM_FLAG,
+    TAG_SENDER_COMP_ID,
+    TAG_SENDING_TIME,
+    TAG_SESSION_REJECT_REASON,
+    TAG_TARGET_COMP_ID,
+    TAG_TEST_REQ_ID,
+    TAG_TEXT,
+    SessionState,
+)
+from fixcore.store.base import MessageStore
+
+
+def _utc_timestamp() -> str:
+    return datetime.now(tz=timezone.utc).strftime("%Y%m%d-%H:%M:%S")
+
+
+# Type alias for the transport-provided send callback
+SendFn = Callable[[bytes], Awaitable[None]]
+
+
+class Session:
+    """Manages a single FIX session's full lifecycle.
+
+    The transport layer calls:
+      - ``on_connect(send_fn)``  — when TCP connection is established
+      - ``on_disconnect()``      — when connection is lost
+      - ``on_data(raw)``         — with each complete, framed FIX message
+
+    User code calls:
+      - ``send_app(message)``    — to send an application message
+      - ``send_logout(text)``    — to initiate a graceful logout
+    """
+
+    def __init__(
+        self,
+        session_id: SessionID,
+        settings: SessionSettings,
+        application: Application,
+        store: MessageStore,
+        log: Log,
+    ) -> None:
+        self._id = session_id
+        self._settings = settings
+        self._app = application
+        self._store = store
+        self._log = log
+
+        # Config (with defaults)
+        self._heartbt_int: int = settings.get_int(session_id, "HeartBtInt", 30)
+        self._logon_timeout: int = settings.get_int(session_id, "LogonTimeout", 10)
+        self._logout_timeout: int = settings.get_int(session_id, "LogoutTimeout", 10)
+        self._is_initiator: bool = (
+            settings.get_or(session_id, "ConnectionType", "initiator").lower() == "initiator"
+        )
+        self._reset_on_logon: bool = settings.get_bool(session_id, "ResetOnLogon", False)
+        self._reset_on_logout: bool = settings.get_bool(session_id, "ResetOnLogout", False)
+        self._reset_on_disconnect: bool = settings.get_bool(session_id, "ResetOnDisconnect", False)
+
+        # Runtime state
+        self._state: SessionState = SessionState.DISCONNECTED
+        self._send_fn: SendFn | None = None
+        self._heartbeat_task: asyncio.Task[None] | None = None
+        self._last_send_time: float = 0.0
+        self._last_recv_time: float = 0.0
+        self._test_req_id: str | None = None
+        self._test_req_sent_at: float = 0.0
+        self._logon_sent_at: float = 0.0
+
+        self._app.on_create(session_id)
+
+    # ------------------------------------------------------------------
+    # Transport interface
+    # ------------------------------------------------------------------
+
+    async def on_connect(self, send_fn: SendFn) -> None:
+        """Called by transport when connection is established."""
+        self._send_fn = send_fn
+        self._last_recv_time = time.monotonic()
+
+        if self._reset_on_logon:
+            self._store.reset()
+
+        self._state = SessionState.LOGON_TIMEOUT
+        self._heartbeat_task = asyncio.create_task(self._timer_loop())
+
+        if self._is_initiator:
+            await self._send_logon()
+
+    async def on_disconnect(self) -> None:
+        """Called by transport when connection is lost."""
+        was_logged_on = self._state == SessionState.LOGGED_ON
+        self._state = SessionState.DISCONNECTED
+        self._send_fn = None
+
+        if self._heartbeat_task is not None:
+            self._heartbeat_task.cancel()
+            try:
+                await self._heartbeat_task
+            except asyncio.CancelledError:
+                pass
+            self._heartbeat_task = None
+
+        self._test_req_id = None
+
+        if self._reset_on_disconnect:
+            self._store.reset()
+
+        if was_logged_on:
+            self._app.on_logout(self._id)
+
+        self._log.on_event("Disconnected")
+
+    async def on_data(self, raw: bytes) -> None:
+        """Called by transport with a single complete framed FIX message."""
+        try:
+            msg = Message.decode(raw)
+        except ValueError as exc:
+            self._log.on_event(f"Decode error: {exc}")
+            return
+
+        self._log.on_incoming(raw.replace(b"\x01", b"|").decode("latin-1"))
+        self._last_recv_time = time.monotonic()
+        self._test_req_id = None  # any incoming message clears a pending TestRequest
+
+        msg_type = msg.msg_type
+        if not msg_type:
+            return
+
+        # Header validation
+        if not self._validate_comp_ids(msg):
+            return
+
+        if not await self._check_seq_num(msg):
+            return
+
+        # Dispatch
+        if msg_type == MSG_LOGON:
+            await self._on_logon(msg)
+        elif msg_type == MSG_LOGOUT:
+            await self._on_logout(msg)
+        elif msg_type == MSG_HEARTBEAT:
+            await self._on_heartbeat(msg)
+        elif msg_type == MSG_TEST_REQUEST:
+            await self._on_test_request(msg)
+        elif msg_type == MSG_RESEND_REQUEST:
+            await self._on_resend_request(msg)
+        elif msg_type == MSG_SEQUENCE_RESET:
+            await self._on_sequence_reset(msg)
+        elif msg_type == MSG_REJECT:
+            await self._on_reject(msg)
+        else:
+            if self._state != SessionState.LOGGED_ON:
+                self._log.on_event(f"Received app message {msg_type!r} while not logged on — ignoring")
+                return
+            self._app.from_app(msg, self._id)
+
+    # ------------------------------------------------------------------
+    # User-facing send API
+    # ------------------------------------------------------------------
+
+    async def send_app(self, message: Message) -> None:
+        """Send an application message. Raises RuntimeError if not logged on."""
+        if self._state != SessionState.LOGGED_ON:
+            raise RuntimeError(f"Session {self._id} is not logged on")
+        await self._send_message(message, is_admin=False)
+
+    async def send_logout(self, text: str = "") -> None:
+        """Initiate a graceful logout."""
+        await self._send_logout(text)
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def session_id(self) -> SessionID:
+        return self._id
+
+    @property
+    def state(self) -> SessionState:
+        return self._state
+
+    @property
+    def is_logged_on(self) -> bool:
+        return self._state == SessionState.LOGGED_ON
+
+    # ------------------------------------------------------------------
+    # Incoming admin message handlers
+    # ------------------------------------------------------------------
+
+    async def _on_logon(self, msg: Message) -> None:
+        if self._state == SessionState.LOGGED_ON:
+            self._log.on_event("Received second Logon while already logged on — ignoring")
+            return
+
+        reset_flag = msg.header.get_or(TAG_RESET_SEQ_NUM_FLAG, "N").upper() == "Y"
+        if reset_flag:
+            self._store.reset()
+            # seq num was already consumed by _check_seq_num; set next target to 2
+            self._store.set_next_target_msg_seq_num(2)
+
+        if not self._is_initiator:
+            # Acceptor: respond with Logon
+            await self._send_logon()
+
+        self._state = SessionState.LOGGED_ON
+        self._app.on_logon(self._id)
+        self._log.on_event("Logon complete")
+
+    async def _on_logout(self, msg: Message) -> None:
+        text = msg.get_field_or(TAG_TEXT, "")
+        self._log.on_event(f"Received Logout{': ' + text if text else ''}")
+
+        if self._state == SessionState.LOGOUT_TIMEOUT:
+            # We sent Logout first; counterparty confirmed — clean disconnect
+            self._state = SessionState.DISCONNECTED
+        else:
+            # Counterparty-initiated logout — echo back and clean up
+            await self._send_logout()
+
+        self._app.on_logout(self._id)
+        self._log.on_event("Logout complete")
+
+    async def _on_heartbeat(self, msg: Message) -> None:
+        # If this is a response to our TestRequest, clear the pending state
+        test_req_id = msg.get_field_or(TAG_TEST_REQ_ID)
+        if test_req_id and test_req_id == self._test_req_id:
+            self._test_req_id = None
+        self._app.from_admin(msg, self._id)
+
+    async def _on_test_request(self, msg: Message) -> None:
+        test_req_id = msg.get_field_or(TAG_TEST_REQ_ID, "")
+        await self._send_heartbeat(test_req_id=test_req_id)
+        self._app.from_admin(msg, self._id)
+
+    async def _on_resend_request(self, msg: Message) -> None:
+        begin = int(msg.get_field_or(TAG_BEGIN_SEQ_NO, "1"))
+        end = int(msg.get_field_or(TAG_END_SEQ_NO, "0"))  # 0 = infinity
+        if end == 0:
+            end = self._store.next_sender_msg_seq_num() - 1
+
+        self._log.on_event(f"ResendRequest [{begin},{end}]")
+        await self._resend_range(begin, end)
+        self._app.from_admin(msg, self._id)
+
+    async def _on_sequence_reset(self, msg: Message) -> None:
+        new_seq_no = int(msg.get_field_or(TAG_NEW_SEQ_NO, "1"))
+        gap_fill = msg.get_field_or(TAG_GAP_FILL_FLAG, "N").upper() == "Y"
+
+        if gap_fill:
+            self._log.on_event(f"GapFill: next expected seq → {new_seq_no}")
+        else:
+            self._log.on_event(f"SequenceReset: next expected seq → {new_seq_no}")
+
+        self._store.set_next_target_msg_seq_num(new_seq_no)
+        self._app.from_admin(msg, self._id)
+
+    async def _on_reject(self, msg: Message) -> None:
+        ref_seq = msg.get_field_or(TAG_REF_SEQ_NUM, "?")
+        reason = msg.get_field_or(TAG_SESSION_REJECT_REASON, "")
+        text = msg.get_field_or(TAG_TEXT, "")
+        self._log.on_event(f"Session Reject for seq {ref_seq}: {reason} {text}".strip())
+        self._app.from_admin(msg, self._id)
+
+    # ------------------------------------------------------------------
+    # Outgoing admin message builders
+    # ------------------------------------------------------------------
+
+    async def _send_logon(self) -> None:
+        msg = Message()
+        msg.header.set(TAG_MSG_TYPE, MSG_LOGON)
+        msg.set_field(TAG_ENCRYPT_METHOD, "0")
+        msg.set_field(TAG_HEART_BT_INT, str(self._heartbt_int))
+        self._app.to_admin(msg, self._id)
+        await self._send_message(msg, is_admin=True)
+        self._logon_sent_at = time.monotonic()
+
+    async def _send_logout(self, text: str = "") -> None:
+        msg = Message()
+        msg.header.set(TAG_MSG_TYPE, MSG_LOGOUT)
+        if text:
+            msg.set_field(TAG_TEXT, text)
+        self._app.to_admin(msg, self._id)
+        await self._send_message(msg, is_admin=True)
+        self._state = SessionState.LOGOUT_TIMEOUT
+
+    async def _send_heartbeat(self, test_req_id: str = "") -> None:
+        msg = Message()
+        msg.header.set(TAG_MSG_TYPE, MSG_HEARTBEAT)
+        if test_req_id:
+            msg.set_field(TAG_TEST_REQ_ID, test_req_id)
+        self._app.to_admin(msg, self._id)
+        await self._send_message(msg, is_admin=True)
+
+    async def _send_test_request(self, test_req_id: str) -> None:
+        msg = Message()
+        msg.header.set(TAG_MSG_TYPE, MSG_TEST_REQUEST)
+        msg.set_field(TAG_TEST_REQ_ID, test_req_id)
+        self._app.to_admin(msg, self._id)
+        await self._send_message(msg, is_admin=True)
+        self._test_req_id = test_req_id
+        self._test_req_sent_at = time.monotonic()
+
+    async def _send_resend_request(self, begin_seq: int, end_seq: int) -> None:
+        msg = Message()
+        msg.header.set(TAG_MSG_TYPE, MSG_RESEND_REQUEST)
+        msg.set_field(TAG_BEGIN_SEQ_NO, str(begin_seq))
+        msg.set_field(TAG_END_SEQ_NO, str(end_seq))
+        self._app.to_admin(msg, self._id)
+        await self._send_message(msg, is_admin=True)
+
+    async def _send_sequence_reset(self, new_seq_no: int, gap_fill: bool = False) -> None:
+        msg = Message()
+        msg.header.set(TAG_MSG_TYPE, MSG_SEQUENCE_RESET)
+        msg.set_field(TAG_GAP_FILL_FLAG, "Y" if gap_fill else "N")
+        msg.set_field(TAG_NEW_SEQ_NO, str(new_seq_no))
+        # For gap-fill: override the seq num to be the beginning of the gap, not current
+        await self._send_message(msg, is_admin=True)
+
+    async def _send_reject(
+        self,
+        ref_seq_num: int,
+        ref_tag: int | None = None,
+        ref_msg_type: str | None = None,
+        reason: int | None = None,
+        text: str = "",
+    ) -> None:
+        msg = Message()
+        msg.header.set(TAG_MSG_TYPE, MSG_REJECT)
+        msg.set_field(TAG_REF_SEQ_NUM, str(ref_seq_num))
+        if ref_tag is not None:
+            msg.set_field(TAG_REF_TAG_ID, str(ref_tag))
+        if ref_msg_type is not None:
+            msg.set_field(TAG_REF_MSG_TYPE, ref_msg_type)
+        if reason is not None:
+            msg.set_field(TAG_SESSION_REJECT_REASON, str(reason))
+        if text:
+            msg.set_field(TAG_TEXT, text)
+        self._app.to_admin(msg, self._id)
+        await self._send_message(msg, is_admin=True)
+
+    # ------------------------------------------------------------------
+    # Resend logic
+    # ------------------------------------------------------------------
+
+    async def _resend_range(self, begin: int, end: int) -> None:
+        """Replay stored messages [begin, end], gap-filling admin messages."""
+        stored = self._store.get(begin, end)
+        seq = begin
+        gap_start: int | None = None
+
+        for raw in stored:
+            try:
+                msg = Message.decode(raw)
+            except ValueError:
+                continue
+
+            msg_seq = int(msg.header.get_or(TAG_MSG_SEQ_NUM, "0"))
+            msg_type = msg.msg_type
+
+            if msg_type in ADMIN_MSG_TYPES:
+                # Admin messages are gap-filled, not re-sent
+                if gap_start is None:
+                    gap_start = msg_seq
+            else:
+                # Flush any pending gap-fill before this app message
+                if gap_start is not None:
+                    await self._send_sequence_reset(msg_seq, gap_fill=True)
+                    gap_start = None
+
+                # Re-send with PossDupFlag
+                msg.header.set(TAG_POSS_DUP_FLAG, "Y")
+                msg.header.set(TAG_ORIG_SENDING_TIME, msg.header.get_or(TAG_SENDING_TIME))
+                msg.header.set(TAG_SENDING_TIME, _utc_timestamp())
+                self._app.to_app(msg, self._id)
+                if self._send_fn is not None:
+                    raw_out = msg.encode()
+                    self._log.on_outgoing(raw_out.replace(b"\x01", b"|").decode("latin-1"))
+                    await self._send_fn(raw_out)
+
+            seq = msg_seq + 1
+
+        # If messages at the tail were all admin, close the gap
+        if gap_start is not None:
+            await self._send_sequence_reset(end + 1, gap_fill=True)
+
+    # ------------------------------------------------------------------
+    # Core send path
+    # ------------------------------------------------------------------
+
+    async def _send_message(self, msg: Message, *, is_admin: bool) -> None:
+        """Stamp header, store, log, and transmit *msg*."""
+        seq_num = self._store.next_sender_msg_seq_num()
+        msg.header.set(TAG_BEGIN_STRING, self._id.begin_string)
+        msg.header.set(TAG_SENDER_COMP_ID, self._id.sender_comp_id)
+        msg.header.set(TAG_TARGET_COMP_ID, self._id.target_comp_id)
+        msg.header.set(TAG_MSG_SEQ_NUM, str(seq_num))
+        msg.header.set(TAG_SENDING_TIME, _utc_timestamp())
+
+        raw = msg.encode()
+        self._store.set(seq_num, raw)
+        self._store.incr_next_sender_msg_seq_num()
+        self._last_send_time = time.monotonic()
+
+        self._log.on_outgoing(raw.replace(b"\x01", b"|").decode("latin-1"))
+
+        if self._send_fn is not None:
+            await self._send_fn(raw)
+
+    # ------------------------------------------------------------------
+    # Sequence number validation
+    # ------------------------------------------------------------------
+
+    def _validate_comp_ids(self, msg: Message) -> bool:
+        sender = msg.header.get_or(TAG_SENDER_COMP_ID)
+        target = msg.header.get_or(TAG_TARGET_COMP_ID)
+        if sender != self._id.target_comp_id or target != self._id.sender_comp_id:
+            self._log.on_event(
+                f"CompID mismatch: got {sender}->{target}, "
+                f"expected {self._id.target_comp_id}->{self._id.sender_comp_id}"
+            )
+            return False
+        return True
+
+    async def _check_seq_num(self, msg: Message) -> bool:
+        """Validate incoming MsgSeqNum.
+
+        Returns True if processing should continue, False to drop the message.
+        """
+        seq_str = msg.header.get_or(TAG_MSG_SEQ_NUM, "0")
+        try:
+            seq_num = int(seq_str)
+        except ValueError:
+            await self._send_reject(0, ref_tag=TAG_MSG_SEQ_NUM, reason=6)
+            return False
+
+        expected = self._store.next_target_msg_seq_num()
+
+        if seq_num == expected:
+            self._store.incr_next_target_msg_seq_num()
+            return True
+
+        if seq_num > expected:
+            self._log.on_event(f"MsgSeqNum gap: expected {expected}, got {seq_num} — sending ResendRequest")
+            await self._send_resend_request(expected, 0)
+            return False
+
+        # seq_num < expected
+        poss_dup = msg.header.get_or(TAG_POSS_DUP_FLAG, "N").upper() == "Y"
+        if poss_dup:
+            # Silently discard duplicate
+            return False
+
+        # Sequence number too low and not a dup — serious error
+        self._log.on_event(f"MsgSeqNum too low: expected {expected}, got {seq_num} — logging out")
+        await self._send_logout(f"MsgSeqNum too low, expected {expected} got {seq_num}")
+        return False
+
+    # ------------------------------------------------------------------
+    # Timer loop (runs as asyncio Task)
+    # ------------------------------------------------------------------
+
+    async def _timer_loop(self) -> None:
+        """Background task: drives heartbeat and test-request logic."""
+        while self._state != SessionState.DISCONNECTED:
+            await asyncio.sleep(1)
+            now = time.monotonic()
+
+            if self._state == SessionState.LOGON_TIMEOUT:
+                # Check logon timeout (initiator)
+                if (
+                    self._is_initiator
+                    and self._logon_sent_at > 0
+                    and now - self._logon_sent_at > self._logon_timeout
+                ):
+                    self._log.on_event("Logon timeout — disconnecting")
+                    self._state = SessionState.DISCONNECTED
+                continue
+
+            if self._state != SessionState.LOGGED_ON:
+                continue
+
+            # Heartbeat: send if we've been idle for HeartBtInt seconds
+            if now - self._last_send_time >= self._heartbt_int:
+                await self._send_heartbeat()
+
+            # Test request: send if we haven't received anything
+            recv_age = now - self._last_recv_time
+            if recv_age >= self._heartbt_int + 1:
+                if self._test_req_id is None:
+                    test_req_id = str(int(now))
+                    await self._send_test_request(test_req_id)
+                elif now - self._test_req_sent_at >= self._heartbt_int:
+                    self._log.on_event("TestRequest timed out — disconnecting")
+                    self._state = SessionState.DISCONNECTED

fixcore/session/session_id.py

@@ -0,0 +1,32 @@
+"""SessionID — immutable identifier for a FIX session."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SessionID:
+    """Uniquely identifies a FIX session.
+
+    Attributes
+    ----------
+    begin_string:
+        FIX version, e.g. ``"FIX.4.2"``, ``"FIX.4.4"``, ``"FIXT.1.1"``.
+    sender_comp_id:
+        SenderCompID of the local party.
+    target_comp_id:
+        TargetCompID of the remote party.
+    qualifier:
+        Optional disambiguator when two sessions share the same
+        BeginString/SenderCompID/TargetCompID triple.
+    """
+
+    begin_string: str
+    sender_comp_id: str
+    target_comp_id: str
+    qualifier: str = ""
+
+    def __str__(self) -> str:
+        base = f"{self.begin_string}:{self.sender_comp_id}->{self.target_comp_id}"
+        return f"{base}:{self.qualifier}" if self.qualifier else base