Artifactspublic-v0

curl

master
ply4 git calls176 ms289 KiB2 cachedprotocol v2
154 lines4.2 KiBRaw

NAME

CURLMOPT_PUSHFUNCTION - callback that approves or denies server pushes

SYNOPSIS

c
#include <curl/curl.h>

int curl_push_callback(CURL *parent,
                       CURL *easy,
                       size_t num_headers,
                       struct curl_pushheaders *headers,
                       void *clientp);

CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHFUNCTION,
                            curl_push_callback func);

DESCRIPTION

This callback gets called when a new HTTP/2 stream is being pushed by the server (using the PUSH_PROMISE frame). If no push callback is set, all offered pushes are denied automatically.

CALLBACK DESCRIPTION

The callback gets its arguments like this:

parent is the handle of the stream on which this push arrives. The new handle has the following options duplicated from the parent: CURLOPT_WRITEFUNCTION(3), CURLOPT_WRITEDATA(3), CURLOPT_HEADERFUNCTION(3), CURLOPT_HEADERDATA(3), CURLOPT_DEBUGFUNCTION(3), CURLOPT_DEBUGDATA(3), CURLOPT_PROGRESSFUNCTION(3), CURLOPT_XFERINFOFUNCTION(3), CURLOPT_PROGRESSDATA(3) and CURLOPT_XFERINFODATA(3).

It is then up to the application to alter/set any options if desired.

easy is a newly created handle that represents this upcoming transfer.

num_headers is the number of name+value pairs that was received and can be accessed

headers is a handle used to access push headers using the accessor functions described below. This only accesses and provides the PUSH_PROMISE headers, the normal response headers are provided in the header callback as usual.

clientp is the pointer set with CURLMOPT_PUSHDATA(3)

If the callback returns CURL_PUSH_OK, the new easy handle is added to the multi handle, the callback must not do that by itself.

The callback can access PUSH_PROMISE headers with two accessor functions. These functions can only be used from within this callback and they can only access the PUSH_PROMISE headers: curl_pushheader_byname(3) and curl_pushheader_bynum(3). The normal response headers are passed to the header callback for pushed streams like for normal streams.

The header fields can also be accessed with curl_easy_header(3), introduced in later libcurl versions.

CALLBACK RETURN VALUE

CURL_PUSH_OK (0)

The application has accepted the stream and it can now start receiving data, the ownership of the curl handle has been taken over by the application.

CURL_PUSH_DENY (1)

The callback denies the stream and no data reaches the application, the easy handle is destroyed by libcurl.

CURL_PUSH_ERROROUT (2)

Returning this code rejects the pushed stream and returns an error back on the parent stream making it get closed with an error. (Added in 7.72.0)

*

All other return codes are reserved for future use.

DEFAULT

NULL, no callback

%PROTOCOLS%

EXAMPLE

c
#include <string.h>

/* only allow pushes for filenames starting with "push-" */
static int push_callback(CURL *parent,
                         CURL *easy,
                         size_t num_headers,
                         struct curl_pushheaders *headers,
                         void *clientp)
{
  char *headp;
  int *transfers = (int *)clientp;
  FILE *out;
  headp = curl_pushheader_byname(headers, ":path");
  if(headp && !strncmp(headp, "/push-", 6)) {
    fprintf(stderr, "The PATH is %s\n", headp);

    /* save the push here */
    out = fopen("pushed-stream", "wb");

    /* write to this file */
    curl_easy_setopt(easy, CURLOPT_WRITEDATA, out);

    (*transfers)++; /* one more */

    return CURL_PUSH_OK;
  }
  return CURL_PUSH_DENY;
}

int main(void)
{
  int counter;
  CURLM *multi = curl_multi_init();
  curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback);
  curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter);
}

%AVAILABILITY%

RETURN VALUE

curl_multi_setopt(3) returns a CURLMcode indicating success or error.

