license: Add MIT license
This commit is contained in:
Björn Benouarets
@@ -5,40 +5,40 @@
|
||||
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 │
|
||||
└─────────────────────────┬───────────────────────────────────┘
|
||||
┌────────────────────────────────────────────────────────────┐
|
||||
│ Client Request │
|
||||
└─────────────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Gateway (chi Router) │
|
||||
┌────────────────────────────────────────────────────────────┐
|
||||
│ Gateway (chi Router) │
|
||||
│ ┌──────────────────────────────────────────────────────┐ │
|
||||
│ │ Middleware Pipeline │ │
|
||||
│ │ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │ │
|
||||
│ │ │ Request ID │→ │ Real IP │→ │ Logger │ │ │
|
||||
│ │ └────────────┘ └────────────┘ └──────────────┘ │ │
|
||||
│ │ Global Middleware Pipeline │ │
|
||||
│ │ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │ │
|
||||
│ │ │ Request ID │→ │ Real IP │→ │ Logger │ │ │
|
||||
│ │ └────────────┘ └────────────┘ └──────────────┘ │ │
|
||||
│ └──────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────┬───────────────────────────────────┘
|
||||
└─────────────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Route Handler │
|
||||
┌────────────────────────────────────────────────────────────┐
|
||||
│ Route Handler │
|
||||
│ ┌──────────────────────────────────────────────────────┐ │
|
||||
│ │ Per-Route Middleware Chain │ │
|
||||
│ │ ┌────────────┐ ┌─────────┐ ┌──────────────┐ │ │
|
||||
│ │ │ Strip │→ │ WAF │→ │ Auth │ │ │
|
||||
│ │ │ Prefix │ │ Filter │ │ Middleware │ │ │
|
||||
│ │ └────────────┘ └─────────┘ └──────────────┘ │ │
|
||||
│ │ Per-Route Middleware Chain │ │
|
||||
│ │ ┌────────────┐ ┌──────────────┐ │ │
|
||||
│ │ │ Strip │→ │ Reverse │ │ │
|
||||
│ │ │ Prefix │ │ Proxy │ │ │
|
||||
│ │ └────────────┘ └──────────────┘ │ │
|
||||
│ └──────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────┬───────────────────────────────────┘
|
||||
└─────────────────────────┬──────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Reverse Proxy (httputil.ReverseProxy) │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ Backend Service │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
┌────────────────────────────────────────────────────────────┐
|
||||
│ Reverse Proxy (httputil.ReverseProxy) │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ Backend Service │
|
||||
└────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Component Architecture
|
||||
@@ -51,18 +51,17 @@ app/
|
||||
├── config/ # Configuration management
|
||||
│ ├── config.go # Config interface
|
||||
│ ├── file.go # File-based config loader
|
||||
│ └── types.go # Configuration type definitions
|
||||
│ └── database.go # Database configuration
|
||||
├── server/ # Core server components
|
||||
│ ├── gateway.go # Main gateway server
|
||||
│ ├── routes.go # Route handler creation
|
||||
│ └── proxy.go # Host-based virtual hosting
|
||||
│ ├── routes.go # Route registration
|
||||
│ ├── api.go # API definitions
|
||||
│ ├── host.go # Host definitions
|
||||
│ └── target.go # Target (backend) definitions
|
||||
├── 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
|
||||
│ ├── host.go # Host logging middleware
|
||||
│ └── logger.go # Structured logging middleware
|
||||
└── utils/ # Utility functions
|
||||
```
|
||||
|
||||
### Core Components
|
||||
@@ -71,25 +70,39 @@ app/
|
||||
|
||||
The Gateway is the main server component that:
|
||||
- Initializes the chi router
|
||||
- Applies global middleware (request_id, real_ip, logger)
|
||||
- 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 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
|
||||
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
|
||||
|
||||
#### Configuration (`config/`)
|
||||
#### API (`server/api.go`)
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
@@ -100,56 +113,56 @@ 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 |
|
||||
| `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:
|
||||
Applied 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
|
||||
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
|
||||
|
||||
## 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()`
|
||||
1. Load `gateway.yaml` via `config.NewFile()`
|
||||
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
|
||||
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"
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user