feat: add base path support for reverse proxy deployments (#157)

Add -base-path configuration option to enable WStunnel server deployment
behind reverse proxies (Envoy, Istio, nginx) with path-based routing.

## Summary

* Add -base-path command-line flag to configure base path prefix
* Implement automatic path normalization (leading/trailing slashes)
* Update HTTP route registration to use base path prefixes
* Add URL rewriting middleware to strip base path from requests
* Preserve existing functionality when no base path is configured

## Features

* **Base Path Configuration**: New -base-path flag for server deployment
* **Path Normalization**: Automatic handling of leading/trailing slashes
* **Route Prefixing**: All endpoints (/_tunnel, /_health_check, /_stats, /_token/)
  support base paths
* **URL Rewriting**: Transparent base path removal before request processing
* **Backward Compatibility**: No impact on existing deployments

## Implementation Details

* Added BasePath field to WSTunnelServer struct
* Created normalizeBasePath() helper for path validation
* Implemented shouldStripBasePath() for proper URL matching
* Added buildPath() utility for route construction
* Enhanced HTTP handler wrapper for automatic path stripping

## Testing

* Comprehensive unit tests for path normalization and URL rewriting
* Integration tests with real HTTP servers and various base path
  configurations
* Edge case testing for empty paths, root paths, and special characters
* All existing tests continue to pass

## Documentation

* Updated README.md with base path configuration examples
* Enhanced CLAUDE.md with operational guidance
* Created comprehensive proxy configuration examples (Envoy, Istio, nginx,
  HAProxy)
* Added Kubernetes deployment examples and troubleshooting guide

## Use Cases

This enables WStunnel deployment in modern containerized environments:

* Kubernetes ingress controllers with path-based routing
* Istio service mesh with VirtualService path matching
* Envoy proxy configurations with prefix routing
* nginx reverse proxy setups with location blocks
* API gateway deployments with versioned paths

## Example Usage

```bash
# Deploy behind reverse proxy at /wstunnel path
./wstunnel srv -port 8080 -base-path /wstunnel

# Access endpoints with base path
curl http://proxy.example.com/wstunnel/_health_check
curl http://proxy.example.com/wstunnel/_stats
```

Fixes #129

Author: rshade

CLAUDE.md

@@ -78,9 +78,11 @@ WStunnel is a WebSocket-based reverse HTTP/HTTPS tunneling solution that enables
 ## Configuration Options
 - **Max Requests Per Tunnel**: Use `-max-requests-per-tunnel N` to limit queued requests per tunnel (default: 20)
 - **Max Clients Per Token**: Use `-max-clients-per-token N` to limit concurrent clients per token (default: 0/unlimited)
+- **Base Path**: Use `-base-path /path` to run behind reverse proxies with path-based routing (e.g., `-base-path /wstunnel`)
 - When a tunnel reaches the max request limit, new requests return "too many requests in-flight, tunnel broken?"
 - When a token reaches the max client limit, new connections return HTTP 429 "Maximum number of clients reached"
 - Client counts are automatically decremented when clients disconnect
+- Base path configuration automatically prefixes all endpoints (/_tunnel, /_health_check, /_stats, /_token/) with the specified path
 
 ## CodeRabbit Review Settings
 The project uses CodeRabbit for automated code reviews (see `.coderabbit.yaml`). When writing code, ensure compliance with:

README.md

@@ -103,6 +103,17 @@ WSTUNSRV RUNNING
 $
 ```
 
+When using a base path, the health check URL includes the base path:
+
+```bash
+$ ./wstunnel srv -port 8080 -base-path /wstunnel &
+2014/01/19 09:51:31 Listening on port 8080
+2014/01/19 09:51:31 Base path configured basePath=/wstunnel
+$ curl http://localhost:8080/wstunnel/_health_check
+WSTUNSRV RUNNING
+$
+```
+
 #### Server Configuration Options
 
 The WStunnel server supports several configuration options to control resource usage and security:
@@ -136,10 +147,26 @@ $ ./wstunnel srv -port 8080 -max-clients-per-token 1 &
 
 This is useful when you want to ensure only a single client instance per token is allowed, preventing unauthorized token sharing or connection conflicts.
 
+**Base Path Configuration:**
+When running behind a reverse proxy (like Envoy, Istio Ingress Gateway, or nginx) with path-based routing, use the `-base-path` option to specify the base path for all endpoints:
+
+```bash
+$ ./wstunnel srv -port 8080 -base-path /wstunnel &
+2024/01/19 09:51:31 Listening on port 8080
+2024/01/19 09:51:31 Base path configured basePath=/wstunnel
+```
+
+With a base path configured, all WStunnel endpoints become available under the specified path:
+- Health check: `http://proxy.example.com/wstunnel/_health_check`
+- Stats: `http://proxy.example.com/wstunnel/_stats`
+- Tunnel endpoint: `ws://proxy.example.com/wstunnel/_tunnel`
+- Token-based requests: `http://proxy.example.com/wstunnel/_token/your-token/path`
+
 **Combined Configuration Example:**
 
 ```bash
 $ ./wstunnel srv -port 8080 \
+  -base-path /api/v1/tunnel \
   -passwords 'prod-token:secure-password,dev-token:dev-pass' \
   -max-requests-per-tunnel 30 \
   -max-clients-per-token 2 &
@@ -161,10 +188,19 @@ $ ./wstunnel cli -tunnel ws://wstun.example.com:8080 -server http://localhost -t
 2014/01/19 09:54:51 Opening ws://wstun.example.com/_tunnel
 ```
 
+If the server is running with a base path (e.g., `-base-path /wstunnel`), include it in the tunnel URL:
+
+```bash
+$ ./wstunnel cli -tunnel ws://wstun.example.com:8080/wstunnel -server http://localhost -token 'my_b!g_$secret!!'
+2014/01/19 09:54:51 Opening ws://wstun.example.com/wstunnel/_tunnel
+```
+
 To use a token with a password for additional security:
 
 ```bash
 $ ./wstunnel cli -tunnel ws://wstun.example.com:8080 -server http://localhost -token 'my_b!g_$secret!!:mypassword'
+# Or with base path:
+$ ./wstunnel cli -tunnel ws://wstun.example.com:8080/wstunnel -server http://localhost -token 'my_b!g_$secret!!:mypassword'
 ```
 
 > **Security Warning**: Passing passwords via command-line arguments is not recommended as they can be exposed through:
@@ -186,13 +222,21 @@ $ ./wstunnel cli -tunnel ws://wstun.example.com:8080 -server http://localhost -t
 On `client.example.com` use curl to make a request to the web server running on `www.example.com`:
 
 ```bash
-
 $ curl 'https://wstun.example.com:8080/_token/my_b!g_$secret!!/some/web/page'
 <html> .......
 $ curl '-HX-Token:my_b!g_$secret!!' https://wstun.example.com:8080/some/web/page
 <html> .......
 ```
 
+If the server is running with a base path, include it in the request URLs:
+
+```bash
+$ curl 'https://wstun.example.com:8080/wstunnel/_token/my_b!g_$secret!!/some/web/page'
+<html> .......
+$ curl '-HX-Token:my_b!g_$secret!!' https://wstun.example.com:8080/wstunnel/some/web/page
+<html> .......
+```
+
 ### Running on Android
 
 WStunnel can be run on Android devices using terminal emulators like Termux. See the [Android documentation](docs/ANDROID.md) for detailed setup instructions.
@@ -270,7 +314,7 @@ server {
 
 ### Monitoring and Status Endpoint
 
-WStunnel server provides a `/_stats` endpoint that displays information about connected tunnels. When accessed from localhost, it provides detailed information including:
+WStunnel server provides a `/_stats` endpoint that displays information about connected tunnels (or `/your-base-path/_stats` when using a base path). When accessed from localhost, it provides detailed information including:
 
 - Number of active tunnels
 - Server configuration limits