Crate net_backend_protocol

Expand description

Shared message types for net_backend_server: plain Rust + serde, usable from any Rust client.

The server and its clients use the same types, so both sides agree on every request, answer and push, and on the JSON they become. The crate contains only data types and pure helpers: no networking, no async runtime, no game engine.

envelope: the WebSocket frames (request, answer, push, first-message auth), close codes, the WsCall / ServerPush traits.
error: the error body of HTTP and WebSocket answers (ApiError) and the stable codes.
ids, time, page: id newtypes on i64, UnixMillis timestamps, cursor pagination.
auth: accounts and sessions (email + password, Steam, refresh, logout, verify, reset), with secrets that never show in Debug.
admin: account administration (list, ban, sessions, roles) and the audit log.
storage: per-user key-value objects (saves) with optimistic versions.
chat: rooms, direct messages, sending, history and the chat.message push.
kinds and routes: every WebSocket type and HTTP path as constants.
http_call: the HttpCall trait pairing every HTTP route with its payload and answer type (the HTTP twin of WsCall).
version: PROTOCOL_VERSION and how it is exchanged.

Feature bevy_net_backend (off by default) implements that client crate’s WsRequest / WsPushMessage for the WebSocket messages and Credentials for AccessToken. The README is the full manual.

Re-exports§

pub use auth::AccessToken;
pub use auth::Password;
pub use auth::RefreshToken;
pub use auth::Secret;
pub use envelope::Ack;
pub use envelope::CloseCode;
pub use envelope::FrameError;
pub use envelope::ServerPush;
pub use envelope::WsAuth;
pub use envelope::WsAuthOk;
pub use envelope::WsCall;
pub use envelope::WsClientFrame;
pub use envelope::WsPushFrame;
pub use envelope::WsRequestFrame;
pub use envelope::WsResponseFrame;
pub use envelope::WsServerFrame;
pub use error::codes;
pub use error::ApiError;
pub use error::ErrorBody;
pub use error::ValidationDetails;
pub use http_call::HttpCall;
pub use http_call::NoPayload;
pub use http_call::PathParams;
pub use http_call::PayloadKind;
pub use ids::MessageId;
pub use ids::RoomId;
pub use ids::UserId;
pub use page::Cursor;
pub use page::Page;
pub use page::PageRequest;
pub use time::UnixMillis;
pub use version::GetServerInfo;
pub use version::ServerInfo;
pub use version::PROTOCOL_HEADER;
pub use version::PROTOCOL_VERSION;

Modules§

admin: Administration: list and inspect accounts, ban and unban them, revoke their sessions, grant and revoke roles, read the audit log, read and write a user’s storage objects (AdminPutObject may set the server write lock). Routes: routes::admin; every one needs an access token of an account with the ADMIN_ROLE role (others get 403 forbidden).
auth: Accounts and sessions: register, login (email + password or a Steam ticket), refresh, logout, the caller’s Account, email verification and password reset. Routes: routes::auth and routes::account.
chat: Chat: rooms, direct messages, sending and history. Joining, leaving, sending and live messages go over the WebSocket (kinds chat.*); the room list, history pages and opening a direct-message room are also HTTP routes (routes::chat).
envelope: The WebSocket envelope: JSON objects in text frames, exactly as bevy_net_backend 0.1.0’s JsonEnvelope speaks them.
error: The error body shared by HTTP and WebSocket: ApiError (code, message, optional details) and the stable error codes.
http_call: Typed HTTP calls: HttpCall pairs a request type with its route (method, path template, authentication), its payload (JSON body, query string or nothing) and its answer type, like WsCall does for WebSocket requests. Server, client and any Rust app share the contract, so a path, a method or an answer type cannot drift between them.
ids: Id newtypes. Every id is a signed 64-bit integer (a BIGINT column on every supported database) and travels as a plain JSON number: {"user_id":42}.
kinds: The WebSocket message kinds: the type field of every frame. Public API from 0.1.0: never renamed; new kinds may be added. A module’s kinds start with the module name and a dot.
page: Cursor pagination: a list endpoint answers a Page with up to limit items and, when there are more, an opaque Cursor to pass back for the next page.
routes: The HTTP routes. Everything versioned lives under PREFIX (/v1), which is public API from 0.1.0: a route is never renamed or removed within /v1, new routes may be added. Path parameters use the {name} syntax; the *_path helpers fill them in.
storage: Storage: save slots and other per-user key-value objects. Routes: routes::storage.
text: Character rules shared by the validate() methods: which characters a name, an email address or a chat message may not contain.
time: Timestamps: UnixMillis, milliseconds since 1970-01-01 00:00:00 UTC as a signed 64-bit integer (a BIGINT column on every supported database, no time zones, no 2038 problem). On the wire it is a plain JSON number: {"sent_at":1790000000000}.
version: Protocol versioning.