Skip to content

remote-dev-box-proxy.md

Latest commit

 

History

History
118 lines (91 loc) · 4.54 KB

remote-dev-box-proxy.md

File metadata and controls

118 lines (91 loc) · 4.54 KB

Remote Dev Box Proxy (rdb)

The remote-dev-box-proxy (aliased as rdb) is a high-performance, Tier 2 reverse proxy written in Go. It resides inside each user's container and handles the dynamic mapping of subdomains and paths to local application services.

Documentation Conventions

Note

Throughout this documentation, we use testdev as the example user account. In a real environment, you should replace testdev with your actual username (e.g., myapp.john.remote-dev-box).

Key Features

  • High Performance: Built on Go's standard library httputil.ReverseProxy.
  • Zero-Reload Updates: CLI commands communicate with the running daemon via a Unix domain socket for instant routing and configuration updates.
  • Single Instance Guard: Prevents multiple daemon processes from conflicting on the same Unix socket.
  • Support for Subdomains & Paths: Routes traffic based on the Host header and URL path prefix.
  • Integrated Help: Comprehensive --help documentation built into the CLI.
  • Fault Isolation: A crash or error in one user's Tier 2 proxy only affects their specific container, not the host or other users.

Architecture

The proxy acts as the second layer in our Tiered Hybrid Routing model:

  1. Tier 1 (Traefik): Host-level proxy (remote-dev-box-traefik). Routes traffic to the correct user container based on the username in the subdomain (e.g., *.testdev.DOMAIN).
  2. Tier 2 (rdb-proxy): Container-level proxy (remote-dev-box-proxy). Routes traffic to specific local ports based on the application name (e.g., api.myapp.testdev.DOMAIN).

Help

Run the --help or -h flag at any level to see usage instructions.

rdb --help
rdb route --help
rdb config --help

Starting the Daemon

The proxy daemon is started automatically by entrypoint.sh as the user.

rdb serve

Configuration

Use the rdb config command to manage persistent settings.

Set a value

rdb config set <key> <value>

Available Keys:

  • localhost: Binds to 127.0.0.1 (true) or 0.0.0.0 (false). Default: false.
  • port: The listening port. Default: 8080.

Tip

Changes made via rdb config set are saved to the configuration file and immediately applied to the running daemon without requiring a restart.

Example:

# Configure to listen on port 9000 and bind to localhost only
rdb config set port 9000
rdb config set localhost true

Managing Routes

Developers can use the rdb shorthand to manage their service routes.

Add a route (Subdomain)

Maps myapp.testdev.remote-dev-box to localhost:8080.

rdb route add myapp.testdev.remote-dev-box localhost:8080

Add multiple subdomains

You can add distinct routes for different subdomains.

# Maps www.myapp.testdev.remote-dev-box -> localhost:3000
rdb route add www.myapp.testdev.remote-dev-box localhost:3000

# Maps api.myapp.testdev.remote-dev-box -> localhost:4000
rdb route add api.myapp.testdev.remote-dev-box localhost:4000

Note: The rdb proxy matches the exact Host header. Ensure the host provided to the CLI matches what Traefik forwards (e.g., api.myapp.testdev.remote-dev-box). We are working on a suffix-handling feature to make this easier.

Add a route (Path-based)

Maps testdev.remote-dev-box/api to localhost:3000.

rdb route add testdev.remote-dev-box localhost:3000 /api

List existing routes

Displays the currently active routing table from the running daemon.

rdb route list

Remove a route

# Remove ALL routes for a host
rdb route remove myapp.testdev.remote-dev-box
# Remove a specific path only
rdb route remove myapp.testdev.remote-dev-box /api

Check Status

Displays the current running status, bind address, and active route count.

rdb route status

Internal Implementation

  • Language: Go 1.22
  • IPC: Unix Domain Socket (/tmp/rdb-proxy.sock)
  • Routing Table: Thread-safe in-memory map with longest-prefix matching for paths.
  • Persistence: Routes are automatically saved to ~/.config/rdb/routes.json and loaded on startup.
  • Configuration: Managed via ~/.config/rdb/config.json.

Security

Traffic between Tier 1 (Traefik) and Tier 2 (rdb-proxy) flows over the isolated remote-dev-net-user network. The proxy only listens on the internal container interface if configured properly, but is typically exposed on port 8080 to the internal network. Architecture tiering ensures that user apps cannot communicate with infrastructure services like the Docker socket proxy.