Skip to content

Commit acef461

Browse files
annevkannevk
authored
Elaborate on obtaining a connection
In particular, define resolving domains and allow connection creation to be a race. As a result this also inlines some of the time capture moments to be directly inside the obtain a connection algorithm. This helps with #1243.
1 parent d0bd853 commit acef461

File tree

1 file changed

+124
-71
lines changed

1 file changed

+124
-71
lines changed

‎fetch.bs

Lines changed: 124 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -2204,6 +2204,47 @@ unset or <a for=request>keepalive</a> is false, <a lt=terminated for=fetch>termi
22042204
<a for="fetch group">fetch record</a>'s <a for="fetch record">fetch</a>.
22052205

22062206

2207+
<h3 id=resolving-domains>Resolving domains</h3>
2208+
2209+
<p tracking-vector>To <dfn>resolve a domain</dfn>, given a <a for=/>network partition key</a>
2210+
<var>key</var> and a <a for=/>domain</a> <var>domain</var>, perform an <a>implementation-defined</a>
2211+
operation to turn <var>domain</var> into a <a for=/>set</a> of one or more
2212+
<a for=/>IP addresses</a>. If this operation succeeds, return the <a for=/>set</a> of
2213+
<a for=/>IP addresses</a>. If it fails, return failure. The results of this operation may be cached.
2214+
If they are cached, <var>key</var> should be used as part of the cache key.
2215+
2216+
<div class=note>
2217+
<p>Typically this operation would involve DNS and as such caching can happen on DNS servers without
2218+
<var>key</var> being taken into account. Depending on the implementation it might also not be
2219+
possible to take <var>key</var> into account locally. [[RFC1035]]
2220+
2221+
<p>The order of the <a for=/>IP addresses</a> <a>resolve a domain</a> can return return can differ
2222+
between invocations.
2223+
2224+
<p>The particulars (apart from the cache key) are not tied down as they are not pertinent to the
2225+
system the Fetch Standard establishes. Other documents ought not to build on this primitive without
2226+
having a considered discussion with the Fetch Standard community first.
2227+
</div>
2228+
2229+
<p>To <dfn>resolve an origin</dfn>, given a <a for=/>network partition key</a> <var>key</var> and an
2230+
<a for=/>origin</a> <var>origin</var>:
2231+
<!-- Should we assert the scheme here to be an HTTP(S) scheme or a WebRTC scheme? -->
2232+
2233+
<ol>
2234+
<li><p>If <var>origin</var>'s <a for=origin>host</a> is an <a for=/>IP address</a>, then return
2235+
« <var>origin</var>'s <a for=origin>host</a> ».
2236+
2237+
<li><p>If the user agent is configured to use a proxy that resolves domains on its own, then return
2238+
« <var>origin</var>'s <a for=origin>host</a> ».
2239+
2240+
<li><p>Return the result of running <a>resolve a domain</a> given <var>key</var> and
2241+
<var>origin</var>'s <a for=origin>host</a>.
2242+
</ol>
2243+
2244+
<p class=note>The same caveat applies. Do not build on this without having a considered discussion
2245+
with the Fetch Standard community first.
2246+
2247+
22072248
<h3 id=connections>Connections</h3>
22082249

22092250
<p>A user agent has an associated <dfn export id=concept-connection-pool>connection pool</dfn>. A
@@ -2274,7 +2315,7 @@ steps:
22742315
<hr>
22752316

22762317
<p>To <dfn export id=concept-connection-obtain>obtain a connection</dfn>, given a
2277-
<a>network partition key</a> <var>key</var>, <a for=/>origin</a>, <var>origin</var>, boolean
2318+
<a>network partition key</a> <var>key</var>, <a for=/>origin</a> <var>origin</var>, boolean
22782319
<var>credentials</var>, an optional boolean <var>forceNew</var> (default false), an optional boolean
22792320
<dfn export for="obtain a connection"><var>http3Only</var></dfn> (default false), and an optional
22802321
boolean <dfn export for="obtain a connection"><var>dedicated</var></dfn> (default false), run these
@@ -2298,55 +2339,103 @@ steps:
22982339
<a>connection</a>.
22992340
</ol>
23002341

