bevy_quinnet

Quinnet provides three channel types to control delivery guarantees and ordering:

• OrderedReliable: Guaranteed delivery and strict ordering (e.g., for chat).
• UnorderedReliable: Guaranteed delivery, but order is not preserved (e.g., for animation triggers).
• Unreliable: No guarantees on delivery or order (e.g., for high-frequency entity positions).

Channels can be pre-configured during connection/endpoint setup using SendChannelsConfiguration, or opened/closed dynamically at runtime. You can have up to 256 channels open simultaneously. Each connection/endpoint has a default channel used when no specific ChannelId is provided.

// Pre-configuring channels at startup
let channels_config = SendChannelsConfiguration::from_configs(vec![
    ChannelConfig::default_ordered_reliable(), // ID 0
    ChannelConfig::default_ordered_reliable(), // ID 1
    ChannelConfig::default_unreliable(),       // ID 2
]);

// Using channels on a client connection
let connection = client.connection();
connection.send_message(message); // Uses default
connection.send_message_on(channel_id, message); // Uses specific ID
connection.set_default_channel(channel_id); // Changes default

// Opening a new channel dynamically
let chat_channel = client.connection().open_channel(ChannelConfig::default()).unwrap();
client.connection().send_message_on(chat_channel, chat_message);

To implement a client, add the QuinnetClientPlugin to your Bevy app. Use the QuinnetClient resource to manage connections and exchange messages. Note that receive_message is generic and works with user-defined enums that implement Serialize and Deserialize.

// 1. Add the plugin
App::new()
    .add_plugins(QuinnetClientPlugin::default())
    .run();

// 2. Connect to a server
fn start_connection(mut client: ResMut<QuinnetClient>) {
    client
        .open_connection(ClientConnectionConfiguration {
            addr_config: ClientAddrConfiguration::from_ips(
                SERVER_HOST,
                SERVER_PORT,
                LOCAL_BIND_IP,
                0,
            ),
            cert_mode: CertificateVerificationMode::SkipVerification,
            defaultables: Default::default(),
        })
        .unwrap();
}

// 3. Handle messages
fn handle_server_messages(mut client: ResMut<QuinnetClient>) {
    while let Some(message) = client.connection_mut().try_receive_message() {
        match message {
            ServerMessage::ChatMessage { client_id, message } => { /* ... */ }
            // ... other variants
        }
    }
}

To implement a server, add the QuinnetServerPlugin to your Bevy app. Use the QuinnetServer resource to start an endpoint. You can process messages from all clients via the endpoint and send messages to specific ClientIds or groups.

// 1. Add the plugin
App::new()
    .add_plugins(QuinnetServerPlugin::default())
    .run();

// 2. Start listening
fn start_listening(mut server: ResMut<QuinnetServer>) {
    server
        .start_endpoint(ServerEndpointConfiguration {
            addr_config: EndpointAddrConfiguration::from_ip(Ipv6Addr::UNSPECIFIED, 6000),
            cert_mode: CertificateRetrievalMode::GenerateSelfSigned {
                server_hostname: Ipv6Addr::LOCALHOST.to_string(),
            },
            defaultables: Default::default(),
        })
        .unwrap();
}

// 3. Handle client messages
fn handle_client_messages(mut server: ResMut<QuinnetServer>) {
    let mut endpoint = server.endpoint_mut();
    for client_id in endpoint.clients() {
        while let Some(message) = endpoint.try_receive_message(client_id) {
            match message {
                ClientMessage::Join { username } => {
                    endpoint.try_send_message(client_id, ServerMessage::InitClient { /*...*/ });
                }
                // ... other variants
            }
        }
    }
}

You can customize how TrustOnFirstUse behaves by configuring the TrustOnFirstUseConfig struct.

Custom Store File

To use a specific file instead of the default quinnet/known_hosts, use KnownHosts::HostsFile:

client.open_connection(/*...*/, CertificateVerificationMode::TrustOnFirstUse(TrustOnFirstUseConfig {
    known_hosts: KnownHosts::HostsFile("MyCustomFile".to_string()),
    ..Default::default()
}),
);

Custom Store and Verifier Behavior

To use an in-memory store (e.g., a HashMap) and define specific automated actions for different certificate statuses, use KnownHosts::Store and the verifier_behaviour field.

Available CertVerifierAction options:

• TrustAndStore: Trust the certificate and save it to the store.
• AbortConnection: Immediately terminate the connection.
• TrustOnce: Trust the certificate for this session only.
• RequestClientAction: Raise a CertInteractionEvent to ask the user for input.

client.open_connection(/*...*/, CertificateVerificationMode::TrustOnFirstUse(TrustOnFirstUseConfig {
    known_hosts: KnownHosts::Store(my_cert_store),
    verifier_behaviour: HashMap::from([
            (CertVerificationStatus::UnknownCertificate, CertVerifierBehaviour::ImmediateAction(CertVerifierAction::TrustAndStore)),
            (CertVerificationStatus::UntrustedCertificate, CertVerifierBehaviour::ImmediateAction(CertVerifierAction::AbortConnection)),
            (CertVerificationStatus::TrustedCertificate, CertVerifierBehaviour::ImmediateAction(CertVerifierAction::TrustOnce)),
        ]),
}),
);

You can control how the client validates server certificates using the CertificateVerificationMode enum. There are three available modes:

1. SkipVerification: No verification is performed on the server certificate. Use this only for testing or in environments where security is not a concern.
2. SignedByCertificateAuthority: The client only trusts certificates signed by a conventional Certificate Authority (CA).
3. TrustOnFirstUse(TrustOnFirstUseConfig): Implements the Trust on First Use (TOFU) scheme. The client trusts the certificate the first time it connects and remembers it for future connections.

use bevy_quinnet::client::certificate::{CertificateVerificationMode, TrustOnFirstUseConfig, KnownHosts};

let config = TrustOnFirstUseConfig {
    known_hosts: KnownHosts::HostsFile("my_own_hosts_file".to_string()),
    ..Default::default()
};

let mode = CertificateVerificationMode::TrustOnFirstUse(config);