.NET Wire Protocol

Routing

IonPath uses a fixed URL scheme for all RPC calls:

Examples:

POST /ion/UserService/GetUser.unary     → unary call
WS   /ion/EventService/WatchAll.ws       → server streaming

CBOR Encoding

All payloads use CBOR (RFC 8949). The content type is application/cbor.

Request Format

Arguments are serialized as a flat CBOR array — base arguments first, then method arguments:

// service UserService(spaceId: u4) { GetUser(userId: u4): User; }

// Request body:
CBOR Array(2): [
    1,    // spaceId (base arg)
    42    // userId (method arg)
]

Response Format

The response body is a CBOR-encoded message:

// msg User { id: u4; name: string; email: string; }

// Response body:
CBOR Array(3): [
    42,              // id
    "Alice",         // name
    "a@example.com"  // email
]

WebSocket Framing

Streaming connections use WebSocket binary frames. Each frame starts with a 1-byte opcode:

Connection Lifecycle

1. Client opens WebSocket to /ion/{service}/{method}.ws
2. Client sends initial frame with serialized arguments (opcode 0x00)
3. Server streams data frames (opcode 0x00)
4. Server sends end frame (opcode 0x01) or error frame (opcode 0x02)

Ticket Authentication

IonPath uses a ticket-based auth model instead of standard bearer tokens:

The IIonTicketExchange interface on the server validates tickets and associates them with a user identity. The IonTicketExtractor handles extraction from the appropriate header for each transport.

Protocol Errors

Errors are signaled via IonProtocolError with an integer code and message string. The error frame in WebSocket uses opcode 0x02. For unary HTTP calls, errors are returned with appropriate HTTP status codes.

IonDescriptorStorage

IonDescriptorStorage holds the metadata for all registered services — including formatter references, executor factories, and route patterns. Generated code registers descriptors at module initialization.