169 lines
7.6 KiB
Markdown
169 lines
7.6 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 │ │
|
|
│ │ ┌────────────┐ ┌──────────────┐ │ │
|
|
│ │ │ Strip │→ │ Reverse │ │ │
|
|
│ │ │ 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
|
|
│ ├── api.go # API definitions
|
|
│ ├── host.go # Host definitions
|
|
│ └── target.go # Target (backend) definitions
|
|
├── middlewares/ # HTTP 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 strip prefix middleware
|
|
- 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.ReverseProxy` instances
|
|
- Handle proxy configuration
|
|
|
|
## 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 to each route handler:
|
|
|
|
1. **StripPrefix** - 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** → StripPrefix (if enabled)
|
|
5. **Reverse Proxy** → Request forwarded to backend API
|
|
6. **Response** → Backend response returned to client
|
|
|
|
## 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)
|
|
7. Initialize Gateway with all components
|
|
8. Configure proxy directors
|
|
9. Register routes with chi router
|
|
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
|
|
- **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"
|
|
}
|
|
```
|