Crate netcode [] [src]

Rust implementation of netcode.io protocol.

This crate contains Server, Client and ConnectToken used to establish a netcode.io session.

Connect Token

Each netcode.io session starts with a ConnectToken. This token is handed out by a HTTPS webserver, authentication server or other private avenue to allow a client to establish a connection with a netcode.io based server. Rather than specifying an address the list of hosts are contained within the token. Note that private keys are included in the clear so HTTPS or other secure measures for delivering the token to the client are required.

Server

The netcode.io server is created with the UDPServer::new(...) call. It accepts a local address, number of clients and private key used to sign the ConnectTokens send to the connecting clients.

Client

The netcode.io client is created with the UDPClient::new(...) call. It accepts a connection token that has been handed out from a webserver or equivalent secure connection.

Server Example

use netcode::{UdpServer, ServerEvent};

fn run_server() {
    const PROTOCOL_ID: u64 = 0xFFEE;
    const MAX_CLIENTS: usize = 32;
    let mut server = UdpServer::new("127.0.0.1:0",
                                    MAX_CLIENTS,
                                    PROTOCOL_ID,
                                    &netcode::generate_key()).unwrap();

    loop {
        server.update(1.0 / 10.0);
        let mut packet_data = [0; netcode::NETCODE_MAX_PAYLOAD_SIZE];
        match server.next_event(&mut packet_data) {
            Ok(Some(e)) => {
                match e {
                    ServerEvent::ClientConnect(_id) => {},
                    ServerEvent::ClientDisconnect(_id) => {},
                    ServerEvent::Packet(_id,_size) => {
                        //Packet from `id` of `size` length stored in `packet_data`
                    },
                    _ => {}
                }
            },
            Ok(None) => {},
            Err(err) => Err(err).unwrap()
        }

        //Tick world/gamestate/etc.
        //Sleep till next frame.
    }
}

Client Example

use netcode::{UdpClient, ClientEvent, ClientState, ConnectToken};
use std::io;

fn run_client() {
    let token_data = [0; 1024]; //Note that this should come from your webserver
                                //or directly from the server you're connecting to.
                                //It must be sent over a secure channel because
                                //it contains private keys in the clear.
    let token = ConnectToken::read(&mut io::Cursor::new(&token_data[..])).unwrap();
    let mut client = UdpClient::new(&token).unwrap();
    loop {
        client.update(1.0 / 10.0);
        let mut packet_data = [0; netcode::NETCODE_MAX_PAYLOAD_SIZE];
        match client.next_event(&mut packet_data) {
            Ok(Some(e)) => {
                match e {
                    ClientEvent::NewState(state) => match state {
                        ClientState::Connected => {},
                        ClientState::Disconnected => {},
                        _ => {}
                    },
                    ClientEvent::Packet(_size) => {
                        //Packet of `size` length stored in `packet_data`
                    },
                    _ => {}
                }
            },
            Ok(None) => {},
            Err(err) => Err(err).unwrap()
        }

        //Sleep till next frame.
    }
}

Token Example

use netcode::{self, ConnectToken};
use std::io;

const EXPIRE_SECONDS: usize = 30;
const PROTOCOL_ID: u64 = 0xFFEE;

let private_key = netcode::generate_key(); //Note: You probably want to
                                           //store this some where safe.
let client_id = get_client_id(); //Unique u64 client id.
let sequence = get_next_sequence(); //sequence passed to generate() must
                                    //be a monotically increasing u64
                                    //to prevent replay attacks.                                        
let user_data = None;   //Any custom user data, can be up to 256 bytes.
                        //Will be encrypted and returned to sever on connect.

let token = ConnectToken::generate_with_string(["127.0.0.1:5000"].iter().cloned(),
                                               &private_key,
                                               EXPIRE_SECONDS,
                                               sequence,
                                               PROTOCOL_ID,
                                               client_id,
                                               user_data).unwrap();
let mut token_data = vec!();
token.write(&mut token_data).unwrap();
//Alteratively if you already have a server you can generate a token like below:
const PROTOCOL_ID: u64 = 0xFFEE;
const MAX_CLIENTS: usize = 32;
let mut server = UdpServer::new("127.0.0.1:0",
                                MAX_CLIENTS,
                                PROTOCOL_ID,
                                &netcode::generate_key()).unwrap();

const EXPIRE_SECONDS: usize = 30;
let client_id = get_client_id(); //Unique u64 client id.

let token = server.generate_token(EXPIRE_SECONDS, client_id, None).unwrap();

Structs

Client

Netcode client object.

ConnectToken

Token used by clients to connect and authenticate to a netcode Server

Server

Netcode server object.

Enums

ClientEvent

Describes event the server receives when calling next_event(..).

ClientState

States represented by the client

InternalError

Errors internal to netcode.

RecvError

Errors from receiving packets

SendError

Errors from sending packets

ServerEvent

Describes event the server receives when calling next_event(..).

UpdateError

Errors from calls to next_event().

Constants

NETCODE_MAX_PACKET_SIZE

Maximum size packet that is sent over the wire.

NETCODE_MAX_PAYLOAD_SIZE

Maximum size of a payload that can be sent(1175).

NETCODE_USER_DATA_BYTES

Maximum size of userdata included in ConnectToken.

Functions

generate_key

Generates a new random private key.

Type Definitions

UdpClient

UDP based netcode client.

UdpServer

UDP based netcode server.