pinggy 0.1.0

package/src/types.ts

@@ -0,0 +1,234 @@
+import { PinggyOptions, TunnelUsageType } from "@pinggy/pinggy";
+
+// Local representation of additional forwarding
+export interface AdditionalForwarding {
+    remoteDomain?: string;
+    remotePort: number;
+    localDomain: string;
+    localPort: number;
+}
+
+export interface TunnelStatus {
+    tunnelid: string,
+    remoteurls: string[],
+    tunnelconfig: PinggyOptions,
+    status: Status,
+    stats: TunnelUsageType
+}
+
+
+
+// Enum for TunnelStateType
+export enum TunnelStateType {
+    New = "idle",
+    Starting = "starting",
+    Running = "running",
+    Live = "live",
+    Closed = "closed",
+    Exited = "exited"
+}
+
+// Enum for TunnelErrorCodeType
+export enum TunnelErrorCodeType {
+    NonResponsive = "non_responsive",
+    FailedToConnect = "failed_to_connect",
+    ErrorInAdditionalForwarding = "additional_forwarding_error",
+    WebdebuggerError = "webdebugger_error",
+    NoError = ""
+}
+
+// Enum for TunnelWarningCode
+export enum TunnelWarningCode {
+    InvalidTunnelServePath = "INVALID_TUNNEL_SERVE_PATH"
+}
+
+// Interface for Warning
+export interface Warning {
+    code: TunnelWarningCode;
+    message: string;
+}
+
+
+
+// Main Status interface
+export interface Status {
+    state: TunnelStateType;
+    errorcode: TunnelErrorCodeType;
+    errormsg: string;
+    createdtimestamp: Date;
+    starttimestamp: Date;
+    endtimestamp: Date;
+    warnings: Warning[];
+}
+
+export type Forwarding = {
+    remoteDomain?: string;
+    remotePort: number;
+    localDomain: string;
+    localPort: number;
+};
+
+export type FinalConfig = (PinggyOptions & { configid: string }) & {
+    conf?: string;
+    saveconf?: string;
+    serve?: string;
+    remoteManagement?: string;
+    additionalForwarding?: Forwarding[];
+    manage?: string;
+    version?: boolean;
+    NoTUI?: boolean;
+    qrCode?: boolean;
+};
+
+export 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";
+
+export const ErrorCode: Record<string, ErrorCodeType> = {
+    InvalidRequestMethodError: "INVALID_REQUEST_METHOD",
+    InvalidRequestBodyError: "COULD_NOT_READ_BODY",
+    InternalServerError: "INTERNAL_SERVER_ERROR",
+    InvalidBodyFormatError: "INVALID_DATA_FORMAT",
+    ErrorStartingTunnel: "ERROR_STARTING_TUNNEL",
+    TunnelNotFound: "TUNNEL_WITH_ID_OR_CONFIG_ID_NOT_FOUND",
+    TunnelAlreadyRunningError: "TUNNEL_WITH_ID_OR_CONFIG_ID_ALREADY_RUNNING",
+    WebsocketUpgradeFailError: "WEBSOCKET_UPGRADE_FAILED",
+    RemoteManagementAlreadyRunning: "REMOTE_MANAGEMENT_ALREADY_RUNNING",
+    RemoteManagementNotRunning: "REMOTE_MANAGEMENT_NOT_RUNNING",
+    RemoteManagementDeserializationFailed: "REMOTE_MANAGEMENT_DESERIALIZATION_FAILED",
+} as const;
+
+export interface ErrorResponse {
+    code: ErrorCodeType;
+    message: string;
+}
+
+export function isErrorResponse(obj: unknown): obj is ErrorResponse {
+    return (
+        typeof obj === 'object' &&
+        obj !== null &&
+        'code' in obj &&
+        'message' in obj &&
+        typeof (obj as ErrorResponse).message === 'string' &&
+        Object.values(ErrorCode).includes((obj as ErrorResponse).code)
+    );
+}
+
+export function newErrorResponse(errorResponse: ErrorResponse): ErrorResponse;
+export function newErrorResponse(code: ErrorCodeType, message: string): ErrorResponse;
+export function newErrorResponse(codeOrError: ErrorCodeType | ErrorResponse, message?: string): ErrorResponse {
+    if (typeof codeOrError === 'object') {
+        return codeOrError;
+    }
+    return {
+        code: codeOrError,
+        message: message!
+    };
+}
+
+
+export interface ResponseObj {
+    response: Uint8Array;
+    requestid: string;
+    command: string;
+    error: boolean;
+    errorresponse: ErrorResponse;
+}
+
+export function NewResponseObject(data: unknown): ResponseObj {
+    const encoder = new TextEncoder();
+    const bytes = encoder.encode(JSON.stringify(data));
+    return {
+        response: bytes,
+        requestid: "",
+        command: "",
+        error: false,
+        errorresponse: {} as ErrorResponse,
+    };
+}
+
+export function NewErrorResponseObject(errorResponse: ErrorResponse): ResponseObj {
+    return {
+        response: new Uint8Array(),
+        requestid: "",
+        command: "",
+        error: true,
+        errorresponse: errorResponse,
+    };
+}
+
+export function newStatus(
+    tunnelState: TunnelStateType,
+    errorCode: TunnelErrorCodeType,
+    errorMsg: string,
+): Status {
+    let assignedState = tunnelState;
+    if (tunnelState === TunnelStateType.Live) {
+        assignedState = TunnelStateType.Running;
+    } else if (tunnelState === TunnelStateType.New) {
+        assignedState = TunnelStateType.Starting;
+    } else if (tunnelState === TunnelStateType.Closed) {
+        assignedState = TunnelStateType.Exited;
+    }
+
+    return {
+        state: assignedState,
+        errorcode: errorCode,
+        errormsg: errorMsg,
+        createdtimestamp: new Date(),
+        starttimestamp: new Date(),
+        endtimestamp: new Date(),
+        warnings: []
+    };
+}
+
+export function newStats(): TunnelUsageType {
+    return {
+        numLiveConnections: 0,
+        numTotalConnections: 0,
+        numTotalReqBytes: 0,
+        numTotalResBytes: 0,
+        numTotalTxBytes: 0,
+        elapsedTime: 0,
+    };
+}
+
+export interface Request {
+    key: number;
+    method: string;
+    uri: string;
+}
+
+export interface Response {
+    key: number;
+    status: string;
+}
+
+export interface ReqResPair {
+    request: Request;
+    response: Response;
+    reqHeaders: string;
+    resHeaders: string;
+    headersLoaded: boolean;
+}
+export interface StatsAll {
+    activeConn: number;
+    numRequests: number;
+    numResponses: number;
+    reqBytes: number;
+    resBytes: number;
+    totalConn: number;
+}
+export interface WebDebuggerSocketRequest {
+    Req: Request;
+    Res: Response;
+}

