@hla4ts/transport 0.1.0

package/README.md

@@ -0,0 +1,386 @@
+# @hla4ts/transport
+
+**HLA 4 Federate Protocol Transport Layer**
+
+This package provides the transport layer for the HLA 4 Federate Protocol, handling TCP/TLS connections, message framing, and low-level communication with HLA 4 RTIs.
+
+## Overview
+
+The Federate Protocol uses a binary framing format over TCP or TLS connections. Each message has a 24-byte header followed by an optional payload. This package handles:
+
+- **Connection management** - TCP and TLS socket connections
+- **Message framing** - Encoding/decoding the 24-byte header
+- **Stream handling** - Buffering partial messages, extracting multiple messages from a single chunk
+
+## Installation
+
+```bash
+bun add @hla4ts/transport
+```
+
+## Quick Start
+
+```typescript
+import { 
+  TlsTransport, 
+  MessageType, 
+  encodeMessage,
+  FEDERATE_PROTOCOL_VERSION,
+} from '@hla4ts/transport';
+
+// Create a TLS transport
+const transport = new TlsTransport({
+  host: 'rti.example.com',
+  port: 15165,
+});
+
+// Set up event handlers
+transport.setEventHandlers({
+  onMessage: (msg) => {
+    console.log('Received:', MessageType[msg.header.messageType]);
+    console.log('Payload size:', msg.payload.length);
+  },
+  onClose: (hadError) => {
+    console.log('Connection closed', hadError ? '(with error)' : '');
+  },
+  onError: (err) => {
+    console.error('Transport error:', err);
+  },
+});
+
+// Connect
+await transport.connect();
+
+// Send a CTRL_NEW_SESSION message
+const payload = new Uint8Array(4);
+new DataView(payload.buffer).setUint32(0, FEDERATE_PROTOCOL_VERSION, false);
+
+const message = encodeMessage(
+  1,                            // sequence number
+  0n,                           // session ID (0 for new session)
+  0,                            // last received sequence number
+  MessageType.CTRL_NEW_SESSION, // message type
+  payload                       // payload
+);
+
+await transport.send(message);
+
+// Later: disconnect
+await transport.disconnect();
+```
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  participant RTI
+  participant Transport as Tcp/TlsTransport
+  participant Decoder as FrameDecoder
+  participant App as Federate Code
+  RTI-->>Transport: TCP/TLS bytes
+  Transport-->>Decoder: push(chunk)
+  Decoder-->>App: onMessage(header, payload)
+  App->>Transport: send(encoded message)
+  Transport-->>RTI: TCP/TLS bytes
+```
+
+## Message Format
+
+Every Federate Protocol message has a **24-byte header**:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Offset │ Size  │ Field                    │ Description         │
+├────────┼───────┼──────────────────────────┼─────────────────────┤
+│ 0      │ 4     │ packetSize               │ Total message size  │
+│ 4      │ 4     │ sequenceNumber           │ Message sequence #  │
+│ 8      │ 8     │ sessionId                │ Session identifier  │
+│ 16     │ 4     │ lastReceivedSequenceNum  │ ACK for flow ctrl   │
+│ 20     │ 4     │ messageType              │ Type of message     │
+├────────┴───────┴──────────────────────────┴─────────────────────┤
+│ 24     │ var   │ payload                  │ Message payload     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+All integers are **big-endian** (network byte order).
+
+## Message Types
+
+### Control Messages (Session Management)
+
+| Code | Name | Direction | Description |
+|------|------|-----------|-------------|
+| 1 | `CTRL_NEW_SESSION` | C → S | Request new session |
+| 2 | `CTRL_NEW_SESSION_STATUS` | S → C | Session creation result |
+| 3 | `CTRL_HEARTBEAT` | Both | Keep-alive ping |
+| 4 | `CTRL_HEARTBEAT_RESPONSE` | Both | Keep-alive pong |
+| 5 | `CTRL_TERMINATE_SESSION` | C → S | Request session end |
+| 6 | `CTRL_SESSION_TERMINATED` | S → C | Session ended |
+| 10 | `CTRL_RESUME_REQUEST` | C → S | Resume dropped session |
+| 11 | `CTRL_RESUME_STATUS` | S → C | Resume result |
+
+### HLA Messages
+
+| Code | Name | Direction | Description |
+|------|------|-----------|-------------|
+| 20 | `HLA_CALL_REQUEST` | C → S | RTI service call (protobuf `CallRequest`) |
+| 21 | `HLA_CALL_RESPONSE` | S → C | RTI response (protobuf `CallResponse`) |
+| 22 | `HLA_CALLBACK_REQUEST` | S → C | Federate callback (protobuf `CallbackRequest`) |
+| 23 | `HLA_CALLBACK_RESPONSE` | C → S | Callback ACK (protobuf `CallbackResponse`) |
+
+## API Reference
+
+### Transports
+
+#### `TlsTransport`
+
+Secure TLS connection (recommended for production):
+
+```typescript
+import { TlsTransport, Ports } from '@hla4ts/transport';
+
+const transport = new TlsTransport({
+  host: 'rti.example.com',
+  port: Ports.TLS,              // 15165 (default)
+  connectionTimeout: 10000,     // 10 seconds (default)
+  noDelay: true,                // TCP_NODELAY (default)
+  
+  // TLS options
+  rejectUnauthorized: true,     // Verify server cert (default)
+  ca: '/path/to/ca.pem',        // Custom CA (optional)
+  cert: '/path/to/client.pem',  // Client cert for mTLS (optional)
+  key: '/path/to/client-key.pem', // Client key for mTLS (optional)
+  serverName: 'rti.example.com',  // SNI hostname (optional)
+});
+```
+
+#### `TcpTransport`
+
+Plain TCP connection (for development/testing only):
+
+```typescript
+import { TcpTransport, Ports } from '@hla4ts/transport';
+
+const transport = new TcpTransport({
+  host: 'localhost',
+  port: Ports.TCP,  // 15164 (default)
+});
+```
+
+### Transport Interface
+
+Both transports implement the `Transport` interface:
+
+```typescript
+interface Transport {
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  isConnected(): boolean;
+  send(data: Uint8Array): Promise<void>;
+  setEventHandlers(handlers: TransportEvents): void;
+  getProtocolName(): string;
+  getRemoteAddress(): string | null;
+}
+
+interface TransportEvents {
+  onMessage?: (message: ReceivedMessage) => void;
+  onClose?: (hadError: boolean) => void;
+  onError?: (error: Error) => void;
+}
+
+interface ReceivedMessage {
+  header: MessageHeader;
+  payload: Uint8Array;
+}
+```
+
+### Message Header Functions
+
+```typescript
+import {
+  encodeHeader,
+  decodeHeader,
+  encodeMessage,
+  getPayloadSize,
+  HEADER_SIZE,        // 24
+  NO_SESSION_ID,      // 0n
+  NO_SEQUENCE_NUMBER, // 0
+} from '@hla4ts/transport';
+
+// Encode just the header (24 bytes)
+const header = encodeHeader(
+  payloadSize,              // payload size in bytes
+  sequenceNumber,           // sequence number
+  sessionId,                // session ID (bigint)
+  lastReceivedSequenceNum,  // ACK
+  messageType               // MessageType enum
+);
+
+// Encode header + payload
+const message = encodeMessage(
+  sequenceNumber,
+  sessionId,
+  lastReceivedSequenceNum,
+  messageType,
+  payload  // optional Uint8Array
+);
+
+// Decode a header
+const header = decodeHeader(buffer);  // throws on invalid data
+console.log(header.packetSize);
+console.log(header.sequenceNumber);
+console.log(header.sessionId);
+console.log(header.messageType);
+
+// Get payload size from header
+const payloadSize = getPayloadSize(header);
+```
+
+### Frame Decoder
+
+For advanced use cases, you can use the `FrameDecoder` directly:
+
+```typescript
+import { FrameDecoder } from '@hla4ts/transport';
+
+const decoder = new FrameDecoder();
+
+decoder.onMessage = (msg) => {
+  console.log('Complete message received');
+  console.log('Type:', msg.header.messageType);
+  console.log('Payload:', msg.payload);
+};
+
+decoder.onError = (err) => {
+  console.error('Decode error:', err);
+};
+
+// Feed data as it arrives (handles fragmentation automatically)
+socket.on('data', (chunk) => {
+  decoder.push(new Uint8Array(chunk));
+});
+
+// Check buffered data
+console.log('Bytes waiting:', decoder.bufferedBytes);
+
+// Reset after connection reset
+decoder.reset();
+```
+
+### Constants
+
+```typescript
+import {
+  FEDERATE_PROTOCOL_VERSION,  // 1
+  Ports,
+  Protocol,
+  NewSessionStatus,
+  ResumeStatus,
+} from '@hla4ts/transport';
+
+// Default ports
+Ports.TCP   // 15164
+Ports.TLS   // 15165
+Ports.WS    // 80
+Ports.WSS   // 443
+
+// Protocol names
+Protocol.TCP  // "tcp"
+Protocol.TLS  // "tls"
+Protocol.WS   // "websocket"
+Protocol.WSS  // "websocketsecure"
+
+// Session status codes
+NewSessionStatus.SUCCESS                      // 0
+NewSessionStatus.UNSUPPORTED_PROTOCOL_VERSION // 1
+NewSessionStatus.OUT_OF_RESOURCES             // 2
+NewSessionStatus.BAD_MESSAGE                  // 3
+NewSessionStatus.OTHER_ERROR                  // 99
+
+// Resume status codes
+ResumeStatus.SUCCESS           // 0
+ResumeStatus.SESSION_NOT_FOUND // 1
+ResumeStatus.NOT_ALLOWED       // 2
+```
+
+## Session Protocol Flow
+
+```
+┌─────────────┐                              ┌─────────────┐
+│   Federate  │                              │     RTI     │
+└──────┬──────┘                              └──────┬──────┘
+       │                                            │
+       │──── TCP/TLS Connect ──────────────────────>│
+       │                                            │
+       │──── CTRL_NEW_SESSION (version=1) ─────────>│
+       │                                            │
+       │<─── CTRL_NEW_SESSION_STATUS (sessionId) ───│
+       │                                            │
+       │──── HLA_CALL_REQUEST (Connect) ───────────>│
+       │<─── HLA_CALL_RESPONSE ─────────────────────│
+       │                                            │
+       │──── HLA_CALL_REQUEST (JoinFederation) ────>│
+       │<─── HLA_CALL_RESPONSE ─────────────────────│
+       │                                            │
+       │     ... HLA calls and callbacks ...        │
+       │                                            │
+       │<─── HLA_CALLBACK_REQUEST (Discover...) ────│
+       │──── HLA_CALLBACK_RESPONSE ────────────────>│
+       │                                            │
+       │──── CTRL_HEARTBEAT ───────────────────────>│
+       │<─── CTRL_HEARTBEAT_RESPONSE ──────────────│
+       │                                            │
+       │──── CTRL_TERMINATE_SESSION ───────────────>│
+       │<─── CTRL_SESSION_TERMINATED ──────────────│
+       │                                            │
+       │──── TCP/TLS Disconnect ───────────────────>│
+       │                                            │
+```
+
+## Error Handling
+
+```typescript
+try {
+  await transport.connect();
+} catch (err) {
+  if (err.message.includes('Connection timeout')) {
+    console.error('RTI not reachable');
+  } else if (err.message.includes('certificate')) {
+    console.error('TLS certificate error');
+  }
+}
+
+transport.setEventHandlers({
+  onError: (err) => {
+    console.error('Transport error:', err);
+    // Attempt reconnection...
+  },
+  onClose: (hadError) => {
+    if (hadError) {
+      console.error('Connection lost unexpectedly');
+    }
+  },
+});
+```
+
+## Testing
+
+```bash
+cd packages/transport
+bun test
+```
+
+## Related Packages
+
+- [`@hla4ts/proto`](../proto) - Protocol buffer types
+- [`@hla4ts/session`](../session) - Session management
+- [`@hla4ts/hla-api`](../hla-api) - High-level HLA API facade
+
+## References
+
+- [IEEE 1516-2025](https://standards.ieee.org/standard/1516-2025.html) - HLA 4 Standard
+- [Pitch FedProClient](https://github.com/Pitch-Technologies/FedProClient) - Reference implementation
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@hla4ts/transport",
+  "version": "0.1.0",
+  "description": "HLA 4 Federate Protocol transport layer with TLS and message framing",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "README.md",
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@hla4ts/proto": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,57 @@
+/**
+ * Federate Protocol Constants
+ */
+
+/** Current Federate Protocol version */
+export const FEDERATE_PROTOCOL_VERSION = 1;
+
+/** Default ports for different transport protocols */
+export const Ports = {
+  /** Plain TCP (unencrypted) */
+  TCP: 15164,
+  /** TLS over TCP (encrypted) */
+  TLS: 15165,
+  /** WebSocket (unencrypted) */
+  WS: 80,
+  /** WebSocket Secure (encrypted) */
+  WSS: 443,
+} as const;
+
+/** Transport protocol names */
+export const Protocol = {
+  TCP: "tcp",
+  TLS: "tls",
+  WS: "websocket",
+  WSS: "websocketsecure",
+} as const;
+
+export type ProtocolType = (typeof Protocol)[keyof typeof Protocol];
+
+/** New session status reason codes */
+export const NewSessionStatus = {
+  /** Session created successfully */
+  SUCCESS: 0,
+  /** Server doesn't support the requested protocol version */
+  UNSUPPORTED_PROTOCOL_VERSION: 1,
+  /** Server is out of resources */
+  OUT_OF_RESOURCES: 2,
+  /** Bad message received */
+  BAD_MESSAGE: 3,
+  /** Other unspecified error */
+  OTHER_ERROR: 99,
+} as const;
+
+export type NewSessionStatusCode =
+  (typeof NewSessionStatus)[keyof typeof NewSessionStatus];
+
+/** Resume status reason codes */
+export const ResumeStatus = {
+  /** Resume successful */
+  SUCCESS: 0,
+  /** Session not found (expired or invalid) */
+  SESSION_NOT_FOUND: 1,
+  /** Resume not allowed in current state */
+  NOT_ALLOWED: 2,
+} as const;
+
+export type ResumeStatusCode = (typeof ResumeStatus)[keyof typeof ResumeStatus];

package/src/frame-decoder.ts

@@ -0,0 +1,136 @@
+/**
+ * Frame Decoder
+ *
+ * Handles accumulating partial data from the network and extracting
+ * complete framed messages. This is necessary because TCP is a stream
+ * protocol and messages may arrive in fragments or multiple messages
+ * may arrive in a single chunk.
+ */
+
+import {
+  HEADER_SIZE,
+  decodeHeader,
+  type MessageHeader,
+} from "./message-header.ts";
+import type { ReceivedMessage } from "./transport.ts";
+
+/** Maximum allowed message size (16 MB) - protection against malformed packets */
+const MAX_MESSAGE_SIZE = 16 * 1024 * 1024;
+
+/**
+ * Frame decoder for length-prefixed messages
+ *
+ * Usage:
+ * ```ts
+ * const decoder = new FrameDecoder();
+ * decoder.onMessage = (msg) => console.log('Got message:', msg);
+ *
+ * // Feed data as it arrives from the socket
+ * socket.on('data', (chunk) => decoder.push(chunk));
+ * ```
+ */
+export class FrameDecoder {
+  private buffer: Uint8Array = new Uint8Array(0);
+  private pendingHeader: MessageHeader | null = null;
+
+  /** Callback for complete messages */
+  public onMessage: ((message: ReceivedMessage) => void) | null = null;
+
+  /** Callback for decode errors */
+  public onError: ((error: Error) => void) | null = null;
+
+  /**
+   * Push incoming data into the decoder
+   * @param chunk Data received from the network
+   */
+  push(chunk: Uint8Array): void {
+    // Append chunk to buffer
+    this.buffer = this.concat(this.buffer, chunk);
+
+    // Process as many complete messages as possible
+    this.processBuffer();
+  }
+
+  /**
+   * Reset the decoder state (e.g., after a connection reset)
+   */
+  reset(): void {
+    this.buffer = new Uint8Array(0);
+    this.pendingHeader = null;
+  }
+
+  /**
+   * Get the number of bytes currently buffered
+   */
+  get bufferedBytes(): number {
+    return this.buffer.length;
+  }
+
+  private processBuffer(): void {
+    while (true) {
+      // If we don't have a header yet, try to read one
+      if (this.pendingHeader === null) {
+        if (this.buffer.length < HEADER_SIZE) {
+          // Not enough data for header yet
+          return;
+        }
+
+        try {
+          this.pendingHeader = decodeHeader(this.buffer.subarray(0, HEADER_SIZE));
+        } catch (error) {
+          this.onError?.(error as Error);
+          // Skip one byte and try again (attempt to resync)
+          this.buffer = this.buffer.subarray(1);
+          continue;
+        }
+
+        // Validate packet size
+        if (this.pendingHeader.packetSize > MAX_MESSAGE_SIZE) {
+          this.onError?.(
+            new Error(
+              `Message too large: ${this.pendingHeader.packetSize} bytes (max: ${MAX_MESSAGE_SIZE})`
+            )
+          );
+          // Reset and skip this header
+          this.pendingHeader = null;
+          this.buffer = this.buffer.subarray(HEADER_SIZE);
+          continue;
+        }
+      }
+
+      // We have a header, check if we have the complete message
+      const totalSize = this.pendingHeader.packetSize;
+      if (this.buffer.length < totalSize) {
+        // Not enough data for complete message yet
+        return;
+      }
+
+      // Extract the complete message
+      const messageData = this.buffer.subarray(0, totalSize);
+      const payload = messageData.subarray(HEADER_SIZE);
+
+      // Create the received message
+      const message: ReceivedMessage = {
+        header: this.pendingHeader,
+        payload: new Uint8Array(payload), // Copy to avoid issues with buffer reuse
+      };
+
+      // Remove this message from buffer
+      this.buffer = this.buffer.subarray(totalSize);
+      this.pendingHeader = null;
+
+      // Emit the message
+      this.onMessage?.(message);
+    }
+  }
+
+  private concat(a: Uint8Array, b: Uint8Array): Uint8Array {
+    if (a.length === 0) return b;
+    if (b.length === 0) return a;
+
+    const result = new Uint8Array(a.length + b.length);
+    result.set(a, 0);
+    result.set(b, a.length);
+    return result;
+  }
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+/**
+ * @hla4ts/transport - HLA 4 Federate Protocol Transport Layer
+ *
+ * This package provides transport implementations for the HLA 4 Federate Protocol,
+ * including message framing, TLS support, and connection management.
+ *
+ * @example
+ * ```ts
+ * import { TlsTransport, MessageType, encodeMessage } from '@hla4ts/transport';
+ *
+ * // Create a TLS transport
+ * const transport = new TlsTransport({
+ *   host: 'rti.example.com',
+ *   port: 15165,
+ * });
+ *
+ * // Set up event handlers
+ * transport.setEventHandlers({
+ *   onMessage: (msg) => {
+ *     console.log('Received:', MessageType[msg.header.messageType]);
+ *   },
+ *   onClose: () => console.log('Connection closed'),
+ *   onError: (err) => console.error('Error:', err),
+ * });
+ *
+ * // Connect and send a message
+ * await transport.connect();
+ * const message = encodeMessage(
+ *   1,                              // sequence number
+ *   0n,                             // session ID (0 for new session)
+ *   0,                              // last received seq num
+ *   MessageType.CTRL_NEW_SESSION,   // message type
+ *   payload                         // optional payload
+ * );
+ * await transport.send(message);
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Message types
+export { MessageType, isControlMessage, isHlaResponse, messageTypeName } from "./message-type.ts";
+
+// Message header encoding/decoding
+export {
+  HEADER_SIZE,
+  NO_SESSION_ID,
+  NO_SEQUENCE_NUMBER,
+  encodeHeader,
+  decodeHeader,
+  encodeMessage,
+  getPayloadSize,
+  type MessageHeader,
+} from "./message-header.ts";
+
+// Constants
+export {
+  FEDERATE_PROTOCOL_VERSION,
+  Ports,
+  Protocol,
+  NewSessionStatus,
+  ResumeStatus,
+  type ProtocolType,
+  type NewSessionStatusCode,
+  type ResumeStatusCode,
+} from "./constants.ts";
+
+// Transport interface
+export type {
+  Transport,
+  TransportOptions,
+  TlsOptions,
+  TransportEvents,
+  ReceivedMessage,
+} from "./transport.ts";
+
+// Frame decoder
+export { FrameDecoder } from "./frame-decoder.ts";
+
+// Transport implementations
+export { TlsTransport } from "./tls-transport.ts";
+export { TcpTransport } from "./tcp-transport.ts";

