iosignal

English | 한국어

A real-time messaging library for Node.js and browsers, providing WebSocket client–server communication, tag-based publish/subscribe and RPC services. Node.js also supports TCP through IOCongSocket.

Documentation and supported environments

The official documentation covers installation, messaging concepts and platform guides in Korean. Follow the five-minute quick start for an overview, and use the quick start below for examples targeting the current version.

| Environment / tool | Support | Package / examples | | --- | --- | --- | | Node.js | WebSocket/TCP servers and clients, publish/subscribe, RPC | This repository · npm | | Browsers | WebSocket clients and web app integration | iosignal/io · examples | | Arduino | Device communication with servers and web apps, authentication and encryption | iosignal-arduino | | CLI | Run servers and clients and test messaging in a terminal | iosignal-cli |

Try messaging in the browser communication workbench.

Installation

npm install iosignal

The Node.js examples below use ESM. Save them as .mjs files or set "type": "module" in your project's package.json.

Quick start

Server

Save the following as server.mjs and run node server.mjs.

import { Server, replyService } from 'iosignal';

const server = new Server({ port: 8080 });
server.attach('reply', replyService);

server.on('ready', () => {
  console.log(`Listening on port ${server.port}`);
});

process.once('SIGINT', () => server.close());

This is a local development server without authentication.

Node.js client

After starting the server, save the following as client.mjs and run node client.mjs.

import { IO } from 'iosignal';

const io = new IO('ws://localhost:8080');
io.on('error', console.error);

io.on('ready', async () => {
  try {
    const response = await io.call('reply', 'echo', 'Hello, iosignal!');
    console.log(response.body);
  } catch (error) {
    console.error(error);
  } finally {
    io.stop();
  }
});

The public API is also available from CommonJS.

const { IO, Server, replyService } = require('iosignal');

Publish and subscribe

Once connected, use subscribe() to subscribe to a tag and signal() to send messages. The following client keeps receiving messages.

import { IO } from 'iosignal';

const io = new IO('ws://localhost:8080');
io.on('error', console.error);
io.on('message', (tag, message) => {
  console.log(tag, message);
});
io.on('ready', () => {
  io.subscribe('room');
  io.signal('room', 'Hello, subscribers!');
});

process.once('SIGINT', () => io.stop());

signal(tag, ...args) supports strings, binary data, objects and multiple arguments. Use unsubscribe(tag) to unsubscribe.

See the messaging guide for tag rules and direct-message handling.

Browsers

For browser projects using a bundler, import the browser-specific entry point.

import IO from 'iosignal/io';

const io = new IO('ws://localhost:8080');
io.on('error', console.error);
io.on('message', (tag, message) => console.log(tag, message));
io.on('ready', () => {
  io.subscribe('room');
  io.signal('room', 'Hello from the browser!');
});

This browser example connects to the same server above. From an HTTPS page, use a wss:// server URL with TLS configured. When finished, call io.stop() to close the connection and stop automatic reconnection.

Arduino support

iosignal-arduino provides an Arduino client and examples for boards including ESP32 and ESP8266. Install the library and its Boho and Crypto dependencies, then configure the network and server in an example for your board. See the official Arduino guide and library README for setup and connection instructions.

CLI support

iosignal-cli runs a server or an interactive client without writing application code. Requires Node.js 22.16.0 or later.

npm install -g iosignal-cli
io-server -l 8080

Connect from another terminal. If the JavaScript server above is already running, run only the client:

io-client -c ws://localhost:8080

Enter help, sub room and pub room hello in the client to explore messaging. To also test Arduino over TCP, start the server with io-server -l 8080 -L 8888 and connect the device to TCP port 8888. See the CLI README for more options.

Main APIs

| API | Purpose | | --- | --- | | Server | Create a WebSocket/TCP server | | IO | Node.js WebSocket client; the browser client when imported from iosignal/io | | IOCongSocket | Node.js TCP client | | server.attach(name, service) | Register an RPC service | | io.call(service, command, ...args) | Make an RPC request | | io.subscribe(tag) / io.unsubscribe(tag) | Subscribe / unsubscribe | | io.signal(tag, ...args) | Publish or send a direct message | | io.on(tag, handler) | Register an event handler | | io.listen(tag, handler) | Register a handler; remember subscriptions for non-direct tags | | io.ping() | Ping the server; receive the protocol pong event | | io.stop() | Stop automatic reconnection and clean up the connection | | server.close(callback) | Shut down the server | | BohoAuth | Server authentication manager | | StringKeyProvider, FileKeyProvider, RedisKeyProvider | Authentication key providers |

Authentication and encryption

Boho provides shared-key authentication and message encryption for JavaScript and Arduino. End-to-end encryption (E2E) uses a separate data key shared only by the final endpoints. See the Boho technical guide for key management, the relationship with TLS, session validation and implementation conditions.

Detailed guides

• Signal tags and direct messages
• Server ping and peer ping
• Boho authentication, encryption and E2E
• Building and verification

License

Package license: MIT.