@hla4ts/session 0.1.0

package/src/timeout-timer.ts

@@ -0,0 +1,204 @@
+/**
+ * Timeout Timer
+ *
+ * Utility class to execute a callback after a timer expires.
+ * Supports extending the timeout and pausing/resuming.
+ *
+ * Can be configured as "eager" (may trigger early) or "lazy" (never triggers early).
+ */
+
+/**
+ * Timer that executes a callback after a timeout.
+ * Supports extending, pausing, and resuming.
+ */
+export class TimeoutTimer {
+  private readonly _timeoutDurationMs: number;
+  private readonly _checkIntervalMs: number;
+  private readonly _offsetTimeMs: number;
+  private _timeoutTimestampMs: number = Number.MAX_SAFE_INTEGER;
+  private _intervalHandle: ReturnType<typeof setInterval> | null = null;
+  private _onTimeout: (() => void) | null = null;
+  private _cancelled: boolean = false;
+
+  /**
+   * Create a new timeout timer.
+   *
+   * @param timeoutDurationMs - Duration until timeout in milliseconds
+   * @param eager - If true, timeout may trigger early but never late. If false, never triggers early.
+   */
+  private constructor(timeoutDurationMs: number, eager: boolean) {
+    this._timeoutDurationMs = timeoutDurationMs;
+
+    // Calculate check interval (check 6 times per timeout period)
+    const wakeUpTimesPerInterval = 6;
+    this._checkIntervalMs = Math.max(
+      1,
+      Math.floor(timeoutDurationMs / wakeUpTimesPerInterval)
+    );
+
+    // For eager mode, trigger slightly before the full timeout
+    this._offsetTimeMs = eager
+      ? this._checkIntervalMs * (wakeUpTimesPerInterval - 1)
+      : timeoutDurationMs;
+  }
+
+  /**
+   * Create a lazy timeout timer (never triggers early, may trigger late)
+   */
+  static createLazy(timeoutDurationMs: number): TimeoutTimer {
+    return new TimeoutTimer(timeoutDurationMs, false);
+  }
+
+  /**
+   * Create an eager timeout timer (may trigger early, never triggers late)
+   */
+  static createEager(timeoutDurationMs: number): TimeoutTimer {
+    return new TimeoutTimer(timeoutDurationMs, true);
+  }
+
+  /**
+   * Get the configured timeout duration
+   */
+  get timeoutDurationMs(): number {
+    return this._timeoutDurationMs;
+  }
+
+  /**
+   * Check if the timer is currently running
+   */
+  get isRunning(): boolean {
+    return this._intervalHandle !== null && !this._cancelled;
+  }
+
+  /**
+   * Start the timer with a callback to execute on timeout.
+   *
+   * @param onTimeout - Callback to execute when the timer expires
+   */
+  start(onTimeout: () => void): void {
+    if (this._timeoutDurationMs === 0) {
+      // Zero timeout means no timeout checking
+      return;
+    }
+
+    if (this._cancelled) {
+      throw new Error("Cannot start a cancelled timer");
+    }
+
+    this._onTimeout = onTimeout;
+
+    // Start the periodic check
+    this._intervalHandle = setInterval(() => {
+      this._checkTimeout();
+    }, this._checkIntervalMs);
+
+    // Set initial timeout timestamp
+    this.extend();
+  }
+
+  /**
+   * Check if the timeout has been reached
+   */
+  private _checkTimeout(): void {
+    const now = Date.now();
+    if (now >= this._timeoutTimestampMs) {
+      this.pause();
+      this._onTimeout?.();
+    }
+  }
+
+  /**
+   * Pause the timer (prevents timeout from triggering)
+   */
+  pause(): void {
+    this._timeoutTimestampMs = Number.MAX_SAFE_INTEGER;
+  }
+
+  /**
+   * Resume the timer after being paused
+   */
+  resume(): void {
+    this.extend();
+  }
+
+  /**
+   * Extend the timeout by resetting the timer
+   */
+  extend(): void {
+    this._timeoutTimestampMs = Date.now() + this._offsetTimeMs;
+  }
+
+  /**
+   * Cancel the timer permanently
+   */
+  cancel(): void {
+    this._cancelled = true;
+    if (this._intervalHandle !== null) {
+      clearInterval(this._intervalHandle);
+      this._intervalHandle = null;
+    }
+    this._onTimeout = null;
+  }
+
+  /**
+   * Get remaining time until timeout (approximate)
+   */
+  get remainingMs(): number {
+    const remaining = this._timeoutTimestampMs - Date.now();
+    return Math.max(0, remaining);
+  }
+}
+
+/**
+ * Simple one-shot timer that executes a callback after a delay.
+ * Can be cancelled before execution.
+ */
+export class OneShotTimer {
+  private _handle: ReturnType<typeof setTimeout> | null = null;
+  private _cancelled: boolean = false;
+
+  /**
+   * Schedule a callback to execute after the specified delay.
+   *
+   * @param callback - Callback to execute
+   * @param delayMs - Delay in milliseconds
+   */
+  schedule(callback: () => void, delayMs: number): void {
+    if (this._cancelled) {
+      throw new Error("Cannot schedule on a cancelled timer");
+    }
+
+    this.clear();
+    this._handle = setTimeout(() => {
+      this._handle = null;
+      if (!this._cancelled) {
+        callback();
+      }
+    }, delayMs);
+  }
+
+  /**
+   * Clear the scheduled callback without executing it
+   */
+  clear(): void {
+    if (this._handle !== null) {
+      clearTimeout(this._handle);
+      this._handle = null;
+    }
+  }
+
+  /**
+   * Cancel the timer permanently
+   */
+  cancel(): void {
+    this._cancelled = true;
+    this.clear();
+  }
+
+  /**
+   * Check if a callback is currently scheduled
+   */
+  get isScheduled(): boolean {
+    return this._handle !== null;
+  }
+}

