idnits 2.17.1 draft-thomson-http-hx-uri-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 05, 2019) is 1869 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Experimental ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 813 -- Looks like a reference, but probably isn't: '2' on line 815 -- Looks like a reference, but probably isn't: '3' on line 817 -- Looks like a reference, but probably isn't: '4' on line 819 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-03 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-messaging-03 ** Obsolete normative reference: RFC 7540 (ref. 'HTTP2') (Obsoleted by RFC 9113) == Outdated reference: A later version (-34) exists of draft-ietf-quic-http-18 Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPbis M. Thomson 3 Internet-Draft Mozilla 4 Intended status: Experimental March 05, 2019 5 Expires: September 6, 2019 7 Identifying HTTP Exchanges with URIs 8 draft-thomson-http-hx-uri-00 10 Abstract 12 URI schemes are defined that enable identification of HTTP exchanges, 13 or parts of those exchanges. 15 Status of This Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at https://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on September 6, 2019. 32 Copyright Notice 34 Copyright (c) 2019 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (https://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 50 1.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 1.2. Conventions and Definitions . . . . . . . . . . . . . . . 4 52 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 53 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 3. Authority . . . . . . . . . . . . . . . . . . . . . . . . . . 5 55 4. Identifying an Exchange . . . . . . . . . . . . . . . . . . . 6 56 4.1. Identifying HTTP/1.1 Exchanges . . . . . . . . . . . . . 6 57 4.2. Identifying HTTP/2 Exchanges . . . . . . . . . . . . . . 6 58 4.3. Identifiers HTTP/3 Exchanges (#exchange3} . . . . . . . . 7 59 4.4. Identifying Server Pushes . . . . . . . . . . . . . . . . 7 60 5. Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 61 5.1. Identifying a Request . . . . . . . . . . . . . . . . . . 7 62 5.2. Identifying a Response . . . . . . . . . . . . . . . . . 8 63 5.3. Redirections . . . . . . . . . . . . . . . . . . . . . . 8 64 6. Identifying Request or Response Components . . . . . . . . . 8 65 6.1. Identifying the Request Method . . . . . . . . . . . . . 8 66 6.2. Identifying the Effective Request URI . . . . . . . . . . 8 67 6.3. Identifying the Response Status . . . . . . . . . . . . . 8 68 6.4. Identifying the Message Body . . . . . . . . . . . . . . 8 69 6.5. Informational (1xx) Responses . . . . . . . . . . . . . . 9 70 6.6. Identifying a Message Header . . . . . . . . . . . . . . 9 71 6.7. Identifying a Message Trailer . . . . . . . . . . . . . . 10 72 6.8. Identifying Header Field Values . . . . . . . . . . . . . 10 73 7. Conditions . . . . . . . . . . . . . . . . . . . . . . . . . 10 74 7.1. Condition Processing Model . . . . . . . . . . . . . . . 11 75 7.2. Percent-Encoding of Condition Values . . . . . . . . . . 11 76 7.3. Status Condition . . . . . . . . . . . . . . . . . . . . 11 77 7.4. Header Field Value Condition . . . . . . . . . . . . . . 12 78 7.5. Response Content Type Condition . . . . . . . . . . . . . 13 79 7.6. Link Relation Condition . . . . . . . . . . . . . . . . . 13 80 8. hx URI Grammar . . . . . . . . . . . . . . . . . . . . . . . 14 81 9. hxr URI Grammar . . . . . . . . . . . . . . . . . . . . . . . 14 82 10. Security Considerations . . . . . . . . . . . . . . . . . . . 15 83 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 84 11.1. hx URI scheme Registration . . . . . . . . . . . . . . . 15 85 11.2. hxr URI scheme Registration . . . . . . . . . . . . . . 16 86 11.3. TLS Exporter Registration . . . . . . . . . . . . . . . 16 87 11.4. hx and hxr URI Scheme Registries . . . . . . . . . . . . 16 88 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 89 12.1. Normative References . . . . . . . . . . . . . . . . . . 16 90 12.2. Informative References . . . . . . . . . . . . . . . . . 18 91 12.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 18 92 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 18 93 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 18 95 1. Introduction 97 It is common for applications that use HTTP [HTTP] to use a "follow 98 your nose" design. In this design, clients make requests to discover 99 or create resources and to learn information about resources they are 100 interested in. Once the identity of resources is learned, clients 101 then interact with those resources. This process is often iterative, 102 with clients following multiple links to reach resources of interest. 104 A negative consequence of these designs is that the discovery or 105 creation steps add latency to any operation that depends on the 106 identity of resources. 108 For applications that use well-defined formats, though the result of 109 a request might be unknown, an application might have reliable 110 knowledge about the form of the response. If components of that 111 answer could be incorporated into another request by reference, then 112 the application might save a round trip for every such occurrence. 114 The "hx" URI scheme identifies components of HTTP exchanges. The 115 "hxr" URI scheme provides for further indirection, allowing the 116 dereferencing of URLs in identified HTTP exchanges. 118 1.1. Example 120 In this simple example, a client wishes to create and then update a 121 resource. 123 POST /make-object?name=example HTTP/1.1 124 Host: example.com 126 The server creates a resource and provides its location in a 127 response: 129 HTTP/1.1 201 Created 130 Location: https://example.com/roZ2ITW 131 Content-Type: example/example+json 133 { 134 "uri": "https://example.com/roZ2ITW", 135 "name": "example", 136 "items": { "a": 1, "b": 2 } 137 } 139 After receiving the identity of the resource, the client can then 140 interact with that resource, here copying the value of "b" to a new 141 key called "c": 143 POST /roZ2ITW HTTP/1.1 144 Host: example.com 146 add_item: c=2 148 With an "hx" URI, and support from the server, the client can send 149 the second request at the same time as the first, relying on the 150 server to dereference the "hxr" URI: 152 POST hxr:///0/a/h/location?201 HTTP/1.1 153 Host: example.com 155 add_item: c=@hx:///0/a/b?ct=example%2fexample+json#/items/b 157 If the server understands the "hxr" URI scheme, it dereferences that 158 URI to determine the target of the request. The value from /items/b 159 (using JSON Pointer [RFC6901]) is copied using the "hx" URI scheme. 161 Note that it can be seen that though the initial POST request that 162 creates the resource is not idempotent, the client is able to 163 construct the next request in a way that ensures that they are 164 conditional on the outcome of that request. This ensures that the 165 transaction does not complete unless all requests are successful. 167 1.2. Conventions and Definitions 169 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 170 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 171 "OPTIONAL" in this document are to be interpreted as described in BCP 172 14 [RFC2119] [RFC8174] when, and only when, they appear in all 173 capitals, as shown here. 175 1.3. Terminology 177 This document uses terminology from HTTP [HTTP]. The phrase HTTP URI 178 is used to refer to http:// and https:// URIs collectively. However, 179 this document is only capable of identifying requests that are sent 180 over secured transports. 182 2. Overview 184 An "hx" URI identifies an HTTP exchange, or parts of that exchange. 185 The primary advantage of this in referring to the product of a 186 request before it is completed. 188 A scheme of "hx" is followed by an authority that identifies the 189 connection on which the exchange was initiated. A minimal path 190 includes an identifier for the exchange, as a decimal number. For 191 instance, assuming that the authority "b5dd5901aef3f33de572" refers 192 to an HTTP/2 connection, the following URI identifies entire exchange 193 on stream 7 of that connection (see Section 4). 195 hx://b5dd5901aef3f33de572/7 197 Adding additional path elements narrows this to refer to the request 198 (see Section 5): 200 hx://b5dd5901aef3f33de572/7/q 202 Further path elements allow components of a message to be identified, 203 such as a Location header field value (see Section 6.8): 205 hx://b5dd5901aef3f33de572/7/a/h/location 207 To ensure that the Location header field is only used if the request 208 resulted in the creation of a new resource (that is, the response had 209 a 201 (Created) status code), conditions can be added to the URI as 210 query parameters: 212 hx://b5dd5901aef3f33de572/7/a/h/location?201 214 A fragment can be used if the content has an associated content type 215 that supports fragment identifiers, which is generally only possible 216 for the body of a request or response: 218 hx://b5dd5901aef3f33de572/7/a/b#title 220 How a fragment is used depends on the content type of the identified 221 resource, so a condition might be added to specify the content type 222 of the target resource: 224 hx://b5dd5901aef3f33de572/7/a/b?ct=text%2Fhtml#title 226 The "hxr" URI scheme is identical to "hx" except that it is 227 dereferenced twice. A reference that uses the "hxr" scheme can 228 therefore be used where a URI would otherwise be used, taking the 229 value of the URI from chosen part of the identified exchange. 231 3. Authority 233 The authority component of an "hx" or "hxr" URI is an identifier for 234 a connection. 236 The process for generating a unique identifier uses TLS exporters 237 (see Section 7.5 of [TLS13]). Consequently, exchanges on connections 238 that do not use TLS cannot be identified using "hx" or "hxr" URIs. 240 A TLS exporter with the label "EXPORTER-hx-authority" and an empty 241 context is used to produce a 10 octet value. This value is then 242 encoded in hexadecimal (that is, Base 16 [RFC4648]) to produce a 20 243 character authority. 245 The authority can be omitted where the identity of the connection can 246 be inferred from context. For instance, where the URI is sent over 247 the same connection. The current connection is used if an authority 248 is absent. 250 hx:///7 252 The userinfo and port components of an "hx" or "hxr" URI MUST NOT be 253 used. Any URI with userinfo or port components is invalid. 255 4. Identifying an Exchange 257 After identifying the connection, the first element of the path after 258 the initial slash ("/") identifies a request-response exchange. 260 A decimal value is used to identify an exchange. How requests are 261 identified depends on the version of HTTP in use. 263 A single "p" character followed by a decimal value is used to 264 identify a server push, see Section 4.4. 266 An "hx" or "hxr" URI always includes fields that identify an 267 exchange. For instance, the following URIs are incomplete and 268 therefore invalid: 270 hx:// 271 hx:/// 272 hx://b5dd5901aef3f33de572/ 274 4.1. Identifying HTTP/1.1 Exchanges 276 In HTTP/1.1 [HTTP11] and earlier, the numeric identifier for an 277 exchange counts the number of exchanges on the connection that 278 precede the target exchange. The first exchange on a connection is 279 therefore identified as "hx:///0". Subsequent requests increment 280 this value by 1. 282 4.2. Identifying HTTP/2 Exchanges 284 In HTTP/2 [HTTP2], the numeric identifier for an exchange corresponds 285 to a HTTP/2 stream identifier. The first exchange on a connection is 286 therefore identified as "hx:///1". As a result, all exchanges that 287 are not server pushes use odd-numbered identifiers. 289 4.3. Identifiers HTTP/3 Exchanges (#exchange3} 291 In HTTP/3 [HTTP3], the numeric identifier for an exchange corresponds 292 to a QUIC stream identifier. The first exchange on a connection is 293 therefore identified as "hx:///0". Consequently, all exchanges that 294 are not server pushes use identifiers that are whole multiples of 4. 296 4.4. Identifying Server Pushes 298 A server push exchange is identified by a "p" prefix followed by a 299 decimal value. For example: 301 hx:///p6 303 In HTTP/2, a stream identifier is sufficient to distinguish between 304 requests and server pushes. Thus, identifying a server push is 305 possible even if the "p" prefix is omitted. In HTTP/2, all server 306 pushes use even-numbered identifiers. 308 Server pushes in HTTP/3 are given a push ID, an identifier that might 309 be the same as the stream ID used for requests. The push ID is used 310 to identify server push in HTTP/3. Thus, in HTTP/3, the "p" prefix 311 is necessary to properly identify a server push. 313 HTTP versions prior to HTTP/2 do not provide server push, so an "hx" 314 URI that attempts to identify a server push cannot be successfully 315 resolved. 317 5. Targets 319 Without further qualification, an "hx" URI identifies a message 320 exchange, both the request and the response as a whole. Applications 321 can narrow this to a request (Section 5.1) or response (Section 5.2). 323 A "hxr" URI always identifies a request or response, it cannot 324 identify a complete exchange. 326 5.1. Identifying a Request 328 A request is identified by adding "/q" to a URI identifying an 329 exchange. For example: 331 hx://546c9bce274b06cf859d/84/q 333 5.2. Identifying a Response 335 A request is identified by adding "/a" to a URI identifying an 336 exchange. For example: 338 hx://18660225619af2c6c300/173/a 340 5.3. Redirections 342 An "hx" or "hxr" URI applies to a single exchange over a single 343 connection. If a 3xx status code results in a client following a 344 redirect, that exchange is identified separately. 346 6. Identifying Request or Response Components 348 After identifying a single message, additional path components can be 349 used to identify parts of the message. 351 TBD: It might make sense to put "/m", "/u", "/s", and "/i" as peers 352 to "/q" and "/a" rather than attaching them underneath. The 353 primary advantage would be a shorter identifier. (Doing this for 354 "/i" alone might work, as that is more of a peer to "/a".) 356 6.1. Identifying the Request Method 358 A path component of "/m" indicates that an 'hx' URI identifies the 359 request method. This component is not valid for an "hxr" URI or an 360 "hx" URI that identifies a response. 362 6.2. Identifying the Effective Request URI 364 A path component of "/u" indicates that an 'hx' or "hxr" URI 365 identifies the effective request URI (see Section 5.3 of [HTTP]). 367 6.3. Identifying the Response Status 369 A path component of "/s" indicates that an 'hx' URI identifies the 370 request method. This component is not valid for an "hxr" URI or an 371 "hx" URI for a request. 373 6.4. Identifying the Message Body 375 A path component of "/b" identifies the body of the message. A body 376 can be identified for both "hx" and "hxr" URIs. 378 Identifying the body of a message without a body (like a GET request 379 or a 204 (No Content) response) successfully identifies the empty 380 body. 382 6.5. Informational (1xx) Responses 384 The "/i" path component can be used to select informational 385 responses. 387 The "/i" component is followed by a path component that identifies 388 which informational responses to select. If this contains a decimal 389 value, this indicates the number of the informational response to 390 select. The first information response is identified with "0", with 391 subsequent information responses each using a number 1 greater than 392 the last. A value of "@" is used to identify the last informational 393 response and a value of "*" identifies all informational responses. 395 TBD: Indexing is a little strange given the use case here. The 396 problem lies in working out what to do with multiple entries. 397 Maybe the right answer is to allow for selecting just the first, 398 last, or all items. That would simplify the scheme a little. 400 Indexing applies after any conditions are applied (see Section 7), 401 allowing a URI to identify single informational response. 403 For example, the following "hx" URIs refer to the third 103 response, 404 the last informational response containing a Link header field, and 405 all informational responses respectively. 407 hx:///71/a/i/2?103 408 hx:///71/a/i/@?h=link 409 hx:///71/a/i/* 411 The path components "/s" (Section 6.3) or "/h" (Section 6.6) can be 412 used to select parts of an informational response. For example, all 413 Link header fields from informational responses can be collected 414 with: 416 hx:///10/a/i/*/h/link/* 418 6.6. Identifying a Message Header 420 A path component of "/h" identifies the header of a message as a 421 whole. When preceded by "/i", this identifies the header of the 422 informational response (see Section 6.5). When not preceded by "/i" 423 it refers to the header from requests and final responses. 425 Without additional path elements, this form is only valid for an "hx" 426 URI; an "hxr" URI requires that specific header fields be identified. 428 6.7. Identifying a Message Trailer 430 A path component of "/t" specifically identifies the trailer of a 431 message. Trailers are subject to the same restrictions as headers 432 with the additional condition that they can't be present on 433 informational responses. 435 6.8. Identifying Header Field Values 437 Adding a path component containing the name of a header field to a 438 path that identifies the a header ("/h" or "/i/.../h") or trailer 439 ("/t") from a message selects that header field only. 441 The next path component indexes header field values, just like 442 informational responses are indexed (see Section 6.5). All values 443 from the message are identified by "*". A decimal value indicates a 444 0-based index into values. The last value is identified by "@". 446 Values that use the HTTP list construction are not indexed by 447 instances of the header field, but by the comma-separated values that 448 are present. Empty values or those containing only whitespace are 449 skipped and cannot be indexed. 451 To illustrate this, there are 4 values that can be indexed in the 452 following HTTP/1.1 example. The third value is "3" and the last 453 ("/@") is "4". 455 Example: 1 456 Example: 2, ,3 457 Example: ,4, 459 As a special case, an "hxr" URI that refers to the value of a Link 460 header field [LINK] can be used as a reference. 462 7. Conditions 464 The query string of an "hx" URI carries a set of conditions. Unless 465 any conditions evaluate to true, the resolution of the URI will fail. 466 This allows for specification of URIs that are conditional on details 467 of the HTTP exchange. 469 For example, the following URI cannot be dereferenced unless the 470 response indicates success, ensuring that the body of an unwanted 471 response like 503 is not used: 473 hx://b5dd5901aef3f33de572/7/a/b?2xx 474 Conditions are separated by the ampersand ("&") character. Each 475 comprises a label that identifies the type of the condition, and an 476 optional value. The value is separated from the label by an equals 477 sign ("=") character. 479 This document defines conditions for status code (Section 7.3), 480 header field values (Section 7.4), and response content-type 481 (Section 7.5). Conditions that are not understood always evaluate to 482 false, causing resolution to fail. 484 7.1. Condition Processing Model 486 Conditions are potentially processed multiple times. 488 Multiple values can be produced for informational responses and 489 header fields. In each case, when multiple values are produced, 490 conditions are evaluated. This might reduce the number of options. 491 If multiple values remain, all options are considered when evaluating 492 the remainder of the URI path. 494 For instance, a Link header field [LINK] might appear multiple times 495 and in multiple informational responses. The Link Relation Type 496 condition (Section 7.6) might be used to select all link relations of 497 a given type across all informational responses. 499 hx:///29/a/i/*/h/link/*?rel=start 501 7.2. Percent-Encoding of Condition Values 503 The URI grammar [URI] prohibits the use of certain characters in the 504 query string. This scheme uses percent-encoding to allow conditions 505 to carry values that are not permitted by the URI grammar. 506 Section 2.1 of [URI] defines percent-encoding. The "hx-pct-encoded" 507 rule in Section 8 defines the characters that don't require encoding; 508 all other values MUST be percent-encoded. 510 7.3. Status Condition 512 Any condition that starts with a numeral from "1" to "5" is used to 513 specify a condition on the response status. 515 If the condition contains three digits, the condition evaluates to 516 true if the response contained a matching status code. 518 A condition that contains a numeral and two "x" characters evaluates 519 to true if the status code is from the identified class. For 520 instance, the following identifies a request that was redirected: 522 hx:///22/q?3xx 524 A condition that specifies an informational status code (1xx) will be 525 true if an informational response of that type was present. It does 526 not result in limiting the components that can be selected. Specific 527 100-series status codes can be used to limit which informational 528 responses are selected if the "/i" path component is used (see 529 Section 6.5). 531 A URI that identifies a header field will resolve the final value of 532 the header field unless a specific portion of the response is 533 specified (using "/i" or "/t"), taking into account values from final 534 responses and trailers as defined in Section 6.6. 536 This condition can be used to identify components of a request, 537 conditional on the status code of the response. 539 New condition definitions MUST NOT start with a numeral from "1" and 540 "5". 542 7.4. Header Field Value Condition 544 The header field condition is identified with a "h" token. A "h=" is 545 followed by the name of the header field. With no further values, 546 this condition is satisfied if a header field with the same name is 547 present in the identified part of the message. An additional "=" 548 character can be added, which causes the condition to be true only 549 when the value of the header field is equal to the remainder of the 550 condition. 552 This condition applies to any header field from the identified 553 object. Thus, if the URI does not specify whether a request or 554 response, the condition is met based on the presence or value of the 555 header or trailer field in request or response, including 556 informational responses. If the target of the URI is a request, 557 response, or informational response, then only header and trailer 558 fields in the corresponding part of the message apply. For instance, 559 if the URI identies the header, then only header fields are used to 560 match. 562 Thus, to identify a request if it contains a User-Agent header field 563 with any value, the following might be used: 565 hx:///30/q?h=user-agent 567 To select a response body only if it indicates that requests for byte 568 ranges are supported, the following might be used: 570 hx:///71/a/b?h=accept-ranges=bytes 572 Alternative forms of matching aside from equality might be provided 573 in future. 575 7.5. Response Content Type Condition 577 The response content type condition matches if the content type of 578 the response matches the specified content type. Acceptable values 579 and rules for determining what values match follow the rules for the 580 Accept header field (see Section 8.4.2 of [HTTP]). 582 The response content type condition is identified by "ct" and is 583 followed by a percent-encoded content type. For example: 585 hx:///12/a/b?ct=text%2Fhtml 587 Unlike the header field condition (Section 7.4), the response content 588 type condition can be used with URIs that identify components of a 589 request. In that case, it indicates that the identification is 590 conditional on the content type of the response (not the request). 592 Separator characters ("/", ";" and ",") MUST be percent-encoded in 593 the value of this condition. 595 7.6. Link Relation Condition 597 A link relation condition filters results by those that contain a 598 link relation [LINK] of the specified type. 600 The link relation condition is identified by "rel" and is followed by 601 a link relation type. Link relations that include non-token 602 characters, such as those that use the URL form, MUST be percent- 603 encoded. 605 If the target is a request, response, informational response, or 606 component that contains header fields, only those messages or parts 607 of messages that contain a link relation of the specified type are 608 selected. 610 If the target is a Link header field, then only link relations of the 611 identified type are selected. Deferencing fails if any other header 612 field is identified. 614 8. hx URI Grammar 616 In ABNF [RFC5234], the "hx" URI scheme can be described as a narrow 617 profile of that defined in [URI]. 619 hx-URI = "hx://" [ hx-authority ] hx-exchange 620 [ hx-target ] [ hx-conditions ] 621 hx-authority = 20HEXDIG 622 hx-exchange = "/" [ "p" ] 1*DIGIT 624 hx-target = hx-request / hx-response 625 hx-request = "/q" [ "/" hx-component ] 626 hx-response = "/a" [ "/" hx-component ] 628 hx-component = hx-method / hx-uri / hx-info 629 / hx-header / hx-body / hx-trailer 630 hx-method = "/m" 631 hx-uri = "/u" 632 hx-info = "/i/" hx-index [ hx-status / hx-header ] 633 hx-status = "/s" 634 hx-header = "/h" [ "/" hx-token [ "/" hx-index ] ] 635 hx-body = "/b" 636 hx-trailer = "/t" [ "/" hx-token [ "/" hx-index ] ] 638 hx-index = 1*DIGIT / "@" / "*" 639 hx-token = 1*hx-token-char 640 hx-token-char = "-" / "." / "_" / DIGIT / ALPHA 642 hx-conditions = "?" hx-condition *("&" hx-condition) 643 hx-condition = hx-status-cond / hx-header-cond 644 / hx-ct-cond / hx-extension-cond 645 hx-status-cond = ("1" / "2" / "3" / "4" / "5") (2DIGIT / "xx") 646 hx-header-cond = "h=" hx-token [ "=" hx-pct-encoded ] 647 hx-ct-cond = "ct=" hx-pct-encoded 648 hx-extension-cond = hx-token [ "=" hx-pct-encoded ] 650 hx-pct-encoded = *( hx-token-char / ("%" 2HEXDIG) ) 652 9. hxr URI Grammar 654 The "hxr" URI scheme uses the same basic grammar as the "hx" URI 655 scheme. However, since this can only ever reference parts of an 656 exchange that could contain a URI, the grammar is more narrowly 657 defined. 659 hxr-URI = "hxr://" [ hx-authority ] "/" hx-exchange 660 hxr-target [ "?" hx-conditions ] 662 hxr-targets = hxr-request / hxr-response 663 hxr-request = "/q/" hxr-component 664 hxr-response = "/a/" hxr-component 666 hxr-component = hx-uri / hxr-info 667 / hxr-header / hx-body / hxr-trailer 668 hxr-info = "/i/" hx-index hxr-header 669 hxr-header = "/h/" hx-token [ "/" hx-index ] 670 hxr-trailer = "/t/" hx-token [ "/" hx-index ] 672 The main difference between the "hx" and "hxr" schemes is that "hxr" 673 URIs contain a narrower set of possible values, omitting all means of 674 identifying parts of a request that cannot produce a URI. 676 10. Security Considerations 678 Resolution of details of unfulfilled requests could present a 679 significant state commitment on servers. Servers that receive 680 requests that depend on other requests might have to block processing 681 until the outcome of the referenced requests is complete. 682 Alternatively, servers might need to hold information about completed 683 requests in anticipation of receiving references to that request. 685 Servers can fail resolution of "hx" or "hxr" URIs if the state 686 required would present an undue burden on their operation. Servers 687 might limit the types of information that can be retained and 688 referenced to reduce this cost. 690 Applications that use these URI schemes MUST define what types of 691 reference a server is expected to be able to handle, or provide a 692 means of negotiating what can be relied on. 694 11. IANA Considerations 696 This document registers the "hx" and "hxr" URI schemes. In support 697 of this, registrations are made in the TLS exporters registry 698 (Section 11.3) and registries are established for managing the 699 parameters of the URI schemes (Section 11.4). 701 11.1. hx URI scheme Registration 703 The "hx" URI scheme is registered according to the procedures in 704 [BCP35]. 706 Scheme name: hx 707 Status: Permanent/Provisional 709 Applications/protocols that use this scheme name: Applications use 710 URIs with this scheme to identify HTTP exchanges, requests, 711 responses, or components of those messages. 713 Contact: IETF Chair chair@ietf.org [1] 715 Change controller: IESG iesg@ietf.org [2] 717 Reference: This document. 719 11.2. hxr URI scheme Registration 721 The "hxr" URI scheme is registered according to the procedures in 722 [BCP35]. 724 Scheme name: hxr 726 Status: Permanent/Provisional 728 Applications/protocols that use this scheme name: Applications use 729 URIs with this scheme in place of URIs where the intended URI is 730 found in a component of an HTTP exchange. 732 Contact: IETF Chair chair@ietf.org [3] 734 Change controller: IESG iesg@ietf.org [4] 736 Reference: This document. 738 11.3. TLS Exporter Registration 740 TODO 742 11.4. hx and hxr URI Scheme Registries 744 TODO considering setting up registries for various bits of the 745 syntax. 747 12. References 749 12.1. Normative References 751 [BCP35] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 752 and Registration Procedures for URI Schemes", BCP 35, 753 RFC 7595, DOI 10.17487/RFC7595, June 2015, 754 . 756 [HTTP] Fielding, R., Nottingham, M., and J. Reschke, "HTTP 757 Semantics", draft-ietf-httpbis-semantics-03 (work in 758 progress), October 2018. 760 [HTTP11] Fielding, R., Nottingham, M., and J. Reschke, "HTTP/1.1 761 Messaging", draft-ietf-httpbis-messaging-03 (work in 762 progress), October 2018. 764 [HTTP2] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 765 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 766 DOI 10.17487/RFC7540, May 2015, 767 . 769 [HTTP3] Bishop, M., "Hypertext Transfer Protocol Version 3 770 (HTTP/3)", draft-ietf-quic-http-18 (work in progress), 771 January 2019. 773 [LINK] Nottingham, M., "Web Linking", RFC 8288, 774 DOI 10.17487/RFC8288, October 2017, 775 . 777 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 778 Requirement Levels", BCP 14, RFC 2119, 779 DOI 10.17487/RFC2119, March 1997, 780 . 782 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 783 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 784 . 786 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 787 Specifications: ABNF", STD 68, RFC 5234, 788 DOI 10.17487/RFC5234, January 2008, 789 . 791 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 792 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 793 May 2017, . 795 [TLS13] Rescorla, E., "The Transport Layer Security (TLS) Protocol 796 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 797 . 799 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 800 Resource Identifier (URI): Generic Syntax", STD 66, 801 RFC 3986, DOI 10.17487/RFC3986, January 2005, 802 . 804 12.2. Informative References 806 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 807 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 808 DOI 10.17487/RFC6901, April 2013, 809 . 811 12.3. URIs 813 [1] mailto:chair@ietf.org 815 [2] mailto:iesg@ietf.org 817 [3] mailto:chair@ietf.org 819 [4] mailto:iesg@ietf.org 821 Acknowledgments 823 TODO acknowledge. 825 Author's Address 827 Martin Thomson 828 Mozilla 830 Email: mt@lowentropy.net