feat(docs): add health check and monitor packages README; mermaid styling fix

2026-01-11 22:30:47 +01:00 · 2026-01-08 18:18:17 +08:00
parent 7556a06716
commit 86f35878fb
3 changed files with 248 additions and 17 deletions
--- a/internal/autocert/README.md
+++ b/internal/autocert/README.md
@@ -71,10 +71,10 @@ flowchart TD
    T --> V[Update SNI Matcher]
    V --> G

-    style E fill:#90EE90
-    style I fill:#FFD700
-    style N fill:#90EE90
-    style U fill:#FFA07A
+    style E fill:#22553F,color:#fff
+    style I fill:#8B8000,color:#fff
+    style N fill:#22553F,color:#fff
+    style U fill:#84261A,color:#fff
 ```

 ## SNI Matching Flow
@@ -97,9 +97,9 @@ flowchart LR
        F -->|No| G[Return default cert]
    end

-    style C fill:#90EE90
-    style E fill:#87CEEB
-    style F fill:#FFD700
+    style C fill:#27632A,color:#fff
+    style E fill:#18597A,color:#fff
+    style F fill:#836C03,color:#fff
 ```

 ### Suffix Tree Structure
@@ -280,7 +280,7 @@ autocert:
  email: admin@example.com
  domains:
    - example.com
-    - "*.example.com"
+    - '*.example.com'
  options:
    CF_API_TOKEN: your-api-token
    CF_ZONE_API_TOKEN: your-zone-token
@@ -334,13 +334,13 @@ autocert:
  email: admin@example.com
  domains:
    - example.com
-    - "*.example.com"
+    - '*.example.com'
  cert_path: certs/example.com.crt
  key_path: certs/example.com.key
  extra:
    - domains:
        - api.example.com
-        - "*.api.example.com"
+        - '*.api.example.com'
      cert_path: certs/api.example.com.crt
      key_path: certs/api.example.com.key
      provider: cloudflare
@@ -358,8 +358,8 @@ flowchart TD
    C --> D[Build SNI Matcher]
    D --> E[Register in SNI Tree]

-    style B fill:#87CEEB
-    style C fill:#FFD700
+    style B fill:#1a2639,color:#fff
+    style C fill:#423300,color:#fff
 ```

 ## Renewal Scheduling
@@ -406,10 +406,10 @@ flowchart TD

    N --> D

-    style F fill:#FFD700
-    style J fill:#FFD700
-    style K fill:#90EE90
-    style M fill:#FFA07A
+    style F fill:#423300,color:#fff
+    style J fill:#423300,color:#fff
+    style K fill:#174014,color:#fff
+    style M fill:#432829,color:#fff
 ```

 **Notifications:** Renewal success/failure triggers system notifications with provider name.
@@ -530,7 +530,7 @@ autocert:
  email: admin@example.com
  domains:
    - example.com
-    - "*.example.com"
+    - '*.example.com'
  options:
    CF_API_TOKEN: ${CF_API_TOKEN}
  resolvers:
