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

2026-03-23 09:31:02 +01:00 · 2026-01-08 23:39:19 +08:00
parent 13441286d1
commit e9d7edef12
54 changed files with 13431 additions and 1519 deletions
--- a/socket-proxy/pkg/README.md
+++ b/socket-proxy/pkg/README.md
@@ -0,0 +1,100 @@
+# socket-proxy/pkg
+
+Core package for the Docker Socket Proxy, providing secure access to the Docker API with endpoint filtering and access control.
+
+## Overview
+
+This package implements a secure proxy that controls access to Docker socket API endpoints. It supports fine-grained permissions for different Docker operations and can restrict HTTP methods (GET-only or GET+POST).
+
+## Architecture
+
+```mermaid
+graph TD
+    A[HTTP Request] --> B[NewHandler Router]
+    B --> C{Method Allowed?}
+    C -->|No| D[405 Method Not Allowed]
+    C -->|Yes| E{Path Allowed?}
+    E -->|No| F[403 Forbidden]
+    E -->|Yes| G[Docker Socket Handler]
+    G --> H[Reverse Proxy]
+    H --> I[Docker Daemon]
+```
+
+## Core Components
+
+### Environment Configuration (`env.go`)
+
+Global configuration flags loaded from environment variables:
+
+| Variable           | Type   | Default                | Description                 |
+| ------------------ | ------ | ---------------------- | --------------------------- |
+| `DockerSocket`     | string | `/var/run/docker.sock` | Path to Docker socket       |
+| `ListenAddr`       | string | (empty)                | HTTP listen address         |
+| `DockerPost`       | bool   | `false`                | Allow POST methods          |
+| `DockerRestarts`   | bool   | `false`                | Allow container restarts    |
+| `DockerStart`      | bool   | `false`                | Allow container starts      |
+| `DockerStop`       | bool   | `false`                | Allow container stops       |
+| `DockerAuth`       | bool   | `false`                | Allow /auth endpoints       |
+| `DockerBuild`      | bool   | `false`                | Allow /build endpoints      |
+| `DockerCommit`     | bool   | `false`                | Allow /commit endpoints     |
+| `DockerContainers` | bool   | `false`                | Allow /containers endpoints |
+| `DockerEvents`     | bool   | `true`                 | Allow /events endpoints     |
+| `DockerExec`       | bool   | `false`                | Allow /exec endpoints       |
+| `DockerImages`     | bool   | `false`                | Allow /images endpoints     |
+| `DockerInfo`       | bool   | `false`                | Allow /info endpoints       |
+| `DockerNetworks`   | bool   | `false`                | Allow /networks endpoints   |
+| `DockerPing`       | bool   | `true`                 | Allow /\_ping endpoints     |
+| `DockerServices`   | bool   | `false`                | Allow /services endpoints   |
+| `DockerSystem`     | bool   | `false`                | Allow /system endpoints     |
+| `DockerVersion`    | bool   | `true`                 | Allow /version endpoints    |
+| `DockerVolumes`    | bool   | `false`                | Allow /volumes endpoints    |
+
+### Request Handler (`handler.go`)
+
+The `NewHandler()` function creates an HTTP router with:
+
+- Path-based access control (allowed/denied paths)
+- HTTP method filtering (GET-only or GET+POST)
+- Version prefix support (e.g., `/v1.41/containers`)
+- Unix domain socket proxying
+
+### Reverse Proxy (`reverseproxy/reverse_proxy.go`)
+
+Based on Go's standard library reverse proxy with enhancements:
+
+- Hop-by-hop header removal
+- WebSocket/h2c upgrade handling
+- Trailer support
+- Context-aware request cancellation
+
+## Usage Example
+
+```go
+package main
+
+import (
+    "log"
+    "net/http"
+    socketproxy "github.com/yusing/godoxy/socketproxy/pkg"
+)
+
+func main() {
+    // Configuration is loaded from environment variables
+    if socketproxy.ListenAddr == "" {
+        log.Fatal("Docker socket address is not set")
+    }
+    log.Printf("Docker socket listening on: %s", socketproxy.ListenAddr)
+    http.ListenAndServe(socketproxy.ListenAddr, socketproxy.NewHandler())
+}
+```
+
+## Security Features
+
+1. **Endpoint Whitelisting**: Only explicitly allowed endpoints are accessible
+1. **Method Restrictions**: Can restrict to GET-only or allow POST
+1. **Connection Keep-Alive**: Maintains persistent connections to Docker socket
+1. **Header Filtering**: Removes hop-by-hop headers to prevent spoofing
+
+## Docker Integration
+
+The proxy connects to the Docker daemon via Unix socket and proxies all allowed requests. The Docker API version prefix is handled automatically for backward compatibility.