websockets-cli: дружественный компаньон для вашего веб-проекта

В этой статье я представлю свой последний проект с открытым исходным кодом, над которым я работал последние несколько месяцев, — 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 🙂 .


Если вам понравилась моя статья и вы хотите продолжить обучение вместе со мной, не стесняйтесь следовать за мной здесь и подписаться на мою рассылку 😉

Оцените статью
devanswers.ru
Добавить комментарий