Edge Region Auto-Routing

Status: Implemented

Overview

When multiple edge regions are configured, the CLI automatically probes each one and connects to the lowest-latency edge. This reduces round-trip time for tunnelled requests without requiring the user to manually pick a region.

Components

Bridge API

• GET /api/cli/edge-regions (public, no auth) -- returns the list of active edge regions with WebSocket URLs.
• Controller: App\Http\Controllers\Api\CliEdgeRegionsController
• Reads from config('jetty.network_regions') and builds per-region WebSocket URLs using each region's hostname (falls back to the default edge_ws_url when no hostname is set).

Response shape:

{
  "edges": [
    {"url": "wss://us.tunnels.example.com/agent", "region": "us-east", "location": "New York"},
    {"url": "wss://eu.tunnels.example.com/agent", "region": "eu-west", "location": "Amsterdam"}
  ]
}

CLI ApiClient (jetty-client/src/ApiClient.php)

• getEdgeRegions(): array -- calls GET /api/cli/edge-regions and returns the edges array. Returns [] on any failure.
• selectFastestEdge(array $edges): ?array -- sends a HEAD request to each edge (converting wss:// to https:// for the probe), measures wall-clock latency, and returns the fastest entry with an added latency_ms key.

CLI ShareCommand (jetty-client/src/Commands/ShareCommand.php)

Before connecting to the edge WebSocket the command:

1. Calls getEdgeRegions().
2. If more than one edge is returned, runs selectFastestEdge().
3. Overrides the default $ws URL with the winning edge URL.
4. Displays the selected region: Connecting to New York (42ms)...
5. Falls back to the default edge URL from the tunnel API response if probing fails or only one region exists.

The selected $ws URL is used for both the initial connection and for reconnects via EdgeAgent::run().

Configuration

Operators configure regions via the JETTY_NETWORK_REGIONS environment variable (JSON array). Each region object should include:

*At least one of name or location must be non-empty.

When no regions are configured (single-edge deployments), the endpoint returns a single entry with the default edge_ws_url and the CLI skips probing entirely.