Artifactspublic-v0

curl

master
ply4 git calls170 ms289 KiB2 cachedprotocol v2
120 lines3.8 KiBRaw

NAME

CURLOPT_CONNECT_TO - connect to another host and port instead

SYNOPSIS

c
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECT_TO,
                          struct curl_slist *connect_to);

DESCRIPTION

Pass a pointer to a linked list of strings with "connect to" information to use for establishing network connections with this handle. The linked list should be a fully valid list of struct curl_slist structs properly filled in. Use curl_slist_append(3) to create the list and curl_slist_free_all(3) to clean up an entire list.

Each single string should be written using the format HOST:PORT:CONNECT-TO-HOST:CONNECT-TO-PORT where HOST is the host of the request, PORT is the port of the request, CONNECT-TO-HOST is the hostname to connect to, and CONNECT-TO-PORT is the port to connect to.

The first string that matches the request's host and port is used.

Dotted numerical IP addresses are supported for HOST and CONNECT-TO-HOST. A numerical IPv6 address must be written within [brackets].

Any of the four values may be empty. When the HOST or PORT is empty, the host or port always match (the request's host or port is ignored). When CONNECT-TO-HOST or CONNECT-TO-PORT is empty, the "connect to" feature is disabled for the host or port, and the request's host or port are used to establish the network connection.

This option is suitable to direct the request at a specific server, e.g. at a specific cluster node in a cluster of servers.

The "connect to" host and port are only used to establish the network connection. They do NOT affect the host and port that are used for TLS/SSL (e.g. SNI, certificate verification) or for the application protocols.

In contrast to CURLOPT_RESOLVE(3), the option CURLOPT_CONNECT_TO(3) does not pre-populate the DNS cache and therefore it does not affect future transfers of other easy handles that have been added to the same multi handle.

The "connect to" host and port are ignored if they are equal to the host and the port in the request URL, because connecting to the host and the port in the request URL is the default behavior.

If an HTTP proxy is used for a request having a special "connect to" host or port, and the "connect to" host or port differs from the request's host and port, the HTTP proxy is automatically switched to tunnel mode for this specific request. This is necessary because it is not possible to connect to a specific host or port in normal (non-tunnel) mode.

When this option is passed to curl_easy_setopt(3), libcurl does not copy the list so you must keep it around until you no longer use this handle for a transfer before you call curl_slist_free_all(3) on the list.

Using this option multiple times makes the last set list override the previous ones. Set it to NULL to disable its use again.

DEFAULT

NULL

%PROTOCOLS%

EXAMPLE

c
int main(void)
{
  CURL *curl;
  struct curl_slist *connect_to = NULL;
  connect_to = curl_slist_append(NULL, "example.com::server1.example.com:");

  curl = curl_easy_init();
  if(curl) {
    CURLcode result;
    curl_easy_setopt(curl, CURLOPT_CONNECT_TO, connect_to);
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");

    result = curl_easy_perform(curl);

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

  curl_slist_free_all(connect_to);
}

%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_CONNECT_TO
5Section: 3
6Source: libcurl
7See-also:
8 - CURLOPT_FOLLOWLOCATION (3)
9 - CURLOPT_HTTPPROXYTUNNEL (3)
10 - CURLOPT_RESOLVE (3)
11 - CURLOPT_URL (3)
12Protocol:
13 - All
14Added-in: 7.49.0
15---
17# NAME
19CURLOPT_CONNECT_TO - connect to another host and port instead
21# SYNOPSIS
23~~~c
24#include <curl/curl.h>
26CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECT_TO,
27 struct curl_slist *connect_to);
28~~~
30# DESCRIPTION
32Pass a pointer to a linked list of strings with "connect to" information to
33use for establishing network connections with this handle. The linked list
34should be a fully valid list of **struct curl_slist** structs properly filled
35in. Use curl_slist_append(3) to create the list and curl_slist_free_all(3) to
36clean up an entire list.
38Each single string should be written using the format
39HOST:PORT:CONNECT-TO-HOST:CONNECT-TO-PORT where HOST is the host of the
40request, PORT is the port of the request, CONNECT-TO-HOST is the hostname to
41connect to, and CONNECT-TO-PORT is the port to connect to.
43The first string that matches the request's host and port is used.
45Dotted numerical IP addresses are supported for HOST and CONNECT-TO-HOST.
46A numerical IPv6 address must be written within [brackets].
48Any of the four values may be empty. When the HOST or PORT is empty, the host
49or port always match (the request's host or port is ignored). When
50CONNECT-TO-HOST or CONNECT-TO-PORT is empty, the "connect to" feature is
51disabled for the host or port, and the request's host or port are used to
52establish the network connection.
54This option is suitable to direct the request at a specific server, e.g. at a
55specific cluster node in a cluster of servers.
57The "connect to" host and port are only used to establish the network
58connection. They do NOT affect the host and port that are used for TLS/SSL
59(e.g. SNI, certificate verification) or for the application protocols.
61In contrast to CURLOPT_RESOLVE(3), the option CURLOPT_CONNECT_TO(3) does not
62pre-populate the DNS cache and therefore it does not affect future transfers
63of other easy handles that have been added to the same multi handle.
65The "connect to" host and port are ignored if they are equal to the host and
66the port in the request URL, because connecting to the host and the port in
67the request URL is the default behavior.
69If an HTTP proxy is used for a request having a special "connect to" host or
70port, and the "connect to" host or port differs from the request's host and
71port, the HTTP proxy is automatically switched to tunnel mode for this
72specific request. This is necessary because it is not possible to connect to a
73specific host or port in normal (non-tunnel) mode.
75When this option is passed to curl_easy_setopt(3), libcurl does not copy the
76list so you **must** keep it around until you no longer use this *handle* for
77a transfer before you call curl_slist_free_all(3) on the list.
79Using this option multiple times makes the last set list override the previous
80ones. Set it to NULL to disable its use again.
82# DEFAULT
84NULL
86# %PROTOCOLS%
88# EXAMPLE
90~~~c
91int main(void)
93 CURL *curl;
94 struct curl_slist *connect_to = NULL;
95 connect_to = curl_slist_append(NULL, "example.com::server1.example.com:");
97 curl = curl_easy_init();
98 if(curl) {
99 CURLcode result;
100 curl_easy_setopt(curl, CURLOPT_CONNECT_TO, connect_to);
101 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
103 result = curl_easy_perform(curl);
105 /* always cleanup */
106 curl_easy_cleanup(curl);
107 }
109 curl_slist_free_all(connect_to);
111~~~
113# %AVAILABILITY%
115# RETURN VALUE
117curl_easy_setopt(3) returns a CURLcode indicating success or error.
119CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
120libcurl-errors(3).
Diagnostics4 git calls · 170 ms
CallStatusSizeTime0170 ms
discover200152 B2 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 · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=165
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=3
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
fetch2001.8 KiB165 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=1817
git.response.cache=MISS
git.response.duration_ms=165
git.fetch.wants=68bc1b6ad4261df6dcf00588a9dbf2b8e899197e
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=1817
git.pkt.payload.max=1796
git.sideband.band1.bytes=1795
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
a5e323c189c55aae
Request
8505b7f9…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format