From: Daniel Stenberg Date: Tue, 13 Sep 2022 07:17:53 +0000 (+0200) Subject: docs: use "WebSocket" in singular X-Git-Tag: curl-7_86_0~247 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=6a1bfbd11b4a51d5d80eb5873633e44b7e397d2f;p=thirdparty%2Fcurl.git docs: use "WebSocket" in singular This is how the RFC calls the protocol. Also rename the file in docs/ to WEBSOCKET.md in uppercase to match how we have done it for many other protocol docs in similar fashion. Add the WebSocket docs to the tarball. Closes #9496 --- diff --git a/docs/Makefile.am b/docs/Makefile.am index 0959ac5939..0d565796fa 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -91,7 +91,8 @@ EXTRA_DIST = \ TODO \ TheArtOfHttpScripting.md \ URL-SYNTAX.md \ - VERSIONS.md + VERSIONS.md \ + WEBSOCKET.md MAN2HTML= roffit $< >$@ diff --git a/docs/WebSockets.md b/docs/WEBSOCKET.md similarity index 68% rename from docs/WebSockets.md rename to docs/WEBSOCKET.md index 5e36e1aa75..dc6f1f2484 100644 --- a/docs/WebSockets.md +++ b/docs/WEBSOCKET.md @@ -4,36 +4,36 @@ Copyright (C) 2000 - 2022 Daniel Stenberg, , et al. SPDX-License-Identifier: curl --> -# WebSockets in curl +# WebSocket in curl ## API -The Websockets API is described in the individual man pages for the new API. +The WebSocket API is described in the individual man pages for the new API. -Websockets with libcurl can be done two ways. +WebSocket with libcurl can be done two ways. -1. Get the websockets frames from the server sent to the write callback. You +1. Get the WebSocket frames from the server sent to the write callback. You can then respond with `curl_ws_send()` from within the callback (or outside of it). -2. Set `CURLOPT_CONNECT_ONLY` to 2L (new for websockets), which makes libcurl +2. Set `CURLOPT_CONNECT_ONLY` to 2L (new for WebSocket), which makes libcurl do a HTTP GET + `Upgrade:` request plus response in the `curl_easy_perform()` call before it returns and then you can use - `curl_ws_recv()` and `curl_ws_send()` to receive and send websocket frames + `curl_ws_recv()` and `curl_ws_send()` to receive and send WebSocket frames from and to the server. The new options to `curl_easy_setopt()`: `CURLOPT_WS_OPTIONS` - to control specific behavior. `CURLWS_RAW_MODE` makes - libcurl provide all websocket traffic raw in the callback. + libcurl provide all WebSocket traffic raw in the callback. The new function calls: - `curl_ws_recv()` - receive a websockets frame + `curl_ws_recv()` - receive a WebSocket frame - `curl_ws_send()` - send a websockets frame + `curl_ws_send()` - send a WebSocket frame - `curl_ws_meta()` - return websockets metadata within a write callback + `curl_ws_meta()` - return WebSocket metadata within a write callback ## Max frame size @@ -55,20 +55,20 @@ since it failed to provide a WebSocket transfer. ## Test suite -I looked for an existing small WebSockets server implementation with maximum +I looked for an existing small WebSocket server implementation with maximum flexibility to dissect and cram into the test suite but I ended up deciding -that extending the existing test suite server sws to deal with WebSockets +that extending the existing test suite server sws to deal with WebSocket might be the better way. - This server is already integrated and working in the test suite - We want maximum control and ability to generate broken protocol and negative tests as well. A dumber and simpler TCP server could then be easier to - massage into this than a "proper" websockets server. + massage into this than a "proper" WebSocket server. -## Command line tool websockets +## Command line tool WebSocket -The plan is to make curl do websockets similar to telnet/nc. That part of the +The plan is to make curl do WebSocket similar to telnet/nc. That part of the work has not been started. Ideas: @@ -84,29 +84,29 @@ Ideas: ## Future work - Verify the Sec-WebSocket-Accept response. It requires a sha-1 function. -- Verify Sec-Websocket-Extensions and Sec-Websocket-Protocol in the response -- Make websockets work with hyper +- Verify Sec-WebSocket-Extensions and Sec-WebSocket-Protocol in the response +- Make WebSocket work with hyper - Consider a `curl_ws_poll()` -- Make sure Websockets code paths are fuzzed +- Make sure WebSocket code paths are fuzzed - Add client-side PING interval - Provide option to disable PING-PONG automation - Support compression (`CURLWS_COMPRESS`) -## Why not libwebsockets +## Why not libWebSocket -[libwebsockets](https://libwebsockets.org/) is said to be a solid, fast and -efficient WebSockets library with a vast amount of users. My plan was +[libWebSocket](https://libWebSocket.org/) is said to be a solid, fast and +efficient WebSocket library with a vast amount of users. My plan was originally to build upon it to skip having to implement the lowlevel parts of -WebSockets myself. +WebSocket myself. -Here are the reasons why I have decided to move forward with WebSockets in -curl **without using libwebsockets**: +Here are the reasons why I have decided to move forward with WebSocket in +curl **without using libWebSocket**: - doxygen generated docs only makes them very hard to navigate. No tutorial, no clearly written explanatory pages for specific functions. - seems (too) tightly integrated with a specific TLS library, while we want to - support websockets with whatever TLS library libcurl was already made to + support WebSocket with whatever TLS library libcurl was already made to work with. - seems (too) tightly integrated with event libraries @@ -117,5 +117,5 @@ curl **without using libwebsockets**: - "bloated" - it is a *huge* library that is actually more lines of code than libcurl itself -- websockets is a fairly simple protocol on the network/framing layer so +- WebSocket is a fairly simple protocol on the network/framing layer so making a homegrown handling of it should be fine diff --git a/docs/libcurl/curl_ws_meta.3 b/docs/libcurl/curl_ws_meta.3 index 4f3bc9cb77..8536702bda 100644 --- a/docs/libcurl/curl_ws_meta.3 +++ b/docs/libcurl/curl_ws_meta.3 @@ -24,7 +24,7 @@ .\" .TH curl_ws_meta 3 "12 Jun 2022" "libcurl 7.85.0" "libcurl Manual" .SH NAME -curl_ws_meta - meta data websocket information +curl_ws_meta - meta data WebSocket information .SH SYNOPSIS .nf #include @@ -44,7 +44,7 @@ received WebSocket traffic, \fIcurl_ws_meta(3)\fP can be called from within the callback to provide additional information about the data. This function only works from within the callback, and only when receiving -Websocket data. +WebSocket data. This function requires an easy handle as input argument for libcurl to know what transfer the question is about, but as there is no such pointer provided diff --git a/docs/libcurl/curl_ws_recv.3 b/docs/libcurl/curl_ws_recv.3 index 5315c56266..bdfcd26671 100644 --- a/docs/libcurl/curl_ws_recv.3 +++ b/docs/libcurl/curl_ws_recv.3 @@ -24,7 +24,7 @@ .\" .TH curl_ws_recv 3 "12 Jun 2022" "libcurl 7.85.0" "libcurl Manual" .SH NAME -curl_ws_recv - receive websocket data +curl_ws_recv - receive WebSocket data .SH SYNOPSIS .nf #include @@ -35,12 +35,12 @@ CURLcode curl_ws_recv(CURL *curl, void *buffer, size_t buflen, .SH DESCRIPTION This function call is EXPERIMENTAL. -Retrives as much as possible of a received WebSockets data fragment into the +Retrives as much as possible of a received WebSocket data fragment into the \fBbuffer\fP, but not more than \fBbuflen\fP bytes. The provide \fIrecvflags\fP argument gets bits set to help characterize the fragment. .SH RECVFLAGS .IP CURLWS_TEXT -The buffer contains text data. Note that this makes a difference to WebSockets +The buffer contains text data. Note that this makes a difference to WebSocket but libcurl itself will not make any verification of the content or precautions that you actually receive valid UTF-8 content. .IP CURLWS_BINARY diff --git a/docs/libcurl/curl_ws_send.3 b/docs/libcurl/curl_ws_send.3 index 89afc8582b..53147cfb1f 100644 --- a/docs/libcurl/curl_ws_send.3 +++ b/docs/libcurl/curl_ws_send.3 @@ -35,14 +35,14 @@ CURLcode curl_ws_send(CURL *curl, const void *buffer, size_t buflen, .SH DESCRIPTION This function call is EXPERIMENTAL. -Send the specific message fragment over the established websockets connection. +Send the specific message fragment over the established WebSocket connection. If \fBCURLWS_RAW_MODE\fP is enabled in \fICURLOPT_WS_OPTIONS(3)\fP, the \fBsendflags\fP argument should be set to 0. .SH SENDFLAGS .IP CURLWS_TEXT -The buffer contains text data. Note that this makes a difference to WebSockets +The buffer contains text data. Note that this makes a difference to WebSocket but libcurl itself will not make any verification of the content or precautions that you actually send valid UTF-8 content. .IP CURLWS_BINARY