🦘 hop

Smart proxying made simple.

An extensible port proxy and request enhancement CLI tool for local development.

Features

• Easy Proxy Management: Add, list, remove, and edit proxies via interactive CLI.
• Path-Based Routing: Forward specific paths to different targets.
• Path Rewriting: Rewrite URL paths using regex patterns (e.g., /api/v1 -> /v2).
• Custom Headers: Inject custom headers (e.g., Authorization cookies) into requests.
• CORS Support: Automatically handles CORS preflight requests.
• Local HTTPS: Auto-generated self-signed certificates for local HTTPS support.
• Project-Level Config: Automatically detects hop.json in your current directory.
• TUI Dashboard: Interactive terminal dashboard to monitor requests and responses in real-time.
• Config Sharing: Export and import proxy configurations easily (Base64/JSON).
• Plugin System: Extend functionality with custom JavaScript plugins.

Installation

npm install -g @miaoosi/hop

Quick Start

Option 1: Using the TUI (Recommended)

1. Launch the management interface:

   hop

2. Add a proxy:

   • Press a to add a new proxy
   • Your default editor will open with the config file
   • Add your proxy configuration (see examples below)
   • Save and exit

3. Start/Stop proxies:

   • Press s to toggle the selected proxy
   • Or press Enter to view details, then s to start/stop

Option 2: Using CLI Commands

1. Add a proxy:

   hop add

   Follow the interactive prompts to configure your proxy.

2. Start the server:

   hop serve

   This will launch the interactive dashboard where you can monitor traffic.

Commands

• hop: Launch the interactive TUI management interface (recommended).
• hop add: Add a new proxy rule.
• hop list: List all configured proxies.
• hop edit: Edit an existing proxy (modify target, headers, rewrites, plugins, etc.).
• hop remove: Remove a proxy.
• hop serve [names...]: Start the proxy server(s) with request monitoring dashboard.
• hop export [name]: Export configuration (Base64).
• hop import <input>: Import configuration from Base64 string or file.

Configuration

hop supports both global and project-level configuration.

1. Project Config (Recommended for teams): Create a hop.json in your project root. hop will prioritize this file if it exists.
2. Global Config: Stored in ~/.hop/config.json.

Configuration Format (hop.json)

{
  "proxies": [
    {
      "name": "api-server",
      "port": 8080,
      "target": "http://localhost:3000",
      "https": true,
      "paths": ["/api", "/auth"], // [] means all paths
      "pathRewrite": {
        "^/api": ""
      },
      "headers": {
        "Authorization": "Bearer token"
      },
      "plugins": ["./my-plugin.js"]
    }
  ]
}

Plugin System

You can extend hop by attaching custom JavaScript plugins to your proxies.

1. Create a plugin file (e.g., logger.js):

module.exports = {
  // Executed before request is forwarded
  onRequest: (req, res, next) => {
    console.log('Request:', req.url);
    req.headers['x-custom-header'] = 'hello';
    next();
  },

  // Executed after response is received
  onResponse: (proxyRes, req, res) => {
    console.log('Status:', proxyRes.statusCode);
  }
};

2. Add it to your proxy:

• Via CLI: Select "Plugins" when adding/editing.
• Via Config: Add "plugins": ["./logger.js"] to your hop.json.

TUI Interface

hop provides two interactive terminal interfaces:

1. Management TUI (Default)

Run hop without arguments to launch the interactive management interface:

hop

Features:

• Proxy List: View all configured proxies with their status (Running/Stopped)
• Quick Actions:
  • ↑/↓: Navigate through proxies
  • Enter: View proxy details
  • a: Add new proxy (opens config in editor)
  • d: Delete proxy (with confirmation)
  • s: Start/Stop selected proxy
  • q / Ctrl+C: Exit

Proxy Details View:

• View complete proxy configuration
• e: Edit proxy (opens config in editor)
• s: Start/Stop proxy
  • Esc / Backspace: Back to list

Configuration Editing: When you press a (add) or e (edit), hop opens your default editor ($EDITOR or vim) with the configuration file. Simply edit the JSON and save to apply changes.

2. Dashboard (Request Monitor)

When you run hop serve, the terminal switches to a real-time request monitoring dashboard:

hop serve

Features:

• Left Panel: Real-time list of requests with method, path, status, and duration
• Right Panel (Top): Detailed view of selected request (headers, body)
• Right Panel (Bottom): System logs
• Keys:
  • ↑/↓: Navigate requests
  • Enter: View request details
  • Tab: Switch between panels
  • f: Toggle auto-scroll
  • q / Ctrl+C: Exit

Output:

┌──────────────┬──────┬─────────────────────────┬──────────────────────┬─────────────────┐
│ Name         │ Port │ Target                  │ Paths                │ Headers         │
├──────────────┼──────┼─────────────────────────┼──────────────────────┼─────────────────┤
│ api-proxy    │ 3000 │ https://api.example.com │ /api/users, /api/... │ Authorization   │
│ auth-service │ 5000 │ https://auth.example.com│ (all)                │ -               │
└──────────────┴──────┴─────────────────────────┴──────────────────────┴─────────────────┘

3. Edit a proxy

hop edit

Select a proxy and choose which properties to edit (name, port, target, paths, or headers). You can:

• Update individual fields
• Add or remove headers
• Replace all headers
• Clear all headers

4. Start the proxy server

Start all proxies:

hop serve

