@hla4ts/session 0.1.0

package/src/session.ts

@@ -0,0 +1,976 @@
+/**
+ * Federate Protocol Session
+ *
+ * Manages the lifecycle of a Federate Protocol session, including:
+ * - Connection establishment and termination
+ * - Session state machine
+ * - Request/response correlation
+ * - Heartbeat/keepalive
+ * - Session resumption after disconnection
+ */
+
+import {
+  type Transport,
+  type ReceivedMessage,
+  MessageType,
+  NO_SESSION_ID,
+  NewSessionStatus,
+} from "@hla4ts/transport";
+
+import {
+  SessionState,
+  isValidTransition,
+  isOperationalState,
+  type SessionOptions,
+  type HlaCallbackRequestListener,
+  type SessionStateListener,
+  type MessageSentListener,
+  DEFAULT_SESSION_OPTIONS,
+} from "./types.ts";
+
+import {
+  SequenceNumber,
+  AtomicSequenceNumber,
+  INITIAL_SEQUENCE_NUMBER,
+  NO_SEQUENCE_NUMBER,
+  isValidSequenceNumber,
+  nextSequenceNumber,
+} from "./sequence-number.ts";
+
+import { TimeoutTimer } from "./timeout-timer.ts";
+
+import {
+  createNewSessionMessage,
+  decodeNewSessionStatus,
+  createResumeRequestMessage,
+  decodeResumeStatus,
+  ResumeStatusCode,
+  createHeartbeatMessage,
+  decodeHeartbeatResponse,
+  createTerminateSessionMessage,
+  createHlaCallRequestMessage,
+  decodeHlaCallResponse,
+  decodeHlaCallbackRequest,
+  createHlaCallbackResponseMessage,
+} from "./messages.ts";
+
+import {
+  SessionLostError,
+  SessionAlreadyTerminatedError,
+  SessionIllegalStateError,
+  BadMessageError,
+  ConnectionTimeoutError,
+} from "./errors.ts";
+
+/**
+ * Deferred promise helper for request/response correlation
+ */
+interface DeferredPromise<T> {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (reason: Error) => void;
+}
+
+function createDeferred<T>(): DeferredPromise<T> {
+  let resolve!: (value: T) => void;
+  let reject!: (reason: Error) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+/**
+ * Federate Protocol Session
+ *
+ * Manages a session with an HLA 4 RTI using the Federate Protocol.
+ *
+ * @example
+ * ```ts
+ * const transport = new TlsTransport({ host: 'rti.example.com', port: 15165 });
+ * const session = new Session(transport);
+ *
+ * session.addStateListener((oldState, newState, reason) => {
+ *   console.log(`State: ${oldState} -> ${newState} (${reason})`);
+ * });
+ *
+ * await session.start({
+ *   onHlaCallbackRequest: (seqNum, callback) => {
+ *     // Handle callback
+ *     session.sendHlaCallbackResponse(seqNum, response);
+ *   }
+ * });
+ *
+ * // Send HLA calls
+ * const response = await session.sendHlaCallRequest(encodedCall);
+ *
+ * // When done
+ * await session.terminate();
+ * ```
+ */
+export class Session {
+  private readonly _transport: Transport;
+  private readonly _options: Required<SessionOptions>;
+
+  // Session state
+  private _state: SessionState = SessionState.NEW;
+  private _sessionId: bigint = NO_SESSION_ID;
+
+  // Sequence number tracking
+  private readonly _nextOutgoingSeqNum = new SequenceNumber(INITIAL_SEQUENCE_NUMBER);
+  private readonly _lastReceivedSeqNum = new AtomicSequenceNumber(NO_SEQUENCE_NUMBER);
+
+  // Request/response correlation
+  private readonly _pendingRequests = new Map<number, DeferredPromise<Uint8Array>>();
+  private _terminationDeferred: DeferredPromise<void> | null = null;
+
+  // Timers
+  private _sessionTimeoutTimer: TimeoutTimer | null = null;
+  private _connectionTimeoutTimer: TimeoutTimer | null = null;
+  private _heartbeatIntervalHandle: ReturnType<typeof setInterval> | null = null;
+
+  // Callbacks
+  private _hlaCallbackListener: HlaCallbackRequestListener | null = null;
+  private readonly _stateListeners: SessionStateListener[] = [];
+  private _messageSentListener: MessageSentListener | null = null;
+
+  // Message history for resumption
+  private readonly _sentMessageHistory: Map<number, Uint8Array> = new Map();
+  private _oldestHistorySeqNum: number = INITIAL_SEQUENCE_NUMBER;
+
+  /**
+   * Create a new session.
+   *
+   * @param transport - The transport to use for communication
+   * @param options - Session configuration options
+   */
+  constructor(transport: Transport, options: SessionOptions = {}) {
+    this._transport = transport;
+    this._options = { ...DEFAULT_SESSION_OPTIONS, ...options };
+  }
+
+  // ==========================================================================
+  // Public API
+  // ==========================================================================
+
+  /**
+   * Get the session ID (0 if not yet established)
+   */
+  get id(): bigint {
+    return this._sessionId;
+  }
+
+  /**
+   * Get the current session state
+   */
+  get state(): SessionState {
+    return this._state;
+  }
+
+  /**
+   * Check if the session is in a state where operations are allowed
+   */
+  get isOperational(): boolean {
+    return isOperationalState(this._state);
+  }
+
+  /**
+   * Add a state change listener
+   */
+  addStateListener(listener: SessionStateListener): void {
+    this._stateListeners.push(listener);
+  }
+
+  /**
+   * Set the message sent listener
+   */
+  setMessageSentListener(listener: MessageSentListener): void {
+    this._messageSentListener = listener;
+  }
+
+  /**
+   * Start the session by connecting to the RTI and establishing a new session.
+   *
+   * @param callbackListener - Handler for incoming HLA callbacks
+   * @throws SessionLostError if the connection cannot be established
+   * @throws SessionIllegalStateError if not in NEW state
+   */
+  async start(callbackListener: HlaCallbackRequestListener): Promise<void> {
+    // Validate state
+    const beforeState = this._compareAndSetState(
+      SessionState.NEW,
+      SessionState.STARTING,
+      "Starting session"
+    );
+
+    if (beforeState === SessionState.TERMINATED) {
+      throw new SessionAlreadyTerminatedError("Cannot start a terminated session");
+    }
+    if (beforeState !== SessionState.NEW) {
+      throw new SessionIllegalStateError(beforeState, "start");
+    }
+
+    this._hlaCallbackListener = callbackListener;
+
+    try {
+      await this._performConnect();
+    } catch (error) {
+      this._compareAndSetState(
+        SessionState.STARTING,
+        SessionState.TERMINATED,
+        `Connection failed: ${error}`
+      );
+      throw error;
+    }
+
+    // Start session timeout timer
+    this._sessionTimeoutTimer = TimeoutTimer.createLazy(this._options.responseTimeout);
+    this._sessionTimeoutTimer.start(() => this._handleSessionTimeout());
+
+    // Start periodic heartbeat sending
+    this._startHeartbeatTimer();
+
+    // Transition to running
+    this._compareAndSetState(SessionState.STARTING, SessionState.RUNNING, "Session established");
+  }
+
+  /**
+   * Resume a dropped session.
+   *
+   * @returns true if resume succeeded
+   * @throws SessionLostError if the server refuses to resume
+   * @throws SessionIllegalStateError if not in DROPPED state
+   */
+  async resume(): Promise<boolean> {
+    const beforeState = this._compareAndSetState(
+      SessionState.DROPPED,
+      SessionState.RESUMING,
+      "Attempting resume"
+    );
+
+    if (beforeState === SessionState.TERMINATED) {
+      throw new SessionAlreadyTerminatedError("Cannot resume a terminated session");
+    }
+    if (beforeState !== SessionState.DROPPED) {
+      throw new SessionIllegalStateError(beforeState, "resume");
+    }
+
+    try {
+      await this._performResume();
+      // Restart heartbeat timer after resume
+      this._startHeartbeatTimer();
+      this._compareAndSetState(SessionState.RESUMING, SessionState.RUNNING, "Session resumed");
+      return true;
+    } catch (error) {
+      if (error instanceof SessionLostError) {
+        this._compareAndSetState(
+          SessionState.RESUMING,
+          SessionState.TERMINATED,
+          `Resume failed: ${error.message}`
+        );
+        throw error;
+      }
+      // Network error - back to dropped state
+      this._compareAndSetState(
+        SessionState.RESUMING,
+        SessionState.DROPPED,
+        `Resume connection failed: ${error}`
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Send a heartbeat message.
+   *
+   * @returns Promise that resolves when the heartbeat response is received
+   * @throws SessionIllegalStateError if not in operational state
+   */
+  async sendHeartbeat(): Promise<void> {
+    this._validateOperationalState("send heartbeat");
+
+    const seqNum = this._nextOutgoingSeqNum.getAndIncrement();
+    const message = createHeartbeatMessage(
+      seqNum,
+      this._sessionId,
+      this._lastReceivedSeqNum.get()
+    );
+
+    const deferred = createDeferred<Uint8Array>();
+    this._pendingRequests.set(seqNum, deferred);
+
+    try {
+      await this._sendMessage(message, seqNum);
+      await deferred.promise;
+    } finally {
+      this._pendingRequests.delete(seqNum);
+    }
+  }
+
+  /**
+   * Send an HLA call request.
+   *
+   * @param encodedHlaCall - Protobuf-encoded HLA call request
+   * @returns Promise that resolves with the protobuf-encoded response
+   * @throws SessionIllegalStateError if not in operational state
+   */
+  async sendHlaCallRequest(encodedHlaCall: Uint8Array): Promise<Uint8Array> {
+    this._validateOperationalState("send HLA call");
+
+    const seqNum = this._nextOutgoingSeqNum.getAndIncrement();
+    const message = createHlaCallRequestMessage(
+      seqNum,
+      this._sessionId,
+      this._lastReceivedSeqNum.get(),
+      encodedHlaCall
+    );
+
+    const deferred = createDeferred<Uint8Array>();
+    this._pendingRequests.set(seqNum, deferred);
+
+    try {
+      await this._sendMessage(message, seqNum);
+      return await deferred.promise;
+    } catch (error) {
+      this._pendingRequests.delete(seqNum);
+      throw error;
+    }
+  }
+
+  /**
+   * Send an HLA callback response.
+   *
+   * @param responseToSequenceNumber - Sequence number of the callback request
+   * @param encodedResponse - Protobuf-encoded callback response
+   * @throws SessionIllegalStateError if not in operational state
+   */
+  async sendHlaCallbackResponse(
+    responseToSequenceNumber: number,
+    encodedResponse: Uint8Array
+  ): Promise<void> {
+    this._validateOperationalState("send callback response");
+
+    const seqNum = this._nextOutgoingSeqNum.getAndIncrement();
+    const message = createHlaCallbackResponseMessage(
+      seqNum,
+      this._sessionId,
+      this._lastReceivedSeqNum.get(),
+      responseToSequenceNumber,
+      encodedResponse
+    );
+
+    await this._sendMessage(message, seqNum);
+  }
+
+  /**
+   * Terminate the session gracefully.
+   *
+   * @param timeoutMs - Timeout for termination (default: responseTimeout)
+   * @throws SessionLostError if termination times out
+   * @throws SessionIllegalStateError if in invalid state
+   */
+  async terminate(timeoutMs?: number): Promise<void> {
+    const timeout = timeoutMs ?? this._options.responseTimeout;
+
+    // Wait if resuming
+    if (this._state === SessionState.RESUMING) {
+      await this._waitForStateChange();
+    }
+
+    // If already terminated, nothing to do
+    if (this._state === SessionState.TERMINATED) {
+      return;
+    }
+
+    const beforeState = this._compareAndSetState(
+      SessionState.RUNNING,
+      SessionState.TERMINATING,
+      "Terminating session"
+    );
+
+    // Handle DROPPED state
+    if (beforeState === SessionState.DROPPED) {
+      this._compareAndSetState(
+        SessionState.DROPPED,
+        SessionState.TERMINATED,
+        "Terminated dropped session"
+      );
+      return;
+    }
+
+    if (beforeState !== SessionState.RUNNING) {
+      throw new SessionIllegalStateError(beforeState, "terminate");
+    }
+
+    // Send termination message
+    this._terminationDeferred = createDeferred<void>();
+    const seqNum = this._nextOutgoingSeqNum.getAndIncrement();
+    const message = createTerminateSessionMessage(
+      seqNum,
+      this._sessionId,
+      this._lastReceivedSeqNum.get()
+    );
+
+    try {
+      await this._sendMessage(message, seqNum);
+
+      // Wait for termination response with timeout
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        setTimeout(
+          () => reject(new SessionLostError("Termination timed out")),
+          timeout
+        );
+      });
+
+      await Promise.race([this._terminationDeferred.promise, timeoutPromise]);
+    } catch (error) {
+      // Session is terminated either way
+      throw error;
+    } finally {
+      this._compareAndSetState(
+        SessionState.TERMINATING,
+        SessionState.TERMINATED,
+        "Session terminated"
+      );
+      this._cleanup();
+    }
+  }
+
+  // ==========================================================================
+  // Connection and Session Establishment
+  // ==========================================================================
+
+  /**
+   * Perform the initial connection and session establishment
+   */
+  private async _performConnect(): Promise<void> {
+    // Set up transport handlers
+    this._transport.setEventHandlers({
+      onMessage: (msg) => this._handleMessage(msg),
+      onClose: (hadError) => this._handleDisconnect(hadError),
+      onError: (err) => this._handleTransportError(err),
+    });
+
+    // Connect with timeout
+    const connectionTimeout = this._options.connectionTimeout;
+    this._connectionTimeoutTimer = TimeoutTimer.createLazy(connectionTimeout);
+
+    let connectionPromise: Promise<void>;
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      this._connectionTimeoutTimer!.start(() => {
+        reject(new ConnectionTimeoutError(connectionTimeout));
+      });
+    });
+
+    try {
+      // Connect to transport
+      connectionPromise = this._transport.connect();
+      await Promise.race([connectionPromise, timeoutPromise]);
+
+      // Send new session message
+      const newSessionMsg = createNewSessionMessage();
+      await this._transport.send(newSessionMsg);
+
+      // Wait for new session status response
+      const statusResponse = await this._waitForNewSessionStatus();
+      
+      if (statusResponse.status !== NewSessionStatus.SUCCESS) {
+        throw new SessionLostError(
+          `Server unable to create session, reason: ${statusResponse.status}`
+        );
+      }
+    } finally {
+      this._connectionTimeoutTimer?.cancel();
+      this._connectionTimeoutTimer = null;
+    }
+  }
+
+  /**
+   * Wait for the CTRL_NEW_SESSION_STATUS response
+   */
+  private _waitForNewSessionStatus(): Promise<{ status: number; sessionId: bigint }> {
+    return new Promise((resolve, reject) => {
+      const restoreHandlers = () => {
+        // Restore normal message handlers after handshake
+        this._transport.setEventHandlers({
+          onMessage: (msg) => this._handleMessage(msg),
+          onClose: (hadError) => this._handleDisconnect(hadError),
+          onError: (err) => this._handleTransportError(err),
+        });
+      };
+
+      const handleStatus = (msg: ReceivedMessage) => {
+        if (msg.header.messageType === MessageType.CTRL_NEW_SESSION_STATUS) {
+          const status = decodeNewSessionStatus(msg.payload);
+          this._sessionId = msg.header.sessionId;
+          this._extendSessionTimer();
+          restoreHandlers(); // Restore handlers before resolving
+          resolve({ status, sessionId: msg.header.sessionId });
+        } else {
+          restoreHandlers(); // Restore handlers before rejecting
+          reject(new BadMessageError(
+            `Expected CTRL_NEW_SESSION_STATUS, got ${MessageType[msg.header.messageType]}`
+          ));
+        }
+      };
+
+      // Temporarily replace handler for handshake
+      this._transport.setEventHandlers({
+        onMessage: handleStatus,
+        onClose: () => {
+          restoreHandlers();
+          reject(new SessionLostError("Connection closed during handshake"));
+        },
+        onError: (err) => {
+          restoreHandlers();
+          reject(new SessionLostError(`Transport error: ${err.message}`, err));
+        },
+      });
+    });
+  }
+
+  /**
+   * Perform session resumption
+   */
+  private async _performResume(): Promise<void> {
+    const lastReceivedRtiMessage = this._lastReceivedSeqNum.get();
+    const oldestAvailableFederateMessage = this._oldestHistorySeqNum;
+
+    // Reconnect transport
+    await this._transport.connect();
+
+    // Send resume request
+    const resumeMsg = createResumeRequestMessage(
+      this._sessionId,
+      lastReceivedRtiMessage,
+      oldestAvailableFederateMessage
+    );
+    await this._transport.send(resumeMsg);
+
+    // Resume session timer
+    this._sessionTimeoutTimer?.resume();
+
+    // Wait for resume status
+    const statusResponse = await this._waitForResumeStatus();
+
+    if (statusResponse.status !== ResumeStatusCode.OK_TO_RESUME) {
+      throw new SessionLostError(
+        `Server refused to resume session, status: ${statusResponse.status}`
+      );
+    }
+
+    // Retransmit messages that the server hasn't received
+    const resumeFromNumber = nextSequenceNumber(statusResponse.lastReceivedFederateSequenceNumber);
+    await this._retransmitMessages(resumeFromNumber);
+  }
+
+  /**
+   * Wait for CTRL_RESUME_STATUS response
+   */
+  private _waitForResumeStatus(): Promise<{ status: number; lastReceivedFederateSequenceNumber: number }> {
+    return new Promise((resolve, reject) => {
+      const restoreHandlers = () => {
+        // Restore normal message handlers after resume handshake
+        this._transport.setEventHandlers({
+          onMessage: (msg) => this._handleMessage(msg),
+          onClose: (hadError) => this._handleDisconnect(hadError),
+          onError: (err) => this._handleTransportError(err),
+        });
+      };
+
+      const handleStatus = (msg: ReceivedMessage) => {
+        if (msg.header.messageType === MessageType.CTRL_RESUME_STATUS) {
+          this._extendSessionTimer();
+          const result = decodeResumeStatus(msg.payload);
+          restoreHandlers(); // Restore handlers before resolving
+          resolve(result);
+        } else {
+          restoreHandlers(); // Restore handlers before rejecting
+          reject(new BadMessageError(
+            `Expected CTRL_RESUME_STATUS, got ${MessageType[msg.header.messageType]}`
+          ));
+        }
+      };
+
+      this._transport.setEventHandlers({
+        onMessage: handleStatus,
+        onClose: () => {
+          restoreHandlers();
+          reject(new SessionLostError("Connection closed during resume"));
+        },
+        onError: (err) => {
+          restoreHandlers();
+          reject(new SessionLostError(`Transport error: ${err.message}`, err));
+        },
+      });
+    });
+  }
+
+  /**
+   * Retransmit messages from the history
+   */
+  private async _retransmitMessages(fromSeqNum: number): Promise<void> {
+    if (!isValidSequenceNumber(fromSeqNum)) {
+      // Retransmit all
+      for (const [_, message] of this._sentMessageHistory) {
+        await this._transport.send(message);
+      }
+      return;
+    }
+
+    // Find and retransmit starting from the specified sequence number
+    for (const [seqNum, message] of this._sentMessageHistory) {
+      if (seqNum >= fromSeqNum) {
+        await this._transport.send(message);
+      }
+    }
+  }
+
+  // ==========================================================================
+  // Message Handling
+  // ==========================================================================
+
+  /**
+   * Handle an incoming message from the transport
+   */
+  private _handleMessage(msg: ReceivedMessage): void {
+    const { header, payload } = msg;
+
+    // Validate session ID (except for CTRL_NEW_SESSION_STATUS which sets it)
+    if (
+      header.messageType !== MessageType.CTRL_NEW_SESSION_STATUS &&
+      header.sessionId !== this._sessionId
+    ) {
+      this._handleBadMessage(`Wrong session ID: ${header.sessionId}, expected ${this._sessionId}`);
+      return;
+    }
+
+    // Validate sequence number for non-control messages
+    if (
+      header.messageType >= MessageType.HLA_CALL_REQUEST &&
+      !isValidSequenceNumber(header.sequenceNumber)
+    ) {
+      this._handleBadMessage(`Invalid sequence number: ${header.sequenceNumber}`);
+      return;
+    }
+
+    switch (header.messageType) {
+      case MessageType.CTRL_HEARTBEAT_RESPONSE:
+        this._handleHeartbeatResponse(payload);
+        break;
+
+      case MessageType.CTRL_SESSION_TERMINATED:
+        this._handleSessionTerminated();
+        break;
+
+      case MessageType.HLA_CALL_RESPONSE:
+        this._handleHlaCallResponse(header.sequenceNumber, payload);
+        break;
+
+      case MessageType.HLA_CALLBACK_REQUEST:
+        this._handleHlaCallbackRequest(header.sequenceNumber, payload);
+        break;
+
+      default:
+        this._handleBadMessage(`Unexpected message type: ${header.messageType}`);
+    }
+  }
+
+  /**
+   * Handle heartbeat response
+   */
+  private _handleHeartbeatResponse(payload: Uint8Array): void {
+    this._extendSessionTimer();
+    const responseToSeqNum = decodeHeartbeatResponse(payload);
+    const deferred = this._pendingRequests.get(responseToSeqNum);
+    if (deferred) {
+      this._pendingRequests.delete(responseToSeqNum);
+      deferred.resolve(new Uint8Array(0));
+    }
+  }
+
+  /**
+   * Handle session terminated message
+   */
+  private _handleSessionTerminated(): void {
+    this._extendSessionTimer();
+    if (this._terminationDeferred) {
+      this._terminationDeferred.resolve();
+      this._terminationDeferred = null;
+    }
+  }
+
+  /**
+   * Handle HLA call response
+   */
+  private _handleHlaCallResponse(sequenceNumber: number, payload: Uint8Array): void {
+    this._trackHlaMessageReceived(sequenceNumber);
+    const response = decodeHlaCallResponse(payload);
+    const deferred = this._pendingRequests.get(response.responseToSequenceNumber);
+    if (deferred) {
+      this._pendingRequests.delete(response.responseToSequenceNumber);
+      deferred.resolve(response.hlaServiceReturnValueOrException);
+    }
+  }
+
+  /**
+   * Handle HLA callback request
+   */
+  private _handleHlaCallbackRequest(sequenceNumber: number, payload: Uint8Array): void {
+    const callback = decodeHlaCallbackRequest(payload);
+    this._hlaCallbackListener?.onHlaCallbackRequest(
+      sequenceNumber,
+      callback.hlaServiceCallbackWithParams
+    );
+    this._trackHlaMessageReceived(sequenceNumber);
+  }
+
+  /**
+   * Handle a bad message
+   */
+  private _handleBadMessage(reason: string): void {
+    console.error(`[Session ${this._sessionId}] Bad message: ${reason}`);
+    
+    // Schedule best-effort termination
+    this.terminate(0).catch(() => {
+      // Ignore termination errors
+    });
+  }
+
+  /**
+   * Track that we received an HLA message
+   */
+  private _trackHlaMessageReceived(sequenceNumber: number): void {
+    this._extendSessionTimer();
+    if (isValidSequenceNumber(sequenceNumber)) {
+      this._lastReceivedSeqNum.set(sequenceNumber);
+    }
+  }
+
+  // ==========================================================================
+  // Transport Events
+  // ==========================================================================
+
+  /**
+   * Handle transport disconnection
+   */
+  private _handleDisconnect(hadError: boolean): void {
+    // If we're in TERMINATING state and get an EOF, complete the termination
+    if (this._state === SessionState.TERMINATING) {
+      this._terminationDeferred?.resolve();
+      return;
+    }
+
+    // Transition to DROPPED if running
+    const oldState = this._compareAndSetState(
+      SessionState.RUNNING,
+      SessionState.DROPPED,
+      hadError ? "Connection lost with error" : "Connection closed"
+    );
+
+    if (oldState === SessionState.RUNNING) {
+      this._sessionTimeoutTimer?.pause();
+      this._stopHeartbeatTimer();
+    }
+  }
+
+  /**
+   * Handle transport error
+   */
+  private _handleTransportError(error: Error): void {
+    console.error(`[Session ${this._sessionId}] Transport error:`, error);
+    this._handleDisconnect(true);
+  }
+
+  // ==========================================================================
+  // Timer Management
+  // ==========================================================================
+
+  /**
+   * Handle session timeout
+   */
+  private _handleSessionTimeout(): void {
+    console.error(
+      `[Session ${this._sessionId}] Session timed out after ${this._options.responseTimeout}ms`
+    );
+    this._transport.disconnect().catch(() => {
+      // Ignore disconnect errors
+    });
+  }
+
+  /**
+   * Extend the session timeout timer
+   */
+  private _extendSessionTimer(): void {
+    this._sessionTimeoutTimer?.extend();
+  }
+
+  /**
+   * Start the periodic heartbeat timer
+   */
+  private _startHeartbeatTimer(): void {
+    // Clear any existing timer
+    this._stopHeartbeatTimer();
+
+    // Only start if heartbeat interval is configured and > 0
+    if (this._options.heartbeatInterval <= 0) {
+      return;
+    }
+
+    // Send heartbeats at regular intervals
+    this._heartbeatIntervalHandle = setInterval(() => {
+      // Only send heartbeat if we're in an operational state
+      if (this.isOperational) {
+        this.sendHeartbeat().catch((error) => {
+          // Log but don't throw - heartbeat failures shouldn't crash the session
+          // The timeout timer will handle detecting if the connection is truly dead
+          console.error(`[Session ${this._sessionId}] Heartbeat failed:`, error);
+        });
+      }
+    }, this._options.heartbeatInterval);
+  }
+
+  /**
+   * Stop the periodic heartbeat timer
+   */
+  private _stopHeartbeatTimer(): void {
+    if (this._heartbeatIntervalHandle !== null) {
+      clearInterval(this._heartbeatIntervalHandle);
+      this._heartbeatIntervalHandle = null;
+    }
+  }
+
+  // ==========================================================================
+  // State Management
+  // ==========================================================================
+
+  /**
+   * Compare and set state atomically
+   */
+  private _compareAndSetState(
+    expectedState: SessionState,
+    newState: SessionState,
+    reason: string
+  ): SessionState {
+    const oldState = this._state;
+    if (oldState !== expectedState) {
+      return oldState;
+    }
+
+    if (!isValidTransition(oldState, newState)) {
+      console.warn(`Invalid state transition: ${oldState} -> ${newState}`);
+      return oldState;
+    }
+
+    this._state = newState;
+    this._fireStateTransition(oldState, newState, reason);
+
+    // Handle cleanup on terminal state
+    if (newState === SessionState.TERMINATED) {
+      this._cleanup();
+    }
+
+    return oldState;
+  }
+
+  /**
+   * Fire state transition to listeners
+   */
+  private _fireStateTransition(
+    oldState: SessionState,
+    newState: SessionState,
+    reason: string
+  ): void {
+    for (const listener of this._stateListeners) {
+      try {
+        listener.onStateTransition(oldState, newState, reason);
+      } catch (error) {
+        console.error("Error in state listener:", error);
+      }
+    }
+  }
+
+  /**
+   * Validate that we're in an operational state
+   */
+  private _validateOperationalState(operation: string): void {
+    if (this._state === SessionState.TERMINATED) {
+      throw new SessionAlreadyTerminatedError();
+    }
+    if (!isOperationalState(this._state)) {
+      throw new SessionIllegalStateError(this._state, operation);
+    }
+  }
+
+  /**
+   * Wait for a state change
+   */
+  private _waitForStateChange(): Promise<SessionState> {
+    return new Promise((resolve) => {
+      const listener: SessionStateListener = {
+        onStateTransition: (_, newState) => {
+          resolve(newState);
+        },
+      };
+      this._stateListeners.push(listener);
+    });
+  }
+
+  // ==========================================================================
+  // Utilities
+  // ==========================================================================
+
+  /**
+   * Send a message and store in history for potential retransmission
+   */
+  private async _sendMessage(message: Uint8Array, seqNum: number): Promise<void> {
+    // Store in history
+    this._sentMessageHistory.set(seqNum, message);
+    
+    // Trim old history entries if needed (keep last 1000)
+    const maxHistorySize = 1000;
+    if (this._sentMessageHistory.size > maxHistorySize) {
+      const oldestToKeep = seqNum - maxHistorySize;
+      for (const [histSeqNum] of this._sentMessageHistory) {
+        if (histSeqNum < oldestToKeep) {
+          this._sentMessageHistory.delete(histSeqNum);
+          this._oldestHistorySeqNum = Math.max(this._oldestHistorySeqNum, histSeqNum + 1);
+        }
+      }
+    }
+
+    await this._transport.send(message);
+    this._messageSentListener?.onMessageSent();
+  }
+
+  /**
+   * Clean up resources on termination
+   */
+  private _cleanup(): void {
+    // Stop heartbeat timer
+    this._stopHeartbeatTimer();
+
+    // Cancel timers
+    this._sessionTimeoutTimer?.cancel();
+    this._sessionTimeoutTimer = null;
+    this._connectionTimeoutTimer?.cancel();
+    this._connectionTimeoutTimer = null;
+
+    // Fail all pending requests
+    const error = new SessionLostError("Session terminated");
+    for (const [_, deferred] of this._pendingRequests) {
+      deferred.reject(error);
+    }
+    this._pendingRequests.clear();
+
+    // Clear history
+    this._sentMessageHistory.clear();
+
+    // Disconnect transport
+    this._transport.disconnect().catch(() => {
+      // Ignore disconnect errors
+    });
+  }
+
+}