@siemsiem/tonpleun 1.1.3 → 2.0.0

package/readme.md

@@ -1,28 +1,34 @@
-# tonpleun  
+# Tonpleun: Server-to-Server Communication via WebSockets
 
-uhhh dit zijn zeer goede docs (nee)
-tonpleun is een websocket server die websocket clients verzoeken laat maken aan andere websocket clients die zich als service registreren.
-voor nu is tonpleun in js maar wrs moet ik het porten naar python omdat ik dan meer code kan hergebruiken voor andere projecten.
+## What Is Tonpleun?
 
-## Installatie
+Tonpleun is a communication layer that lets servers call functions on other servers and perform basic WebSocket communication with other servers or local clients.
 
-gebruik dit gewoon niet...
+It is designed to make building a network of communicating servers easier, without having to manage all low-level communication details yourself.
 
-maar als je het toch wilt gebruiken download de repo compile het met tsc en run main.js met node.
+## Features
 
-## Gebruik
+- Call functions on other servers
+- Send messages to other servers (message handling logic is up to your app)
+- Register config values that other clients can update
+- Basic client privilege levels
+- Simple API for registering and calling services
+- Optional schema-based validation for service input/output (for example with Zod)
 
-gebruik het niet  
-maar als je onverstandig genoeg bent om het toch te gebruiken gebruik lib.ts om een client te maken die verbinding maakt met de tonpleun server.
+## Installation
 
-## Configuratie
+```bash
+npm install tonpleun
+```
 
-tonpleun heeft geen configuratie opties.
+## Usage
 
-## Licentie
+See [run-server.ts](./run-server.ts) and [test-client.ts](./test-client.ts) for example usage.
 
-heel eerlijk het boeit me niet wat je doet met deze slechte code dus doe er mee wat je wilt.
+## AI-Generated Code
 
-## Bijdragen
+Some small parts of this codebase were made with AI assistance.
 
-uhhhhh maak een pr ofzo.  
+The major AI-assisted parts are the schema validation and the WebUI (idfk how to make a build script). This README was also improved with Copilot help for readability.
+
+English is not my first language, and I have dyslexia, so this workflow helps me write clearer documentation faster.

package/src/clientLib.ts

@@ -1,178 +1,287 @@
 import WebSocket from 'ws';
 import { randomUUID } from 'crypto';
-import { requestType, stringPacketOptions, type getServicePacketClient, type GetServiceResponsePacketToServer, type GetServiceResponsePacketToClient, type InitPacket, type packet, type StringPacket, type registerConfigPacket, type setConfigPacket, type fakeTypeType, type namedFakeType, InitResponsePacket } from './types.js';
+import {
+  requestType,
+  stringPacketOptions,
+  type getServicePacketClient,
+  type GetServiceResponsePacketToServer,
+  type GetServiceResponsePacketToClient,
+  type InitPacket,
+  type packet,
+  type StringPacket,
+  type registerConfigPacket,
+  type setConfigPacket,
+  InitResponsePacket,
+  getServicePacketClientSchema,
+  getServiceResponsePacketToClientSchema,
+  initResponsePacketSchema,
+  packetSchema,
+  setConfigPacketSchema,
+  stringPacketSchema
+} from './types.js';
 import { WsSend } from './helpers.js';
 import { assert } from 'console';
 import { writeFileSync, mkdirSync } from 'fs';
 import { dirname } from 'path';
 
-const url = "ws://localhost:8765";
-export let ws: WebSocket;
-const serviceCallbacks = new Map<string, (...args: any[]) => any>();
-let clinetIDStore = "error";
-const localConfigs = new Map<string, registerConfigPacket>();
-let key: any = undefined;
+type ValidationSuccess = {
+  success: true;
+  data: unknown;
+};
 
-const VERSION = {
-    MAJOR: 1,
-    MINOR: 1,
-    PATCH: 3
-}
-export async function genHelper() {
-    console.info('genHelper called');
-    const result = await getService('genHelper', 'tonpleun', []);
+type ValidationFailure = {
+  success: false;
+  error?: {
+    issues?: unknown;
+  } | unknown;
+};
 
-    const outPath = dirname('./src/GEN.ts');
-    mkdirSync(outPath, { recursive: true });
-    writeFileSync('./src/GEN.ts', result);
-    console.info('GEN.ts gegenereerd in ./src/GEN.ts');
-    return result;
-}
+export type ServiceInputValidator = {
+  safeParse: (data: unknown) => ValidationSuccess | ValidationFailure;
+};
 
