Tonpleun

Server-to-Server Communication via WebSockets

A lightweight communication layer that lets servers call functions on other servers and perform WebSocket communication effortlessly.

npm install @siemsiem/tonpleun

Features

Remote Function Calls

Call functions on other servers as easily as calling local functions.

Server-to-Server Messaging

Send messages between servers with custom handling logic.

Schema Validation

Optional input/output validation with Zod schemas.

Config Management

Register config values that clients can update dynamically.

Privilege Levels

Basic client privilege system for access control.

Simple API

Easy-to-use API for registering and calling services.

Installation

Install via npm
npm install @siemsiem/tonpleun
Requirements
  • Node.js (latest LTS version recommended)
  • WebSocket support (ws package included)
  • Optional: Zod for schema validation

Examples

Basic Server Setup

import startServer from '@siemsiem/tonpleun/server'

// Start a Tonpleun server (defaults to ws://localhost:8765)
startServer()

Registering a Service

import Tonpleun from '@siemsiem/tonpleun'
import { z } from 'zod'

// Create a client instance with a unique ID
const provider = new Tonpleun('provider-server')

// Wait for initialization before registering services
await provider.initialized

// Register a simple service
await provider.registerService(
    'add',
    (a: number, b: number) => a + b
)

// Register a service with Zod validation
const multiplySchema = z.tuple([z.number(), z.number()])

await provider.registerService(
    'multiply',
    (a: number, b: number) => a * b,
    multiplySchema  // Optional input validation
)

Calling Remote Services

import Tonpleun from '@siemsiem/tonpleun'

// Create consumer client
const consumer = new Tonpleun('consumer-client')

// Wait for initialization
await consumer.initialized

// Call a service on another client
// getService(ServiceId, ClientId, args)
const result = await consumer.getService('add', 'provider-server', [5, 3])

console.log(result) // 8

// If validation fails, you'll get an error object
const invalid = await consumer.getService('add', 'provider-server', ['x', 3])
// Returns: { error: 'Invalid service input', issues: [...] }

Complete Example

import Tonpleun from '@siemsiem/tonpleun'
import { z } from 'zod'

async function main() {
    // Create two clients
    const provider = new Tonpleun('provider')
    const consumer = new Tonpleun('consumer')

    // Define validation schema
    const addArgsSchema = z.tuple([z.number(), z.number()])

    // Register service on provider
    await provider.registerService(
        'add',
        (a: number, b: number) => a + b,
        addArgsSchema
    )

    // Call service from consumer
    const result = await consumer.getService('add', 'provider', [2, 3])
    
    if (result !== 5) {
        throw new Error(`Expected 5, got: ${result}`)
    }

    console.log('Success! 2 + 3 =', result)
}

main()

Config Management

import Tonpleun from '@siemsiem/tonpleun'

const client = new Tonpleun('config-manager')
await client.initialized

// Register a config item
await client.registerConfigItem(
    'maxConnections',           // name
    'Maximum connections',      // description
    '100',                      // default value
    'max-conn-id'              // unique ID
)

// Update config value
await client.SetConfigItem('max-conn-id', '200')

// Get config value locally
const value = client.getConfigValue('max-conn-id')
console.log('Max connections:', value) // '200'

API Reference

Creates a new Tonpleun client instance. Connects to ws://localhost:8765 by default.

Parameters:
  • ClientId (string) - Unique identifier for this client
  • creds (any, optional) - Authentication credentials
Properties:
  • initialized - Promise that resolves when client is ready
  • ws - WebSocket instance

Registers a service that can be called by other clients.

Parameters:
  • ServiceId (string) - Unique service identifier
  • callback (Function) - Function to execute when service is called
  • inputSchema (optional) - Zod schema for input validation
Returns: Promise<void>

Calls a service registered on another client.

Parameters:
  • ServiceId (string) - Service identifier to call
  • ClientId (string) - Target client that has the service
  • inputs (any[]) - Array of arguments to pass
Returns: Promise<any> - Result from the service or error object

Registers a configuration item that can be updated.

Parameters:
  • name (string) - Config name
  • description (string) - Config description
  • value (string) - Default value
  • id (string) - Unique identifier
Returns: Promise<void>

Updates a configuration item value.

Parameters:
  • id (string) - Config identifier
  • newValue (string) - New value
  • clientId (string, optional) - Target client
Returns: Promise<void>

Gets a local configuration value.

Parameters:
  • id (string) - Config identifier
Returns: any | undefined