Realtime Ingress Validation And Failure Policy
Realtime ingress validation decides whether a client packet is accepted, dropped, or turns into a disconnect. The policy is descriptor-owned: generated realtime registry metadata names the packet, the handler, the packet budget, fairness throttle metadata, failure reason, disconnect code, and whether a failure should stop the stream.
Purpose
Use this page when adding a client-to-server realtime packet, changing packet limits, or debugging sessions that disconnect after a malformed, oversized, misrouted, or rate-limited message.
The important boundary is that packet validation is not just parsing. The server validates the stream or datagram envelope, decodes the packet, applies shared field validation, checks transport-class rules, applies fairness throttles where the descriptor requires them, records packet-validation metrics, and only then dispatches to gameplay, movement, chat, trigger, snapshot-receipt, heartbeat, or disconnect handlers.
Stream Ingress Pipeline
Stream ingress starts in handle_inbound_realtime_stream_packet. The reliable stream reader yields a stream class and envelope. The server validates the envelope against the runtime profile, looks up client_stream_ingress_metadata, decodes the packet, validates packet fields, checks that the packet is allowed on the current reliable stream class, and dispatches through the descriptor handler.
Envelope failures are always fatal to the stream. Decode, field-validation, handler-mismatch, and stream-class failures use the descriptor's failure metadata. Some field failures disconnect, while descriptor-marked failures can drop and continue.
Datagram Ingress Pipeline
Datagram ingress is transport-adaptive. The runtime profile owns the frame and packet size budgets. Datagram validation checks the outer frame, decodes the datagram, validates decoded fields, and records packet-validation failures with descriptor packet names so metrics match the protocol registry.
Datagrams are best-effort, so rate-limit and malformed-packet behavior must be intentionally chosen. Do not copy stream failure behavior into a datagram handler unless the descriptor explicitly says a bad datagram should disconnect the session.
Descriptor-Owned Failure Controls
The shared failure object carries packet_kind, reason, disconnect_code, control, and a stable metric label. DisconnectAndStopStream writes a realtime disconnect packet and closes the stream path. DropAndContinue records the failure and lets the session keep reading.
When changing a failure mode, update the descriptor metadata and shared packet-validation tests first. Runtime code should consume descriptor output rather than hard-coding a packet-specific disconnect policy.
Rate Limits
Fairness throttles are distinct from admission abuse throttles. Ingress fairness applies to already-activated clients and is tied to packet families such as movement, chat, gameplay state, equipment state, trigger authority, gameplay action, and snapshot repair.
If a descriptor has rate-limit metadata, the ingress path converts the throttle rejection into the descriptor's packet-validation failure. Trigger authority also records trigger-specific rejection metrics.
Debugging
Start with packet-validation metrics and disconnect codes. packet_too_large usually means the runtime profile and packet budget disagree with the payload size. malformed_packet usually means an unknown message id, wrong direction, invalid enum, decode error, or field validation failure. rate_limited points to fairness throttle metadata and local per-IP or per-session limiter state.
For stream-class issues, compare the client packet kind with the negotiated reliable stream topology. For datagram issues, compare the runtime profile datagram budget with the generated datagram descriptor.