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