-export async function awaitServiceMessage(expectedFor: stringPacketOptions): Promise<StringPacket> {
-    return new Promise<StringPacket>((resolve) => {
-        const handler = (raw: Buffer) => {
-            const rawPacket = JSON.parse(raw.toString()) as packet;
-            if (rawPacket.type === requestType.Success) {
-                const data = rawPacket.data as StringPacket;
-                if (data.for === expectedFor) {
-                    ws.removeListener('message', handler);
-                    resolve(data);
-                }
-            }
-        };
-        ws.on('message', handler);
-    });
-}
-export async function registerConfigItem(name: string, description: string, value: string, idthing: string) {
+export default class Tonpleun {
+  private url = "ws://localhost:8765";
+  public ws: WebSocket;
+  private serviceCallbacks = new Map<string, (...args: any[]) => any>();
+  private serviceInputSchemas = new Map<string, ServiceInputValidator>();
+  private clinetIDStore = "error";
+  private localConfigs = new Map<string, registerConfigPacket>();
+  private key: any = undefined;
+  public initialized: Promise<StringPacket>;
 
-    WsSend(ws, { type: requestType.RegisterConifg, data: { name: name, description: description, defaultValue: value, type: typeof value, id: idthing } as registerConfigPacket, key })
-    // Wacht tot de verbinding is geopend
-    return new Promise<void>((resolve) => {
-        awaitServiceMessage(stringPacketOptions.registerConfigSuccess).then(() => {
-            localConfigs.set(idthing, { name, id: idthing, description, type: typeof value as fakeTypeType, defaultValue: value } as registerConfigPacket)
-            resolve();
-        });
-    });
-}
-export async function SetConfigItem(idthing: string, newValue: string, clientId?: string) {
-    WsSend(ws, { type: requestType.SetConfig, data: { ClientId: clientId || clinetIDStore, id: idthing, newValue: newValue } as setConfigPacket, key })
-    return new Promise<void>((resolve) => {
-        awaitServiceMessage(stringPacketOptions.setConfigSuccess).then(() => {
-            const existing = localConfigs.get(idthing);
-            if (existing) {
-                localConfigs.set(idthing, { ...existing, value: newValue } as registerConfigPacket);
-            }
-            resolve();
-        });
-    });
-}
+  private VERSION = {
+    MAJOR: 2,
+    MINOR: 0,
+    PATCH: 0
+  }
 
-export async function registerService(ServiceId: string, args: namedFakeType[], callback: (...args: any[]) => any) {
-    WsSend(ws, { type: requestType.RegisterService, data: { ServiceId, args }, key });
-    serviceCallbacks.set(ServiceId, callback);
-    return new Promise<void>((resolve) => {
-        awaitServiceMessage(stringPacketOptions.registerServiceSuccess).then(() => {
-            resolve();
-        });
+  public async awaitServiceMessage(expectedFor: stringPacketOptions): Promise<StringPacket> {
+    return new Promise<StringPacket>((resolve) => {
+      const handler = (raw: Buffer) => {
+        let parsedRaw: unknown;
+        try {
+          parsedRaw = JSON.parse(raw.toString());
+        } catch {
+          return;
+        }
+        const packetResult = packetSchema.safeParse(parsedRaw);
+        if (!packetResult.success) {
+          return;
+        }
+        const rawPacket = packetResult.data as packet;
+        if (rawPacket.type === requestType.Success) {
+          const stringResult = stringPacketSchema.safeParse(rawPacket.data);
+          if (!stringResult.success) {
+            return;
+          }
+          const data = stringResult.data as StringPacket;
+          if (data.for === expectedFor) {
+            this.ws.removeListener('message', handler);
+            resolve(data);
+          }
+        }
+      };
+      this.ws.on('message', handler);
     });
-}
-export async function getService(ServiceId: string, ClientId: string, inputs: any[]): Promise<any> {
+  }
+  public async registerConfigItem(name: string, description: string, value: string, idthing: string) {
+    await this.initialized;
+    const waitForAck = this.awaitServiceMessage(stringPacketOptions.registerConfigSuccess);
+    WsSend(this.ws, { type: requestType.RegisterConifg, data: { name: name, description: description, defaultValue: value, type: typeof value, id: idthing } as registerConfigPacket, key: this.key })
+    await waitForAck;
+    this.localConfigs.set(idthing, { name, id: idthing, description, type: typeof value as registerConfigPacket['type'], defaultValue: value } as registerConfigPacket)
+  }
+  public async SetConfigItem(idthing: string, newValue: string, clientId?: string) {
+    await this.initialized;
+    const waitForAck = this.awaitServiceMessage(stringPacketOptions.setConfigSuccess);
+    WsSend(this.ws, { type: requestType.SetConfig, data: { ClientId: clientId || this.clinetIDStore, id: idthing, newValue: newValue } as setConfigPacket, key: this.key })
+    await waitForAck;
+    const existing = this.localConfigs.get(idthing);
+    if (existing) {
+      this.localConfigs.set(idthing, { ...existing, value: newValue } as registerConfigPacket);
+    }
+  }
+  public async registerService(ServiceId: string, callback: (...args: any[]) => any, inputSchema?: ServiceInputValidator) {
+    await this.initialized;
+    const waitForAck = this.awaitServiceMessage(stringPacketOptions.registerServiceSuccess);
+    this.serviceCallbacks.set(ServiceId, callback);
+    if (inputSchema) {
+      this.serviceInputSchemas.set(ServiceId, inputSchema);
+    }
+    WsSend(this.ws, { type: requestType.RegisterService, data: { ServiceId }, key: this.key });
+    await waitForAck;
+  }
+  public async getService(ServiceId: string, ClientId: string, inputs: any[]): Promise<any> {
+    await this.initialized;
     const connectionId = randomUUID();
-    WsSend(ws, { type: requestType.GetService, data: { ClientId, ServiceId, args: inputs, connectionId } as getServicePacketClient, key });
-    return new Promise<any>((resolve) => {
-        const handler = (raw: Buffer) => {
-            const rawPacket = JSON.parse(raw.toString()) as packet;
-            if (rawPacket.type === requestType.GetServiceResponse) {
-                const data = rawPacket.data as GetServiceResponsePacketToClient;
-                if (data.serviceId === ServiceId && data.connectionId === connectionId) {
-                    ws.removeListener('message', handler);
-                    resolve(data.result);
-                }
-            }
-        };
-        ws.on('message', handler);
+    const responsePromise = new Promise<any>((resolve) => {
+      const handler = (raw: Buffer) => {
+        let parsedRaw: unknown;
+        try {
+          parsedRaw = JSON.parse(raw.toString());
+        } catch {
+          return;
+        }
+        const packetResult = packetSchema.safeParse(parsedRaw);
+        if (!packetResult.success) {
+          return;
+        }
+        const rawPacket = packetResult.data as packet;
+        if (rawPacket.type === requestType.GetServiceResponse) {
+          const responseResult = getServiceResponsePacketToClientSchema.safeParse(rawPacket.data);
+          if (!responseResult.success) {
+            return;
+          }
+          const data = responseResult.data as GetServiceResponsePacketToClient;
+          if (data.serviceId === ServiceId && data.connectionId === connectionId) {
+            this.ws.removeListener('message', handler);
+            resolve(data.result);
+          }
+        }
+      };
+      this.ws.on('message', handler);
     });
-}
-
-export async function initializeClient(ClientId: string, creds?: any) {
-    clinetIDStore = ClientId;
-    key = creds;
-    ws = new WebSocket(url);
+    WsSend(this.ws, { type: requestType.GetService, data: { ClientId, ServiceId, args: inputs, connectionId } as getServicePacketClient, key: this.key });
+    return responsePromise;
+  }
+  constructor(ClientId: string, creds?: any) {
+    this.clinetIDStore = ClientId;
+    this.key = creds;
+    this.ws = new WebSocket(this.url);
 
-    ws.on('open', () => {
-        console.log('Verbonden met tonpleun server.');
-        WsSend(ws, { type: requestType.Init, data: { ClientId } as InitPacket, key })
+    this.ws.on('open', () => {
+      console.log('Verbonden met tonpleun server.');
+      WsSend(this.ws, { type: requestType.Init, data: { ClientId } as InitPacket, key: this.key })
 
     });
-    ws.on('close', () => {
-        console.log('Verbinding met tonpleun server gesloten.');
+    this.ws.on('close', () => {
+      console.log('Verbinding met tonpleun server gesloten.');
     });
-    ws.on('error', (error) => {
-        console.error('Fout opgetreden:', error);
-        ws.close();
+    this.ws.on('error', (error) => {
+      console.error('Fout opgetreden:', error);
+      this.ws.close();
     });
-    ws.on('message', (data) => {
-        const rawPacket = JSON.parse(data.toString()) as packet
-        if (rawPacket.type === requestType.GetService) {
-            const serviceData = rawPacket.data as getServicePacketClient;
-            const callback = serviceCallbacks.get(serviceData.ServiceId);
-            if (callback) {
-                try {
-                    const result = callback(...serviceData.args);
-                    WsSend(ws, {
-                        type: requestType.GetServiceResponse, data: {
-                            result: result,
-                            ServiceId: serviceData.ServiceId,
-                            connectionId: serviceData.connectionId,
-                        } as GetServiceResponsePacketToServer,
-                        key
-                    });
-                } catch (error) {
-                    console.error(`Fout bij uitvoeren van service ${serviceData.ServiceId}:`, error);
-                }
+    this.ws.on('message', (data) => {
+      let parsedRaw: unknown;
+      try {
+        parsedRaw = JSON.parse(data.toString());
+      } catch {
+        return;
+      }
+      const packetResult = packetSchema.safeParse(parsedRaw);
+      if (!packetResult.success) {
+        return;
+      }
+      const rawPacket = packetResult.data as packet
+      if (rawPacket.type === requestType.GetService) {
+        const serviceDataResult = getServicePacketClientSchema.safeParse(rawPacket.data);
+        if (!serviceDataResult.success) {
+          return;
+        }
+        const serviceData = serviceDataResult.data as getServicePacketClient;
+        const callback = this.serviceCallbacks.get(serviceData.ServiceId);
+        if (callback) {
+          try {
+            const schema = this.serviceInputSchemas.get(serviceData.ServiceId);
+            let callbackArgs: any[] = serviceData.args;
+            if (schema) {
+              const schemaResult = schema.safeParse(serviceData.args);
+              if (!schemaResult.success) {
+                const validationError = schemaResult.error;
+                const issues = (typeof validationError === 'object' && validationError !== null && 'issues' in validationError)
+                  ? (validationError as { issues?: unknown }).issues
+                  : validationError;
+                WsSend(this.ws, {
+                  type: requestType.GetServiceResponse, data: {
+                    result: {
+                      error: 'Invalid service input',
+                      issues
+                    },
+                    ServiceId: serviceData.ServiceId,
+                    connectionId: serviceData.connectionId,
+                  } as GetServiceResponsePacketToServer,
+                  key: this.key
+                });
+                return;
+              }
+              callbackArgs = Array.isArray(schemaResult.data) ? schemaResult.data : [schemaResult.data];
             }
 
-        } else if (rawPacket.type === requestType.SetConfig) {
-            const cfg = rawPacket.data as setConfigPacket;
-            const existing = localConfigs.get(cfg.id);
-            if (existing) {
-                localConfigs.set(cfg.id, { ...existing, value: cfg.newValue } as registerConfigPacket);
-            }
+            const result = callback(...callbackArgs);
+            WsSend(this.ws, {
+              type: requestType.GetServiceResponse, data: {
+                result: result,
+                ServiceId: serviceData.ServiceId,
+                connectionId: serviceData.connectionId,
+              } as GetServiceResponsePacketToServer,
+              key: this.key
+            });
+          } catch (error) {
+            console.error(`Fout bij uitvoeren van service ${serviceData.ServiceId}:`, error);
+          }
         }
-    });
 
-    return new Promise<StringPacket>((resolve) => {
-        const handler = (raw: Buffer) => {
-            const rawPacket = JSON.parse(raw.toString()) as packet;
-            if (rawPacket.type === requestType.Init) {
-                const data = rawPacket.data as InitResponsePacket;
-                assert(data.versionMajor === VERSION.MAJOR, `Major versie mismatch: Client versie is ${VERSION.MAJOR}, server versie is ${data.versionMajor}.`);
-                if (data.versionMinor !== VERSION.MINOR) {
-                    console.warn(`Waarschuwing: Minor versie mismatch: Client versie is ${VERSION.MINOR}, server versie is ${data.versionMinor}. Mogelijk zijn er incompatibiliteiten.`);
-                }
-                if (data.versionPatch !== VERSION.PATCH) {
-                    console.warn(`Waarschuwing: Patch versie mismatch: Client versie is ${VERSION.PATCH}, server versie is ${data.versionPatch}. Mogelijk zijn er bugs of ontbrekende functies.`);
-                }
-                ws.removeListener('message', handler);
-                console.info('Client geïnitialiseerd met versie:', data.versionMajor, data.versionMinor, data.versionPatch);
-                console.info('gebruik via GEN.ts is aanbevolen')
-                resolve({ for: stringPacketOptions.initSuccess, msg: 'Init succesvol' } as StringPacket);
-            }
-        };
-        ws.on('message', handler);
+      } else if (rawPacket.type === requestType.SetConfig) {
+        const setConfigResult = setConfigPacketSchema.safeParse(rawPacket.data);
+        if (!setConfigResult.success) {
+          return;
+        }
+        const cfg = setConfigResult.data as setConfigPacket;
+        const existing = this.localConfigs.get(cfg.id);
+        if (existing) {
+          this.localConfigs.set(cfg.id, { ...existing, value: cfg.newValue } as registerConfigPacket);
+        }
+      }
+    });
+    this.initialized = new Promise<StringPacket>((resolve) => {
+      const handler = (raw: Buffer) => {
+        let parsedRaw: unknown;
+        try {
+          parsedRaw = JSON.parse(raw.toString());
+        } catch {
+          return;
+        }
+        const packetResult = packetSchema.safeParse(parsedRaw);
+        if (!packetResult.success) {
+          return;
+        }
+        const rawPacket = packetResult.data as packet;
+        if (rawPacket.type === requestType.Init) {
+          const initResult = initResponsePacketSchema.safeParse(rawPacket.data);
+          if (!initResult.success) {
+            return;
+          }
+          const data = initResult.data as InitResponsePacket;
+          assert(data.versionMajor === this.VERSION.MAJOR, `Major versie mismatch: Client versie is ${this.VERSION.MAJOR}, server versie is ${data.versionMajor}.`);
+          if (data.versionMinor !== this.VERSION.MINOR) {
+            console.warn(`Waarschuwing: Minor versie mismatch: Client versie is ${this.VERSION.MINOR}, server versie is ${data.versionMinor}. Mogelijk zijn er incompatibiliteiten.`);
+          }
+          if (data.versionPatch !== this.VERSION.PATCH) {
+            console.warn(`Waarschuwing: Patch versie mismatch: Client versie is ${this.VERSION.PATCH}, server versie is ${data.versionPatch}. Mogelijk zijn er bugs of ontbrekende functies.`);
+          }
+          this.ws.removeListener('message', handler);
+          console.info('Client geïnitialiseerd met versie:', data.versionMajor, data.versionMinor, data.versionPatch);
+          resolve({ for: stringPacketOptions.initSuccess, msg: 'Init succesvol' } as StringPacket);
+        }
+      };
+      this.ws.on('message', handler);
     });
-}
 
-export function getConfigValue(id: string): any | undefined {
-    const item = localConfigs.get(id);
+  }
+
+  public getConfigValue(id: string): any | undefined {
+    const item = this.localConfigs.get(id);
     return item ? (item.value ?? item.defaultValue) : undefined;
-}
-export const TESTING_HELPERS = {
+  }
+  public TESTING_HELPERS = {
     done: () => {
-        ws.send(JSON.stringify({ type: requestType.Success, data: { msg: 'done', for: stringPacketOptions.initSuccess } as StringPacket, key }));
+      this.ws.send(JSON.stringify({ type: requestType.Success, data: { msg: 'done', for: stringPacketOptions.initSuccess } as StringPacket, key: this.key }));
     },
     error: (msg: string) => {
-        ws.send(JSON.stringify({ type: requestType.Success, data: { msg: msg, for: stringPacketOptions.initSuccess } as StringPacket, key }));
+      this.ws.send(JSON.stringify({ type: requestType.Success, data: { msg: msg, for: stringPacketOptions.initSuccess } as StringPacket, key: this.key }));
     }
-}
+  }
+
+
+}