@hla4ts/session 0.1.0

package/src/messages.ts

@@ -0,0 +1,329 @@
+/**
+ * Session Message Encoding/Decoding
+ *
+ * Handles encoding and decoding of Federate Protocol session control messages.
+ * These are the messages used for session management (not HLA calls/callbacks).
+ */
+
+import {
+  encodeMessage,
+  MessageType,
+  FEDERATE_PROTOCOL_VERSION,
+  NO_SESSION_ID,
+  type MessageHeader,
+} from "@hla4ts/transport";
+import {
+  INITIAL_SEQUENCE_NUMBER,
+  NO_SEQUENCE_NUMBER as SEQ_NO_SEQUENCE_NUMBER,
+} from "./sequence-number.ts";
+
+// Size of a 32-bit integer in bytes
+const INT32_SIZE = 4;
+
+/**
+ * Create a CTRL_NEW_SESSION message to initiate a new session.
+ *
+ * Payload format:
+ * - protocolVersion (4 bytes, big-endian)
+ *
+ * @returns Encoded message ready to send
+ */
+export function createNewSessionMessage(): Uint8Array {
+  const payload = new Uint8Array(INT32_SIZE);
+  const view = new DataView(payload.buffer);
+  view.setUint32(0, FEDERATE_PROTOCOL_VERSION, false); // big-endian
+
+  return encodeMessage(
+    INITIAL_SEQUENCE_NUMBER,
+    NO_SESSION_ID,
+    SEQ_NO_SEQUENCE_NUMBER,
+    MessageType.CTRL_NEW_SESSION,
+    payload
+  );
+}
+
+/**
+ * Decode a CTRL_NEW_SESSION_STATUS response.
+ *
+ * Payload format:
+ * - reason (4 bytes, big-endian) - 0 = success
+ *
+ * @param payload - The message payload
+ * @returns Status code (0 = success)
+ */
+export function decodeNewSessionStatus(payload: Uint8Array): number {
+  if (payload.length < INT32_SIZE) {
+    throw new Error(
+      `NewSessionStatus payload too small: ${payload.length} bytes`
+    );
+  }
+  const view = new DataView(payload.buffer, payload.byteOffset);
+  return view.getUint32(0, false); // big-endian
+}
+
+/**
+ * Create a CTRL_RESUME_REQUEST message to resume a dropped session.
+ *
+ * Payload format:
+ * - lastReceivedSequenceNumber (4 bytes, big-endian)
+ * - oldestAvailableSequenceNumber (4 bytes, big-endian)
+ *
+ * @param sessionId - The session ID to resume
+ * @param lastReceivedSequenceNumber - Last sequence number received from RTI
+ * @param oldestAvailableSequenceNumber - Oldest message still available for retransmission
+ * @returns Encoded message ready to send
+ */
+export function createResumeRequestMessage(
+  sessionId: bigint,
+  lastReceivedSequenceNumber: number,
+  oldestAvailableSequenceNumber: number
+): Uint8Array {
+  const payload = new Uint8Array(INT32_SIZE * 2);
+  const view = new DataView(payload.buffer);
+  view.setUint32(0, lastReceivedSequenceNumber, false);
+  view.setUint32(4, oldestAvailableSequenceNumber, false);
+
+  return encodeMessage(
+    SEQ_NO_SEQUENCE_NUMBER,
+    sessionId,
+    lastReceivedSequenceNumber,
+    MessageType.CTRL_RESUME_REQUEST,
+    payload
+  );
+}
+
+/**
+ * Decoded resume status response
+ */
+export interface ResumeStatusResult {
+  /** Status code (0 = success) */
+  status: number;
+  /** Last sequence number the server received from us */
+  lastReceivedFederateSequenceNumber: number;
+}
+
+/**
+ * Resume status codes
+ */
+export const ResumeStatusCode = {
+  /** Resume successful */
+  OK_TO_RESUME: 0,
+  /** Session not found (expired or invalid) */
+  SESSION_NOT_FOUND: 1,
+  /** Resume not allowed */
+  NOT_ALLOWED: 2,
+} as const;
+
+/**
+ * Decode a CTRL_RESUME_STATUS response.
+ *
+ * Payload format:
+ * - status (4 bytes, big-endian)
+ * - lastReceivedFederateSequenceNumber (4 bytes, big-endian)
+ *
+ * @param payload - The message payload
+ * @returns Decoded resume status
+ */
+export function decodeResumeStatus(payload: Uint8Array): ResumeStatusResult {
+  if (payload.length < INT32_SIZE * 2) {
+    throw new Error(`ResumeStatus payload too small: ${payload.length} bytes`);
+  }
+  const view = new DataView(payload.buffer, payload.byteOffset);
+  return {
+    status: view.getUint32(0, false),
+    lastReceivedFederateSequenceNumber: view.getUint32(4, false),
+  };
+}
+
+/**
+ * Create a CTRL_HEARTBEAT message.
+ *
+ * No payload - the header contains all necessary information.
+ *
+ * @param sequenceNumber - Sequence number for this heartbeat
+ * @param sessionId - Current session ID
+ * @param lastReceivedSequenceNumber - Last sequence number received from RTI
+ * @returns Encoded message ready to send
+ */
+export function createHeartbeatMessage(
+  sequenceNumber: number,
+  sessionId: bigint,
+  lastReceivedSequenceNumber: number
+): Uint8Array {
+  return encodeMessage(
+    sequenceNumber,
+    sessionId,
+    lastReceivedSequenceNumber,
+    MessageType.CTRL_HEARTBEAT
+  );
+}
+
+/**
+ * Decode a CTRL_HEARTBEAT_RESPONSE.
+ *
+ * Payload format:
+ * - responseToSequenceNumber (4 bytes, big-endian)
+ *
+ * @param payload - The message payload
+ * @returns The sequence number this is a response to
+ */
+export function decodeHeartbeatResponse(payload: Uint8Array): number {
+  if (payload.length < INT32_SIZE) {
+    throw new Error(
+      `HeartbeatResponse payload too small: ${payload.length} bytes`
+    );
+  }
+  const view = new DataView(payload.buffer, payload.byteOffset);
+  return view.getUint32(0, false);
+}
+
+/**
+ * Create a CTRL_TERMINATE_SESSION message.
+ *
+ * No payload.
+ *
+ * @param sequenceNumber - Sequence number for this message
+ * @param sessionId - Current session ID
+ * @param lastReceivedSequenceNumber - Last sequence number received from RTI
+ * @returns Encoded message ready to send
+ */
+export function createTerminateSessionMessage(
+  sequenceNumber: number,
+  sessionId: bigint,
+  lastReceivedSequenceNumber: number
+): Uint8Array {
+  return encodeMessage(
+    sequenceNumber,
+    sessionId,
+    lastReceivedSequenceNumber,
+    MessageType.CTRL_TERMINATE_SESSION
+  );
+}
+
+/**
+ * Create an HLA_CALL_REQUEST message.
+ *
+ * Payload format:
+ * - hlaServiceCallWithParams (variable, protobuf-encoded CallRequest)
+ *
+ * @param sequenceNumber - Sequence number for this message
+ * @param sessionId - Current session ID
+ * @param lastReceivedSequenceNumber - Last sequence number received from RTI
+ * @param hlaCallPayload - Protobuf-encoded HLA call request
+ * @returns Encoded message ready to send
+ */
+export function createHlaCallRequestMessage(
+  sequenceNumber: number,
+  sessionId: bigint,
+  lastReceivedSequenceNumber: number,
+  hlaCallPayload: Uint8Array
+): Uint8Array {
+  return encodeMessage(
+    sequenceNumber,
+    sessionId,
+    lastReceivedSequenceNumber,
+    MessageType.HLA_CALL_REQUEST,
+    hlaCallPayload
+  );
+}
+
+/**
+ * Decoded HLA call response
+ */
+export interface HlaCallResponseResult {
+  /** Sequence number this is a response to */
+  responseToSequenceNumber: number;
+  /** The HLA response payload (protobuf-encoded CallResponse) */
+  hlaServiceReturnValueOrException: Uint8Array;
+}
+
+/**
+ * Decode an HLA_CALL_RESPONSE message.
+ *
+ * Payload format:
+ * - responseToSequenceNumber (4 bytes, big-endian)
+ * - hlaServiceReturnValueOrException (remaining bytes)
+ *
+ * @param payload - The message payload
+ * @returns Decoded HLA call response
+ */
+export function decodeHlaCallResponse(payload: Uint8Array): HlaCallResponseResult {
+  if (payload.length < INT32_SIZE) {
+    throw new Error(
+      `HlaCallResponse payload too small: ${payload.length} bytes`
+    );
+  }
+  const view = new DataView(payload.buffer, payload.byteOffset);
+  const responseToSequenceNumber = view.getUint32(0, false);
+
+  return {
+    responseToSequenceNumber,
+    hlaServiceReturnValueOrException: payload.slice(INT32_SIZE),
+  };
+}
+
+/**
+ * Decoded HLA callback request
+ */
+export interface HlaCallbackRequestResult {
+  /** The HLA callback payload (protobuf-encoded CallbackRequest) */
+  hlaServiceCallbackWithParams: Uint8Array;
+}
+
+/**
+ * Decode an HLA_CALLBACK_REQUEST message.
+ *
+ * Payload format:
+ * - hlaServiceCallbackWithParams (all bytes, protobuf-encoded CallbackRequest)
+ *
+ * @param payload - The message payload
+ * @returns Decoded HLA callback request
+ */
+export function decodeHlaCallbackRequest(payload: Uint8Array): HlaCallbackRequestResult {
+  return {
+    hlaServiceCallbackWithParams: payload,
+  };
+}
+
+/**
+ * Create an HLA_CALLBACK_RESPONSE message.
+ *
+ * Payload format:
+ * - responseToSequenceNumber (4 bytes, big-endian)
+ * - hlaCallbackResponse (remaining bytes, protobuf-encoded CallbackResponse)
+ *
+ * @param sequenceNumber - Sequence number for this message
+ * @param sessionId - Current session ID
+ * @param lastReceivedSequenceNumber - Last sequence number received from RTI
+ * @param responseToSequenceNumber - Sequence number of the callback request
+ * @param hlaCallbackResponse - Protobuf-encoded callback response
+ * @returns Encoded message ready to send
+ */
+export function createHlaCallbackResponseMessage(
+  sequenceNumber: number,
+  sessionId: bigint,
+  lastReceivedSequenceNumber: number,
+  responseToSequenceNumber: number,
+  hlaCallbackResponse: Uint8Array
+): Uint8Array {
+  const payloadSize = INT32_SIZE + hlaCallbackResponse.length;
+  const payload = new Uint8Array(payloadSize);
+  const view = new DataView(payload.buffer);
+  view.setUint32(0, responseToSequenceNumber, false);
+  payload.set(hlaCallbackResponse, INT32_SIZE);
+
+  return encodeMessage(
+    sequenceNumber,
+    sessionId,
+    lastReceivedSequenceNumber,
+    MessageType.HLA_CALLBACK_RESPONSE,
+    payload
+  );
+}
+
+/**
+ * Get a human-readable description of a message header
+ */
+export function describeHeader(header: MessageHeader): string {
+  return `[seq=${header.sequenceNumber}, session=${header.sessionId}, lastRecv=${header.lastReceivedSequenceNumber}, type=${MessageType[header.messageType] ?? header.messageType}]`;
+}

