feat: add admin API endpoints for monitoring and auditing (#158)

Add comprehensive admin API endpoints to enable programmatic monitoring and auditing of
WStunnel server operations:

- **`/admin/monitoring`**: Provides aggregate statistics (unique tunnels, connections,
  request counts) for dashboards and alerting systems
- **`/admin/auditing`**: Provides detailed tunnel information including active connections,
  client details, and request history for security auditing

- **Consolidated admin functionality** in `tunnel/admin_service.go` for maintainability
  and extensibility
- **SQLite-based persistence** with automatic cleanup of records older than 7 days
- **Thread-safe operations** with proper mutex usage for concurrent access
- **Extensible design** allowing easy addition of new admin endpoints

- **Real-time tunnel monitoring**: Track active tunnels, connections, and request volumes
- **Request lifecycle tracking**: Complete audit trail from request start to
  completion/error
- **Client identification**: IP addresses, reverse DNS, WHOIS data, and client version
  tracking
- **Base path support**: Full compatibility with existing base path configuration
- **JSON API responses**: Machine-readable format suitable for automation and web UIs

- `request_events` table: Tracks all HTTP requests with status, timing, and client
  information
- `tunnel_events` table: Records tunnel lifecycle events (connect/disconnect/errors)
- Automatic indexing for performance on common queries
- Built-in cleanup to prevent unbounded growth

```bash
curl http://localhost:8080/admin/monitoring
```
```json
{
  "timestamp": "2025-01-09T15:30:45Z",
  "unique_tunnels": 3,
  "tunnel_connections": 3,
  "pending_requests": 5,
  "completed_requests": 1247,
  "errored_requests": 23
}
```

```bash
curl http://localhost:8080/admin/auditing
```
```json
{
  "timestamp": "2025-01-09T15:30:45Z",
  "tunnels": {
    "my_secret_token": {
      "token": "my_secret_token",
      "remote_addr": "192.168.1.100:54321",
      "remote_name": "client.example.com",
      "client_version": "wstunnel v1.0.0",
      "last_activity": "2025-01-09T15:30:40Z",
      "active_connections": [...],
      "last_error_time": "2025-01-09T15:25:00Z",
      "last_success_time": "2025-01-09T15:30:35Z",
      "pending_requests": 1
    }
  }
}
```

- **Comprehensive test coverage** including lifecycle testing, error handling, and edge
  cases
- **Integration tests** for HTTP handlers with proper status codes and JSON validation
- **Mock server testing** to ensure compatibility with existing WSTunnelServer
  architecture
- **Base path integration testing** to verify proper path handling

- **User documentation** added to README.md with API examples and field descriptions
- **Operations guide** in `docs/ADMIN_API.md` with monitoring scripts, alerting rules,
  and troubleshooting
- **Security recommendations** for production deployment

- **Monitoring dashboards**: Integrate with Prometheus, Grafana, or custom monitoring
  systems
- **Security auditing**: Track client connections, identify suspicious activity, generate
  compliance reports
- **Debugging and troubleshooting**: Inspect active connections, view recent errors,
  identify performance issues
- **Capacity planning**: Monitor usage patterns and plan infrastructure scaling
- **Web UI development**: JSON APIs provide foundation for future web-based admin
  interfaces

- **No breaking changes** to existing functionality
- **Optional initialization** - admin service gracefully handles initialization failures
- **Existing endpoints unchanged** - all current APIs remain fully functional
- **Configuration compatibility** - works with all existing server configuration
  options

Resolves #143 #144

Author: rshade

CLAUDE.md

@@ -19,11 +19,16 @@ WStunnel is a WebSocket-based reverse HTTP/HTTPS tunneling solution that enables
 - `go test -run="<test name>" ./tunnel` - Run a single test
 - `go test ./...` - Run all tests in the project
 
+## Format Commands
+- `make format` - Format all Go files with gofmt
+
 ## Lint Commands
 - `make lint` - Run gofmt check, go vet, golangci-lint, and yamllint
 - `golangci-lint run` - Run comprehensive linting checks
 - `yamllint .github/workflows/` - Check YAML formatting in GitHub workflows
 
+**IMPORTANT** Always run `make format`, `make lint`, and `make test` after making code changes
+
 ## Code Style Guidelines
 - **Formatting**: Use gofmt, tabs for indentation
 - **Imports**: Standard library first, third-party after, group related imports
@@ -99,4 +104,4 @@ Use `~/bin/coderabbit-fix` to automatically apply CodeRabbit suggestions:
 - `coderabbit-fix 153` - Apply all fixes from PR 153
 - `coderabbit-fix 153 --dry-run` - Show what would be changed without applying
 - The tool extracts detailed instructions from CodeRabbit comments including "Prompt for AI Agents" sections
-- Always run `make lint` and `make test` after applying fixes to ensure code quality
+- Always run `make format`, `make lint` and `make test` after applying fixes to ensure code quality

Makefile

@@ -151,6 +151,12 @@ yamllint-fix:
 	  echo "yamllint not found. Install with: pip install yamllint"; \
 	fi
 
+# Format all Go files
+format:
+	@echo "Formatting Go files..."
+	gofmt -w $(shell find . -type f -not -path './.*' -not -path './vendor/*' -not -name 'version.go' -name '*.go')
+	@echo "✓ All .go files formatted"
+
 travis-test: lint
 	go test -race -coverprofile=coverage.txt -covermode=atomic ./...
 

README.md

@@ -358,6 +358,112 @@ The configuration limits section shows:
 
 Note: Full statistics are only available when the endpoint is accessed from localhost. Remote requests will only see the total number of tunnels.
 
+### Admin API Endpoints
+
+WStunnel server provides two JSON API endpoints for programmatic monitoring and auditing:
+
+#### `/admin/monitoring` - Aggregate Statistics
+
+Returns high-level statistics in JSON format, suitable for monitoring dashboards and alerting systems.
+
+**Example Request:**
+```bash
+curl http://localhost:8080/admin/monitoring
+# With base path:
+curl http://localhost:8080/wstunnel/admin/monitoring
+```
+
+**Example Response:**
+```json
+{
+  "timestamp": "2025-01-09T15:30:45Z",
+  "unique_tunnels": 3,
+  "tunnel_connections": 3,
+  "pending_requests": 5,
+  "completed_requests": 1247,
+  "errored_requests": 23
+}
+```
+
+**Fields:**
+- `unique_tunnels`: Number of unique tunnel tokens registered
+- `tunnel_connections`: Number of active tunnel connections
+- `pending_requests`: Current number of requests waiting for response
+- `completed_requests`: Total successful requests since server start
+- `errored_requests`: Total failed requests since server start
+
+#### `/admin/auditing` - Detailed Tunnel Information
+
+Returns comprehensive details about all active tunnels and their connections, suitable for security auditing and detailed analysis.
+
+**Example Request:**
+```bash
+curl http://localhost:8080/admin/auditing
+# With base path:
+curl http://localhost:8080/wstunnel/admin/auditing
+```
+
+**Example Response:**
+```json
+{
+  "timestamp": "2025-01-09T15:30:45Z",
+  "tunnels": {
+    "my_secret_token": {
+      "token": "my_secret_token",
+      "remote_addr": "192.168.1.100:54321",
+      "remote_name": "client.example.com",
+      "remote_whois": "Example Corp",
+      "client_version": "wstunnel v1.0.0",
+      "last_activity": "2025-01-09T15:30:40Z",
+      "active_connections": [
+        {
+          "request_id": 123,
+          "method": "GET",
+          "uri": "/api/data",
+          "remote_addr": "10.0.0.5",
+          "start_time": "2025-01-09T15:30:30Z"
+        }
+      ],
+      "last_error_time": "2025-01-09T15:25:00Z",
+      "last_error_addr": "10.0.0.3",
+      "last_success_time": "2025-01-09T15:30:35Z",
+      "last_success_addr": "10.0.0.5",
+      "pending_requests": 1
+    }
+  }
+}
+```
+
+**Tunnel Fields:**
+- `token`: The tunnel token (first 8 characters shown in logs)
+- `remote_addr`: IP address and port of the tunnel client
+- `remote_name`: Reverse DNS lookup of the client IP
+- `remote_whois`: WHOIS information for the client IP (if available)
+- `client_version`: Version string reported by the tunnel client
+- `last_activity`: Timestamp of last tunnel activity
+- `active_connections`: Array of currently active HTTP requests
+- `last_error_time`: Timestamp of most recent failed request (optional)
+- `last_error_addr`: IP address of most recent failed request (optional)
+- `last_success_time`: Timestamp of most recent successful request (optional)
+- `last_success_addr`: IP address of most recent successful request (optional)
+- `pending_requests`: Number of requests currently pending
+
+**Active Connection Fields:**
+- `request_id`: Unique identifier for the request
+- `method`: HTTP method (GET, POST, etc.)
+- `uri`: The requested URI path
+- `remote_addr`: IP address of the client making the request
+- `start_time`: When the request was initiated
+
+**Use Cases:**
+- **Monitoring**: Use `/admin/monitoring` for dashboards, alerting, and performance tracking
+- **Security Auditing**: Use `/admin/auditing` to track which clients are connecting from where
+- **Debugging**: Use `/admin/auditing` to see active requests and recent errors
+- **Capacity Planning**: Monitor request volumes and tunnel usage patterns
+- **Web UI Integration**: Both endpoints return JSON suitable for web-based admin interfaces
+
+**Security Note:** These endpoints are accessible without authentication. In production environments, consider placing them behind a reverse proxy with appropriate access controls.
+
 ### Reading wstunnel server logs
 
 Sample: