Merge pull request #3 from cube-root/mocks

Mocks

Author: abhisawesome

README.md

@@ -20,6 +20,7 @@ That's it! Your local server running on port 3000 is now accessible from the int
 - **Request Inspector** - Built-in web UI to monitor all proxied requests and responses in real-time
 - **API Composer** - Postman-like request builder inside the inspector to craft and send HTTP requests
 - **cURL Export** - Generate copy-ready cURL commands from any captured request
+- **Mock Mode** - Define mock responses for API paths without a running backend, with a web UI to manage mocks
 - **Token Protection** - Secure your tunnels with authentication tokens
 - **Self-Hostable** - Run your own ProxyHub server
 - **Session Timeouts** - Configurable session duration limits
@@ -74,6 +75,31 @@ Inspector features:
 - **cURL export** — expand the cURL section on any request detail page to get a ready-to-copy command
 - Light/dark theme
 
+### Mock Mode
+
+Define mock API responses without needing a real backend server. Mock mode includes a web UI for managing mocks and supports exact, prefix, and regex path matching.
+
+```bash
+# Pure mock mode (no local server needed)
+proxyhub --mock
+
+# Hybrid mode (mocked paths return mock data, others proxy to localhost)
+proxyhub --mock -p 3000
+
+# Inspector automatically enables mock mode
+proxyhub -p 3000 --inspect
+```
+
+Once running, open the Mock Manager URL shown in the terminal (e.g., `http://localhost:3001/mocks`) to create and manage mocks.
+
+Mock features:
+- **Pure mock mode** — no local server required, define all responses via the UI
+- **Hybrid mode** — combine mocks with a real backend; mocked paths return mock data, non-mocked paths proxy normally
+- **Path matching** — exact, prefix, or regex matching with configurable priority
+- **Response customization** — set status codes, headers, body, and response delay
+- **Inspector integration** — mocked requests appear in the inspector with a `MOCK` badge
+- Enable/disable individual mocks without deleting them
+
 ### Token Protection
 
 Secure your tunnel so only requests with the correct token can access it:
@@ -96,14 +122,17 @@ curl -H "X-Proxy-Token: mysecrettoken" https://your-tunnel.proxyhub.cloud/
 
 | Option | Description |
 |--------|-------------|
-| `-p, --port <port>` | Port number to proxy (required) |
+| `-p, --port <port>` | Port number to proxy |
+| `-m, --mock` | Enable mock mode |
 | `-t, --token <token>` | Token for tunnel protection |
 | `-i, --inspect` | Enable request inspector UI |
 | `--inspect-port <port>` | Port for inspector UI (default: port + 1000) |
 | `-d, --debug` | Enable debug mode |
 | `-V, --version` | Output version number |
 | `-h, --help` | Display help |
 
+Either `--port` or `--mock` is required. Using `--inspect` automatically enables mock mode.
+
 ## Self-Hosting
 
 ### Docker (Recommended)

packages/client/README.md

@@ -59,6 +59,31 @@ Inspector features:
 - **cURL export** — expand the cURL section on any request detail page to get a ready-to-copy command
 - Light/dark theme
 
+### Mock Mode
+
+Define mock API responses without needing a real backend server. Mock mode includes a web UI for managing mocks and supports exact, prefix, and regex path matching.
+
+```bash
+# Pure mock mode (no local server needed)
+proxyhub --mock
+
+# Hybrid mode (mocked paths return mock data, others proxy to localhost)
+proxyhub --mock -p 3000
+
+# Inspector automatically enables mock mode
+proxyhub -p 3000 --inspect
+```
+
+Once running, open the Mock Manager URL shown in the terminal (e.g., `http://localhost:3001/mocks`) to create and manage mocks.
+
+Mock features:
+- **Pure mock mode** — no local server required, define all responses via the UI
+- **Hybrid mode** — combine mocks with a real backend; mocked paths return mock data, non-mocked paths proxy normally
+- **Path matching** — exact, prefix, or regex matching with configurable priority
+- **Response customization** — set status codes, headers, body, and response delay
+- **Inspector integration** — mocked requests appear in the inspector with a `MOCK` badge
+- Enable/disable individual mocks without deleting them
+
 ### Token Protection
 
 Secure your tunnel so only requests with the correct token can access it:
@@ -83,14 +108,17 @@ proxyhub -p 3000 --debug
 
 | Option | Description |
 |--------|-------------|
-| `-p, --port <port>` | Port number to proxy (required) |
+| `-p, --port <port>` | Port number to proxy |
+| `-m, --mock` | Enable mock mode |
 | `-t, --token <token>` | Token for tunnel protection |
 | `-i, --inspect` | Enable request inspector UI |
 | `--inspect-port <port>` | Port for inspector UI (default: port + 1000) |
 | `-d, --debug` | Enable debug mode |
 | `-V, --version` | Output version number |
 | `-h, --help` | Display help |
 
+Either `--port` or `--mock` is required. Using `--inspect` automatically enables mock mode.
+
 ## Self-Hosted Server
 
 Connect to your own ProxyHub server using environment variables:

packages/client/package.json

@@ -23,8 +23,12 @@
     "api",
     "testing"
   ],
