luca 2.0.0 → 3.0.0

package/src/servers/socket.ts

@@ -0,0 +1,258 @@
+import { z } from 'zod'
+import { ServerStateSchema, ServerOptionsSchema, ServerEventsSchema } from '../schemas/base.js'
+import { type StartOptions, Server, type ServerState } from '../server.js';
+import { WebSocketServer as BaseServer } from 'ws'
+import type { PendingRequest } from '../clients/websocket.js'
+
+declare module '../server' {
+  interface AvailableServers {
+    websocket: typeof WebsocketServer
+  }
+}
+
+export const SocketServerOptionsSchema = ServerOptionsSchema.extend({
+  json: z.boolean().optional().describe('When enabled, incoming messages are automatically JSON-parsed before emitting the message event, and outgoing send/broadcast calls JSON-stringify the payload'),
+})
+export type SocketServerOptions = z.infer<typeof SocketServerOptionsSchema>
+
+export const SocketServerEventsSchema = ServerEventsSchema.extend({
+  connection: z.tuple([z.any().describe('The raw WebSocket client instance from the ws library')]).describe('Fires when a new client connects'),
+  message: z.tuple([z.any().describe('The message data (JSON-parsed object when json option is enabled, raw Buffer/string otherwise)'), z.any().describe('The WebSocket client that sent the message — use with server.send(ws, data) to reply')]).describe('Fires when a message is received from a client. Handler signature: (data, ws)'),
+}).describe('WebSocket server events')
+
+/**
+ * WebSocket server built on the `ws` library with optional JSON message framing.
+ *
+ * Manages WebSocket connections, tracks connected clients, and bridges
+ * messages to Luca's event bus. When `json` mode is enabled, incoming
+ * messages are automatically JSON-parsed (with `.toString()` for Buffer data)
+ * and outgoing messages via `send()` / `broadcast()` are JSON-stringified.
+ * When `json` mode is disabled, raw message data is emitted as-is and
+ * `send()` / `broadcast()` still JSON-stringify for safety.
+ *
+ * Supports ask/reply semantics when paired with the Luca WebSocket client.
+ * The server can `ask(ws, type, data)` a connected client and await a typed
+ * response, or handle incoming asks from clients by listening for messages
+ * with a `requestId` and replying via `send(ws, { replyTo, data })`.
+ * Requests time out if no reply arrives within the configurable window.
+ *
+ * @extends Server
+ *
+ * @example
+ * ```typescript
+ * const ws = container.server('websocket', { json: true })
+ * await ws.start({ port: 8080 })
+ *
+ * ws.on('message', (data, client) => {
+ *   console.log('Received:', data)
+ *   ws.broadcast({ echo: data })
+ * })
+ *
+ * // ask/reply: request info from a connected client
+ * ws.on('connection', async (client) => {
+ *   const info = await ws.ask(client, 'identify')
+ *   console.log('Client says:', info)
+ * })
+ * ```
+ */
+export class WebsocketServer<T extends ServerState = ServerState, K extends SocketServerOptions = SocketServerOptions> extends Server<T,K> {
+    static override shortcut = 'servers.websocket' as const
+    static override stateSchema = ServerStateSchema
+    static override optionsSchema = SocketServerOptionsSchema
+    static override eventsSchema = SocketServerEventsSchema
+
+    static { Server.register(this, 'websocket') }
+    
+    _wss?: BaseServer 
+
+    get wss(): BaseServer {
+      if (this._wss) {
+        return this._wss
+      }
+      
+      return this._wss = new BaseServer({ 
+        port: this.port 
+      })
+    }
+
+    connections : Set<any> = new Set()
+    _pending = new Map<string, PendingRequest>()
+
+    async broadcast(message: any): Promise<this> {
+      for(const ws of this.connections) {
+        await ws.send(JSON.stringify(message))
+      }
+      
+      return this
+    }
+    
+    async send(ws: any, message: any): Promise<this> {
+      await ws.send(JSON.stringify(message))
+      return this
+    }
+
+    /**
+     * Send a request to a specific client and wait for a correlated response.
+     * The client is expected to reply with a message whose `replyTo` matches
+     * the `requestId` of this message.
+     *
+     * @param ws - The WebSocket client to ask
+     * @param type - A string identifying the request type
+     * @param data - Optional payload
+     * @param timeout - How long to wait (default 10 000 ms)
+     * @returns The `data` field of the response
+     *
+     * @example
+     * ```typescript
+     * ws.on('connection', async (client) => {
+     *   const info = await ws.ask(client, 'identify')
+     *   console.log('Client says:', info)
+     * })
+     * ```
+     */
+    async ask<R = any>(ws: any, type: string, data?: any, timeout = 10000): Promise<R> {
+      const requestId = this.container.utils.uuid()
+
+      return new Promise<R>((resolve, reject) => {
+        const timer = setTimeout(() => {
+          this._pending.delete(requestId)
+          reject(new Error(`ask("${type}") timed out after ${timeout}ms`))
+        }, timeout)
+
+        this._pending.set(requestId, { resolve, reject, timer })
+        this.send(ws, { type, data, requestId })
+      })
+    }
+
+    /** @internal Resolve a pending ask() if the incoming message has a replyTo field. Returns true if handled. */
+    _handleReply(message: any): boolean {
+      if (!message || !message.replyTo) return false
+
+      const pending = this._pending.get(message.replyTo)
+      if (!pending) return false
+
+      this._pending.delete(message.replyTo)
+      clearTimeout(pending.timer)
+
+      if (message.error) {
+        pending.reject(new Error(message.error))
+      } else {
+        pending.resolve(message.data)
+      }
+      return true
+    }
+
+    /** @internal Reject all pending ask() calls — used on stop. */
+    _rejectAllPending(reason: string) {
+      for (const [id, pending] of this._pending) {
+        clearTimeout(pending.timer)
+        pending.reject(new Error(reason))
+      }
+      this._pending.clear()
+    }
+
+    /**
+     * Start the WebSocket server. A runtime `port` overrides the constructor
+     * option and is written to state before the underlying `ws.Server` is created,
+     * so the server binds to the correct port.
+     *
+     * @param options - Optional runtime overrides for port and host
+     */
+    override async start(options?: StartOptions): Promise<this> {
+      if (this.isListening) {
+        return this
+      }
+
+      await this._drainPendingPlugins()
+
+      // Apply runtime port to state before configure/wss touches it
+      if (options?.port) {
+        this.state.set('port', options.port)
+        // Reset cached wss so it rebinds to the new port
+        this._wss = undefined
+      }
+
+      if(!this.isConfigured || options?.port) {
+        await this.configure()
+      }
+
+      const { wss } = this
+      
+      wss.on('connection', (ws) => {
+        this.connections.add(ws)
+        this.emit('connection', ws)
+
+        ws.on('message', (raw) => {
+          let data: any = raw
+          if (this.options.json) {
+            try {
+              data = JSON.parse(typeof raw === 'string' ? raw : raw.toString())
+            } catch {}
+          }
+
+          // Route reply messages to pending ask() calls
+          if (this._handleReply(data)) return
+
+          // If this message is a request (has requestId), provide a reply helper
+          if (data && data.requestId) {
+            const requestId = data.requestId
+            data.reply = (responseData: any) => this.send(ws, { replyTo: requestId, data: responseData })
+            data.replyError = (error: string) => this.send(ws, { replyTo: requestId, error })
+          }
+
+          this.emit('message', data, ws)
+        })
+      })
+      
+      this.state.set('listening', true)
+
+      return this
+    }
+
+    override async stop(): Promise<this> {
+      if (this.isStopped) {
+        return this
+      }
+
+      this._rejectAllPending('WebSocket server stopped')
+
+      await Promise.race([
+        new Promise<void>((resolve) => {
+          if (!this._wss) {
+            resolve()
+            return
+          }
+
+          for (const ws of this.connections) {
+            try {
+              ws.terminate?.()
+              ws.close?.()
+            } catch {}
+          }
+          this.connections.clear()
+
+          try {
+            this._wss.close(() => {
+              this._wss = undefined
+              resolve()
+            })
+          } catch {
+            this._wss = undefined
+            resolve()
+          }
+        }),
+        new Promise<void>((resolve) => setTimeout(resolve, 500)),
+      ])
+
+      this.state.set('listening', false)
+      this.state.set('stopped', true)
+      return this
+    }
+    
+    /** The port this server will bind to. Defaults to 8081 if not set via constructor options or start(). */
+    override get port(): number {
+      return this.state.get('port') || this.options.port || 8081
+    }
+}
+
+export default WebsocketServer

