🔄 iola

Table of contents (click to open)

• Description


• Installation


• Usage




• CLI


• REST API




• WebSocket


• Socket.IO


• TCP & Unix socket


• License

Description

iola - a command-line 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:

1. Allows reading and sending messages via REST API
2. Logs all socket events in the console
3. Has Swagger UI for REST API
4. Works on Linux, macOS and Windows

Supported clients:

1. WebSocket
2. Socket.IO
3. TCP
4. Unix socket

Installation

Via npm (for all platforms where Node.js >= 12 installed).

``bash
$ npm install -g iola
`

Via homebrew (Linux, macOS).
`bash
$ brew tap pvarentsov/iola
$ brew install iola
`

Via scoop (Windows).
`bash
$ scoop bucket add iola https://github.com/pvarentsov/scoop-iola.git
$ scoop install iola
`

Or download standalone binary from releases (Linux, macOS, Windows).

Usage

$3

$ iola --help
iola - a socket client with REST API
Usage: iola [options] [command]
Options:
  --version                 Display version
  --help                    Display help
Commands:
  ws [options] <address>    Run websocket client
  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

$3

> These examples use HTTPie as the REST API client.

#### Send any data
`shell


Send string message

$ http POST http://127.0.0.1:3000/messages data='Hi, Server!'
{
"messageId": 1
}

Get string message by id

$ http GET http://127.0.0.1:3000/messages/1
{
"id": 1,
"date": "2022-07-15T21:48:19.939Z",
"message": {
"data": "Hi, Server!",
"format": "string"
},
"type": "SentMessage"
}

Send json string message

$ http POST http://127.0.0.1:3000/messages data:='{"message":"Hi, Server!"}'
{
"messageId": 2
}

Get json string message by id

$ http GET http://127.0.0.1:3000/messages/2
{
"id": 2,
"date": "2022-07-15T22:16:31.887Z",
"message": {
"data": {
"message": "Hi, Server!"
},
"format": "json"
},
"type": "SentMessage"
}
`

#### Send binary data
`shell


Send byte-array message

$ http POST http://127.0.0.1:3000/messages bytes:='[72,101,108,108,111,33]'
{
"messageId": 1
}

Get byte-array message by id

$ http GET http://127.0.0.1:3000/messages/1
{
"id": 1,
"date": "2022-07-15T22:23:32.591Z",
"message": {
"data": [72,101,108,108,111,33],
"format": "byte-array",
"size": 6
},
"type": "SentMessage"
}
`

All clients support --binary-encoding option for more readability of sent and received binary messages.
`shell


Run iola client with -binary-encoding option

$ iola ws ws://127.0.0.1:8080 --binary-encoding utf8

Send byte-array message

$ http POST http://127.0.0.1:3000/messages bytes:='[72,101,108,108,111,33]'
{
"messageId": 1
}

Get sent byte-array message by id

$ http GET http://127.0.0.1:3000/messages/1
{
"id": 1,
"date": "2022-07-15T22:23:32.591Z",
"message": {
"data": [72,101,108,108,111,33],
"format": "byte-array",
"size": 6,
"utf8": "Hello!"
},
"type": "SentMessage"
}

Get received byte-array message by id

$ http GET http://127.0.0.1:3000/messages/2
{
"id": 2,
"date": "2022-07-15T22:23:32.591Z",
"message": {
"data": [72,105,44,32,73,111,108,97,33],
"format": "byte-array",
"size": 9,
"utf8": "Hi, Iola!"
},
"type": "ReceivedMessage"
}
`

#### List messages
`shell


List messages