package/src/types.ts

@@ -0,0 +1,235 @@
+/**
+ * Session Types and State Machine
+ *
+ * Defines the session state machine, options, and event types for
+ * the HLA 4 Federate Protocol session layer.
+ */
+
+/**
+ * Session states following the IEEE 1516-2025 specification.
+ *
+ * States can be divided into two categories:
+ * - **Stable states**: NEW, RUNNING, DROPPED, TERMINATED
+ * - **Transitory states**: STARTING, RESUMING, TERMINATING
+ *
+ * When in a transitory state, the thread that initiated the transition
+ * has exclusive access to the session.
+ */
+export enum SessionState {
+  /**
+   * Session instance created but not yet started.
+   * Initial state after construction.
+   */
+  NEW = "NEW",
+
+  /**
+   * Session start() has been called, establishing connection with RTI.
+   * Transitory state - caller has exclusive access.
+   */
+  STARTING = "STARTING",
+
+  /**
+   * Session is connected and running normally.
+   * HLA calls and callbacks can be exchanged.
+   */
+  RUNNING = "RUNNING",
+
+  /**
+   * Session has experienced a connection loss.
+   * Can be resumed with resume() or terminated.
+   */
+  DROPPED = "DROPPED",
+
+  /**
+   * Session is attempting to resume after a connection loss.
+   * Transitory state - caller has exclusive access.
+   */
+  RESUMING = "RESUMING",
+
+  /**
+   * Session termination has been requested.
+   * Waiting for server acknowledgment.
+   */
+  TERMINATING = "TERMINATING",
+
+  /**
+   * Session is terminated and can no longer be used.
+   * Final state - session cannot be restarted.
+   */
+  TERMINATED = "TERMINATED",
+}
+
+/**
+ * Valid state transitions for the session state machine.
+ * Maps from current state to array of valid next states.
+ */
+export const VALID_TRANSITIONS: Record<SessionState, SessionState[]> = {
+  [SessionState.NEW]: [SessionState.STARTING],
+  [SessionState.STARTING]: [SessionState.RUNNING, SessionState.TERMINATED],
+  [SessionState.RUNNING]: [SessionState.DROPPED, SessionState.TERMINATING],
+  [SessionState.DROPPED]: [
+    SessionState.RESUMING,
+    SessionState.TERMINATING,
+    SessionState.RUNNING, // Direct transition when resume succeeds quickly
+  ],
+  [SessionState.RESUMING]: [
+    SessionState.RUNNING,
+    SessionState.DROPPED,
+    SessionState.TERMINATED,
+  ],
+  [SessionState.TERMINATING]: [SessionState.TERMINATED],
+  [SessionState.TERMINATED]: [], // Terminal state
+};
+
+/**
+ * Check if a state transition is valid
+ */
+export function isValidTransition(
+  from: SessionState,
+  to: SessionState
+): boolean {
+  return VALID_TRANSITIONS[from].includes(to);
+}
+
+/**
+ * Check if a state allows operations (sending messages)
+ */
+export function isOperationalState(state: SessionState): boolean {
+  return (
+    state === SessionState.RUNNING ||
+    state === SessionState.DROPPED ||
+    state === SessionState.RESUMING
+  );
+}
+
+/**
+ * Session configuration options
+ */
+export interface SessionOptions {
+  /**
+   * Timeout for initial connection response (milliseconds).
+   * @default 30000
+   */
+  connectionTimeout?: number;
+
+  /**
+   * Timeout for responses from the server (milliseconds).
+   * The session will be considered lost if no response is received within this time.
+   * @default 180000 (3 minutes)
+   */
+  responseTimeout?: number;
+
+  /**
+   * Maximum number of connection retry attempts.
+   * @default 3
+   */
+  maxRetryAttempts?: number;
+
+  /**
+   * Size of the message queue for outgoing messages.
+   * @default 1000
+   */
+  messageQueueSize?: number;
+
+  /**
+   * Enable rate limiting for outgoing messages.
+   * @default false
+   */
+  rateLimitEnabled?: boolean;
+
+  /**
+   * Interval between heartbeat checks (milliseconds).
+   * @default 10000 (10 seconds)
+   */
+  heartbeatInterval?: number;
+}
+
+/**
+ * Default session options
+ */
+export const DEFAULT_SESSION_OPTIONS: Required<SessionOptions> = {
+  connectionTimeout: 30000,
+  responseTimeout: 180000,
+  maxRetryAttempts: 3,
+  messageQueueSize: 1000,
+  rateLimitEnabled: false,
+  heartbeatInterval: 10000,
+};
+
+/**
+ * Callback invoked when an HLA callback request is received from the RTI
+ */
+export interface HlaCallbackRequestListener {
+  /**
+   * Handle an incoming HLA callback from the RTI.
+   *
+   * @param sequenceNumber - The sequence number of the callback request
+   * @param hlaCallback - The encoded callback data (protobuf CallbackRequest)
+   */
+  onHlaCallbackRequest(sequenceNumber: number, hlaCallback: Uint8Array): void;
+}
+
+/**
+ * Callback invoked when the session state changes
+ */
+export interface SessionStateListener {
+  /**
+   * Handle a session state transition.
+   *
+   * @param oldState - The previous session state
+   * @param newState - The new session state
+   * @param reason - Description of why the transition occurred
+   */
+  onStateTransition(
+    oldState: SessionState,
+    newState: SessionState,
+    reason: string
+  ): void;
+}
+
+/**
+ * Callback invoked when a message is sent
+ */
+export interface MessageSentListener {
+  /**
+   * Called when a message has been sent to the server.
+   * Can be used to implement heartbeat logic.
+   */
+  onMessageSent(): void;
+}
+
+/**
+ * Session statistics
+ */
+export interface SessionStats {
+  /** Total HLA calls sent */
+  hlaCallCount: number;
+  /** Total HLA callbacks received */
+  hlaCallbackCount: number;
+  /** Number of times the session was resumed */
+  resumeCount: number;
+  /** Number of messages in the call request queue */
+  callRequestQueueLength: number;
+  /** Number of messages in the callback response queue */
+  callbackResponseQueueLength: number;
+  /** Number of HLA calls awaiting response */
+  pendingRequestCount: number;
+}
+
+/**
+ * New session status message payload structure
+ */
+export interface NewSessionStatusPayload {
+  /** Status code (0 = success) */
+  status: number;
+}
+
+/**
+ * Resume status message payload structure
+ */
+export interface ResumeStatusPayload {
+  /** Status code (0 = success) */
+  status: number;
+  /** Last sequence number received by the server */
+  lastReceivedFederateSequenceNumber: number;
+}