Crate nevy

Crate nevy 

Source
Expand description

§Nevy

Nevy is a quic networking library built with quinn in bevy.

§Getting started

To start a connection with quic you need an endpoint. An endpoint is an entity that contains the state machine for all of it’s connections.

let endpoint_entity = commands
    .spawn(
        QuicEndpoint::new(
            "0.0.0.0:0", // Bind to any port.
            quinn_proto::EndpointConfig::default(),
            None, // No server config.
            AlwaysRejectIncoming::new(), // never accept incoming connections.
        )
        .unwrap(),
    )
    .id();

To open a connection you insert the ConnectionOf component along with a ConnectionConfig. This will also insert a QuicConnection onto the entity if opening the connection succeeds, and will always insert a ConnectionStatus. This component is an identifier for the connection within the endpoint.

commands.spawn((
    ConnectionOf(endpoint_entity),
    QuicConnectionConfig {
        client_config: create_connection_config(),
        address: "127.0.0.1:27518".parse().unwrap(),
        server_name: "example.server".to_string(),
    },
));

Nevy uses relations between ConnectionOf and EndpointOf to represent it’s connections. This means that to respond to incoming connections you can query for added connections.

connection_q: Query<Entity, Added<QuicConnection>>

To interact with a QuicConnection you need to retrieve it’s state from the QuicEndpoint it is a ConnectionOf.

This is a system that will send a message on a quic stream whenever a connection establishes.

fn send_message(
    connection_q: Query<
        (&ConnectionOf, &QuicConnection, &ConnectionStatus),
        Changed<ConnectionStatus>,
    >,
    mut endpoint_q: Query<&mut QuicEndpoint>,
) -> Result<(), BevyError> {
    for (connection_of, connection, status) in connection_q.iter() {
        // only operate on connections that have just changed to established
        let ConnectionStatus::Established = status else {
            continue;
        };

        // get the endpoint component
        let mut endpoint = endpoint_q.get_mut(**connection_of)?;

        // get the connection state from the endpoint
        let connection = endpoint.get_connection(connection)?;

        // open a unidirectional stream on the connection.
        let stream_id = connection
            .open_stream(Dir::Uni)
            .ok_or("Streams should not be exhausted")?;

        // write some data
        connection.write_send_stream(stream_id, "Hello Server!".as_bytes())?;

        // finish the stream
        connection.finish_send_stream(stream_id)?;

        info!("Connection established, sent message");
    }

    Ok(())
}

Lastly, when connections close the entity is not despawned nor are any of it’s connection components removed. This is so that you can still retrieve the connection state from it’s endpoint to read any remaining data. Make sure to despawn any closed connections once you are done with them.

The entity can be reused for another connection once it’s ConnectionOf component is removed or replaced.

§Bevy versions

BevyNevy
0.160.1
0.170.2.3

Re-exports§

pub use quinn_proto;

Structs§

AlwaysAcceptIncoming
This type implements IncomingConnectionHandler and will always accept incoming connections.
AlwaysRejectIncoming
This type implements IncomingConnectionHandler and will always reject incoming connections.
Chunk
A chunk of data received by a stream
ConnectionMut
ConnectionOf
This component represents a connection on a QuicEndpoint.
EndpointOf
Relationship target for all ConnectionOfs for a QuicEndpoint
EndpointWithHeaderedConnections
When this component exists on an endpoint the RecvStreamHeaders component will automatically be inserted onto all new connections of that endpoint.
EndpointWithNetMessageConnections
When this component exists on an endpoint the [NetMessageRecvStreams] component will automatically be inserted onto all new connections of that endpoint.
HeaderedStreamState
A state machine used for writing a header and then stream data.
LocalNetMessageSender
System parameter that holds a Local NetMessageSendStreamState for each connection.
NetMessageId
Holds the id of a message.
NetMessageReceiveHeader
Holds the unique stream header id to recieve messages on.
NetMessageReceiveStreams
Holds the state machines for the message streams of a connection.
NetMessageSendHeader
Holds the unique stream header id to send messages on.
NetMessageSendStreamState
State machine for a stream that sends messages.
NevyHeaderPlugin
Adds stream header logic to an app.
NevyNetMessagesPlugin
Adds message receiving logic to an app.
NevyPlugin
Plugin which adds observers and update systems for quic endpoints and connections.
NoConnectionState
Returned when attempting to get the connection state from a QuicEndpoint with an invalid QuicConnection
QuicConnection
Component that exists on an entity when it is a ConnectionOf a QuicEndpoint.
QuicConnectionConfig
Must be inserted onto a connection entity to open a connection.
QuicEndpoint
A quic endpoint.
ReceivedNetMessages
Buffer of received messages from all streams for a connection.
RecvStreamHeaders
Stores incoming streams that are processing headers or ready to be used.
SharedNetMessageSender
System parameter that accesses a shared NetMessageSendStreamState for each connection.
StreamId
Id for a stream on a particular connection
StreamsExhausted
An error returned when the maximum number of streams of a given direction has been reached.
UpdateEndpointSystems
System set where quic endpoints are updated and packets are sent and received.
UpdateHeaderSystems
System set where streams are accepted and headers are processed.
VarIntBoundsExceeded
A value was too large for a quic variable length integer

Enums§

ConnectionStatus
The status of a QuicConnection.
Dir
Whether a stream communicates data in both directions or only from the initiator
ResetStreamError
An error returned when resetting a stream fails
StopStreamError
An error returned when stopping a stream fails
StreamEvent
Events to do with streams.
StreamFinishError
An error returned when finishing a stream fails
StreamReadError
An error returned when reading from a stream fails
StreamWriteError
An error returned when writing to a stream fails
UpdateNetMessageSystems
System sets messages are processed.

Constants§

DEFAULT_NEVY_SCHEDULE
The schedule that nevy performs updates in by default

Traits§

AddNetMessage
Trait extension for App that allows assigning adding messages.
AddSharedSender
Trait extension for App that allows adding a SharedNetMessageSender.
IncomingConnectionHandler
Implement this trait to define logic for handling incoming connections.
NetMessageSender