nebula-notebook 0.1.0

package/node-server/dist/cluster/kernel-proxy.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Kernel Proxy
+ *
+ * Handles proxying kernel operations to peer servers in a cluster.
+ * When a kernel is started on a remote server, this module manages
+ * the communication between the client and the remote kernel.
+ */
+import { WebSocket } from 'ws';
+import { PeerServer } from './server-registry';
+interface ProxiedSession {
+    serverId: string;
+    remoteSessionId: string;
+    remoteWs?: WebSocket;
+    localWs?: WebSocket;
+}
+/**
+ * Create a composite session ID that encodes the server
+ */
+export declare function createProxiedSessionId(serverId: string, remoteSessionId: string): string;
+/**
+ * Parse a composite session ID
+ */
+export declare function parseSessionId(sessionId: string): {
+    isProxied: boolean;
+    serverId?: string;
+    remoteSessionId?: string;
+};
+/**
+ * Check if a session ID is for a proxied (remote) kernel
+ */
+export declare function isProxiedSession(sessionId: string): boolean;
+/**
+ * Get the server for a session
+ */
+export declare function getSessionServer(sessionId: string): PeerServer | null;
+/**
+ * Start a kernel on a remote server
+ */
+export declare function startRemoteKernel(serverId: string, kernelName: string, filePath?: string): Promise<{
+    sessionId: string;
+    created?: boolean;
+    createdAt?: number;
+}>;
+/**
+ * Interrupt a kernel on a remote server
+ */
+export declare function interruptRemoteKernel(sessionId: string): Promise<void>;
+/**
+ * Restart a kernel on a remote server
+ */
+export declare function restartRemoteKernel(sessionId: string): Promise<void>;
+/**
+ * Get status of a kernel on a remote server
+ */
+export declare function getRemoteKernelStatus(sessionId: string): Promise<{
+    status: string;
+    execution_count?: number;
+    memory_mb?: number;
+}>;
+/**
+ * Shutdown a kernel on a remote server
+ */
+export declare function shutdownRemoteKernel(sessionId: string): Promise<void>;
+/**
+ * Get available kernels from a remote server
+ */
+export declare function getRemoteKernels(serverId: string): Promise<{
+    kernels: any[];
+}>;
+/**
+ * Get active kernel sessions from a remote server
+ */
+export declare function getRemoteKernelSessions(serverId: string): Promise<{
+    sessions: any[];
+}>;
+/**
+ * Get dead kernel sessions from a remote server
+ */
+export declare function getRemoteDeadKernelSessions(serverId: string): Promise<{
+    sessions: any[];
+}>;
+/**
+ * Cleanup dead kernel sessions on a remote server
+ */
+export declare function cleanupRemoteDeadKernelSessions(serverId: string, sessionIds?: string[]): Promise<{
+    deleted: number;
+}>;
+/**
+ * Create a WebSocket proxy to a remote kernel
+ */
+export declare function createWebSocketProxy(sessionId: string, clientWs: WebSocket): WebSocket | null;
+/**
+ * Get all proxied sessions
+ */
+export declare function getProxiedSessions(): Map<string, ProxiedSession>;
+/**
+ * Cleanup all proxied sessions
+ */
+export declare function cleanupProxiedSessions(): void;
+export {};

package/node-server/dist/cluster/kernel-proxy.js