package/src/message-header.ts

@@ -0,0 +1,141 @@
+/**
+ * Federate Protocol Message Header
+ *
+ * The message header is a 24-byte structure that precedes every message
+ * in the Federate Protocol. It contains:
+ *
+ * - packetSize (4 bytes): Total size of the packet including header
+ * - sequenceNumber (4 bytes): Monotonically increasing sequence number
+ * - sessionId (8 bytes): Unique session identifier
+ * - lastReceivedSequenceNumber (4 bytes): ACK for flow control
+ * - messageType (4 bytes): Type of message (see MessageType enum)
+ */
+
+import { MessageType } from "./message-type.ts";
+
+/** Size of the message header in bytes */
+export const HEADER_SIZE = 24;
+
+/** Special value indicating no session ID */
+export const NO_SESSION_ID = 0n;
+
+/** Special value indicating no sequence number */
+export const NO_SEQUENCE_NUMBER = 0;
+
+/**
+ * Decoded message header
+ */
+export interface MessageHeader {
+  /** Total packet size including header */
+  packetSize: number;
+  /** Message sequence number */
+  sequenceNumber: number;
+  /** Session identifier */
+  sessionId: bigint;
+  /** Last received sequence number (for ACK) */
+  lastReceivedSequenceNumber: number;
+  /** Type of message */
+  messageType: MessageType;
+}
+
+/**
+ * Encode a message header into a 24-byte buffer
+ */
+export function encodeHeader(
+  payloadSize: number,
+  sequenceNumber: number,
+  sessionId: bigint,
+  lastReceivedSequenceNumber: number,
+  messageType: MessageType
+): Uint8Array {
+  const packetSize = HEADER_SIZE + payloadSize;
+  const buffer = new ArrayBuffer(HEADER_SIZE);
+  const view = new DataView(buffer);
+
+  // All values are big-endian (network byte order)
+  view.setUint32(0, packetSize, false);
+  view.setUint32(4, sequenceNumber, false);
+  view.setBigUint64(8, sessionId, false);
+  view.setUint32(16, lastReceivedSequenceNumber, false);
+  view.setUint32(20, messageType, false);
+
+  return new Uint8Array(buffer);
+}
+
+/**
+ * Decode a message header from a 24-byte buffer
+ * @throws Error if buffer is too small or contains invalid data
+ */
+export function decodeHeader(buffer: Uint8Array): MessageHeader {
+  if (buffer.length < HEADER_SIZE) {
+    throw new Error(
+      `Buffer too small for header: expected ${HEADER_SIZE} bytes, got ${buffer.length}`
+    );
+  }
+
+  const view = new DataView(
+    buffer.buffer,
+    buffer.byteOffset,
+    buffer.byteLength
+  );
+
+  const packetSize = view.getUint32(0, false);
+  if (packetSize < HEADER_SIZE) {
+    throw new Error(`Invalid packet size: ${packetSize} (minimum is ${HEADER_SIZE})`);
+  }
+
+  const sequenceNumber = view.getUint32(4, false);
+  const sessionId = view.getBigUint64(8, false);
+  const lastReceivedSequenceNumber = view.getUint32(16, false);
+  const messageTypeValue = view.getUint32(20, false);
+
+  // Validate message type
+  if (!Object.values(MessageType).includes(messageTypeValue)) {
+    throw new Error(`Unknown message type: ${messageTypeValue}`);
+  }
+
+  return {
+    packetSize,
+    sequenceNumber,
+    sessionId,
+    lastReceivedSequenceNumber,
+    messageType: messageTypeValue as MessageType,
+  };
+}
+
+/**
+ * Get the payload size from a header
+ */
+export function getPayloadSize(header: MessageHeader): number {
+  return header.packetSize - HEADER_SIZE;
+}
+
+/**
+ * Encode a complete message (header + payload)
+ */
+export function encodeMessage(
+  sequenceNumber: number,
+  sessionId: bigint,
+  lastReceivedSequenceNumber: number,
+  messageType: MessageType,
+  payload?: Uint8Array
+): Uint8Array {
+  const payloadSize = payload?.length ?? 0;
+  const header = encodeHeader(
+    payloadSize,
+    sequenceNumber,
+    sessionId,
+    lastReceivedSequenceNumber,
+    messageType
+  );
+
+  if (payloadSize === 0) {
+    return header;
+  }
+
+  // Combine header and payload
+  const message = new Uint8Array(HEADER_SIZE + payloadSize);
+  message.set(header, 0);
+  message.set(payload!, HEADER_SIZE);
+  return message;
+}

