Websocat1 features missing in Websocat4

[vi]

Websocat4 is a full rewrite of Websocat1. It makes it impractical to implement all the features accumulated in Websocat1 at the same time.

This issue tracks status of porting Websocat1 features to Websocat4 and allows voting using Github comment reactions to determine the priority. Each list entry links to a comment where you are expected to put reactions to attract my attention to a particular missing feature.

The list is styled as a websocat --help=full output converted to a checkboxed list. Checked items means the feature is already implemented in Websocat4.

Flags

• --stdout-announce-listening-ports
• --async-stdio
• --compress-deflate
• --compress-gzip
• --compress-zlib
• --crypto-reverse
• --dump-spec
• -e, --set-environment
• -E, --exit-on-eof
• --foreachmsg-wait-read
• --jsonrpc
• --jsonrpc-omit-jsonrpc
• --just-generate-key
• --lengthprefixed-little-endian
• --lengthprefixed-skip-read-direction
• --lengthprefixed-skip-write-direction
• --linemode-strip-newlines
• -0, --null-terminated
• --no-line
• --no-exit-on-zeromsg
• --no-fixups
• --no-async-stdio
• -1, --one-message
• --oneshot
• --print-ping-rtts
• --exec-exit-on-disconnect
• --exec-sighup-on-stdin-close
• --exec-sighup-on-zero-msg
• -q
• --reuser-send-zero-msg-on-disconnect
• -s, --server-mode (but the latter is named just --server instead of --server-mode)
• -S, --strict
• --timestamp-monotonic
• -k, --insecure
• --udp-broadcast
• --udp-multicast-loop
• --udp-broadcast
• --udp-oneshot
• --udp-reuseaddr
• --uncompress-deflate
• --uncompress-gzip
• --uncompress-zlib
• -u, --unidirectional
• -U, --unidirectional-reverse
• --accept-from-fd
• --unlink
• -V, --version
• -v
• -b, --binary
• -n, --no-close
• --websocket-ignore-zeromsg
• -t, --text
• --base64
• --base64-text

Options

• --socks5
• --autoreconnect-delay-millis
• --basic-auth
• --basic-auth-file
• --queue-len
• -B, --buffer-size - note that buffer size does not limit maximum message size in Websocat4
• --byte-to-exit-on
• --client-pkcs12-der
• --client-pkcs12-passwd
• --close-reason
• --close-status-code
• --crypto-key
• -H, --header
• --server-header
• --exec-args
• --header-to-env
• -h, --help
• --help=short
• --help=doc
• --inhibit-pongs
• --just-generate-accept
• --lengthprefixed-nbytes
• --max-messages
• --max-messages-rev
• --conncap
• --max-sent-pings
• --max-ws-frame-length
• --max-ws-message-length
• --origin
• --pkcs12-der
• --pkcs12-passwd
• -p, --preamble
• -P, --preamble-reverse
• --prometheus
• --request-header
• -X, --request-method
• --request-uri
• --restrict-uri
• -F, --static-file
• --socks5-bind-script
• --socks5-user-pass
• --socks5-destination
• --tls-domain
• --udp-multicast
• --udp-multicast-iface-v4
• --udp-multicast-iface-v6
• --udp-ttl
• --ua
• --protocol
• --server-protocol
• --websocket-version
• --binary-prefix
• --ws-c-uri
• --ping-interval
• --ping-timeout
• --text-prefix

Endpoints

