Crate gday_contact_exchange_protocol

source ·
Expand description

Note: this crate is still in early-development, so expect breaking changes.

This protocol lets two users exchange their public and (optionally) private 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 with DEFAULT_TLS_PORT. Then they exchange contacts like so:

let room_code = 42;

// A client tells the server to create a room.
// The server responds with ServerMsg::RoomCreated or
// ServerMsg::ErrorRoomTaken.
let request = ClientMsg::CreateRoom { room_code };
write_to(request, &mut tls_ipv4)?;
let response: ServerMsg = read_from(&mut tls_ipv4)?;

// Each peer sends ClientMsg::RecordPublicAddr
// from all their endpoints.
// The server records the client's public addresses from these connections.
// The server responds with ServerMsg::ReceivedAddr
let request = ClientMsg::RecordPublicAddr { room_code, is_creator: true };
write_to(request, &mut tls_ipv4)?;
let response: ServerMsg = read_from(&mut tls_ipv4)?;
write_to(request, &mut tls_ipv6)?;
let response: ServerMsg = read_from(&mut tls_ipv6)?;

// Both peers share their local address with the server.
// The server immediately responds with ServerMsg::ClientContact,
// containing each client's FullContact.
let local_contact = Contact {
    v4: todo!("local v4 addr"),
    v6: todo!("local v6 addr")
};
let request = ClientMsg::ReadyToShare { local_contact, room_code, is_creator: true };
write_to(request, &mut tls_ipv4)?;
let response: ServerMsg = read_from(&mut tls_ipv4)?;

// Once both clients have sent ClientMsg::ShareContact,
// the server sends both clients a ServerMsg::PeerContact
// containing the FullContact of the peer.
let response: ServerMsg = read_from(&mut tls_ipv4)?;

// 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 network endpoint. May have IPv6, IPv4, none, or both.
  • FullContact
    The public and local 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_TCP_PORT
    The port that contact exchange servers using unencrypted TCP should listen on.
  • DEFAULT_TLS_PORT
    The port that contact exchange servers using encrypted TLS should listen on.

Functions§