wsta
The WebSocket Transfer Agent
wsta is a cli tool written in rust for interfacing with WebSockets. wsta has the philosophy of being an easy tool to learn and thus gets out of your way to let you work your UNIX magic directly on the WebSocket traffic. The way wsta does this is to be as pipe-friendly as possible, letting you chain it into complex pipelines or bash scripts as you see fit, or just keep it simple and use it as is.
See the manual or type man wsta for details.
Cool things you can do
Since wsta is really pipe-friendly, you can easily work with your output in a way that suits you. If you have a websocket-service that returns JSON, you might want to have your data printed in a nice, readable format. jq is perfect for that.
$ wsta ws://echo.websocket.org '{"values":{"test": "what?"}}' | jq .values
Connected to ws://echo.websocket.org
{
"test": "what?"
}
Because wsta reads from stdin, it can also be used as an interactive prompt if you wish to send messages to the server interactively.
$ wsta ws://echo.websocket.org
Connected to ws://echo.websocket.org
ping
ping
hello
hello
If you're debugging some nasty problem with your stream, you are probably only interested in frames related to your problem. Good news, grep is here to save the day!
$ while true; do echo $(( RANDOM %= 200 )); sleep 0.2; done | wsta ws://echo.websocket.org | grep '147'
147
147
147
147
147
147
Use wsta to monitor your websocket uptime. Use the --ping option to keep the connection alive, and check the exit code for issues. You can also send the last few messages with POST data for a higher quality alert.
while true; do
# Start persistent connection, pinging evey 10 seconds to stay alive
wsta -v --ping 10 ws://echo.websocket.org > messages.txt
if [ $? -gt 0 ]; then
tail messages.txt | curl -F "messages=@-" https://SOUNDTHEALARM.yourcompany.com
fi
sleep 30
done
If you need to load test your server over a WebSocket connection, it is simple to write a short bash script to do this. The following example uses a loop to continously send messages to the server and saturate the connection as much as possible. This example could also be ran in parallel as many times as required to add more saturated connections to the load test.
for i in {1..1000}
do
echo "subscribe?giveMeLotsOfData=true&id=$i"
echo "unsubscribe?id=$i"
done | wsta ws://echo.websocket.org
wsta also supports binary data using the --binary argument. When provided, all data read from stdin is assumed to be in binary format. The following simplified example records a binary stream from the microphone and sends it continously to the server, reading the response JSON as it comes in.
For more information on binary mode, see the manual and #5.
$ arecord --format=S16_LE --rate=44100 | wsta -b 'wss://example.com' | jq .results
"hello "
"hello this is me "
"hello this is me talking to "
"hello this is me talking to people "
"hello this is me talking to people "
Configuration profiles
A neat feature of wsta is the ability to have several separate configuration profiles. Configuration profiles are basically presets of CLI arguments like urls and headers saved to a file for easy reuse at a later point.
If you have web services in different environments, you might for example want to have a foo-dev and foo-prod configuration file. This makes it easy to at a later date connect to foo by simply running wsta -P foo-dev,
These files could be checked into VCS and shared between colleagues.
An example of a configuration file:
url = "ws://echo.websocket.org";
headers = ["Origin:google.com", "Foo:Bar"];
show_headers = true;
See the manual for more information.
Installation
Requirements
Currently the only requirement to run wsta is rust-openssl. If you get an error about a missing ssllib.so or similar, try installing OpenSSL runtime libraries and headers. Have a look at this link for instructions on how to do so.
64-bit Linux
I've set up a download page here that you can get wsta
https://software.opensuse.org/download.html?project=home%3Aesphen&package=wsta
I'm working on getting more distributions, as well as 32-bit into the Open Build Service pipeline, which is what creates the releases on that page. For now, you need a 64-bit system to use that page. If you don't use a 64-bit system, have a look below at binaries or compiling it yourself.
Gentoo Linux
wsta can be found in the Gentoo portage tree as dev-util/wsta. In order to install it, simply run the following command.
emerge dev-util/wsta
Mac OS X
To install on Max OS X, ensure you have homebrew installed, then run the following commands. It's going to take a while, please be patient.
brew tap esphen/wsta https://github.com/esphen/wsta.git
brew install wsta
You can also find binary releases on the releases page.
Other Linux distributions
I only provide so many Linux distros on OBS, and only 64-bit versions. If your computer does not fit into the distros provided, then have a look at the download section of the most recent release, and place the attached binary into your $PATH.
https://github.com/esphen/wsta/releases
Windows
Windows binaries are compiled for each release. Ensure you have a command prompt with GNU libraries, for example the git prompt, and run the provided binary file from there.
You can find binary releases on the releases page.
Compile it yourself
DON'T PANIC. It's really easy to compile and install wsta yourself! Rust provides solid tools like cargo for automating the compilation. If you compile wsta yourself, it should run on all of rust's supported platforms.
# Install the rust language and tools
curl https://sh.rustup.rs -sSf | sh
# Install gcc and OpenSSL on your OS
dnf install -y gcc openssl-devel
# Install wsta to `$HOME/.cargo` or `$CARGO_HOME` if set.
# To change the install path, try setting --root to a directory like /usr/local
cargo install --git https://github.com/esphen/wsta.git
Development setup
Install the rust language and tools.
curl https://sh.rustup.rs -sSf | sh
Run the program
cargo run -- -vvv -I -e ws://echo.websocket.org
In order to generate the man page, groff is needed
make man
If updates to the man page are done, remember to generate the markdown manual afterwards
make wsta.md
1.3k Jan 2, 2023
13 Oct 28, 2022
94 Dec 30, 2022
91 Jan 5, 2023
94 Dec 30, 2022
19 Aug 22, 2022
8 Sep 7, 2022
1 Feb 14, 2022
261 Dec 27, 2022
1 Feb 11, 2022
2 Aug 27, 2022
5 Dec 21, 2022
5 Apr 2, 2023
12 Nov 12, 2022
10 Nov 11, 2022
294 Dec 23, 2022
47 Dec 15, 2022
4 Aug 14, 2022
104 Oct 7, 2023