Mercurial > hg > index.cgi
view docs/extension-packet.txt @ 9:a11b330771e0
Fix buffer pointer handling when logging received bytes
Actually save the read buffer pointer so we can log the actual protocol
bytes read in all cases correctly instead of displaying out of bounds memory
in the case where the packet arrives in multiple pieces.
author | William Astle <lost@l-w.ca> |
---|---|
date | Sat, 30 Jul 2016 10:35:14 -0600 |
parents | 2e382e1a173e |
children | 7231f922b0f2 |
line wrap: on
line source
This document describes an extension to the LWWire protocol which provides raw packet data transfer. This extension leaves it up to the protocol server to decide how it obtains packets from and sends packets to the wider network. It is expected that this will likely be a virtual network interface of some kind but that is not strictly required. This extension only describes the mechanism for passing packets between the server and the client. Essentially, it is a link layer protocol. LWWire Server Operations ======================== The server side will maintain a transmit queue. This queue will have some defined maximum length after which any subsequent packets will be dropped until space opens in the queue. The length of the queue will be settable by the client up to some server defined maximum size. The maximum size supported by the server is left up to the server but it must necessarily be at least 1 and probably higher to support any significant data transfer. The server must drop any packets unless this extension is enabled. If the extension is disabled after being enabled, any packets in the queue must be immediately dropped. The queue must also be cleared upon a protocol reset. LWWire Protocol Extension ========================= This extension is called PACKET and is assigned extension number 01. It defines the following operations in its extension space. 00 PACKET_POLL This requests information about the next packet in the server's queue. Request: Octet Meaning ----- ------- 0-2 F3 01 00 Response: Octet Meaning ----- ------- 0-1 16 bit length If the returned length is zero, then there is no packet queued on the server. Subsequent PACKET_POLL calls will return the same result until the packet in the queue is either retrieved or dropped. 01 PACKET_RECEIVE This receives the first packet in the queue. Request: Octet Meaning ----- ------- 0-2 F3 01 01 Response: Octet Meaning ----- ------- 0-n packet data This request MUST NOT be issued without first calling PACKET_POLL to determine the length of the packet. If it is issued when no packet is waiting, the server MUST trigger an unknown operation error state. The client sends no indication that it has received the packet. As soon as the server has delivered the packet on the wire, it must remove it from the queue. If it detects an error condition during transmission, it MAY choose to retain the packet at the head of the queue. The client must issue another PACKET_POLL to learn the length of the next packet in the queue, if there is one. 02 PACKET_SEND This request allows the client to deliver a packet to the server. Request: Octet Meaning ----- ------- 0-2 F3 01 02 3-4 16 bit length 5- packet data There is no response from the server. The server is free to drop the packet if it cannot handle it, just as any other packet receiver may do. The client will receive no indication that this has happened. This is indistinguishable from any other cause of packets to be dropped. 03 PACKET_DROP This is a complement to PACKET_RECEIVE. It causes the server to discard the packet at the head of its transmit queue. Request: Octet Meaning ----- ------- 0-2 F3 01 03 There is no response from the server. If the server has no packets in its queue, nothing happens. A sequence of PACKET_POLL/PACKET_DROP until PACKET_POLL returns an empty queue indication can be used to clear the server queue. This operation allows the client to refuse delivery of a packet that it will not be able to handle in a timely manner or which it cannot handle at all due to size. 04 PACKET_SETRXMTU 05 PACKET_SETQUEUELEN 06 PACKET_SETTXMTU These requests allow for setting parameters for the server queue. Request: Octet Meaning ----- ------- 0-2 F3 01 <op> 3-+x <value> Response: Octet Meaning ----- ------- 0-x actual value set "x" is the size of the value. MTU is a 16 bit value. Queue length is an 8 bit value. See the Link Parameters section for more detail on the various parameters that can be set. Link Parameters =============== Queue length (QUEUELEN) ----------------------- This is the maximum length of queue of packets waiting to be delivered to the client. Setting this too high can lead to overwhelming the client with packets it cannot handle. A faster client may choose to increase this value while a slower client may choose to decrease it. The client may choose to adjust this value based on the work load it currently has, as well. The server must respect any request to set the queue length for any value less than it's maximum capable queue length. The minimum limit for the queue length is 2, but servers should support a higher queue length if possible. Receive MTU (RXMTU) ------------------- This is the maximum packet size the client is willing to accept. While the client need not set this, it is beneficial to do so. That way, the server side can drop packets that are too big rather than queuing them. In fact, in IP (and similar) settings, the sending side can then send a "packet too big" indicator which may cause remote transmitters to reduce their packet sizes. In particular, TCP benefits from this. By default, the server will send any packets it receives of any size. That is, the MTU will be assumed to be compatible with any packets it might receive the network. The client can discover what the server's notion of the maximum packet size is by querying the RXMTU. It is recommended that the default RXMTU on the server be no greater than 1500 (ethernet MTU) and no lower than 576, but these values should be chosen based on the protocols being transported by the server and client. Transmit MTU (TXMTU) -------------------- This is the maximum packet size the server is willing to relay. This will default to the same size as the RXMTU setting. However, changing the RXMTU will not change the TXMTU setting. The client should query this at startup to find out what packets it shouldn't bother sending so it can pass along "too big" notifications to its own transmitters. If the server receives from the client a packet larger than the TXMTU setting, it should just drop it. Normally, the client will not set this value. It can simply use its own notion of MTU to avoid sending packets larger than it wants to handle and the server can blithely go on with a larger notion. However, if the client does set the value lower, it can be useful for the server to discard rogue packet transmissions from the client. The restrictions on this value are the same as for the RXMTU value. The server must not reject any reasonable value smaller than its actual limit from the client should the client choose to set one. The server need not accept a value larger than its actual capability, of course.