1# Specification 2 3We use this document to detail the internal specification of Yamux. 4This is used both as a guide for implementing Yamux, but also for 5alternative interoperable libraries to be built. 6 7# Framing 8 9Yamux uses a streaming connection underneath, but imposes a message 10framing so that it can be shared between many logical streams. Each 11frame contains a header like: 12 13* Version (8 bits) 14* Type (8 bits) 15* Flags (16 bits) 16* StreamID (32 bits) 17* Length (32 bits) 18 19This means that each header has a 12 byte overhead. 20All fields are encoded in network order (big endian). 21Each field is described below: 22 23## Version Field 24 25The version field is used for future backward compatibility. At the 26current time, the field is always set to 0, to indicate the initial 27version. 28 29## Type Field 30 31The type field is used to switch the frame message type. The following 32message types are supported: 33 34* 0x0 Data - Used to transmit data. May transmit zero length payloads 35 depending on the flags. 36 37* 0x1 Window Update - Used to updated the senders receive window size. 38 This is used to implement per-session flow control. 39 40* 0x2 Ping - Used to measure RTT. It can also be used to heart-beat 41 and do keep-alives over TCP. 42 43* 0x3 Go Away - Used to close a session. 44 45## Flag Field 46 47The flags field is used to provide additional information related 48to the message type. The following flags are supported: 49 50* 0x1 SYN - Signals the start of a new stream. May be sent with a data or 51 window update message. Also sent with a ping to indicate outbound. 52 53* 0x2 ACK - Acknowledges the start of a new stream. May be sent with a data 54 or window update message. Also sent with a ping to indicate response. 55 56* 0x4 FIN - Performs a half-close of a stream. May be sent with a data 57 message or window update. 58 59* 0x8 RST - Reset a stream immediately. May be sent with a data or 60 window update message. 61 62## StreamID Field 63 64The StreamID field is used to identify the logical stream the frame 65is addressing. The client side should use odd ID's, and the server even. 66This prevents any collisions. Additionally, the 0 ID is reserved to represent 67the session. 68 69Both Ping and Go Away messages should always use the 0 StreamID. 70 71## Length Field 72 73The meaning of the length field depends on the message type: 74 75* Data - provides the length of bytes following the header 76* Window update - provides a delta update to the window size 77* Ping - Contains an opaque value, echoed back 78* Go Away - Contains an error code 79 80# Message Flow 81 82There is no explicit connection setup, as Yamux relies on an underlying 83transport to be provided. However, there is a distinction between client 84and server side of the connection. 85 86## Opening a stream 87 88To open a stream, an initial data or window update frame is sent 89with a new StreamID. The SYN flag should be set to signal a new stream. 90 91The receiver must then reply with either a data or window update frame 92with the StreamID along with the ACK flag to accept the stream or with 93the RST flag to reject the stream. 94 95Because we are relying on the reliable stream underneath, a connection 96can begin sending data once the SYN flag is sent. The corresponding 97ACK does not need to be received. This is particularly well suited 98for an RPC system where a client wants to open a stream and immediately 99fire a request without waiting for the RTT of the ACK. 100 101This does introduce the possibility of a connection being rejected 102after data has been sent already. This is a slight semantic difference 103from TCP, where the conection cannot be refused after it is opened. 104Clients should be prepared to handle this by checking for an error 105that indicates a RST was received. 106 107## Closing a stream 108 109To close a stream, either side sends a data or window update frame 110along with the FIN flag. This does a half-close indicating the sender 111will send no further data. 112 113Once both sides have closed the connection, the stream is closed. 114 115Alternatively, if an error occurs, the RST flag can be used to 116hard close a stream immediately. 117 118## Flow Control 119 120When Yamux is initially starts each stream with a 256KB window size. 121There is no window size for the session. 122 123To prevent the streams from stalling, window update frames should be 124sent regularly. Yamux can be configured to provide a larger limit for 125windows sizes. Both sides assume the initial 256KB window, but can 126immediately send a window update as part of the SYN/ACK indicating a 127larger window. 128 129Both sides should track the number of bytes sent in Data frames 130only, as only they are tracked as part of the window size. 131 132## Session termination 133 134When a session is being terminated, the Go Away message should 135be sent. The Length should be set to one of the following to 136provide an error code: 137 138* 0x0 Normal termination 139* 0x1 Protocol error 140* 0x2 Internal error 141