2301-
<li><p>Let <var>connection</var> be null.
2342+
<li><p>Let <var>timingInfo</var> be a new <a for=/>connection timing info</a>.
23022343

2303-
<li>
2304-
<p>Run these steps, but <a>abort when</a> the ongoing fetch is <a for=fetch>terminated</a>:
2344+
<li><p>Set <var>timingInfo</var>'s <a for="connection timing info">domain lookup start time</a> to
2345+
the <a for=/>unsafe shared current time</a>.
23052346

2306-
<ol>
2307-
<li>
2308-
<p>Set <var>connection</var> to a new <a for=/>connection</a> whose <a for=connection>key</a> is
2309-
<var>key</var>, <a for=connection>origin</a> is <var>origin</var>, and
2310-
<a for=connection>credentials</a> is <var>credentials</var>.
2311-
<a for=/>Record connection timing info</a> given <var>connection</var> and use
2312-
<var>connection</var> to establish an HTTP connection to <var>origin</var>.
2313-
[[!HTTP]] [[!HTTP-SEMANTICS]] [[!HTTP-COND]] [[!HTTP-CACHING]] [[!HTTP-AUTH]] [[!TLS]]
2314-
2315-
<p>If <var>http3Only</var> is true, then establish an HTTP/3 connection. [[!HTTP3]]
2347+
<li><p>Let <var>hosts</var> be the result of running <a>resolve an origin</a> given <var>key</var>
2348+
and <var>origin</var>.
23162349

2317-
<p>When establishing an HTTP/3 connection, include SETTINGS_ENABLE_WEBTRANSPORT with a value of
2318-
1 and H3_DATAGRAM with a value of 1 in the initial SETTINGS frame. [[!WEBTRANSPORT-HTTP3]]
2319-
[[!HTTP3-DATAGRAM]]
2350+
<li><p>If <var>hosts</var> is failure, then return failure.
23202351

2321-
<p>If <var>credentials</var> is false, then do <em>not</em> send a TLS client certificate.
2322-
2323-
<p>If establishing a connection does not succeed (e.g., a DNS, TCP, or TLS error), then return
2324-
failure.
2325-
</ol>
2352+
<li><p>Set <var>timingInfo</var>'s <a for="connection timing info">domain lookup end time</a> to
2353+
the <a for=/>unsafe shared current time</a>.
23262354

23272355
<li>
2328-
<p><a>If aborted</a>, then:
2356+
<p>Let <var>connection</var> be the result of running this step: run <a>create a connection</a>
2357+
given <var>key</var>, <var>origin</var>, <var>credentials</var>, an <a>implementation-defined</a>
2358+
<a for=/>host</a> from <var>hosts</var>, <var>timingInfo</var>, and <var>http3Only</var> an
2359+
<a>implementation-defined</a> number of times, <a>in parallel</a> from each other, and wait for at
2360+
least 1 to return a value. In an <a>implementation-defined</a> manner, select a value to return
2361+
from the returned values and return it. Any other returned values that are <a>connections</a> may
2362+
be closed.
23292363

2330-
<ol>
2331-
<li><p>If <var>connection</var> is not null, then close <var>connection</var>.
2364+
<p class=note>Essentially this allows an implementation to pick one or more
2365+
<a for=/>IP addresses</a> from the return value of <a>resolve a domain</a> (assuming no proxy) and
2366+
race them against each other, favor <a for=/>IPv6 addresses</a>, retry in case of a timeout, etc.
23322367

2333-
<li><p>Return failure.
2334-
</ol>
2368+
<li><p>If <var>connection</var> is failure, then return failure.
23352369

