@frp-bridge/core 0.0.2 → 0.0.4

package/dist/index.d.mts

@@ -1,591 +0,0 @@
-import { NodeRegisterPayload, NodeHeartbeatPayload, NodeInfo as NodeInfo$1, NodeListQuery, NodeListResponse, NodeStatistics, TunnelSyncPayload, ProxyConfig, ClientConfig, ServerConfig, RpcRequest } from '@frp-bridge/types';
-import { EventEmitter } from 'node:events';
-
-type Awaitable<T> = T | Promise<T>;
-type RuntimeMode = 'client' | 'server';
-type RuntimeStatus = 'idle' | 'starting' | 'running' | 'stopping' | 'error';
-interface RuntimeContext {
-    id: string;
-    mode: RuntimeMode;
-    workDir: string;
-    platform: string;
-    clock?: () => number;
-    logger?: RuntimeLogger;
-}
-interface RuntimeLogger {
-    debug: (message: string, context?: Record<string, unknown>) => void;
-    info: (message: string, context?: Record<string, unknown>) => void;
-    warn: (message: string, context?: Record<string, unknown>) => void;
-    error: (message: string, context?: Record<string, unknown>) => void;
-}
-interface RuntimeState {
-    status: RuntimeStatus;
-    version: number;
-    lastAppliedAt?: number;
-    lastError?: RuntimeError;
-}
-interface CommandMetadata {
-    requestId?: string;
-    correlationId?: string;
-    author?: string;
-    issuedAt?: number;
-}
-interface RuntimeCommand<TPayload = unknown> {
-    name: string;
-    payload: TPayload;
-    metadata?: CommandMetadata;
-}
-interface CommandResult<TResult = unknown> {
-    status: CommandStatus;
-    version?: number;
-    events?: RuntimeEvent[];
-    result?: TResult;
-    error?: RuntimeError;
-    snapshot?: ConfigSnapshot;
-}
-type CommandStatus = 'success' | 'failed' | 'pending';
-interface RuntimeQuery<TPayload = unknown> {
-    name: string;
-    payload?: TPayload;
-}
-interface QueryResult<TResult = unknown> {
-    result: TResult;
-    version: number;
-}
-interface RuntimeEvent<TPayload = unknown> {
-    type: string;
-    timestamp: number;
-    version?: number;
-    payload?: TPayload;
-}
-interface RuntimeError {
-    code: RuntimeErrorCode;
-    message: string;
-    details?: Record<string, unknown>;
-}
-type RuntimeErrorCode = 'VALIDATION_ERROR' | 'RUNTIME_ERROR' | 'SYSTEM_ERROR' | 'PORT_CONFLICT' | 'RPC_NOT_AVAILABLE' | 'RPC_ERROR';
-interface ConfigSnapshot {
-    version: number;
-    checksum: string;
-    appliedAt: number;
-    author?: string;
-    summary?: string;
-}
-interface SnapshotStorage {
-    save: (snapshot: ConfigSnapshot) => Awaitable<void>;
-    load: (version: number) => Awaitable<ConfigSnapshot | undefined>;
-    list: () => Awaitable<ConfigSnapshot[]>;
-}
-interface CommandHandlerContext {
-    context: RuntimeContext;
-    state: RuntimeState;
-    emit: (events: RuntimeEvent[]) => void;
-    requestVersionBump: () => number;
-}
-type CommandHandler<TPayload = unknown, TResult = unknown> = (command: RuntimeCommand<TPayload>, ctx: CommandHandlerContext) => Awaitable<CommandResult<TResult>>;
-type QueryHandler<TPayload = unknown, TResult = unknown> = (query: RuntimeQuery<TPayload>, ctx: RuntimeContext) => Awaitable<QueryResult<TResult>>;
-interface RuntimeAdapters {
-    storage?: SnapshotStorage;
-    commands?: Record<string, CommandHandler>;
-    queries?: Record<string, QueryHandler>;
-}
-
-declare class FrpRuntime {
-    private readonly context;
-    private readonly storage?;
-    private readonly commandHandlers;
-    private readonly queryHandlers;
-    private eventBuffer;
-    private commandQueue;
-    private state;
-    constructor(context: RuntimeContext, adapters?: RuntimeAdapters);
-    registerCommand(name: string, handler: CommandHandler): void;
-    registerQuery(name: string, handler: QueryHandler): void;
-    execute<TPayload, TResult = unknown>(command: RuntimeCommand<TPayload>): Promise<CommandResult<TResult>>;
-    query<TPayload, TResult = unknown>(query: RuntimeQuery<TPayload>): Promise<QueryResult<TResult>>;
-    snapshot(): RuntimeState;
-    drainEvents(): RuntimeEvent[];
-    private runCommand;
-    private pushEvents;
-    private bumpVersion;
-    private persistSnapshot;
-    private normalizeError;
-    private buildError;
-    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?: any;
-}
-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 logger?;
-    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;
-}
-
-/**
- * FRP process management utilities
- */
-
-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 */
-    mode: 'client' | 'server';
-    /** Optional logger */
-    logger?: RuntimeLogger;
-}
-interface NodeInfo {
-    /** Node ID */
-    id: string;
-    /** Node name */
-    name: string;
-    /** Server address */
-    serverAddr: string;
-    /** Server port */
-    serverPort?: number;
-    /** Authentication token */
-    token?: string;
-    /** Additional config */
-    config?: Partial<ClientConfig | ServerConfig>;
-}
-/**
- * Manages FRP client/server lifecycle, config, and tunnels
- */
-declare class FrpProcessManager extends EventEmitter {
-    private readonly workDir;
-    private version;
-    private readonly mode;
-    private readonly specifiedVersion?;
-    private readonly logger;
-    private process;
-    private configPath;
-    private binaryPath;
-    private uptime;
-    private isManualStop;
-    constructor(options: FrpProcessManagerOptions);
-    /** Ensure version is fetched and binary path is set */
-    private ensureVersion;
-    /** Download FRP binary for current platform */
-    downloadFrpBinary(): Promise<void>;
-    /** Update FRP binary to latest version */
-    updateFrpBinary(newVersion?: string): Promise<void>;
-    /** Check if binary exists */
-    hasBinary(): boolean;
-    /** Get current configuration */
-    getConfig(): ClientConfig | ServerConfig | null;
-    /** Update configuration */
-    updateConfig(config: Partial<ClientConfig | ServerConfig>): void;
-    /** Backup configuration */
-    backupConfig(): Promise<string>;
-    /** Return the absolute config file path */
-    getConfigPath(): string;
-    /** Read raw config file contents */
-    getConfigRaw(): string | null;
-    /** Overwrite config file with provided content */
-    updateConfigRaw(content: string): void;
-    /** Start FRP process */
-    start(): Promise<void>;
-    /** Stop FRP process */
-    stop(): Promise<void>;
-    /** Check if process is running */
-    isRunning(): boolean;
-    /** Add node (for client mode) */
-    addNode(node: NodeInfo): void;
-    /** Get node info */
-    getNode(): NodeInfo | null;
-    /** Update node info */
-    updateNode(node: Partial<NodeInfo>): void;
-    /** Remove node */
-    removeNode(): void;
-    /** Add tunnel (proxy) */
-    addTunnel(proxy: ProxyConfig): void;
-    /** Check if proxy type uses remotePort */
-    private typeUsesRemotePort;
-    /** Get tunnel by name */
-    getTunnel(name: string): ProxyConfig | null;
-    /** Update tunnel */
-    updateTunnel(name: string, proxy: Partial<ProxyConfig>): void;
-    /** Remove tunnel */
-    removeTunnel(name: string): void;
-    /** List all tunnels */
-    listTunnels(): ProxyConfig[];
-    /**
-     * Query current process status
-     */
-    queryProcess(): {
-        pid: number | undefined;
-        uptime: number;
-    };
-    private setupProcessListeners;
-}
-
-interface RpcClientOptions {
-    url: string;
-    nodeId: string;
-    getRegisterPayload: () => Promise<NodeInfo$1> | NodeInfo$1;
-    handleRequest: (req: RpcRequest) => Promise<unknown>;
-    reconnectInterval?: number;
-    logger?: {
-        info?: (msg: string, data?: unknown) => void;
-        warn?: (msg: string, data?: unknown) => void;
-        error?: (msg: string, data?: unknown) => void;
-    };
-}
-declare class RpcClient {
-    private readonly options;
-    private ws;
-    private reconnectTimer?;
-    private readonly reconnectInterval;
-    constructor(options: RpcClientOptions);
-    connect(): Promise<void>;
-    disconnect(): void;
-    private createConnection;
-    private handleMessage;
-    private handleRpcRequest;
-    private send;
-    private scheduleReconnect;
-}
-
-interface RpcServerOptions {
-    port: number;
-    heartbeatInterval?: number;
-    logger?: {
-        info?: (msg: string, data?: unknown) => void;
-        warn?: (msg: string, data?: unknown) => void;
-        error?: (msg: string, data?: unknown) => void;
-    };
-    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>;
-}
-declare class RpcServer {
-    private readonly options;
-    private readonly clients;
-    private readonly pendingRequests;
-    private readonly wsToNode;
-    private heartbeatTimer?;
-    private server?;
-    constructor(options: RpcServerOptions);
-    start(): void;
-    stop(): void;
-    rpcCall(nodeId: string, method: string, params: Record<string, unknown>, timeout?: number): Promise<unknown>;
-    private handleMessage;
-    private handleRpcResponse;
-    private handleClose;
-    private startHeartbeat;
-}
-
-interface FrpBridgeRuntimeOptions {
-    id?: string;
-    mode?: RuntimeMode;
-    logger?: RuntimeLogger;
-    clock?: () => number;
-    platform?: string;
-    workDir?: string;
-}
-interface FrpBridgeProcessOptions extends Partial<Omit<FrpProcessManagerOptions, 'mode'>> {
-    mode?: 'client' | 'server';
-}
-interface FrpBridgeRpcOptions {
-    serverPort?: number;
-    serverHeartbeatInterval?: number;
-    serverValidateToken?: (token: string | undefined, nodeId: string | undefined) => boolean | Promise<boolean>;
-    serverAuthorize?: (nodeId: string, method: string) => boolean | Promise<boolean>;
-    clientUrl?: string;
-    clientNodeId?: string;
-    clientToken?: string;
-    clientReconnectInterval?: number;
-    getRegisterPayload?: () => Promise<NodeInfo$1> | NodeInfo$1;
-    handleRequest?: (req: RpcRequest) => 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 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;
-    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;
-}
-
-/**
- * Core constants
- */
-/** GitHub repository owner */
-declare const GITHUB_OWNER = "fatedier";
-/** GitHub repository name */
-declare const GITHUB_REPO = "frp";
-/** Platform-specific binary names */
-declare const BINARY_NAMES: {
-    readonly client: "frpc.exe" | "frpc";
-    readonly server: "frps.exe" | "frps";
-};
-/** Platform architecture mapping */
-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 {
-    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"
-}
-
-declare class FileSnapshotStorage implements SnapshotStorage {
-    private readonly directory;
-    constructor(directory: string);
-    save(snapshot: ConfigSnapshot): Promise<void>;
-    load(version: number): Promise<ConfigSnapshot | undefined>;
-    list(): Promise<ConfigSnapshot[]>;
-    private buildPath;
-}
-
-/**
- * Utility functions
- */
-/** Get latest FRP version from GitHub releases */
-declare function getLatestVersion(): Promise<string>;
-/** Get platform identifier for FRP release */
-declare function getPlatform(): string;
-/** Get GitHub release download URL */
-declare function getDownloadUrl(version: string, platform: string): string;
-/** Download file from URL */
-declare function downloadFile(url: string, dest: string): Promise<void>;
-/** Execute command */
-declare function executeCommand(command: string): Promise<{
-    stdout: string;
-    stderr: string;
-}>;
-/** Check if command exists */
-declare function commandExists(command: string): Promise<boolean>;
-/** Ensure directory exists */
-declare function ensureDir(dirPath: string): void;
-/** Parse TOML-like config to JSON */
-declare function parseToml(content: string): Record<string, any>;
-/** Convert JSON to TOML-like config */
-declare function toToml(obj: Record<string, any>): string;
-
-export { ARCH_MAP, BINARY_NAMES, ClientNodeCollector, ErrorCode, FileNodeStorage, FileSnapshotStorage, FrpBridge, FrpBridgeError, FrpProcessManager, FrpRuntime, GITHUB_OWNER, GITHUB_REPO, NodeManager, OS_MAP, RpcClient, RpcServer, commandExists, downloadFile, ensureDir, executeCommand, getDownloadUrl, getLatestVersion, getPlatform, parseToml, toToml };
-export type { Awaitable, ClientCollectorOptions, CommandHandler, CommandHandlerContext, CommandMetadata, CommandResult, CommandStatus, ConfigSnapshot, FrpBridgeOptions, FrpProcessManagerOptions, NodeEvent, NodeInfo, NodeManagerOptions, NodeStorage, QueryHandler, QueryResult, RpcClientOptions, RpcServerOptions, RuntimeAdapters, RuntimeCommand, RuntimeContext, RuntimeError, RuntimeErrorCode, RuntimeEvent, RuntimeLogger, RuntimeMode, RuntimeQuery, RuntimeState, RuntimeStatus, SnapshotStorage };