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

REST API

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

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.

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.

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.