• ws://
• `wss://
• ws-listen:
• inetd-ws:
• l-ws-unix:
• l-ws-abstract:
• ws-lowlevel-client:
• ws-lowlevel-server:
• wss-listen:
• http:
• asyncstdio:
• inetd:
• tcp:
• tcp-listen:
• ssl-listen:
• sh-c:
• cmd:
• exec:
• readfile:
• writefile:
• appendfile:
• udp:
• udp-listen:
• open-async:
• open-fd:
• threadedstdio:
• -
• unix:
• unix-listen:
• unix-dgram:
• abstract:
• abstract-listen:
• abstract-dgram:
• mirror:
• literalreply:
• clogged:
• literal:
• assert:
• assert2:
• seqpacket:
• seqpacket-listen:
• random:
• namedpipeconnect:

Overlays

• ws-upgrade:
• http-request:
• http-post-sse:
• ssl-connect:
• ssl-accept:
• reuse-raw:
• broadcast:
• autoreconnect:
• ws-c:
• msg2line:
• line2msg:
• lengthprefixed:
• foreachmsg:
• log
• jsonrpc:
• timestamp:
• socks5-connect:
• socks5-bind:
• crypto:
• prometheus:
• exit_on_specific_byte:
• drop_on_backpressure:
• waitfordata:

Misc

• Lints
• Examples in doc.md

[vi]

Websocat1 can print a line on stdout when a listening port is ready to accept a connection.

Example:

$ /opt/websocat --stdout-announce-listening-ports -bE  ws-l:127.0.0.1:1234 mirror:
LISTEN proto=tcp,ip=127.0.0.1,port=1234

[vi]

Websocat1 can use stdin/stdout in nonblocking mode, providing simpler code path and increased efficiency in some scenarios at the cost of increased probability of some bugs.

This is especially useful if stdin/stdout is known to be not a terminal and not a regular file.

This point also tracks ability to open arbitrary files (or inherit file descriptors) as async devices.

[vi]

Websocat1 can decompress the data coming from a WebSocket or compress it before writing to a WebSocket. This is unrelated to permessage-deflate.

[vi]

Websocat1 (max edition) contains a simple ad-hoc way to encrypt/obfuscate messages using a key (without IVs).

[vi]

Websocat1 can set special environment variables when starting subprocesses with exec:/cmd:/sh-c: that depend on incoming client socket address or used request URL.

[vi]

Websocat1 can turn each message into a new connection (that sends one message, possibly receives one message in reply).

This includes the --foreachmsg-wait-read mode.

[vi]

Websocat1 can turn each line like QQQ www into a JSON snippet like {"jsonrpc":"2.0","id":1, "method":"QQQ", "params":[www]}, which can provide some convenience to interact with some services like Chromium's remotely controlled mode from terminal.

[vi]

Instead of normal operation, Websocat1 can just print a Sec-Websocket-Key or Sec-Websocket-Accept header values, to aid implementing hacky Websocket upgrades using other tools.

[vi]

Websocat1 can convert packets to byte stream (and back) using binary length-prefixed format where you can specify the length of the length field.

[vi]

Websocat1 contains some tricks to adjust trailing newlines in WebSocket messages.

[vi]

Websocat1 can be configured to use zero byte instead of newline to separate messages in a byte stream.

Websocat4 can as well with --separator 0, but specifically -0 or --null-terminated is not yet recognized as an alias to --separator 0 at the moment.

[vi]

Websocat4 and Websocat1 have different architectural decisions regarding to how to connect bytestream-oriented and datagram-oriented sockets (where a WebSocket counts as datagram-orinted). This makes direct port of --no-line impractical, but similar effect may be imitated using other means, such as using chunks: instead of lines: even in text mode.

[vi]

Websocat4 should not exit on zero-length messages by default (except of with seqpacket:, for which it may cause the recipient to exit), so --no-exit-on-zeromsg may be less applicable. A dummy option may be added for compatibility.

[vi]

Like Websocat1, Websocat4 applies automatic transformations to the arguments you use. --no-fixups may be added to inhibit this step, which would typically lead to errors, unlike in Websocat1 where it led to possible suboptimal operation.

[vi]

Websocat1 contains a mode where it automatically closes the connection after a single message. Such overlay can easily be added to Websocat4 (though it would work only with datagram-oriended Sockets).

This also extends to a non-one (but fixed) number of messages.

[vi]

Like Websocat1, Websocat4 attempts to serve multiple connections (including in parallel) when you specify a listening socket at the left side.

However, --oneshot option to explicitly limit it to one connection is not yet supported (but can be added reasonable easily).

Specifying listener at the right side, unlike in Websocat1, leads to errors instead of being a --oneshot analogue.

[vi]

Both Websocat1 and Websocat4 reply to pings, but Websocat1 can also send pings periodically. This includes additional features like printing RTTs for resulting pong replies or stopping outgoing pings after some moment.

Aborting connection on ping timeouts is also in scope of this point.

[vi]

Websocat1's subprocess executors typically waits for child process termination before considering connection as really closed.

Websocat4's subprocess module is currently simpler in this regard. --exec-exit-on-disconnect-like behaviour may be default now, but if there will be refinements in this regard, the option may need to reappear.

[vi]

On UNIX-like platforms, Websocat1's subprocess executor can send SIGHUP to processes when associated connection gets closed. In Websocat4 it is not yet implemented (maybe the process is just killed instead, maybe it dangles).

[vi]

Websocat1 have -v and -q to affect verbosity of diagnostic output. Websocat4 has RUST_LOG support, but no relevant CLI options at the moment.

Making non-debug, user-friendly logs is not in scope of this point, just the options to affect verbosity.

[vi]

Websocat1 contains reuse-broadcast: (alias reuse:) and reuse-raw: overlays. Websocat4 does not yet.

This includes various additional options that affect details of reuser behaviour.

[vi]

Unlike Websocat1, Websocat4 makes use of WebSocket continuation frames and does not need to cache the whole message in memory, so buffer size should not affect maximum line length.

Lines that does not end with the separator are still processed. --strict may be reintroduced to drop such potentially chopped lines with a warning instead of sending them.

[vi]

Websocat1 contains timestamp: overlay that modifies messages, adding a numeric timestamp before each message.

[vi]

Websocat1 can set various UDP socket options, allowing to use broadcasts, multicasts, set TTL.

[vi]

--udp-oneshot may be less relevant for Websocat4, given it has new udp-server: mode, if --one-message gets implemented.

[vi]

Instead of binding a TCP socket, Websocat1 can accept connections from an inherited file descriptor (e.g. from SystemD).

[vi]

Websocat1 has explicit option to inhibit zero-length WebSocket messages, which can cause problems, e.g. an abort in a seqpacket: connection.

[vi]

Websocat1 can base64-encode binary messages before printing (or base64-decode input messages before sending).

If needed, this can extend to text messages.

[vi]

Websocat1 can use SOCKS5 proxies.

Note that listening for incoming connections over SOCKS5 proxy is tracked as a separate comment below.

[vi]

Websocat1 has autoreconnect: overlay that allows to retry underlying connection without breaking upstream connection.

[vi]

Websocat1 can deliberately inhibit replying to WebSocket ping frames, to aid testing of timeout codepaths in other apps.

[vi]

Websocat1 can limit number of connections being served in parallel, quickly rejecting excessive incoming connections.

[vi]

Websocat1 buffers full WebSocket message in memory prior to processing them, making it necessary to set some limits to avoid DoS.

Websocat4 can typically work with partial messages, making such limits less necessary. Instead, endpoint limitations (i.e. maximum UDP or seqpacket datagrams size) should be provided.

But other applications interfacing Websocat may be surprised that previously filtered giant messages now go though, so such options may still be needed, even for websocket-to-websocket scenarios. Specifically --max-ws-frame-length is probably unneeded, as --buffer-size will just serve that need, but there is currently no --max-ws-message-length analogue.

[vi]

Websocat1 has a little helper to set Origin: request HTTP header in a more user-friendly way.

[vi]

Websocat1 can act as a TLS server. Websocat4 only has client mode at the moment.

This includes wss-listen: helper.

[vi]

Websocat1 can inject CLI-specified fixed messages before normal traffic, allowing to e.g. authorize and subscribe to something over WebSocket in a convenient way.

[vi]

Websocat1 (max edition) contains special overlay that collects some statistics about connections and traffic in them, allowing to expose a Prometheus endpoint.

[vi]

Websocat1 contains a way to send arbitrary HTTP requests and use outgoing/incoming bodies as a sort-of-socket.

[vi]

For incoming connections Websocat1 and Websocat4 ignores request URL by default, but Websocat1 has a way to restrict WebSocket connections to specific URL and bind some other specific URLs to static files, to act as a quick development server.

[vi]

When using SOCKS5 proxies, Websocat1 can request them to open new port for listening for a incoming connection instead of initiating a connection. This mode is rather exotic and may be not widely supported.

[vi]

Websocat1 has a helper to set User-Agent: HTTP request header in a bit more user-friendly way.

[vi]

Websocat1 has a way to override Sec-WebSocket-Version from default 13 to something else.

Note that is is probably against the RFC and does not change anything else besides that value.

[vi]

Websocat1 can modify messages, prefixing text and binary message with user-specified strings (and recognizing such prefixes when reading messages from user).

This allows to work with both text and binary WebSocket messages.

[vi]

Websocat1 supports inetd mode, i.e. using stdin/stdout as a socket where incoming WebSocket connection is expected.

This includes a inetd-ws: helper.

[vi]

Websocat1 has l-ws-unix: and l-ws-abstract: as aliases for ws-u:unix-l: and ws-u:abstract-l: respectively.

Websocat4 also can listen for WebSocket connections over UNIX sockets (including abstract-namespaced), but those specific CLI shortcuts are not yet recognized.

[vi]

Websocat1 can read and write (or append) files directly.

[vi]

Websocat1 includes a crude support of using a pair of SOCK_DGRAM AF_UNIX` sockets.

