mirror of
https://github.com/yusing/godoxy.git
synced 2026-03-20 16:23:53 +01:00
docs: add per package README for implementation details (AI generated with human review)
This commit is contained in:
yusing
100
socket-proxy/pkg/README.md
Normal file
100
socket-proxy/pkg/README.md
Normal file
@@ -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.
|
||||
73
socket-proxy/pkg/reverseproxy/README.md
Normal file
73
socket-proxy/pkg/reverseproxy/README.md
Normal file
@@ -0,0 +1,73 @@
|
||||
# Socket Proxy Reverse Proxy
|
||||
|
||||
This package provides an HTTP reverse proxy implementation for proxying requests to Unix sockets (typically Docker sockets). It is based on Go's `net/http/httputil.ReverseProxy` with simplifications for socket proxying use cases.
|
||||
|
||||
## Differences from `net/http/httputil.ReverseProxy`
|
||||
|
||||
| Feature | stdlib `httputil.ReverseProxy` | This package |
|
||||
| --------------------- | ------------------------------ | ----------------------------------- |
|
||||
| Request modification | `Director` or `Rewrite` | `Director` only |
|
||||
| Response modification | `ModifyResponse` hook | Not supported |
|
||||
| Buffering | Uses `io.Copy` | Uses `ioutils.CopyCloseWithContext` |
|
||||
| Flush support | `Flush()` method | Not exposed |
|
||||
|
||||
### Key Simplifications
|
||||
|
||||
1. **Director only**: Only the `Director` function is supported. The stdlib's `Rewrite` type and `ModifyResponse` hook are removed.
|
||||
|
||||
2. **Context-aware body copying**: Uses `ioutils.CopyCloseWithContext` which:
|
||||
|
||||
- Respects request context for cancellation
|
||||
- Uses `Content-Length` for optimal copying when available
|
||||
- Properly handles trailer headers
|
||||
|
||||
3. **No buffering**: Unlike the stdlib which can buffer responses, this implementation streams directly to the client.
|
||||
|
||||
## Usage
|
||||
|
||||
```go
|
||||
rp := &reverseproxy.ReverseProxy{
|
||||
Director: func(req *http.Request) {
|
||||
req.URL.Scheme = "http"
|
||||
req.URL.Host = "api.moby.localhost"
|
||||
req.RequestURI = req.URL.String()
|
||||
},
|
||||
Transport: &http.Transport{
|
||||
DialContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
|
||||
return net.DialTimeout("unix", "/var/run/docker.sock", 5*time.Second)
|
||||
},
|
||||
DisableCompression: true,
|
||||
},
|
||||
}
|
||||
|
||||
http.HandleFunc("/", rp.ServeHTTP)
|
||||
http.ListenAndServe(":2375", nil)
|
||||
```
|
||||
|
||||
## Socket Proxy Integration
|
||||
|
||||
The socket proxy uses this package in `socket-proxy/pkg/handler.go`:
|
||||
|
||||
```go
|
||||
func dockerSocketHandler(socket string) http.HandlerFunc {
|
||||
rp := &reverseproxy.ReverseProxy{
|
||||
Director: func(req *http.Request) {
|
||||
req.URL.Scheme = "http"
|
||||
req.URL.Host = "api.moby.localhost"
|
||||
req.RequestURI = req.URL.String()
|
||||
},
|
||||
Transport: &http.Transport{
|
||||
DialContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
|
||||
dialer := &net.Dialer{KeepAlive: 1 * time.Second}
|
||||
return dialer.DialContext(ctx, "unix", socket)
|
||||
},
|
||||
DisableCompression: true,
|
||||
},
|
||||
}
|
||||
return rp.ServeHTTP
|
||||
}
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
This code is based on Go's `net/http/httputil` and is licensed under the BSD-style license found at the top of `reverse_proxy.go`.
|
||||
Reference in New Issue
Block a user