@iprokit/service/lib/service.d.ts

Powering distributed systems with simplicity and speed.

/**
 * @iProKit/Service
 * Copyright (c) 2019-2025 Rutvik Katuri / iProTechs
 * SPDX-License-Identifier: Apache-2.0
 */
/// <reference types="node" />
/// <reference types="node" />
import { EventEmitter } from 'events';
import { AddressInfo } from 'net';
import { Server as HttpServer, IServer as IHttpServer, IRouter, RequestHandler } from './http';
import { Server as ScpServer, IServer as IScpServer, IExecutor, IncomingHandler, ReplyFunction, ConductorFunction, Client as RemoteService, ClientOptions as RemoteServiceOptions } from './scp';
import { Server as SdpServer, Attributes as SdpAttributes } from './sdp';
/**
 * A lightweight `Service` for managing HTTP routes and SCP executions.
 * Ensures smooth communication and coordination by bridging protocols and managing remote service interactions.
 *
 * @emits `start` when the service starts.
 * @emits `stop` when the service stops.
 */
export default class Service extends EventEmitter implements IHttpServer, IScpServer {
    #private;
    /**
     * Unique identifier of the service.
     */
    readonly identifier: string;
    /**
     * HTTP server instance.
     */
    readonly httpServer: HttpServer;
    /**
     * SCP server instance.
     */
    readonly scpServer: ScpServer;
    /**
     * SDP server instance.
     */
    readonly sdpServer: SdpServer;
    /**
     * Remote service instances.
     */
    readonly remoteServices: Map<string, RemoteService>;
    /**
     * Creates an instance of `Service`.
     *
     * @param identifier unique identifier of the service.
     */
    constructor(identifier: string);
    /**
     * HTTP routes registered.
     */
    get routes(): import("./http").Route[];
    /**
     * SCP executions registered.
     */
    get executions(): import("./scp").Execution[];
    /**
     * SDP pods discovered.
     */
    get pods(): Map<string, import("./sdp").IPod>;
    /**
     * `true` if the servers are listening for connections, `false` otherwise.
     */
    get listening(): {
        http: boolean;
        scp: boolean;
        sdp: boolean;
    };
    /**
     * Retrieves the bound address, family, and port of the servers as reported by the operating system.
     */
    address(): {
        http: AddressInfo | null;
        scp: AddressInfo | null;
        sdp: AddressInfo | null;
    };
    /**
     * Multicast group that have been joined.
     */
    get membership(): string | null;
    /**
     * Local address of the service.
     */
    get localAddress(): string | null;
    /**
     * State of the service.
     */
    get state(): "stopped" | "created" | "starting" | "started" | "stopping";
    /**
     * Establishes the connection to a remote service.
     */
    private onAvailable;
    /**
     * Terminates the connection to a remote service.
     */
    private onUnavailable;
    /**
     * Links this service to a remote service.
     *
     * No-op if the remote service is already linked.
     *
     * @param identifier unique identifier of the remote service.
     * @param remoteService remote service instance.
     */
    link(identifier: string, remoteService: RemoteService): this;
    /**
     * Registers a HTTP route for handling GET requests.
     *
     * @param path path pattern.
     * @param handlers request handler functions.
     */
    get(path: string, ...handlers: Array<RequestHandler>): this;
    /**
     * Registers a HTTP route for handling POST requests.
     *
     * @param path path pattern.
     * @param handlers request handler functions.
     */
    post(path: string, ...handlers: Array<RequestHandler>): this;
    /**
     * Registers a HTTP route for handling PUT requests.
     *
     * @param path path pattern.
     * @param handlers request handler functions.
     */
    put(path: string, ...handlers: Array<RequestHandler>): this;
    /**
     * Registers a HTTP route for handling PATCH requests.
     *
     * @param path path pattern.
     * @param handlers request handler functions.
     */
    patch(path: string, ...handlers: Array<RequestHandler>): this;
    /**
     * Registers a HTTP route for handling DELETE requests.
     *
     * @param path path pattern.
     * @param handlers request handler functions.
     */
    delete(path: string, ...handlers: Array<RequestHandler>): this;
    /**
     * Registers a HTTP route for handling ALL requests.
     *
     * @param path path pattern.
     * @param handlers request handler functions.
     */
    all(path: string, ...handlers: Array<RequestHandler>): this;
    /**
     * Mounts multiple HTTP routers.
     *
     * @param path path pattern.
     * @param routers routers to mount.
     */
    mount(path: string, ...routers: Array<IRouter>): this;
    /**
     * Broadcasts the supplied to all remote services.
     * Returns identifiers of remote services that successfully received broadcast.
     *
     * @param operation operation pattern.
     * @param args arguments to broadcast.
     */
    broadcast(operation: string, ...args: Array<any>): Promise<string[]>;
    /**
     * Registers a SCP execution for handling REPLY I/O.
     *
     * Remote handler function receives a message from a remote service and returns a reply.
     *
     * @param operation operation pattern.
     * @param func function to be executed.
     */
    reply<Returned>(operation: string, func: ReplyFunction<Returned>): this;
    /**
     * Registers a SCP execution for handling CONDUCTOR I/O.
     *
     * Remote handler function receives a message from a remote service and coordinates signals.
     *
     * @param operation operation pattern.
     * @param func function to be executed.
     */
    conductor(operation: string, func: ConductorFunction): this;
    /**
     * Registers a SCP execution for handling OMNI I/O.
     *
     * @param operation operation pattern.
     * @param handler incoming handler function.
     */
    omni(operation: string, handler: IncomingHandler): this;
    /**
     * Attaches a SCP executor.
     *
     * @param operation operation pattern.
     * @param executor executor to attach.
     */
    attach(operation: string, executor: IExecutor): this;
    /**
     * Starts the service by listening on HTTP, SCP, and SDP servers, connecting to remote services registered.
     *
     * @param httpPort local HTTP port.
     * @param scpPort local SCP port.
     * @param sdpPort local SDP port.
     * @param sdpAddress address of the SDP multicast group.
     * @emits `start` when the service starts.
     */
    start(httpPort: number, scpPort: number, sdpPort: number, sdpAddress: string): Promise<this>;
    /**
     * Stops the service by closing all servers and disconnecting from remote services registered.
     *
     * @emits `stop` when the service stops.
     */
    stop(): Promise<this>;
}
export { RemoteService, RemoteServiceOptions };
export interface Attributes extends SdpAttributes {
    http: string;
    scp: string;
}