If implemented in Websocat4, it would be less crude.

For now, you are adviced to use seqpacket: instead (maybe by implementing your own mini-adapter between dgram and seqpacket).

[vi]

Websocat1 includes a mirror: virtual socket that sends every messages or byte stream content back.

[vi]

Websocat1 includes a literalreply: virtual socket that sends back some fixed message in response to each input message.

Websocat4 has literal: and literal-base64: endpoints, but they only send data once.

[vi]

Websocat1 includes clogged: virtual socket that hangs requests to read or write any data.

[vi]

Websocat1 includes assert: or assert2: virtual sockets that check that their input matches specified string, failing a connection (or entire Websocat process) on mismatch. This may be useful for tests.

[vi]

Websocat includes an easy way to get random bytes, similar to /dev/urandom.

[vi]

Websocat1 has some ability to use Server-Send events over HTTP/1 as a sort-of-socket.

If Websocat4 gains similar ability, it is unlikely it would work the same as in Websocat1.

[vi]

msg2line: and line2msg: from Websocat1 are unlikely to be directly ported to Websocat4.

There is just lines: overlay (that gets automatically inserted where appropriate). Accessing individual parts of the stream-to-message splitter can be done using custom Rhai scripts.

[vi]

Websocat1 has an overlay to blackhole data when underlying connection stop readily accepting more content (i.e. experience backpressure).

[vi]

Websocat1 can be ordered to to delay initiating outgoing connection until first portion of data to be sent there is available.

[vi]

Websocat1 checks CLI arguments for sanity and shows various warnings if they do not make sense.

[vi]

Most endpoints and overlays in doc.md have associated examples in Websocat1.

Documentation is currently more terse in Websocat4 in this regard.

[vi]

On Windows, Websocat1 has a connector to named pipes.