Crate nevy 

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

Bevy	Nevy
0.16	0.1

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

ConnectionOf

This component represents a connection on a QuicEndpoint.

ConnectionState

The state for a connection accessed through a QuicEndpoint using a QuicConnection component.

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.

EndpointWithMessageConnections

When this component exists on an endpoint the MessageRecvStreams 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.

LocalMessageSender

System parameter that holds a Local MessageSendStreamState for each connection.

MessageId

Holds the id of a message.

MessageRecvStreams

Holds the state machines for the message streams of a connection.

MessageSendStreamState

State machine for a stream that sends messages.

NevyHeaderPlugin

Adds stream header logic to an app.

NevyMessagesPlugin

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.

ReceivedMessages

Buffer of received messages from all streams for a connection.

RecvStreamHeaders

Stores incoming streams that are processing headers or ready to be used.

SharedMessageSender

System parameter that accesses a shared MessageSendStreamState 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.

UpdateEndpoints

System set where quic endpoints are updated and packets are sent and received.

UpdateHeaders

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

UpdateMessageSet

System sets messages are processed.

Constants

DEFAULT_NEVY_SCHEDULE

The schedule that nevy performs updates in by default

Traits

AddMessage

Trait extension for App that allows assigning adding messages.

AddSharedSender

Trait extension for App that allows adding a SharedMessageSender.

IncomingConnectionHandler

Implement this trait to define logic for handling incoming connections.