#tcp-connection #exchange #protocols #sockets #contact #peer #file-transfer

gday_contact_exchange_protocol

Protocol for peers to exchange their socket addresses via a server

3 unstable releases

0.2.1 Jul 12, 2024
0.2.0 Jul 8, 2024
0.1.1 Jun 7, 2024

#1688 in Network programming


Used in 3 crates (2 directly)

MIT license

16KB
152 lines

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

gday_contact_exchange_protocol

Crates.io Version docs.rs

This protocol lets two users exchange their public and (optionally) private socket addresses via a server.

See the documentation.

Used by:

  • gday - Command line tool for sending files.
  • gday_server - Server that lets two peers share their socket addresses.
  • gday_hole_punch - Library for establishing peer-to-peer TCP connection.

lib.rs:

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.
#

Dependencies

~2.8–9MB
~84K SLoC