package/src/state.ts

@@ -0,0 +1,101 @@
+export type StateChangeType = 'add' | 'update' | 'delete';
+export type StateChangeCallback<K extends keyof any, V> = (changeType: StateChangeType, key: K, value?: V) => void;
+export type SetStateValue<T extends object> = Partial<T> | ((current: T, state: State<T>) => Partial<T>);
+
+export class State<T extends object = any> {
+    private state: Partial<T>;
+    private observers: StateChangeCallback<keyof T, T[keyof T]>[];
+    private _version = 0
+
+    constructor(options?: { initialState: Partial<T>}) {
+        this.state = {
+            ...(options?.initialState || {}) as Partial<T>
+        };
+        this.observers = [];
+        
+        Object.defineProperty(this, 'state', { enumerable: false });
+        Object.defineProperty(this, '_version', { enumerable: false });
+        Object.defineProperty(this, 'observers', { enumerable: false });
+    }
+    
+    get version() {
+        return this._version
+    }
+
+    observe(callback: StateChangeCallback<keyof T, T[keyof T]>): () => void {
+        this.observers.push(callback);
+
+        return () => {
+            const index = this.observers.indexOf(callback);
+            if (index !== -1) {
+                this.observers.splice(index, 1);
+            }
+        };
+    }
+
+    keys() : string[] {
+        return Object.keys(this.state);
+    }
+
+    get<K extends keyof T>(key: K): T[K] | undefined {
+        return this.state[key];
+    }
+
+    set<K extends keyof T>(key: K, value: T[K]): this {
+        if(value === this.state[key]) {
+          return this
+        }
+
+        const changeType: StateChangeType = this.state.hasOwnProperty(key) ? 'update' : 'add';
+        this.state[key] = value;
+        this._version++
+        this.observers.forEach(callback => callback(changeType, key, value));
+        return this
+    }
+
+    delete<K extends keyof T>(key: K): this {
+        if (this.state.hasOwnProperty(key)) {
+            const value = this.state[key];
+            delete this.state[key];
+            this._version++
+            this.observers.forEach(callback => callback('delete', key, value));
+        }
+        
+        return this
+    }
+
+    has<K extends keyof T>(key: K): boolean {
+        return this.state.hasOwnProperty(key);
+    }
+
+    get current(): T {
+        return this.state as T;
+    }
+
+    clear(): void {
+        const keys = Object.keys(this.state);
+        this.state = {};
+        this._version++
+        keys.forEach(key => {
+            this.observers.forEach(callback => callback('delete', key as keyof T));
+        });
+    }
+   
+    entries() : [keyof T, T[keyof T]][] {
+        return Object.entries(this.state) as [keyof T, T[keyof T]][];
+    }
+
+    values() : T[keyof T][] {
+      return Object.values(this.state);
+    }
+
+    setState(value: SetStateValue<T>): void {
+        const newState = typeof value === 'function' ? value(this.current, this) : value;
+        for (const key in newState) {
+            if (Object.prototype.hasOwnProperty.call(newState, key)) {
+                // @ts-ignore-next-line
+                this.set(key as keyof T, newState[key as keyof T]);
+            }
+        }
+    }
+}

