Devious Baton Protocol for Exercising WebTransport

3.1. Query Parameters

The behavior of the protocol can be configured by parameters indicated by the client. These parameters are transmitted in query parameters in the session establishment URL. Sending parameters is optional but omission of a parameter requires the server to interpret that as the default value.¶

The server MUST support the following optional query parameters:¶

• version - an integer specifying the draft version of Devious Baton the client intends to use¶

If the version is invalid or the server does not support the specified version, it MUST reject the WebTransport session with a 4xx status code. The default value is 0.¶

• baton - an integer between 1 and 255, inclusive, which the server will use as the initial baton value for all batons.¶

If the baton value is invalid, the server MUST reject the WebTransport session with a 4xx status code. There is no default - if unspecified the server chooses a random baton value between 1 and 255, inclusive.¶

• count - a positive integer specifying how many batons will be sent in parallel¶

The default value is 1. If the client asks for more batons than the server is capable of sending, the server MUST reject the WebTransport session with a 4xx status code.¶

3.2. Protocol Version

This draft defines Devious Baton protocol version 0.¶

4.1. Setup

Upon successful negotiation of a WebTransport session to the Devious Baton endpoint, the server opens a unidirectional stream for each baton. If there is insufficient stream credit to open a unidirectional stream, the server MUST close the WebTransport session with the DA_YAMN session error code. The server sends a Baton message with the initial baton value on each stream and closes it.¶

4.2. Processing a Baton Message

When either endpoint receives a Baton message on a stream, it takes the following actions:¶

• If the value of the baton is 0, the endpoint decrements the number of active batons by one.¶
• If the value of the baton is not 0, the endpoint MUST send a new Baton message with a baton value equal to the incoming baton value + 1 modulo 256. The new Baton message is sent on a stream, decribed below.¶
• After sending the Baton message, the endpoint MUST send a FIN on the stream.¶

The endpoint selects the outgoing Baton message stream based on how the incoming Baton message arrived.¶

• If the incoming Baton message arrived on a unidirectional stream, the endpoint opens a bidirectional stream and sends the outgoing Baton message on it.¶
• If the Baton message arrived on a peer-initiated bidirectional stream, the endpoint sends the outgoing Baton message on that stream.¶
• If the Baton message arrived on a self-initiated bidirectional stream, the endpoint opens a unidirectional stream and sends the outgoing Baton message on it.¶

If an endpoint receives a baton message with an unexpected value, it MAY close the WebTransport session with the SUS session error code.¶

If the endpoint has insufficient stream credit to open the correct type of stream, it MUST close the WebTransport session with the DA_YAMN session error code.¶

If the endpoint has insufficient flow control credit to send the Baton message, it SHOULD send as much as limits allow, and wait for additional credit. The endpoint SHOULD close the WebTransport session with the BORED session error code if the peer takes too long to grant credit.¶

4.3. Baton message

Baton Message {
  padding length(i)
  padding(...)
  baton(1)
}

To allow for exercising of long streams and flow control, the Baton message begins with an aribtrary amount of padding. padding length specifies the number of bytes of padding. The padding field contains padding length octets of padding. The receiver ignores the bytes themselves so they can be any value, for example 0 or random data.¶

baton contains the current value of the baton. It is a single byte to enforce the modulo 256 arithmetic.¶

4.4. Datagrams

When a client endpoint receives a Baton message with a baton value = 1 modulo 7, it sends a datagram with an identical Baton message. When a server endpoint receives a Baton message with a baton value = 0 modulo 7, it sends a datagram with an identical Baton message. Note that a Baton message in a datagram MUST use a padding value small enough such that the entire Baton message fits in a single datagram.¶

4.5. Session Closure

Each endpoint tracks the number of active batons. It is initally equal to the client's count parameter. Each time a baton exchange completes or is reset, the number of active batons is decreased by 1. When the number of active batons reaches 0, the endpoint MUST close the WebTransport session with no error.¶

To close a Devious Baton Session with an error, the endpoint initiating the close sends a CLOSE_WEBTRANSPORT_SESSION capsule with the specified session error code. To close the session without an error, the endpoint initiating the close sends a FIN on the CONNECT stream.¶

4.6. Error Handling

If an endpoint receives a gracefully closed stream or datagram with an incomplete Baton message, it MUST close the WebTransport session with the BRUH session error code.¶

Either endpoint can send a STOP_SENDING or RESET_STREAM on an open stream. STOP_SENDING MUST use the IDC stream error code. Upon receipt of a STOP_SENDING on a stream, or a RESET_STREAM on a bidirectional stream, the endpoint MUST send a RESET_STREAM for that stream with the WHATEVER stream error code unless it has already closed the stream. A RESET_STREAM sent spontaneously MUST use the I_LIED stream error code.¶

If an endpoint gets tired of waiting for the next Baton message, it MAY close the WebTransport session with the BORED error code.¶