๐ iola
Table of contents (click to open)
Description
iola - a socket client with REST API. It helps to work with socket servers using your favorite REST client.
iola tries to simplify socket server testing and support the most popular socket clients. The main way to interact with the tool is the REST API. This approach allows you to use the rich functionality of modern REST clients to work with sockets.
The potential of the tool is revealed when using API clients such as Postman, Insomnia, etc. You can manage collections of requests for projects that have socket-based API, use dynamic variables in requests and many other features supported by these clients.
Features:
- Allows reading and sending messages via REST API
- Logs all socket events in the console
- Swagger UI for REST API
- Works on Linux, MacOS and Windows
Supported clients:
- WebSocket
- Socket.IO
- TCP
- Unix socket
Installation
Via npm (for all platforms where Node.js is installed).
$ npm install -g iola
Via homebrew (MacOS only).
$ brew tap pvarentsov/iola
$ brew install iola
Or download standalone binary from releases.
Usage
CLI
$ iola --help iola - a socket client with REST API Usage: iola [options] [command] Options: --version Display version --help Display help Commands: websocket|ws [options] <address> Run websocket client socketio|io [options] <address> Run socket.io client tcp [options] <address> Run tcp client unix [options] <address> Run unix client help [command] Display help for command API: GET /messages Get message list GET /messages/{id} Get message by id POST /messages Send message GET /swagger Get swagger
REST API
Clients
Common
All socket clients have the next options:
WebSocket
$ iola help websocket Usage: iola websocket [options] Run websocket client Options: -ap, --api-port <port> Set api port (default: "3000") -ah, --api-host <host> Set api host (default: "127.0.0.1") -h, --header <key:value...> Set http headers -rt, --reply-timeout <timeout> Set reply timeout in ms (default: "1000") -be, --binary-encoding <encoding> Set binary encoding (choices: "ascii","utf8","base64","hex") -ne, --no-emoji Disable emoji --help Display help Examples: $ iola websocket ws://127.0.0.1:8080 $ iola ws ws://127.0.0.1:8080/?token=secret $ iola ws ws://127.0.0.1:8080 --header authorization:"Bearer token" $ iola websocket ws://127.0.0.1:8080 --binary-encoding utf8 $ iola websocket ws://127.0.0.1:8080 --reply-timeout 3000 --no-emoji
message formats
string
json
byte-array
http headers
You can pass http headers using --header <key:value...>
option. Examples:
iola ws ws://127.0.0.1:8080 --header authorization:"Bearer token"
iola ws ws://127.0.0.1:8080 -h content-type:application/json -h content-length:42
server reply
You can pass the RequestId to the request with json data in order to await the server reply with such RequestId in the reply data.
RequestId field can be one of the following:
requestId
request_id
reqId
req_id
traceId
trace_id
Default reply timeout is 1000 ms. To change it you can set --reply-timeout <timeout>
option.
Socket.IO
iola relies on Socket.IO v4. Please check a version compatibility.
$ iola help socketio Usage: iola socketio|io [options] Run socket.io client Options: -ap, --api-port <port> Set api port (default: "3000") -ah, --api-host <host> Set api host (default: "127.0.0.1") -h, --header <key:value...> Set http headers -a, --auth <key:value...> Set authentication payload -t, --transport <transport> Set transport (choices: "polling","websocket") -rt, --reply-timeout <timeout> Set reply timeout in ms (default: "1000") -be, --binary-encoding <encoding> Set binary encoding (choices: "ascii","utf8","base64","hex") -ne, --no-emoji Disable emoji --help Display help Examples: $ iola socketio http://127.0.0.1:8080 $ iola io http://127.0.0.1:8080/?token=secret --transport websocket $ iola io http://127.0.0.1:8080 --header authorization:"Bearer token" $ iola io http://127.0.0.1:8080 --auth user:iola --auth pass:qwerty1 $ iola socketio http://127.0.0.1:8080 --binary-encoding utf8 $ iola socketio http://127.0.0.1:8080 --reply-timeout 3000 --no-emoji
message formats
string
number
boolean
null
json
byte-array
transport
Client supports "websocket" and "polling" transports. It tries to use "websocket" first, if available.
You can explicitly set the type of transport using --transport <transport>
option.
http headers
You can pass http headers using --header <key:value...>
option. Examples:
iola io http://127.0.0.1:8080 --header authorization:"Bearer token"
iola io http://127.0.0.1:8080 -h content-type:application/json -h content-length:42
auth
Socket.IO client can send credentials with the auth option.
You can set the auth payload using --auth <key:value...>
option. Examples:
iola io http://127.0.0.1:8080 --auth user:iola --auth pass:qwerty1
iola io http://127.0.0.1:8080 --a token:"super secret"
server reply
Socket.IO supports server replies. This feature is named acknowledgements.
Default reply timeout is 1000 ms. To change it you can set --reply-timeout <timeout>
option.
TCP & Unix socket
TCP and Unix socket clients have the same api.
TCP
$ iola help tcp Usage: iola tcp [options] Run tcp client Options: -ap, --api-port <port> Set api port (default: "3000") -ah, --api-host <host> Set api host (default: "127.0.0.1") -s, --sync Enable sync mode -rt, --reply-timeout <timeout> Set reply timeout in ms (sync mode only) (default: "1000") -be, --binary-encoding <encoding> Set binary encoding (choices: "ascii","utf8","base64","hex") -ne, --no-emoji Disable emoji --help Display help Examples: $ iola tcp 127.0.0.1:8080 $ iola tcp 127.0.0.1:8080 --sync $ iola tcp 127.0.0.1:8080 --binary-encoding utf8 $ iola tcp 127.0.0.1:8080 --no-emoji
Unix socket
$ iola help unix Usage: iola unix [options] Run unix client Options: -ap, --api-port <port> Set api port (default: "3000") -ah, --api-host <host> Set api host (default: "127.0.0.1") -s, --sync Enable sync mode -rt, --reply-timeout <timeout> Set reply timeout in ms (sync mode only) (default: "1000") -be, --binary-encoding <encoding> Set binary encoding (choices: "ascii","utf8","base64","hex") -ne, --no-emoji Disable emoji --help Display help Examples: $ iola unix ./unix.sock $ iola unix ./unix.sock --sync $ iola unix ./unix.sock --binary-encoding utf8 $ iola unix ./unix.sock --no-emoji
Clients support async and sync modes and use async mode by default.
In async mode, the client and the server exchange messages independently within one connection.
Sync mode uses a request/response protocol. The client opens a new connection for each request, the server responds. The connection is closed either on the server side after a successful response or by a timeout on the client side.
message formats
byte-array
sync mode
To enable sync mode need to set --sync
option.
server reply
Server replies are supported only in sync mode. If the server does not close the connection, the client will close it on its own during the reply timeout.
Default reply timeout is 1000 ms. To change it you can set --reply-timeout <timeout>
option.
License
This project is licensed under the MIT License.