Realtime Datagram Codecs And Ingress Policy

Realtime datagrams carry freshness-first state such as movement, gameplay state, and equipment state. Use them only when loss, duplication, stale arrival, and reordering are acceptable or recoverable.

Contract Families

Client datagrams are encoded and decoded by the common-proto realtime wire codec. Server datagrams use the server envelope side of the same protocol family. The registry describes the packet contract, while codec arms and game-server ingress policy decide how a concrete body is parsed and handled.

Movement datagrams are stricter than cosmetic state. Movement can disconnect or hard-fail on throttle or malformed transport contract violations. Cosmetic gameplay state may be dropped and counted while the session continues.

Version Fields And Defaults

Datagrams do not get compatibility for free. If a datagram body changes semantics, add a registry row, capability, or versioned body shape rather than reinterpreting an existing oneof arm. Default behavior should be conservative because old clients may still send older bodies.

Compatibility Rules

Never put durable side effects on a datagram-only path. Pair reliable completion with a stream message, acknowledgement, repair path, or durable state projection. Unknown oneof kinds, malformed protobuf, payload budget violations, and missing movement transport contracts should fail according to the registry and ingress contract.

Adding Fields Safely

Update the registry descriptor, codec dispatch, validation, server ingress handler, delivery contract, and tests together. Decide whether the packet can be dropped, coalesced, or must disconnect on failure. Add packet capture expectations for debugging the new body.

Test Checklist

Cover registry rows, delivery metadata, encode/decode arms, validator budgets, unsupported datagram bodies, ingress policy, throttling behavior, and packet capture naming.