243 lines
11 KiB
Markdown
243 lines
11 KiB
Markdown
# Architecture
|
|
|
|
## System Overview
|
|
|
|
The SecNex API Gateway follows a modular architecture with clear separation of concerns. The system is built using the chi/v5 HTTP router and implements a middleware pipeline pattern.
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────┐
|
|
│ Client Request │
|
|
└─────────────────────────┬──────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌────────────────────────────────────────────────────────────┐
|
|
│ Gateway (chi Router) │
|
|
│ ┌──────────────────────────────────────────────────────┐ │
|
|
│ │ Global Middleware Pipeline │ │
|
|
│ │ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │ │
|
|
│ │ │ Request ID │→ │ Real IP │→ │ Logger │ │ │
|
|
│ │ └────────────┘ └────────────┘ └──────────────┘ │ │
|
|
│ └──────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────┬──────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌────────────────────────────────────────────────────────────┐
|
|
│ Route Handler │
|
|
│ ┌──────────────────────────────────────────────────────┐ │
|
|
│ │ Per-Route Middleware Chain │ │
|
|
│ │ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │ │
|
|
│ │ │ Auth │→ │ Strip │→ │ Reverse │ │ │
|
|
│ │ │ Middleware │ │ Prefix │ │ Proxy │ │ │
|
|
│ │ └────────────┘ └────────────┘ └──────────────┘ │ │
|
|
│ └──────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────┬──────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌────────────────────────────────────────────────────────────┐
|
|
│ Reverse Proxy (httputil.ReverseProxy) │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ Backend Service │
|
|
└────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Component Architecture
|
|
|
|
### Directory Structure
|
|
|
|
```
|
|
app/
|
|
├── main.go # Application entry point
|
|
├── config/ # Configuration management
|
|
│ ├── config.go # Config interface
|
|
│ ├── file.go # File-based config loader
|
|
│ └── database.go # Database configuration
|
|
├── server/ # Core server components
|
|
│ ├── gateway.go # Main gateway server
|
|
│ ├── routes.go # Route registration & middleware chain
|
|
│ ├── api.go # API definitions
|
|
│ ├── host.go # Host definitions
|
|
│ └── target.go # Target (backend) definitions
|
|
├── middlewares/ # HTTP middleware
|
|
│ ├── auth.go # Authentication middleware
|
|
│ ├── host.go # Host logging middleware
|
|
│ └── logger.go # Structured logging middleware
|
|
└── utils/ # Utility functions
|
|
```
|
|
|
|
### Core Components
|
|
|
|
#### Gateway (`server/gateway.go`)
|
|
|
|
The Gateway is the main server component that:
|
|
- Initializes the chi router
|
|
- Applies global middleware (request_id, real_ip, logger, host)
|
|
- Configures proxy directors for each API
|
|
- Registers route handlers
|
|
- Starts the HTTP server
|
|
|
|
#### Routes (`server/routes.go`)
|
|
|
|
The Routes component handles:
|
|
- Creating route handlers from configuration
|
|
- Applying per-route middleware chain (Auth → StripPrefix)
|
|
- Registering routes with chi router (method-agnostic)
|
|
- Connecting routes to API backends
|
|
|
|
#### API (`server/api.go`)
|
|
|
|
API definitions that:
|
|
- Link hosts to backend targets
|
|
- Implement `http.Handler` interface for proxying
|
|
- Delegate requests to the reverse proxy
|
|
|
|
#### Hosts (`server/host.go`)
|
|
|
|
Host definitions for:
|
|
- Virtual hosting support
|
|
- Domain-based routing
|
|
- Host header validation
|
|
|
|
#### Targets (`server/target.go`)
|
|
|
|
Target (backend) definitions that:
|
|
- Store backend service URLs
|
|
- Create `httputil.NewSingleHostReverseProxy` instances
|
|
- Handle proxy configuration
|
|
|
|
#### Auth Middleware (`middlewares/auth.go`)
|
|
|
|
Authentication middleware that:
|
|
- Validates presence of configured auth header (e.g., `X-Api-Key`, `Authorization`)
|
|
- Supports path-based filtering via include/exclude patterns
|
|
- Removes auth header before forwarding to backend
|
|
- Provides extensive DEBUG logging for troubleshooting
|
|
|
|
## Middleware Chain
|
|
|
|
### Global Middleware
|
|
|
|
Applied to all requests via chi middleware:
|
|
|
|
| Feature | Description |
|
|
|---------|-------------|
|
|
| `request_id` | Adds unique request ID to context |
|
|
| `real_ip` | Determines the real client IP from headers |
|
|
| `logger` | Logs HTTP requests with structured JSON output |
|
|
| `host` | Logs the host header for each request |
|
|
|
|
### Per-Route Middleware
|
|
|
|
Applied in order to each route handler:
|
|
|
|
1. **Auth** (if enabled) - Validates authentication header with path filtering
|
|
2. **StripPrefix** (if enabled) - Removes specified prefix from request path before proxying
|
|
|
|
## Request Flow
|
|
|
|
1. **Client Request** → Gateway receives HTTP request
|
|
2. **Global Middleware** → Request ID, Real IP, Host logging, Logger applied
|
|
3. **Route Matching** → Chi matches route pattern (e.g., `/api/v1/*`)
|
|
4. **Per-Route Middleware** → Auth → StripPrefix (if enabled)
|
|
5. **Reverse Proxy** → Request forwarded to backend API
|
|
6. **Response** → Backend response returned to client
|
|
|
|
## Authentication Flow
|
|
|
|
The authentication middleware supports flexible path-based filtering:
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ Include and Exclude both empty? │
|
|
└──────────────────┬──────────────────┘
|
|
│ Yes
|
|
┌─────────┴─────────┐
|
|
│ Auth required │
|
|
│ for ALL paths │
|
|
└───────────────────┘
|
|
|
|
│ No
|
|
┌─────────┴─────────┐
|
|
▼ │
|
|
┌───────────────────┐ │
|
|
│ Only Include set? │ │
|
|
└─────────┬─────────┘ │
|
|
│ Yes │ No │
|
|
▼ ▼ │
|
|
┌────────┐ ┌────────────────┐│
|
|
│ Auth │ │ Exclude set? ││
|
|
│ ONLY │ └───────┬────────┘│
|
|
│ for │ │ No │
|
|
│ Include│ ┌────┴────┐ │
|
|
│ paths │ │ Auth │ │
|
|
└────────┘ │ for ALL │ │
|
|
└────┬────┘ │
|
|
│ Yes │
|
|
┌─────────┴─────────┐│
|
|
│ Auth EXCEPT ││
|
|
│ matching Exclude ││
|
|
└───────────────────┘│
|
|
│
|
|
▼
|
|
Check Auth Header
|
|
```
|
|
|
|
**Path Filtering Logic:**
|
|
1. **Both include and exclude empty** → Auth required for ALL paths
|
|
2. **Only include set** → Auth required ONLY for paths matching include patterns
|
|
3. **Only exclude set** → Auth required for ALL paths EXCEPT those matching exclude patterns
|
|
4. **Both set** → Include takes precedence (same as #2)
|
|
|
|
**Wildcard Pattern Matching:**
|
|
- `*` matches any path
|
|
- `/api/*` matches `/api/` and any subpath
|
|
- `/api/v1/public/test/*` matches the prefix and any subpath
|
|
|
|
## Configuration Flow
|
|
|
|
1. Load `gateway.yaml` via `config.NewFile()`
|
|
2. Parse YAML into `Configuration` struct
|
|
3. Create Hosts from configuration
|
|
4. Create Targets from configuration
|
|
5. Create APIs (linking Hosts to Targets)
|
|
6. Create Routes (linking Routes to APIs with Auth config)
|
|
7. Initialize Gateway with all components
|
|
8. Configure proxy directors
|
|
9. Register routes with chi router (including Auth middleware)
|
|
10. Start HTTP server
|
|
|
|
## Logging
|
|
|
|
The gateway uses structured JSON logging via `masterlog`:
|
|
|
|
- **HTTP Request Logging** - method, path, status, duration, host, IP
|
|
- **Gateway Events** - startup, route registration, proxy configuration
|
|
- **Auth Debug Logs** - detailed auth decision logging when DEBUG level enabled
|
|
- **Sensitive Field Pseudonymization** - user_id, email, ip fields are pseudonymized
|
|
|
|
Example log output:
|
|
```json
|
|
{
|
|
"level": "info",
|
|
"msg": "HTTP Request",
|
|
"method": "GET",
|
|
"path": "/api/v1/users",
|
|
"status": 200,
|
|
"duration": "45ms",
|
|
"host": "localhost:8080",
|
|
"ip": "127.0.0.1:52342"
|
|
}
|
|
```
|
|
|
|
Auth debug logs (when DEBUG level enabled):
|
|
```json
|
|
{
|
|
"level": "debug",
|
|
"msg": "AuthMiddleware: Checking if path requires auth",
|
|
"path": "/api/v1/users",
|
|
"requires_auth": true,
|
|
"include": [],
|
|
"exclude": ["/api/v1/public/*"]
|
|
}
|
|
```
|