Crate gday_contact_exchange_protocol

Expand description

Protocol for peers to exchange their socket addresses via a server.

On it’s own, this library doesn’t do anything other than define a shared protocol. In most cases, you should use one of the following crates:

gday: A command line tool for sending files to peers.
gday_hole_punch: A library for establishing a peer-to-peer TCP connection.
gday_server: A server binary that facilitates this protocol.

§Example

First, both peers connect with TLS on both IPv4 and IPv6 (if possible) to a gday server on DEFAULT_PORT. Then they exchange contacts like so:

use gday_contact_exchange_protocol::{ClientMsg, Contact, ServerMsg, read_from, write_to};
let room_code = String::from("Room code");

// One client tells the server to create a room.
// The server responds with ServerMsg::RoomCreated or
// an error message.
let request = ClientMsg::CreateRoom {
    room_code: room_code.clone(),
};
write_to(&request, &mut tls_ipv4)?;
let ServerMsg::RoomCreated = read_from(&mut tls_ipv4)? else {
    panic!()
};

// Both peers send ClientMsg::RecordPublicAddr
// from their IPv4 and/or IPv6 endpoints.
// The server records the client's public addresses from these connections.
// The server responds with ServerMsg::ReceivedAddr or an error message.
let request = ClientMsg::RecordPublicAddr {
    room_code: room_code.clone(),
    is_creator: true,
};
write_to(&request, &mut tls_ipv4)?;
let ServerMsg::ReceivedAddr = read_from(&mut tls_ipv4)? else {
    panic!()
};
write_to(&request, &mut tls_ipv6)?;
let ServerMsg::ReceivedAddr = read_from(&mut tls_ipv6)? else {
    panic!()
};

// Both peers share their local address with the server.
// The server immediately responds with ServerMsg::ClientContact,
// containing the client's FullContact.
let local_contact = Contact {
    v4: Some("1.8.3.1:2304".parse()?),
    v6: Some("[ab:41::b:43]:92".parse()?),
};
let request = ClientMsg::ReadyToShare {
    local_contact,
    room_code,
    is_creator: true,
};
write_to(&request, &mut tls_ipv4)?;
let ServerMsg::ClientContact(my_contact) = read_from(&mut tls_ipv4)? else {
    panic!()
};

// Once both clients have sent ClientMsg::ReadyToShare,
// the server sends both clients a ServerMsg::PeerContact
// containing the FullContact of the peer.
let ServerMsg::PeerContact(peer_contact) = read_from(&mut tls_ipv4)? else {
    panic!()
};

// The server then closes the room, and the peers disconnect.

// The peers then connect directly to each other using a library
// such as gday_hole_punch.

Structs§

Contact: The addresses of a single client. May have IPv6, IPv4, none, or both.
FullContact: The local and public endpoints of an client.

Enums§

ClientMsg: A message from client to server.
Error: Message serialization/deserialization error.
ServerMsg: A message from server to client.

Constants§

DEFAULT_PORT: The port that contact exchange servers using TLS should listen on.
PROTOCOL_VERSION: Version of the protocol. Different numbers wound indicate incompatible protocol breaking changes.

Functions§