package/src/message-type.ts

@@ -0,0 +1,62 @@
+/**
+ * Federate Protocol Message Types
+ *
+ * These message types are defined in the IEEE 1516-2025 Federate Protocol specification.
+ * They are used in the message header to indicate the type of message being sent.
+ */
+
+export enum MessageType {
+  // Session Management (Control Messages)
+  /** Client → Server: Request to create a new session */
+  CTRL_NEW_SESSION = 1,
+  /** Server → Client: Response with session creation status */
+  CTRL_NEW_SESSION_STATUS = 2,
+  /** Bidirectional: Keep-alive ping */
+  CTRL_HEARTBEAT = 3,
+  /** Bidirectional: Keep-alive pong */
+  CTRL_HEARTBEAT_RESPONSE = 4,
+  /** Client → Server: Request to terminate session */
+  CTRL_TERMINATE_SESSION = 5,
+  /** Server → Client: Confirmation of session termination */
+  CTRL_SESSION_TERMINATED = 6,
+
+  // Reconnection
+  /** Client → Server: Request to resume a dropped session */
+  CTRL_RESUME_REQUEST = 10,
+  /** Server → Client: Response with resume status */
+  CTRL_RESUME_STATUS = 11,
+
+  // HLA Calls and Callbacks
+  /** Client → Server: HLA RTI service call (protobuf CallRequest) */
+  HLA_CALL_REQUEST = 20,
+  /** Server → Client: HLA RTI service response (protobuf CallResponse) */
+  HLA_CALL_RESPONSE = 21,
+  /** Server → Client: HLA callback to federate (protobuf CallbackRequest) */
+  HLA_CALLBACK_REQUEST = 22,
+  /** Client → Server: HLA callback acknowledgment (protobuf CallbackResponse) */
+  HLA_CALLBACK_RESPONSE = 23,
+}
+
+/**
+ * Check if a message type is a control message (session management)
+ */
+export function isControlMessage(type: MessageType): boolean {
+  return type < MessageType.HLA_CALL_REQUEST;
+}
+
+/**
+ * Check if a message type is an HLA response
+ */
+export function isHlaResponse(type: MessageType): boolean {
+  return (
+    type === MessageType.HLA_CALL_RESPONSE ||
+    type === MessageType.HLA_CALLBACK_RESPONSE
+  );
+}
+
+/**
+ * Get a human-readable name for a message type
+ */
+export function messageTypeName(type: MessageType): string {
+  return MessageType[type] ?? `UNKNOWN(${type})`;
+}

