@blokjs/trigger-websocket 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# @blokjs/trigger-websocket
+
+## 0.2.0
+
+### Minor Changes
+
+- Initial public release of Blok packages.
+
+  This release includes:
+
+  - Core packages: @blokjs/shared, @blokjs/helper, @blokjs/runner
+  - Node packages: @blokjs/api-call, @blokjs/if-else, @blokjs/react
+  - Trigger packages: pubsub, queue, webhook, websocket, worker, cron, grpc
+  - CLI tool: blokctl
+  - Editor support: @blokjs/lsp-server, @blokjs/syntax
+
+### Patch Changes
+
+- Updated dependencies
+  - @blokjs/shared@0.2.0
+  - @blokjs/helper@0.2.0
+  - @blokjs/runner@0.2.0

package/dist/WebSocketTrigger.d.ts

@@ -0,0 +1,264 @@
+/**
+ * WebSocketTrigger - Real-time bidirectional communication trigger
+ *
+ * Extends TriggerBase to handle WebSocket connections for:
+ * - Real-time messaging
+ * - Live updates and notifications
+ * - Collaborative features
+ * - Streaming data
+ *
+ * Features:
+ * - Connection management (connect, disconnect, reconnect)
+ * - Room/channel support for broadcasting
+ * - Message routing to workflows
+ * - Heartbeat/ping-pong for connection health
+ * - Authentication middleware
+ * - Binary message support
+ */
+import type { HelperResponse, WebSocketTriggerOpts } from "@blok/helper";
+import { DefaultLogger, type GlobalOptions, type BlokService, TriggerBase, type TriggerResponse } from "@blok/runner";
+/**
+ * WebSocket message types
+ */
+export type WebSocketMessageType = "text" | "binary" | "ping" | "pong";
+/**
+ * WebSocket connection state
+ */
+export type WebSocketState = "connecting" | "connected" | "disconnecting" | "disconnected";
+/**
+ * WebSocket message structure
+ */
+export interface WebSocketMessage {
+    /** Unique message ID */
+    id: string;
+    /** Message type */
+    type: WebSocketMessageType;
+    /** Event name (for routing) */
+    event: string;
+    /** Message payload */
+    data: unknown;
+    /** Timestamp */
+    timestamp: Date;
+    /** Raw message data */
+    raw?: Buffer | string;
+}
+/**
+ * WebSocket client connection
+ */
+export interface WebSocketClient {
+    /** Unique client ID */
+    id: string;
+    /** Connection state */
+    state: WebSocketState;
+    /** Rooms/channels the client is subscribed to */
+    rooms: Set<string>;
+    /** Client metadata */
+    metadata: Record<string, unknown>;
+    /** Connection timestamp */
+    connectedAt: Date;
+    /** Last activity timestamp */
+    lastActivity: Date;
+    /** Send message to client */
+    send(data: string | Buffer): void;
+    /** Close connection */
+    close(code?: number, reason?: string): void;
+    /** Ping the client */
+    ping(): void;
+}
+/**
+ * WebSocket room/channel for broadcasting
+ */
+export interface WebSocketRoom {
+    /** Room name */
+    name: string;
+    /** Clients in the room */
+    clients: Set<string>;
+    /** Room metadata */
+    metadata: Record<string, unknown>;
+    /** Created timestamp */
+    createdAt: Date;
+}
+/**
+ * WebSocket event types for lifecycle hooks
+ */
+export type WebSocketEventType = "connection" | "message" | "close" | "error" | "ping" | "pong" | "join_room" | "leave_room";
+/**
+ * WebSocket event for workflow triggering
+ */
+export interface WebSocketEvent {
+    /** Event type */
+    type: WebSocketEventType;
+    /** Client ID */
+    clientId: string;
+    /** Message (for message events) */
+    message?: WebSocketMessage;
+    /** Room name (for room events) */
+    room?: string;
+    /** Error (for error events) */
+    error?: Error;
+    /** Close code (for close events) */
+    closeCode?: number;
+    /** Close reason (for close events) */
+    closeReason?: string;
+}
+/**
+ * Authentication result
+ */
+export interface AuthResult {
+    authenticated: boolean;
+    clientId?: string;
+    metadata?: Record<string, unknown>;
+    error?: string;
+}
+/**
+ * Authentication handler function type
+ */
+export type AuthHandler = (request: unknown, headers: Record<string, string>) => Promise<AuthResult> | AuthResult;
+/**
+ * Workflow model with WebSocket trigger configuration
+ */
+interface WebSocketWorkflowModel {
+    path: string;
+    config: {
+        name: string;
+        version: string;
+        trigger?: {
+            websocket?: WebSocketTriggerOpts;
+            [key: string]: unknown;
+        };
+        [key: string]: unknown;
+    };
+}
+/**
+ * WebSocketTrigger - Handle WebSocket connections and messages
+ */
+export declare abstract class WebSocketTrigger extends TriggerBase {
+    protected nodeMap: GlobalOptions;
+    protected readonly tracer: import("@opentelemetry/api").Tracer;
+    protected readonly logger: DefaultLogger;
+    protected websocketWorkflows: WebSocketWorkflowModel[];
+    protected clients: Map<string, WebSocketClient>;
+    protected rooms: Map<string, WebSocketRoom>;
+    protected activeConnections: number;
+    protected totalMessages: number;
+    protected heartbeatInterval: NodeJS.Timeout | null;
+    protected heartbeatIntervalMs: number;
+    protected maxClients: number;
+    protected messageRateLimit: number;
+    protected abstract nodes: Record<string, BlokService<unknown>>;
+    protected abstract workflows: Record<string, HelperResponse>;
+    protected authHandler?: AuthHandler;
+    constructor();
+    /**
+     * Load nodes into the node map
+     */
+    loadNodes(): void;
+    /**
+     * Load workflows into the workflow map
+     */
+    loadWorkflows(): void;
+    /**
+     * Set authentication handler
+     */
+    setAuthHandler(handler: AuthHandler): void;
+    /**
+     * Initialize WebSocket trigger
+     */
+    listen(): Promise<number>;
+    /**
+     * Stop the WebSocket trigger
+     */
+    stop(): Promise<void>;
+    protected onHmrWorkflowChange(): Promise<void>;
+    /**
+     * Handle new WebSocket connection
+     */
+    handleConnection(socket: {
+        send: (data: string | Buffer) => void;
+        close: (code?: number, reason?: string) => void;
+        ping: () => void;
+    }, request: unknown, headers?: Record<string, string>): Promise<WebSocketClient | null>;
+    /**
+     * Handle WebSocket message
+     */
+    handleMessage(clientId: string, data: string | Buffer, isBinary: boolean): Promise<TriggerResponse | null>;
+    /**
+     * Handle WebSocket close
+     */
+    handleClose(clientId: string, code: number, reason: string): Promise<void>;
+    /**
+     * Handle WebSocket error
+     */
+    handleError(clientId: string, error: Error): Promise<void>;
+    /**
+     * Handle ping from client
+     */
+    handlePing(clientId: string): void;
+    /**
+     * Handle pong from client
+     */
+    handlePong(clientId: string): void;
+    /**
+     * Join a room/channel
+     */
+    joinRoom(clientId: string, roomName: string): Promise<boolean>;
+    /**
+     * Leave a room/channel
+     */
+    leaveRoom(clientId: string, roomName: string): Promise<boolean>;
+    /**
+     * Send message to a specific client
+     */
+    sendToClient(clientId: string, event: string, data: unknown): boolean;
+    /**
+     * Broadcast message to all clients in a room
+     */
+    broadcastToRoom(roomName: string, event: string, data: unknown, excludeClient?: string): number;
+    /**
+     * Broadcast message to all connected clients
+     */
+    broadcastToAll(event: string, data: unknown, excludeClient?: string): number;
+    /**
+     * Get client by ID
+     */
+    getClient(clientId: string): WebSocketClient | undefined;
+    /**
+     * Get all clients in a room
+     */
+    getClientsInRoom(roomName: string): WebSocketClient[];
+    /**
+     * Get connection stats
+     */
+    getStats(): {
+        activeConnections: number;
+        totalMessages: number;
+        roomCount: number;
+        clientsByRoom: Record<string, number>;
+    };
+    /**
+     * Get all workflows that have WebSocket triggers
+     */
+    protected getWebSocketWorkflows(): WebSocketWorkflowModel[];
+    /**
+     * Find workflow matching the WebSocket event
+     */
+    protected findMatchingWorkflow(event: WebSocketEvent): WebSocketWorkflowModel | null;
+    /**
+     * Trigger a workflow based on WebSocket event
+     */
+    protected triggerEvent(event: WebSocketEvent): Promise<TriggerResponse | null>;
+    /**
+     * Execute a workflow for a WebSocket event
+     */
+    protected executeWorkflow(event: WebSocketEvent, workflow: WebSocketWorkflowModel, _config: WebSocketTriggerOpts): Promise<TriggerResponse>;
+    /**
+     * Start heartbeat monitoring
+     */
+    protected startHeartbeat(): void;
+    /**
+     * Stop heartbeat monitoring
+     */
+    protected stopHeartbeat(): void;
+}
+export default WebSocketTrigger;
+//# sourceMappingURL=WebSocketTrigger.d.ts.map

package/dist/WebSocketTrigger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebSocketTrigger.d.ts","sourceRoot":"","sources":["../src/WebSocketTrigger.ts"],"names":[],"mappings":"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"}