В этой статье я представлю свой последний проект с открытым исходным кодом, над которым я работал последние несколько месяцев, — websockets-cli. Это интерфейс командной строки (CLI) для взаимодействия с сервером websockets.
Почему?
Есть две основные причины для этого проекта:
- Каждый раз, когда я работаю над веб-проектом с использованием websockets, я обнаруживаю, что мне нужен простой инструмент CLI для тестирования того, что я закодировал. Я всегда заканчивал тем, что писал сценарий для решения этой проблемы, потому что не мог найти подходящую библиотеку.
- Это забавный проект 🙃.
Конечно, есть графические решения, такие как Postman, которые помогут вам с websockets, но я уверен, что я не единственный, кто предпочитает работать с терминалом для такого тестирования.
Установка
Для установки вам понадобится python3.7 или новее и установленный pip. После этого вы можете набрать:
$ pip install websockets-cli
Вы также можете использовать другой менеджер пакетов, например, poetry. У меня есть
если вы не знаете этот инструмент.
$ poetry add -D websockets-cli
Если вам нужна какая-то глобальная установка, вы можете использовать библиотеку pipx.
$ pipx install websockets-cli
Настройки
Существует множество настроек, которые вы можете сконфигурировать для своих нужд. Все они определены в этом разделе официальной документации. Вы можете настроить их либо с помощью:
- файл pyproject.toml
- переменные окружения
- пользовательский env-файл с именем
.ws.envв вашем текущем рабочем или домашнем каталоге.
Примечание:
- файл pyproject.toml имеет приоритет над переменными окружения.
Использование
CLI прост в использовании. Чтобы узнать все доступные команды, просто введите ws в терминале:
$ ws
Usage: ws [OPTIONS] COMMAND [ARGS]...
A convenient websocket cli.
Example usage:
# listens incoming messages from endpoint ws://localhost:8000/path
$ ws listen ws://localhost:8000/path
# sends text "hello world" in a text frame
$ ws text wss://ws.postman-echo.com/raw "hello world"
# sends the content from json file "hello.json" in a binary frame
$ ws byte wss://ws.postman-echo.com/raw file@hello.json
Options:
--version Show the version and exit.
-h, --help Show this message and exit.
Commands:
byte Sends binary message to URL endpoint.
echo-server Runs an echo websocket server.
install-completion Install completion script for bash, zsh and fish...
listen Listens messages on a given URL.
ping Pings a websocket server located at URL.
pong Sends a pong to websocket server located at URL.
session Opens an interactive session to communicate with...
tail An emulator of the tail unix command that output...
text Sends text message on URL endpoint.
Установка-дополнение
Первая команда для использования — install-completion, которая добавит поддержку завершения для команд и опций. Она будет работать для bash, fish и zsh. Планируется поддержка Windows (Powershell).
$ ws install-completion
# when the command succeeded, you should see the following message
Successfully installed completion script!
Эхо-сервер
Если вы хотите самостоятельно разместить вебсокетный сервер echo, как это делает Postman, вы можете выполнить команду echo-server. Вот пример:
$ ws echo-server -H ::1 -p 8000
Running server on ::1:8000 💫
# To stop the server, you can just tap Ctrl+C
^CProgram was interrupted by Ctrl+C, good bye! 👋
Прослушать
Часто вы хотите видеть входящие сообщения от конечной точки websocket. Это очень просто с помощью websockets-cli:
# assuming you have an endpoint localhost:8000 sending messages
$ ws listen :8000
# you will have an output like the following
──────────────────── TEXT message on 2022-05-25 07:10:07 ────────────────────────────────────
{"hello": "world"}
──────────────────── BINARY message on 2022-05-25 07:10:07 ──────────────────────────────────────
b'{"hello": "world"}'
Сессия
Вероятно, это команда, которую вы будете использовать чаще всего. Она позволяет полностью взаимодействовать с сервером websocket. Вы можете отправлять ping, pong, close, text и binary фреймы.
$ ws session wss://ws.postman-echo.com/raw
Welcome to the interactive websocket session! 🌟
For more information about commands, type the help command.
When you see <> around a word, it means this argument is optional.
To know more about a particular command type help <command>.
To close the session, you can type Ctrl+D or the quit command.
> help
The session program lets you interact with a websocket endpoint with the
following commands:
• ping <message>: Sends a ping with an optional message.
• pong <message>: Sends a pong with an optional message.
• text message: Sends text message.
• byte message: Sends byte message.
• close <code> <reason>: Closes the websocket connection with an optional code
and message.
• quit: equivalent to close 1000.
> help close
Closes the session given a code and an optional reason.
Example usage:
If no code is given, 1000 is considered as default meaning a normal closure.
Thus, it is equivalent to the quit command.
┌────────────────────────────────────────────────────────────────────────────┐
│ > close │
└────────────────────────────────────────────────────────────────────────────┘
Closes the connection with a code 1001 and no message.
┌────────────────────────────────────────────────────────────────────────────┐
│ > close 1001 │
└────────────────────────────────────────────────────────────────────────────┘
Closes the connection with a code 1003 and a message "received unknown data".
The message length must not be greater than 123 bytes.
┌────────────────────────────────────────────────────────────────────────────┐
│ > close 1003 'received unknown data' │
└────────────────────────────────────────────────────────────────────────────┘
To know more about close codes, please refer to the RFC.
> quit
Bye! 👋
Благодаря prompt-toolkit команда session имеет такие возможности, как:
- Подсветка синтаксиса
- Автозавершение подкоманд
- Возможность чтения истории предыдущих команд, набранных в текущем сеансе работы
- Автосоветы команд на основе вашей истории в текущем сеансе.
На этом я остановлюсь на презентации, если вы хотите узнать больше о проекте, вы можете ознакомиться с официальной документацией.
Я надеюсь, что вы найдете его интересным для использования, если вы много играете с websockets 🙂 .
Если вам понравилась моя статья и вы хотите продолжить обучение вместе со мной, не стесняйтесь следовать за мной здесь и подписаться на мою рассылку 😉