package/src/tcp-transport.ts

@@ -0,0 +1,154 @@
+/**
+ * TCP Transport Implementation
+ *
+ * Provides a plain TCP connection for the Federate Protocol.
+ * Note: This is unencrypted and should only be used for local development/testing.
+ */
+
+import { connect, type Socket, type SocketHandler } from "bun";
+import { FrameDecoder } from "./frame-decoder.ts";
+import { Ports, Protocol } from "./constants.ts";
+import type {
+  Transport,
+  TransportEvents,
+  TransportOptions,
+  ReceivedMessage,
+} from "./transport.ts";
+
+/**
+ * Plain TCP Transport for Federate Protocol
+ *
+ * ⚠️ WARNING: This transport is unencrypted. Use TlsTransport for production.
+ *
+ * @example
+ * ```ts
+ * const transport = new TcpTransport({
+ *   host: 'localhost',
+ *   port: 15164,
+ * });
+ *
+ * await transport.connect();
+ * ```
+ */
+export class TcpTransport implements Transport {
+  private readonly options: Required<TransportOptions>;
+  private socket: Socket<{ decoder: FrameDecoder }> | null = null;
+  private events: TransportEvents = {};
+  private decoder: FrameDecoder;
+  private connected = false;
+
+  constructor(options: TransportOptions) {
+    this.options = {
+      host: options.host,
+      port: options.port ?? Ports.TCP,
+      connectionTimeout: options.connectionTimeout ?? 10000,
+      noDelay: options.noDelay ?? true,
+    };
+
+    this.decoder = new FrameDecoder();
+    this.decoder.onMessage = (msg) => this.handleMessage(msg);
+    this.decoder.onError = (err) => this.handleError(err);
+  }
+
+  async connect(): Promise<void> {
+    if (this.socket) {
+      throw new Error("Already connected");
+    }
+
+    const decoder = this.decoder;
+    const transport = this;
+
+    return new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        reject(new Error(`Connection timeout after ${this.options.connectionTimeout}ms`));
+      }, this.options.connectionTimeout);
+
+      const socketHandler: SocketHandler<{ decoder: FrameDecoder }> = {
+        data(_socket, data) {
+          decoder.push(new Uint8Array(data));
+        },
+        open(_socket) {
+          clearTimeout(timeoutId);
+          transport.connected = true;
+          resolve();
+        },
+        close(_socket) {
+          transport.connected = false;
+          transport.socket = null;
+          transport.events.onClose?.(false);
+        },
+        error(_socket, error) {
+          clearTimeout(timeoutId);
+          transport.connected = false;
+          const err = error instanceof Error ? error : new Error(String(error));
+          transport.events.onError?.(err);
+          reject(err);
+        },
+        connectError(_socket, error) {
+          clearTimeout(timeoutId);
+          const err = error instanceof Error ? error : new Error(String(error));
+          reject(err);
+        },
+      };
+
+      connect({
+        hostname: this.options.host,
+        port: this.options.port,
+        socket: socketHandler,
+        data: { decoder },
+      })
+        .then((socket) => {
+          this.socket = socket;
+        })
+        .catch(reject);
+    });
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.socket) {
+      this.socket.end();
+      this.socket = null;
+      this.connected = false;
+      this.decoder.reset();
+    }
+  }
+
+  isConnected(): boolean {
+    return this.connected && this.socket !== null;
+  }
+
+  async send(data: Uint8Array): Promise<void> {
+    if (!this.socket || !this.connected) {
+      throw new Error("Not connected");
+    }
+
+    const written = this.socket.write(data);
+    if (written < data.length) {
+      throw new Error(
+        `Failed to write all data: wrote ${written} of ${data.length} bytes`
+      );
+    }
+  }
+
+  setEventHandlers(handlers: TransportEvents): void {
+    this.events = handlers;
+  }
+
+  getProtocolName(): string {
+    return Protocol.TCP;
+  }
+
+  getRemoteAddress(): string | null {
+    return this.socket
+      ? `${this.options.host}:${this.options.port}`
+      : null;
+  }
+
+  private handleMessage(message: ReceivedMessage): void {
+    this.events.onMessage?.(message);
+  }
+
+  private handleError(error: Error): void {
+    this.events.onError?.(error);
+  }
+}

