Envelopes and routing

The default LilyEnvelopeCodec carries an application message in a JSON envelope. Using a WebSocket Text or Binary frame does not let you skip that envelope.

Event envelope#

{
  "protocol_version": 2,
  "msg_type": "event",
  "event": "hello:greet",
  "content_kind": "json",
  "content_type": "application/json",
  "encoding": "identity",
  "data": { "name": "Ada" },
  "namespace": "hello",
  "timestamp": 0
}

The event carries the full namespace:action name. It must match the connection's namespace; route lookup is exact and case-sensitive. Lookup occurs before the message DI scope and user hooks. An unknown action is not treated as an application message that reaches a guard.

Content kinds#

For example, base64 AAEC represents the bytes [0, 1, 2]. For a typed binary event:

{
  "protocol_version": 2,
  "msg_type": "event",
  "event": "techniques:binary",
  "content_kind": "binary",
  "content_type": "application/octet-stream",
  "encoding": "base64",
  "data": "AAEC",
  "ack_id": "binary-1"
}

This message targets the binary action in the extractor example. Putting raw file bytes in a WebSocket Binary frame does not produce a valid default Lily v2 envelope. send_binary selects the transport frame, while BinaryPayload selects the kind of application content.

Optional fields#

If supplied, namespace must match the route. timestamp defaults to 0 when absent and cannot be negative. ack_id correlates the response and is limited to 128 bytes. Message IDs also have a 128-byte limit. The envelope's metadata field holds at most 32 string pairs, with keys up to 128 bytes and values up to 1024 bytes.

MessageHeaders reads this envelope metadata, not HTTP Upgrade headers. Do not derive identity or room permissions from client-supplied text in these fields. Unknown envelope fields are rejected; put custom content in your DTO's data instead of adding arbitrary fields outside the schema.

Incoming versus outgoing messages#

The codec can decode an ACK envelope, but server dispatch accepts only inbound event messages. Calling an ordinary action by sending msg_type: "ack" to the server is unsupported. The server's ACK authority comes from the incoming event's ack_id.

Malformed envelopes, namespace mismatches, unknown routes, and domain rejections are separate boundaries. Errors explains public failure outcomes, while outcomes explains successful returns. Frame/message byte limits are covered in backpressure and the reference.