package/src/utils/getFreePort.ts

@@ -0,0 +1,41 @@
+import net from "net";
+
+/**
+ * Get a free TCP port.
+ * If `providedPort` is available, returns that.
+ * Otherwise, returns a randomly assigned free port from the OS.
+ */
+export function getFreePort(webDebugger: string): Promise<number> {
+    return new Promise((resolve, reject) => {
+        // Try provided port first
+        const tryPort = (portToTry: number) => {
+            const server = net.createServer();
+
+            server.unref(); 
+
+            server.on("error", (err) => {
+                // If provided port failed, try random port (0)
+                if (portToTry !== 0) {
+                    tryPort(0);
+                } else {
+                    reject(err);
+                }
+            });
+
+            server.listen(portToTry, () => {
+                const address: net.AddressInfo = server.address() as net.AddressInfo;
+                const port = address ? address.port : 0;
+                server.close(() => resolve(port));
+            });
+        };
+        let providedPort = 0;
+        if (webDebugger && webDebugger.includes(":")) {
+            const portPart = webDebugger.split(":")[1];
+            const parsed = parseInt(portPart, 10);
+            if (!isNaN(parsed) && parsed > 0 && parsed < 65536) {
+                providedPort = parsed;
+            }
+        }
+        tryPort(providedPort);
+    });
+}

package/src/utils/parseArgs.ts

