plaza_session
License: Mozilla Public License 2.0 (MPL-2.0) · Status: Experimental
Real network transports for plaza: actix-web WebSockets and length-delimited TCP. Hand one to a StateController instead of writing a transport yourself.
How to use it: README.USAGE.md. Full surface: API_REFERENCE.md.
Install
[]
= "0"
= { = "0", = false, = ["actix_ws", "json"] }
| Feature | Default | Gives you |
|---|---|---|
actix_ws |
yes | ActixWsPlazaSession: WebSockets on actix-web 4 |
tcp |
yes | TcpPlazaSession: length-delimited TCP |
actix_host |
no | host::Host: the listen-server HTTP layer, serving a browser client from the same origin as the socket |
json |
yes | JsonCodec and the codec a session type falls back to when it names none |
msgpack |
no | MsgPackCodec and MsgPackNamedCodec |
The shared connection manager compiles either way.
Turning off json drops serde_json from the build, so name the transport features you want instead of only setting default-features = false. You lose the constructors that take no codec argument (new, bind) and the default type parameter, so a session type names its codec: ActixWsPlazaSession<Op, PlayerId, MsgPackCodec>. actix_ws brings serde_json back regardless, since actix-web depends on it. A build without serde_json uses TCP or a transport of your own.
What it gives you
| Problem | Piece |
|---|---|
| Serving a browser client over WebSockets | ActixWsPlazaSession |
| A native client over a length-delimited byte stream | TcpPlazaSession |
| Turning a socket away before anything is allocated or announced | AgentFactory returning a Farewell (TCP); the route, before handle_connection (WebSocket) |
| Admitting a socket on a credential it presents after the upgrade, held unregistered until then | ConnectionAdmitter behind admit_connection or bind_with_admitter (see admission) |
| Knowing how far away a client is, without asking it | agent_rtt (the socket) and agent_link_rtt (a real frame's journey) |
| Stamping a reply with your simulation clock, so a client can fit the offset | SessionOptions::clock |
| Testing at 200ms with 5% loss on a local machine | LinkProfile, DirectionProfile, Delivery |
| Sizing every queue and cap from what your game actually does | Workload and its seven presets |
| Deciding what a full queue costs: a frame, a connection or a stall | Overflow |
| Ending a session with a close code and a reason the client hears on any transport | Farewell through close_connection, deregister_agent, disconnect_all |
| Bounding a session that must expire | set_deadline |
| Knowing who is idle and who is flooding | agent_idle_for, agent_inbound |
| Making a flood cost the client that sent it and nobody else | SessionOptions::rate_limit_inbound with a Rate (see gate) |
| Sending a slow client fewer, complete frames instead of dropping some | set_outbound_budget with an OutboundBudget, then agent_owed at the snapshot pass (see budget) |
| Telling a stale client it is stale | ProtocolVersion in a Hello, read back with protocol |
| Serving a wasm bundle from the same origin as the socket | host::Host (feature actix_host) |
| The whole simulation stack behind that | host::SimHost |
| Putting plaza on QUIC, Steam or another transport | TransportSession + LinkDriver |
Status
Experimental. The API changes.