1--- 2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al. 3SPDX-License-Identifier: curl 4Title: libcurl 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) 15--- 16 17# NAME 18 19libcurl-ws - WebSocket interface overview 20 21# DESCRIPTION 22 23The WebSocket interface provides functions for receiving and sending WebSocket 24data. 25 26# INCLUDE 27 28You still only include <curl/curl.h> in your code. 29 30# SETUP 31 32WebSocket is also often known as *WebSockets*, in plural. It is done by 33upgrading a regular HTTP(S) GET request to a WebSocket connection. 34 35WebSocket is a TCP-like message-based communication protocol done over HTTP, 36specified in RFC 6455. 37 38To initiate a WebSocket session with libcurl, setup an easy handle to use a 39URL with a "WS://" or "WSS://" scheme. "WS" is for cleartext communication 40over HTTP and "WSS" is for doing WebSocket securely over HTTPS. 41 42A WebSocket request is done as an HTTP/1 GET request with an "Upgrade 43WebSocket" request header field. When the upgrade is accepted by the server, 44it responds with a 101 Switching and then the client can speak WebSocket with 45the server. The communication can happen in both directions at the same time. 46 47# MESSAGES 48 49WebSocket communication is message based. That means that both ends send and 50receive entire messages, not streams like TCP. A WebSocket message is sent 51over the wire in one or more frames. Each frame in a message can have a size 52up to 2^63 bytes. 53 54libcurl delivers WebSocket data as frame fragments. It might send a whole 55frame, but it might also deliver them in pieces depending on size and network 56patterns. It makes sure to provide the API user about the exact specifics 57about the fragment: type, offset, size and how much data there is pending to 58arrive for the same frame. 59 60A message has an unknown size until the last frame header for the message has 61been received since only frames have set sizes. 62 63# Raw mode 64 65libcurl can be told to speak WebSocket in "raw mode" by setting the 66**CURLWS_RAW_MODE** bit to the CURLOPT_WS_OPTIONS(3) option. 67 68Raw WebSocket means that libcurl passes on the data from the network without 69parsing it leaving that entirely to the application. This mode assumes that 70the user of this knows WebSocket and can parse and figure out the data all by 71itself. 72 73This mode is intended for applications that already have a WebSocket 74parser/engine that want to switch over to use libcurl for enabling WebSocket, 75and keep parts of the existing software architecture. 76 77# PING 78 79WebSocket is designed to allow long-lived sessions and in order to keep the 80connections alive, both ends can send PING messages for the other end to 81respond with a PONG. 82 83libcurl automatically responds to server PING messages with a PONG. It does 84not send any PING messages automatically. 85 86# MODELS 87 88Because of the many different ways WebSocket can be used, which is much more 89flexible than limited to plain downloads or uploads, libcurl offers two 90different API models to use it: 91 921. Using a write callback with CURLOPT_WRITEFUNCTION(3) much like other 93downloads for when the traffic is download oriented. 94 952. Using CURLOPT_CONNECT_ONLY(3) and use the WebSocket recv/send 96functions. 97 98# Callback model 99 100When a write callback is set and a WebSocket transfer is performed, the 101callback is called to deliver all WebSocket data that arrives. 102 103The callback can then call curl_ws_meta(3) to learn about the details of 104the incoming data fragment. 105 106# CONNECT_ONLY model 107 108By setting CURLOPT_CONNECT_ONLY(3) to **2L**, the transfer only 109establishes and setups the WebSocket communication and then returns control 110back to the application. 111 112Once such a setup has been successfully performed, the application can proceed 113and use curl_ws_recv(3) and curl_ws_send(3) freely to exchange 114WebSocket messages with the server. 115 116# AVAILABILITY 117 118The WebSocket API was introduced as experimental in 7.86.0 and is still 119experimental today. 120 121It is only built-in if explicitly opted in at build time. We discourage use of 122the WebSocket API in production because of its experimental state. We might 123change API, ABI and behavior before this "goes live". 124