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