CURLM_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: CURLMOPT_PUSHFUNCTION
5Section: 3
6Source: libcurl
7See-also:
8 - CURLMOPT_PIPELINING (3)
9 - CURLMOPT_PUSHDATA (3)
10 - CURLOPT_PIPEWAIT (3)
11 - RFC 7540
12Protocol:
13 - HTTP
14Added-in: 7.44.0
15---
17# NAME
19CURLMOPT_PUSHFUNCTION - callback that approves or denies server pushes
21# SYNOPSIS
23~~~c
24#include <curl/curl.h>
26int curl_push_callback(CURL *parent,
27 CURL *easy,
28 size_t num_headers,
29 struct curl_pushheaders *headers,
30 void *clientp);
32CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHFUNCTION,
33 curl_push_callback func);
34~~~
36# DESCRIPTION
38This callback gets called when a new HTTP/2 stream is being pushed by the
39server (using the PUSH_PROMISE frame). If no push callback is set, all offered
40pushes are denied automatically.
42# CALLBACK DESCRIPTION
44The callback gets its arguments like this:
46*parent* is the handle of the stream on which this push arrives. The new
47handle has the following options duplicated from the parent:
48CURLOPT_WRITEFUNCTION(3), CURLOPT_WRITEDATA(3), CURLOPT_HEADERFUNCTION(3),
49CURLOPT_HEADERDATA(3), CURLOPT_DEBUGFUNCTION(3), CURLOPT_DEBUGDATA(3),
50CURLOPT_PROGRESSFUNCTION(3), CURLOPT_XFERINFOFUNCTION(3),
51CURLOPT_PROGRESSDATA(3) and CURLOPT_XFERINFODATA(3).
53It is then up to the application to alter/set any options if desired.
55*easy* is a newly created handle that represents this upcoming transfer.
57*num_headers* is the number of name+value pairs that was received and can
58be accessed
60*headers* is a handle used to access push headers using the accessor
61functions described below. This only accesses and provides the PUSH_PROMISE
62headers, the normal response headers are provided in the header callback as
63usual.
65*clientp* is the pointer set with CURLMOPT_PUSHDATA(3)
67If the callback returns CURL_PUSH_OK, the new easy handle is added to the
68multi handle, the callback must not do that by itself.
70The callback can access PUSH_PROMISE headers with two accessor functions.
71These functions can only be used from within this callback and they can only
72access the PUSH_PROMISE headers: curl_pushheader_byname(3) and
73curl_pushheader_bynum(3). The normal response headers are passed to the header
74callback for pushed streams like for normal streams.
76The header fields can also be accessed with curl_easy_header(3),
77introduced in later libcurl versions.
79# CALLBACK RETURN VALUE
81## CURL_PUSH_OK (0)
83The application has accepted the stream and it can now start receiving data,
84the ownership of the curl handle has been taken over by the application.
86## CURL_PUSH_DENY (1)
88The callback denies the stream and no data reaches the application, the easy
89handle is destroyed by libcurl.
91## CURL_PUSH_ERROROUT (2)
93Returning this code rejects the pushed stream and returns an error back on the
94parent stream making it get closed with an error. (Added in 7.72.0)
96## *
98All other return codes are reserved for future use.
100# DEFAULT
102NULL, no callback
104# %PROTOCOLS%
106# EXAMPLE
108~~~c
109#include <string.h>
111/* only allow pushes for filenames starting with "push-" */
112static int push_callback(CURL *parent,
113 CURL *easy,
114 size_t num_headers,
115 struct curl_pushheaders *headers,
116 void *clientp)
118 char *headp;
119 int *transfers = (int *)clientp;
120 FILE *out;
121 headp = curl_pushheader_byname(headers, ":path");
122 if(headp && !strncmp(headp, "/push-", 6)) {
123 fprintf(stderr, "The PATH is %s\n", headp);
125 /* save the push here */
126 out = fopen("pushed-stream", "wb");
128 /* write to this file */
129 curl_easy_setopt(easy, CURLOPT_WRITEDATA, out);
131 (*transfers)++; /* one more */
133 return CURL_PUSH_OK;
134 }
135 return CURL_PUSH_DENY;
138int main(void)
140 int counter;
141 CURLM *multi = curl_multi_init();
142 curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback);
143 curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter);
145~~~
147# %AVAILABILITY%
149# RETURN VALUE
151curl_multi_setopt(3) returns a CURLMcode indicating success or error.
153CURLM_OK (0) means everything was OK, non-zero means an error occurred, see
154libcurl-errors(3).
Diagnostics4 git calls · 176 ms
CallStatusSizeTime0176 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 · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=3
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=170
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
fetch2001.9 KiB171 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=1943
git.response.cache=MISS
git.response.duration_ms=171
git.fetch.wants=c9b587d91960b23681bc196f17a7496e049948bc
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=1943
git.pkt.payload.max=1922
git.sideband.band1.bytes=1921
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
a5e342159b966e2a
Request
b034ab36…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format