@plexspaces/sdk 0.1.7 → 0.1.8

package/dist/ws_thin_client.js

@@ -0,0 +1,302 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2025 PlexSpaces Contributors
+//
+// WsThinClient — browser and Node.js WebSocket thin-node client.
+//
+// Speaks the binary protobuf WsFrame protocol defined in
+// proto/plexspaces/v1/transport/websocket.proto.
+//
+// Usage:
+//   const client = new WsThinClient({ wsUrl: 'ws://localhost:8091/ws', jwtToken });
+//   const nodeId = await client.connect();
+//   const myId = client.localActorId('alice', 'ChatClient', 'chat');
+//   await client.tell(chatRoomId, 'send', { text: 'hello' });
+//   const reply = await client.ask(chatRoomId, 'status', {});
+//   client.onMessage((from, msgType, payload) => console.log(from, msgType, payload));
+//   await client.disconnect();
+import { decodeWsFrame, encodeWsFrameAsk, encodeWsFrameHeartbeat, encodeWsFrameNodePing, encodeWsFrameNodeRegister, encodeWsFrameTell, } from './wire/ws-frame-wire.js';
+// ─── Inline ULID generator (Crockford base32, ~20 lines, zero deps) ─────────
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+function newUlid() {
+    const now = Date.now();
+    // 10-char timestamp component (48 bits → 10 Crockford base32 chars)
+    let t = now;
+    let ts = '';
+    for (let i = 9; i >= 0; i--) {
+        ts = CROCKFORD[t % 32] + ts;
+        t = Math.floor(t / 32);
+    }
+    // 16-char randomness component (80 bits → 16 Crockford base32 chars)
+    // 10 bytes × 8 bits = 80 bits; bit-pack into 16 × 5-bit groups.
+    const rb = new Uint8Array(10);
+    if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+        crypto.getRandomValues(rb);
+    }
+    else {
+        for (let i = 0; i < 10; i++)
+            rb[i] = Math.floor(Math.random() * 256);
+    }
+    let rand = '';
+    let acc = 0, bits = 0;
+    for (let i = 0; i < 10; i++) {
+        acc = (acc << 8) | rb[i];
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            rand += CROCKFORD[(acc >>> bits) & 0x1f];
+        }
+    }
+    // 10×8=80 bits, 80/5=16 chars exactly; bits===0 here.
+    return ts + rand; // 10 + 16 = 26 chars — valid ULID
+}
+// ─── WsThinClient ────────────────────────────────────────────────────────────
+export class WsThinClient {
+    constructor(opts) {
+        this.opts = opts;
+        this.ws = null;
+        this.assignedNodeId = '';
+        this.pendingAsks = new Map();
+        this.pendingPings = new Map();
+        this.pendingReg = null;
+        this.messageHandler = null;
+        this.heartbeatTimer = null;
+        this.HEARTBEAT_INTERVAL_MS = 25000;
+        this.DEFAULT_ASK_TIMEOUT_MS = 5000;
+    }
+    /**
+     * Open the WebSocket, complete the NodeRegistration handshake, and start the
+     * heartbeat loop.  Returns the server-assigned node_id.
+     */
+    async connect() {
+        return new Promise((resolve, reject) => {
+            // Build URL — append token as query param if provided
+            let url = this.opts.wsUrl;
+            if (this.opts.jwtToken) {
+                const sep = url.includes('?') ? '&' : '?';
+                url = `${url}${sep}token=${encodeURIComponent(this.opts.jwtToken)}`;
+            }
+            this.ws = new WebSocket(url);
+            this.ws.binaryType = 'arraybuffer';
+            this.ws.onopen = () => {
+                // Send NodeRegistration as first frame
+                const nodeId = this.opts.nodeId ?? newUlid();
+                const capabilities = {};
+                if (this.opts.tenant)
+                    capabilities['tenant'] = this.opts.tenant;
+                if (this.opts.namespace)
+                    capabilities['namespace'] = this.opts.namespace;
+                // Include client resource hints if available (browser context)
+                if (typeof navigator !== 'undefined') {
+                    capabilities['cpu_cores'] = String(navigator.hardwareConcurrency ?? 1);
+                }
+                // Collect browser resource hints for NodeResourceHints field 11
+                const resourceHints = {};
+                if (typeof navigator !== 'undefined') {
+                    resourceHints.availableCores = navigator.hardwareConcurrency ?? 1;
+                }
+                const requestId = newUlid();
+                this.pendingReg = { resolve, reject };
+                const frame = encodeWsFrameNodeRegister(requestId, nodeId, '', capabilities, resourceHints);
+                this.ws.send(frame);
+            };
+            this.ws.onmessage = (ev) => {
+                const buf = ev.data instanceof ArrayBuffer
+                    ? new Uint8Array(ev.data)
+                    : new Uint8Array(ev.data);
+                this.handleFrame(buf);
+            };
+            this.ws.onerror = () => {
+                const err = new Error('WebSocket error');
+                this.rejectAllPending(err);
+                reject(err);
+            };
+            this.ws.onclose = (ev) => {
+                const err = new Error(`WebSocket closed: ${ev.code} ${ev.reason}`);
+                this.rejectAllPending(err);
+                if (this.pendingReg) {
+                    this.pendingReg.reject(err);
+                    this.pendingReg = null;
+                }
+                this.stopHeartbeat();
+            };
+        });
+    }
+    /**
+     * Fire-and-forget. actorId must be the canonical form:
+     *   {name}//{type}::{namespace}@{nodeId}
+     */
+    async tell(actorId, msgType, payload) {
+        const frame = encodeWsFrameTell(newUlid(), actorId, msgType, new TextEncoder().encode(JSON.stringify(payload)));
+        this.send(frame);
+    }
+    /**
+     * Request-reply. Returns the response payload (parsed JSON).
+     * Rejects with a timeout error if no response arrives within timeoutMs.
+     */
+    async ask(actorId, msgType, payload, timeoutMs = this.DEFAULT_ASK_TIMEOUT_MS) {
+        const requestId = newUlid();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingAsks.delete(requestId);
+                reject(new Error(`ask timeout after ${timeoutMs}ms for ${actorId}`));
+            }, timeoutMs);
+            this.pendingAsks.set(requestId, { resolve, reject, timer });
+            const frame = encodeWsFrameAsk(requestId, actorId, msgType, new TextEncoder().encode(JSON.stringify(payload)), timeoutMs);
+            this.send(frame);
+        });
+    }
+    /**
+     * Register a handler for incoming tell frames addressed to this thin node.
+     * Called whenever the server routes a tell to one of this node's actor IDs.
+     */
+    onMessage(handler) {
+        this.messageHandler = handler;
+    }
+    /**
+     * Send a SWIM-compatible ping to a target node and return its resource hints.
+     * The target nodeId must be known to the server (registered in SWIM membership).
+     */
+    async pingNode(targetNodeId, timeoutMs = 5000) {
+        const requestId = newUlid();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingPings.delete(requestId);
+                reject(new Error(`ping timeout for ${targetNodeId}`));
+            }, timeoutMs);
+            this.pendingPings.set(requestId, { resolve, reject, timer });
+            const frame = encodeWsFrameNodePing(requestId, this.assignedNodeId, Date.now());
+            this.send(frame);
+        });
+    }
+    /** Send a heartbeat frame to keep the WS session alive. */
+    async heartbeat() {
+        const frame = encodeWsFrameHeartbeat(newUlid(), this.assignedNodeId);
+        this.send(frame);
+    }
+    /**
+     * Build a canonical actor ID on this thin node.
+     * Format: {name}//{type}::{namespace}@{assignedNodeId}
+     */
+    localActorId(name, type, namespace) {
+        const ns = namespace ?? this.opts.namespace ?? 'default';
+        return `${name}//${type}::${ns}@${this.assignedNodeId}`;
+    }
+    /** The server-assigned node_id (available after connect() resolves). */
+    get nodeId() {
+        return this.assignedNodeId;
+    }
+    /** Generate a new ULID. Exposed so examples can use it without a dep. */
+    static newUlid() {
+        return newUlid();
+    }
+    /** Disconnect and clean up. */
+    async disconnect() {
+        this.stopHeartbeat();
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            this.ws.close(1000, 'client disconnect');
+        }
+        this.ws = null;
+    }
+    // ─── Private ──────────────────────────────────────────────────────────────
+    send(data) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('WsThinClient: not connected');
+        }
+        this.ws.send(data);
+    }
+    handleFrame(buf) {
+        const frame = decodeWsFrame(buf);
+        switch (frame.type) {
+            case 'node_register_ack': {
+                if (this.pendingReg) {
+                    const reg = this.pendingReg;
+                    this.pendingReg = null;
+                    if (frame.success) {
+                        this.assignedNodeId = frame.assignedNodeId;
+                        this.startHeartbeat();
+                        reg.resolve(frame.assignedNodeId);
+                    }
+                    else {
+                        reg.reject(new Error(`registration failed: ${frame.errorMessage}`));
+                    }
+                }
+                break;
+            }
+            case 'ask_response': {
+                const pending = this.pendingAsks.get(frame.requestId);
+                if (pending) {
+                    clearTimeout(pending.timer);
+                    this.pendingAsks.delete(frame.requestId);
+                    if (frame.success) {
+                        pending.resolve(frame.payloadJson);
+                    }
+                    else {
+                        pending.reject(new Error(frame.errorMessage || 'ask failed'));
+                    }
+                }
+                break;
+            }
+            case 'tell_response':
+                // Fire-and-forget — nothing to resolve
+                break;
+            case 'heartbeat_ack':
+                // Heartbeat acknowledged — nothing to do
+                break;
+            case 'node_ping_response': {
+                const pending = this.pendingPings.get(frame.requestId);
+                if (pending) {
+                    clearTimeout(pending.timer);
+                    this.pendingPings.delete(frame.requestId);
+                    pending.resolve({
+                        success: true,
+                        nodeId: frame.nodeId,
+                        cpuPercent: frame.cpuPercent,
+                        memoryAvailableMb: frame.memoryAvailableMb,
+                        availableCores: frame.availableCores,
+                    });
+                }
+                break;
+            }
+            case 'incoming_tell': {
+                if (this.messageHandler) {
+                    this.messageHandler(frame.actorId, frame.msgType, frame.payloadJson);
+                }
+                break;
+            }
+            case 'error': {
+                // Reject the matching pending ask if one exists
+                const pending = this.pendingAsks.get(frame.requestId);
+                if (pending) {
+                    clearTimeout(pending.timer);
+                    this.pendingAsks.delete(frame.requestId);
+                    pending.reject(new Error(`server error ${frame.code}: ${frame.message}`));
+                }
+                break;
+            }
+            // 'unknown' — silently ignored (forward-compatible)
+        }
+    }
+    startHeartbeat() {
+        this.heartbeatTimer = setInterval(() => {
+            this.heartbeat().catch(() => { });
+        }, this.HEARTBEAT_INTERVAL_MS);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer !== null) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    rejectAllPending(err) {
+        for (const [, p] of this.pendingAsks) {
+            clearTimeout(p.timer);
+            p.reject(err);
+        }
+        this.pendingAsks.clear();
+        for (const [, p] of this.pendingPings) {
+            clearTimeout(p.timer);
+            p.reject(err);
+        }
+        this.pendingPings.clear();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plexspaces/sdk",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "PlexSpaces TypeScript SDK - build actors with minimal boilerplate (inheritance-based)",
   "type": "module",
   "main": "dist/index.js",

package/dist/actor.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/actor.test.js

@@ -1,171 +0,0 @@
-// SPDX-License-Identifier: AGPL-3.0-or-later
-// Copyright (C) 2025 PlexSpaces Contributors
-//
-// Unit tests for PlexSpacesActor base class
-import { PlexSpacesActor } from './actor';
-// Mock host.log for testing
-let mockHostLog;
-// Override the import for testing (in real WASM, jco provides this)
-// @ts-ignore - Test override
-global.hostLog = undefined;
-class TestActor extends PlexSpacesActor {
-    getDefaultState() {
-        return { count: 0, name: '' };
-    }
-    onIncrement(payload) {
-        const amount = Number(payload.amount ?? 1);
-        this.state.count += amount;
-        return { count: this.state.count };
-    }
-    onSetName(payload) {
-        this.state.name = String(payload.name ?? '');
-        return { name: this.state.name };
-    }
-    onGet() {
-        return { count: this.state.count, name: this.state.name };
-    }
-}
-describe('PlexSpacesActor', () => {
-    let actor;
-    beforeEach(() => {
-        actor = new TestActor();
-        mockHostLog = undefined;
-    });
-    describe('init', () => {
-        it('should initialize with default state', () => {
-            const result = actor.init('{}');
-            expect(result).toBe('');
-            expect(actor.state.count).toBe(0);
-            expect(actor.state.name).toBe('');
-        });
-        it('should call onInit with parsed config', () => {
-            const config = JSON.stringify({ name: 'test-actor' });
-            const result = actor.init(config);
-            expect(result).toBe('');
-        });
-        it('should return error on invalid JSON', () => {
-            const result = actor.init('invalid json');
-            expect(result).toContain('ERROR');
-        });
-    });
-    describe('handle', () => {
-        beforeEach(() => {
-            actor.init('{}');
-        });
-        it('should dispatch to onIncrement handler', () => {
-            const payload = JSON.stringify({ op: 'increment', amount: 5 });
-            const result = actor.handle('sender', 'call', payload);
-            const parsed = JSON.parse(result);
-            expect(parsed.count).toBe(5);
-            expect(actor.state.count).toBe(5);
-        });
-        it('should dispatch to onSetName handler', () => {
-            const payload = JSON.stringify({ op: 'set_name', name: 'test' });
-            const result = actor.handle('sender', 'call', payload);
-            const parsed = JSON.parse(result);
-            expect(parsed.name).toBe('test');
-            expect(actor.state.name).toBe('test');
-        });
-        it('should return error for unknown operation', () => {
-            const payload = JSON.stringify({ op: 'unknown' });
-            const result = actor.handle('sender', 'call', payload);
-            const parsed = JSON.parse(result);
-            expect(parsed.error).toBe('unknown_op');
-        });
-        it('should handle handler errors gracefully', () => {
-            class ErrorActor extends PlexSpacesActor {
-                getDefaultState() {
-                    return { count: 0, name: '' };
-                }
-                onError() {
-                    throw new Error('Handler error');
-                }
-            }
-            const errorActor = new ErrorActor();
-            errorActor.init('{}');
-            const payload = JSON.stringify({ op: 'error' });
-            const result = errorActor.handle('sender', 'call', payload);
-            expect(result).toContain('ERROR');
-        });
-    });
-    describe('getState', () => {
-        it('should return serialized state', () => {
-            actor.init('{}');
-            actor.state.count = 42;
-            actor.state.name = 'test';
-            const stateJson = actor.getState();
-            const parsed = JSON.parse(stateJson);
-            expect(parsed.count).toBe(42);
-            expect(parsed.name).toBe('test');
-        });
-        it('should cache serialized state', () => {
-            actor.init('{}');
-            const state1 = actor.getState();
-            const state2 = actor.getState();
-            expect(state1).toBe(state2);
-        });
-    });
-    describe('setState', () => {
-        it('should restore state from JSON', () => {
-            const stateJson = JSON.stringify({ count: 100, name: 'restored' });
-            const result = actor.setState(stateJson);
-            expect(result).toBe('');
-            expect(actor.state.count).toBe(100);
-            expect(actor.state.name).toBe('restored');
-        });
-        it('should return error on invalid JSON', () => {
-            const result = actor.setState('invalid json');
-            expect(result).toContain('ERROR');
-        });
-        it('should handle empty state', () => {
-            const result = actor.setState('');
-            expect(result).toBe('');
-        });
-    });
-    describe('logging (actorLog)', () => {
-        // Note: actorLog is not exported, so we test it indirectly through error handling
-        // In a real WASM environment, hostLog would be provided by jco componentize
-        it('should handle errors without throwing', () => {
-            // This test verifies that logging failures don't crash the actor
-            class LoggingActor extends PlexSpacesActor {
-                getDefaultState() {
-                    return { count: 0, name: '' };
-                }
-                onTest() {
-                    // This will trigger actorLog internally on error
-                    return { status: 'ok' };
-                }
-            }
-            const loggingActor = new LoggingActor();
-            loggingActor.init('{}');
-            const payload = JSON.stringify({ op: 'test' });
-            // Should not throw even if hostLog is unavailable
-            expect(() => {
-                loggingActor.handle('sender', 'call', payload);
-            }).not.toThrow();
-        });
-    });
-    describe('safeStringify', () => {
-        it('should serialize simple objects', () => {
-            actor.init('{}');
-            const obj = { a: 1, b: 'test' };
-            const result = actor.safeStringify(obj);
-            expect(result).toBe(JSON.stringify(obj));
-        });
-        it('should handle circular references', () => {
-            actor.init('{}');
-            const obj = { a: 1 };
-            obj.self = obj;
-            // Should not throw
-            expect(() => {
-                actor.safeStringify(obj);
-            }).not.toThrow();
-        });
-        it('should handle large arrays', () => {
-            actor.init('{}');
-            const largeArray = Array.from({ length: 1000 }, (_, i) => i);
-            const result = actor.safeStringify(largeArray);
-            expect(result).toBe(JSON.stringify(largeArray));
-        });
-    });
-});