$ http GET http://127.0.0.1:3000/messages
[
{
"id": 1,
"date": "2022-07-15T22:26:57.442Z",
"message": {
"data": "Hi, Server",
"format": "string"
},
"type": "SentMessage"
},
{
"id": 2,
"date": "2022-07-15T22:26:57.445Z",
"message": {
"data": "Hi, Iola!",
"format": "string"
},
"type": "ReceivedMessage"
}
]
`

#### Swagger

To get to know the REST API in more detail you can see a swagger that is exposed on the /swagger path.

WebSocket

$ iola help ws
Usage: iola ws [options] <address>
Run websocket client
Options:
  --api-port <port>             Set api port (default: "3000")
  --api-host <host>             Set api host (default: "127.0.0.1")
  --header <key:value...>       Set http headers
  --reply-timeout <timeout>     Set reply timeout in ms (default: "1000")
  --binary-encoding <encoding>  Set binary encoding (choices: "ascii","utf8","base64","hex")
  --no-emoji                    Disable emoji
  --help                        Display help
Examples: 
  $ iola ws 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 ws ws://127.0.0.1:8080 --binary-encoding utf8 
  $ iola ws ws://127.0.0.1:8080 --reply-timeout 3000 --no-emoji

$3

* string
* json
* byte-array

$3

You can pass the RequestId to the request with json data 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

`shell
$ http POST http://127.0.0.1:3000/messages data:='{"requestId":"1","message":"Hi, Server!"}'
{
"messageId": 1,
"reply": {
"data": {
"requestId": "1",
"message": "Hi, Iola!"
},
"format": "json"
}
}
`

Socket.IO

iola relies on Socket.IO v4. Please check a version compatibility.

$ iola help io
Usage: iola io [options] <address>
Run socket.io client
Options:
  --api-port <port>             Set api port (default: "3000")
  --api-host <host>             Set api host (default: "127.0.0.1")
  --header <key:value...>       Set http headers
  --auth <key:value...>         Set authentication payload
  --transport <transport>       Set transport (choices: "websocket","polling")
  --reply-timeout <timeout>     Set reply timeout in ms (default: "1000")
  --binary-encoding <encoding>  Set binary encoding (choices: "ascii","utf8","base64","hex")
  --no-emoji                    Disable emoji
  --help                        Display help
Examples: 
  $ iola io 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 io http://127.0.0.1:8080 --binary-encoding utf8 
  $ iola io http://127.0.0.1:8080 --reply-timeout 3000 --no-emoji

$3

* string
* number
* boolean
* null
* json
* byte-array

$3

Client supports "websocket" and "polling" transports. It tries to use "websocket" first, if available.
You can explicitly set the type of transport using --transport option.

$3

Socket.IO client can send auth credentials using --auth option.

$3

You can pass event name to sending message. Default event name - *.

`shell
$ http POST http://127.0.0.1:3000/messages event='greeting' data='Hi, Server!'
{
"messageId": 1,
"reply": {
"data": {
"message": "Hi, Iola!"
},
"event": "greeting",
"format": "json"
}
}
`

$3

Socket.IO client supports server replies by default.

TCP & Unix socket

TCP and Unix socket clients have the same api.

$ iola help tcp|unix
 
Usage: iola tcp|unix [options] <address>
Run tcp|unix client
Options:
  --api-port <port>             Set api port (default: "3000")
  --api-host <host>             Set api host (default: "127.0.0.1")
  --sync                        Enable sync mode
  --reply-timeout <timeout>     Set reply timeout in ms (sync mode only) (default: "1000")
  --binary-encoding <encoding>  Set binary encoding (choices: "ascii","utf8","base64","hex")
  --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
  $ iola unix ./unix.sock
  $ iola unix ./unix.sock --sync
  $ iola unix ./unix.sock --binary-encoding utf8 
  $ iola unix ./unix.sock --no-emoji

$3

* byte-array

$3

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 connection will be closed either on the server side after a successful response or by a timeout on the client side.
To enable sync mode you need to set --sync` option.

$3

Server replies are supported only in sync mode.
If the server does not close the connection after receiving the request, the client will close it itself by reply timeout.

License

This project is licensed under the MIT License.