package/src/web/clients/socket.ts

@@ -0,0 +1,99 @@
+import Websocket from 'isomorphic-ws'
+import { Client } from '../../client'
+import { WebSocketClient, type WebSocketClientState, type WebSocketClientOptions } from '../../clients/websocket'
+import { WebSocketClientEventsSchema } from '../../schemas/base.js'
+
+/**
+ * Web-specific WebSocket client implementation using isomorphic-ws.
+ * Extends the base WebSocketClient with platform-specific transport and
+ * an envelope format that wraps sent data with a unique ID. Inherits
+ * ask/reply semantics from the base WebSocketClient — protocol messages
+ * (those with `requestId` or `replyTo`) bypass the envelope wrapper to
+ * maintain compatibility with the Luca WebSocket server's ask/reply flow.
+ */
+export class SocketClient<T extends WebSocketClientState = WebSocketClientState, K extends WebSocketClientOptions = WebSocketClientOptions> extends WebSocketClient<T,K> {
+  // @ts-expect-error widening ws type for isomorphic-ws compatibility
+  declare ws: Websocket | WebSocket
+
+  static override shortcut = 'clients.websocket' as const
+  static override eventsSchema = WebSocketClientEventsSchema
+
+  static { Client.register(this, 'websocket') }
+
+  /**
+   * Send data over the WebSocket with an ID envelope.
+   * Wraps the payload in { id, data } before JSON serialization.
+   * Messages with a `requestId` or `replyTo` are sent as-is to
+   * preserve the ask/reply protocol.
+   */
+  override async send(data: any) {
+    if(!this.isConnected && !this.hasError) {
+      await this.connect()
+    }
+
+    if(typeof this.ws === 'undefined') {
+      throw new Error(`Missing websocket instance`)
+    }
+
+    // Protocol messages (ask/reply) bypass the envelope
+    if (data && (data.requestId || data.replyTo)) {
+      this.ws.send(JSON.stringify(data))
+    } else {
+      this.ws.send(JSON.stringify({
+        id: this.container.utils.uuid(),
+        data
+      }))
+    }
+  }
+
+  /**
+   * Establish a WebSocket connection using isomorphic-ws.
+   * Bridges raw WebSocket events to the Helper event bus and tracks connection state.
+   */
+  override async connect() {
+    if(this.isConnected) {
+      return this
+    }
+
+    const ws = this.ws = new Websocket(this.options.baseURL!)
+    const state = this.state as any
+
+    await new Promise<void>((resolve, reject) => {
+      ws.onopen = () => {
+        state.set('connected', true)
+        state.set('connectionError', undefined)
+        state.set('reconnectAttempts', 0)
+        this.emit('open')
+        resolve()
+      }
+
+      ws.onerror = (event: any) => {
+        state.set('connectionError', event)
+        this.emit('error', event)
+        reject(event)
+      }
+
+      ws.onmessage = (event: any) => {
+        let data = event?.data ?? event
+        try {
+          data = JSON.parse(typeof data === 'string' ? data : data.toString())
+        } catch {}
+        if (!this._handleReply(data)) {
+          this.emit('message', data)
+        }
+      }
+
+      ws.onclose = (event: any) => {
+        state.set('connected', false)
+        this.emit('close', event?.code, event?.reason)
+      }
+    }).catch((error) => {
+      state.set('connectionError', error)
+      throw error
+    })
+
+    return this
+  }
+}
+
+export default SocketClient