@@ -0,0 +1,361 @@
+"use strict";
+/**
+ * Kernel Proxy
+ *
+ * Handles proxying kernel operations to peer servers in a cluster.
+ * When a kernel is started on a remote server, this module manages
+ * the communication between the client and the remote kernel.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProxiedSessionId = createProxiedSessionId;
+exports.parseSessionId = parseSessionId;
+exports.isProxiedSession = isProxiedSession;
+exports.getSessionServer = getSessionServer;
+exports.startRemoteKernel = startRemoteKernel;
+exports.interruptRemoteKernel = interruptRemoteKernel;
+exports.restartRemoteKernel = restartRemoteKernel;
+exports.getRemoteKernelStatus = getRemoteKernelStatus;
+exports.shutdownRemoteKernel = shutdownRemoteKernel;
+exports.getRemoteKernels = getRemoteKernels;
+exports.getRemoteKernelSessions = getRemoteKernelSessions;
+exports.getRemoteDeadKernelSessions = getRemoteDeadKernelSessions;
+exports.cleanupRemoteDeadKernelSessions = cleanupRemoteDeadKernelSessions;
+exports.createWebSocketProxy = createWebSocketProxy;
+exports.getProxiedSessions = getProxiedSessions;
+exports.cleanupProxiedSessions = cleanupProxiedSessions;
+const ws_1 = require("ws");
+const server_registry_1 = require("./server-registry");
+const proxiedSessions = new Map();
+function getClusterHeaders() {
+    const secret = process.env.NEBULA_CLUSTER_SECRET;
+    return secret ? { 'X-Nebula-Cluster-Secret': secret } : {};
+}
+/**
+ * Create a composite session ID that encodes the server
+ */
+function createProxiedSessionId(serverId, remoteSessionId) {
+    return `${serverId}::${remoteSessionId}`;
+}
+/**
+ * Parse a composite session ID
+ */
+function parseSessionId(sessionId) {
+    if (sessionId.includes('::')) {
+        const [serverId, remoteSessionId] = sessionId.split('::', 2);
+        return { isProxied: true, serverId, remoteSessionId };
+    }
+    return { isProxied: false };
+}
+/**
+ * Check if a session ID is for a proxied (remote) kernel
+ */
+function isProxiedSession(sessionId) {
+    return sessionId.includes('::');
+}
+/**
+ * Get the server for a session
+ */
+function getSessionServer(sessionId) {
+    const { isProxied, serverId } = parseSessionId(sessionId);
+    if (!isProxied || !serverId)
+        return null;
+    return server_registry_1.serverRegistry.getServer(serverId) || null;
+}
+/**
+ * Start a kernel on a remote server
+ */
+async function startRemoteKernel(serverId, kernelName, filePath) {
+    const server = server_registry_1.serverRegistry.getServer(serverId);
+    if (!server) {
+        throw new Error(`Server not found: ${serverId}`);
+    }
+    if (server.status !== 'online') {
+        throw new Error(`Server is offline: ${serverId}`);
+    }
+    // Call the remote server's kernel start endpoint
+    const endpoint = filePath
+        ? `${server.url}/api/kernels/for-file`
+        : `${server.url}/api/kernels/start`;
+    const body = filePath
+        ? { file_path: filePath, kernel_name: kernelName }
+        : { kernel_name: kernelName };
+    const response = await fetch(endpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...getClusterHeaders() },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({ detail: 'Unknown error' }));
+        throw new Error(error.detail || `Failed to start kernel on ${serverId}`);
+    }
+    const result = await response.json();
+    const remoteSessionId = result.session_id;
+    // Create composite session ID
+    const proxySessionId = createProxiedSessionId(serverId, remoteSessionId);
+    // Track the proxied session
+    proxiedSessions.set(proxySessionId, {
+        serverId,
+        remoteSessionId,
+    });
+    console.log(`[KernelProxy] Started kernel on ${serverId}, session: ${proxySessionId}`);
+    return {
+        sessionId: proxySessionId,
+        created: filePath ? result.created : true,
+        createdAt: result.created_at,
+    };
+}
+/**
+ * Interrupt a kernel on a remote server
+ */
+async function interruptRemoteKernel(sessionId) {
+    const { serverId, remoteSessionId } = parseSessionId(sessionId);
+    if (!serverId || !remoteSessionId) {
+        throw new Error('Invalid proxied session ID');
+    }
+    const server = server_registry_1.serverRegistry.getServer(serverId);
+    if (!server) {
+        throw new Error(`Server not found: ${serverId}`);
+    }
+    const response = await fetch(`${server.url}/api/kernels/${remoteSessionId}/interrupt`, {
+        method: 'POST',
+        headers: { ...getClusterHeaders() },
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({ detail: 'Unknown error' }));
+        throw new Error(error.detail || 'Failed to interrupt kernel');
+    }
+}
+/**
+ * Restart a kernel on a remote server
+ */
+async function restartRemoteKernel(sessionId) {
+    const { serverId, remoteSessionId } = parseSessionId(sessionId);
+    if (!serverId || !remoteSessionId) {
+        throw new Error('Invalid proxied session ID');
+    }
+    const server = server_registry_1.serverRegistry.getServer(serverId);
+    if (!server) {
+        throw new Error(`Server not found: ${serverId}`);
+    }
+    const response = await fetch(`${server.url}/api/kernels/${remoteSessionId}/restart`, {
+        method: 'POST',
+        headers: { ...getClusterHeaders() },
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({ detail: 'Unknown error' }));
+        throw new Error(error.detail || 'Failed to restart kernel');
+    }
+}
+/**
+ * Get status of a kernel on a remote server
+ */
+async function getRemoteKernelStatus(sessionId) {
+    const { serverId, remoteSessionId } = parseSessionId(sessionId);
+    if (!serverId || !remoteSessionId) {
+        throw new Error('Invalid proxied session ID');
+    }
+    const server = server_registry_1.serverRegistry.getServer(serverId);
+    if (!server) {
+        throw new Error(`Server not found: ${serverId}`);
+    }
+    const response = await fetch(`${server.url}/api/kernels/${remoteSessionId}/status`, {
+        headers: { ...getClusterHeaders() },
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({ detail: 'Unknown error' }));
+        throw new Error(error.detail || 'Failed to get kernel status');
+    }
+    return response.json();
+}
+/**
+ * Shutdown a kernel on a remote server
+ */
+async function shutdownRemoteKernel(sessionId) {
+    const { serverId, remoteSessionId } = parseSessionId(sessionId);
+    if (!serverId || !remoteSessionId) {
+        throw new Error('Invalid proxied session ID');
+    }
+    const server = server_registry_1.serverRegistry.getServer(serverId);
+    if (!server) {
+        throw new Error(`Server not found: ${serverId}`);
+    }
+    const response = await fetch(`${server.url}/api/kernels/${remoteSessionId}`, {
+        method: 'DELETE',
+        headers: { ...getClusterHeaders() },
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({ detail: 'Unknown error' }));
+        throw new Error(error.detail || 'Failed to shutdown kernel');
+    }
+    // Clean up proxied session
+    proxiedSessions.delete(sessionId);
+}
+/**
+ * Get available kernels from a remote server
+ */
+async function getRemoteKernels(serverId) {
+    const server = server_registry_1.serverRegistry.getServer(serverId);
+    if (!server) {
+        throw new Error(`Server not found: ${serverId}`);
+    }
+    if (server.status !== 'online') {
+        throw new Error(`Server is offline: ${serverId}`);
+    }
+    const response = await fetch(`${server.url}/api/kernels`, {
+        headers: { ...getClusterHeaders() },
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({ detail: 'Unknown error' }));
+        throw new Error(error.detail || 'Failed to fetch kernels');
+    }
+    return response.json();
+}
+/**
+ * Get active kernel sessions from a remote server
+ */
+async function getRemoteKernelSessions(serverId) {
+    const server = server_registry_1.serverRegistry.getServer(serverId);
+    if (!server) {
+        throw new Error(`Server not found: ${serverId}`);
+    }
+    if (server.status !== 'online') {
+        throw new Error(`Server is offline: ${serverId}`);
+    }
+    const response = await fetch(`${server.url}/api/kernels/sessions`, {
+        headers: { ...getClusterHeaders() },
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({ detail: 'Unknown error' }));
+        throw new Error(error.detail || 'Failed to fetch kernel sessions');
+    }
+    return response.json();
+}
+/**
+ * Get dead kernel sessions from a remote server
+ */
+async function getRemoteDeadKernelSessions(serverId) {
+    const server = server_registry_1.serverRegistry.getServer(serverId);
+    if (!server) {
+        throw new Error(`Server not found: ${serverId}`);
+    }
+    if (server.status !== 'online') {
+        throw new Error(`Server is offline: ${serverId}`);
+    }
+    const response = await fetch(`${server.url}/api/kernels/dead`, {
+        headers: { ...getClusterHeaders() },
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({ detail: 'Unknown error' }));
+        throw new Error(error.detail || 'Failed to fetch dead kernel sessions');
+    }
+    return response.json();
+}
+/**
+ * Cleanup dead kernel sessions on a remote server
+ */
+async function cleanupRemoteDeadKernelSessions(serverId, sessionIds) {
+    const server = server_registry_1.serverRegistry.getServer(serverId);
+    if (!server) {
+        throw new Error(`Server not found: ${serverId}`);
+    }
+    if (server.status !== 'online') {
+        throw new Error(`Server is offline: ${serverId}`);
+    }
+    const response = await fetch(`${server.url}/api/kernels/dead/cleanup`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...getClusterHeaders() },
+        body: JSON.stringify({ session_ids: sessionIds }),
+    });
+    if (!response.ok) {
+        const error = await response.json().catch(() => ({ detail: 'Unknown error' }));
+        throw new Error(error.detail || 'Failed to cleanup dead kernel sessions');
+    }
+    return response.json();
+}
+/**
+ * Create a WebSocket proxy to a remote kernel
+ */
+function createWebSocketProxy(sessionId, clientWs) {
+    const { serverId, remoteSessionId } = parseSessionId(sessionId);
+    if (!serverId || !remoteSessionId) {
+        return null;
+    }
+    const server = server_registry_1.serverRegistry.getServer(serverId);
+    if (!server) {
+        console.error(`[KernelProxy] Server not found for WebSocket proxy: ${serverId}`);
+        return null;
+    }
+    // Create WebSocket URL for remote server
+    const wsUrl = server.url.replace(/^http/, 'ws') + `/api/kernels/${remoteSessionId}/ws`;
+    console.log(`[KernelProxy] Creating WebSocket proxy to ${wsUrl}`);
+    const remoteWs = new ws_1.WebSocket(wsUrl, {
+        headers: getClusterHeaders(),
+    });
+    // Forward messages from remote to client
+    remoteWs.on('message', (data, isBinary) => {
+        if (clientWs.readyState !== ws_1.WebSocket.OPEN) {
+            return;
+        }
+        if (isBinary) {
+            clientWs.send(data);
+            return;
+        }
+        clientWs.send(typeof data === 'string' ? data : data.toString());
+    });
+    // Forward messages from client to remote
+    clientWs.on('message', (data, isBinary) => {
+        if (remoteWs.readyState !== ws_1.WebSocket.OPEN) {
+            return;
+        }
+        if (isBinary) {
+            remoteWs.send(data);
+            return;
+        }
+        remoteWs.send(typeof data === 'string' ? data : data.toString());
+    });
+    // Handle remote close
+    remoteWs.on('close', () => {
+        console.log(`[KernelProxy] Remote WebSocket closed for ${sessionId}`);
+        if (clientWs.readyState === ws_1.WebSocket.OPEN) {
+            clientWs.close();
+        }
+    });
+    // Handle client close
+    clientWs.on('close', () => {
+        console.log(`[KernelProxy] Client WebSocket closed for ${sessionId}`);
+        if (remoteWs.readyState === ws_1.WebSocket.OPEN) {
+            remoteWs.close();
+        }
+    });
+    // Handle errors
+    remoteWs.on('error', (err) => {
+        console.error(`[KernelProxy] Remote WebSocket error for ${sessionId}:`, err);
+    });
+    // Track the proxy
+    const session = proxiedSessions.get(sessionId);
+    if (session) {
+        session.remoteWs = remoteWs;
+        session.localWs = clientWs;
+    }
+    return remoteWs;
+}
+/**
+ * Get all proxied sessions
+ */
+function getProxiedSessions() {
+    return proxiedSessions;
+}
+/**
+ * Cleanup all proxied sessions
+ */
+function cleanupProxiedSessions() {
+    for (const [sessionId, session] of proxiedSessions.entries()) {
+        if (session.remoteWs) {
+            session.remoteWs.close();
+        }
+        if (session.localWs) {
+            session.localWs.close();
+        }
+        proxiedSessions.delete(sessionId);
+    }
+}

package/node-server/dist/cluster/server-registry.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Server Registry
+ *
+ * Manages registration of peer servers in a Nebula cluster.
+ * Peer servers can register with a main server to enable
+ * cross-server kernel access.
+ */
+import type { ServerResources } from '../resources/resource-service';
+export interface PeerServer {
+    id: string;
+    host: string;
+    port: number;
+    name?: string;
+    url: string;
+    registeredAt: number;
+    lastHeartbeat: number;
+    status: 'online' | 'offline' | 'unknown';
+    kernelspecs?: string[];
+    resources?: ServerResources;
+}
+export interface RegisterRequest {
+    host: string;
+    port: number;
+    name?: string;
+    secret?: string;
+    resources?: ServerResources;
+}
+declare class ServerRegistry {
+    private servers;
+    private clusterSecret;
+    private cleanupInterval;
+    private localServerId;
+    constructor();
+    /**
+     * Set the local server's ID (called on startup)
+     */
+    setLocalServerId(id: string): void;
+    /**
+     * Get the local server's ID
+     */
+    getLocalServerId(): string;
+    /**
+     * Validate registration secret
+     */
+    private getClusterSecret;
+    private validateSecret;
+    /**
+     * Generate server ID from host and port
+     */
+    private generateServerId;
+    /**
+     * Register a peer server
+     */
+    register(request: RegisterRequest): {
+        success: boolean;
+        serverId?: string;
+        error?: string;
+    };
+    /**
+     * Unregister a peer server
+     */
+    unregister(serverId: string): boolean;
+    /**
+     * Record heartbeat from a peer server
+     */
+    heartbeat(serverId: string, resources?: ServerResources): boolean;
+    /**
+     * Get a specific peer server
+     */
+    getServer(serverId: string): PeerServer | undefined;
+    /**
+     * Get all registered peer servers
+     */
+    getAllServers(): PeerServer[];
+    /**
+     * Get all online peer servers
+     */
+    getOnlineServers(): PeerServer[];
+    /**
+     * Check server health and update status
+     */
+    private checkServerHealth;
+    /**
+     * Start the cleanup interval
+     */
+    private startCleanupInterval;
+    /**
+     * Stop the cleanup interval (for shutdown)
+     */
+    shutdown(): void;
+    /**
+     * Get cluster info for API response
+     */
+    getClusterInfo(localResources?: ServerResources): {
+        localServerId: string;
+        peerCount: number;
+        onlineCount: number;
+        servers: Array<{
+            id: string;
+            name?: string;
+            url: string;
+            status: string;
+            isLocal: boolean;
+            resources?: ServerResources;
+        }>;
+    };
+}
+export declare const serverRegistry: ServerRegistry;
+export {};