license: Add MIT license
This commit is contained in:
Björn Benouarets
@@ -12,33 +12,30 @@ gateway:
|
||||
- request_id
|
||||
- real_ip
|
||||
- logger
|
||||
- host
|
||||
|
||||
proxies:
|
||||
- id: "proxy-id"
|
||||
host: "example.com"
|
||||
target: "http://backend:3000"
|
||||
hosts:
|
||||
- id: "host-001"
|
||||
name: "localhost"
|
||||
domain: "localhost:8080"
|
||||
|
||||
targets:
|
||||
- id: "target-001"
|
||||
name: "httpbin"
|
||||
url: "https://httpbin.org"
|
||||
|
||||
apis:
|
||||
- id: "api-id"
|
||||
target: "https://api.example.com"
|
||||
- id: "api-001"
|
||||
host: "host-001"
|
||||
target: "target-001"
|
||||
|
||||
routes:
|
||||
- id: "route-id"
|
||||
- id: "route-001"
|
||||
api: "api-001"
|
||||
path: "/api/v1/*"
|
||||
strip_prefix:
|
||||
enabled: true
|
||||
prefix: "/api/v1"
|
||||
security:
|
||||
auth:
|
||||
enabled: true
|
||||
type: "api_key"
|
||||
header: "X-Api-Key"
|
||||
path:
|
||||
include: []
|
||||
exclude: []
|
||||
waf:
|
||||
enabled: true
|
||||
methods: ["GET", "POST"]
|
||||
```
|
||||
|
||||
## Sections
|
||||
@@ -61,37 +58,49 @@ Available global features:
|
||||
|---------|-------------|
|
||||
| `request_id` | Adds unique request ID to each request |
|
||||
| `real_ip` | Determines real client IP from headers |
|
||||
| `logger` | Logs all HTTP requests |
|
||||
| `logger` | Logs all HTTP requests with structured JSON |
|
||||
| `host` | Logs the host header for each request |
|
||||
|
||||
### Proxies
|
||||
### Hosts
|
||||
|
||||
Virtual hosting configuration for host-based routing.
|
||||
Virtual hosting configuration for domain-based routing.
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | string | Unique proxy identifier |
|
||||
| `host` | string | Domain/host name to match |
|
||||
| `target` | string | Backend URL to proxy to |
|
||||
| `id` | string | Unique host identifier (referenced by APIs) |
|
||||
| `name` | string | Human-readable name |
|
||||
| `domain` | string | Domain/host name to match |
|
||||
|
||||
### Targets
|
||||
|
||||
Backend service definitions referenced by APIs.
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | string | Unique target identifier (referenced by APIs) |
|
||||
| `name` | string | Human-readable name |
|
||||
| `url` | string | Backend URL to proxy to |
|
||||
|
||||
### APIs
|
||||
|
||||
Backend service definitions referenced by routes.
|
||||
Links hosts to backend targets.
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | string | Unique API identifier (referenced by routes) |
|
||||
| `target` | string | Backend URL |
|
||||
| `host` | string | Host ID to use |
|
||||
| `target` | string | Target ID to proxy to |
|
||||
|
||||
### Routes
|
||||
|
||||
Route definitions with security policies.
|
||||
Route definitions with path patterns and prefix stripping.
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `id` | string | Unique route identifier (must match API ID) |
|
||||
| `id` | string | Unique route identifier |
|
||||
| `api` | string | API ID to use for this route |
|
||||
| `path` | string | Chi route pattern (e.g., `/api/v1/*`) |
|
||||
| `strip_prefix` | object | Prefix stripping configuration |
|
||||
| `security` | object | Security policies (auth, WAF) |
|
||||
|
||||
#### Strip Prefix
|
||||
|
||||
@@ -100,91 +109,112 @@ Route definitions with security policies.
|
||||
| `enabled` | boolean | Enable prefix stripping |
|
||||
| `prefix` | string | Prefix to remove from path |
|
||||
|
||||
#### Security
|
||||
|
||||
##### Authentication
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `enabled` | boolean | Enable authentication |
|
||||
| `type` | string | Auth type (`api_key`, `session`, etc.) |
|
||||
| `header` | string | Header name to validate |
|
||||
| `path` | object | Path-based filtering |
|
||||
|
||||
##### Auth Path Filtering
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `include` | array | Paths that require auth (empty = all) |
|
||||
| `exclude` | array | Paths that skip auth |
|
||||
|
||||
**Include/Exclude Logic:**
|
||||
- If `include` is set → only matching paths require auth
|
||||
- If `include` is empty → all paths require auth except `exclude`
|
||||
|
||||
Wildcards (`*`) are supported in path patterns.
|
||||
|
||||
##### WAF (Web Application Firewall)
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `enabled` | boolean | Enable WAF |
|
||||
| `methods` | array | Allowed HTTP methods (`["*"]` for all) |
|
||||
|
||||
## Example Configurations
|
||||
|
||||
### Public API (No Auth)
|
||||
### Simple Proxy (No Prefix Stripping)
|
||||
|
||||
```yaml
|
||||
gateway:
|
||||
host: "0.0.0.0"
|
||||
port: 8080
|
||||
features:
|
||||
- logger
|
||||
|
||||
hosts:
|
||||
- id: "host-001"
|
||||
name: "localhost"
|
||||
domain: "localhost:8080"
|
||||
|
||||
targets:
|
||||
- id: "target-001"
|
||||
name: "backend"
|
||||
url: "https://api.example.com"
|
||||
|
||||
apis:
|
||||
- id: "api-001"
|
||||
host: "host-001"
|
||||
target: "target-001"
|
||||
|
||||
routes:
|
||||
- id: "public-api"
|
||||
path: "/public/*"
|
||||
strip_prefix:
|
||||
enabled: true
|
||||
prefix: "/public"
|
||||
security:
|
||||
auth:
|
||||
enabled: false
|
||||
waf:
|
||||
enabled: true
|
||||
methods: ["GET", "POST"]
|
||||
- id: "route-001"
|
||||
api: "api-001"
|
||||
path: "/api/*"
|
||||
```
|
||||
|
||||
### Protected API with API Key
|
||||
**Request flow:**
|
||||
- Client requests: `/api/users/123`
|
||||
- Backend receives: `/api/users/123`
|
||||
|
||||
### Prefix Stripping
|
||||
|
||||
```yaml
|
||||
routes:
|
||||
- id: "protected-api"
|
||||
- id: "route-001"
|
||||
api: "api-001"
|
||||
path: "/api/v1/*"
|
||||
strip_prefix:
|
||||
enabled: true
|
||||
prefix: "/api/v1"
|
||||
security:
|
||||
auth:
|
||||
enabled: true
|
||||
type: "api_key"
|
||||
header: "X-Api-Key"
|
||||
waf:
|
||||
enabled: true
|
||||
methods: ["*"]
|
||||
```
|
||||
|
||||
### Mixed Auth (Path-based)
|
||||
**Request flow:**
|
||||
- Client requests: `/api/v1/users/123`
|
||||
- Gateway strips: `/api/v1`
|
||||
- Backend receives: `/users/123`
|
||||
|
||||
### Multiple Routes
|
||||
|
||||
```yaml
|
||||
routes:
|
||||
- id: "mixed-api"
|
||||
- id: "public-route"
|
||||
api: "api-001"
|
||||
path: "/public/*"
|
||||
strip_prefix:
|
||||
enabled: true
|
||||
prefix: "/public"
|
||||
|
||||
- id: "api-route"
|
||||
api: "api-001"
|
||||
path: "/api/v1/*"
|
||||
strip_prefix:
|
||||
enabled: true
|
||||
prefix: "/api/v1"
|
||||
```
|
||||
|
||||
### Multiple Backends
|
||||
|
||||
```yaml
|
||||
hosts:
|
||||
- id: "host-001"
|
||||
name: "api-host"
|
||||
domain: "api.example.com"
|
||||
- id: "host-002"
|
||||
name: "admin-host"
|
||||
domain: "admin.example.com"
|
||||
|
||||
targets:
|
||||
- id: "target-001"
|
||||
name: "api-backend"
|
||||
url: "https://api-backend.internal"
|
||||
- id: "target-002"
|
||||
name: "admin-backend"
|
||||
url: "https://admin-backend.internal"
|
||||
|
||||
apis:
|
||||
- id: "api-001"
|
||||
host: "host-001"
|
||||
target: "target-001"
|
||||
- id: "api-002"
|
||||
host: "host-002"
|
||||
target: "target-002"
|
||||
|
||||
routes:
|
||||
- id: "route-001"
|
||||
api: "api-001"
|
||||
path: "/api/*"
|
||||
security:
|
||||
auth:
|
||||
enabled: true
|
||||
header: "Authorization"
|
||||
path:
|
||||
include: ["/api/admin/*", "/api/users/*/profile"]
|
||||
exclude: ["/api/health", "/api/public/*"]
|
||||
waf:
|
||||
enabled: true
|
||||
methods: ["*"]
|
||||
- id: "route-002"
|
||||
api: "api-002"
|
||||
path: "/admin/*"
|
||||
```
|
||||
|
||||
## Configuration Loading
|
||||
@@ -192,7 +222,7 @@ routes:
|
||||
The gateway loads configuration from a file path relative to the binary:
|
||||
|
||||
```go
|
||||
cfg, err := config.NewFileConfig("../gateway.yaml")
|
||||
cfg, err := config.NewFile("../gateway.yaml")
|
||||
```
|
||||
|
||||
For Docker deployments, mount the config file:
|
||||
@@ -201,3 +231,16 @@ For Docker deployments, mount the config file:
|
||||
volumes:
|
||||
- ./gateway.yaml:/app/gateway.yaml:ro
|
||||
```
|
||||
|
||||
## Chi Route Patterns
|
||||
|
||||
The gateway uses chi/v5 routing patterns. Common patterns:
|
||||
|
||||
| Pattern | Matches | Example |
|
||||
|---------|---------|---------|
|
||||
| `/api/*` | `/api/` and any subpath | `/api/users`, `/api/users/123` |
|
||||
| `/api/v1/*` | `/api/v1/` and any subpath | `/api/v1/users` |
|
||||
| `/users/{id}` | `/users/` with any value | `/users/123` |
|
||||
| `/files/*` | `/files/` and any subpath | `/files/doc.pdf` |
|
||||
|
||||
Note: `/*` matches zero or more path segments.
|
||||
|
||||
Reference in New Issue
Block a user