🔄 iola

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).

$ npm install -g iola

Via homebrew (Linux, macOS).

$ brew tap pvarentsov/iola
$ brew install iola

Via scoop (Windows).

$ scoop bucket add iola https://github.com/pvarentsov/scoop-iola.git
$ scoop install iola

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

Usage

CLI

$ 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

REST API

Note: These examples use HTTPie as the REST API client.

Send any data

# 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

# 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 <encoding> option for more readability of sent and received binary messages.

# 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

# 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

Message formats

• string
• json
• byte-array

Server replies

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

$ 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

Message formats

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

Transports

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.

Auth

Socket.IO client can send auth credentials using --auth <key:value...> option.

Pass event

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

$ 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"
    }
}

Server replies

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

Message formats

• byte-array

Modes

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.

Server replies

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.