Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/pvarentsov/iola

🔄 iola: Command-line socket client with REST API.
https://github.com/pvarentsov/iola

iola socket-client socketio-client tcp-client unix-socket-client websocket-client

Last synced: 2 months ago
JSON representation

🔄 iola: Command-line socket client with REST API.

Host: GitHub
URL: https://github.com/pvarentsov/iola
Owner: pvarentsov
License: mit
Created: 2021-05-11T09:09:18.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2023-10-12T21:28:39.000Z (12 months ago)
Last Synced: 2024-05-13T01:41:24.782Z (5 months ago)
Topics: iola, socket-client, socketio-client, tcp-client, unix-socket-client, websocket-client
Language: TypeScript
Homepage:
Size: 15.5 MB
Stars: 149
Watchers: 6
Forks: 15
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome-cli-apps - iola - Socket client with REST API. (Development / Chat)
fucking-awesome-cli-apps - iola - Socket client with REST API. (Development / Chat)
awesome-nestjs - iola - Socket client with Rest API. (Projects using NestJS)

README

🔄 iola

Table of contents (click to open)

Description

Installation

Usage

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](https://www.postman.com/), [Insomnia](https://insomnia.rest/), 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](https://nodejs.org/en/) >= 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](https://github.com/pvarentsov/iola/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](https://httpie.io) 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

### 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

```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](https://socket.io/docs/v4/client-installation/#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 ` option.

### Auth

Socket.IO client can send [auth credentials](https://socket.io/docs/v4/middlewares/#sending-credentials) using `--auth ` option.

### Pass event

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

### 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](https://github.com/pvarentsov/iola/blob/main/LICENSE).