package/src/web/container.ts

@@ -0,0 +1,75 @@
+export * from '../container.js'
+import { Container } from '../container.js'
+import { Client } from '../client.js'
+import { RestClient } from '../clients/rest.js'
+import { SocketClient } from './clients/socket.js'
+import type { AvailableFeatures } from '../feature.js'
+import type { ContainerState, ContainerArgv } from '../container.js' 
+import type { ClientsInterface } from '../client.js'
+import type { AssetLoader } from './features/asset-loader.js'
+import type { VoiceRecognition } from './features/voice-recognition.js'
+import type { Speech } from './features/speech.js'
+import type { Network } from './features/network.js'
+import type { WebVault } from './features/vault.js'
+import type { VM } from './features/vm.js'
+import type { Esbuild } from './features/esbuild.js'
+import type { Helpers } from './features/helpers.js'
+import type { ContainerLink } from './features/container-link.js'
+
+import * as WebContainerExtensions from './extension.js'
+
+export { Client, RestClient, SocketClient }
+
+export interface WebFeatures extends AvailableFeatures {
+  assetLoader: typeof AssetLoader
+  voice: typeof VoiceRecognition
+  speech: typeof Speech
+  vault: typeof WebVault
+  vm: typeof VM;
+  esbuild: typeof Esbuild
+  helpers: typeof Helpers
+  containerLink: typeof ContainerLink
+}
+
+export interface WebContainer extends ClientsInterface {
+  assetLoader?: AssetLoader
+  voice?: VoiceRecognition
+  speech?: Speech
+  network?: Network
+  vault?: WebVault
+  helpers?: Helpers
+  containerLink?: ContainerLink
+}
+
+export interface WebContainerState extends ContainerState { }
+
+/**
+ * Browser-specific container that extends the base Container with web client support
+ * and browser-specific features like speech, voice recognition, and asset loading.
+ */
+export class WebContainer<Features extends WebFeatures = WebFeatures, K extends WebContainerState = WebContainerState> extends Container<Features, K> {
+  /** Returns the base Client class for creating custom clients. */
+  get Client() {
+    return Client
+  }
+
+  /** Returns the SocketClient class for WebSocket connections. */
+  get SocketClient() {
+    return SocketClient
+  }
+
+  /** Returns the RestClient class for HTTP REST API connections. */
+  get RestClient() {
+    return RestClient
+  }
+
+  useHelpers: any[] = [WebContainerExtensions]
+
+  constructor(options: any = {}) {
+    super(options)
+    this.use(WebContainerExtensions as any)
+    this.feature("helpers" as any, { enable: true })
+  }
+}
+
+export const helperCache = new Map()