package/src/tls-transport.ts

@@ -0,0 +1,193 @@
+/**
+ * TLS Transport Implementation
+ *
+ * Provides a TLS-encrypted TCP connection for the Federate Protocol.
+ * Uses Bun's built-in TLS support.
+ */
+
+import { connect, type Socket, type SocketHandler, type TLSOptions } from "bun";
+import { FrameDecoder } from "./frame-decoder.ts";
+import { Ports, Protocol } from "./constants.ts";
+import type {
+  Transport,
+  TransportEvents,
+  TlsOptions,
+  ReceivedMessage,
+} from "./transport.ts";
+
+/**
+ * TLS Transport for Federate Protocol
+ *
+ * @example
+ * ```ts
+ * const transport = new TlsTransport({
+ *   host: 'localhost',
+ *   port: 15165,
+ * });
+ *
+ * transport.setEventHandlers({
+ *   onMessage: (msg) => console.log('Received:', msg.header.messageType),
+ *   onClose: () => console.log('Disconnected'),
+ *   onError: (err) => console.error('Error:', err),
+ * });
+ *
+ * await transport.connect();
+ * await transport.send(someData);
+ * await transport.disconnect();
+ * ```
+ */
+export class TlsTransport implements Transport {
+  private readonly options: Required<
+    Pick<TlsOptions, "host" | "port" | "connectionTimeout" | "noDelay">
+  > &
+    Omit<TlsOptions, "host" | "port" | "connectionTimeout" | "noDelay">;
+
+  private socket: Socket<{ decoder: FrameDecoder }> | null = null;
+  private events: TransportEvents = {};
+  private decoder: FrameDecoder;
+  private connected = false;
+
+  constructor(options: TlsOptions) {
+    this.options = {
+      host: options.host,
+      port: options.port ?? Ports.TLS,
+      connectionTimeout: options.connectionTimeout ?? 10000,
+      noDelay: options.noDelay ?? true,
+      ca: options.ca,
+      cert: options.cert,
+      key: options.key,
+      rejectUnauthorized: options.rejectUnauthorized ?? true,
+      serverName: options.serverName,
+    };
+
+    this.decoder = new FrameDecoder();
+    this.decoder.onMessage = (msg) => this.handleMessage(msg);
+    this.decoder.onError = (err) => this.handleError(err);
+  }
+
+  async connect(): Promise<void> {
+    if (this.socket) {
+      throw new Error("Already connected");
+    }
+
+    const decoder = this.decoder;
+    const transport = this;
+
+    return new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        reject(new Error(`Connection timeout after ${this.options.connectionTimeout}ms`));
+      }, this.options.connectionTimeout);
+
+      const socketHandler: SocketHandler<{ decoder: FrameDecoder }> = {
+        data(_socket, data) {
+          decoder.push(new Uint8Array(data));
+        },
+        open(_socket) {
+          clearTimeout(timeoutId);
+          transport.connected = true;
+          resolve();
+        },
+        close(_socket) {
+          transport.connected = false;
+          transport.socket = null;
+          transport.events.onClose?.(false);
+        },
+        error(_socket, error) {
+          clearTimeout(timeoutId);
+          transport.connected = false;
+          const err = error instanceof Error ? error : new Error(String(error));
+          transport.events.onError?.(err);
+          reject(err);
+        },
+        connectError(_socket, error) {
+          clearTimeout(timeoutId);
+          const err = error instanceof Error ? error : new Error(String(error));
+          reject(err);
+        },
+      };
+
+      // Build TLS options
+      const tlsConfig: TLSOptions = {
+        rejectUnauthorized: this.options.rejectUnauthorized,
+      };
+
+      // Add optional TLS settings
+      if (this.options.ca) {
+        tlsConfig.ca = Bun.file(this.options.ca);
+      }
+      if (this.options.cert) {
+        tlsConfig.cert = Bun.file(this.options.cert);
+      }
+      if (this.options.key) {
+        tlsConfig.key = Bun.file(this.options.key);
+      }
+      if (this.options.serverName) {
+        tlsConfig.serverName = this.options.serverName;
+      }
+
+      connect({
+        hostname: this.options.host,
+        port: this.options.port,
+        socket: socketHandler,
+        data: { decoder },
+        tls: tlsConfig,
+      })
+        .then((socket) => {
+          this.socket = socket;
+        })
+        .catch(reject);
+    });
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.socket) {
+      this.socket.end();
+      this.socket = null;
+      this.connected = false;
+      this.decoder.reset();
+    }
+  }
+
+  isConnected(): boolean {
+    return this.connected && this.socket !== null;
+  }
+
+  async send(data: Uint8Array): Promise<void> {
+    if (!this.socket || !this.connected) {
+      throw new Error("Not connected");
+    }
+
+    const written = this.socket.write(data);
+    if (written < data.length) {
+      // Bun's socket.write returns the number of bytes written
+      // If not all bytes were written, we need to wait for drain
+      // For simplicity, we'll throw an error here
+      // In production, you'd want to buffer and retry
+      throw new Error(
+        `Failed to write all data: wrote ${written} of ${data.length} bytes`
+      );
+    }
+  }
+
+  setEventHandlers(handlers: TransportEvents): void {
+    this.events = handlers;
+  }
+
+  getProtocolName(): string {
+    return Protocol.TLS;
+  }
+
+  getRemoteAddress(): string | null {
+    return this.socket
+      ? `${this.options.host}:${this.options.port}`
+      : null;
+  }
+
+  private handleMessage(message: ReceivedMessage): void {
+    this.events.onMessage?.(message);
+  }
+
+  private handleError(error: Error): void {
+    this.events.onError?.(error);
+  }
+}

