Artifactspublic-v0

curl

master
ply4 git calls199 ms290 KiB2 cachedprotocol v2
154 lines6.0 KiBRaw

NAME

libcurl-ws - WebSocket interface overview

DESCRIPTION

The WebSocket interface provides functions for receiving and sending WebSocket data.

INCLUDE

You still only include <curl/curl.h> in your code.

SETUP

WebSocket is also often known as WebSockets, in plural. It is done by upgrading a regular HTTP(S) GET request to a WebSocket connection.

WebSocket is a TCP-like message-based communication protocol done over HTTP, specified in RFC 6455.

To initiate a WebSocket session with libcurl, setup an easy handle to use a URL with a ws:// or wss:// scheme. "WS" is for cleartext communication over HTTP and "WSS" is for doing WebSocket securely over HTTPS.

A WebSocket request is done as an HTTP/1 GET request with an "Upgrade WebSocket" request header field. When the upgrade is accepted by the server, it responds with a 101 Switching and then the client can speak WebSocket with the server. The communication can happen in both directions at the same time.

EXTENSIONS

The WebSocket protocol allows the client to request and negotiate extensions can add additional features and restrictions to the protocol.

libcurl does not support the use of extensions and always sets up a connection without them.

MESSAGES

WebSocket communication is message based. That means that both ends send and receive entire messages, not streams like TCP. A WebSocket message is sent over the wire in one or more frames. A message which is split into several frames is referred to as a fragmented message and the individual frames are called fragments. Each frame (or fragment) in a message can have a size of up to 2^63 bytes and declares the frame size in the header. The total size of a message that is fragmented into multiple frames is not limited by the protocol and the number of fragments is not known until the final fragment is received.

Transmission of a frame must not be interrupted by any other data transfers and transmission of the different fragments of a message must not be interrupted by other user data frames. Control frames - PING, PONG and CLOSE - may be transmitted in between any other two frames, even in between two fragments of the same user data message. The control frames themselves on the other hand must never be fragmented and are limited to a size of 125 bytes.

libcurl delivers WebSocket data as chunks of frames. It might deliver a whole frame as a single chunk, but it might also deliver it in several pieces depending on size and network patterns. See the individual API documentations for further information.

PING

WebSocket is designed to allow long-lived sessions and in order to keep the connections alive, both ends can send PING messages for the other end to respond with a PONG. Both ends may also send unsolicited PONG messages as unidirectional heartbeat.

libcurl automatically responds to server PING messages with a PONG that echoes the payload of the PING message. libcurl does neither send any PING messages nor any unsolicited PONG messages automatically. The automatic reply to PING messages can be disabled through CURLOPT_WS_OPTIONS(3).

MODELS

Because of the many different ways WebSocket can be used, which is much more flexible than limited to plain downloads or uploads, libcurl offers two different API models to use it:

  1. CURLOPT_WRITEFUNCTION/CURLOPT_READFUNCTION model: Using a write callback with CURLOPT_WRITEFUNCTION(3) much like other downloads for when the traffic is download oriented.

Using a read callback with CURLOPT_READFUNCTION(3) much like other uploads for sending WebSocket frames to the server.

  1. CURLOPT_CONNECT_ONLY model: Using curl_ws_recv(3) and curl_ws_send(3) functions.

CURLOPT_WRITEFUNCTION/CURLOPT_READFUNCTION MODEL

CURLOPT_CONNECT_ONLY(3) must be unset or 0L for this model to take effect.

curl_easy_perform(3) establishes and sets up the WebSocket communication and then blocks for the whole duration of the connection. libcurl calls the callback configured in CURLOPT_WRITEFUNCTION(3), whenever an incoming chunk of WebSocket data is received. The callback is handed a pointer to the payload data as an argument and can call curl_ws_meta(3) to get relevant metadata.

With libcurl 8.16.0 or later, sending of WebSocket frames via a CURLOPT_READFUNCTION(3) is supported. To use that on such a connection, register a callback via CURLOPT_READFUNCTION(3) and set CURLOPT_UPLOAD(3) as well. Once, the WebSocket connection is established, your callback is invoked to get data to send. That data is sent in a CURLWS_BINARY frame with length of exactly the data returned.

To send other frame types or longer frames, use curl_ws_start_frame(3) in the read callback. See the websocket-updown example.

When using curl_multi_perform(3) to drive transfers, more possibilities exist. The CURLOPT_READFUNCTION(3) may return CURL_READFUNC_PAUSE when it has no more data to send. Calling curl_easy_pause(3) afterwards resumes the upload and the read callback is invoked again.

CURLOPT_CONNECT_ONLY MODEL

CURLOPT_CONNECT_ONLY(3) must be 2L for this model to take effect.

curl_easy_perform(3) only establishes and sets up the WebSocket communication and then returns control back to the application. The application can then use curl_ws_recv(3) and curl_ws_send(3) to exchange WebSocket messages with the server.

RAW MODE

libcurl can be told to speak WebSocket in "raw mode" by setting the CURLWS_RAW_MODE bit of the CURLOPT_WS_OPTIONS(3) option.

Raw WebSocket means that libcurl passes on the data from the network without parsing it, leaving that entirely to the application.

This mode is intended for applications that already have a WebSocket parser/engine and want to switch over to use libcurl for enabling WebSocket, and keep parts of the existing software architecture.

1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: libcurl-ws
5Section: 3
6Source: libcurl
7See-also:
8 - CURLOPT_CONNECT_ONLY (3)
9 - CURLOPT_WRITEFUNCTION (3)
10 - CURLOPT_WS_OPTIONS (3)
11 - curl_easy_init (3)
12 - curl_ws_meta (3)
13 - curl_ws_recv (3)
14 - curl_ws_send (3)
15Protocol:
16 - All
17Added-in: 7.86.0
18---
20# NAME
22libcurl-ws - WebSocket interface overview
24# DESCRIPTION
26The WebSocket interface provides functions for receiving and sending WebSocket
27data.
29# INCLUDE
31You still only include \<curl/curl.h\> in your code.
33# SETUP
35WebSocket is also often known as *WebSockets*, in plural. It is done by
36upgrading a regular HTTP(S) GET request to a WebSocket connection.
38WebSocket is a TCP-like message-based communication protocol done over HTTP,
39specified in RFC 6455.
41To initiate a WebSocket session with libcurl, setup an easy handle to use a
42URL with a `ws://` or `wss://` scheme. "WS" is for cleartext communication
43over HTTP and "WSS" is for doing WebSocket securely over HTTPS.
45A WebSocket request is done as an HTTP/1 GET request with an "Upgrade
46WebSocket" request header field. When the upgrade is accepted by the server,
47it responds with a 101 Switching and then the client can speak WebSocket with
48the server. The communication can happen in both directions at the same time.
50# EXTENSIONS
52The WebSocket protocol allows the client to request and negotiate *extensions*
53can add additional features and restrictions to the protocol.
55libcurl does not support the use of extensions and always sets up a connection
56without them.
58# MESSAGES
60WebSocket communication is message based. That means that both ends send and
61receive entire messages, not streams like TCP. A WebSocket message is sent
62over the wire in one or more frames. A message which is split into several
63frames is referred to as a *fragmented* message and the individual frames are
64called *fragments*. Each frame (or fragment) in a message can have a size of
65up to 2^63 bytes and declares the frame size in the header. The total size of
66a message that is fragmented into multiple frames is not limited by the
67protocol and the number of fragments is not known until the final fragment is
68received.
70Transmission of a frame must not be interrupted by any other data transfers and
71transmission of the different fragments of a message must not be interrupted by
72other user data frames. Control frames - PING, PONG and CLOSE - may be
73transmitted in between any other two frames, even in between two fragments of
74the same user data message. The control frames themselves on the other hand
75must never be fragmented and are limited to a size of 125 bytes.
77libcurl delivers WebSocket data as chunks of frames. It might deliver a whole
78frame as a single chunk, but it might also deliver it in several pieces
79depending on size and network patterns. See the individual API documentations
80for further information.
82# PING
84WebSocket is designed to allow long-lived sessions and in order to keep the
85connections alive, both ends can send PING messages for the other end to
86respond with a PONG. Both ends may also send unsolicited PONG messages as
87unidirectional heartbeat.
89libcurl automatically responds to server PING messages with a PONG that echoes
90the payload of the PING message. libcurl does neither send any PING messages
91nor any unsolicited PONG messages automatically. The automatic reply to PING
92messages can be disabled through CURLOPT_WS_OPTIONS(3).
94# MODELS
96Because of the many different ways WebSocket can be used, which is much more
97flexible than limited to plain downloads or uploads, libcurl offers two
98different API models to use it:
1001. CURLOPT_WRITEFUNCTION/CURLOPT_READFUNCTION model:
101Using a write callback with CURLOPT_WRITEFUNCTION(3) much like other
102downloads for when the traffic is download oriented.
104Using a read callback with CURLOPT_READFUNCTION(3) much like other
105uploads for sending WebSocket frames to the server.
1072. CURLOPT_CONNECT_ONLY model:
108Using curl_ws_recv(3) and curl_ws_send(3) functions.
110## CURLOPT_WRITEFUNCTION/CURLOPT_READFUNCTION MODEL
112CURLOPT_CONNECT_ONLY(3) must be unset or **0L** for this model to take effect.
114curl_easy_perform(3) establishes and sets up the WebSocket communication and
115then blocks for the whole duration of the connection. libcurl calls the
116callback configured in CURLOPT_WRITEFUNCTION(3), whenever an incoming chunk
117of WebSocket data is received. The callback is handed a pointer to the payload
118data as an argument and can call curl_ws_meta(3) to get relevant metadata.
120With libcurl 8.16.0 or later, sending of WebSocket frames via a
121CURLOPT_READFUNCTION(3) is supported. To use that on such a connection,
122register a callback via CURLOPT_READFUNCTION(3) and set CURLOPT_UPLOAD(3)
123as well. Once, the WebSocket connection is established, your callback is
124invoked to get data to send. That data is sent in a *CURLWS_BINARY* frame with
125length of exactly the data returned.
127To send other frame types or longer frames, use curl_ws_start_frame(3)
128in the read callback. See the *websocket-updown* example.
130When using curl_multi_perform(3) to drive transfers, more possibilities
131exist. The CURLOPT_READFUNCTION(3) may return *CURL_READFUNC_PAUSE* when
132it has no more data to send. Calling curl_easy_pause(3) afterwards
133resumes the upload and the read callback is invoked again.
135## CURLOPT_CONNECT_ONLY MODEL
137CURLOPT_CONNECT_ONLY(3) must be **2L** for this model to take effect.
139curl_easy_perform(3) only establishes and sets up the WebSocket communication
140and then returns control back to the application. The application can then use
141curl_ws_recv(3) and curl_ws_send(3) to exchange WebSocket messages with the
142server.
144# RAW MODE
146libcurl can be told to speak WebSocket in "raw mode" by setting the
147**CURLWS_RAW_MODE** bit of the CURLOPT_WS_OPTIONS(3) option.
149Raw WebSocket means that libcurl passes on the data from the network without
150parsing it, leaving that entirely to the application.
152This mode is intended for applications that already have a WebSocket
153parser/engine and want to switch over to use libcurl for enabling WebSocket,
154and keep parts of the existing software architecture.
Diagnostics4 git calls · 199 ms
CallStatusSizeTime0199 ms
discover200152 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
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 · hit23 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=23
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.7 KiB174 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=174
git.response.bytes=2720
git.response.cache=MISS
git.response.duration_ms=174
git.fetch.wants=cce13abb243ffcf0ab2b98f9e465eb7d50fc2e9e
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=2720
git.pkt.payload.max=2699
git.sideband.band1.bytes=2698
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
a5e3571b69882c38
Request
f9fda00d…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format