Internet DRAFT - draft-frindell-webtrans-devious-baton
draft-frindell-webtrans-devious-baton
WebTransport A. Frindell
Internet-Draft Meta
Intended status: Informational 10 July 2023
Expires: 11 January 2024
Devious Baton Protocol for Exercising WebTransport
draft-frindell-webtrans-devious-baton-00
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."
Frindell Expires 11 January 2024 [Page 1]
Internet-Draft devious-baton July 2023
This Internet-Draft will expire on 11 January 2024.
Copyright Notice
Copyright (c) 2023 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3
3. Session Establishment . . . . . . . . . . . . . . . . . . . . 3
3.1. Query Parameters . . . . . . . . . . . . . . . . . . . . 3
3.2. Protocol Version . . . . . . . . . . . . . . . . . . . . 4
4. Protocol Behavior . . . . . . . . . . . . . . . . . . . . . . 4
4.1. Setup . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4.2. Processing a Baton Message . . . . . . . . . . . . . . . 4
4.3. Baton message . . . . . . . . . . . . . . . . . . . . . . 5
4.4. Datagrams . . . . . . . . . . . . . . . . . . . . . . . . 6
4.5. Session Closure . . . . . . . . . . . . . . . . . . . . . 6
4.6. Error Handling . . . . . . . . . . . . . . . . . . . . . 6
4.6.1. Stream Error Codes . . . . . . . . . . . . . . . . . 6
4.6.2. Session Error Codes . . . . . . . . . . . . . . . . . 7
5. Security Considerations . . . . . . . . . . . . . . . . . . . 7
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
7. Normative References . . . . . . . . . . . . . . . . . . . . 7
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 8
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8
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.
Frindell Expires 11 January 2024 [Page 2]
Internet-Draft devious-baton July 2023
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.
Frindell Expires 11 January 2024 [Page 3]
Internet-Draft devious-baton July 2023
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.
Frindell Expires 11 January 2024 [Page 4]
Internet-Draft devious-baton July 2023
* 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.
Frindell Expires 11 January 2024 [Page 5]
Internet-Draft devious-baton July 2023
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.
Frindell Expires 11 January 2024 [Page 6]
Internet-Draft devious-baton July 2023
+==========+======+================================+
| Name | Code | Description |
+==========+======+================================+
| IDC | 0x01 | I don't care about this stream |
+----------+------+--------------------------------+
| WHATEVER | 0x02 | The peer asked for this |
+----------+------+--------------------------------+
| I_LIED | 0x03 | Spontaneous reset |
+----------+------+--------------------------------+
Table 1: Stream Error Codes
4.6.2. Session Error Codes
The following error codes can be sent in the
CLOSE_WEBTRANSPORT_SESSION capsule.
+=========+======+=================================+
| 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 |
+---------+------+---------------------------------+
Table 2: Session Error Codes
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
Frindell Expires 11 January 2024 [Page 7]
Internet-Draft devious-baton July 2023
[OVERVIEW] Vasiliev, V., "The WebTransport Protocol Framework", Work
in Progress, Internet-Draft, draft-ietf-webtrans-overview-
05, 24 January 2023,
<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, March 1997,
<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,
May 2017, <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
Email: afrind@meta.com
Frindell Expires 11 January 2024 [Page 8]
