@nimbus-sh/core 0.1.0

package/src/substrate/lifo/kernel/network/tunnel/WebSocketTunnel.ts

@@ -0,0 +1,387 @@
+import type { Packet } from '../types.js';
+import type { NetworkStack } from '../NetworkStack.js';
+import { BaseTunnel } from './BaseTunnel.js';
+import { Buffer } from '../../../node-compat/buffer.js';
+import type { VirtualResponseWithDone } from '../../../node-compat/http.js';
+
+/**
+ * WebSocket Tunnel - Bridge virtual network to external WebSocket server
+ *
+ * This tunnel connects Lifo's virtual network stack to an external WebSocket
+ * tunnel server, enabling host machine access to virtual servers.
+ *
+ * Example:
+ *   tunnel --server=ws://localhost:3005
+ *
+ * Access from host:
+ *   http://localhost:3005/3000/ → Port 3000 in virtual network
+ */
+export class WebSocketTunnel extends BaseTunnel {
+	type: 'ssh' = 'ssh'; // Using 'ssh' type for compatibility
+
+	private wsUrl: string;
+	private ws: WebSocket | null = null;
+	private portRegistry?: Map<number, any>;
+	private defaultPort: number | null = null;
+	private reconnectTimer?: any;
+	private isReconnecting = false;
+
+	// Packet queue
+	private packetQueue: Packet[] = [];
+	private waitingResolvers: Array<(packet: Packet) => void> = [];
+
+	constructor(
+		id: string,
+		wsUrl: string,
+		networkStack: NetworkStack,
+		portRegistry?: Map<number, any>,
+		namespace = 'default',
+		defaultPort: number | null = null
+	) {
+		super(id, networkStack, namespace, 1400); // WebSocket overhead
+
+		this.wsUrl = wsUrl;
+		this.portRegistry = portRegistry;
+		this.defaultPort = defaultPort;
+
+		this.config = {
+			mode: 'websocket',
+			server: wsUrl,
+			ports: portRegistry ? Array.from(portRegistry.keys()) : [],
+			defaultPort: defaultPort ?? undefined,
+		};
+	}
+
+	protected getTunnelPrefix(): string {
+		return 'wst';
+	}
+
+	/**
+	 * Bring tunnel up - connect to WebSocket server
+	 */
+	override async up(): Promise<void> {
+		if (this.state === 'up') {
+			return;
+		}
+
+		await this.connect();
+		this.state = 'up';
+		this.interface.up();
+	}
+
+	/**
+	 * Bring tunnel down - disconnect from WebSocket server
+	 */
+	override async down(): Promise<void> {
+		if (this.state === 'down') {
+			return;
+		}
+
+		this.isReconnecting = false;
+
+		if (this.reconnectTimer) {
+			clearTimeout(this.reconnectTimer);
+			this.reconnectTimer = undefined;
+		}
+
+		if (this.ws) {
+			this.ws.close();
+			this.ws = null;
+		}
+
+		this.state = 'down';
+		this.interface.down();
+	}
+
+	/**
+	 * Send packet through WebSocket tunnel
+	 */
+	async send(packet: Packet): Promise<void> {
+		if (this.state === 'down' || !this.ws || this.ws.readyState !== WebSocket.OPEN) {
+			throw new Error('WebSocket tunnel is not connected');
+		}
+
+		try {
+			// Serialize packet
+			const data = this.serializePacket(packet);
+
+			// Send through WebSocket
+			this.ws.send(data);
+
+			// Update stats
+			this.updateStats(data.byteLength, 'tx');
+		} catch (error) {
+			this.updateStats(0, 'tx', true);
+			throw error;
+		}
+	}
+
+	/**
+	 * Receive packet from WebSocket tunnel
+	 */
+	async recv(): Promise<Packet> {
+		if (this.state === 'down') {
+			throw new Error('WebSocket tunnel is down');
+		}
+
+		if (this.packetQueue.length > 0) {
+			return this.packetQueue.shift()!;
+		}
+
+		return new Promise((resolve) => {
+			this.waitingResolvers.push(resolve);
+		});
+	}
+
+	/**
+	 * Connect to WebSocket server
+	 */
+	private async connect(): Promise<void> {
+		return new Promise((resolve, reject) => {
+			try {
+				// Get WebSocket constructor
+				let WebSocketConstructor: typeof WebSocket;
+
+				if (typeof globalThis.WebSocket !== 'undefined') {
+					WebSocketConstructor = globalThis.WebSocket;
+				} else {
+					// Node.js - would need to import ws package
+					reject(new Error('WebSocket not available'));
+					return;
+				}
+
+				this.ws = new WebSocketConstructor(this.wsUrl);
+
+				this.ws.addEventListener('open', () => {
+					this.isReconnecting = false;
+					resolve();
+				});
+
+				this.ws.addEventListener('message', (event) => {
+					this.handleMessage(event.data);
+				});
+
+				this.ws.addEventListener('close', () => {
+					if (this.state === 'up' && !this.isReconnecting) {
+						this.scheduleReconnect();
+					}
+				});
+
+				this.ws.addEventListener('error', (error) => {
+					console.error('WebSocket tunnel error:', error);
+					if (this.state === 'down') {
+						reject(error);
+					}
+				});
+
+			} catch (error) {
+				reject(error);
+			}
+		});
+	}
+
+	/**
+	 * Schedule reconnection attempt
+	 */
+	private scheduleReconnect(): void {
+		if (this.isReconnecting) return;
+
+		this.isReconnecting = true;
+		this.reconnectTimer = setTimeout(async () => {
+			if (this.state === 'up') {
+				try {
+					await this.connect();
+				} catch (error) {
+					this.scheduleReconnect();
+				}
+			}
+		}, 5000);
+	}
+
+	/**
+	 * Handle incoming WebSocket message
+	 */
+	private handleMessage(data: any): void {
+		try {
+			const message = JSON.parse(data.toString());
+
+			if (message.type === 'request') {
+				// Handle HTTP request from tunnel server
+				this.handleHttpRequest(message);
+			} else if (message.type === 'response') {
+				// Handle response (if we're acting as client)
+				this.handleHttpResponse(message);
+			}
+		} catch (error) {
+			console.error('Error handling WebSocket message:', error);
+		}
+	}
+
+	/**
+	 * Handle HTTP request from tunnel server
+	 */
+	private async handleHttpRequest(message: any): Promise<void> {
+		const { requestId, method, url, headers, body } = message;
+
+		let port: number;
+		let path: string;
+
+		if (this.defaultPort) {
+			// Default port mode: all requests go to the default port
+			port = this.defaultPort;
+			path = url || '/';
+		} else {
+			// Path-based routing: /PORT/path
+			const match = url.match(/^\/(\d+)(\/.*)?$/);
+
+			if (!match) {
+				this.sendError(requestId, 400, 'Invalid URL format. Use /PORT/path or configure default port');
+				return;
+			}
+
+			port = parseInt(match[1], 10);
+			path = match[2] || '/';
+		}
+
+		// Check if port exists in registry
+		if (!this.portRegistry || !this.portRegistry.has(port)) {
+			this.sendError(requestId, 404, `No server listening on port ${port}`);
+			return;
+		}
+
+		// Get handler
+		const handler = this.portRegistry.get(port);
+
+		// Create virtual request/response
+		const vReq = {
+			method,
+			url: path,
+			headers,
+			body: Buffer.from(body || '', 'base64').toString(),
+		};
+
+		const vRes: VirtualResponseWithDone = {
+			statusCode: 200,
+			headers: {} as Record<string, string>,
+			body: '',
+		};
+
+		try {
+			// Call handler
+			handler(vReq, vRes);
+
+			// Wait for async middleware to call res.end() (populates vRes)
+			// Add a 25s safety timeout so we respond before external timeout
+			if (vRes._donePromise) {
+				const timeout = new Promise<'timeout'>((resolve) =>
+					setTimeout(() => resolve('timeout'), 25000)
+				);
+				const result = await Promise.race([vRes._donePromise.then(() => 'done' as const), timeout]);
+				if (result === 'timeout') {
+					console.error(`[WebSocketTunnel] TIMEOUT waiting for response: ${method} ${path}`);
+					this.sendError(requestId, 504, `Gateway timeout: server did not respond for ${path}`);
+					return;
+				}
+			}
+
+			// Send response back through WebSocket
+			this.sendResponse(requestId, vRes.statusCode, vRes.headers, vRes.body);
+
+			// Update stats
+			this.updateStats(vRes.body.length, 'tx');
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			this.sendError(requestId, 500, `Internal server error: ${errorMessage}`);
+		}
+	}
+
+	/**
+	 * Handle HTTP response (for client-side requests)
+	 */
+	private handleHttpResponse(_message: any): void {
+		// For future client-side request support
+		// Not needed for current server-only implementation
+	}
+
+	/**
+	 * Send HTTP response through WebSocket
+	 */
+	private sendResponse(requestId: string, statusCode: number, headers: Record<string, string>, body: string): void {
+		if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+			return;
+		}
+
+		const response = {
+			type: 'response',
+			requestId,
+			statusCode,
+			headers,
+			body: Buffer.from(body).toString('base64'),
+		};
+
+		this.ws.send(JSON.stringify(response));
+	}
+
+	/**
+	 * Send error response through WebSocket
+	 */
+	private sendError(requestId: string, statusCode: number, message: string): void {
+		if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+			return;
+		}
+
+		const response = {
+			type: 'response',
+			requestId,
+			statusCode,
+			headers: { 'Content-Type': 'text/plain' },
+			body: Buffer.from(message).toString('base64'),
+		};
+
+		this.ws.send(JSON.stringify(response));
+	}
+
+	/**
+	 * Serialize packet to bytes
+	 */
+	private serializePacket(packet: Packet): ArrayBuffer {
+		const header = new Uint8Array(9);
+		const view = new DataView(header.buffer);
+
+		view.setUint16(0, packet.source.port);
+		view.setUint16(2, packet.destination.port);
+		view.setUint8(4, packet.protocol === 'tcp' ? 6 : 17);
+		view.setUint32(5, packet.data.length);
+
+		const combined = new Uint8Array(header.length + packet.data.length);
+		combined.set(header);
+		combined.set(packet.data, header.length);
+
+		return combined.buffer;
+	}
+
+	/**
+	 * Get tunnel status string
+	 */
+	override toString(): string {
+		const base = super.toString();
+		const server = this.wsUrl;
+		const connected = this.ws && this.ws.readyState === WebSocket.OPEN ? '✓' : '✗';
+		const ports = this.portRegistry ? Array.from(this.portRegistry.keys()).join(',') : 'none';
+		return `${base} ${server} [${connected}] ports=${ports}`;
+	}
+
+	/**
+	 * Get connection status
+	 */
+	isConnected(): boolean {
+		return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+	}
+
+	/**
+	 * Get active ports
+	 */
+	getActivePorts(): number[] {
+		return this.portRegistry ? Array.from(this.portRegistry.keys()).sort((a, b) => a - b) : [];
+	}
+}

package/src/substrate/lifo/kernel/network/types.ts

@@ -0,0 +1,178 @@
+/**
+ * Network layer types and interfaces
+ * Implements a virtual network stack similar to Linux
+ */
+
+/**
+ * IP address (v4 or v6)
+ */
+export interface IPAddress {
+  version: 4 | 6;
+  address: string;
+  subnet?: string; // CIDR notation (e.g., "24" for /24)
+}
+
+/**
+ * Network interface state
+ */
+export type InterfaceState = 'up' | 'down';
+
+/**
+ * Network interface statistics
+ */
+export interface InterfaceStats {
+  rxPackets: number;
+  txPackets: number;
+  rxBytes: number;
+  txBytes: number;
+  rxErrors: number;
+  txErrors: number;
+  rxDropped: number;
+  txDropped: number;
+}
+
+/**
+ * Virtual network interface (like eth0, lo, etc.)
+ */
+export interface NetworkInterface {
+  name: string;
+  type: 'loopback' | 'ethernet' | 'tunnel';
+  state: InterfaceState;
+  mtu: number;
+  addresses: IPAddress[];
+  mac?: string; // MAC address (for ethernet interfaces)
+  stats: InterfaceStats;
+  namespace: string; // Network namespace ID
+}
+
+/**
+ * Routing table entry
+ */
+export interface RouteEntry {
+  destination: string; // IP or CIDR (e.g., "0.0.0.0/0" for default)
+  gateway?: string; // Next hop gateway
+  interface: string; // Interface name
+  metric: number; // Route priority
+  namespace: string; // Network namespace ID
+}
+
+/**
+ * Socket types
+ */
+export type SocketType = 'tcp' | 'udp' | 'raw';
+export type SocketState = 'closed' | 'listen' | 'syn-sent' | 'established' | 'close-wait' | 'fin-wait';
+
+/**
+ * Socket address
+ */
+export interface SocketAddress {
+  ip: string;
+  port: number;
+}
+
+/**
+ * Virtual socket
+ */
+export interface Socket {
+  fd: number; // File descriptor
+  type: SocketType;
+  state: SocketState;
+  localAddress?: SocketAddress;
+  remoteAddress?: SocketAddress;
+  namespace: string;
+
+  // Socket operations
+  bind(address: SocketAddress): void;
+  connect(address: SocketAddress): Promise<void>;
+  listen(backlog?: number): void;
+  accept(): Promise<Socket>;
+  send(data: Uint8Array): Promise<number>;
+  recv(maxBytes: number): Promise<Uint8Array>;
+  close(): void;
+  deliverPacket(packet: Packet): void;
+  toString(): string;
+}
+
+/**
+ * Network packet
+ */
+export interface Packet {
+  source: SocketAddress;
+  destination: SocketAddress;
+  protocol: SocketType;
+  data: Uint8Array;
+  timestamp: number;
+}
+
+/**
+ * DNS record types
+ */
+export type DNSRecordType = 'A' | 'AAAA' | 'CNAME' | 'MX' | 'TXT';
+
+/**
+ * DNS record
+ */
+export interface DNSRecord {
+  type: DNSRecordType;
+  name: string;
+  value: string;
+  ttl: number;
+}
+
+/**
+ * Network namespace
+ */
+export interface NetworkNamespace {
+  id: string;
+  name: string;
+  interfaces: Map<string, NetworkInterface>;
+  routes: RouteEntry[];
+  sockets: Map<number, Socket>;
+  arpTable: Map<string, string>; // IP -> MAC
+}
+
+/**
+ * Tunnel types
+ */
+export type TunnelType = 'ssh' | 'gre' | 'ipip' | 'vxlan';
+
+/**
+ * SSH tunnel configuration
+ */
+export interface SSHTunnelConfig {
+  type: 'local' | 'remote' | 'dynamic';
+  localAddress: SocketAddress;
+  remoteAddress: SocketAddress;
+  sshHost: string;
+  sshPort: number;
+  sshUser?: string;
+  sshKey?: string;
+}
+
+/**
+ * Network tunnel
+ */
+export interface NetworkTunnel {
+  id: string;
+  type: TunnelType;
+  state: 'up' | 'down';
+  interface: NetworkInterface;
+  config: SSHTunnelConfig | Record<string, unknown>;
+
+  // Tunnel operations
+  up(): Promise<void>;
+  down(): Promise<void>;
+  send(packet: Packet): Promise<void>;
+  recv(): Promise<Packet>;
+}
+
+/**
+ * Port binding
+ */
+export interface PortBinding {
+  port: number;
+  address: string;
+  protocol: SocketType;
+  handler: (socket: Socket) => void | Promise<void>;
+  namespace: string;
+}

package/src/substrate/lifo/kernel/persistence/PersistenceManager.ts

@@ -0,0 +1,50 @@
+import type { INode } from '../vfs/types.js';
+import { serialize, deserialize } from './serializer.js';
+import type { PersistenceBackend } from './backends.js';
+
+const DEBOUNCE_MS = 1000;
+
+export class PersistenceManager {
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(private backend: PersistenceBackend) {}
+
+  async open(): Promise<void> {
+    await this.backend.open();
+  }
+
+  async load(): Promise<INode | null> {
+    try {
+      const data = await this.backend.loadTree();
+      if (data) {
+        try {
+          return deserialize(data);
+        } catch {
+          return null;
+        }
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  async save(root: INode): Promise<void> {
+    try {
+      const data = serialize(root);
+      await this.backend.saveTree(data);
+    } catch {
+      // Gracefully ignore save errors
+    }
+  }
+
+  scheduleSave(root: INode): void {
+    if (this.timer) {
+      clearTimeout(this.timer);
+    }
+    this.timer = setTimeout(() => {
+      this.save(root).catch(() => {});
+      this.timer = null;
+    }, DEBOUNCE_MS);
+  }
+}

package/src/substrate/lifo/kernel/persistence/backends.ts

@@ -0,0 +1,36 @@
+import type { SerializedNode } from './serializer.js';
+
+// ---------------------------------------------------------------------------
+// PersistenceBackend interface
+// ---------------------------------------------------------------------------
+
+export interface PersistenceBackend {
+  open(): Promise<void>;
+  loadTree(): Promise<SerializedNode | null>;
+  saveTree(root: SerializedNode): Promise<void>;
+  close?(): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// MemoryPersistenceBackend
+// ---------------------------------------------------------------------------
+
+export class MemoryPersistenceBackend implements PersistenceBackend {
+  private tree: SerializedNode | null = null;
+
+  async open(): Promise<void> {
+    // Nothing to initialize for in-memory storage.
+  }
+
+  async loadTree(): Promise<SerializedNode | null> {
+    return this.tree;
+  }
+
+  async saveTree(root: SerializedNode): Promise<void> {
+    this.tree = root;
+  }
+
+  async close(): Promise<void> {
+    this.tree = null;
+  }
+}

package/src/substrate/lifo/kernel/persistence/index.ts

@@ -0,0 +1,5 @@
+export { PersistenceManager } from './PersistenceManager.js';
+export type { PersistenceBackend } from './backends.js';
+export { MemoryPersistenceBackend } from './backends.js';
+export { serialize, deserialize } from './serializer.js';
+export type { SerializedNode } from './serializer.js';