From: Daniel Stenberg Date: Wed, 14 Jun 2023 08:57:50 +0000 (+0200) Subject: libcurl-ws.3. WebSocket API overview X-Git-Tag: curl-8_2_0~95 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=43372423451274e6ac3ea2b792d2b3b8b01f90dd;p=thirdparty%2Fcurl.git libcurl-ws.3. WebSocket API overview Closes #11314 --- diff --git a/.github/scripts/cleanspell.pl b/.github/scripts/cleanspell.pl index a7f19c5628..3e4b9ece9e 100755 --- a/.github/scripts/cleanspell.pl +++ b/.github/scripts/cleanspell.pl @@ -70,7 +70,7 @@ while() { $_ =~ s/curl_ws_(send|recv|meta)//g; $_ =~ s/curl_url_(dup)//g; $_ =~ s/curl_pushheader_by(name|num)//g; - $_ =~ s/libcurl-env//g; + $_ =~ s/libcurl-(env|ws)//g; $_ =~ s/(^|\W)((tftp|https|http|ftp):\/\/[a-z0-9\-._~%:\/?\#\[\]\@!\$&'()*+,;=]+)//gi; print O $_; } diff --git a/docs/libcurl/Makefile.inc b/docs/libcurl/Makefile.inc index d25f94f4dc..35122e7279 100644 --- a/docs/libcurl/Makefile.inc +++ b/docs/libcurl/Makefile.inc @@ -117,4 +117,5 @@ man_MANS = \ libcurl-thread.3 \ libcurl-tutorial.3 \ libcurl-url.3 \ + libcurl-ws.3 \ libcurl.3 diff --git a/docs/libcurl/libcurl-ws.3 b/docs/libcurl/libcurl-ws.3 new file mode 100644 index 0000000000..9cc5bdb47b --- /dev/null +++ b/docs/libcurl/libcurl-ws.3 @@ -0,0 +1,103 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" * SPDX-License-Identifier: curl +.\" * +.\" ************************************************************************** +.TH libcurl 3 "10 Sep 2018" "libcurl" "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 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. + +.SH MESSAGES +WebSocket communication is message based. That means that is sends and +receives entire messages, not streams like TCP. A WebSocket message is sent +over the wire in one or more frames. Each frame in a message can have a size +up to 2^63 bytes. + +libcurl delivers WebSocket data as frame fragments. It might send a whole +frame, but it might also deliver them in pieces depending on size and network +patterns. It makes sure to provide the API user about the exact specifics +about the fragment: type, offset, size and how much data there is pending to +arrive for the same frame. + +A message has an unknown size until the last frame header for the message has +been received since only frames have set sizes. +.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. + +libcurl automatically responds to server PING messages with a PONG. It does +not send any PING messages automatically. +.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. Using a write callback with \fICURLOPT_WRITEFUNCTION(3)\fP much like other +downloads for when the traffic is download oriented. + +2. Using \fICURLOPT_CONNECT_ONLY(3)\fP and use the WebSocket recv/send +functions at will. +.SH "Callback model" +When a write callback is set and a WebSocket transfer is performed, the +callback will be called to deliver all WebSocket data that arrives. + +The callback can then call \fIcurl_ws_meta(3)\fP to learn about the details of +the incoming data fragment. +.SH "CONNECT_ONLY model" +By setting \fICURLOPT_CONNECT_ONLY(3)\fP to \fB2L\fP, the transfer will only +establish and setup the WebSocket communication and then return control back +to the application. + +Once such a setup has been successfully performed, the application can proceed +and use \fIcurl_ws_recv(3)\fP and \fIcurl_ws_send(3)\fP freely to exchange +WebSocket messages with the server. +.SH AVAILABILITY +The WebSocket API was introduced as experimental in 7.86.0 and is still +experimental today. + +It is only built-in if explicitly opted in at build time. We discourage use of +the WebSocket API in production because of its experimental state. We might +change API, ABI and behavior before this "goes live". +.SH "SEE ALSO" +.BR curl_ws_meta "(3), " curl_ws_recv "(3), " curl_ws_send "(3), " +.BR curl_easy_init "(3), " CURLOPT_CONNECT_ONLY "(3), " +.BR CURLOPT_WRITEFUNCTION "(3)"