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.

Contents

• Highlights
• Usage
• Control Frames
• Examples
• Plugins
• Wurl vs wsta
• Install

Highlights

• 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

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

Connect to a server

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.

Showing more information

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.

Control frames

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

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.

Examples

Plugins

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.

wurl vs wsta

Pros

• 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

Cons

• 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?)

Install

First party distribution:

• crates.io
• binaries
• docker

Third party distibution:

• None yet

crates.io

NOT YET PUBLISHED

$ cargo install wurl

If you are a rust programmer, it is easy to install wurl using the cargo CLI.

To update to a newer version, simply overwrite the old executable when installing.

$ cargo install --force wurl

binaries

All tagged releases on GitHub have compiled binaries attached to them.

docker

$ 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"

Other distribution systems

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.