package/src/transport.ts

@@ -0,0 +1,99 @@
+/**
+ * Transport Interface
+ *
+ * Defines the contract for Federate Protocol transports (TCP, TLS, WebSocket).
+ */
+
+import type { MessageHeader } from "./message-header.ts";
+
+/**
+ * Transport connection options
+ */
+export interface TransportOptions {
+  /** Server hostname or IP address */
+  host: string;
+  /** Server port (defaults to Ports.TCP for TCP, Ports.TLS for TLS) */
+  port?: number;
+  /** Connection timeout in milliseconds */
+  connectionTimeout?: number;
+  /** Enable TCP_NODELAY (disable Nagle's algorithm) */
+  noDelay?: boolean;
+}
+
+/**
+ * TLS-specific options
+ */
+export interface TlsOptions extends TransportOptions {
+  /** Path to CA certificate file (for server verification) */
+  ca?: string;
+  /** Path to client certificate file (for mutual TLS) */
+  cert?: string;
+  /** Path to client private key file (for mutual TLS) */
+  key?: string;
+  /** Skip server certificate verification (INSECURE - for testing only) */
+  rejectUnauthorized?: boolean;
+  /** Server name for SNI */
+  serverName?: string;
+}
+
+/**
+ * Received message with header and payload
+ */
+export interface ReceivedMessage {
+  header: MessageHeader;
+  payload: Uint8Array;
+}
+
+/**
+ * Transport event handlers
+ */
+export interface TransportEvents {
+  /** Called when a complete message is received */
+  onMessage?: (message: ReceivedMessage) => void;
+  /** Called when the connection is closed */
+  onClose?: (hadError: boolean) => void;
+  /** Called when an error occurs */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Transport interface for Federate Protocol communication
+ */
+export interface Transport {
+  /**
+   * Connect to the server
+   * @throws Error if connection fails
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Disconnect from the server
+   */
+  disconnect(): Promise<void>;
+
+  /**
+   * Check if the transport is connected
+   */
+  isConnected(): boolean;
+
+  /**
+   * Send raw bytes to the server
+   * @param data The data to send
+   */
+  send(data: Uint8Array): Promise<void>;
+
+  /**
+   * Set event handlers
+   */
+  setEventHandlers(handlers: TransportEvents): void;
+
+  /**
+   * Get the protocol name (tcp, tls, websocket, websocketsecure)
+   */
+  getProtocolName(): string;
+
+  /**
+   * Get the remote address
+   */
+  getRemoteAddress(): string | null;
+}