Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Bevy Simplenet
Provides a bi-directional server/client channel implemented over websockets. This crate is suitable for user authentication, talking to a matchmaking service, communicating between micro-services, games that don't have strict latency requirements, etc.
- Client/server channel includes one-shot messages and a request/response API.
- Client message statuses can be tracked.
- Clients automatically work on native and WASM targets.
- Clients can be authenticated by the server.
- Provides optional server TLS.
Check out the example for a demonstration of how to build a Bevy client using this crate.
Check out bevy_simplenet_events for an event-based framework for networking that builds on this crate.
Features
default
: includesbevy
,client
,server
featuresbevy
: derivesResource
onClient
andServer
client
: enables clients (native and WASM targets)server
: enables servers (native-only targets)tls-rustls
: enables TLS for servers viarustls
tls-openssl
: enables TLS for servers viaOpenSSL
WASM
On WASM targets the client backend will not update while any other tasks are running. You must either build an IO-oriented application that naturally spends a lot of time polling tasks, or manually release the main thread periodically (e.g. with web_sys::Window::set_timeout_with_callback_and_timeout_and_arguments_0()
). For Bevy apps the latter happens automatically at the end of every app update/tick (see the bevy::app::ScheduleRunnerPlugin
implementation).
Usage notes
- Servers and clients must be created with enfync runtimes. The backend is ezsockets.
- A client's
AuthRequest
type must match the corresponding server'sAuthenticator
type. - Client ids are defined by clients via their
AuthRequest
when connecting to a server. Connections will be rejected if an id is already connected. - Client connect messages will be cloned for all reconnect attempts, so they should be treated as static data.
- Server or client messages may fail to send if the underlying connection is broken. Clients can use the signals returned from
Client::send()
andClient::request()
to track the status of a message. Client request results will always be emitted byClient::next()
. Message tracking is not available for servers. - Tracing levels assume the server is trusted and clients are not trusted.
Example
An example using bevy
to manage client and server resources.
Setup
Common
Specify all the message types in a ChannelPack
. Messages are automatically serialized and deserialized, so concrete types are required.
/// Clients send these when connecting to the server.
;
/// Clients can send these at any time.
;
/// Client requests are special messages that expect a response from the server.
;
/// Servers can send these at any time.
;
/// Servers send these in response to client requests.
;
;
Server
Prepare to make servers. We need a separate ServerFactory
to embed the channel's protocol version in a centralized location.
Make a server and insert it into an app.
Client
Prepare to make clients. We need a separate ClientFactory
to embed the channel's protocol version, as with the server factory.
Make a client and insert it into an app.
Sending from the client
Send a message. The send
method returns a MessageSignal
that can be used to track the message status.
Send a request. The request
method returns a RequestSignal
that can be used to track the request status.
Sending from the Server
Send a message.
Send a response. The RequestToken
allows us to correctly associate the response with the original response. If you drop the token then the client will automatically receive a ClientEvent::Reject
event and their RequestSignal
will return RequestStatus::Rejected
.
Reading on the client
All client events are synchronized to ensure deterministic, unambiguous behavior.
type TestClientEvent = ;
Reading on the server
All server events are synchronized to ensure deterministic, unambiguous behavior.
type TestServerEvent = ;
Client authentication
Servers have three options for authenticating clients:
Authentication::None
: All connections are valid.Authentication::Secret
: A connection is valid if the client providesAuthRequest::Secret
with a matching secret.Authentication::Token
: A connection is valid if the client providesAuthRequest::Token
with a token produced by your backend.
Generating and managing auth tokens is very simple.
- Generate auth keys in your backend and setup a server.
let = generate_auth_token_keys;
let server = server_factory.new_server;
Typically the keypair will be generated on one frontend server, and the pubkey
will be sent to other servers for running bevy_simplenet
servers that will authenticate tokens.
-
Client sends their credentials (e.g. login name and password) to your frontend.
-
Your frontend validates the credentials and produces an auth token allowing the user's client id
123u128
to connect to your backend.
// This token expires after 10 seconds.
let token = make_auth_token_from_lifetime;
You send this token to the client.
- Client makes a
bevy_simplenet
client using the received token.
let client = client_factory.new_client;
Note that the server_url
can be transmitted alongside the token for convenience. This way clients only need to know the auth token endpoint, and you can provision backend servers as needed.
When the token expires, bevy_simplenet
clients will stop automatically reconnecting on network error and instead shut down and emit ClientEvent::Report(ClientReport::IsDead(_))
. You can request a new auth token and set up a new client in that event.
It is recommended to set a relatively low auth token expiry if you are concerned about DoS from clients clogging up the server's capacity, or if you have a force-disconnect/blacklist mechanism in your backend (which presumably communicates with the auth-token-producing endpoint).
TODOs
- Add server shut down procedure.
- Use const generics to bake protocol versions into
Server
andClient
directly, instead of relying on factories (currently blocked by lack of robust compiler support).
Bevy compatability
bevy | bevy_simplenet |
---|---|
0.14 | v0.12 - master |
0.13 | v0.9 - v0.11 |
0.12 | v0.5 - v0.8 |
0.11 | v0 - v0.4 |