The WebSocket CLI for developers
WebSockets can be hard to work with due to their stateful nature. It is not really feasible to just open a websocket in a web browser like you can with a RESTful API, so tools are needed. wurl (pronounced 'whirl') is that tool.
It is a ground up rewrite of wsta. Still heavy work in progress, but usable.
- Transmit messages to and from WebSocket servers from a CLI
- Composable by design, works great with UNIX pipes
- Easy to learn
- Inherently scriptable
- Follows the UNIX philosophy of doing one thing, and doing it well
- Written in rust, providing type safety and thread safety
- Extensible as a rust library
USAGE:
wurl [FLAGS] [OPTIONS] <URL>
FLAGS:
-e, --echo Enables echoing of outgoing frames
-h, --help Prints help information
-i, --include Include the HTTP headers in the output
-s, --silent Supresses all output except incoming frames
-V, --version Prints version information
-v, --verbose Increments verbosity by one
OPTIONS:
-H, --header <header:value>... Adds headers to the WebSocket HTTP handshake
-C, --control-frames <type> Enables echoing of control frames [possible values: all, in, out]
ARGS:
<URL> The URL of the server to connect to
To connect to a server with wurl
, you pass it the only required parameter, a
URL of the WebSocket server.
$ wurl wss://echo.websocket.org
Connected to wss://echo.websocket.org
After this, wurl
listens to stdin and sends any lines it reads to the
server as messages. WebSocket control frames are also supported, see the
control frames section for more information about that.
If you pass the -e, --echo
flag, you will see outgoing frames as well. These
are always prefixed with >
and a space to ensure they are possible to filter
out.
You may sometimes encounter issues connecting to a server. In this case it may
be useful to see more information about the WebSocket upgrade request. In order
to do this, pass the -i
flag.
$ wurl -i wss://echo.websocket.org
WebSocket upgrade request
---
GET / HTTP/1.1
Connection: Upgrade
Host: echo.websocket.org:443
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: bIkIvw9EcchOo931ELJpOg==
Upgrade: websocket
Origin: https://echo.websocket.org
WebSocket upgrade response
---
HTTP/1.1 101 Web Socket Protocol Handshake
Connection: Upgrade
Date: Mon, 09 Apr 2018 18:00:10 GMT
Sec-WebSocket-Accept: 9j72nbYPuMMhmEpRl4xmN+YnZDI=
Server: Kaazing Gateway
Upgrade: websocket
Connected to wss://echo.websocket.org
Displaying control frames may be useful, for example to see if your server is pinging correctly.
It will be supported to send control frames to the server using commands. The currently available commands are:
/ping
- Sends a ping frame/ping <message>
- Sends a ping frame with the given message/pong
- Sends a pong frame/pong <message>
- Sends a pong frame with the given message/close <code>
- Sends a close code to the server/close <code> <msg>
- Sends a close code with a given message to the server
If you need to send a frame which contains a leading slash like the above commands, add a leading space to escape it.
Authentication is not built in to wurl
, but setting custom headers is
possible. Use the -H
option to set as many authentication headers as you need.
For an easy way of setting an authentication header automatically, see wurl-auth.
The main wurl executable is intentionally kept tiny. Many other programs
integrate well wurl
, and some provide features you may need. Here are some
that are designed to work well with wurl
.
- wurl-auth - Set authentication headers
- wurl-tools - Easily automate sending of messages
Feel free to add to this list if you created something cool.
- Ground up rewrite using a modern rust toolchain and libraries
- (Should be) Much faster and handle higher throughput due to the new async, event driven architecture and no locking
- Is now a library in addition to a CLI which makes it possible for rust programmers to programmatically control wurl
- Supports control frames
- Follows the UNIX philosophy, and is just as pipe-friendly as wsta
- Supports musl-based OSes (like alpine linux)
- Supports LibreSSL-based OSes??
- OSes via first-party distributed docker image
- Does not support binary data. If this is requested enough, it may in the future. Please see this issue
- No man pages (yet)
- Does not have first party distribution through OS package managers. The system used by wsta was not satisfactory, and will not be used again. Packaging will have to be done by volunteers. (Pst, want to be a packager?)
First party distribution:
Third party distibution:
- None yet
If you are a rust programmer, it is easy to install wurl using the cargo CLI.
$ cargo install wurl
Remember to make sure that $HOME/.cargo/bin
is on your $PATH
, or you will
not be able to find the installed binary.
To update to a newer version, simply overwrite the old executable when installing.
$ cargo install --force wurl
All tagged releases on GitHub have compiled binaries attached to them. See the releases page for the download links for your system.
$ docker run -it --rm --network=host esphen/wurl
If you do not have the rust toolchain installed and there is no package for your OS, you may use the docker image, which will run on all platforms that docker supports.
If you use docker, it may be an idea to add an alias to make running it through docker easy. For example:
$ alias wurl="docker run -it --rm --network=host esphen/wurl"
Would you like to maintain a package for your OS? If it is not listed above, feel free to add it to the package manager of your choice. Once you have done so, please make a pull request to add it to the list above.