@@ -0,0 +1,29 @@
+import { parseArgs } from "util";
+import { cliOptions } from "../cli/options.js";
+
+export type OptionSpec = {
+    type: 'string' | 'boolean';
+    multiple?: boolean;
+    short?: string;
+    description?: string;
+    hidden?: boolean;
+};
+
+export type CliOptions = typeof cliOptions;
+
+export type ParsedValues<T extends Record<string, OptionSpec>> = {
+    [K in keyof T]:
+    T[K]['type'] extends 'string'
+    ? (T[K]['multiple'] extends true ? string[] : string | undefined)
+    : (T[K]['type'] extends 'boolean' ? boolean | undefined : never);
+};
+
+export function parseCliArgs<T extends Record<string, OptionSpec>>(options: T) {
+    return parseArgs({
+        options,
+        allowPositionals: true,
+    }) as unknown as {
+        values: ParsedValues<T>;
+        positionals: string[];
+    };
+}

package/src/utils/printer.ts

@@ -0,0 +1,79 @@
+import chalk from "chalk";
+import ora, {Ora} from "ora";
+
+interface CLIErrorDefinition {
+  match: (err: unknown) => boolean;
+  message: (err: unknown) => string;
+}
+
+class CLIPrinter {
+  private static spinner: Ora | null = null;
+  private static isCLIError(err: unknown): err is Error & { code?: string; option?: string; value?: string } {
+    return err instanceof Error;
+  }
+  private static errorDefinitions: CLIErrorDefinition[] = [
+    {
+      match: (err) => this.isCLIError(err) && err.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION",
+      message: (err) => {
+        const match = /Unknown option '(.+?)'/.exec((err as any).message);
+        const option = match ? match[1] : '(unknown)';
+        return `Unknown option '${option}'. Please check your command or use pinggy --h for guidance.`;
+      },
+    },
+    {
+      match: (err) => this.isCLIError(err) && err.code === "ERR_PARSE_ARGS_MISSING_OPTION_VALUE",
+      message: (err) => `Missing required argument for option '${(err as any).option}'.`,
+    },
+    {
+      match: (err) => this.isCLIError(err) && err.code === "ERR_PARSE_ARGS_INVALID_OPTION_VALUE",
+      message: (err) => `Invalid argument'${(err as any).message}'.`,
+    },
+    {
+      match: (err) => this.isCLIError(err) && err.code === "ENOENT",
+      message: (err) => `File or directory not found: ${(err as any).message}`,
+    },
+    {
+      match: () => true, // fallback
+      message: (err) => (this.isCLIError(err) ? err.message : String(err)),
+    },
+  ];
+
+  static print(message: string, ...args: any[]) {
+    console.log(message, ...args);
+  }
+
+  static error(err: unknown) {
+    const def = this.errorDefinitions.find((d) => d.match(err))!;
+    const msg = def.message(err);
+    console.error(chalk.redBright("✖ Error:"), chalk.red(msg));
+    process.exit(1);
+  }
+
+  static warn(message: string) {
+    console.warn(chalk.yellowBright("⚠ Warning:"), chalk.yellow(message));
+  }
+
+  static success(message: string) {
+    console.log(chalk.greenBright("✔ Success:"), chalk.green(message));
+  }
+  static info(message: string) {
+    console.log(chalk.blue(message));
+  }
+
+
+  static startSpinner(message: string) {
+    this.spinner = ora({ text: message, color: "cyan" }).start();
+  }
+
+  static stopSpinnerSuccess(message: string) {
+    this.spinner?.succeed(message);
+    this.spinner = null;
+  }
+
+  static stopSpinnerFail(message: string) {
+    this.spinner?.fail(message);
+    this.spinner = null;
+  }
+}
+
+export default CLIPrinter;

package/src/utils/util.ts

@@ -0,0 +1,13 @@
+import { readFileSync } from 'fs';
+import { createRequire } from 'module';
+
+export function isValidPort(p: number): boolean {
+    return Number.isInteger(p) && p > 0 && p < 65536;
+}
+
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json');
+
+export function getVersion(): string {
+    return pkg.version ?? '';
+}

package/tsconfig.jest.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": ["node", "jest"],
+    "noEmit": true
+  },
+  "include": ["src/**/*"]
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "es2016",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "lib": ["es2017", "dom"],
+    "types": ["node"],
+    "jsx": "react-jsx",
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "**/*.test.ts"]
+}