Artifactspublic-v0

curl

master
ply4 git calls361 ms289 KiB2 cachedprotocol v2
130 lines4.3 KiBRaw

NAME

CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS - timing of connect attempts

SYNOPSIS

c
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS,
                          long timeout);

DESCRIPTION

Happy eyeballs is an algorithm that controls connecting to a host that resolves to more than one IP address. A common setup is to expose an IPv4 and IPv6 address (dual-stack). Other host offer a range of addresses for one or both stacks.

IP Addresses

When curl is built with IPv6 support, it attempts to connect to IPv6 first, when available. When that fails, another connect attempt for the first IPv4 address (again, if available) is started. Should that fail, the next IPv6 address is used, then the next IPv4, etc. If there are only addresses for one stack, those are tried one after the other.

When there is neither a positive nor negative response to an attempt, another attempt is started after timeout has passed. Then another, after timeout has passed again. As long as there are addresses available.

When all addresses have been tried and failed, the transfer fails. All attempts are aborted after CURLOPT_CONNECTTIMEOUT_MS(3) has passed, counted from the first attempt onward.

The range of suggested useful values for timeout is limited. Happy Eyeballs RFC 6555 says "It is RECOMMENDED that connection attempts be paced 150-250 ms apart to balance human factors against network load." libcurl currently defaults to 200 ms. Firefox and Chrome currently default to 300 ms.

As an example, for a host that resolves to 'a1_v4, a2_v4, a3_v6, a4_v6' curl opens a socket to 'a3_v6' first. When that does not report back, it opens another socket to 'a1_v4' after 200ms. The first socket is left open and might still succeed. When 200ms have gone by again, a socket for 'a4_v6' is opened. 200ms later, 'a2_v4' is tried.

At this point, there are 4 sockets open (unless the network has reported anything back). That took 3 times the happy eyeballs timeout, so 600ms in the default setting. When any of those four report a success, that socket is used for the transfer and the other three are closed.

There is a limit on the number of sockets opened for connect attempts. When that limit is reached and more addresses are available, the oldest attempt is discarded. This limit is currently 6. With the default happy eyeballs timeout of 200ms, this closes attempts after 1.2 seconds as long as there are more addresses to try.

There are situations where connect attempts fail, but the failure is considered being inconclusive. The QUIC protocol may encounter this. When a QUIC server restarts, it may send replies indicating that it is not accepting new connections right now, but maybe later.

Such "inclusive" connect attempt failures cause a restart of the attempt, with the same address on a new socket, closing the previous one. Repeatedly until CURLOPT_CONNECTTIMEOUT_MS(3) strikes.

HTTPS

When connection with the HTTPS protocol to a host that may talk HTTP/3, HTTP/2 or HTTP/1.1, curl applies a similar happy eyeballs strategy when attempting these versions.

When HTTPS only involves a TCP connection, the versions are negotiated via ALPN, the TLS extension, in a single connect. Since HTTP/3 runs on QUIC (which runs on UDP), it requires a separate connect attempt.

The HTTP/3 attempt is started first and, after timeout expires, the HTTP/2 (or 1.1) attempt is started in parallel.

DEFAULT

CURL_HET_DEFAULT (currently defined as 200L)

%PROTOCOLS%

EXAMPLE

c
int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode result;
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");

    /* Set the timeout to 300 milliseconds */
    curl_easy_setopt(curl, CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS, 300L);

    result = curl_easy_perform(curl);

    /* always cleanup */
    curl_easy_cleanup(curl);
  }
}

%AVAILABILITY%

RETURN VALUE

curl_easy_setopt(3) returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK, non-zero means an error occurred, see libcurl-errors(3).

