156 lines
7.8 KiB
Markdown
156 lines
7.8 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) │
|
|
│ ┌──────────────────────────────────────────────────────┐ │
|
|
│ │ Middleware Pipeline │ │
|
|
│ │ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │ │
|
|
│ │ │ Request ID │→ │ Real IP │→ │ Logger │ │ │
|
|
│ │ └────────────┘ └────────────┘ └──────────────┘ │ │
|
|
│ └──────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────┬───────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Route Handler │
|
|
│ ┌──────────────────────────────────────────────────────┐ │
|
|
│ │ Per-Route Middleware Chain │ │
|
|
│ │ ┌────────────┐ ┌─────────┐ ┌──────────────┐ │ │
|
|
│ │ │ Strip │→ │ WAF │→ │ Auth │ │ │
|
|
│ │ │ Prefix │ │ Filter │ │ Middleware │ │ │
|
|
│ │ └────────────┘ └─────────┘ └──────────────┘ │ │
|
|
│ └──────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────┬───────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 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
|
|
│ └── types.go # Configuration type definitions
|
|
├── server/ # Core server components
|
|
│ ├── gateway.go # Main gateway server
|
|
│ ├── routes.go # Route handler creation
|
|
│ └── proxy.go # Host-based virtual hosting
|
|
├── middlewares/ # HTTP middleware
|
|
│ ├── auth.go # Authentication middleware
|
|
│ └── waf.go # Web Application Firewall
|
|
├── handlers/ # Request handlers
|
|
│ └── route.go # Route handlers (placeholder)
|
|
└── res/ # HTTP responses
|
|
└── error.go # Error response utilities
|
|
```
|
|
|
|
### 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)
|
|
- Registers route handlers
|
|
- Starts the HTTP server
|
|
|
|
#### Routes (`server/routes.go`)
|
|
|
|
The Routes component creates handlers for each configured route:
|
|
1. Finds the matching API backend target
|
|
2. Creates a reverse proxy using `httputil.NewSingleHostReverseProxy`
|
|
3. Optionally strips prefix from the request path
|
|
4. Applies middleware chain: WAF → Auth
|
|
|
|
#### Configuration (`config/`)
|
|
|
|
Configuration is loaded from YAML and provides:
|
|
- Gateway settings (host, port, features)
|
|
- Route definitions with security policies
|
|
- API backend targets
|
|
- Proxy configurations for virtual hosting
|
|
|
|
## 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 |
|
|
| `logger` | Logs HTTP requests |
|
|
|
|
### Per-Route Middleware
|
|
|
|
Applied in order to each route handler:
|
|
|
|
1. **StripPrefix** - Removes specified prefix from request path before proxying
|
|
2. **WAF** - Filters requests based on HTTP method
|
|
3. **Auth** - Validates authentication credentials
|
|
|
|
## Request Flow
|
|
|
|
1. **Client Request** → Gateway receives HTTP request
|
|
2. **Global Middleware** → Request ID, Real IP, Logging applied
|
|
3. **Route Matching** → Chi matches route pattern (e.g., `/api/v1/dev/*`)
|
|
4. **Per-Route Middleware** → StripPrefix → WAF → Auth
|
|
5. **Reverse Proxy** → Request forwarded to backend API
|
|
6. **Response** → Backend response returned to client
|
|
|
|
## Authentication Flow
|
|
|
|
The authentication middleware supports path-based filtering:
|
|
|
|
```
|
|
┌─────────────────────┐
|
|
│ Include Set? │
|
|
└──────────┬──────────┘
|
|
│
|
|
┌─────┴─────┐
|
|
│ Yes │ No
|
|
▼ ▼
|
|
┌─────────┐ ┌─────────────┐
|
|
│ Match │ │ Exclude │
|
|
│ Include?│ │ Set? │
|
|
└────┬────┘ └──────┬──────┘
|
|
│ │
|
|
┌──┴──┐ ┌──┴──┐
|
|
│Yes │No │Yes │No
|
|
▼ ▼ ▼ ▼
|
|
┌────┐┌────┐ ┌────┐┌────┐
|
|
│Auth││Skip│ │Skip││Auth│
|
|
└────┘└────┘ └────┘└────┘
|
|
```
|
|
|
|
## Configuration Flow
|
|
|
|
1. Load `gateway.yaml` via `config.NewFileConfig()`
|
|
2. Parse YAML into `Configuration` struct
|
|
3. Create Gateway with configuration
|
|
4. Create Routes from route definitions and API targets
|
|
5. Register handlers with chi router
|
|
6. Start HTTP server
|