Skip to content

Commit

Permalink
1.13.0, update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@vi
vi committed Mar 31, 2024
1 parent 84834f7 commit 06643a7
Show file tree
Hide file tree
Showing 5 changed files with 293 additions and 177 deletions.
5 changes: 3 additions & 2 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
<a name="unreleased"></a>
# Unreleased
<a name="v1.13.0"></a>
# [Happy eyeballs (v1.13.0)](https://github.com/vi/websocat/releases/tag/v1.13.0) - 31 Mar 2024

* `waitfordata:` overlay to delay connection initiation until first data is attempted to be written to it
* Dockerfile updates
* `lengthprefixed:` overlay - alternative to base64 mode
* Fix for #23 - "happy eyeballs" for ws:// and wss:// URLs.

<a name="v1.12.0"></a>
# [Maintainance release (v1.12.0)](https://github.com/vi/websocat/releases/tag/v1.12.0) - 17 Sep 2023
Expand Down
2 changes: 1 addition & 1 deletion Cargo.lock
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion Cargo.toml
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "websocat"
version = "1.12.0"
version = "1.13.0"
authors = ["Vitaly \"_Vi\" Shukela <[email protected]>"]
license = "MIT"
repository = "https://github.com/vi/websocat"
Expand Down
206 changes: 118 additions & 88 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@ There is a [list of all address types and overlays](doc.md).
<details><summary>`websocat --help=long` output</summary>

```
websocat 1.12.0
websocat 1.13.0
Vitaly "_Vi" Shukela <[email protected]>
Command-line client for web sockets, like netcat/curl/socat for ws://.
Expand All @@ -153,92 +153,118 @@ USAGE:
websocat [FLAGS] [OPTIONS] <addr1> <addr2> (advanced mode)
FLAGS:
--stdout-announce-listening-ports [A] Print a line to stdout for each port being listened
--async-stdio [A] On UNIX, set stdin and stdout to nonblocking mode instead of
spawning a thread. This should improve performance, but may break other
programs running on the same console.
--compress-deflate [A] Compress data coming to a WebSocket using deflate method. Affects
only binary WebSocket messages.
--compress-gzip [A] Compress data coming to a WebSocket using gzip method. Affects only
binary WebSocket messages.
--compress-zlib [A] Compress data coming to a WebSocket using zlib method. Affects only
binary WebSocket messages.
--crypto-reverse [A] Swap encryption and decryption operations in `crypto:` specifier -
encrypt on read, decrypto on write.
--dump-spec [A] Instead of running, dump the specifiers representation to stdout
-e, --set-environment Set WEBSOCAT_* environment variables when doing exec:/cmd:/sh-c:
Currently it's WEBSOCAT_URI and WEBSOCAT_CLIENT for
request URI and client address (if TCP)
Beware of ShellShock or similar security problems.
-E, --exit-on-eof Close a data transfer direction if the other one reached EOF
--foreachmsg-wait-read [A] Wait for reading to finish before closing foreachmsg:'s peer
--jsonrpc Format messages you type as JSON RPC 2.0 method calls. First word
becomes method name, the rest becomes parameters, possibly automatically
wrapped in [].
--jsonrpc-omit-jsonrpc [A] Omit `jsonrpc` field when using `--jsonrpc`, e.g. for Chromium
--just-generate-key [A] Just a Sec-WebSocket-Key value without running main Websocat
--linemode-strip-newlines [A] Don't include trailing \n or \r\n coming from streams in WebSocket
messages
-0, --null-terminated Use \0 instead of \n for linemode
--no-line [A] Don't automatically insert line-to-message transformation
--no-exit-on-zeromsg [A] Don't exit when encountered a zero message. Zero messages are used
internally in Websocat, so it may fail to close connection at all.
--no-fixups [A] Don't perform automatic command-line fixups. May destabilize
websocat operation. Use --dump-spec without --no-fixups to discover what
is being inserted automatically and read the full manual about Websocat
internal workings.
--no-async-stdio [A] Inhibit using stdin/stdout in a nonblocking way if it is not a tty
-1, --one-message Send and/or receive only one message. Use with --no-close and/or -u/-U.
--oneshot Serve only once. Not to be confused with -1 (--one-message)
--print-ping-rtts Print measured round-trip-time to stderr after each received WebSocket
pong.
--exec-exit-on-disconnect [A] Make exec: or sh-c: or cmd: immediately exit when connection is
closed, don't wait for termination.
--exec-sighup-on-stdin-close [A] Make exec: or sh-c: or cmd: send SIGHUP on UNIX when input is
closed.
--exec-sighup-on-zero-msg [A] Make exec: or sh-c: or cmd: send SIGHUP on UNIX when facing incoming
zero-length message.
-q Suppress all diagnostic messages, except of startup errors
--reuser-send-zero-msg-on-disconnect [A] Make reuse-raw: send a zero-length message to the peer when some
clients disconnects.
-s, --server-mode Simple server mode: specify TCP port or addr:port as single argument
-S, --strict strict line/message mode: drop too long messages instead of splitting
them, drop incomplete lines.
--timestamp-monotonic [A] Use monotonic clock for `timestamp:` overlay
-k, --insecure Accept invalid certificates and hostnames while connecting to TLS
--udp-broadcast [A] Set SO_BROADCAST
--udp-multicast-loop [A] Set IP[V6]_MULTICAST_LOOP
--udp-oneshot [A] udp-listen: replies only one packet per client
--udp-reuseaddr [A] Set SO_REUSEADDR for UDP socket. Listening TCP sockets are always
reuseaddr.
--uncompress-deflate [A] Uncompress data coming from a WebSocket using deflate method.
Affects only binary WebSocket messages.
--uncompress-gzip [A] Uncompress data coming from a WebSocket using deflate method.
Affects only binary WebSocket messages.
--uncompress-zlib [A] Uncompress data coming from a WebSocket using deflate method.
Affects only binary WebSocket messages.
-u, --unidirectional Inhibit copying data in one direction
-U, --unidirectional-reverse Inhibit copying data in the other direction (or maybe in both directions
if combined with -u)
--accept-from-fd [A] Do not call `socket(2)` in UNIX socket listener peer, start with
`accept(2)` using specified file descriptor number as argument instead
of filename
--unlink [A] Unlink listening UNIX socket before binding to it
-V, --version Prints version information
-v Increase verbosity level to info or further
-b, --binary Send message to WebSockets as binary messages
-n, --no-close Don't send Close message to websocket on EOF
--websocket-ignore-zeromsg [A] Silently drop incoming zero-length WebSocket messages. They may
cause connection close due to usage of zero-len message as EOF flag
inside Websocat.
-t, --text Send message to WebSockets as text messages
--base64 Encode incoming binary WebSocket messages in one-line Base64 If
`--binary-prefix` (see `--help=full`) is set, outgoing WebSocket
messages that start with the prefix are decoded from base64 prior to
sending.
--base64-text [A] Encode incoming text WebSocket messages in one-line Base64. I don't
know whether it can be ever useful, but it's for symmetry with
`--base64`.
--stdout-announce-listening-ports [A] Print a line to stdout for each port being listened
--async-stdio
[A] On UNIX, set stdin and stdout to nonblocking mode instead of spawning a thread. This should improve
performance, but may break other programs running on the same console.
--compress-deflate
[A] Compress data coming to a WebSocket using deflate method. Affects only binary WebSocket messages.
--compress-gzip
[A] Compress data coming to a WebSocket using gzip method. Affects only binary WebSocket messages.
--compress-zlib
[A] Compress data coming to a WebSocket using zlib method. Affects only binary WebSocket messages.
--crypto-reverse
[A] Swap encryption and decryption operations in `crypto:` specifier - encrypt on read, decrypto on write.
--dump-spec [A] Instead of running, dump the specifiers representation to stdout
-e, --set-environment
Set WEBSOCAT_* environment variables when doing exec:/cmd:/sh-c:
Currently it's WEBSOCAT_URI and WEBSOCAT_CLIENT for
request URI and client address (if TCP)
Beware of ShellShock or similar security problems.
-E, --exit-on-eof Close a data transfer direction if the other one reached EOF
--foreachmsg-wait-read [A] Wait for reading to finish before closing foreachmsg:'s peer
--jsonrpc
Format messages you type as JSON RPC 2.0 method calls. First word becomes method name, the rest becomes
parameters, possibly automatically wrapped in [].
--jsonrpc-omit-jsonrpc [A] Omit `jsonrpc` field when using `--jsonrpc`, e.g. for Chromium
--just-generate-key [A] Just a Sec-WebSocket-Key value without running main Websocat
--lengthprefixed-little-endian
[A] Use little-endian framing headers instead of big-endian for `lengthprefixed:` overlay.
--lengthprefixed-skip-read-direction
[A] Only affect one direction of the `lengthprefixed:` overlay, bypass tranformation for the other one.
--lengthprefixed-skip-write-direction
[A] Only affect one direction of the `lengthprefixed:` overlay, bypass tranformation for the other one.
--linemode-strip-newlines
[A] Don't include trailing \n or \r\n coming from streams in WebSocket messages
-0, --null-terminated Use \0 instead of \n for linemode
--no-line [A] Don't automatically insert line-to-message transformation
--no-exit-on-zeromsg
[A] Don't exit when encountered a zero message. Zero messages are used internally in Websocat, so it may
fail to close connection at all.
--no-fixups
[A] Don't perform automatic command-line fixups. May destabilize websocat operation. Use --dump-spec without
--no-fixups to discover what is being inserted automatically and read the full manual about Websocat
internal workings.
--no-async-stdio [A] Inhibit using stdin/stdout in a nonblocking way if it is not a tty
-1, --one-message Send and/or receive only one message. Use with --no-close and/or -u/-U.
--oneshot Serve only once. Not to be confused with -1 (--one-message)
--print-ping-rtts
Print measured round-trip-time to stderr after each received WebSocket pong.
--exec-exit-on-disconnect
[A] Make exec: or sh-c: or cmd: immediately exit when connection is closed, don't wait for termination.
--exec-sighup-on-stdin-close
[A] Make exec: or sh-c: or cmd: send SIGHUP on UNIX when input is closed.
--exec-sighup-on-zero-msg
[A] Make exec: or sh-c: or cmd: send SIGHUP on UNIX when facing incoming zero-length message.
-q Suppress all diagnostic messages, except of startup errors
--reuser-send-zero-msg-on-disconnect
[A] Make reuse-raw: send a zero-length message to the peer when some clients disconnects.
-s, --server-mode Simple server mode: specify TCP port or addr:port as single argument
-S, --strict
strict line/message mode: drop too long messages instead of splitting them, drop incomplete lines.
--timestamp-monotonic [A] Use monotonic clock for `timestamp:` overlay
-k, --insecure Accept invalid certificates and hostnames while connecting to TLS
--udp-broadcast [A] Set SO_BROADCAST
--udp-multicast-loop [A] Set IP[V6]_MULTICAST_LOOP
--udp-oneshot [A] udp-listen: replies only one packet per client
--udp-reuseaddr
[A] Set SO_REUSEADDR for UDP socket. Listening TCP sockets are always reuseaddr.
--uncompress-deflate
[A] Uncompress data coming from a WebSocket using deflate method. Affects only binary WebSocket messages.
--uncompress-gzip
[A] Uncompress data coming from a WebSocket using deflate method. Affects only binary WebSocket messages.
--uncompress-zlib
[A] Uncompress data coming from a WebSocket using deflate method. Affects only binary WebSocket messages.
-u, --unidirectional Inhibit copying data in one direction
-U, --unidirectional-reverse
Inhibit copying data in the other direction (or maybe in both directions if combined with -u)
--accept-from-fd
[A] Do not call `socket(2)` in UNIX socket listener peer, start with `accept(2)` using specified file
descriptor number as argument instead of filename
--unlink [A] Unlink listening UNIX socket before binding to it
-V, --version Prints version information
-v Increase verbosity level to info or further
-b, --binary Send message to WebSockets as binary messages
-n, --no-close Don't send Close message to websocket on EOF
--websocket-ignore-zeromsg
[A] Silently drop incoming zero-length WebSocket messages. They may cause connection close due to usage of
zero-len message as EOF flag inside Websocat.
-t, --text Send message to WebSockets as text messages
--base64
Encode incoming binary WebSocket messages in one-line Base64 If `--binary-prefix` (see `--help=full`) is
set, outgoing WebSocket messages that start with the prefix are decoded from base64 prior to sending.
--base64-text
[A] Encode incoming text WebSocket messages in one-line Base64. I don't know whether it can be ever useful,
but it's for symmetry with `--base64`.
OPTIONS:
--socks5 <auto_socks5>
Expand Down Expand Up @@ -293,6 +319,9 @@ OPTIONS:
--just-generate-accept <just_generate_accept>
[A] Just a Sec-WebSocket-Accept value based on supplied Sec-WebSocket-Key value without running main
Websocat
--lengthprefixed-nbytes <lengthprefixed_header_bytes>
[A] Use this number of length header bytes for `lengthprefixed:` overlay. [default: 4]
--max-messages <max_messages>
Maximum number of messages to copy in one direction.
Expand Down Expand Up @@ -458,6 +487,7 @@ Full list of overlays:
ws-c: Low-level WebSocket connector. Argument is a some another address. [A]
msg2line: Line filter: Turns messages from packet stream into lines of byte stream. [A]
line2msg: Line filter: turn lines from byte stream into messages as delimited by '\\n' or '\\0' [A]
lengthprefixed: Turn stream of bytes to/from data packets with length-prefixed framing. [A]
foreachmsg: Execute something for each incoming message.
log: Log each buffer as it pass though the underlying connector.
jsonrpc: [A] Turns messages like `abc 1,2` into `{"jsonrpc":"2.0","id":412, "method":"abc", "params":[1,2]}`.
Expand All @@ -467,6 +497,7 @@ Full list of overlays:
crypto: [A] Encrypts written messages and decrypts (and verifies) read messages with a static key, using ChaCha20-Poly1305 algorithm.
prometheus: [A] Account connections, messages, bytes and other data and expose Prometheus metrics on a separate port.
exit_on_specific_byte: [A] Turn specific byte into a EOF, allowing user to escape interactive Websocat session
waitfordata: Wait for some data to pending being written before starting connecting. [A]
```
</details>

Expand All @@ -485,7 +516,6 @@ Limitations
* Current version of Websocat don't receive notification about closed sockets. This makes serving without `-E` or `-u` options or in backpressure scenarios prone to socket leak.
* Readline is not integrated. Users are advices to wrap websocat using [`rlwrap`](https://linux.die.net/man/1/rlwrap) tool for more convenient CLI.
* Build process of current version of Websocat is not properly automated and is fragile.
* `ws://localhost` may fail if service is not listening both IPv4 and IPv6 properly. There is a workaround based on `ws-c:tcp:` if needed. Or just use `ws://127.0.0.1`.

See also
---
Expand Down
Loading

0 comments on commit 06643a7

Please sign in to comment.