Internet-Draft devious-baton July 2023
Frindell Expires 11 January 2024 [Page]
Workgroup:
WebTransport
Internet-Draft:
draft-frindell-webtrans-devious-baton-latest
Published:
Intended Status:
Informational
Expires:
Author:
A. Frindell
Meta

Devious Baton Protocol for Exercising WebTransport

Abstract

This document describes a simple protocol that can be used to exercise the functionality provided by WebTransport. The protocol passes a "baton" between endpoints, using both unidirectional and bidirectional streams.

About This Document

This note is to be removed before publishing as an RFC.

The latest revision of this draft can be found at https://afrind.github.io/draft-frindell-webtrans-devious-baton/draft-frindell-webtrans-devious-baton.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-frindell-webtrans-devious-baton/.

Discussion of this document takes place on the WebTransport Working Group mailing list (mailto:webtransport@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/webtransport/. Subscribe at https://www.ietf.org/mailman/listinfo/webtransport/.

Source for this draft and an issue tracker can be found at https://github.com/afrind/draft-frindell-webtrans-devious-baton.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on 11 January 2024.

Table of Contents

1. Introduction

WebTransport offers applications the ability to send and receive data over bidirectional and unidirectional streams, as well as send and received datagrams. The Devious Baton protocol is an application that can be used to test the full suite of functionality in a WebTransport implementation and demonstrate interoperability.

The protocol works by passing a "baton" -- a one byte integer -- between endpoints using streams. A receiving endpoint increments the baton value modulo 256 and sends it to the peer until the baton's value reaches 0.

2. Conventions and Definitions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Client:

The endpoint that initiates the WebTransport session

Server:

The endpoint that did not initiate the WebTransport session

Devious Baton Session:

A single WebTransport session initiated as described in Section 3

3. Session Establishment

The client initiates a WebTransport session as defined in [OVERVIEW]. The protocol can be used by any endpoint, but for interoperability it is RECOMMENDED that the URL path be /webtransport/devious-baton.

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. Protocol Behavior

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.

4.6.1. Stream Error Codes

The following error codes can be sent in RESET_STREAM and STOP_SENDING frames.

Table 1: Stream Error Codes
Name Code Description
IDC 0x01 I don't care about this stream
WHATEVER 0x02 The peer asked for this
I_LIED 0x03 Spontaneous reset

4.6.2. Session Error Codes

The following error codes can be sent in the CLOSE_WEBTRANSPORT_SESSION capsule.

Table 2: Session Error Codes
Name Code Description
DA_YAMN 0x01 There is insufficient stream credit to continue the protocol
BRUH 0x02 Received a malformed Baton message
SUS 0x03 Received an unexpected Baton message
BORED 0x04 Got tired of waiting for the next message

5. Security Considerations

There are not believed to be any further security considerations beyond those presented in QUIC Transport.

6. IANA Considerations

This document has no IANA actions.

7. Normative References

[OVERVIEW]
Vasiliev, V., "The WebTransport Protocol Framework", Work in Progress, Internet-Draft, draft-ietf-webtrans-overview-05, , <https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-overview-05>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.

Acknowledgments

Martin Thomson, Christian Huitema and Lucas Pardue contributed ideas to this protocol. David Schinazi suggested the name Devious Baton.

Error code naming inspiration by middle schoolers everywhere, but specifically James Frindell.

Author's Address

Alan Frindell
Meta