-  "author": "",
+  "author": "Abhijith V",
   "license": "MIT",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
   "homepage": "https://proxyhub.app",
   "repository": {
     "type": "git",

packages/client/src/@types/index.d.ts

@@ -1,10 +1,11 @@
 declare global {
     interface ClientInitializationOptions {
-        port: number;
+        port?: number;
         debug?: boolean;
         token?: string;
         inspect?: boolean;
         inspectPort?: number;
+        mock?: boolean;
     }
 
     interface TunnelRequestArgument {
@@ -88,6 +89,47 @@ declare global {
         avg_duration_ms: number | null;
     }
 
+    interface MockDefinition {
+        id: string;
+        method: string;
+        path: string;
+        path_type: 'exact' | 'prefix' | 'regex';
+        status_code: number;
+        headers: string;
+        body: string | null;
+        delay_ms: number;
+        priority: number;
+        enabled: number;
+        description: string | null;
+        created_at: string;
+        updated_at: string;
+    }
+
+    interface MockInsert {
+        method?: string;
+        path: string;
+        path_type?: string;
+        status_code?: number;
+        headers?: string;
+        body?: string;
+        delay_ms?: number;
+        priority?: number;
+        description?: string;
+    }
+
+    interface MockUpdate {
+        method?: string;
+        path?: string;
+        path_type?: string;
+        status_code?: number;
+        headers?: string;
+        body?: string;
+        delay_ms?: number;
+        priority?: number;
+        enabled?: number;
+        description?: string;
+    }
+
 }
 
 export {};

packages/client/src/index.ts

@@ -23,28 +23,51 @@ program
     .name('ProxyHub')
     .description("Test your API's with ease - Tunnel localhost to the internet")
     .version(version)
-    .requiredOption('-p, --port <port>', 'Port number for proxying', portNumberCustomValidationForCommander)
+    .option('-p, --port <port>', 'Port number for proxying', portNumberCustomValidationForCommander)
     .option('-d, --debug', 'Enable debug mode', false)
     .option('-t, --token <token>', 'Token for tunnel protection')
     .option('-i, --inspect', 'Enable request inspector', false)
+    .option('-m, --mock', 'Enable mock mode', false)
     .option('--inspect-port <port>', 'Port for inspector UI', parseInt);
 
 // Parse command line arguments
 program.parse(process.argv);
 
 // Get parsed options and check for env var fallback
-const parsedOpts = program.opts() as ClientInitializationOptions;
+const parsedOpts = program.opts() as ClientInitializationOptions & { port?: number };
 const options: ClientInitializationOptions = {
     port: parsedOpts.port,
     debug: parsedOpts.debug,
     token: parsedOpts.token || process.env.PROXYHUB_TOKEN,
     inspect: parsedOpts.inspect,
     inspectPort: parsedOpts.inspectPort,
+    mock: parsedOpts.mock,
 };
 
+// Validate: need either port or mock mode
+if (!options.port && !options.mock) {
+    console.error(chalk.red('Error: Either --port or --mock is required.'));
+    console.error(chalk.gray('  Use --port <port> to proxy to a local server'));
+    console.error(chalk.gray('  Use --mock for pure mock mode (no local server needed)'));
+    process.exit(1);
+}
+
+// Mock and inspect are co-dependent — enabling either enables both
+if (options.mock || options.inspect) {
+    options.mock = true;
+    options.inspect = true;
+}
+
 // Startup logging
 console.log('\nStarting ProxyHub Client...');
-console.log('Target:', chalk.cyan(`http://localhost:${options.port}`));
+if (options.port) {
+    console.log('Target:', chalk.cyan(`http://localhost:${options.port}`));
+}
+if (options.mock && options.port) {
+    console.log('Mode:', chalk.magenta('hybrid (mock + proxy)'));
+} else if (options.mock) {
+    console.log('Mode:', chalk.magenta('pure mock (no local server)'));
+}
 if (options.token) {
     console.log('Token protection:', chalk.green('enabled'));
 }
@@ -61,7 +84,6 @@ socketHandler(options);
 
 // Start inspector if enabled
 if (options.inspect) {
-    const inspectPort = options.inspectPort || options.port + 1000;
-    startInspector(inspectPort, options.port);
+    const inspectPort = options.inspectPort || (options.port ? options.port + 1000 : 3001);
+    startInspector(inspectPort, options.port, { mock: options.mock });
 }
-

packages/client/src/lib/db.ts

@@ -40,6 +40,23 @@ export function initDb(): void {
         CREATE INDEX IF NOT EXISTS idx_requests_method ON requests(method);
         CREATE INDEX IF NOT EXISTS idx_requests_status_code ON requests(status_code);
         CREATE INDEX IF NOT EXISTS idx_requests_path ON requests(path);
+
+        CREATE TABLE IF NOT EXISTS mocks (
+            id          TEXT PRIMARY KEY,
+            method      TEXT NOT NULL DEFAULT '*',
+            path        TEXT NOT NULL,
+            path_type   TEXT NOT NULL DEFAULT 'exact',
+            status_code INTEGER NOT NULL DEFAULT 200,
+            headers     TEXT NOT NULL DEFAULT '{}',
+            body        TEXT,
+            delay_ms    INTEGER NOT NULL DEFAULT 0,
+            priority    INTEGER NOT NULL DEFAULT 0,
+            enabled     INTEGER NOT NULL DEFAULT 1,
+            description TEXT,
+            created_at  TEXT NOT NULL,
+            updated_at  TEXT NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS idx_mocks_enabled ON mocks(enabled);
     `);
 
     // Migrate: add response_body column if missing (existing DBs)
@@ -57,7 +74,7 @@ export function closeDb(): void {
     }
 }
 
-function getDb(): Database.Database {
+export function getDb(): Database.Database {
     if (!db) throw new Error('Database not initialized. Call initDb() first.');
     return db;
 }