docs: add per package README for implementation details (AI generated with human review)

2026-01-11 21:10:30 +01:00 · 2026-01-08 23:39:19 +08:00
parent 13441286d1
commit e9d7edef12
54 changed files with 13431 additions and 1519 deletions
--- a/agent/cmd/README.md
+++ b/agent/cmd/README.md
@@ -0,0 +1,52 @@
+# agent/cmd
+
+The main entry point for the GoDoxy Agent, a secure monitoring and proxy agent that runs alongside Docker containers.
+
+## Overview
+
+This package contains the `main.go` entry point for the GoDoxy Agent. The agent is a TLS-enabled server that provides:
+
+- Secure Docker socket proxying with client certificate authentication
+- HTTP proxy capabilities for container traffic
+- System metrics collection and monitoring
+- Health check endpoints
+
+## Architecture
+
+```mermaid
+graph TD
+    A[main] --> B[Logger Init]
+    A --> C[Load CA Certificate]
+    A --> D[Load Server Certificate]
+    A --> E[Log Version Info]
+    A --> F[Start Agent Server]
+    A --> G[Start Socket Proxy]
+    A --> H[Start System Info Poller]
+    A --> I[Wait Exit]
+
+    F --> F1[TLS with mTLS]
+    F --> F2[Agent Handler]
+    G --> G1[Docker Socket Proxy]
+```
+
+## Main Function Flow
+
+1. **Logger Setup**: Configures zerolog with console output
+1. **Certificate Loading**: Loads CA and server certificates for TLS/mTLS
+1. **Version Logging**: Logs agent version and configuration
+1. **Agent Server**: Starts the main HTTPS server with agent handlers
+1. **Socket Proxy**: Starts Docker socket proxy if configured
+1. **System Monitoring**: Starts system info polling
+1. **Graceful Shutdown**: Waits for exit signal (3 second timeout)
+
+## Configuration
+
+See `agent/pkg/env/README.md` for configuration options.
+
+## Dependencies
+
+- `agent/pkg/agent` - Core agent types and constants
+- `agent/pkg/env` - Environment configuration
+- `agent/pkg/server` - Server implementation
+- `socketproxy/pkg` - Docker socket proxy
+- `internal/metrics/systeminfo` - System metrics
--- a/agent/pkg/agent/README.md
+++ b/agent/pkg/agent/README.md
@@ -0,0 +1,108 @@
+# Agent Package
+
+The `agent` package provides the client-side implementation for interacting with GoDoxy agents. It handles agent configuration, secure communication via TLS, and provides utilities for agent deployment and management.
+
+## Architecture Overview
+
+```mermaid
+graph TD
+    subgraph GoDoxy Server
+        AP[Agent Pool] --> AC[AgentConfig]
+    end
+
+    subgraph Agent Communication
+        AC -->|HTTPS| AI[Agent Info API]
+        AC -->|TLS| ST[Stream Tunneling]
+    end
+
+    subgraph Deployment
+        G[Generator] --> DC[Docker Compose]
+        G --> IS[Install Script]
+    end
+
+    subgraph Security
+        NA[NewAgent] --> Certs[Certificates]
+    end
+```
+
+## File Structure
+
+| File                                                     | Purpose                                                   |
+| -------------------------------------------------------- | --------------------------------------------------------- |
+| [`config.go`](agent/pkg/agent/config.go)                 | Core configuration, initialization, and API client logic. |
+| [`new_agent.go`](agent/pkg/agent/new_agent.go)           | Agent creation and certificate generation logic.          |
+| [`docker_compose.go`](agent/pkg/agent/docker_compose.go) | Generator for agent Docker Compose configurations.        |
+| [`bare_metal.go`](agent/pkg/agent/bare_metal.go)         | Generator for bare metal installation scripts.            |
+| [`env.go`](agent/pkg/agent/env.go)                       | Environment configuration types and constants.            |
+| [`common/`](agent/pkg/agent/common)                      | Shared constants and utilities for agents.                |
+
+## Core Types
+
+### [`AgentConfig`](agent/pkg/agent/config.go:29)
+
+The primary struct used by the GoDoxy server to manage a connection to an agent. It stores the agent's address, metadata, and TLS configuration.
+
+### [`AgentInfo`](agent/pkg/agent/config.go:45)
+
+Contains basic metadata about the agent, including its version, name, and container runtime (Docker or Podman).
+
+### [`PEMPair`](agent/pkg/agent/new_agent.go:53)
+
+A utility struct for handling PEM-encoded certificate and key pairs, supporting encryption, decryption, and conversion to `tls.Certificate`.
+
+## Agent Creation and Certificate Management
+
+### Certificate Generation
+
+The [`NewAgent`](agent/pkg/agent/new_agent.go:147) function creates a complete certificate infrastructure for an agent:
+
+- **CA Certificate**: Self-signed root certificate with 1000-year validity.
+- **Server Certificate**: For the agent's HTTPS server, signed by the CA.
+- **Client Certificate**: For the GoDoxy server to authenticate with the agent.
+
+All certificates use ECDSA with P-256 curve and SHA-256 signatures.
+
+### Certificate Security
+
+- Certificates are encrypted using AES-GCM with a provided encryption key.
+- The [`PEMPair`](agent/pkg/agent/new_agent.go:53) struct provides methods for encryption, decryption, and conversion to `tls.Certificate`.
+- Base64 encoding is used for certificate storage and transmission.
+
+## Key Features
+
+### 1. Secure Communication
+
+All communication between the GoDoxy server and agents is secured using mutual TLS (mTLS). The [`AgentConfig`](agent/pkg/agent/config.go:29) handles the loading of CA and client certificates to establish secure connections.
+
+### 2. Agent Discovery and Initialization
+
+The [`Init`](agent/pkg/agent/config.go:231) and [`InitWithCerts`](agent/pkg/agent/config.go:110) methods allow the server to:
+
+- Fetch agent metadata (version, name, runtime).
+- Verify compatibility between server and agent versions.
+- Test support for TCP and UDP stream tunneling.
+
+### 3. Deployment Generators
+
+The package provides interfaces and implementations for generating deployment artifacts:
+
+- **Docker Compose**: Generates a `docker-compose.yml` for running the agent as a container via [`AgentComposeConfig.Generate()`](agent/pkg/agent/docker_compose.go:21).
+- **Bare Metal**: Generates a shell script to install and run the agent as a systemd service via [`AgentEnvConfig.Generate()`](agent/pkg/agent/bare_metal.go:27).
+
+### 4. Fake Docker Host
+
+The package supports a "fake" Docker host scheme (`agent://<addr>`) to identify containers managed by an agent, allowing the GoDoxy server to route requests appropriately. See [`IsDockerHostAgent`](agent/pkg/agent/config.go:90) and [`GetAgentAddrFromDockerHost`](agent/pkg/agent/config.go:94).
+
+## Usage Example
+
+```go
+cfg := &agent.AgentConfig{}
+cfg.Parse("192.168.1.100:8081")
+
+ctx := context.Background()
+if err := cfg.Init(ctx); err != nil {
+    log.Fatal(err)
+}
+
+fmt.Printf("Connected to agent: %s (Version: %s)\n", cfg.Name, cfg.Version)
+```
--- a/agent/pkg/agentproxy/README.md
+++ b/agent/pkg/agentproxy/README.md
@@ -0,0 +1,122 @@
+# agent/pkg/agentproxy
+
+Package for configuring HTTP proxy connections through the GoDoxy Agent using HTTP headers.
+
+## Overview
+
+This package provides types and functions for parsing and setting agent proxy configuration via HTTP headers. It supports both a modern base64-encoded JSON format and a legacy header-based format for backward compatibility.
+
+## Architecture
+
+```mermaid
+graph LR
+    A[HTTP Request] --> B[ConfigFromHeaders]
+    B --> C{Modern Format?}
+    C -->|Yes| D[Parse X-Proxy-Config Base64 JSON]
+    C -->|No| E[Parse Legacy Headers]
+    D --> F[Config]
+    E --> F
+
+    F --> G[SetAgentProxyConfigHeaders]
+    G --> H[Modern Headers]
+    G --> I[Legacy Headers]
+```
+
+## Public Types
+
+### Config
+
+```go
+type Config struct {
+    Scheme string       // Proxy scheme (http or https)
+    Host   string       // Proxy host (hostname or hostname:port)
+    HTTPConfig         // Extended HTTP configuration
+}
+```
+
+The `HTTPConfig` embedded type (from `internal/route/types`) includes:
+
+- `NoTLSVerify` - Skip TLS certificate verification
+- `ResponseHeaderTimeout` - Timeout for response headers
+- `DisableCompression` - Disable gzip compression
+
+## Public Functions
+
+### ConfigFromHeaders
+
+```go
+func ConfigFromHeaders(h http.Header) (Config, error)
+```
+
+Parses proxy configuration from HTTP request headers. Tries modern format first, falls back to legacy format if not present.
+
+### proxyConfigFromHeaders
+
+```go
+func proxyConfigFromHeaders(h http.Header) (Config, error)
+```
+
+Parses the modern base64-encoded JSON format from `X-Proxy-Config` header.
+
+### proxyConfigFromHeadersLegacy
+
+```go
+func proxyConfigFromHeadersLegacy(h http.Header) Config
+```
+
+Parses the legacy header format:
+
+- `X-Proxy-Host` - Proxy host
+- `X-Proxy-Https` - Whether to use HTTPS
+- `X-Proxy-Skip-Tls-Verify` - Skip TLS verification
+- `X-Proxy-Response-Header-Timeout` - Response timeout in seconds
+
+### SetAgentProxyConfigHeaders
+
+```go
+func (cfg *Config) SetAgentProxyConfigHeaders(h http.Header)
+```
+
+Sets headers for modern format with base64-encoded JSON config.
+
+### SetAgentProxyConfigHeadersLegacy
+
+```go
+func (cfg *Config) SetAgentProxyConfigHeadersLegacy(h http.Header)
+```
+
+Sets headers for legacy format with individual header fields.
+
+## Header Constants
+
+Modern headers:
+
+- `HeaderXProxyScheme` - Proxy scheme
+- `HeaderXProxyHost` - Proxy host
+- `HeaderXProxyConfig` - Base64-encoded JSON config
+
+Legacy headers (deprecated):
+
+- `HeaderXProxyHTTPS`
+- `HeaderXProxySkipTLSVerify`
+- `HeaderXProxyResponseHeaderTimeout`
+
+## Usage Example
+
+```go
+// Reading configuration from incoming request headers
+func handleRequest(w http.ResponseWriter, r *http.Request) {
+    cfg, err := agentproxy.ConfigFromHeaders(r.Header)
+    if err != nil {
+        http.Error(w, "Invalid proxy config", http.StatusBadRequest)
+        return
+    }
+
+    // Use cfg.Scheme and cfg.Host to proxy the request
+    // ...
+}
+```
+
+## Integration
+
+This package is used by `agent/pkg/handler/proxy_http.go` to configure reverse proxy connections based on request headers.
--- a/agent/pkg/certs/README.md
+++ b/agent/pkg/certs/README.md
@@ -0,0 +1,131 @@
+# agent/pkg/certs
+
+Certificate management package for creating and extracting certificate archives.
+
+## Overview
+
+This package provides utilities for packaging SSL certificates into ZIP archives and extracting them. It is used by the GoDoxy Agent to distribute certificates to clients in a convenient format.
+
+## Architecture
+
+```mermaid
+graph LR
+    A[Raw Certs] --> B[ZipCert]
+    B --> C[ZIP Archive]
+    C --> D[ca.pem]
+    C --> E[cert.pem]
+    C --> F[key.pem]
+
+    G[ZIP Archive] --> H[ExtractCert]
+    H --> I[ca, crt, key]
+```
+
+## Public Functions
+
+### ZipCert
+
+```go
+func ZipCert(ca, crt, key []byte) ([]byte, error)
+```
+
+Creates a ZIP archive containing three PEM files:
+
+- `ca.pem` - CA certificate
+- `cert.pem` - Server/client certificate
+- `key.pem` - Private key
+
+**Parameters:**
+
+- `ca` - CA certificate in PEM format
+- `crt` - Certificate in PEM format
+- `key` - Private key in PEM format
+
+**Returns:**
+
+- ZIP archive bytes
+- Error if packing fails
+
+### ExtractCert
+
+```go
+func ExtractCert(data []byte) (ca, crt, key []byte, err error)
+```
+
+Extracts certificates from a ZIP archive created by `ZipCert`.
+
+**Parameters:**
+
+- `data` - ZIP archive bytes
+
+**Returns:**
+
+- `ca` - CA certificate bytes
+- `crt` - Certificate bytes
+- `key` - Private key bytes
+- Error if extraction fails
+
+### AgentCertsFilepath
+
+```go
+func AgentCertsFilepath(host string) (filepathOut string, ok bool)
+```
+
+Generates the file path for storing agent certificates.
+
+**Parameters:**
+
+- `host` - Agent hostname
+
+**Returns:**
+
+- Full file path within `certs/` directory
+- `false` if host is invalid (contains path separators or special characters)
+
+### isValidAgentHost
+
+```go
+func isValidAgentHost(host string) bool
+```
+
+Validates that a host string is safe for use in file paths.
+
+## Constants
+
+```go
+const AgentCertsBasePath = "certs"
+```
+
+Base directory for storing certificate archives.
+
+```go
+package main
+
+import (
+    "os"
+    "github.com/yusing/godoxy/agent/pkg/certs"
+)
+
+func main() {
+    // Read certificate files
+    caData, _ := os.ReadFile("ca.pem")
+    certData, _ := os.ReadFile("cert.pem")
+    keyData, _ := os.ReadFile("key.pem")
+
+    // Create ZIP archive
+    zipData, err := certs.ZipCert(caData, certData, keyData)
+    if err != nil {
+        panic(err)
+    }
+
+    // Save to file
+    os.WriteFile("agent-certs.zip", zipData, 0644)
+
+    // Extract from archive
+    ca, crt, key, err := certs.ExtractCert(zipData)
+    // ...
+}
+```
+
+## File Format
+
+The ZIP archive uses `zip.Store` compression (no compression) for fast creation and extraction. Each file is stored with its standard name (`ca.pem`, `cert.pem`, `key.pem`).
--- a/agent/pkg/env/README.md
+++ b/agent/pkg/env/README.md
@@ -0,0 +1,52 @@
+# agent/pkg/env
+
+Environment configuration package for the GoDoxy Agent.
+
+## Overview
+
+This package manages environment variable parsing and provides a centralized location for all agent configuration options. It is automatically initialized on import.
+
+## Variables
+
+| Variable                   | Type             | Default                | Description                             |
+| -------------------------- | ---------------- | ---------------------- | --------------------------------------- |
+| `DockerSocket`             | string           | `/var/run/docker.sock` | Path to Docker socket                   |
+| `AgentName`                | string           | System hostname        | Agent identifier                        |
+| `AgentPort`                | int              | `8890`                 | Agent server port                       |
+| `AgentSkipClientCertCheck` | bool             | `false`                | Skip mTLS certificate verification      |
+| `AgentCACert`              | string           | (empty)                | Base64 Encoded CA certificate + key     |
+| `AgentSSLCert`             | string           | (empty)                | Base64 Encoded server certificate + key |
+| `Runtime`                  | ContainerRuntime | `docker`               | Container runtime (docker or podman)    |
+
+## ContainerRuntime Type
+
+```go
+type ContainerRuntime string
+
+const (
+    ContainerRuntimeDocker  ContainerRuntime = "docker"
+    ContainerRuntimePodman  ContainerRuntime = "podman"
+)
+```
+
+## Public Functions
+
+### DefaultAgentName
+
+```go
+func DefaultAgentName() string
+```
+
+Returns the system hostname as the default agent name. Falls back to `"agent"` if hostname cannot be determined.
+
+### Load
+
+```go
+func Load()
+```
+
+Reloads all environment variables from the environment. Called automatically on package init, but can be called again to refresh configuration.
+
+## Validation
+
+The `Load()` function validates that `Runtime` is either `docker` or `podman`. An invalid runtime causes a fatal error.
--- a/agent/pkg/handler/README.md
+++ b/agent/pkg/handler/README.md
@@ -0,0 +1,127 @@
+# agent/pkg/handler
+
+HTTP request handler package for the GoDoxy Agent.
+
+## Overview
+
+This package provides the HTTP handler for the GoDoxy Agent server, including endpoints for:
+
+- Version information
+- Agent name and runtime
+- Health checks
+- System metrics (via SSE)
+- HTTP proxy routing
+- Docker socket proxying
+
+## Architecture
+
+```mermaid
+graph TD
+    A[HTTP Request] --> B[NewAgentHandler]
+    B --> C{ServeMux Router}
+
+    C --> D[GET /version]
+    C --> E[GET /name]
+    C --> F[GET /runtime]
+    C --> G[GET /health]
+    C --> H[GET /system-info]
+    C --> I[GET /proxy/http/#123;path...#125;]
+    C --> J[ /#42; Docker Socket]
+
+    H --> K[Gin Router]
+    K --> L[WebSocket Upgrade]
+    L --> M[SystemInfo Poller]
+```
+
+## Public Types
+
+### ServeMux
+
+```go
+type ServeMux struct{ *http.ServeMux }
+```
+
+Wrapper around `http.ServeMux` with agent-specific endpoint helpers.
+
+**Methods:**
+
+- `HandleEndpoint(method, endpoint string, handler http.HandlerFunc)` - Registers handler with API base path
+- `HandleFunc(endpoint string, handler http.HandlerFunc)` - Registers GET handler with API base path
+
+## Public Functions
+
+### NewAgentHandler
+
+```go
+func NewAgentHandler() http.Handler
+```
+
+Creates and configures the HTTP handler for the agent server. Sets up:
+
+- Gin-based metrics handler with WebSocket support for SSE
+- All standard agent endpoints
+- HTTP proxy endpoint
+- Docker socket proxy fallback
+
+## Endpoints
+
+| Endpoint                | Method   | Description                          |
+| ----------------------- | -------- | ------------------------------------ |
+| `/version`              | GET      | Returns agent version                |
+| `/name`                 | GET      | Returns agent name                   |
+| `/runtime`              | GET      | Returns container runtime            |
+| `/health`               | GET      | Health check with scheme query param |
+| `/system-info`          | GET      | System metrics via SSE or WebSocket  |
+| `/proxy/http/{path...}` | GET/POST | HTTP proxy with config from headers  |
+| `/*`                    | \*       | Docker socket proxy                  |
+
+## Sub-packages
+
+### proxy_http.go
+
+Handles HTTP proxy requests by reading configuration from request headers and proxying to the configured upstream.
+
+**Key Function:**
+
+- `ProxyHTTP(w, r)` - Proxies HTTP requests based on `X-Proxy-*` headers
+
+### check_health.go
+
+Handles health check requests for various schemes.
+
+**Key Function:**
+
+- `CheckHealth(w, r)` - Performs health checks with configurable scheme
+
+**Supported Schemes:**
+
+- `http`, `https` - HTTP health check
+- `h2c` - HTTP/2 cleartext health check
+- `tcp`, `udp`, `tcp4`, `udp4`, `tcp6`, `udp6` - TCP/UDP health check
+- `fileserver` - File existence check
+
+## Usage Example
+
+```go
+package main
+
+import (
+    "net/http"
+    "github.com/yusing/godoxy/agent/pkg/handler"
+)
+
+func main() {
+    mux := http.NewServeMux()
+    mux.Handle("/", handler.NewAgentHandler())
+
+    http.ListenAndServe(":8890", mux)
+}
+```
+
+## WebSocket Support
+
+The handler includes a permissive WebSocket upgrader for internal use (no origin check). This enables real-time system metrics streaming via Server-Sent Events (SSE).
+
+## Docker Socket Integration
+
+All unmatched requests fall through to the Docker socket handler, allowing the agent to proxy Docker API calls when configured.