1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS
5Section: 3
6Source: libcurl
7Protocol:
8 - All
9See-also:
10 - CURLOPT_CONNECTTIMEOUT_MS (3)
11 - CURLOPT_LOW_SPEED_LIMIT (3)
12 - CURLOPT_TIMEOUT (3)
13Added-in: 7.59.0
14---
16# NAME
18CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS - timing of connect attempts
20# SYNOPSIS
22~~~c
23#include <curl/curl.h>
25CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS,
26 long timeout);
27~~~
29# DESCRIPTION
31Happy eyeballs is an algorithm that controls connecting to a host that
32resolves to more than one IP address. A common setup is to expose an
33IPv4 and IPv6 address (dual-stack). Other host offer a range of addresses
34for one or both stacks.
36## IP Addresses
38When curl is built with IPv6 support, it attempts to connect to IPv6
39first, when available. When that fails, another connect attempt for
40the first IPv4 address (again, if available) is started. Should that
41fail, the next IPv6 address is used, then the next IPv4, etc. If there
42are only addresses for one stack, those are tried one after the other.
44When there is neither a positive nor negative response to an attempt,
45another attempt is started after *timeout* has passed. Then another,
46after *timeout* has passed again. As long as there are addresses available.
48When all addresses have been tried and failed, the transfer fails.
49All attempts are aborted after CURLOPT_CONNECTTIMEOUT_MS(3) has
50passed, counted from the first attempt onward.
52The range of suggested useful values for *timeout* is limited. Happy
53Eyeballs RFC 6555 says "It is RECOMMENDED that connection attempts be paced
54150-250 ms apart to balance human factors against network load." libcurl
55currently defaults to 200 ms. Firefox and Chrome currently default to 300 ms.
57As an example, for a host that resolves to 'a1_v4, a2_v4, a3_v6, a4_v6'
58curl opens a socket to 'a3_v6' first. When that does not report back,
59it opens another socket to 'a1_v4' after 200ms. The first socket is
60left open and might still succeed. When 200ms have gone by again, a
61socket for 'a4_v6' is opened. 200ms later, 'a2_v4' is tried.
63At this point, there are 4 sockets open (unless the network has reported
64anything back). That took 3 times the happy eyeballs timeout, so 600ms
65in the default setting. When any of those four report a success, that
66socket is used for the transfer and the other three are closed.
68There is a limit on the number of sockets opened for connect attempts. When
69that limit is reached and more addresses are available, the oldest
70attempt is discarded. This limit is currently 6. With the default
71happy eyeballs timeout of 200ms, this closes attempts after 1.2 seconds
72*as long as there are more addresses to try*.
74There are situations where connect attempts fail, but the failure is
75considered being inconclusive. The QUIC protocol may encounter this.
76When a QUIC server restarts, it may send replies indicating that it
77is not accepting new connections right now, but maybe later.
79Such "inclusive" connect attempt failures cause a restart of
80the attempt, with the same address on a new socket, closing the
81previous one. Repeatedly until CURLOPT_CONNECTTIMEOUT_MS(3) strikes.
83## HTTPS
85When connection with the HTTPS protocol to a host that may talk HTTP/3,
86HTTP/2 or HTTP/1.1, curl applies a similar happy eyeballs strategy when
87attempting these versions.
89When HTTPS only involves a TCP connection, the versions are negotiated
90via ALPN, the TLS extension, in a single connect. Since HTTP/3 runs on
91QUIC (which runs on UDP), it requires a separate connect attempt.
93The HTTP/3 attempt is started first and, after *timeout* expires, the
94HTTP/2 (or 1.1) attempt is started in parallel.
96# DEFAULT
98CURL_HET_DEFAULT (currently defined as 200L)
100# %PROTOCOLS%
102# EXAMPLE
104~~~c
105int main(void)
107 CURL *curl = curl_easy_init();
108 if(curl) {
109 CURLcode result;
110 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
112 /* Set the timeout to 300 milliseconds */
113 curl_easy_setopt(curl, CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS, 300L);
115 result = curl_easy_perform(curl);
117 /* always cleanup */
118 curl_easy_cleanup(curl);
119 }
121~~~
123# %AVAILABILITY%
125# RETURN VALUE
127curl_easy_setopt(3) returns a CURLcode indicating success or error.
129CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
130libcurl-errors(3).
Diagnostics4 git calls · 361 ms
CallStatusSizeTime0361 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit2 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=2
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=356
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2002.1 KiB356 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=2159
git.response.cache=MISS
git.response.duration_ms=356
git.fetch.wants=9136021c3aa845322d96e92c1eaac6916a1abc00
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2159
git.pkt.payload.max=2138
git.sideband.band1.bytes=2137
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e333a6de79f485
Request
5398a710…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format