@hla4ts/session 0.1.0 → 0.1.1

package/src/messages.ts

@@ -1,329 +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}]`;
-}
+/**
+ * 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}]`;
+}