package/src/web/extension.ts

@@ -0,0 +1,30 @@
+import type { Container } from '../container'
+
+import { Client, type ClientsInterface } from '../client.js'
+import { AssetLoader } from './features/asset-loader.js'
+import { Helpers } from './features/helpers.js'
+import { VoiceRecognition } from './features/voice-recognition.js'
+import { Speech } from './features/speech.js'
+import { SocketClient } from './clients/socket.js'
+import { Network } from './features/network.js'
+import { WebVault } from './features/vault.js'
+import { VM } from './features/vm.js'
+import { Esbuild } from './features/esbuild.js'
+import { ContainerLink } from './features/container-link.js'
+
+export function attach<K extends Container & ClientsInterface>(container: K, options?: any) : Container & ClientsInterface {
+  container
+    .use(Client)
+    .use(AssetLoader)
+    .use(Helpers)
+    .use(VoiceRecognition)
+    .use(Speech)
+    .use(SocketClient)
+    .use(Network)
+    .use(VM)
+    .use(WebVault)
+    .use(Esbuild)
+    .use(ContainerLink)
+
+  return container
+}

package/src/web/feature.ts

@@ -0,0 +1,12 @@
+import type { WebContainer } from './container.js'
+import { type FeatureOptions, type FeatureState, type AvailableFeatures, features, Feature as UniversalFeature } from '../feature.js'
+
+export { features }
+
+export type { AvailableFeatures, FeatureState, FeatureOptions }
+
+export class Feature<T extends FeatureState = FeatureState, K extends FeatureOptions = FeatureOptions> extends UniversalFeature<T, K> {
+    override get container() : WebContainer {
+        return super.container as WebContainer 
+    }
+}

package/src/web/features/asset-loader.ts

@@ -0,0 +1,72 @@
+import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import { Feature } from "../feature.js";
+
+/**
+ * Injects scripts and stylesheets into the page at runtime.
+ *
+ * Provides helpers for loading external libraries from unpkg.com,
+ * injecting arbitrary script/link tags, and managing load state.
+ * Used by other web features (e.g. Esbuild) to pull in dependencies on demand.
+ *
+ * @extends Feature
+ *
+ * @example
+ * ```typescript
+ * const loader = container.feature('assetLoader')
+ * await loader.loadScript('https://unpkg.com/lodash')
+ * await AssetLoader.loadStylesheet('https://unpkg.com/normalize.css')
+ * ```
+ */
+export class AssetLoader extends Feature {
+  static override stateSchema = FeatureStateSchema
+  static override optionsSchema = FeatureOptionsSchema
+  static override shortcut = "features.assetLoader" as const
+
+  static { Feature.register(this, 'assetLoader') }
+
+  static loadStylesheet(href: string) {
+    return new Promise((resolve, reject) => {
+      const link = document.createElement("link");
+      link.rel = "stylesheet";
+      link.href = href;
+      link.onload = () => resolve(link);
+      link.onerror = () => reject(new Error(`Failed to load stylesheet: ${href}`));
+
+      document.head.appendChild(link);
+    });
+  }
+
+  removeStylesheet(href:string) {
+    const links = document.querySelectorAll(`link[href="${href}"]`);
+
+    links.forEach((link) => {
+      document.head.removeChild(link);
+    });
+  }
+
+  async loadScript(url: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const script = document.createElement("script");
+      script.src = url;
+      script.async = true;
+
+      script.onload = () => {
+        resolve();
+      };
+
+      script.onerror = () => {
+        reject(new Error(`Failed to load script: ${url}`));
+      };
+
+      document.head.appendChild(script);
+    });
+  }
+
+  async unpkg(packageName: string, globalName: string): Promise<any> {
+    const url = `https://unpkg.com/${packageName}`;
+    await this.loadScript(url);
+    return (window as any)[globalName];
+  }
+}
+
+export default AssetLoader;