Start specific proxies by name:

hop serve api-proxy auth-service

Output:

✔ Hop proxy server running!

✓ Started api-proxy on port 3000 → https://api.example.com (paths: /api/users, /api/posts)
✓ Started auth-service on port 5000 → https://auth.example.com

ℹ Press Ctrl+C to stop

5. Remove a proxy

hop remove

Select the proxy you want to remove from the list.

6. Get help

hop help

Commands

| Command | Aliases | Description | |---------|---------|-------------| | hop add | - | Add a new proxy rule (interactive) | | hop list | ls | List all configured proxies | | hop edit | - | Edit an existing proxy rule (interactive) | | hop remove | rm | Remove a proxy rule (interactive) | | hop serve [names...] | start | Start proxy servers (all or specific ones) | | hop help | - | Display detailed help information |

Path Matching

When adding a proxy, you can specify which paths should be proxied:

? Paths to proxy (comma-separated, leave empty for all): /api/users, /api/posts, /v1/auth

How it works:

• If paths are specified, only requests matching those paths will be proxied
• Matches exact paths and sub-paths (e.g., /api/users matches /api/users/123)
• If no paths are specified, all requests are proxied
• Non-matching requests return 404 with a helpful message

Example:

# Only /api/users and /api/posts are proxied
$ curl http://localhost:3000/api/users      # ✓ Proxied
$ curl http://localhost:3000/api/users/123  # ✓ Proxied
$ curl http://localhost:3000/other          # ✗ 404: Path not configured

Configuration

Hop stores configuration in ~/.hop/config.json:

{
  "proxies": [
    {
      "name": "api-proxy",
      "port": 3000,
      "target": "https://api.example.com",
      "paths": ["/api/users", "/api/posts"],
      "headers": {
        "Authorization": "Bearer your-token-here",
        "Cookie": "session=abc123"
      }
    },
    {
      "name": "auth-service",
      "port": 5000,
      "target": "https://auth.example.com"
    }
  ]
}

CORS Configuration

By default, Hop automatically handles CORS headers by mirroring the client's requested headers. For more control, you can configure CORS settings:

{
  "name": "custom-cors-proxy",
  "port": 3000,
  "target": "https://api.example.com",
  "cors": {
    "allowOrigin": "https://myapp.com",
    "allowHeaders": ["Content-Type", "Authorization", "X-Custom-Header"],
    "allowMethods": ["GET", "POST", "PUT", "DELETE"],
    "allowCredentials": true
  }
}

CORS Options:

• allowOrigin (string, optional): Specific origin to allow. Defaults to the request origin or *
• allowHeaders (string[] | '*', optional): Array of allowed headers or '*' for all. If not specified, automatically mirrors the client's requested headers
• allowMethods (string[], optional): Array of allowed HTTP methods. Defaults to ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS']
• allowCredentials (boolean, optional): Whether to allow credentials. Defaults to true

[!NOTE] The default behavior (without explicit CORS config) is smart - it automatically allows whatever headers the client requests, making it work seamlessly with any custom headers like x-csrf-token without manual configuration.

Use Cases

• 🔐 API Development - Proxy API requests to add authentication headers
• 🧪 Testing - Test APIs with different headers without modifying code
• 🍪 Session Management - Add cookies for local development
• 🌐 Remote Development - Forward requests to remote servers with custom headers
• 🛣️ Path Routing - Proxy only specific API endpoints
• 🎯 Multi-Service - Run multiple proxies for different microservices

Examples

Example 1: API with Authentication

# Add an API proxy with auth header
hop add
? Proxy name: my-api
? Port: 3000
? Target: https://api.production.com
? Paths: /api/v1/users, /api/v1/products
? Add custom headers? Yes
? Header name: Authorization
? Header value: Bearer your-api-token

# Start the proxy
hop serve my-api

# Make requests
curl http://localhost:3000/api/v1/users  # Proxied with auth header

Example 2: Multiple Services

# Add multiple proxies
hop add  # Create "users-api" on port 3000
hop add  # Create "orders-api" on port 4000
hop add  # Create "auth-api" on port 5000

# Start all services
hop serve

# Or start only specific services
hop serve users-api orders-api

Example 3: Editing an Existing Proxy

# Edit a proxy configuration
hop edit
? Select proxy to edit: my-api (port: 3000 → https://api.production.com)
? What would you like to edit? (Press space to select)
  ◉ Port
  ◉ Headers

? New local port: 3001
? How would you like to manage headers? Keep existing and add more
? Header name: X-Custom-Header
? Header value: custom-value
? Add another header? No

✔ Proxy updated: my-api

Example 4: Custom CORS Configuration

For scenarios where you need strict CORS control or want to allow specific origins only:

{
  "name": "secure-api",
  "port": 4000,
  "target": "https://secure-api.example.com",
  "headers": {
    "Authorization": "Bearer secret-token"
  },
  "cors": {
    "allowOrigin": "https://trusted-domain.com",
    "allowHeaders": ["Content-Type", "Authorization", "X-CSRF-Token"],
    "allowMethods": ["GET", "POST"],
    "allowCredentials": true
  }
}

This configuration:

• Only allows requests from https://trusted-domain.com
• Restricts headers to a specific whitelist
• Only permits GET and POST methods
• Enables credential support for cookies and auth headers

Development

# Clone the repository
git clone https://github.com/knight174/hop.git
cd hop

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm run dev

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT