@frp-bridge/core 0.0.1 → 0.0.3

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { ClientConfig, ServerConfig, ProxyConfig } from '@frp-bridge/types';
+import { NodeRegisterPayload, NodeHeartbeatPayload, NodeInfo as NodeInfo$1, NodeListQuery, NodeListResponse, NodeStatistics, TunnelSyncPayload, ProxyConfig, ClientConfig, ServerConfig, RpcRequest as RpcRequest$1 } from '@frp-bridge/types';
+import { EventEmitter } from 'node:events';
 
 type Awaitable<T> = T | Promise<T>;
 type RuntimeMode = 'client' | 'server';
@@ -62,7 +63,7 @@ interface RuntimeError {
     message: string;
     details?: Record<string, unknown>;
 }
-type RuntimeErrorCode = 'VALIDATION_ERROR' | 'RUNTIME_ERROR' | 'SYSTEM_ERROR';
+type RuntimeErrorCode = 'VALIDATION_ERROR' | 'RUNTIME_ERROR' | 'SYSTEM_ERROR' | 'PORT_CONFLICT' | 'RPC_NOT_AVAILABLE' | 'RPC_ERROR';
 interface ConfigSnapshot {
     version: number;
     checksum: string;
@@ -113,13 +114,223 @@ declare class FrpRuntime {
     private now;
 }
 
+/**
+ * Client-side node information collector
+ * Gathers system information and reports to server via heartbeat
+ */
+
+interface ClientCollectorOptions {
+    /** Node ID (set by server after registration) */
+    nodeId?: string;
+    /** Heartbeat interval in milliseconds (default: 30000) */
+    heartbeatInterval?: number;
+    /** Logger instance */
+    logger?: {
+        debug?: (msg: string, data?: unknown) => void;
+        info?: (msg: string, data?: unknown) => void;
+        error?: (msg: string, error?: unknown) => void;
+    };
+}
+/**
+ * Collects node information on client side
+ * Used in client mode to send system info and heartbeat to server
+ */
+declare class ClientNodeCollector {
+    private nodeId?;
+    private heartbeatInterval;
+    private logger;
+    private heartbeatTimer?;
+    constructor(options?: ClientCollectorOptions);
+    /** Set node ID after server registration */
+    setNodeId(nodeId: string): void;
+    /** Collect current node information */
+    collectNodeInfo(): Partial<NodeRegisterPayload>;
+    /** Collect heartbeat payload */
+    collectHeartbeat(): Partial<NodeHeartbeatPayload>;
+    /**
+     * Start periodic heartbeat collection
+     * Callback will be called at each interval with heartbeat payload
+     */
+    startHeartbeat(callback: (payload: Partial<NodeHeartbeatPayload>) => void, interval?: number): void;
+    /** Stop periodic heartbeat collection */
+    stopHeartbeat(): void;
+    /** Check if heartbeat is running */
+    isHeartbeatRunning(): boolean;
+}
+
+/**
+ * Node Manager for server-side node management
+ * Handles node registration, heartbeat, tunnel registry, and queries
+ */
+
+interface NodeManagerOptions {
+    heartbeatTimeout?: number;
+    logger?: Partial<RuntimeLogger>;
+}
+interface NodeStorage {
+    save: (node: NodeInfo$1) => Promise<void> | void;
+    delete: (id: string) => Promise<void> | void;
+    load: (id: string) => Promise<NodeInfo$1 | undefined> | NodeInfo$1 | undefined;
+    list: () => Promise<NodeInfo$1[]> | NodeInfo$1[];
+}
+type NodeEvent = 'node:registered' | 'node:heartbeat' | 'node:unregistered' | 'node:statusChanged' | 'tunnel:synced';
+/**
+ * Manages nodes in server mode
+ * Stores node info, handles heartbeat, manages global tunnel registry, emits events
+ */
+declare class NodeManager extends EventEmitter {
+    private context;
+    private nodes;
+    private heartbeatTimers;
+    private tunnelRegistry;
+    private storage?;
+    private heartbeatTimeout;
+    private readonly log;
+    constructor(context: RuntimeContext, options?: NodeManagerOptions, storage?: NodeStorage);
+    initialize(): Promise<void>;
+    /** Register a new node (called when client connects) */
+    registerNode(payload: NodeRegisterPayload): Promise<NodeInfo$1>;
+    /** Update node heartbeat and status */
+    updateHeartbeat(payload: NodeHeartbeatPayload): Promise<void>;
+    /** Unregister a node (called when client disconnects) */
+    unregisterNode(nodeId: string): Promise<void>;
+    /** Get node by id */
+    getNode(id: string): Promise<NodeInfo$1 | undefined>;
+    /** List nodes with pagination and filtering */
+    listNodes(query?: NodeListQuery): Promise<NodeListResponse>;
+    /** Get node statistics */
+    getStatistics(): Promise<NodeStatistics>;
+    /** Check if node exists */
+    hasNode(id: string): boolean;
+    /** Get all online nodes */
+    getOnlineNodes(): NodeInfo$1[];
+    /** Get all offline nodes */
+    getOfflineNodes(): NodeInfo$1[];
+    /** Get nodes by status */
+    getNodesByStatus(status: NodeInfo$1['status']): NodeInfo$1[];
+    /** Setup heartbeat timer for a node */
+    private setupHeartbeatTimer;
+    /** Clear heartbeat timer for a node */
+    private clearHeartbeatTimer;
+    /** Handle heartbeat timeout */
+    private handleHeartbeatTimeout;
+    /** Sync tunnels for a node (called when node connects or updates tunnels) */
+    syncTunnels(payload: TunnelSyncPayload): Promise<void>;
+    /** Get tunnels for a specific node */
+    getNodeTunnels(nodeId: string): ProxyConfig[];
+    /** Get all tunnels across all nodes */
+    getAllTunnels(): Map<string, ProxyConfig[]>;
+    /** Check if a remotePort is in use across all nodes (for conflict detection) */
+    isRemotePortInUse(remotePort: number, excludeNodeId?: string): {
+        inUse: boolean;
+        nodeId?: string;
+        tunnelName?: string;
+    };
+    /** Clear tunnels for a node (called when node disconnects) */
+    private clearNodeTunnels;
+    /** Update dispose method to clear tunnels */
+    dispose(): Promise<void>;
+}
+
+/**
+ * File-based node storage implementation
+ * Persists node information to disk
+ */
+
+/**
+ * Stores nodes in JSON files
+ * Directory structure:
+ * ~/.frp-bridge/runtime/nodes/
+ *   ├── nodes.json (index of all nodes)
+ *   └── node-{id}.json (individual node data)
+ */
+declare class FileNodeStorage implements NodeStorage {
+    private storagePath;
+    private indexPath;
+    private nodeDir;
+    constructor(storagePath: string);
+    /** Save or update a node */
+    save(node: NodeInfo$1): Promise<void>;
+    /** Delete a node */
+    delete(id: string): Promise<void>;
+    /** Load a single node */
+    load(id: string): Promise<NodeInfo$1 | undefined>;
+    /** Load all nodes */
+    list(): Promise<NodeInfo$1[]>;
+    /** Update the index of node IDs */
+    private updateIndex;
+}
+
+/**
+ * 配置合并方法 - core 包内部使用
+ * 将预设配置和用户配置合并成最终的 frp 配置
+ */
+
+/**
+ * 预设配置接口
+ */
+interface PresetConfig {
+    frps?: FrpsPresetConfig;
+    frpc?: FrpcPresetConfig;
+}
+interface FrpsPresetConfig {
+    bindPort?: number;
+    vhostHTTPPort?: number;
+    vhostHTTPSPort?: number;
+    domain?: string;
+    dashboardPort?: number;
+    dashboardUser?: string;
+    dashboardPassword?: string;
+    authToken?: string;
+    subdomainHost?: string;
+}
+interface FrpcPresetConfig {
+    serverAddr?: string;
+    serverPort?: number;
+    authToken?: string;
+    user?: string;
+    heartbeatInterval?: number;
+}
+/**
+ * 默认预设配置
+ */
+declare const DEFAULT_PRESET_CONFIG: PresetConfig;
+/**
+ * 合并预设配置和用户配置，生成最终的 TOML 配置
+ */
+declare function mergeConfigs(presetConfig: PresetConfig, userConfig: string, type: 'frps' | 'frpc'): string;
+/**
+ * 从 tunnels 数组生成并保存 FRP 配置文件
+ */
+declare function saveFrpConfigFile(configPath: string, tunnels: ProxyConfig[], presetConfig: PresetConfig, type: 'frps' | 'frpc'): void;
+/**
+ * 将配置对象转换为 TOML 格式
+ */
+declare function configToToml(config: Record<string, any>): string;
+/**
+ * 验证预设配置
+ */
+declare function validatePresetConfig(config: PresetConfig, type: 'frps' | 'frpc'): {
+    valid: boolean;
+    errors: string[];
+};
+
 /**
  * FRP process management utilities
+ *
+ * This class serves as a facade that delegates to specialized components:
+ * - ProcessController: Process lifecycle management
+ * - ConfigurationStore: Configuration file operations
+ * - TunnelManager: Tunnel/proxy management
+ * - NodeManager: Node information management
+ * - BinaryManager: Binary file management
  */
 
 interface FrpProcessManagerOptions {
     /** Working directory for FRP files */
     workDir?: string;
+    /** Path to config file (overrides default) */
+    configPath?: string;
     /** FRP version (defaults to latest) */
     version?: string;
     /** Mode: client or server */
@@ -143,16 +354,29 @@ interface NodeInfo {
 }
 /**
  * Manages FRP client/server lifecycle, config, and tunnels
+ *
+ * This class now serves as a facade that delegates to specialized components:
+ * - ProcessController: Process lifecycle management
+ * - ConfigurationStore: Configuration file operations
+ * - TunnelManager: Tunnel/proxy management
+ * - NodeManager: Node information management
+ * - BinaryManager: Binary file management
  */
-declare class FrpProcessManager {
+declare class FrpProcessManager extends EventEmitter {
     private readonly workDir;
-    private version;
     private readonly mode;
     private readonly specifiedVersion?;
     private readonly logger;
+    private readonly configPath;
+    private readonly processController;
+    private readonly configStore;
+    private readonly binaryManager;
+    private readonly presetConfigManager;
+    private tunnelManager;
+    private nodeManager;
     private process;
-    private configPath;
-    private binaryPath;
+    private uptime;
+    private isManualStop;
     constructor(options: FrpProcessManagerOptions);
     /** Ensure version is fetched and binary path is set */
     private ensureVersion;
@@ -163,17 +387,17 @@ declare class FrpProcessManager {
     /** Check if binary exists */
     hasBinary(): boolean;
     /** Get current configuration */
-    getConfig(): ClientConfig | ServerConfig | null;
+    getConfig(): Promise<ClientConfig | ServerConfig | null>;
     /** Update configuration */
-    updateConfig(config: Partial<ClientConfig | ServerConfig>): void;
+    updateConfig(config: Partial<ClientConfig | ServerConfig>): Promise<void>;
     /** Backup configuration */
     backupConfig(): Promise<string>;
     /** Return the absolute config file path */
     getConfigPath(): string;
     /** Read raw config file contents */
-    readConfigFile(): string | null;
+    getConfigRaw(): string | null;
     /** Overwrite config file with provided content */
-    writeConfigFile(content: string): void;
+    updateConfigRaw(content: string): void;
     /** Start FRP process */
     start(): Promise<void>;
     /** Stop FRP process */
@@ -181,23 +405,492 @@ declare class FrpProcessManager {
     /** Check if process is running */
     isRunning(): boolean;
     /** Add node (for client mode) */
-    addNode(node: NodeInfo): void;
+    addNode(node: NodeInfo): Promise<void>;
     /** Get node info */
-    getNode(): NodeInfo | null;
+    getNode(): Promise<NodeInfo | null>;
     /** Update node info */
-    updateNode(node: Partial<NodeInfo>): void;
+    updateNode(node: Partial<NodeInfo>): Promise<void>;
     /** Remove node */
-    removeNode(): void;
+    removeNode(): Promise<void>;
     /** Add tunnel (proxy) */
-    addTunnel(proxy: ProxyConfig): void;
+    addTunnel(proxy: ProxyConfig): Promise<void>;
     /** Get tunnel by name */
-    getTunnel(name: string): ProxyConfig | null;
+    getTunnel(name: string): Promise<ProxyConfig | null>;
     /** Update tunnel */
-    updateTunnel(name: string, proxy: Partial<ProxyConfig>): void;
+    updateTunnel(name: string, proxy: Partial<ProxyConfig>): Promise<void>;
     /** Remove tunnel */
-    removeTunnel(name: string): void;
+    removeTunnel(name: string): Promise<void>;
     /** List all tunnels */
-    listTunnels(): ProxyConfig[];
+    listTunnels(): Promise<ProxyConfig[]>;
+    /**
+     * 生成 FRP 配置文件（合并预设配置和用户 tunnels）
+     * @param force 是否强制重新生成
+     */
+    generateConfig(force?: boolean): Promise<void>;
+    /**
+     * 获取预设配置
+     */
+    getPresetConfig(): PresetConfig;
+    /**
+     * 保存预设配置
+     */
+    savePresetConfig(config: Record<string, any>): void;
+    /**
+     * Query current process status
+     */
+    queryProcess(): {
+        pid: number | undefined;
+        uptime: number;
+    };
+}
+
+/**
+ * RPC 消息类型定义
+ * 提供类型安全的消息结构和类型守卫
+ */
+/**
+ * RPC 消息类型枚举
+ */
+declare enum RpcMessageType {
+    REGISTER = "register",
+    COMMAND = "command",
+    RESPONSE = "response",
+    PING = "ping",
+    PONG = "pong"
+}
+/**
+ * 节点注册消息
+ */
+interface RegisterMessage {
+    type: RpcMessageType.REGISTER;
+    nodeId: string;
+    payload: Record<string, unknown>;
+}
+/**
+ * RPC 请求
+ */
+interface RpcRequest {
+    id: string;
+    method: string;
+    params: Record<string, unknown>;
+    timeout?: number;
+}
+/**
+ * RPC 响应状态
+ */
+type RpcResponseStatus = 'success' | 'error';
+/**
+ * RPC 响应
+ */
+interface RpcResponse {
+    id: string;
+    status: RpcResponseStatus;
+    result?: unknown;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Ping 消息
+ */
+interface PingMessage {
+    type: RpcMessageType.PING;
+    timestamp: number;
+}
+/**
+ * Pong 消息
+ */
+interface PongMessage {
+    type: RpcMessageType.PONG;
+    timestamp: number;
+}
+/**
+ * 所有 RPC 消息类型
+ */
+type RpcMessage = RegisterMessage | RpcRequest | RpcResponse | PingMessage | PongMessage;
+/**
+ * Event-based RPC message type (matching document spec)
+ */
+interface EventRpcMessage {
+    type: 'command' | 'event';
+    action: string;
+    payload: unknown;
+    id?: string;
+    targetNodeId?: string;
+}
+/**
+ * Command message (frps -> frpc)
+ */
+interface CommandRpcMessage extends EventRpcMessage {
+    type: 'command';
+    id: string;
+}
+/**
+ * Event message (frpc -> frps)
+ */
+interface EventRpcMessageEvent extends EventRpcMessage {
+    type: 'event';
+    id?: string;
+}
+/**
+ * Tunnel add payload
+ */
+interface TunnelAddPayload {
+    name: string;
+    type: 'tcp' | 'http' | 'https' | 'stcp' | 'sudp' | 'xtcp';
+    localPort: number;
+    remotePort?: number;
+    customDomains?: string[];
+    subdomain?: string;
+    nodeId?: string;
+    [key: string]: unknown;
+}
+/**
+ * Tunnel delete payload
+ */
+interface TunnelDeletePayload {
+    name: string;
+    nodeId?: string;
+}
+/**
+ * Tunnel response payload
+ */
+interface TunnelResponsePayload {
+    success: boolean;
+    error?: string;
+    tunnel?: TunnelAddPayload;
+}
+/**
+ * Node delete payload
+ */
+interface NodeDeletePayload {
+    name: string;
+}
+/**
+ * Node response payload
+ */
+interface NodeResponsePayload {
+    success: boolean;
+    error?: string;
+    deletedNode?: string;
+}
+/**
+ * All message types including event-based
+ */
+type AllRpcMessage = RpcMessage | EventRpcMessage;
+/**
+ * 类型守卫：检查是否为注册消息
+ */
+declare function isRegisterMessage(msg: unknown): msg is RegisterMessage;
+/**
+ * 类型守卫：检查是否为 RPC 请求
+ */
+declare function isRpcRequest(msg: unknown): msg is RpcRequest;
+/**
+ * 类型守卫：检查是否为 RPC 响应
+ */
+declare function isRpcResponse(msg: unknown): msg is RpcResponse;
+/**
+ * 类型守卫：检查是否为 Ping 消息
+ */
+declare function isPingMessage(msg: unknown): msg is PingMessage;
+/**
+ * 类型守卫：检查是否为 Pong 消息
+ */
+declare function isPongMessage(msg: unknown): msg is PongMessage;
+/**
+ * 类型守卫：检查是否为 Event-based RPC 消息
+ */
+declare function isEventRpcMessage(msg: unknown): msg is EventRpcMessage;
+/**
+ * 类型守卫：检查是否为 Command 消息
+ */
+declare function isCommandMessage(msg: unknown): msg is CommandRpcMessage;
+/**
+ * 类型守卫：检查是否为 Event 消息
+ */
+declare function isEventMessage(msg: unknown): msg is EventRpcMessageEvent;
+/**
+ * 类型守卫：检查是否为 TunnelAddPayload
+ */
+declare function isTunnelAddPayload(data: unknown): data is TunnelAddPayload;
+/**
+ * 类型守卫：检查是否为 TunnelDeletePayload
+ */
+declare function isTunnelDeletePayload(data: unknown): data is TunnelDeletePayload;
+/**
+ * 类型守卫：检查是否为 NodeDeletePayload
+ */
+declare function isNodeDeletePayload(data: unknown): data is NodeDeletePayload;
+
+/**
+ * RPC 中间件系统
+ * 提供可扩展的请求处理管道
+ */
+
+/**
+ * 中间件上下文
+ */
+interface MiddlewareContext {
+    request: RpcRequest;
+    response: Partial<RpcResponse>;
+    startTime: number;
+}
+/**
+ * 中间件函数类型
+ */
+type MiddlewareFn = (context: MiddlewareContext, next: () => Promise<void>) => Promise<void>;
+/**
+ * 中间件选项
+ */
+interface MiddlewareOptions {
+    preHooks?: MiddlewareFn[];
+    postHooks?: MiddlewareFn[];
+}
+/**
+ * 日志中间件
+ */
+declare function loggingMiddleware(logger?: {
+    info?: (msg: string, data?: unknown) => void;
+    warn?: (msg: string, data?: unknown) => void;
+    error?: (msg: string, data?: unknown) => void;
+}): MiddlewareFn;
+/**
+ * 认证中间件
+ */
+declare function authMiddleware(validateToken: (token: string | undefined) => boolean | Promise<boolean>): MiddlewareFn;
+/**
+ * 超时中间件
+ */
+declare function timeoutMiddleware(timeoutMs: number): MiddlewareFn;
+/**
+ * 错误处理中间件
+ */
+declare function errorHandlerMiddleware(logger?: {
+    error?: (msg: string, data?: unknown) => void;
+}): MiddlewareFn;
+/**
+ * 中间件管道
+ */
+declare class MiddlewarePipeline {
+    private middlewares;
+    /**
+     * 添加中间件
+     */
+    use(middleware: MiddlewareFn): this;
+    /**
+     * 执行中间件管道
+     */
+    execute(request: RpcRequest, handler: () => Promise<unknown>): Promise<Partial<RpcResponse>>;
+    /**
+     * 执行处理器
+     */
+    private executeHandler;
+    /**
+     * 清空中间件
+     */
+    clear(): void;
+}
+
+/**
+ * RPC 重连策略
+ * 提供可配置的重连机制，包括指数退避
+ */
+/**
+ * 重连策略接口
+ */
+interface ReconnectStrategy {
+    /**
+     * 判断是否应该重连
+     */
+    shouldReconnect: (attempt: number) => boolean;
+    /**
+     * 获取重连延迟时间（毫秒）
+     */
+    getDelay: (attempt: number) => number;
+    /**
+     * 达到最大重连次数时的回调
+     */
+    onMaxAttemptsReached: () => void;
+}
+/**
+ * 指数退避重连策略
+ */
+declare class ExponentialBackoffStrategy implements ReconnectStrategy {
+    private maxAttempts;
+    private baseDelay;
+    private maxDelay;
+    private logger?;
+    constructor(maxAttempts?: number, baseDelay?: number, maxDelay?: number, logger?: {
+        error?: (msg: string, data?: unknown) => void;
+    } | undefined);
+    shouldReconnect(attempt: number): boolean;
+    getDelay(attempt: number): number;
+    onMaxAttemptsReached(): void;
+}
+/**
+ * 固定间隔重连策略
+ */
+declare class FixedIntervalStrategy implements ReconnectStrategy {
+    private maxAttempts;
+    private interval;
+    private logger?;
+    constructor(maxAttempts?: number, interval?: number, logger?: {
+        error?: (msg: string, data?: unknown) => void;
+    } | undefined);
+    shouldReconnect(attempt: number): boolean;
+    getDelay(): number;
+    onMaxAttemptsReached(): void;
+}
+/**
+ * 线性增长重连策略
+ */
+declare class LinearBackoffStrategy implements ReconnectStrategy {
+    private maxAttempts;
+    private baseDelay;
+    private increment;
+    private maxDelay;
+    private logger?;
+    constructor(maxAttempts?: number, baseDelay?: number, increment?: number, maxDelay?: number, logger?: {
+        error?: (msg: string, data?: unknown) => void;
+    } | undefined);
+    shouldReconnect(attempt: number): boolean;
+    getDelay(attempt: number): number;
+    onMaxAttemptsReached(): void;
+}
+/**
+ * 无限重连策略（永不停止）
+ */
+declare class InfiniteReconnectStrategy implements ReconnectStrategy {
+    private baseDelay;
+    private maxDelay;
+    constructor(baseDelay?: number, maxDelay?: number);
+    shouldReconnect(): boolean;
+    getDelay(attempt: number): number;
+    onMaxAttemptsReached(): void;
+}
+
+interface RpcClientOptions {
+    url: string;
+    nodeId: string;
+    getRegisterPayload: () => Promise<NodeInfo$1> | NodeInfo$1;
+    handleRequest: (req: RpcRequest$1) => Promise<unknown>;
+    handleCommand?: (command: CommandRpcMessage) => Promise<unknown>;
+    reconnectStrategy?: ReconnectStrategy;
+    logger?: Partial<RuntimeLogger>;
+}
+declare class RpcClient {
+    private readonly options;
+    private ws;
+    private reconnectTimer?;
+    private reconnectAttempt;
+    private readonly reconnectStrategy;
+    private connectionState;
+    private readonly log;
+    constructor(options: RpcClientOptions);
+    connect(): Promise<void>;
+    disconnect(): void;
+    /**
+     * Get current connection state
+     */
+    getConnectionState(): 'connecting' | 'connected' | 'disconnected';
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Send an event message to server (matching document spec)
+     */
+    sendEvent(event: EventRpcMessageEvent): boolean;
+    private createConnection;
+    private handleMessage;
+    /**
+     * Handle event-based command messages from server (matching document spec)
+     */
+    private handleCommandEvent;
+    private handleRpcRequest;
+    private send;
+    private scheduleReconnect;
+}
+
+/**
+ * Command status for tracking
+ */
+interface RpcCommandStatus {
+    commandId: string;
+    nodeId: string;
+    action: string;
+    status: 'pending' | 'completed' | 'failed';
+    result?: unknown;
+    error?: string;
+    timestamp: number;
+}
+interface RpcServerOptions {
+    port: number;
+    heartbeatInterval?: number;
+    validateToken?: (token: string | undefined, nodeId: string | undefined) => boolean | Promise<boolean>;
+    authorize?: (nodeId: string, method: string) => boolean | Promise<boolean>;
+    onRegister?: (nodeId: string, payload: NodeInfo$1) => void | Promise<void>;
+    onEvent?: (nodeId: string, event: EventRpcMessage) => void | Promise<void>;
+    commandTimeout?: number;
+    logger?: Partial<RuntimeLogger>;
+}
+declare class RpcServer {
+    private readonly options;
+    private readonly clients;
+    private readonly pendingRequests;
+    private readonly commandStatuses;
+    private readonly wsToNode;
+    private heartbeatTimer?;
+    private server?;
+    private readonly defaultCommandTimeout;
+    private readonly log;
+    constructor(options: RpcServerOptions);
+    start(): void;
+    stop(): void;
+    rpcCall(nodeId: string, method: string, params: Record<string, unknown>, timeout?: number): Promise<unknown>;
+    /**
+     * Send event-based message to a specific node (matching document spec)
+     */
+    sendToNode(nodeId: string, message: EventRpcMessage): boolean;
+    /**
+     * Broadcast event-based message to all connected nodes
+     */
+    broadcast(message: EventRpcMessage): void;
+    /**
+     * Get list of all online node IDs
+     */
+    getOnlineNodes(): string[];
+    /**
+     * Check if a specific node is online
+     */
+    isNodeOnline(nodeId: string): boolean;
+    /**
+     * Get the count of online nodes
+     */
+    getOnlineNodeCount(): number;
+    /**
+     * Get command status by ID
+     */
+    getRpcCommandStatus(commandId: string): RpcCommandStatus | undefined;
+    /**
+     * Get all command statuses
+     */
+    getAllRpcCommandStatuses(): RpcCommandStatus[];
+    /**
+     * Clear completed/failed command statuses older than specified milliseconds
+     */
+    clearOldStatuses(maxAge?: number): void;
+    private handleMessage;
+    /**
+     * Handle event-based messages from clients
+     */
+    private handleEventMessage;
+    private handleRegister;
+    private handleRpcResponse;
+    private handleClose;
+    private startHeartbeat;
 }
 
 interface FrpBridgeRuntimeOptions {
@@ -210,34 +903,93 @@ interface FrpBridgeRuntimeOptions {
 }
 interface FrpBridgeProcessOptions extends Partial<Omit<FrpProcessManagerOptions, 'mode'>> {
     mode?: 'client' | 'server';
-    workDir?: string;
 }
+interface FrpBridgeRpcOptions {
+    serverPort?: number;
+    serverHeartbeatInterval?: number;
+    serverValidateToken?: (token: string | undefined, nodeId: string | undefined) => boolean | Promise<boolean>;
+    serverAuthorize?: (nodeId: string, method: string) => boolean | Promise<boolean>;
+    serverOnRegister?: (nodeId: string, payload: NodeInfo$1) => void | Promise<void>;
+    serverOnEvent?: (nodeId: string, event: EventRpcMessage) => void | Promise<void>;
+    serverCommandTimeout?: number;
+    clientUrl?: string;
+    clientNodeId?: string;
+    clientToken?: string;
+    clientReconnectInterval?: number;
+    getRegisterPayload?: () => Promise<NodeInfo$1> | NodeInfo$1;
+    handleRequest?: (req: RpcRequest$1) => Promise<unknown>;
+}
+
 interface FrpBridgeOptions {
     mode: 'client' | 'server';
     workDir?: string;
+    configPath?: string;
     runtime?: FrpBridgeRuntimeOptions;
     process?: FrpBridgeProcessOptions;
+    rpc?: FrpBridgeRpcOptions;
     storage?: SnapshotStorage;
     commands?: Record<string, CommandHandler>;
     queries?: Record<string, QueryHandler>;
     eventSink?: (event: RuntimeEvent) => void;
 }
+/**
+ * FrpBridge - Main facade class for managing FRP bridge operations.
+ *
+ * This class serves as a facade that coordinates multiple components:
+ * - Runtime management (command/query execution)
+ * - Process management (FRP process lifecycle)
+ * - Node management (server mode only)
+ * - RPC communication
+ *
+ * Design patterns used:
+ * - Facade Pattern: Simplifies interface to complex subsystems
+ * - Dependency Injection: All dependencies injected via constructor
+ * - Factory Pattern: Handlers created via factory functions
+ */
 declare class FrpBridge {
-    private readonly options;
     private readonly runtime;
     private readonly process;
+    private readonly mode;
     private readonly eventSink?;
+    private readonly nodeManager?;
+    private readonly clientCollector?;
+    private readonly rpcServer?;
+    private readonly rpcClient?;
     constructor(options: FrpBridgeOptions);
+    /**
+     * Execute a command
+     */
     execute<TPayload, TResult = unknown>(command: RuntimeCommand<TPayload>): Promise<CommandResult<TResult>>;
+    /**
+     * Execute a query
+     */
     query<TPayload, TResult = unknown>(query: RuntimeQuery<TPayload>): Promise<QueryResult<TResult>>;
+    /**
+     * Get current runtime state snapshot
+     */
     snapshot(): RuntimeState;
+    /**
+     * Drain and return all pending events
+     */
     drainEvents(): RuntimeEvent[];
     getProcessManager(): FrpProcessManager;
     getRuntime(): FrpRuntime;
-    private createDefaultCommands;
-    private createDefaultQueries;
+    getNodeManager(): NodeManager | undefined;
+    getClientCollector(): ClientNodeCollector | undefined;
+    getRpcServer(): RpcServer | undefined;
+    getRpcClient(): RpcClient | undefined;
+    /**
+     * Initialize all async components
+     */
+    initialize(): Promise<void>;
+    /**
+     * Cleanup and dispose all resources
+     */
+    dispose(): Promise<void>;
+    /**
+     * Forward runtime events to external event sink
+     */
     private forwardEvents;
-    private runConfigMutation;
 }
 
 /**
@@ -257,26 +1009,122 @@ declare const ARCH_MAP: Record<string, string>;
 /** Platform OS mapping */
 declare const OS_MAP: Record<string, string>;
 
-/** Custom error for FRP Bridge operations */
-declare class FrpBridgeError extends Error {
+/**
+ * Base error class for all FRP Bridge errors
+ * Provides consistent error structure and handling
+ */
+declare abstract class FrpBridgeErrorBase extends Error {
+    /**
+     * Error code for programmatic error handling
+     */
+    abstract readonly code: string;
+    /**
+     * HTTP status code (optional, for API responses)
+     */
+    readonly statusCode?: number;
+    /**
+     * Additional error details
+     */
+    readonly details?: unknown;
+    constructor(message: string, details?: unknown);
+    /**
+     * Convert error to plain object for serialization
+     */
+    toJSON(): {
+        code: string;
+        message: string;
+        statusCode?: number;
+        details?: unknown;
+    };
+}
+/**
+ * Generic error for uncategorized errors
+ */
+declare class GenericError extends FrpBridgeErrorBase {
     readonly code: string;
-    readonly details?: unknown | undefined;
-    constructor(message: string, code: string, details?: unknown | undefined);
-}
-/** Error codes */
-declare enum ErrorCode {
-    BINARY_NOT_FOUND = "BINARY_NOT_FOUND",
-    DOWNLOAD_FAILED = "DOWNLOAD_FAILED",
-    EXTRACTION_FAILED = "EXTRACTION_FAILED",
-    CONFIG_NOT_FOUND = "CONFIG_NOT_FOUND",
-    CONFIG_INVALID = "CONFIG_INVALID",
-    PROCESS_ALREADY_RUNNING = "PROCESS_ALREADY_RUNNING",
-    PROCESS_NOT_RUNNING = "PROCESS_NOT_RUNNING",
-    PROCESS_START_FAILED = "PROCESS_START_FAILED",
-    UNSUPPORTED_PLATFORM = "UNSUPPORTED_PLATFORM",
-    VERSION_FETCH_FAILED = "VERSION_FETCH_FAILED",
-    MODE_ERROR = "MODE_ERROR",
-    NOT_FOUND = "NOT_FOUND"
+    constructor(message: string, code: string, details?: unknown);
+}
+
+/**
+ * Categorized error classes for FRP Bridge
+ * Each error extends FrpBridgeErrorBase directly
+ */
+
+/**
+ * Configuration errors (400 Bad Request)
+ */
+declare class ConfigNotFoundError extends FrpBridgeErrorBase {
+    readonly code = "CONFIG_NOT_FOUND";
+    readonly statusCode = 400;
+}
+declare class ConfigInvalidError extends FrpBridgeErrorBase {
+    readonly code = "CONFIG_INVALID";
+    readonly statusCode = 400;
+}
+/**
+ * Process errors
+ */
+declare class ProcessNotRunningError extends FrpBridgeErrorBase {
+    readonly code = "PROCESS_NOT_RUNNING";
+    readonly statusCode = 409;
+}
+declare class ProcessAlreadyRunningError extends FrpBridgeErrorBase {
+    readonly code = "PROCESS_ALREADY_RUNNING";
+    readonly statusCode = 409;
+}
+declare class ProcessStartFailedError extends FrpBridgeErrorBase {
+    readonly code = "PROCESS_START_FAILED";
+    readonly statusCode = 500;
+}
+/**
+ * Binary errors (500 Internal Server Error)
+ */
+declare class BinaryNotFoundError extends FrpBridgeErrorBase {
+    readonly code = "BINARY_NOT_FOUND";
+    readonly statusCode = 500;
+}
+declare class DownloadFailedError extends FrpBridgeErrorBase {
+    readonly code = "DOWNLOAD_FAILED";
+    readonly statusCode = 500;
+}
+declare class ExtractionFailedError extends FrpBridgeErrorBase {
+    readonly code = "EXTRACTION_FAILED";
+    readonly statusCode = 500;
+}
+/**
+ * Network/Version errors (503 Service Unavailable)
+ */
+declare class VersionFetchError extends FrpBridgeErrorBase {
+    readonly code = "VERSION_FETCH_FAILED";
+    readonly statusCode = 503;
+}
+/**
+ * Validation errors (400 Bad Request)
+ */
+declare class ValidationError extends FrpBridgeErrorBase {
+    readonly code = "VALIDATION_ERROR";
+    readonly statusCode = 400;
+}
+/**
+ * Mode/State errors (409 Conflict)
+ */
+declare class ModeError extends FrpBridgeErrorBase {
+    readonly code = "MODE_ERROR";
+    readonly statusCode = 409;
+}
+/**
+ * Resource not found (404 Not Found)
+ */
+declare class NotFoundError extends FrpBridgeErrorBase {
+    readonly code = "NOT_FOUND";
+    readonly statusCode = 404;
+}
+/**
+ * Platform errors (500 Internal Server Error)
+ */
+declare class PlatformError extends FrpBridgeErrorBase {
+    readonly code = "UNSUPPORTED_PLATFORM";
+    readonly statusCode = 500;
 }
 
 declare class FileSnapshotStorage implements SnapshotStorage {
@@ -288,6 +1136,51 @@ declare class FileSnapshotStorage implements SnapshotStorage {
     private buildPath;
 }
 
+/**
+ * Unified TOML parsing and serialization module
+ * Wraps smol-toml with consistent error handling
+ */
+interface ParseOptions {
+    /**
+     * Parse integers as BigInt
+     */
+    integersAsBigInt?: boolean | 'asNeeded';
+}
+interface StringifyOptions {
+    /**
+     * Serialize numbers as floats
+     */
+    numbersAsFloat?: boolean;
+}
+/**
+ * Parse TOML string to JavaScript object
+ * @param content - TOML string content
+ * @param options - Parse options
+ * @returns Parsed JavaScript object
+ * @throws {Error} If TOML is invalid
+ */
+declare function parse<T = Record<string, any>>(content: string, options?: ParseOptions): T;
+/**
+ * Serialize JavaScript object to TOML string
+ * @param obj - JavaScript object to serialize
+ * @param options - Stringify options
+ * @returns TOML string
+ * @throws {Error} If object contains unserializable values
+ */
+declare function stringify(obj: Record<string, any>, options?: StringifyOptions): string;
+/**
+ * Check if a string is valid TOML
+ * @param content - String content to check
+ * @returns true if valid TOML, false otherwise
+ */
+declare function isValidToml(content: string): boolean;
+/**
+ * Parse TOML file content safely (returns null on error)
+ * @param content - TOML string content
+ * @returns Parsed object or null if parsing fails
+ */
+declare function safeParse<T = Record<string, any>>(content: string): T | null;
+
 /**
  * Utility functions
  */
@@ -308,10 +1201,16 @@ declare function executeCommand(command: string): Promise<{
 declare function commandExists(command: string): Promise<boolean>;
 /** Ensure directory exists */
 declare function ensureDir(dirPath: string): void;
-/** Parse TOML-like config to JSON */
+/** Find existing FRP version in work directory */
+declare function findExistingVersion(workDir: string): string | null;
+/**
+ * Parse TOML-like config to JSON
+ */
 declare function parseToml(content: string): Record<string, any>;
-/** Convert JSON to TOML-like config */
+/**
+ * Convert JSON to TOML-like config
+ */
 declare function toToml(obj: Record<string, any>): string;
 
-export { ARCH_MAP, BINARY_NAMES, ErrorCode, FileSnapshotStorage, FrpBridge, FrpBridgeError, FrpProcessManager, FrpRuntime, GITHUB_OWNER, GITHUB_REPO, OS_MAP, commandExists, downloadFile, ensureDir, executeCommand, getDownloadUrl, getLatestVersion, getPlatform, parseToml, toToml };
-export type { Awaitable, CommandHandler, CommandHandlerContext, CommandMetadata, CommandResult, CommandStatus, ConfigSnapshot, FrpBridgeOptions, FrpProcessManagerOptions, NodeInfo, QueryHandler, QueryResult, RuntimeAdapters, RuntimeCommand, RuntimeContext, RuntimeError, RuntimeErrorCode, RuntimeEvent, RuntimeLogger, RuntimeMode, RuntimeQuery, RuntimeState, RuntimeStatus, SnapshotStorage };
+export { ARCH_MAP, BINARY_NAMES, BinaryNotFoundError, ClientNodeCollector, ConfigInvalidError, ConfigNotFoundError, DEFAULT_PRESET_CONFIG, DownloadFailedError, FrpBridgeErrorBase as Error, ExponentialBackoffStrategy, ExtractionFailedError, FileNodeStorage, FileSnapshotStorage, FixedIntervalStrategy, FrpBridge, FrpBridgeErrorBase, FrpProcessManager, FrpRuntime, GITHUB_OWNER, GITHUB_REPO, GenericError, InfiniteReconnectStrategy, LinearBackoffStrategy, MiddlewarePipeline, ModeError, NodeManager, NotFoundError, OS_MAP, PlatformError, ProcessAlreadyRunningError, ProcessNotRunningError, ProcessStartFailedError, RpcClient, RpcMessageType, RpcServer, ValidationError, VersionFetchError, authMiddleware, commandExists, configToToml, downloadFile, ensureDir, errorHandlerMiddleware, executeCommand, findExistingVersion, getDownloadUrl, getLatestVersion, getPlatform, isCommandMessage, isEventMessage, isEventRpcMessage, isNodeDeletePayload, isPingMessage, isPongMessage, isRegisterMessage, isRpcRequest, isRpcResponse, isTunnelAddPayload, isTunnelDeletePayload, isValidToml, loggingMiddleware, mergeConfigs, parse, parseToml, safeParse, saveFrpConfigFile, stringify, timeoutMiddleware, toToml, validatePresetConfig };
+export type { AllRpcMessage, Awaitable, ClientCollectorOptions, CommandHandler, CommandHandlerContext, CommandMetadata, CommandResult, CommandRpcMessage, CommandStatus, ConfigSnapshot, EventRpcMessage, EventRpcMessageEvent, FrpBridgeOptions, FrpProcessManagerOptions, FrpcPresetConfig, FrpsPresetConfig, MiddlewareContext, MiddlewareFn, MiddlewareOptions, NodeDeletePayload, NodeEvent, NodeInfo, NodeManagerOptions, NodeResponsePayload, NodeStorage, ParseOptions, PingMessage, PongMessage, PresetConfig, QueryHandler, QueryResult, ReconnectStrategy, RegisterMessage, RpcClientOptions, RpcCommandStatus, RpcMessage, RpcRequest, RpcResponse, RpcResponseStatus, RpcServerOptions, RuntimeAdapters, RuntimeCommand, RuntimeContext, RuntimeError, RuntimeErrorCode, RuntimeEvent, RuntimeLogger, RuntimeMode, RuntimeQuery, RuntimeState, RuntimeStatus, SnapshotStorage, StringifyOptions, TunnelAddPayload, TunnelDeletePayload, TunnelResponsePayload };