23362370
<li><p>If <var>dedicated</var> is false, then <a for=set>append</a> <var>connection</var> to the
23372371
user agent's <a>connection pool</a>.
23382372

23392373
<li><p>Return <var>connection</var>.
23402374
</ol>
23412375

2342-
<p class="note no-backref">This is intentionally a little vague as the finer points are still
2343-
evolving. Describing this helps explain the <code>&lt;link rel=preconnect></code> feature and
2344-
clearly stipulates that <a>connections</a> are keyed on
2345-
<b>credentials</b>. The latter clarifies that e.g., TLS session identifiers are not reused across
2346-
<a>connections</a> whose <b>credentials</b> are false with
2347-
<a>connections</a> whose <b>credentials</b> are true.
2348-
<!-- See https://github.com/whatwg/fetch/issues/114#issuecomment-143500095 for when we make
2349-
WebSocket saner -->
2376+
<p class=note>This is intentionally a little vague as there are a lot of nuances to connection
2377+
management that are best left to the discretion of implementers. Describing this helps explain the
2378+
<code>&lt;link rel=preconnect></code> feature and clearly stipulates that <a>connections</a> are
2379+
keyed on <a for=/>credentials</a>. The latter clarifies that, e.g., TLS session identifiers are not
2380+
reused across <a>connections</a> whose <a for=connection>credentials</a> are false with
2381+
<a>connections</a> whose <a for=connection>credentials</a> are true.
2382+
2383+
<hr>
2384+
2385+
<p>To <dfn>create a connection</dfn>, given a <a for=/>network partition key</a> <var>key</var>,
2386+
<a for=/>origin</a> <var>origin</var>, boolean <var>credentials</var>, <a for=/>host</a>
2387+
<var>host</var>, <a for=/>connection timing info</a> <var>timingInfo</var>, and boolean
2388+
<var>http3Only</var>, run these steps:
2389+
2390+
<ol>
2391+
<li><p>Set <var>timingInfo</var>'s <a for="connection timing info">connection start time</a> to the
2392+
<a for=/>unsafe shared current time</a>.
2393+
2394+
<li>
2395+
<p>Let <var>connection</var> be a new <a for=/>connection</a> whose <a for=connection>key</a> is
2396+
<var>key</var>, <a for=connection>origin</a> is <var>origin</var>,
2397+
<a for=connection>credentials</a> is <var>credentials</var>, and <a for=connection>timing info</a>
2398+
is <var>timingInfo</var>. <a for=/>Record connection timing info</a> given <var>connection</var>
2399+
and use <var>connection</var> to establish an HTTP connection to <var>host</var>, taking
2400+
<var>origin</var> into account. [[!HTTP]] [[!HTTP-SEMANTICS]] [[!HTTP-COND]] [[!HTTP-CACHING]]
2401+
[[!HTTP-AUTH]] [[!TLS]]
2402+
2403+
<p>If <var>http3Only</var> is true, then establish an HTTP/3 connection. [[!HTTP3]]
2404+
2405+
<p>When establishing an HTTP/3 connection, include SETTINGS_ENABLE_WEBTRANSPORT with a value of 1
2406+
and H3_DATAGRAM with a value of 1 in the initial SETTINGS frame. [[!WEBTRANSPORT-HTTP3]]
2407+
[[!HTTP3-DATAGRAM]]
2408+
2409+
<p>If <var>credentials</var> is false, then do <em>not</em> send a TLS client certificate.
2410+
2411+
<p>If establishing a connection does not succeed (e.g., a TCP or TLS error), then return failure.
2412+
2413+
<li>
2414+
<p>Set <var>timingInfo</var>'s <a for="connection timing info">ALPN negotiated protocol</a> to
2415+
<var>connection</var>'s ALPN Protocol ID, with the following caveats: [[RFC7301]]
2416+
2417+
<ul>
2418+
<li><p>When a proxy is configured, if a tunnel connection is established then this must be the
2419+
ALPN Protocol ID of the tunneled protocol, otherwise it must be the ALPN Protocol ID of the first
2420+
hop to the proxy.
2421+
2422+
<li>
2423+
<p>In case the user agent is using an experimental, non-registered protocol, the user agent must
2424+
use the used ALPN Protocol ID, if any. If ALPN was not used for protocol negotiations, the user
2425+
agent may use another descriptive string.
2426+
2427+
<p class=note><var>timingInfo</var>'s
2428+
<a for="connection timing info">ALPN negotiated protocol</a> is intended to identify the network
2429+
protocol in use regardless of how it was actually negotiated; that is, even if ALPN is not used
2430+
to negotiate the network protocol, this is the ALPN Protocol IDs that indicates the protocol in
2431+
use.
2432+
</ul>
2433+
2434+
<p class=note>IANA maintains a
2435+
<a href="https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids">list of ALPN Protocol IDs</a>.
2436+
2437+
<li><p>Return <var>connection</var>.
2438+
</ol>
23502439

