Koshare Router Server/Client for Node.js

• Koshare Router Server/Client for Node.js
  • What's Koshare Router
  • Protocol Specification
  • API
    • Client
    • Server
  • License

What's Koshare Router

Koshare Router is a simple publish/subscribe protocol based on WebSocket designed by @gladkikhartem.

The original C++ server implementation is at gladkikhartem/koshare-router.

Since the original repository has been archived, and the original public server has been shut down, I created this Node.js implementation based on ws.

This server implementation is "almost" fully compatible with the original C++ one. And I have a public server at wss://chensi.moe/koshare.

Protocol Specification

Read here.

API

Client

type ForwardPacketHandler<T> = (packet: ForwardPacket<T>) => void;

class KoshareClient {
    static connect(endpoint: string, prefix?: string): Promise<KoshareClient>;

    subscribe<T extends object>(topic: string, handler: ForwardPacketHandler<T>): Promise<void>;

    unsubscribe(topic: string): Promise<void>;
    unsubscribe<T extends object>(topic: string, handler: ForwardPacketHandler<T>): Promise<void>;

    broadcast<T extends object>(topic: string, body?: T): Promise<void>;
    message<T extends object>(topic: string, destination: number, body?: T): Promise<void>;

    close(): void;
}

Example:

import { KoshareClient } from '@yume-chan/koshare-router';

(async () => {
    const echo = await KoshareClient.connect('wss://chensi.moe/koshare');
    await echo.subscribe('echo', async (packet) => {
        await echo.message('echo', packet.src, { ...packet, type: undefined, topic: undefined, src: undefined, dst: undefined });
    });

    const client = await KoshareClient.connect('wss://chensi.moe/koshare');
    await client.subscribe('echo', (packet) => {
        console.log(packet);
    });
    await client.broadcast('echo', { content: 'test' });

    echo.close();
    client.close();
})();

Server

class KoshareServer extends EventEmitter {
    static create(options?: import('ws').ServerOptions): Promise<KoshareServer>;

    readonly socket: import('ws').Server;

    on<T>(type: 'packet', listener: (packet: ClientPacket<T>) => void): this;

    handleUpgrade(request: import('http').IncomingMessage, socket: import('net').Socket, upgradeHead: Buffer): void;

    close(): void;
}

Example:

import { KoshareServer } from '@yume-chan/koshare-router';

(async () => {
    const server = KoshareServer.create({ port: 8080 });

    server.close();
})();

License

MIT