@iprokit/service/lib/scp/protocol.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" />
/// <reference types="node" />
/// <reference types="node" />
/// <reference types="node" />
import { Duplex, Readable, Writable } from 'stream';
import { Socket as TcpSocket } from 'net';
import { TLSSocket } from 'tls';
import Frame from './frame';
import RFI, { IRFI, Mode, Parameters } from './rfi';
import Signal from './signal';
declare const readingPaused: unique symbol;
declare const rifSent: unique symbol;
/**
 * `Protocol` provides a high-level abstraction for the Service Communication Protocol (SCP).
 * It manages the encoding and decoding of SCP frames over a duplex stream by encapsulating a user-provided socket.
 */
export default class Protocol extends Duplex {
    /**
     * Underlying socket.
     */
    readonly socket: TcpSocket | TLSSocket;
    /**
     * `true` when read buffer is full and calls to `push` return `false`.
     * Additionally new frames will not be read off the underlying socket until the consumer calls `read`.
     */
    private [readingPaused];
    /**
     * Creates an instance of `Protocol`.
     *
     * @param socket underlying socket.
     */
    constructor(socket: TcpSocket | TLSSocket);
    /**
     * Implements the readable stream method `_read`.
     *
     * WARNING: Should not be called by the consumer.
     */
    _read(): void;
    /**
     * Implements the writable stream method `_write`.
     *
     * WARNING: Should not be called by the consumer.
     */
    _write(frame: Frame, encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
    /**
     * Implements the writable stream method `_final`.
     * Used when `end()` is called to end the writable stream.
     *
     * WARNING: Should not be called by the consumer.
     */
    _final(callback: (error?: Error | null) => void): void;
    /**
     * Implements the readable/writable stream method `_destroy`.
     * Used when `destroy()` is called to destroy the stream.
     *
     * WARNING: Should not be called by the consumer.
     */
    _destroy(error: Error | null, callback: (error: Error | null) => void): void;
    /**
     * Fired when `readable` event is triggered on the underlying socket.
     * This is called every time there is a new frame to be read from the underlying socket.
     */
    private onReadable;
    /**
     * Fired when end is received on the underlying socket.
     * Ends the readable stream.
     */
    private onEnd;
    /**
     * Sends a heartbeat signal to keep the connection alive.
     *
     * @param callback callback called after the signal is sent.
     */
    heartbeat(callback: (error?: Error | null) => void): this;
}
/**
 * `Readable` stream that decodes SCP frames into data.
 *
 * @emits `rfi` when RFI is received.
 */
export declare class Incoming extends Readable implements IRFI {
    #private;
    /**
     * Underlying SCP stream.
     */
    readonly scp: Protocol;
    /**
     * `true` when read buffer is full and calls to `push` return `false`.
     * Additionally new frame will not be read off underlying SCP stream until the consumer calls `read`.
     */
    private [readingPaused];
    /**
     * Creates an instance of `Incoming`.
     *
     * @param scp underlying SCP stream.
     */
    constructor(scp: Protocol);
    /**
     * RFI received on the stream.
     */
    get rfi(): RFI;
    get mode(): Mode;
    get operation(): string;
    get parameters(): Parameters;
    /**
     * Gets a parameter value.
     *
     * @param key parameter key.
     */
    get<K extends keyof Parameters>(key: K): Parameters[K];
    /**
     * Returns `true` if the parameter exists, `false` otherwise.
     *
     * @param key parameter key.
     */
    has(key: keyof Parameters): boolean;
    /**
     * Returns an array of parameter keys.
     */
    keys(): string[];
    /**
     * Returns an array of parameter values.
     */
    values(): (string | undefined)[];
    /**
     * Returns an array of key-value pairs of parameters.
     */
    entries(): [string, string | undefined][];
    /**
     * Returns the number of parameters.
     */
    get size(): number;
    /**
     * Sets the string encoding to apply when decoding `DATA` frames.
     * If not set, raw Buffers will be returned.
     *
     * Note: This does not affect `SIGNAL` frames, which will continue to be emitted as `Signal` objects.
     *
     * @param encoding string encoding to apply.
     */
    setEncoding(encoding: BufferEncoding): this;
    /**
     * Implements the readable stream method `_read`.
     *
     * WARNING: Should not be called by the consumer.
     */
    _read(): void;
    /**
     * Implements the readable stream method `_destroy`.
     * Used when `destroy()` is called to destroy the stream.
     *
     * WARNING: Should not be called by the consumer.
     */
    _destroy(error: Error | null, callback: (error: Error | null) => void): void;
    /**
     * Fired when `readable` event is triggered on the underlying SCP stream.
     * This is called every time there is a new frame to be read from the underlying SCP stream.
     */
    private onReadable;
    /**
     * Fired when end is received on the underlying SCP stream.
     * Ends the readable stream.
     */
    private onEnd;
}
/**
 * `Writable` stream that encodes stream data into SCP frames.
 */
export declare class Outgoing extends Writable implements IRFI {
    #private;
    /**
     * Underlying SCP stream.
     */
    readonly scp: Protocol;
    /**
     * `true` if the RFI has been sent, `false` otherwise.
     */
    private [rifSent];
    /**
     * Creates an instance of `Outgoing`.
     *
     * @param scp underlying SCP stream.
     */
    constructor(scp: Protocol);
    /**
     * RFI to send on the stream.
     */
    get rfi(): RFI;
    get mode(): Mode;
    get operation(): string;
    get parameters(): Parameters;
    /**
     * Sets RFI to send on the stream.
     *
     * @param mode mode of the remote function.
     * @param operation operation of the remote function.
     * @param parameters optional parameters of the remote function.
     */
    setRFI(mode: Mode, operation: string, parameters?: Parameters): this;
    /**
     * Gets a parameter value.
     *
     * @param key parameter key.
     */
    get<K extends keyof Parameters>(key: K): Parameters[K];
    /**
     * Returns `true` if the parameter exists, `false` otherwise.
     *
     * @param key parameter key.
     */
    has(key: keyof Parameters): boolean;
    /**
     * Sets a parameter.
     *
     * @param key parameter key.
     * @param value parameter value.
     */
    set<K extends keyof Parameters>(key: K, value: Parameters[K]): this;
    /**
     * Removes a parameter.
     *
     * @param key parameter key.
     */
    delete(key: keyof Parameters): this;
    /**
     * Returns an array of parameter keys.
     */
    keys(): string[];
    /**
     * Returns an array of parameter values.
     */
    values(): (string | undefined)[];
    /**
     * Returns an array of key-value pairs of parameters.
     */
    entries(): [string, string | undefined][];
    /**
     * Returns the number of parameters.
     */
    get size(): number;
    /**
     * Implements the writable stream method `_write`.
     * Writes RFI frame on the first pass and payload frames subsequently.
     *
     * WARNING: Should not be called by the consumer.
     */
    _write(chunk: string | Buffer | Signal, encoding: BufferEncoding, callback: (error?: Error | null) => void): void;
    /**
     * Implements the writable stream method `_final`.
     * If RFI is sent, writes end frame then signal end.
     * Otherwise signal end directly.
     *
     * WARNING: Should not be called by the consumer.
     */
    _final(callback: (error?: Error | null) => void): void;
    /**
     * Writes RFI into the underlying SCP stream.
     *
     * @param rfi RFI to write.
     * @param callback callback called when the write operation is complete.
     */
    private writeRFI;
    /**
     * Writes payload(data/signal) into the underlying SCP stream.
     *
     * @param payload payload to write.
     * @param encoding string encoding to apply when encoding strings into Buffers. If not set, `utf8` will be used by default.
     * @param callback callback called when the write operation is complete.
     */
    private writePayload;
    /**
     * Writes data into the underlying SCP stream.
     *
     * @param data data to write.
     * @param startHead start head.
     * @param endHead end head.
     * @param callback callback called when the write operation is complete.
     */
    private writeData;
    /**
     * Writes signal into the underlying SCP stream.
     *
     * @param signal signal to write.
     * @param callback callback called when the write operation is complete.
     */
    private writeSignal;
    /**
     * Writes end into the underlying SCP stream.
     *
     * @param callback callback called when the write operation is complete.
     */
    private writeEnd;
    /**
     * Writes frame into the underlying SCP stream.
     *
     * @param frame frame to write.
     * @param callback callback called when the write operation is complete.
     */
    private writeFrame;
}
export {};