init: Initial commit

2026-02-05 18:37:35 +01:00
commit 31f5b4081a
25 changed files with 1759 additions and 0 deletions
--- a/.docs/architecture.md
+++ b/.docs/architecture.md
@@ -0,0 +1,155 @@
+# 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