libcurl-ws.3. WebSocket API overview

Closes #11314

diff --git a/.github/scripts/cleanspell.pl b/.github/scripts/cleanspell.pl
index a7f19c56285608712f250b09544b11ae439a4ab9..3e4b9ece9e082abde42b06a63ade7dd12c55a4d6 100755 (executable)
--- a/.github/scripts/cleanspell.pl
+++ b/.github/scripts/cleanspell.pl
@@ -70,7 +70,7 @@ while(<F>) {
         $_ =~ 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 d25f94f4dcc27cea7e64eff5dd7a37d09ea1efca..35122e72798394d51e3a323da78269f0350d765e 100644 (file)
--- 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 (file)
index 0000000..9cc5bdb
--- /dev/null
+++ b/docs/libcurl/libcurl-ws.3
@@ -0,0 +1,103 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, 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 <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.
+
+.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)"