@push.rocks/smartipc/dist_ts/classes.transports.d.ts

A library for node inter process communication, providing an easy-to-use API for IPC.

import * as plugins from './smartipc.plugins.js';
/**
 * Message envelope structure for all IPC messages
 */
export interface IIpcMessageEnvelope<T = any> {
    id: string;
    type: string;
    correlationId?: string;
    timestamp: number;
    payload: T;
    headers?: Record<string, any>;
}
/**
 * Transport configuration options
 */
export interface IIpcTransportOptions {
    /** Unique identifier for this transport */
    id: string;
    /**
     * When true, a client transport will NOT auto-start a server when connect()
     * encounters ECONNREFUSED/ENOENT. Useful for strict client/daemon setups.
     * Default: false. Can also be overridden by env SMARTIPC_CLIENT_ONLY=1.
     */
    clientOnly?: boolean;
    /** Socket path for Unix domain sockets or pipe name for Windows */
    socketPath?: string;
    /** TCP host for network transport */
    host?: string;
    /** TCP port for network transport */
    port?: number;
    /** Enable message encryption */
    encryption?: boolean;
    /** Authentication token */
    authToken?: string;
    /** Socket timeout in ms */
    timeout?: number;
    /** Enable TCP no delay (Nagle's algorithm) */
    noDelay?: boolean;
    /** Maximum message size in bytes (default: 8MB) */
    maxMessageSize?: number;
    /** Automatically cleanup stale socket file on start (default: false) */
    autoCleanupSocketFile?: boolean;
    /** Socket file permissions mode (e.g. 0o600) */
    socketMode?: number;
}
/**
 * Connection state events
 */
export interface IIpcTransportEvents {
    connect: () => void;
    disconnect: (reason?: string) => void;
    error: (error: Error) => void;
    message: (message: IIpcMessageEnvelope) => void;
    drain: () => void;
}
/**
 * Abstract base class for IPC transports
 */
export declare abstract class IpcTransport extends plugins.EventEmitter {
    protected options: IIpcTransportOptions;
    protected connected: boolean;
    protected messageBuffer: Buffer;
    protected currentMessageLength: number | null;
    constructor(options: IIpcTransportOptions);
    /**
     * Connect the transport
     */
    abstract connect(): Promise<void>;
    /**
     * Disconnect the transport
     */
    abstract disconnect(): Promise<void>;
    /**
     * Send a message through the transport
     */
    abstract send(message: IIpcMessageEnvelope): Promise<boolean>;
    /**
     * Check if transport is connected
     */
    isConnected(): boolean;
    /**
     * Parse incoming data with length-prefixed framing
     */
    protected parseIncomingData(data: Buffer): void;
    /**
     * Frame a message with length prefix
     */
    protected frameMessage(message: IIpcMessageEnvelope): Buffer;
    /**
     * Handle socket errors
     */
    protected handleError(error: Error): void;
}
/**
 * Unix domain socket transport for Linux/Mac
 */
export declare class UnixSocketTransport extends IpcTransport {
    private socket;
    private server;
    private clients;
    private socketToClientId;
    private clientIdToSocket;
    /**
     * Connect as client or start as server
     */
    connect(): Promise<void>;
    /**
     * Start as server
     */
    private startServer;
    /**
     * Parse incoming data from a specific client socket
     */
    private parseIncomingDataFromClient;
    private clientBuffers?;
    private clientLengths?;
    /**
     * Setup socket event handlers
     */
    private setupSocketHandlers;
    /**
     * Disconnect the transport
     */
    disconnect(): Promise<void>;
    /**
     * Send a message
     */
    send(message: IIpcMessageEnvelope): Promise<boolean>;
    /**
     * Get the socket path
     */
    private getSocketPath;
}
/**
 * Named pipe transport for Windows
 */
export declare class NamedPipeTransport extends UnixSocketTransport {
}
/**
 * TCP transport for network IPC
 */
export declare class TcpTransport extends IpcTransport {
    private socket;
    private server;
    private clients;
    /**
     * Connect as client or start as server
     */
    connect(): Promise<void>;
    /**
     * Start as server
     */
    private startServer;
    /**
     * Setup socket event handlers
     */
    private setupSocketHandlers;
    /**
     * Disconnect the transport
     */
    disconnect(): Promise<void>;
    /**
     * Send a message
     */
    send(message: IIpcMessageEnvelope): Promise<boolean>;
}
/**
 * Factory function to create appropriate transport based on platform and options
 */
export declare function createTransport(options: IIpcTransportOptions): IpcTransport;