Add path-based routing for Cloudflare free SSL compatibility

Path-based routing allows tunnel URLs like tunnel.example.com/id/ instead of id.tunnel.example.com, which works with Cloudflare's free Universal SSL certificate.

Changes:

- Add EXIO_ROUTING_MODE config (path or subdomain, default: path)

- Server extracts tunnel ID from path and rewrites request before forwarding

- Client queries /_config endpoint to determine URL format

- Add comprehensive tests for path extraction and rewriting

- Update documentation with routing mode configuration

Author: SonnyTaylor

README.md

@@ -16,6 +16,7 @@ Exio is a developer tool that creates secure tunnels from your local machine to
 - **PSK authentication** - Simple shared-secret authentication model
 - **Interactive TUI** - Real-time request inspection with `--tui` flag
 - **Cloudflare-ready** - Designed to sit behind Cloudflare Tunnel for production deployments
+- **Flexible routing** - Path-based (`tunnel.example.com/id/`) or subdomain-based (`id.tunnel.example.com`) routing
 
 ## Installation
 
@@ -59,13 +60,17 @@ This interactive wizard will prompt you for your server URL and authentication t
 # Expose local port 3000
 exio http 3000
 
-# Request a specific subdomain
+# Request a specific tunnel ID
 exio http 3000 --subdomain my-app
 
 # With real-time request viewer
 exio http 3000 --tui
 ```
 
+Your service will be available at a URL like:
+- **Path mode (default)**: `https://tunnel.example.com/my-app/`
+- **Subdomain mode**: `https://my-app.tunnel.example.com`
+
 ### Manual Configuration
 
 Alternatively, configure via environment variables:
@@ -152,10 +157,20 @@ sudo systemctl start exiod
 
 ### Cloudflare Tunnel Configuration
 
+**For path-based routing (recommended):**
+1. Create a Cloudflare Tunnel in your Zero Trust dashboard
+2. Configure public hostname: `tunnel.example.com`
+3. Set service: `http://localhost:8080`
+4. Add a single DNS CNAME record for `tunnel` pointing to your tunnel
+
+**For subdomain-based routing:**
 1. Create a Cloudflare Tunnel in your Zero Trust dashboard
-2. Configure public hostname: `*.dev.example.com`
+2. Configure public hostname: `*.tunnel.example.com`
 3. Set service: `http://localhost:8080`
-4. The tunnel handles SSL termination; Exio receives plain HTTP
+4. Add a wildcard DNS CNAME record for `*.tunnel`
+5. Requires Cloudflare Advanced Certificate Manager for SSL on `*.tunnel.example.com`
+
+The tunnel handles SSL termination; Exio receives plain HTTP.
 
 ## Protocol Details
 
@@ -167,8 +182,20 @@ The client establishes a WebSocket connection to `/_connect` with:
 
 ### Data Plane
 
-1. Server receives HTTP request for `<subdomain>.dev.example.com`
-2. Server extracts subdomain from Host header
+**Path-based routing (default):**
+1. Server receives HTTP request for `tunnel.example.com/my-app/api/users`
+2. Server extracts tunnel ID (`my-app`) from the first path segment
+3. Server rewrites path to `/api/users` (strips tunnel ID prefix)
+4. Server looks up session in registry
+5. Server opens new Yamux stream to client
+6. Server writes modified HTTP request to stream
+7. Client reads request, forwards to local service
+8. Client writes response back to stream
+9. Server copies response to original HTTP response writer
+
+**Subdomain-based routing:**
+1. Server receives HTTP request for `my-app.tunnel.example.com/api/users`
+2. Server extracts subdomain (`my-app`) from Host header
 3. Server looks up session in registry
 4. Server opens new Yamux stream to client
 5. Server writes raw HTTP request to stream
@@ -209,7 +236,15 @@ Use `--no-rewrite-host` to disable this behavior if your local service requires
 |------|-------------|-------------|
 | `--port, -p` | `EXIO_PORT` | Listening port (default: 8080) |
 | `--token, -t` | `EXIO_TOKEN` | Authentication token (required) |
-| `--domain, -d` | `EXIO_BASE_DOMAIN` | Base domain for subdomains (required) |
+| `--domain, -d` | `EXIO_BASE_DOMAIN` | Base domain for tunnel URLs (required) |
+| `--routing-mode, -r` | `EXIO_ROUTING_MODE` | Routing mode: `path` (default) or `subdomain` |
+
+### Routing Modes
+
+| Mode | URL Format | SSL Requirements |
+|------|------------|------------------|
+| `path` | `https://tunnel.example.com/my-app/` | Standard SSL (free Cloudflare) |
+| `subdomain` | `https://my-app.tunnel.example.com` | Wildcard SSL (Advanced Certificate Manager) |
 
 ## License
 

cmd/exiod/main.go

@@ -45,11 +45,13 @@ func init() {
 	rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.exiod.yaml)")
 	rootCmd.Flags().IntP("port", "p", 8080, "Server listening port")
 	rootCmd.Flags().StringP("token", "t", "", "Authentication token")
-	rootCmd.Flags().StringP("domain", "d", "", "Base domain for tunnel subdomains")
+	rootCmd.Flags().StringP("domain", "d", "", "Base domain for tunnel URLs")
+	rootCmd.Flags().StringP("routing-mode", "r", "path", "Routing mode: 'path' (tunnel.example.com/id/) or 'subdomain' (id.tunnel.example.com)")
 
 	viper.BindPFlag("port", rootCmd.Flags().Lookup("port"))
 	viper.BindPFlag("token", rootCmd.Flags().Lookup("token"))
 	viper.BindPFlag("domain", rootCmd.Flags().Lookup("domain"))
+	viper.BindPFlag("routing-mode", rootCmd.Flags().Lookup("routing-mode"))
 
 	// Add version command
 	rootCmd.AddCommand(&cobra.Command{
@@ -80,15 +82,22 @@ func initConfig() {
 	viper.BindEnv("port", "EXIO_PORT")
 	viper.BindEnv("token", "EXIO_TOKEN")
 	viper.BindEnv("domain", "EXIO_BASE_DOMAIN")
+	viper.BindEnv("routing-mode", "EXIO_ROUTING_MODE")
 
 	viper.ReadInConfig()
 }
 
 func runServer(cmd *cobra.Command, args []string) error {
+	routingMode := viper.GetString("routing-mode")
+	if routingMode == "" {
+		routingMode = "path" // Default to path-based routing
+	}
+
 	config := &server.Config{
-		Port:       viper.GetInt("port"),
-		Token:      viper.GetString("token"),
-		BaseDomain: viper.GetString("domain"),
+		Port:        viper.GetInt("port"),
+		Token:       viper.GetString("token"),
+		BaseDomain:  viper.GetString("domain"),
+		RoutingMode: routingMode,
 	}
 
 	if config.Token == "" {
@@ -99,6 +108,10 @@ func runServer(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("base domain is required (set EXIO_BASE_DOMAIN or use --domain)")
 	}
 
+	if routingMode != "path" && routingMode != "subdomain" {
+		return fmt.Errorf("invalid routing mode '%s': must be 'path' or 'subdomain'", routingMode)
+	}
+
 	srv, err := server.New(config)
 	if err != nil {
 		return fmt.Errorf("failed to create server: %w", err)

docs/DEPLOYMENT.md

@@ -52,8 +52,13 @@ EXIO_PORT=8080
 # openssl rand -hex 32
 EXIO_TOKEN=your-secret-token-here
 
-# Base domain for tunnel subdomains
-EXIO_BASE_DOMAIN=dev.example.com
+# Base domain for tunnel URLs
+EXIO_BASE_DOMAIN=tunnel.example.com
+
+# Routing mode: "path" (default) or "subdomain"
+# - path: URLs like https://tunnel.example.com/my-app/
+# - subdomain: URLs like https://my-app.tunnel.example.com
+EXIO_ROUTING_MODE=path
 EOF
 
 # Secure the config file
@@ -131,13 +136,32 @@ cloudflared tunnel create exio
 
 Create `/etc/cloudflared/config.yml`:
 
+**For path-based routing (recommended):**
+
+```yaml
+tunnel: <TUNNEL_ID>
+credentials-file: /etc/cloudflared/<TUNNEL_ID>.json
+
+ingress:
+  # Single hostname for path-based routing
+  - hostname: "tunnel.example.com"
+    service: http://localhost:8080
+  # Catch-all (required)
+  - service: http_status:404
+```
+
+**For subdomain-based routing:**
+
 ```yaml
 tunnel: <TUNNEL_ID>
 credentials-file: /etc/cloudflared/<TUNNEL_ID>.json
 
 ingress:
   # Wildcard for all subdomains
-  - hostname: "*.dev.example.com"
+  - hostname: "*.tunnel.example.com"
+    service: http://localhost:8080
+  # Base domain for control plane
+  - hostname: "tunnel.example.com"
     service: http://localhost:8080
   # Catch-all (required)
   - service: http_status:404
@@ -146,12 +170,23 @@ ingress:
 ### 5. Configure DNS
 
 In Cloudflare Dashboard:
+
+**For path-based routing (recommended):**
 1. Go to DNS settings
 2. Add CNAME record:
-   - Name: `*.dev` (or your subdomain)
+   - Name: `tunnel`
    - Target: `<TUNNEL_ID>.cfargotunnel.com`
    - Proxy status: Proxied
 
+This is covered by Cloudflare's free Universal SSL certificate.
+
+**For subdomain-based routing:**
+1. Go to DNS settings
+2. Add CNAME records:
+   - Name: `tunnel`, Target: `<TUNNEL_ID>.cfargotunnel.com`, Proxied
+   - Name: `*.tunnel`, Target: `<TUNNEL_ID>.cfargotunnel.com`, Proxied
+3. Enable Advanced Certificate Manager in SSL/TLS settings to get a certificate for `*.tunnel.example.com`
+
 ### 6. Run cloudflared as Service
 
 ```bash

internal/client/client.go

@@ -4,7 +4,9 @@ package client
 import (
 	"bufio"
 	"context"
+	"encoding/json"
 	"fmt"
+	"io"
 	"log"
 	"net"
 	"net/http"
@@ -30,9 +32,16 @@ type Config struct {
 	RewriteHost bool
 }
 
+// ServerConfig holds the server's configuration returned from /_config endpoint.
+type ServerConfig struct {
+	RoutingMode string `json:"routing_mode"`
+	BaseDomain  string `json:"base_domain"`
+}
+
 // Client is the Exio tunneling client (exio).
 type Client struct {
 	config        *Config
+	serverConfig  *ServerConfig
 	authenticator *auth.Authenticator
 	session       *transport.Session
 	logger        *log.Logger
@@ -74,8 +83,64 @@ func New(config *Config) (*Client, error) {
 	}, nil
 }
 
+// fetchServerConfig queries the server's /_config endpoint to get routing mode.
+func (c *Client) fetchServerConfig(ctx context.Context) error {
+	configURL, err := url.Parse(c.config.ServerURL)
+	if err != nil {
+		return fmt.Errorf("invalid server URL: %w", err)
+	}
+
+	configURL.Path = "/_config"
+
+	req, err := http.NewRequestWithContext(ctx, "GET", configURL.String(), nil)
+	if err != nil {
+		return fmt.Errorf("failed to create config request: %w", err)
+	}
+
+	client := &http.Client{Timeout: 10 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		// If we can't reach the config endpoint, assume subdomain mode for backward compatibility
+		c.logger.Printf("Warning: Could not fetch server config, assuming subdomain mode: %v", err)
+		c.serverConfig = &ServerConfig{
+			RoutingMode: protocol.RoutingModeSubdomain,
+			BaseDomain:  extractBaseDomain(c.config.ServerURL),
+		}
+		return nil
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		// Older servers may not have /_config endpoint
+		c.logger.Printf("Warning: Server config endpoint returned %d, assuming subdomain mode", resp.StatusCode)
+		c.serverConfig = &ServerConfig{
+			RoutingMode: protocol.RoutingModeSubdomain,
+			BaseDomain:  extractBaseDomain(c.config.ServerURL),
+		}
+		return nil
+	}
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return fmt.Errorf("failed to read config response: %w", err)
+	}
+
+	var serverConfig ServerConfig
+	if err := json.Unmarshal(body, &serverConfig); err != nil {
+		return fmt.Errorf("failed to parse config response: %w", err)
+	}
+
+	c.serverConfig = &serverConfig
+	return nil
+}
+
 // Connect establishes a tunnel connection to the server.
 func (c *Client) Connect(ctx context.Context) error {
+	// First, fetch server configuration to determine routing mode
+	if err := c.fetchServerConfig(ctx); err != nil {
+		return fmt.Errorf("failed to fetch server config: %w", err)
+	}
+
 	// Build the WebSocket URL
 	serverURL, err := url.Parse(c.config.ServerURL)
 	if err != nil {
@@ -154,9 +219,12 @@ func (c *Client) Connect(ctx context.Context) error {
 	c.connectedAt = time.Now()
 	c.mu.Unlock()
 
-	// Build public URL (assume https and the server's base domain)
-	// The actual URL depends on the server configuration
-	c.publicURL = fmt.Sprintf("https://%s.%s", c.config.Subdomain, extractBaseDomain(c.config.ServerURL))
+	// Build public URL based on server's routing mode
+	if c.serverConfig.RoutingMode == protocol.RoutingModePath {
+		c.publicURL = fmt.Sprintf("https://%s/%s/", c.serverConfig.BaseDomain, c.config.Subdomain)
+	} else {
+		c.publicURL = fmt.Sprintf("https://%s.%s", c.config.Subdomain, c.serverConfig.BaseDomain)
+	}
 
 	c.logger.Printf("Tunnel established!")
 	c.logger.Printf("Public URL: %s", c.publicURL)