--- a/internal/health/check/README.md
+++ b/internal/health/check/README.md
@@ -0,0 +1,198 @@
+# Health Check
+
+This package provides low-level health check implementations for different protocols and services in GoDoxy.
+
+## Health Check Types
+
+### Docker Health Check
+
+Checks the health status of Docker containers using the Docker API.
+
+**Flow:**
+
+```mermaid
+flowchart TD
+    A[Docker Health Check] --> B{Docker Failures > Threshold?}
+    B -->|yes| C[Return Error: Too Many Failures]
+    B -->|no| D[Container Inspect API Call]
+    D --> E{Inspect Successful?}
+    E -->|no| F[Increment Failure Count]
+    E -->|yes| G[Parse Container State]
+
+    G --> H{Container Status}
+    H -->|dead/exited/paused/restarting/removing| I[Unhealthy: Container State]
+    H -->|created| J[Unhealthy: Not Started]
+    H -->|running| K{Health Check Configured?}
+
+    K -->|no| L[Return Error: No Health Check]
+    K -->|yes| M[Check Health Status]
+    M --> N{Health Status}
+    N -->|healthy| O[Healthy]
+    N -->|unhealthy| P[Unhealthy: Last Log Output]
+
+    I --> Q[Reset Failure Count]
+    J --> Q
+    O --> Q
+    P --> Q
+```
+
+**Key Features:**
+
+- Intercepts Docker API responses to extract container state
+- Tracks failure count with configurable threshold (3 failures)
+- Supports containers with and without health check configurations
+- Returns detailed error information from Docker health check logs
+
+### HTTP Health Check
+
+Performs HTTP/HTTPS health checks using fasthttp for optimal performance.
+
+**Flow:**
+
+```mermaid
+flowchart TD
+    A[HTTP Health Check] --> B[Create FastHTTP Request]
+    B --> C[Set Headers and Method]
+    C --> D[Execute Request with Timeout]
+    D --> E{Request Successful?}
+
+    E -->|no| F{Error Type}
+    F -->|TLS Error| G[Healthy: TLS Error Ignored]
+    F -->|Other Error| H[Unhealthy: Error Details]
+
+    E -->|yes| I{Status Code}
+    I -->|5xx| J[Unhealthy: Server Error]
+    I -->|Other| K[Healthy]
+
+    G --> L[Return Result with Latency]
+    H --> L
+    J --> L
+    K --> L
+```
+
+**Key Features:**
+
+- Uses fasthttp for high-performance HTTP requests
+- Supports both GET and HEAD methods
+- Configurable timeout and path
+- Handles TLS certificate verification errors gracefully
+- Returns latency measurements
+
+### H2C Health Check
+
+Performs HTTP/2 cleartext (h2c) health checks for services that support HTTP/2 without TLS.
+
+**Flow:**
+
+```mermaid
+flowchart TD
+    A[H2C Health Check] --> B[Create HTTP/2 Transport]
+    B --> C[Set AllowHTTP: true]
+    C --> D[Create HTTP Request]
+    D --> E[Set Headers and Method]
+    E --> F[Execute Request with Timeout]
+    F --> G{Request Successful?}
+
+    G -->|no| H[Unhealthy: Error Details]
+    G -->|yes| I[Check Status Code]
+    I --> J{Status Code}
+    J -->|5xx| K[Unhealthy: Server Error]
+    J -->|Other| L[Healthy]
+
+    H --> M[Return Result with Latency]
+    K --> M
+    L --> M
+```
+
+**Key Features:**
+
+- Uses HTTP/2 transport with cleartext support
+- Supports both GET and HEAD methods
+- Configurable timeout and path
+- Returns latency measurements
+
+### FileServer Health Check
+
+Checks if a file server root directory exists and is accessible.
+
+**Flow:**
+
+```mermaid
+flowchart TD
+    A[FileServer Health Check] --> B[Start Timer]
+    B --> C[Stat Directory Path]
+    C --> D{Directory Exists?}
+
+    D -->|no| E[Unhealthy: Path Not Found]
+    D -->|yes| F[Healthy: Directory Accessible]
+    D -->|error| G[Return Error]
+
+    E --> H[Return Result with Latency]
+    F --> H
+    G --> I[Return Error]
+```
+
+**Key Features:**
+
+- Simple directory existence check
+- Measures latency of filesystem operation
+- Distinguishes between "not found" and other errors
+- Returns detailed error information
+
+### Stream Health Check
+
+Checks stream endpoint connectivity by attempting to establish a network connection.
+
+**Flow:**
+
+```mermaid
+flowchart TD
+    A[Stream Health Check] --> B[Create Dialer]
+    B --> C[Set Timeout and Fallback Delay]
+    C --> D[Start Timer]
+    D --> E[Dial Network Connection]
+    E --> F{Connection Successful?}
+
+    F -->|no| G{Error Type}
+    G -->|Connection Errors| H[Unhealthy: Connection Failed]
+    G -->|Other Error| I[Return Error]
+
+    F -->|yes| J[Close Connection]
+    J --> K[Healthy: Connection Established]
+
+    H --> L[Return Result with Latency]
+    K --> L
+```
+
+**Key Features:**
+
+- Generic network connection check
+- Supports any stream protocol (TCP, UDP, etc.)
+- Handles common connection errors gracefully
+- Measures connection establishment latency
+- Automatically closes connections
+
+## Common Features
+
+### Error Handling
+
+All health checks implement consistent error handling:
+
+- **Temporary Errors**: Network timeouts, connection failures
+- **Permanent Errors**: Invalid configurations, missing resources
+- **Graceful Degradation**: Returns health status even when errors occur
+
+### Performance Monitoring
+
+- **Latency Measurement**: All checks measure execution time
+- **Timeout Support**: Configurable timeouts prevent hanging
+- **Resource Cleanup**: Proper cleanup of connections and resources
+
+### Integration
+
+These health checks are used by the monitor package to implement route-specific health monitoring:
+
+- HTTP/HTTPS routes use HTTP health checks
+- File server routes use FileServer health checks
+- Stream routes use Stream health checks
+- Docker containers use Docker health checks with fallbacks
--- a/internal/health/monitor/README.md
+++ b/internal/health/monitor/README.md
@@ -0,0 +1,33 @@
+# Health Monitor
+
+This package provides health monitoring functionality for different types of routes in GoDoxy.
+
+## Health Check Flow
+
+```mermaid
+flowchart TD
+    A[NewMonitor route] --> B{IsAgent route}
+    B -->|true| C[NewAgentProxiedMonitor]
+    B -->|false| D{IsDocker route}
+    D -->|true| E[NewDockerHealthMonitor]
+    D -->|false| F[Route Type Switch]
+
+    F --> G[HTTP Monitor]
+    F --> H[FileServer Monitor]
+    F --> I[Stream Monitor]
+
+    E --> J[Selected Monitor]
+
+    C --> K[Agent Health Check]
+    G --> L{Scheme h2c?}
+    L -->|true| M[H2C Health Check]
+    L -->|false| N[HTTP Health Check]
+    H --> O[FileServer Health Check]
+    I --> P[Stream Health Check]
+
+    K --> Q{IsDocker route}
+    Q -->|true| R[NewDockerHealthMonitor with Agent as Fallback]
+    Q -->|false| K
+
+    R --> K
+```