laantungir/nostr_core_lib
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

un-nest curl

Browse Source
This commit is contained in:
Laan Tungir
2025-08-16 11:22:44 -04:00
parent 77186c88dd
commit 58cabadc44
5586 changed files with 310 additions and 310 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
curl-8.15.0/docs/libcurl/libcurl-ws.3 Normal file
View File

@@ -0,0 +1,106 @@
.\" generated by cd2nroff 0.1 from libcurl-ws.md
.TH libcurl-ws 3 "2025-08-14" libcurl
.SH NAME
libcurl\-ws \- WebSocket interface overview
.SH DESCRIPTION
The WebSocket interface provides functions for receiving and sending WebSocket
data.
.SH INCLUDE
You still only include <curl/curl.h> in your code.
.SH SETUP
WebSocket is also often known as \fIWebSockets\fP, 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.
.SH EXTENSIONS
The WebSocket protocol allows the client to request and negotiate \fIextensions\fP
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.
.SH 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 \fIfragmented\fP message and the individual frames are
called \fIfragments\fP. 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.
.SH 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 \fICURLOPT_WS_OPTIONS(3)\fP.
.SH 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 model:
Using a write callback with \fICURLOPT_WRITEFUNCTION(3)\fP much like other
downloads for when the traffic is download oriented.
2. CURLOPT_CONNECT_ONLY model:
Using \fIcurl_ws_recv(3)\fP and \fIcurl_ws_send(3)\fP functions.
.IP "CURLOPT_WRITEFUNCTION MODEL"
\fICURLOPT_CONNECT_ONLY(3)\fP must be unset or \fB0L\fP for this model to take effect.
\fIcurl_easy_perform(3)\fP establishes and sets up the WebSocket communication and
then blocks for the whole duration of the connection. libcurl calls the
callback configured in \fICURLOPT_WRITEFUNCTION(3)\fP, 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 \fIcurl_ws_meta(3)\fP to get relevant metadata.
.IP "CURLOPT_CONNECT_ONLY MODEL"
\fICURLOPT_CONNECT_ONLY(3)\fP must be \fB2L\fP for this model to take effect.
\fIcurl_easy_perform(3)\fP only establishes and sets up the WebSocket communication
and then returns control back to the application. The application can then use
\fIcurl_ws_recv(3)\fP and \fIcurl_ws_send(3)\fP to exchange WebSocket messages with the
server.
.SH RAW MODE
libcurl can be told to speak WebSocket in "raw mode" by setting the
\fBCURLWS_RAW_MODE\fP bit of the \fICURLOPT_WS_OPTIONS(3)\fP 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.
.SH SEE ALSO
.BR CURLOPT_CONNECT_ONLY (3),
.BR CURLOPT_WRITEFUNCTION (3),
.BR CURLOPT_WS_OPTIONS (3),
.BR curl_easy_init (3),
.BR curl_ws_meta (3),
.BR curl_ws_recv (3),
.BR curl_ws_send (3)