Skip to content

websocket.md

Latest commit

 

History

History
177 lines (127 loc) · 5.97 KB

websocket.md

File metadata and controls

177 lines (127 loc) · 5.97 KB
Raw

WebSocket

fetch supports WebSocket connections for real-time bidirectional communication.

Basic Usage

Connect using ws:// or wss:// URL schemes:

fetch ws://echo.websocket.events
fetch wss://echo.websocket.events

Sending Messages

Initial Message

Use -d or -j to send a single message on connect:

fetch ws://echo.websocket.events -d "hello"
fetch ws://echo.websocket.events -j '{"type": "subscribe", "channel": "updates"}'

By default, outgoing messages are sent as text when the payload is valid UTF-8 and as binary when it is not. Use --ws-message-mode text|binary|auto to force the frame type:

fetch ws://api.example.com/upload -d @payload.bin --ws-message-mode binary

Piped Input

Pipe lines from stdin. fetch sends each line as a separate text message. It also sends empty lines:

echo "hello" | fetch ws://echo.websocket.events
printf "msg1\nmsg2\n" | fetch ws://echo.websocket.events

fetch connects before it reads piped input. It streams each line as the line arrives. After stdin reaches EOF, it prints server messages until the server closes the connection.

With --ws-message-mode auto, piped input is still line-delimited, but a line that is not valid UTF-8 is sent as a binary message. With --ws-message-mode binary, piped input is streamed as raw byte chunks and newline bytes are preserved.

Text and auto stdin modes cap each line at 16 MiB before a newline. Use --ws-message-mode binary for larger messages or raw byte streams without line delimiters.

If stdin, stdout, and stderr are terminals, fetch opens an interactive prompt. Type a message and press Enter to send it. Press Ctrl+C or Ctrl+D to exit. Prompt input is capped at 16 MiB. Interactive history is byte-bounded, so old messages are evicted rather than allowing server traffic to grow memory without limit.

Control this behavior with --ws-interactive:

# Automatically use the prompt when attached to a terminal
fetch ws://api.example.com/stream --ws-interactive auto

# Require the prompt, failing if stdio is not a terminal
fetch ws://api.example.com/stream --ws-interactive on

# Disable the prompt and stream server messages to stdout
fetch ws://api.example.com/stream --ws-interactive off

Output

  • Text messages: fetch writes text messages to stdout. On a terminal, it automatically formats JSON messages.
  • Binary messages: fetch writes raw bytes if stdout is redirected or piped. It never writes binary frames directly to a terminal and gives a warning instead.
  • Terminal safety: Unformatted server text is escaped before terminal output so control sequences cannot be interpreted by the terminal.
  • Formatting: Use --format on to force JSON formatting, or --format off to disable it.

Incoming server frames and assembled messages are capped at 16 MiB. Larger messages fail with a WebSocket message size diagnostic instead of being printed.

# Force JSON formatting
fetch ws://api.example.com/stream --format on

# Disable formatting
fetch ws://api.example.com/stream --format off

Verbose Output

Use -v flags to see connection details:

# Show response status and headers
fetch -v ws://echo.websocket.events -d "hello"

# Show request and response headers with prefixes
fetch -vv ws://echo.websocket.events -d "hello"

Sensitive handshake headers such as Authorization, Cookie, Set-Cookie, Proxy-Authorization, and AWS session tokens are redacted in verbose and --dry-run output.

Authentication

Header-based authentication options work with WebSocket connections. fetch sends the headers during the HTTP upgrade handshake. It converts URL credentials to a Basic Authorization header and removes them from the handshake URL.

WebSocket requests do not support Digest authentication (--digest). Digest authentication requires a challenge and a retry before the upgrade completes.

fetch --bearer mytoken ws://api.example.com/ws
fetch --basic user:pass ws://api.example.com/ws
fetch ws://user:pass@api.example.com/ws
fetch -H "Authorization: Bearer mytoken" ws://api.example.com/ws

Subprotocols

Specify WebSocket subprotocols with the Sec-WebSocket-Protocol header:

fetch -H "Sec-WebSocket-Protocol: graphql-ws" wss://api.example.com/graphql

Network Options

WebSocket connections honor --dns-server for direct TCP connections and for local target resolution through plain socks5:// proxies. Use socks5h:// to make the SOCKS proxy resolve the target hostname.

When --proxy is absent, WebSocket dialing uses the same environment and system proxy selection as HTTP, including HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY. ws:// uses HTTP proxy selection and wss:// uses HTTPS proxy selection.

Timeout

The --timeout flag applies to connection setup, the WebSocket handshake, and materializing an initial -d/-j message. The established connection stays open until the server closes or stdin EOF:

fetch --timeout 5 ws://api.example.com/ws

Use --connect-timeout to limit WebSocket connection setup. The limit applies to custom DNS resolution, the TCP connection, proxy CONNECT or SOCKS negotiation, and TLS handshakes. If both timeout flags are set, the remaining --timeout value limits the connect timeout:

fetch --connect-timeout 2 --timeout 10 wss://api.example.com/ws

Limitations

  • WebSocket requires HTTP/1.1 for the upgrade handshake. Using --http 2 or --http 3 with WebSocket is not supported.
  • WebSocket (ws:// / wss://) cannot be combined with HTTP/gRPC-only options, including --grpc, protobuf schema flags, --form, --multipart, --xml, --edit, --unix, redirects, ranges, compression/content-encoding options, image/status handling, output-file/clipboard flags, or retry flags.
  • The pager is disabled for WebSocket output; explicitly setting --pager produces a warning.

See Also