package/src/sequence-number.ts

@@ -0,0 +1,200 @@
+/**
+ * Sequence Number Management
+ *
+ * Handles sequence numbers with wrap-around behavior as defined in the
+ * IEEE 1516-2025 Federate Protocol specification.
+ *
+ * Sequence numbers are 32-bit unsigned integers that wrap around from
+ * MAX_VALUE (2^31 - 1) back to 0. The value 0x80000000 is reserved as
+ * "no sequence number" and is never used as a valid sequence number.
+ */
+
+/**
+ * Invalid/no sequence number marker.
+ * Binary: 10000000 00000000 00000000 00000000
+ * This is stored as a 32-bit signed integer (-2147483648 = Integer.MIN_VALUE)
+ * but transmitted as unsigned (2147483648).
+ */
+export const NO_SEQUENCE_NUMBER = 0x80000000 >>> 0; // Force unsigned
+
+/**
+ * Initial sequence number for new sessions
+ */
+export const INITIAL_SEQUENCE_NUMBER = 0;
+
+/**
+ * Maximum valid sequence number (2^31 - 1)
+ */
+export const MAX_SEQUENCE_NUMBER = 0x7fffffff;
+
+/**
+ * Check if a value is a valid sequence number
+ */
+export function isValidSequenceNumber(value: number): boolean {
+  // Valid sequence numbers are 0 to MAX_SEQUENCE_NUMBER (0x7FFFFFFF)
+  // Invalid is 0x80000000 and above (as unsigned)
+  return value >= 0 && value <= MAX_SEQUENCE_NUMBER;
+}
+
+/**
+ * Get the next sequence number with wrap-around
+ */
+export function nextSequenceNumber(current: number): number {
+  const next = current + 1;
+  // Wrap around if we exceed max or hit the invalid marker
+  return next > MAX_SEQUENCE_NUMBER ? INITIAL_SEQUENCE_NUMBER : next;
+}
+
+/**
+ * Add two sequence numbers with wrap-around
+ */
+export function addSequenceNumbers(a: number, b: number): number {
+  const sum = a + b;
+  // Mask to keep in valid range (clear high bit)
+  return sum & MAX_SEQUENCE_NUMBER;
+}
+
+/**
+ * Check if a candidate sequence number is within an interval [oldest, newest]
+ * Handles wrap-around correctly.
+ */
+export function isInInterval(
+  candidate: number,
+  oldest: number,
+  newest: number
+): boolean {
+  if (!isValidSequenceNumber(oldest) || !isValidSequenceNumber(candidate) || !isValidSequenceNumber(newest)) {
+    throw new Error("All sequence numbers must be valid");
+  }
+
+  if (oldest <= newest) {
+    // Normal case: no wrap-around in interval
+    return oldest <= candidate && candidate <= newest;
+  } else {
+    // Wrap-around case: interval spans from oldest to MAX, then 0 to newest
+    return candidate >= oldest || candidate <= newest;
+  }
+}
+
+/**
+ * Mutable sequence number class for tracking and incrementing
+ */
+export class SequenceNumber {
+  private _value: number;
+
+  constructor(initialValue: number = INITIAL_SEQUENCE_NUMBER) {
+    this._value = initialValue;
+  }
+
+  /**
+   * Get the current value
+   */
+  get value(): number {
+    return this._value;
+  }
+
+  /**
+   * Set a new value
+   */
+  set(newValue: number): void {
+    this._value = newValue;
+  }
+
+  /**
+   * Increment and return the new value
+   */
+  increment(): number {
+    this._value = nextSequenceNumber(this._value);
+    return this._value;
+  }
+
+  /**
+   * Get current value and then increment
+   */
+  getAndIncrement(): number {
+    const current = this._value;
+    this._value = nextSequenceNumber(this._value);
+    return current;
+  }
+
+  /**
+   * Check if the current value is valid
+   */
+  isValid(): boolean {
+    return isValidSequenceNumber(this._value);
+  }
+
+  /**
+   * Create a copy
+   */
+  clone(): SequenceNumber {
+    return new SequenceNumber(this._value);
+  }
+
+  toString(): string {
+    return String(this._value);
+  }
+}
+
+/**
+ * Thread-safe (atomic-like) sequence number for concurrent access.
+ * In JavaScript/TypeScript this provides a clean interface for
+ * atomic get/set operations.
+ */
+export class AtomicSequenceNumber {
+  private _value: number;
+
+  constructor(initialValue: number = NO_SEQUENCE_NUMBER) {
+    this._value = initialValue;
+  }
+
+  /**
+   * Get the current value
+   */
+  get(): number {
+    return this._value;
+  }
+
+  /**
+   * Set a new value
+   */
+  set(newValue: number): void {
+    this._value = newValue;
+  }
+
+  /**
+   * Compare and set: only set if current value equals expected
+   * Returns true if the value was set
+   */
+  compareAndSet(expected: number, newValue: number): boolean {
+    if (this._value === expected) {
+      this._value = newValue;
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Get current value and then set new value
+   */
+  getAndSet(newValue: number): number {
+    const current = this._value;
+    this._value = newValue;
+    return current;
+  }
+
+  /**
+   * Increment and return the new value
+   */
+  incrementAndGet(): number {
+    this._value = nextSequenceNumber(this._value);
+    return this._value;
+  }
+
+  /**
+   * Check if the current value is valid
+   */
+  isValid(): boolean {
+    return isValidSequenceNumber(this._value);
+  }
+}