@bakit/service 3.2.0 → 4.0.0

package/dist/index.d.ts

@@ -1,256 +1,323 @@
+import EventEmitter from 'node:events';
+import * as _bakit_utils from '@bakit/utils';
+import { Awaitable, Collection, FunctionLike, Promisify } from '@bakit/utils';
 import { Socket } from 'node:net';
-import { EventBus, Awaitable, FunctionLike, Promisify } from '@bakit/utils';
-import { ValueOf, MergeExclusive } from 'type-fest';
 
 type Serializable =
-	| null
-	| undefined
 	| string
 	| number
 	| boolean
-	| bigint
-	| Date
-	| Buffer
-	| Uint8Array
+	| null
+	| undefined
 	| Serializable[]
-	| { [key: string | number]: Serializable }
-	| Map<string | number, Serializable>
-	| Set<Serializable>
-	| void;
+	| { [key: string]: Serializable };
 
-interface BaseClientDriver extends EventBus<BaseClientDriverEvents> {
-	send(message: Serializable): void;
-	connect(): void;
-	disconnect(): void;
-	readonly ready: boolean;
+interface RPCResponseError {
+	message: string;
+	name: string;
+	constructorName: string;
+	stack?: string;
+	cause?: RPCResponseError;
+	errors?: RPCResponseError[]; // For AggregateError
+	[key: string]: unknown;
 }
 
-interface BaseServerDriver extends EventBus<BaseServerDriverEvents> {
-	broadcast(message: Serializable): void;
-	send(connection: unknown, message: Serializable): void;
-	listen(): void;
-	close(): void;
+declare const SUPPORTED_LENGTH_BYTES: readonly [1, 2, 4, 8];
+interface FrameCodecOptions {
+    maxBufferSize?: number;
+    maxFrameSize?: number;
+    lengthBytes?: (typeof SUPPORTED_LENGTH_BYTES)[number];
+    endian?: "big" | "little";
+    lengthIncludesHeader?: boolean;
 }
-
-interface BaseClientDriverEvents {
-	message: [message: Serializable];
-	connect: [];
-	disconnect: [];
-	error: [error: Error];
-}
-
-interface BaseServerDriverEvents {
-	listen: [];
-	close: [];
-	message: [connection: unknown, message: Serializable];
-	clientConnect: [connection: unknown];
-	clientDisconnect: [connection: unknown];
-	clientError: [connection: unknown, error: Error];
+declare class FrameCodec {
+    private buffer;
+    readonly options: Required<FrameCodecOptions>;
+    stats: {
+        bytesReceived: number;
+        bytesDecoded: number;
+        framesDecoded: number;
+        bufferCopies: number;
+    };
+    constructor(options?: FrameCodecOptions);
+    push(chunk: Buffer): Buffer[];
+    get bufferedBytes(): number;
+    reset(): void;
+    private readLength;
+    encode(payload: Buffer): Buffer<ArrayBufferLike>;
+    static encode(payload: Buffer, options?: FrameCodecOptions): Buffer;
+    static serialize(obj: Serializable): Buffer;
+    static deserialize(buf: Buffer): Serializable;
 }
 
-declare const SocketState: {
-    readonly Idle: 0;
-    readonly Connecting: 1;
-    readonly Connected: 2;
-    readonly Disconnected: 3;
-    readonly Reconnecting: 4;
-    readonly Destroyed: 5;
-};
-type SocketState = ValueOf<typeof SocketState>;
-declare const IPCServerState: {
-    readonly Idle: 0;
-    readonly Listening: 1;
-    readonly Closed: 2;
-};
-type IPCServerState = ValueOf<typeof IPCServerState>;
-interface IPCServerEvents extends BaseServerDriverEvents {
-    message: [socket: Socket, message: Serializable];
-    clientConnect: [socket: Socket];
-    clientDisconnect: [socket: Socket];
-    clientError: [socket: Socket, error: Error];
-    drain: [socket: Socket];
-}
-interface IPCClientEvents extends BaseClientDriverEvents {
+type EventMap<T> = Record<keyof T, any[]> | DefaultEventMap;
+type DefaultEventMap = [never];
+interface BaseClientDriverEvents {
+    message: [message: Serializable];
+    connect: [];
+    disconnect: [];
+    error: [error: Error];
 }
-interface IPCServer extends EventBus<IPCServerEvents> {
-    listen(): void;
-    close(): void;
-    broadcast(message: Serializable): void;
-    send(socket: Socket, message: Serializable): void;
-    readonly state: IPCServerState;
+interface BaseServerDriverEvents<Connection = unknown> {
+    listen: [];
+    close: [];
+    error: [error: Error];
+    message: [connection: Connection, message: Serializable];
+    connectionAdd: [connection: Connection];
+    connectionRemove: [connection: Connection];
+    connectionError: [connection: Connection, error: Error];
 }
-interface IPCSocketConnection extends EventBus<IPCClientEvents>, IPCSocketMessageHandler {
-    connect: () => void;
-    disconnect: () => void;
-    destroy: () => void;
-    reconnect: () => void;
-    write: (chunk: Buffer) => void;
-    readonly state: SocketState;
-    readonly ready: boolean;
+declare abstract class BaseDriver<Options extends object, Events extends EventMap<Events>> extends EventEmitter<Events> {
+    options: Options;
+    constructor(options: Options);
 }
-interface IPCSocketMessageHandler extends BaseClientDriver {
-    handleData: (chunk: Buffer) => void;
+declare abstract class BaseClientDriver<Options extends object = object, Events extends EventMap<Events> & BaseClientDriverEvents = BaseClientDriverEvents> extends BaseDriver<Options, Events> {
+    constructor(options: Options);
+    abstract readonly ready: boolean;
+    abstract send(message: Serializable): Awaitable<void>;
+    abstract connect(): Awaitable<void>;
+    abstract disconnect(): Awaitable<void>;
 }
-interface IPCServerOptions {
-    id: string;
-    platform?: NodeJS.Platform;
+declare abstract class BaseServerDriver<Options extends object = object, Connection = unknown, Events extends EventMap<Events> & BaseServerDriverEvents<Connection> = BaseServerDriverEvents<Connection>> extends BaseDriver<Options, Events> {
+    constructor(options: Options);
+    readonly _connectionType: Connection;
+    abstract readonly connections: Set<Connection> | Map<unknown, Connection> | Connection[];
+    abstract listen(): Awaitable<void>;
+    abstract close(): Awaitable<void>;
+    abstract send(connection: Connection, message: Serializable): Awaitable<void>;
+    abstract broadcast(message: Serializable): Awaitable<unknown>;
 }
+
 interface IPCClientOptions {
     id: string;
-    platform?: NodeJS.Platform;
-    connection?: IPCSocketConnectionOptions;
+    codec?: FrameCodecOptions;
+    reconnect?: IPCClientReconnectOptions;
 }
-interface IPCSocketConnectionOptions {
-    autoReconnect?: boolean;
-    maxReconnectAttempts?: number;
-    reconnectDelay?: number;
-    requestConcurrency?: number;
+interface IPCClientReconnectOptions {
+    /** Enable auto-reconnect (default: true) */
+    enabled?: boolean;
+    /** Max retry attempts (default: 5) */
+    maxRetries?: number;
+    /** Initial delay in ms (default: 1000) */
+    initialDelay?: number;
+    /** Backoff multiplier (default: 1.5) */
+    backoff?: number;
+    /** Max delay in ms (default: 30000) */
+    maxDelay?: number;
 }
-interface IPCSocketMessageHandlerOptions {
-    onWrite(chunk: Buffer): void;
-    onMessage(message: Serializable): void;
+interface IPCClientEvents extends BaseClientDriverEvents {
+    reconnect: [];
+    reconnecting: [attempt: number, delay: number];
 }
-declare const DEFAULT_IPC_SOCKET_CONNECTION_OPTIONS: {
-    readonly autoReconnect: true;
-    readonly maxReconnectAttempts: 10;
-    readonly reconnectDelay: 5000;
-    readonly requestConcurrency: 10;
-};
-declare function getIPCPath(id: string, platform?: NodeJS.Platform): string;
-declare function createIPCClient(options: IPCClientOptions): IPCSocketConnection;
-declare function createIPCServer(options: IPCServerOptions): IPCServer;
-declare function createIPCSocketConnection(socketPath: string, options?: IPCSocketConnectionOptions): IPCSocketConnection;
-declare function createIPCSocketMessageHandler(options: IPCSocketMessageHandlerOptions): {
-    handleData: (chunk: Buffer) => void;
-    send: (message: Serializable) => void;
-};
-
-interface RPCErrorPayload {
-    message: string;
-    code?: number | string;
-    data?: Serializable;
+declare enum IPCClientState {
+    Idle = 0,
+    Connecting = 1,
+    Connected = 2,
+    Disconnected = 3
 }
-declare class RPCError extends Error implements RPCErrorPayload {
-    readonly code?: number | string;
-    readonly data?: Serializable;
-    constructor(message: string, options?: Omit<RPCErrorPayload, "message">);
+declare const DEFAULT_IPC_CLIENT_RECONNECT_OPTIONS: Required<IPCClientReconnectOptions>;
+declare class IPCClient extends BaseClientDriver<IPCClientOptions, IPCClientEvents> {
+    private socket?;
+    private codec;
+    state: IPCClientState;
+    private _ready;
+    private reconnectTimer?;
+    private reconnectOptions;
+    private reconnectAttempt;
+    private isIntentionalClose;
+    private queue;
+    constructor(options: IPCClientOptions);
+    get path(): string;
+    get ready(): boolean;
+    connect(): Promise<void>;
+    send(message: Serializable): Promise<void>;
+    disconnect(): Promise<void>;
+    private init;
+    private cleanup;
+    private onSocketConnect;
+    private onSocketClose;
+    private onSocketError;
+    private onSocketData;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+    private makeMessage;
+    private serialize;
+    private deserialize;
 }
-declare function serializeRPCError(error: unknown): RPCErrorPayload;
-declare function deserializeRPCError(payload: RPCErrorPayload): RPCError;
+declare function createIPCClient(options: IPCClientOptions): IPCClient;
 
-/**
- * Transport driver type identifiers.
- */
-declare const TransportDriver: {
-    /**
-     * Uses Unix Domain Sockets / Named Pipes for communications between processes.
-     */
-    readonly IPC: "ipc";
-};
-type TransportDriver = ValueOf<typeof TransportDriver>;
-interface TransportClientDriverSpecificOptions {
-    [TransportDriver.IPC]: IPCClientOptions;
-}
-interface TransportServerDriverSpecificOptions {
-    [TransportDriver.IPC]: IPCServerOptions;
-}
-type TransportClientOptions = {
-    [D in TransportDriver]: {
-        driver: D;
-    } & TransportClientDriverSpecificOptions[D];
-}[TransportDriver];
-type TransportServerOptions = {
-    [D in TransportDriver]: {
-        driver: D;
-    } & TransportServerDriverSpecificOptions[D];
-}[TransportDriver];
-interface TransportClient extends TransportClientProtocol, EventBus<TransportClientEvents> {
-    send: BaseServerDriver["send"];
-    connect: BaseClientDriver["connect"];
-    disconnect: BaseClientDriver["disconnect"];
-    readonly ready: boolean;
-}
-interface TransportServer extends TransportServerProtocol, EventBus<TransportServerEvents> {
-    broadcast: BaseServerDriver["broadcast"];
-    listen: BaseServerDriver["listen"];
-    close: BaseServerDriver["close"];
-}
-interface TransportClientProtocol {
-    request<T>(method: string, ...args: Serializable[]): Promise<T>;
+interface IPCConnectionEvents {
+    message: [message: Serializable];
+    close: [];
+    error: [error: Error];
 }
-type RPCHandler<Args extends Serializable[], Result extends Serializable> = (...args: Args) => Awaitable<Result>;
-interface TransportServerProtocol {
-    handle<Args extends Serializable[], Result extends Serializable>(method: string, handler: RPCHandler<Args, Result>): void;
+declare class IPCConnection extends EventEmitter<IPCConnectionEvents> {
+    server: IPCServer;
+    socket: Socket;
+    private codec;
+    constructor(server: IPCServer, socket: Socket);
+    send(message: Serializable): Promise<void>;
+    destroy(): void;
+    private setupListeners;
+    private handleData;
 }
-interface RPCRequestMessage {
-    type: "request";
+
+interface IPCServerOptions {
     id: string;
-    method: string;
-    args: Serializable[];
+    codec?: FrameCodecOptions;
 }
-type RPCResponseMessage = {
-    type: "response";
-    id: string;
-} & MergeExclusive<{
-    result: Serializable;
-}, {
-    error: RPCErrorPayload;
-}>;
+type IPCServerEvents = BaseServerDriverEvents<IPCConnection>;
+declare class IPCServer extends BaseServerDriver<IPCServerOptions, IPCConnection, IPCServerEvents> {
+    private server?;
+    private codecOptions;
+    connections: Collection<Socket, IPCConnection>;
+    codec: FrameCodec;
+    constructor(options: IPCServerOptions);
+    get path(): string;
+    listen(): Promise<void>;
+    private handleConnection;
+    send(connection: IPCConnection, message: Serializable): Awaitable<void>;
+    /**
+     * Send message to a specific client
+     */
+    sendSocket(socket: Socket, message: Serializable): Promise<void>;
+    /**
+     * Broadcast to all connected clients
+     * Returns count of successful sends (fire-and-forget, errors emitted via 'clientError')
+     */
+    broadcast(message: Serializable): Promise<void>;
+    /**
+     * Close server and disconnect all clients
+     */
+    close(): Promise<void>;
+    private sendSocketFrame;
+}
+declare function createIPCServer(options: IPCServerOptions): IPCServer;
+
 interface TransportClientEvents {
     connect: [];
     disconnect: [];
     error: [error: Error];
+    message: [message: Serializable];
 }
-interface TransportServerEvents {
+declare class TransportClient<D extends BaseClientDriver> extends EventEmitter<TransportClientEvents> {
+    readonly driver: D;
+    private pending;
+    constructor(driver: D);
+    connect(): _bakit_utils.Awaitable<void>;
+    disconnect(): _bakit_utils.Awaitable<void>;
+    request<Result extends Serializable>(method: string, ...args: Serializable[]): Promise<Result>;
+    send(message: Serializable): _bakit_utils.Awaitable<void>;
+    private setupDriverListeners;
+    private handleMessage;
+    private hydrateError;
+    private captureCallStack;
+    private isResponseMessage;
+}
+declare function createTransportClient<D extends BaseClientDriver<object, any>>(driver: D): TransportClient<D>;
+
+type RPCHandler = (...args: Serializable[]) => Promise<Serializable | Error>;
+interface TransportServerEvents<D extends BaseServerDriver> {
     listen: [];
     close: [];
     error: [error: Error];
-    clientConnect: [connection: unknown];
-    clientDisconnect: [connection: unknown];
+    connectionAdd: [connection: D["_connectionType"]];
+    connectionRemove: [connection: D["_connectionType"]];
+    connectionError: [connection: D["_connectionType"], error: Error];
+    message: [connection: D["_connectionType"], message: Serializable];
 }
-declare function createTransportClient(options: TransportClientOptions): TransportClient;
-declare function createTransportServer(options: TransportServerOptions): TransportServer;
-declare function createTransportClientProtocol(driver: BaseClientDriver): TransportClientProtocol;
-declare function createTransportServerProtocol(driver: BaseServerDriver): TransportServerProtocol;
+declare class TransportServer<D extends BaseServerDriver> extends EventEmitter<TransportServerEvents<D>> {
+    readonly driver: D;
+    private handlers;
+    constructor(driver: D);
+    get connections(): D["connections"];
+    handle(method: string, handler: RPCHandler): void;
+    listen(): ReturnType<D["listen"]>;
+    close(): ReturnType<D["close"]>;
+    broadcast(message: Serializable): ReturnType<D["broadcast"]>;
+    private setupDriverListeners;
+    private handleMessage;
+    private isRequestMessage;
+}
+declare function createTransportServer<D extends BaseServerDriver<object, any>>(driver: D): TransportServer<D>;
 
-interface ServiceOptions {
-    name: string;
-    transport: TransportClientOptions & TransportServerOptions;
+declare enum ServiceDriver {
+    IPC = "ipc"
 }
-interface Service {
-    readonly name: string;
-    readonly role: ServiceRole;
-    initialize?: FunctionLike<[], Awaitable<void>>;
-    onReady?: FunctionLike<[], Awaitable<void>>;
-    define<F extends ServiceFunction>(method: string, handler: F): Promisify<F>;
+interface DriverOptionsMap {
+    [ServiceDriver.IPC]: {
+        id: string;
+        server?: Omit<IPCServerOptions, "id">;
+        client?: Omit<IPCClientOptions, "id">;
+    };
 }
-type ServiceFunction = FunctionLike<any[], Awaitable<any>>;
-declare const ServiceRole: {
-    readonly Client: "client";
-    readonly Server: "server";
-};
-type ServiceRole = ValueOf<typeof ServiceRole>;
+type ServiceOptions = {
+    [D in keyof DriverOptionsMap]: {
+        driver: D;
+    } & DriverOptionsMap[D];
+}[keyof DriverOptionsMap];
 interface ServiceClientRuntime {
-    role: typeof ServiceRole.Client;
-    transport: TransportClient;
+    role: "client";
+    transport: TransportClient<BaseClientDriver>;
 }
 interface ServiceServerRuntime {
-    role: typeof ServiceRole.Server;
-    transport: TransportServer;
-}
-type ServiceRuntime = ServiceClientRuntime | ServiceServerRuntime;
-interface MutableRuntime {
-    role: ServiceRole | "unknown";
-    transport?: TransportClient | TransportServer;
+    role: "server";
+    transport: TransportServer<BaseServerDriver>;
 }
-interface ServiceInteral {
-    runtime: ServiceRuntime;
-    bind(role: "client" | "server"): void;
+declare class Service {
+    readonly options: ServiceOptions;
+    private runtime?;
+    private handlers;
+    private binding?;
+    constructor(options: ServiceOptions);
+    get role(): "client" | "server";
+    define<F extends FunctionLike>(method: string, handler: F): Promisify<F>;
+    protected ensureServerBound(): Promise<void> | undefined;
+    protected ensureClientBound(): Promise<void> | undefined;
 }
 declare function createService(options: ServiceOptions): Service;
-declare function startServiceServer(service: Service): Promise<void>;
-declare function assertRuntimeClient(service: Service, runtime: MutableRuntime): asserts runtime is ServiceClientRuntime;
-declare function assertRuntimeServer(service: Service, runtime: MutableRuntime): asserts runtime is ServiceServerRuntime;
-declare function getInternalService(service: Service): ServiceInteral;
+declare function getServices(entryDir?: string, cwd?: string): Promise<string[]>;
+declare function getServiceName(servicePath: string, cwd?: string): string;
+
+interface ServiceProcessEvents {
+    stdout: [chunk: Buffer];
+    stderr: [chunk: Buffer];
+    spawn: [];
+    error: [err: Error];
+    exit: [code: number | null, signal: NodeJS.Signals | null];
+}
+declare enum ServiceState {
+    Idle = 0,
+    Starting = 1,
+    Running = 2,
+    Restarting = 3,
+    Stopping = 4,
+    Stopped = 5
+}
+declare class ServiceProcess extends EventEmitter<ServiceProcessEvents> {
+    readonly path: string;
+    private child?;
+    private spawnTimestamp;
+    private _state;
+    constructor(path: string);
+    get name(): string;
+    get state(): ServiceState;
+    get ready(): boolean;
+    get uptime(): number;
+    start(): void;
+    stop(): Promise<void>;
+    restart(): Promise<void>;
+    private init;
+    private cleanup;
+    private onChildSpawn;
+    private onChildExit;
+}
+
+declare function getIPCPath(id: string, platform?: NodeJS.Platform): string;
+declare function isServerRunning(path: string): Promise<boolean>;
+
+declare function serializeRPCError(err: Error): RPCResponseError;
+declare function createDynamicRPCError(data: RPCResponseError): Error;
+declare function isSerializedError(value: unknown): value is RPCResponseError;
 
-export { type BaseClientDriver, type BaseClientDriverEvents, type BaseServerDriver, type BaseServerDriverEvents, DEFAULT_IPC_SOCKET_CONNECTION_OPTIONS, type IPCClientEvents, type IPCClientOptions, type IPCServer, type IPCServerEvents, type IPCServerOptions, IPCServerState, type IPCSocketConnection, type IPCSocketConnectionOptions, type IPCSocketMessageHandler, type IPCSocketMessageHandlerOptions, type MutableRuntime, RPCError, type RPCErrorPayload, type RPCHandler, type RPCRequestMessage, type RPCResponseMessage, type Serializable, type Service, type ServiceClientRuntime, type ServiceFunction, type ServiceInteral, type ServiceOptions, ServiceRole, type ServiceRuntime, type ServiceServerRuntime, SocketState, type TransportClient, type TransportClientDriverSpecificOptions, type TransportClientEvents, type TransportClientOptions, type TransportClientProtocol, TransportDriver, type TransportServer, type TransportServerDriverSpecificOptions, type TransportServerEvents, type TransportServerOptions, type TransportServerProtocol, assertRuntimeClient, assertRuntimeServer, createIPCClient, createIPCServer, createIPCSocketConnection, createIPCSocketMessageHandler, createService, createTransportClient, createTransportClientProtocol, createTransportServer, createTransportServerProtocol, deserializeRPCError, getIPCPath, getInternalService, serializeRPCError, startServiceServer };
+export { BaseClientDriver, type BaseClientDriverEvents, BaseServerDriver, type BaseServerDriverEvents, DEFAULT_IPC_CLIENT_RECONNECT_OPTIONS, FrameCodec, type FrameCodecOptions, IPCClient, type IPCClientEvents, type IPCClientOptions, type IPCClientReconnectOptions, IPCClientState, IPCServer, type IPCServerEvents, type IPCServerOptions, type RPCHandler, Service, type ServiceClientRuntime, ServiceDriver, type ServiceOptions, ServiceProcess, type ServiceProcessEvents, type ServiceServerRuntime, ServiceState, TransportClient, type TransportClientEvents, TransportServer, type TransportServerEvents, createDynamicRPCError, createIPCClient, createIPCServer, createService, createTransportClient, createTransportServer, getIPCPath, getServiceName, getServices, isSerializedError, isServerRunning, serializeRPCError };