Skip to content

Core format

Anirudh Balaji edited this page Jun 10, 2020 · 11 revisions

This is a description of the transit-independent, extensible PearDrop protocol.

Packet types

All offsets are in big endian, and offsets and lengths are in bytes. Multi-byte payloads are to be coded in big endian.

In bitfields, offsets are in little endian, and offsets and lengths are in bits.

Advertisement packet

Maximum length: 128 bytes

From: sender

To: advertise

Offset Length Type Name Description
0x0 0x1 u8 exts_len Number of extensions this packet contains.
0x1 max 0x7f [Extension; ext_len] exts The extensions in this packet. Maximum 127 bytes total.

end: 0x80

AdFlags bitfield

Reserved for extensions.

Sender packet

Maximum length: 4096 bytes

From: sender

To: single receiver

Offset Length Type Name Description
0x0 12 bits u12 name_len Length of the filename. Maximum of 4084 bytes.
12 bits 12 bits u12 mime_len Length of the MIME type. Maximum of 4084 bytes.
0x1 name_len &str name Filename of the file being sent. Maximum length of 4084 bytes.
0xff6 mime_len &str mimetype MIME type of the file being sent. Maximum length of 4084 bytes.
0x0 0x1 u8 ext_len Number of extensions this packet contains.
0x1 max 0xff8 [Extension; ext_len] exts The extensions in this packet. Maximum 4088 bytes total.
0xff8 0x8 u64 len Length of the data.

end: 0x1000

Receiver acknowledge packet

Maximum length: 128 bytes

From: receiver

To: sender

Offset Length Type Name Description
0x0 4 bits ReceiverAcknowledgeType type Type of the packet being acknowledged.
4 bits 4 bits u4 exts_len Number of extensions in this packet.
0x1 max 0x7f [Extension; ext_len] exts The extensions in this packet. Maximum 31 bytes total.

end: 0x80

ReceiverAcknowledgeType bitfield

Let the 4 bits of this type be a,b,c,d where a is the highest bit.

b,c,d should contain an (anonymous) enum, better described with code as compared to a table:

#[repr(u3)]
pub enum __anonymous__ {
	SenderPacket,
	DataPacket,
	AdPacket,
}

If the type is AdPacket or SenderPacket then a is a flag indicating accept/reject where 1 is accept and 0 is reject. Otherwise, it should be assumed to be part of the enum.

Data packet

No maximum length. This should be the length specified in the sender packet.

This should be sent over a reliable stream protocol (like TCP), or properly chunked otherwise.

This packet simply consists of the data and nothing else.

Common types

Extension trait

Reserved for extensions. All sub-structs must have these fields at the start:

Offset Length Type Name Description
0x0 0x1 ExtType type Type of this extension.

ExtType enum

Must fit in a u8. Reserved for extensions.

Handshake

Sender     Receiver(s)     Receiver
   ------------->
   advertisement

   <----------------------------
   acknowledge: advertisement

   <--------------------------->
   (optional) extension pre-handshakes

   ---------------------------->
   sender packet

   <----------------------------
   acknowledge: sender

   <--------------------------->
   (optional) extension post-handshakes

   ---------------------------->
   data packet

   <----------------------------
   acknowledge: data

   transfer complete :)
Clone this wiki locally