23512440
<hr>
23522441

@@ -2355,18 +2444,6 @@ clearly stipulates that <a>connections</a> are keyed on
23552444
<a for=connection>timing info</a> and observe these requirements:
23562445

23572446
<ul>
2358-
<li><p><var>timingInfo</var>'s <a for="connection timing info">domain lookup start time</a>
2359-
should be the <a for=/>unsafe shared current time</a> immediately before starting the domain
2360-
lookup, or beginning retrieval of the information from cache.
2361-
2362-
<li><p><var>timingInfo</var>'s <a for="connection timing info">domain lookup end time</a> should
2363-
be the <a for=/>unsafe shared current time</a> immediately after finishing the domain lookup, or
2364-
retrieving the information from cache.
2365-
2366-
<li><p><var>timingInfo</var>'s <a for="connection timing info">connection start time</a> should
2367-
be the <a for=/>unsafe shared current time</a> immediately before establishing the connection to
2368-
the server or proxy.
2369-
23702447
<li>
23712448
<p><var>timingInfo</var>'s <a for="connection timing info">connection end time</a> should be the
23722449
<a for=/>unsafe shared current time</a> immediately after establishing the connection to the
@@ -2401,30 +2478,6 @@ clearly stipulates that <a>connections</a> are keyed on
24012478
<a for="connection timing info">secure connection start time</a> should be the result of calling
24022479
<a for=/>unsafe shared current time</a> immmediately before starting the handshake process to
24032480
secure <var>connection</var>. [[!TLS]]
2404-
2405-
<li>
2406-
<p><var>timingInfo</var>'s <a for="connection timing info">ALPN negotiated protocol</a> should be
2407-
the <var>connection</var>'s ALPN Protocol ID, with the following caveats: [[RFC7301]]
2408-
2409-
<ul>
2410-
<li><p>When a proxy is configured, if a tunnel connection is established then this must be the
2411-
ALPN Protocol ID of the tunneled protocol, otherwise it must be the ALPN Protocol ID of the first
2412-
hop to the proxy.
2413-
2414-
<li>
2415-
<p>In case the user agent is using an experimental, non-registered protocol, the user agent must
2416-
use the used ALPN Protocol ID, if any. If ALPN was not used for protocol negotiations, the user
2417-
agent may use another descriptive string.
2418-
2419-
<p class=note><var>timingInfo</var>'s
2420-
<a for="connection timing info">ALPN negotiated protocol</a> is intended to identify the network
2421-
protocol in use regardless of how it was actually negotiated; that is, even if ALPN is not used
2422-
to negotiate the network protocol, this is the ALPN Protocol IDs that indicates the protocol in
2423-
use.
2424-
</ul>
2425-
2426-
<p class=note>IANA maintains a
2427-
<a href="https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids">list of ALPN Protocol IDs</a>.
24282481
</ul>
24292482

24302483
<p class=note>The <a for=/>clamp and coarsen connection timing info</a> algorithm ensures that

0 commit comments

Comments
 (0)