pinggy 0.3.3 → 0.3.5

package/dist/index.d.ts

@@ -1,552 +1 @@
 #!/usr/bin/env node
-import { PinggyOptions, TunnelInstance, TunnelUsageType, TunnelType } from '@pinggy/pinggy';
-import { Worker } from 'node:worker_threads';
-import { z } from 'zod';
-import winston from 'winston';
-
-interface AdditionalForwarding {
-    localDomain: string;
-    localPort: number;
-    remoteDomain?: string;
-    remotePort?: number;
-    protocol?: 'http' | 'tcp' | 'udp' | 'tls';
-}
-declare enum TunnelStateType {
-    New = "idle",
-    Starting = "starting",
-    Running = "running",
-    Live = "live",
-    Closed = "closed",
-    Exited = "exited"
-}
-declare enum TunnelErrorCodeType {
-    NonResponsive = "non_responsive",
-    FailedToConnect = "failed_to_connect",
-    ErrorInAdditionalForwarding = "additional_forwarding_error",
-    WebdebuggerError = "webdebugger_error",
-    NoError = ""
-}
-declare enum TunnelWarningCode {
-    InvalidTunnelServePath = "INVALID_TUNNEL_SERVE_PATH",
-    UnknownWarning = "UNKNOWN_WARNING"
-}
-interface Warning {
-    code: TunnelWarningCode;
-    message: string;
-}
-interface Status {
-    state: TunnelStateType;
-    errorcode: TunnelErrorCodeType;
-    errormsg: string;
-    createdtimestamp: string;
-    starttimestamp: string;
-    endtimestamp: string;
-    warnings: Warning[];
-}
-type ErrorCodeType = "INVALID_REQUEST_METHOD" | "COULD_NOT_READ_BODY" | "INTERNAL_SERVER_ERROR" | "INVALID_DATA_FORMAT" | "ERROR_STARTING_TUNNEL" | "TUNNEL_WITH_ID_OR_CONFIG_ID_NOT_FOUND" | "TUNNEL_WITH_ID_OR_CONFIG_ID_ALREADY_RUNNING" | "WEBSOCKET_UPGRADE_FAILED" | "REMOTE_MANAGEMENT_ALREADY_RUNNING" | "REMOTE_MANAGEMENT_NOT_RUNNING" | "REMOTE_MANAGEMENT_DESERIALIZATION_FAILED";
-interface ErrorResponse {
-    code: ErrorCodeType;
-    message: string;
-}
-type RemoteManagementStatusType = "CONNECTING" | "DISCONNECTING" | "RECONNECTING" | "RUNNING" | "NOT_RUNNING" | "ERROR";
-interface RemoteManagementState {
-    status: RemoteManagementStatusType;
-    errorMessage: string;
-}
-
-/**
- * Manages the lifecycle and state of multiple tunnel instances.
- * Implements the Singleton pattern to ensure only one tunnel manager exists in the application.
- *
- * @remarks
- * This class provides comprehensive tunnel management capabilities including:
- * - Creation and initialization of tunnels
- * - Starting and stopping tunnels
- * - Managing tunnel configurations and states
- * - Handling additional forwarding rules
- * - Monitoring tunnel status
- *
- * @sealed
- * @singleton
- */
-
-interface ManagedTunnel {
-    tunnelid: string;
-    configid: string;
-    tunnelName?: string;
-    instance: TunnelInstance;
-    tunnelConfig?: PinggyOptions;
-    configWithForwarding?: PinggyOptions;
-    additionalForwarding?: AdditionalForwarding[];
-    serveWorker?: Worker | null;
-    warnings?: Warning[];
-    serve?: string;
-    isStopped?: boolean;
-    createdAt?: string;
-    startedAt?: string | null;
-    stoppedAt?: string | null;
-    autoReconnect?: boolean;
-}
-interface TunnelList {
-    tunnelid: string;
-    configid: string;
-    tunnelName?: string;
-    tunnelConfig: PinggyOptions;
-    remoteurls: string[];
-    additionalForwarding?: AdditionalForwarding[];
-    serve?: string;
-}
-type StatsListener = (tunnelId: string, stats: TunnelUsageType) => void;
-type ErrorListener = (tunnelId: string, errorMsg: string, isFatal: boolean) => void;
-type DisconnectListener = (tunnelId: string, error: string, messages: string[]) => void;
-type TunnelWorkerErrorListner = (tunnelid: string, error: Error) => void;
-type StartListener = (tunnelId: string, urls: string[]) => void;
-interface ITunnelManager {
-    createTunnel(config: (PinggyOptions & {
-        configid: string;
-        tunnelid?: string;
-        tunnelName?: string;
-    }) & {
-        additionalForwarding?: AdditionalForwarding[];
-    }): Promise<ManagedTunnel>;
-    startTunnel(tunnelId: string): Promise<string[]>;
-    stopTunnel(tunnelId: string): {
-        configid: string;
-        tunnelid: string;
-    };
-    stopAllTunnels(): void;
-    getTunnelUrls(tunnelId: string): Promise<string[]>;
-    getAllTunnels(): Promise<TunnelList[]>;
-    getTunnelStatus(tunnelId: string): Promise<string>;
-    getTunnelInstance(configId?: string, tunnelId?: string): TunnelInstance;
-    getTunnelConfig(configId?: string, tunnelId?: string): Promise<PinggyOptions>;
-    restartTunnel(tunnelId: string): Promise<void>;
-    updateConfig(newConfig: PinggyOptions & {
-        configid: string;
-        additionalForwarding?: AdditionalForwarding[];
-        tunnelName?: string;
-    }): Promise<ManagedTunnel>;
-    getManagedTunnel(configId?: string, tunnelId?: string): ManagedTunnel;
-    getTunnelGreetMessage(tunnelId: string): Promise<string | null>;
-    getTunnelStats(tunnelId: string): TunnelUsageType[] | null;
-    getLatestTunnelStats(tunnelId: string): TunnelUsageType | null;
-    registerStatsListener(tunnelId: string, listener: StatsListener): Promise<[string, string]>;
-    registerErrorListener(tunnelId: string, listener: ErrorListener): Promise<string>;
-    registerWorkerErrorListner(tunnelId: string, listener: TunnelWorkerErrorListner): void;
-    registerStartListener(tunnelId: string, listener: StartListener): Promise<string>;
-    deregisterErrorListener(tunnelId: string, listenerId: string): void;
-    registerDisconnectListener(tunnelId: string, listener: DisconnectListener): Promise<string>;
-    deregisterDisconnectListener(tunnelId: string, listenerId: string): void;
-    deregisterStatsListener(tunnelId: string, listenerId: string): void;
-    getLocalserverTlsInfo(tunnelId: string): Promise<string | boolean>;
-    removeStoppedTunnelByTunnelId(tunnelId: string): boolean;
-    removeStoppedTunnelByConfigId(configId: string): boolean;
-}
-declare class TunnelManager implements ITunnelManager {
-    private static instance;
-    private tunnelsByTunnelId;
-    private tunnelsByConfigId;
-    private tunnelStats;
-    private tunnelStatsListeners;
-    private tunnelErrorListeners;
-    private tunnelDisconnectListeners;
-    private tunnelWorkerErrorListeners;
-    private tunnelStartListeners;
-    private constructor();
-    static getInstance(): TunnelManager;
-    /**
-     * Creates a new managed tunnel instance with the given configuration.
-     * Builds the config with forwarding rules and creates the tunnel instance.
-     *
-     * @param config - The tunnel configuration options
-     * @param config.configid - Unique identifier for the tunnel configuration
-     * @param config.tunnelid - Optional custom tunnel identifier. If not provided, a random UUID will be generated
-     * @param config.additionalForwarding - Optional array of additional forwarding configurations
-     *
-     * @throws {Error} When configId is invalid or empty
-     * @throws {Error} When a tunnel with the given configId already exists
-     *
-     * @returns {ManagedTunnel} A new managed tunnel instance containing the tunnel details,
-     *                          status information, and statistics
-     */
-    createTunnel(config: (PinggyOptions & {
-        tunnelType: string[] | undefined;
-    } & {
-        configid: string;
-        tunnelid?: string;
-        tunnelName?: string;
-    }) & {
-        additionalForwarding?: AdditionalForwarding[];
-    } & {
-        serve?: string;
-    }): Promise<ManagedTunnel>;
-    /**
-     * Internal method to create a tunnel with an already-processed configuration.
-     * This is used by createTunnel, restartTunnel, and updateConfig to avoid config processing.
-     *
-     * @param params - Configuration parameters with already-processed forwarding rules
-     * @returns The created ManagedTunnel instance
-     * @private
-     */
-    private _createTunnelWithProcessedConfig;
-    /**
-     * Builds the Pinggy configuration by merging the default forwarding rule
-     * with additional forwarding rules from additionalForwarding array.
-     *
-     * @param config - The base Pinggy configuration
-     * @param additionalForwarding - Optional array of additional forwarding rules
-     * @returns Modified PinggyOptions
-     */
-    private buildPinggyConfig;
-    /**
-     * Start a tunnel that was created but not yet started
-     */
-    startTunnel(tunnelId: string): Promise<string[]>;
-    /**
-     * Stops a running tunnel and updates its status.
-     *
-     * @param tunnelId - The unique identifier of the tunnel to stop
-     * @throws {Error} If the tunnel with the given tunnelId is not found
-     * @remarks
-     * - Clears the tunnel's remote URLs
-     * - Updates the tunnel's state to Exited if stopped successfully
-     * - Logs the stop operation with tunnelId and configId
-     */
-    stopTunnel(tunnelId: string): {
-        configid: string;
-        tunnelid: string;
-    };
-    /**
-     * Get all public URLs for a tunnel
-     */
-    getTunnelUrls(tunnelId: string): Promise<string[]>;
-    /**
-     * Get all TunnelStatus currently managed by this TunnelManager
-     * @returns An array of all TunnelStatus objects
-     */
-    getAllTunnels(): Promise<TunnelList[]>;
-    /**
-     * Get status of a tunnel
-     */
-    getTunnelStatus(tunnelId: string): Promise<string>;
-    /**
-     * Stop all tunnels
-     */
-    stopAllTunnels(): void;
-    /**
-     * Remove a stopped tunnel's records so it will no longer be returned by list methods.
-     *
-     *
-     * @param tunnelId - the tunnel id to remove
-     * @returns true if the record was removed, false otherwise
-     */
-    removeStoppedTunnelByTunnelId(tunnelId: string): boolean;
-    /**
-     * Remove a stopped tunnel by its config id.
-     * @param configId - the config id to remove
-     * @returns true if the record was removed, false otherwise
-     */
-    removeStoppedTunnelByConfigId(configId: string): boolean;
-    private _cleanupTunnelRecords;
-    /**
-     * Get tunnel instance by either configId or tunnelId
-     * @param configId - The configuration ID of the tunnel
-     * @param tunnelId - The tunnel ID
-     * @returns The tunnel instance
-     * @throws Error if neither configId nor tunnelId is provided, or if tunnel is not found
-     */
-    getTunnelInstance(configId?: string, tunnelId?: string): TunnelInstance;
-    /**
-     * Get tunnel config by either configId or tunnelId
-     * @param configId - The configuration ID of the tunnel
-     * @param tunnelId - The tunnel ID
-     * @returns The tunnel config
-     * @throws Error if neither configId nor tunnelId is provided, or if tunnel is not found
-     */
-    getTunnelConfig(configId?: string, tunnelId?: string): Promise<PinggyOptions>;
-    /**
-     * Restarts a tunnel with its current configuration.
-     * This function will stop the tunnel if it's running and start it again.
-     * All configurations including additional forwarding rules are preserved.
-     */
-    restartTunnel(tunnelid: string): Promise<void>;
-    /**
-     * Updates the configuration of an existing tunnel.
-     *
-     * This method handles the process of updating a tunnel's configuration while preserving
-     * its state. If the tunnel is running, it will be stopped, updated, and restarted.
-     * In case of failure, it attempts to restore the original configuration.
-     *
-     * @param newConfig - The new configuration to apply, including configid and optional additional forwarding
-     *
-     * @returns Promise resolving to the updated ManagedTunnel
-     * @throws Error if the tunnel is not found or if the update process fails
-     */
-    updateConfig(newConfig: PinggyOptions & {
-        tunnelType: string[] | undefined;
-    } & {
-        configid: string;
-        additionalForwarding?: AdditionalForwarding[];
-        tunnelName?: string;
-        serve?: string;
-    }): Promise<ManagedTunnel>;
-    /**
-     * Retrieve the ManagedTunnel object by either configId or tunnelId.
-     * Throws an error if neither id is provided or the tunnel is not found.
-     */
-    getManagedTunnel(configId?: string, tunnelId?: string): ManagedTunnel;
-    getTunnelGreetMessage(tunnelId: string): Promise<string | null>;
-    getTunnelStats(tunnelId: string): TunnelUsageType[] | null;
-    getLatestTunnelStats(tunnelId: string): TunnelUsageType | null;
-    /**
-     * Registers a listener function to receive tunnel statistics updates.
-     * The listener will be called whenever any tunnel's stats are updated.
-     *
-     * @param tunnelId - The tunnel ID to listen to stats for
-     * @param listener - Function that receives tunnelId and stats when updates occur
-     * @returns A unique listener ID that can be used to deregister the listener and tunnelId
-     *
-     * @throws {Error} When the specified tunnelId does not exist
-     */
-    registerStatsListener(tunnelId: string, listener: StatsListener): Promise<[string, string]>;
-    registerErrorListener(tunnelId: string, listener: ErrorListener): Promise<string>;
-    registerDisconnectListener(tunnelId: string, listener: DisconnectListener): Promise<string>;
-    registerWorkerErrorListner(tunnelId: string, listener: TunnelWorkerErrorListner): Promise<void>;
-    registerStartListener(tunnelId: string, listener: StartListener): Promise<string>;
-    /**
-     * Removes a previously registered stats listener.
-     *
-    * @param tunnelId - The tunnel ID the listener was registered for
-    * @param listenerId - The unique ID returned when the listener was registered
-    */
-    deregisterStatsListener(tunnelId: string, listenerId: string): void;
-    deregisterErrorListener(tunnelId: string, listenerId: string): void;
-    deregisterDisconnectListener(tunnelId: string, listenerId: string): void;
-    getLocalserverTlsInfo(tunnelId: string): Promise<string | false>;
-    /**
-     * Sets up the stats callback for a tunnel during creation.
-     * This callback will update stored stats and notify all registered listeners.
-     */
-    private setupStatsCallback;
-    private notifyErrorListeners;
-    private setupErrorCallback;
-    private setupDisconnectCallback;
-    private setUpTunnelWorkerErrorCallback;
-    /**
-     * Updates the stored stats for a tunnel and notifies all registered listeners.
-     */
-    private updateStats;
-    /**
-     * Normalizes raw usage data from the SDK into a consistent TunnelStats format.
-     */
-    private normalizeStats;
-    private parseNumber;
-    private startStaticFileServer;
-}
-
-declare const TunnelConfigSchema: z.ZodPipe<z.ZodObject<{
-    allowPreflight: z.ZodOptional<z.ZodBoolean>;
-    allowpreflight: z.ZodOptional<z.ZodBoolean>;
-    autoreconnect: z.ZodBoolean;
-    basicauth: z.ZodNullable<z.ZodArray<z.ZodObject<{
-        username: z.ZodString;
-        password: z.ZodString;
-    }, z.core.$strip>>>;
-    bearerauth: z.ZodNullable<z.ZodString>;
-    configid: z.ZodString;
-    configname: z.ZodString;
-    greetmsg: z.ZodOptional<z.ZodString>;
-    force: z.ZodBoolean;
-    forwardedhost: z.ZodString;
-    fullRequestUrl: z.ZodBoolean;
-    headermodification: z.ZodArray<z.ZodObject<{
-        key: z.ZodString;
-        value: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        type: z.ZodEnum<{
-            add: "add";
-            remove: "remove";
-            update: "update";
-        }>;
-    }, z.core.$strip>>;
-    httpsOnly: z.ZodBoolean;
-    internalwebdebuggerport: z.ZodNumber;
-    ipwhitelist: z.ZodNullable<z.ZodArray<z.ZodString>>;
-    localport: z.ZodNumber;
-    localsservertls: z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>;
-    localservertlssni: z.ZodNullable<z.ZodString>;
-    regioncode: z.ZodString;
-    noReverseProxy: z.ZodBoolean;
-    serveraddress: z.ZodString;
-    serverport: z.ZodNumber;
-    statusCheckInterval: z.ZodNumber;
-    token: z.ZodString;
-    tunnelTimeout: z.ZodNumber;
-    type: z.ZodEnum<{
-        http: TunnelType.Http;
-        tcp: TunnelType.Tcp;
-        tls: TunnelType.Tls;
-        udp: TunnelType.Udp;
-        tlstcp: TunnelType.TlsTcp;
-    }>;
-    webdebuggerport: z.ZodNumber;
-    xff: z.ZodString;
-    additionalForwarding: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        remoteDomain: z.ZodOptional<z.ZodString>;
-        remotePort: z.ZodOptional<z.ZodNumber>;
-        localDomain: z.ZodString;
-        localPort: z.ZodNumber;
-    }, z.core.$strip>>>;
-    serve: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>, z.ZodTransform<{
-    allowPreflight: boolean | undefined;
-    allowpreflight: boolean | undefined;
-    autoreconnect: boolean;
-    basicauth: {
-        username: string;
-        password: string;
-    }[] | null;
-    bearerauth: string | null;
-    configid: string;
-    configname: string;
-    force: boolean;
-    forwardedhost: string;
-    fullRequestUrl: boolean;
-    headermodification: {
-        key: string;
-        type: "add" | "remove" | "update";
-        value?: string[] | undefined;
-    }[];
-    httpsOnly: boolean;
-    internalwebdebuggerport: number;
-    ipwhitelist: string[] | null;
-    localport: number;
-    localsservertls: string | boolean;
-    localservertlssni: string | null;
-    regioncode: string;
-    noReverseProxy: boolean;
-    serveraddress: string;
-    serverport: number;
-    statusCheckInterval: number;
-    token: string;
-    tunnelTimeout: number;
-    type: TunnelType;
-    webdebuggerport: number;
-    xff: string;
-    greetmsg?: string | undefined;
-    additionalForwarding?: {
-        localDomain: string;
-        localPort: number;
-        remoteDomain?: string | undefined;
-        remotePort?: number | undefined;
-    }[] | undefined;
-    serve?: string | undefined;
-}, {
-    autoreconnect: boolean;
-    basicauth: {
-        username: string;
-        password: string;
-    }[] | null;
-    bearerauth: string | null;
-    configid: string;
-    configname: string;
-    force: boolean;
-    forwardedhost: string;
-    fullRequestUrl: boolean;
-    headermodification: {
-        key: string;
-        type: "add" | "remove" | "update";
-        value?: string[] | undefined;
-    }[];
-    httpsOnly: boolean;
-    internalwebdebuggerport: number;
-    ipwhitelist: string[] | null;
-    localport: number;
-    localsservertls: string | boolean;
-    localservertlssni: string | null;
-    regioncode: string;
-    noReverseProxy: boolean;
-    serveraddress: string;
-    serverport: number;
-    statusCheckInterval: number;
-    token: string;
-    tunnelTimeout: number;
-    type: TunnelType;
-    webdebuggerport: number;
-    xff: string;
-    allowPreflight?: boolean | undefined;
-    allowpreflight?: boolean | undefined;
-    greetmsg?: string | undefined;
-    additionalForwarding?: {
-        localDomain: string;
-        localPort: number;
-        remoteDomain?: string | undefined;
-        remotePort?: number | undefined;
-    }[] | undefined;
-    serve?: string | undefined;
-}>>;
-type TunnelConfig = z.infer<typeof TunnelConfigSchema>;
-
-interface TunnelResponse {
-    tunnelid: string;
-    remoteurls: string[];
-    tunnelconfig: TunnelConfig;
-    status: Status;
-    stats: TunnelUsageType;
-}
-interface TunnelHandler {
-    handleStart(config: TunnelConfig): Promise<TunnelResponse | ErrorResponse>;
-    handleUpdateConfig(config: TunnelConfig): Promise<TunnelResponse | ErrorResponse>;
-    handleList(): Promise<TunnelResponse[] | ErrorResponse>;
-    handleStop(tunnelid: string): Promise<TunnelResponse | ErrorResponse>;
-    handleGet(tunnelid: string): Promise<TunnelResponse | ErrorResponse>;
-    handleRestart(tunnelid: string): Promise<TunnelResponse | ErrorResponse>;
-    handleRegisterStatsListener(tunnelid: string, listener: (tunnelId: string, stats: TunnelUsageType) => void): void;
-    handleUnregisterStatsListener(tunnelid: string, listnerId: string): void;
-    handleGetTunnelStats(tunnelid: string): TunnelUsageType[] | ErrorResponse;
-    handleRegisterDisconnectListener(tunnelid: string, listener: DisconnectListener): void;
-    handleRemoveStoppedTunnelByTunnelId(tunnelId: string): boolean | ErrorResponse;
-    handleRemoveStoppedTunnelByConfigId(configId: string): boolean | ErrorResponse;
-}
-declare class TunnelOperations implements TunnelHandler {
-    private tunnelManager;
-    constructor();
-    private buildStatus;
-    private buildTunnelResponse;
-    private error;
-    handleStart(config: TunnelConfig): Promise<TunnelResponse | ErrorResponse>;
-    handleUpdateConfig(config: TunnelConfig): Promise<TunnelResponse | ErrorResponse>;
-    handleList(): Promise<TunnelResponse[] | ErrorResponse>;
-    handleStop(tunnelid: string): Promise<TunnelResponse | ErrorResponse>;
-    handleGet(tunnelid: string): Promise<TunnelResponse | ErrorResponse>;
-    handleRestart(tunnelid: string): Promise<TunnelResponse | ErrorResponse>;
-    handleRegisterStatsListener(tunnelid: string, listener: (tunnelId: string, stats: TunnelUsageType) => void): void;
-    handleUnregisterStatsListener(tunnelid: string, listnerId: string): void;
-    handleGetTunnelStats(tunnelid: string): TunnelUsageType[] | ErrorResponse;
-    handleRegisterDisconnectListener(tunnelid: string, listener: DisconnectListener): void;
-    handleRemoveStoppedTunnelByConfigId(configId: string): boolean | ErrorResponse;
-    handleRemoveStoppedTunnelByTunnelId(tunnelId: string): boolean | ErrorResponse;
-}
-
-interface BaseLogConfig {
-    level?: string;
-    filePath?: string;
-    stdout?: boolean;
-    source?: boolean;
-    silent?: boolean;
-    enableSdkLog?: boolean;
-}
-type BaseLogConfigType = BaseLogConfig;
-declare function enablePackageLogging(opts?: BaseLogConfigType): winston.Logger;
-
-/**
- * Initiate remote management mode with a WebSocket connection.
- * - Connect with Authorization: Bearer <token>
- * - On HTTP 401: print Unauthorized and exit
- * - On other failures: retry every 15 seconds
- * - Keep running until closed or SIGINT
- */
-declare function initiateRemoteManagement(token: string, manage?: string): Promise<RemoteManagementState>;
-declare function closeRemoteManagement(timeoutMs?: number): Promise<RemoteManagementState>;
-declare function getRemoteManagementState(): RemoteManagementState;
-
-export { TunnelManager, TunnelOperations, type TunnelResponse, closeRemoteManagement, enablePackageLogging, getRemoteManagementState, initiateRemoteManagement };