├── .circleci └── config.yml ├── .github ├── CODEOWNERS └── workflows │ ├── archive.yml │ ├── ghpages.yml │ ├── publish.yml │ └── update.yml ├── .gitignore ├── .travis.yml ├── CONTRIBUTING.md ├── LICENSE.md ├── Makefile ├── README.md └── draft-ietf-webtrans-overview.md /.circleci/config.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | jobs: 3 | build: 4 | docker: 5 | - image: martinthomson/i-d-template:latest 6 | working_directory: ~/draft 7 | 8 | steps: 9 | - checkout 10 | 11 | # Build txt and html versions of drafts 12 | - run: 13 | name: "Build Drafts" 14 | command: "make 'CLONE_ARGS=--reference ~/git-reference'" 15 | 16 | # Update editor's copy on gh-pages 17 | - run: 18 | name: "Update GitHub Pages" 19 | command: | 20 | if [ "${CIRCLE_TAG#draft-}" == "${CIRCLE_TAG}" ]; then 21 | make gh-pages 22 | fi 23 | 24 | # For tagged builds, upload to the datatracker. 25 | - deploy: 26 | name: "Upload to Datatracker" 27 | command: | 28 | if [ "${CIRCLE_TAG#draft-}" != "${CIRCLE_TAG}" ]; then 29 | make upload 30 | fi 31 | 32 | # Save GitHub issues 33 | - run: 34 | name: "Save GitHub Issues" 35 | command: "make issues || make issues DISABLE_ISSUE_FETCH=true && make gh-issues" 36 | 37 | # Create and store artifacts 38 | - run: 39 | name: "Create Artifacts" 40 | command: "make artifacts CI_ARTIFACTS=/tmp/artifacts" 41 | 42 | - store_artifacts: 43 | path: /tmp/artifacts 44 | 45 | 46 | workflows: 47 | version: 2 48 | build: 49 | jobs: 50 | - build: 51 | filters: 52 | tags: 53 | only: /.*?/ 54 | -------------------------------------------------------------------------------- /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | # Automatically generated CODEOWNERS 2 | # Regenerate with `make update-codeowners` 3 | draft-ietf-webtrans-overview.md vasilvv@google.com 4 | -------------------------------------------------------------------------------- /.github/workflows/archive.yml: -------------------------------------------------------------------------------- 1 | name: "Archive Issues and Pull Requests" 2 | 3 | on: 4 | schedule: 5 | - cron: '0 0 * * 0,2,4' 6 | repository_dispatch: 7 | types: [archive] 8 | workflow_dispatch: 9 | inputs: 10 | archive_full: 11 | description: 'Recreate the archive from scratch' 12 | default: false 13 | type: boolean 14 | 15 | jobs: 16 | build: 17 | name: "Archive Issues and Pull Requests" 18 | runs-on: ubuntu-latest 19 | steps: 20 | - name: "Checkout" 21 | uses: actions/checkout@v4 22 | 23 | # Note: No caching for this build! 24 | 25 | - name: "Update Archive" 26 | uses: martinthomson/i-d-template@v1 27 | env: 28 | ARCHIVE_FULL: ${{ inputs.archive_full }} 29 | with: 30 | make: archive 31 | token: ${{ github.token }} 32 | 33 | - name: "Update GitHub Pages" 34 | uses: martinthomson/i-d-template@v1 35 | with: 36 | make: gh-archive 37 | token: ${{ github.token }} 38 | 39 | - name: "Save Archive" 40 | uses: actions/upload-artifact@v4 41 | with: 42 | path: archive.json 43 | -------------------------------------------------------------------------------- /.github/workflows/ghpages.yml: -------------------------------------------------------------------------------- 1 | name: "Update Editor's Copy" 2 | 3 | on: 4 | push: 5 | paths-ignore: 6 | - README.md 7 | - CONTRIBUTING.md 8 | - LICENSE.md 9 | - .gitignore 10 | pull_request: 11 | paths-ignore: 12 | - README.md 13 | - CONTRIBUTING.md 14 | - LICENSE.md 15 | - .gitignore 16 | 17 | jobs: 18 | build: 19 | name: "Update Editor's Copy" 20 | runs-on: ubuntu-latest 21 | steps: 22 | - name: "Checkout" 23 | uses: actions/checkout@v4 24 | 25 | - name: "Setup" 26 | id: setup 27 | run: date -u "+date=%FT%T" >>"$GITHUB_OUTPUT" 28 | 29 | - name: "Caching" 30 | uses: actions/cache@v4 31 | with: 32 | path: | 33 | .refcache 34 | .venv 35 | .gems 36 | node_modules 37 | .targets.mk 38 | key: i-d-${{ steps.setup.outputs.date }} 39 | restore-keys: i-d- 40 | 41 | - name: "Build Drafts" 42 | uses: martinthomson/i-d-template@v1 43 | with: 44 | token: ${{ github.token }} 45 | 46 | - name: "Update GitHub Pages" 47 | uses: martinthomson/i-d-template@v1 48 | if: ${{ github.event_name == 'push' }} 49 | with: 50 | make: gh-pages 51 | token: ${{ github.token }} 52 | 53 | - name: "Archive Built Drafts" 54 | uses: actions/upload-artifact@v4 55 | with: 56 | path: | 57 | draft-*.html 58 | draft-*.txt 59 | -------------------------------------------------------------------------------- /.github/workflows/publish.yml: -------------------------------------------------------------------------------- 1 | name: "Publish New Draft Version" 2 | 3 | on: 4 | push: 5 | tags: 6 | - "draft-*" 7 | workflow_dispatch: 8 | inputs: 9 | email: 10 | description: "Submitter email" 11 | default: "" 12 | type: string 13 | 14 | jobs: 15 | build: 16 | name: "Publish New Draft Version" 17 | runs-on: ubuntu-latest 18 | steps: 19 | - name: "Checkout" 20 | uses: actions/checkout@v4 21 | 22 | # See https://github.com/actions/checkout/issues/290 23 | - name: "Get Tag Annotations" 24 | run: git fetch -f origin ${{ github.ref }}:${{ github.ref }} 25 | 26 | - name: "Setup" 27 | id: setup 28 | run: date -u "+date=%FT%T" >>"$GITHUB_OUTPUT" 29 | 30 | - name: "Caching" 31 | uses: actions/cache@v4 32 | with: 33 | path: | 34 | .refcache 35 | .venv 36 | .gems 37 | node_modules 38 | .targets.mk 39 | key: i-d-${{ steps.setup.outputs.date }} 40 | restore-keys: i-d- 41 | 42 | - name: "Build Drafts" 43 | uses: martinthomson/i-d-template@v1 44 | with: 45 | token: ${{ github.token }} 46 | 47 | - name: "Upload to Datatracker" 48 | uses: martinthomson/i-d-template@v1 49 | with: 50 | make: upload 51 | env: 52 | UPLOAD_EMAIL: ${{ inputs.email }} 53 | 54 | - name: "Archive Submitted Drafts" 55 | uses: actions/upload-artifact@v4 56 | with: 57 | path: "versioned/draft-*-[0-9][0-9].*" 58 | -------------------------------------------------------------------------------- /.github/workflows/update.yml: -------------------------------------------------------------------------------- 1 | name: "Update Generated Files" 2 | # This rule is not run automatically. 3 | # It can be run manually to update all of the files that are part 4 | # of the template, specifically: 5 | # - README.md 6 | # - CONTRIBUTING.md 7 | # - .note.xml 8 | # - .github/CODEOWNERS 9 | # - Makefile 10 | # 11 | # 12 | # This might be useful if you have: 13 | # - added, removed, or renamed drafts (including after adoption) 14 | # - added, removed, or changed draft editors 15 | # - changed the title of drafts 16 | # 17 | # Note that this removes any customizations you have made to 18 | # the affected files. 19 | on: workflow_dispatch 20 | 21 | jobs: 22 | build: 23 | name: "Update Files" 24 | runs-on: ubuntu-latest 25 | steps: 26 | - name: "Checkout" 27 | uses: actions/checkout@v4 28 | 29 | - name: "Update Generated Files" 30 | uses: martinthomson/i-d-template@v1 31 | with: 32 | make: update-files 33 | token: ${{ github.token }} 34 | 35 | - name: "Push Update" 36 | run: git push 37 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.html 2 | *.pdf 3 | *.redxml 4 | *.swp 5 | *.txt 6 | *.upload 7 | *~ 8 | .tags 9 | /*-[0-9][0-9].xml 10 | /.gems/ 11 | /.refcache 12 | /.targets.mk 13 | /.venv/ 14 | /.vscode/ 15 | /lib 16 | /node_modules/ 17 | /versioned/ 18 | Gemfile.lock 19 | archive.json 20 | draft-ietf-webtrans-overview.xml 21 | package-lock.json 22 | report.xml 23 | !requirements.txt 24 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: python 2 | sudo: false 3 | dist: xenial 4 | 5 | addons: 6 | apt: 7 | packages: 8 | - python-pip 9 | - xsltproc 10 | 11 | env: 12 | global: 13 | - GOPATH="${TRAVIS_BUILD_DIR}/.go_workspace" 14 | - mmark_src=github.com/miekg/mmark/mmark 15 | - mmark=./mmark 16 | 17 | install: 18 | - pip install xml2rfc 19 | - if head -1 -q *.md | grep '^\-\-\-' >/dev/null 2>&1; then gem install --no-doc kramdown-rfc2629; fi 20 | - if head -1 -q *.md | grep '^%%%' >/dev/null 2>&1; then go get "$mmark_src" && go build "$mmark_src"; fi 21 | 22 | script: 23 | - make 24 | - make issues || make issues DISABLE_ISSUE_FETCH=true && make gh-issues 25 | - make gh-pages 26 | 27 | deploy: 28 | provider: script 29 | script: make upload 30 | skip_cleanup: true 31 | on: 32 | tags: true 33 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | This repository relates to activities in the Internet Engineering Task Force 4 | ([IETF](https://www.ietf.org/)). All material in this repository is considered 5 | Contributions to the IETF Standards Process, as defined in the intellectual 6 | property policies of IETF currently designated as 7 | [BCP 78](https://www.rfc-editor.org/info/bcp78), 8 | [BCP 79](https://www.rfc-editor.org/info/bcp79) and the 9 | [IETF Trust Legal Provisions (TLP) Relating to IETF Documents](http://trustee.ietf.org/trust-legal-provisions.html). 10 | 11 | Any edit, commit, pull request, issue, comment or other change made to this 12 | repository constitutes Contributions to the IETF Standards Process 13 | (https://www.ietf.org/). 14 | 15 | You agree to comply with all applicable IETF policies and procedures, including, 16 | BCP 78, 79, the TLP, and the TLP rules regarding code components (e.g. being 17 | subject to a Simplified BSD License) in Contributions. 18 | 19 | 20 | ## Working Group Information 21 | 22 | Discussion of this work occurs on the [WebTransport 23 | Working Group mailing list](mailto:webtransport@ietf.org) 24 | ([archive](https://mailarchive.ietf.org/arch/browse/webtransport/), 25 | [subscribe](https://www.ietf.org/mailman/listinfo/webtransport)). 26 | In addition to contributions in GitHub, you are encouraged to participate in 27 | discussions there. 28 | 29 | **Note**: Some working groups adopt a policy whereby substantive discussion of 30 | technical issues needs to occur on the mailing list. 31 | 32 | You might also like to familiarize yourself with other 33 | [Working Group documents](https://datatracker.ietf.org/wg/webtrans/documents/). 34 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | # License 2 | 3 | See the 4 | [guidelines for contributions](https://github.com/ietf-wg-webtrans/draft-ietf-webtrans-overview/blob/main/CONTRIBUTING.md). 5 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | LIBDIR := lib 2 | include $(LIBDIR)/main.mk 3 | 4 | $(LIBDIR)/main.mk: 5 | ifneq (,$(shell grep "path *= *$(LIBDIR)" .gitmodules 2>/dev/null)) 6 | git submodule sync 7 | git submodule update $(CLONE_ARGS) --init 8 | else 9 | git clone -q --depth 10 $(CLONE_ARGS) \ 10 | -b main https://github.com/martinthomson/i-d-template $(LIBDIR) 11 | endif 12 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # The WebTransport Protocol Framework 2 | 3 | This is the working area for the IETF [WEBTRANS Working Group](https://datatracker.ietf.org/wg/webtrans/documents/) Internet-Draft, "The WebTransport Protocol Framework". 4 | 5 | * [Editor's Copy](https://ietf-wg-webtrans.github.io/draft-ietf-webtrans-overview/#go.draft-ietf-webtrans-overview.html) 6 | * [Datatracker Page](https://datatracker.ietf.org/doc/draft-ietf-webtrans-overview) 7 | * [Working Group Draft](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-overview) 8 | * [Compare Editor's Copy to Working Group Draft](https://ietf-wg-webtrans.github.io/draft-ietf-webtrans-overview/#go.draft-ietf-webtrans-overview.diff) 9 | 10 | 11 | ## Contributing 12 | 13 | See the 14 | [guidelines for contributions](https://github.com/ietf-wg-webtrans/draft-ietf-webtrans-overview/blob/main/CONTRIBUTING.md). 15 | 16 | Contributions can be made by creating pull requests. 17 | The GitHub interface supports creating pull requests using the Edit (✏) button. 18 | 19 | 20 | ## Command Line Usage 21 | 22 | Formatted text and HTML versions of the draft can be built using `make`. 23 | 24 | ```sh 25 | $ make 26 | ``` 27 | 28 | Command line usage requires that you have the necessary software installed. See 29 | [the instructions](https://github.com/martinthomson/i-d-template/blob/main/doc/SETUP.md). 30 | 31 | -------------------------------------------------------------------------------- /draft-ietf-webtrans-overview.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: The WebTransport Protocol Framework 3 | abbrev: WebTransport 4 | docname: draft-ietf-webtrans-overview-latest 5 | date: {DATE} 6 | category: std 7 | workgroup: WEBTRANS 8 | 9 | ipr: trust200902 10 | area: Applications and Real-Time 11 | 12 | stand_alone: yes 13 | pi: [toc, sortrefs, symrefs] 14 | 15 | author: 16 | - 17 | ins: V. Vasiliev 18 | name: Victor Vasiliev 19 | organization: Google 20 | email: vasilvv@google.com 21 | 22 | informative: 23 | CSP: 24 | target: https://www.w3.org/TR/CSP/ 25 | title: "Content Security Policy Level 3" 26 | author: 27 | org: W3C 28 | date: Working Draft 29 | 30 | --- abstract 31 | 32 | The WebTransport Protocol Framework enables clients constrained by the Web 33 | security model to communicate with a remote server using a secure multiplexed 34 | transport. It consists of a set of individual protocols that are safe to expose 35 | to untrusted applications, combined with an abstract model that allows them 36 | to be used interchangeably. 37 | 38 | This document defines the overall requirements on the protocols used in 39 | WebTransport, as well as the common features of the protocols, support for some 40 | of which may be optional. 41 | 42 | --- note_Note_to_Readers 43 | 44 | Discussion of this draft takes place on the WebTransport mailing list 45 | (webtransport@ietf.org), which is archived at 46 | \. 47 | 48 | The repository tracking the issues for this draft can be found at 49 | \. 50 | The web API draft corresponding to this document can be found at 51 | \. 52 | 53 | --- middle 54 | 55 | # Introduction 56 | 57 | The WebTransport Protocol Framework enables clients constrained by the Web 58 | security model to communicate with a remote server using a secure multiplexed 59 | transport. It consists of a set of individual protocols that are safe to expose 60 | to untrusted applications, combined with an abstract model that allows them 61 | to be used interchangeably. 62 | 63 | This document defines the overall requirements on the protocols used in 64 | WebTransport, as well as the common features of the protocols, support for some 65 | of which may be optional. 66 | 67 | ## Background 68 | 69 | Historically, web applications that needed a bidirectional data stream between a 70 | client and a server could rely on WebSockets {{?RFC6455}}, a message-based 71 | protocol compatible with the Web security model. However, since the 72 | abstraction it provides is a single ordered reliable stream of messages, it 73 | suffers from head-of-line blocking, meaning that all messages must be sent and 74 | received in order even if they could be processed independently of each other, 75 | and some messages may no longer be relevant. This makes it a poor fit for 76 | latency-sensitive applications which rely on partial reliability and stream 77 | independence for performance. 78 | 79 | One existing option available to Web developers are WebRTC data channels 80 | {{?RFC8831}}, which provide a WebSocket-like API for a peer-to-peer SCTP 81 | channel protected by DTLS. In theory, it is possible to use it for the use 82 | cases addressed by this specification. However, in practice, it has not seen 83 | wide adoption outside of browser-to-browser settings due to its dependency on 84 | ICE (which fits poorly with the Web model) and userspace SCTP (which has a 85 | limited number of implementations available due to not being used in other 86 | contexts). 87 | 88 | An alternative design would be to open multiple WebSocket connections over 89 | HTTP/3 {{?RFC9220}}. That would avoid head-of-line blocking and provide an 90 | ability to cancel a stream by closing the corresponding WebSocket session. 91 | However, this approach has a number of drawbacks, which all stem primarily from 92 | the fact that semantically each WebSocket is a completely independent entity: 93 | 94 | * Each new stream would require a WebSocket handshake to agree on application 95 | protocol used, meaning that it would take at least one RTT to establish each 96 | new stream before the client can write to it. 97 | * Only clients can initiate streams. Server-initiated streams and other 98 | alternative modes of communication (such as the QUIC DATAGRAM frame 99 | {{?RFC9221}}) are not available. 100 | * While the streams would normally be pooled by the user agent, this is not 101 | guaranteed, and the general process of mapping a WebSocket to a server is 102 | opaque to the client. This introduces unpredictable performance properties 103 | into the system, and prevents optimizations which rely on the streams being on 104 | the same connection (for instance, it might be possible for the client to 105 | request different retransmission priorities for different streams, but that 106 | would be much more complex unless they are all on the same connection). 107 | 108 | WebTransport avoids all of those issues by letting applications create a single 109 | transport object that can contain multiple streams multiplexed together in a 110 | single context (similar to SCTP, HTTP/2, QUIC and others), and can also be used 111 | to send unreliable datagrams (similar to UDP). 112 | 113 | ## Conventions and Definitions 114 | 115 | The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 116 | "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this 117 | document are to be interpreted as described in BCP 14 {{!RFC2119}} {{!RFC8174}} 118 | when, and only when, they appear in all capitals, as shown here. 119 | 120 | WebTransport is a framework that aims to abstract away the underlying transport 121 | protocol while still exposing a few key transport-layer aspects to application 122 | developers. It is structured around the following concepts: 123 | 124 | WebTransport session: 125 | 126 | : A WebTransport session is a single communication context established between a 127 | client and a server. It may correspond to a specific transport-layer 128 | connection, or it may be a logical entity within an existing multiplexed 129 | transport-layer connection. WebTransport sessions are logically independent 130 | from one another even if some sessions can share an underlying 131 | transport-layer connection. 132 | 133 | WebTransport protocol: 134 | 135 | : A WebTransport protocol is a specific protocol that can be used to establish 136 | a WebTransport session. 137 | 138 | Datagram: 139 | 140 | : A datagram is a unit of transmission that is limited in size (typically to 141 | the path MTU), does not have an expectation of being delivered reliably, and 142 | is treated atomically by the transport. 143 | 144 | Stream: 145 | 146 | : A stream is a sequence of bytes that is reliably delivered to the receiving 147 | application in the same order as it was transmitted by the sender. Streams 148 | can be of arbitrary length, and therefore cannot always be buffered entirely 149 | in memory. WebTransport protocols and APIs are expected to provide partial 150 | stream data to the application before the stream has been entirely received. 151 | 152 | Message: 153 | 154 | : A message is a stream that is sufficiently small that it can be fully buffered 155 | before being passed to the application. WebTransport does not define messages 156 | as a primitive, since from the transport perspective they can be simulated 157 | by fully buffering a stream before passing it to the application. However, 158 | this distinction is important to highlight since some of the similar protocols 159 | and APIs (notably WebSocket {{?RFC6455}}) use messages as a core abstraction. 160 | 161 | Server: 162 | 163 | : A WebTransport server is an application that accepts incoming WebTransport 164 | sessions. In cases when WebTransport is served over a multiplexed protocol 165 | (such as HTTP/2 or HTTP/3), "WebTransport server" refers to a handler for a 166 | specific multiplexed endpoint (e.g. an application handling specific HTTP 167 | resource), rather than the application listening on a given TCP or UDP 168 | socket. 169 | 170 | Client: 171 | 172 | : A WebTransport client is an application that initiates the transport 173 | session and may be running in a constrained security context, for instance, 174 | a JavaScript application running inside a browser. 175 | 176 | User agent: 177 | 178 | : A WebTransport user agent is a software system that has an unrestricted 179 | access to the host network stack and can create transports on behalf 180 | of the client. 181 | 182 | # Common Transport Requirements {#common-requirements} 183 | 184 | Since clients are not necessarily trusted and have to be constrained by the 185 | Web security model, WebTransport imposes certain requirements on any specific 186 | protocol used. 187 | 188 | All WebTransport protocols MUST use TLS {{!RFC8446}} or a semantically 189 | equivalent security protocol (for instance, DTLS {{?RFC9147}}). 190 | The protocols SHOULD use TLS version 1.3 or later, unless they aim for 191 | backwards compatibility with legacy systems. 192 | 193 | All WebTransport protocols MUST require the user agent to obtain and maintain 194 | explicit consent from the server to send data. For connection-oriented 195 | protocols (such as TCP or QUIC), the connection establishment and keep-alive 196 | mechanisms suffice. STUN Consent Freshness {{?RFC7675}} is another example of 197 | a mechanism satisfying this requirement. 198 | 199 | All WebTransport protocols MUST limit the rate at which the client sends data. 200 | This SHOULD be accomplished via a feedback-based congestion control mechanism 201 | (such as {{?RFC5681}} or {{?RFC9002}}). 202 | 203 | All WebTransport protocols MUST support simultaneously establishing multiple 204 | sessions between the same client and server. 205 | 206 | All WebTransport protocols MUST prevent clients from establishing transport 207 | sessions to network endpoints that are not WebTransport servers. 208 | 209 | All WebTransport protocols MUST provide a way for the user agent to indicate 210 | the origin {{!RFC6454}} of the client to the server. 211 | 212 | All WebTransport protocols MUST provide a way for a server endpoint location to 213 | be described using a URI {{!RFC3986}}. This enables integration with various 214 | Web platform features that represent resources as URIs, such as Content 215 | Security Policy [CSP]. 216 | 217 | All WebTransport protocols MUST provide a way for the session initiator to 218 | negotiate a subprotocol with the peer when establishing a WebTransport session. 219 | The session initiator provides an optional list of subprotocols to the peer. 220 | The peer selects one and responds indicating the selected subprotocol or 221 | rejects the session establishment request if none of the subprotocols are 222 | supported. Note that the semantics of individual subprotocol token values is 223 | determined by the WebTransport resource in question and are not registered in 224 | IANA's "ALPN Protocol IDs" registry. 225 | 226 | # Session Establishment 227 | 228 | WebTransport session establishment is an asynchronous process. A session is 229 | considered _ready_ from the client's perspective when the server has confirmed 230 | that it is willing to accept the session with the provided origin and URI. 231 | WebTransport protocols MAY allow clients to send data before the session is 232 | ready; however, they MUST NOT use mechanisms that are unsafe against replay 233 | attacks without an explicit indication from the client. 234 | 235 | ## Application Protocol Negotiation 236 | 237 | WebTransport sessions offer a protocol negotiation mechanism, similar to 238 | TLS Application-Layer Protocol Negotiation Extension (ALPN) {{?RFC7301}}. 239 | 240 | When establishing a session, a WebTransport client can offer the server a list 241 | of protocols that it would like to use on that session, in preference order. 242 | When the server receives such a list, it selects a single choice from that list 243 | and communicates that choice to the client. A server that does not wish to use 244 | any of the protocols offered by the client can reject the WebTransport session 245 | establishment attempt. 246 | 247 | # Transport Features 248 | 249 | All transport protocols MUST provide datagrams, unidirectional and 250 | bidirectional streams in order to make the transport protocols interchangeable. 251 | 252 | ## Session-Wide Features {#features-session} 253 | 254 | Any WebTransport protocol SHALL provide the following operations on the 255 | session: 256 | 257 | establish a session 258 | : Create a new WebTransport session given a URI {{!RFC3986}} of the requester. 259 | An origin {{!RFC6454}} MUST be given if the WebTransport session is coming 260 | from a browser client; otherwise, it is OPTIONAL. 261 | 262 | terminate a session 263 | : Terminate the session while communicating to the peer an unsigned 32-bit 264 | error code and an error reason string of at most 1024 bytes. As soon as the 265 | session is terminated, no further application data will be exchanged on it. 266 | The error code and string are optional; the default values are 0 and "". The 267 | delivery of the error code and string MAY be best-effort. 268 | 269 | Any WebTransport protocol SHALL provide the following events: 270 | 271 | session terminated event 272 | : Indicates that the WebTransport session has been terminated, either by the 273 | peer or by the local networking stack, and no user data can be exchanged on 274 | it any further. If the session has been terminated as a result of the peer 275 | performing the "terminate a session" operation above, a corresponding error 276 | code and an error string can be provided. 277 | 278 | ## Datagrams {#features-datagrams} 279 | 280 | A datagram is a sequence of bytes that is limited in size (generally to the path 281 | MTU) and is not expected to be transmitted reliably. The general goal for 282 | WebTransport datagrams is to be similar in behavior to UDP while being subject 283 | to common requirements expressed in {{common-requirements}}. 284 | 285 | A WebTransport sender is not expected to retransmit datagrams, though it may 286 | end up doing so if it is using TCP or some other underlying protocol that only 287 | provides reliable delivery. WebTransport datagrams are not expected to be flow 288 | controlled, meaning that the receiver might drop datagrams if the application 289 | is not consuming them fast enough. 290 | 291 | The application MUST be provided with the maximum datagram size that it can 292 | send. The size SHOULD be derived from the result of performing path MTU 293 | discovery. 294 | 295 | In the WebTransport model, all of the outgoing and incoming datagrams are 296 | placed into a size-bound queue (similar to a network interface card queue). 297 | 298 | Any WebTransport protocol SHALL provide the following operations on the 299 | session: 300 | 301 | send a datagram 302 | : Enqueues a datagram to be sent to the peer. This can potentially result in 303 | the datagram being dropped if the queue is full. 304 | 305 | receive a datagram 306 | : Dequeues an incoming datagram, if one is available. 307 | 308 | get maxiumum datagram size 309 | : Returns the largest size of the datagram that a WebTransport session is 310 | expected to be able to send. 311 | 312 | ## Streams {#features-streams} 313 | 314 | A unidirectional stream is a one-way reliable in-order stream of bytes where the 315 | initiator is the only endpoint that can send data. A bidirectional stream 316 | allows both endpoints to send data and can be conceptually represented as a pair 317 | of unidirectional streams. 318 | 319 | The streams are in general expected to follow the semantics and the state 320 | machine of QUIC streams ({{?RFC9000}}, Sections 2 and 3). 321 | TODO: describe the stream state machine explicitly. 322 | 323 | A WebTransport stream can be reset, indicating that the endpoint is not 324 | interested in either sending or receiving any data related to the stream. In 325 | that case, the sender is expected to not retransmit any data that was already 326 | sent on that stream. 327 | 328 | Streams SHOULD be sufficiently lightweight that they can be used as messages. 329 | 330 | Data sent on a stream is flow controlled by the transport protocol. In addition 331 | to flow controlling stream data, the creation of new streams is flow controlled 332 | as well: an endpoint may only open a limited number of streams until the peer 333 | explicitly allows creating more streams. From the perspective of the client, 334 | this is presented as a size-bounded queue of incoming streams. 335 | 336 | Any WebTransport protocol SHALL provide the following operations on the 337 | session: 338 | 339 | create a unidirectional stream 340 | : Creates an outgoing unidirectional stream; this operation may block until the 341 | flow control of the underlying protocol allows for it to be completed. 342 | 343 | create a bidirectional stream 344 | : Creates an outgoing bidirectional stream; this operation may block until the 345 | flow control of the underlying protocol allows for it to be completed. 346 | 347 | receive a unidirectional stream 348 | : Removes a stream from the queue of incoming unidirectional streams, if one is 349 | available. 350 | 351 | receive a bidirectional stream 352 | : Removes a stream from the queue of incoming bidirectional streams, if one is 353 | available. 354 | 355 | Any WebTransport protocol SHALL provide the following operations on an 356 | individual stream: 357 | 358 | send bytes 359 | : Add bytes into the stream send buffer. The sender can also indicate a FIN, 360 | signalling the fact that no new data will be send on the stream. Not 361 | applicable for incoming unidirectional streams. 362 | 363 | receive bytes 364 | : Removes bytes from the stream receive buffer. FIN can be received together 365 | with the stream data. Not applicable for outgoing unidirectional streams. 366 | 367 | abort send side 368 | : Sends a signal to the peer that the write side of the stream has been aborted. 369 | Discards the send buffer; if possible, no currently outstanding data is 370 | transmitted or retransmitted. An unsigned 32-bit error code can be supplied 371 | as a part of the signal to the peer; if omitted, the error code is presumed 372 | to be 0. 373 | 374 | abort receive side 375 | : Sends a signal to the peer that the read side of the stream has been aborted. 376 | Discards the receive buffer; the peer is typically expected to abort the 377 | corresponding send side in response. An unsigned 32-bit error code can be 378 | supplied as a part of the signal to the peer. 379 | 380 | Any WebTransport protocol SHALL provide the following events for an individual 381 | stream: 382 | 383 | send side aborted 384 | : Indicates that the peer has aborted the corresponding receive side of the 385 | stream. An unsigned 32-bit error code from the peer may be available. 386 | 387 | receive side aborted 388 | : Indicates that the peer has aborted the corresponding send side of the 389 | stream. An unsigned 32-bit error code from the peer may be available. 390 | 391 | all data committed 392 | : Indicates that all of the outgoing data on the stream, including the end 393 | stream indication, is in the state where aborting the send side would have no 394 | further effect on any data being delivered. 395 | 396 | : For protocols, like HTTP/2, stream data might be passed to another 397 | component (like a kernel) for transmission. Once data is passed to that 398 | component it might not be possible to abort the sending of stream data 399 | without also aborting the entire connection. 400 | For these protocols, data is considered committed once it passes to the 401 | other component. 402 | 403 | : A protocol, like HTTP/3, that uses a more integrated stack might be able to 404 | retract data further into the process. For these protocols, sending on a 405 | stream might be aborted at any time until all data has been received and 406 | acknowledged by the peer, corresponding to the "Data Recvd" state in QUIC; 407 | see {{Section 3.1 of !QUIC=RFC9000}}. 408 | 409 | # Transport Properties 410 | 411 | WebTransport defines common semantics for multiple protocols to allow them to 412 | be used interchangeably. Nevertheless, those protocols still have 413 | substantially different performance properties that an application may want to 414 | query. 415 | 416 | The most notable property is support for unreliable data delivery. The 417 | protocol is defined to support unreliable delivery if: 418 | 419 | * Resetting a stream results in the lost stream data no longer being 420 | retransmitted, and 421 | * The datagrams are never retransmitted. 422 | 423 | Another important property is pooling support. Pooling means that multiple 424 | transport sessions may end up sharing the same transport layer connection, and 425 | thus share a congestion controller and other contexts. 426 | 427 | # Security Considerations 428 | 429 | Providing untrusted clients with a reasonably low-level access to the network 430 | comes with risks. This document mitigates those risks by imposing a set of 431 | common requirements described in {{common-requirements}}. 432 | 433 | WebTransport mandates the use of TLS for all protocols implementing it. This 434 | has a dual purpose. On one hand, it protects the transport from the network, 435 | including both potential attackers and ossification by middleboxes. On the 436 | other hand, it protects the network elements from potential confusion attacks 437 | such as the one discussed in Section 10.3 of {{?RFC6455}}. 438 | 439 | One potential concern is that even when a transport cannot be created, the 440 | connection error would reveal enough information to allow an attacker to scan 441 | the network addresses that would normally be inaccessible. Because of that, the 442 | user agent that runs untrusted clients MUST NOT provide any detailed error 443 | information until the server has confirmed that it is a WebTransport endpoint. 444 | For example, the client must not be able to distinguish between a network 445 | address that is unreachable and one that is reachable but is not a WebTransport 446 | server. 447 | 448 | WebTransport does not support any traditional means of HTTP-based 449 | authentication. It is not necessarily based on HTTP, and hence does not support 450 | HTTP cookies or HTTP authentication. Since it requires TLS, individual 451 | transport protocols MAY expose TLS-based authentication capabilities such as 452 | client certificates. 453 | 454 | # IANA Considerations 455 | 456 | There are no requests to IANA in this document. 457 | 458 | --- back 459 | --------------------------------------------------------------------------------