license: Add MIT license

2026-02-05 23:59:17 +01:00
parent 30adf0c701
commit 137be3e1e0
8 changed files with 611 additions and 295 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

 ## Project Overview

-SecNex API Gateway is a Go-based API gateway built with chi/v5 routing. It acts as a reverse proxy with configurable security features including authentication and WAF (Web Application Firewall) capabilities.
+SecNex API Gateway is a Go-based API gateway built with chi/v5 routing. It acts as a reverse proxy with configurable features including path-based routing, prefix stripping, and structured logging.

 ## Build and Run

@@ -23,77 +23,79 @@ The gateway loads configuration from `gateway.yaml` (sibling to the `app/` direc
 app/
 ├── main.go           # Entry point
 ├── config/           # Configuration loading and types
-├── server/           # Gateway, routes, and proxy setup
-├── middlewares/      # Auth and WAF middleware
-├── handlers/         # Route handlers (currently empty)
-└── res/              # HTTP error responses
+├── server/           # Gateway, routes, hosts, targets, and API definitions
+├── middlewares/      # HTTP middleware (logger, host)
+└── utils/            # Utility functions
 ```

 ### Core Components

 **Gateway (`server/gateway.go`)**
 - Main server using chi/v5 router
- Dynamically enables features via config: `request_id`, `real_ip`, `logger`
+- Dynamically enables features via config: `request_id`, `real_ip`, `logger`, `host`
+- Configures proxy directors for each API
 - Registers route handlers and starts HTTP server

 **Routes (`server/routes.go`)**
 - Creates handlers for each route configured in `gateway.yaml`
 - For each 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 WAF middleware (method filtering)
-  5. Applies Auth middleware (header-based authentication)
+  2. Creates a handler with optional strip prefix middleware
+  3. Registers with chi router using `r.Handle()` (method-agnostic)

-**Proxy (`server/proxy.go`)**
- Host-based virtual hosting proxy (separate from routes)
- Maps `proxy.host` to a backend target
- Currently unused in main.go but available
+**API (`server/api.go`)**
+- Links hosts to backend targets
+- Implements `http.Handler` interface
+- Delegates to the reverse proxy

-**Configuration Flow**
-1. `config.NewFileConfig("../gateway.yaml")` loads YAML
+**Hosts (`server/host.go`)**
+- Host definitions for virtual hosting
+- Domain-based routing support
+
+**Targets (`server/target.go`)**
+- Backend service definitions
+- Creates `httputil.NewSingleHostReverseProxy` instances
+
+### Configuration Flow
+
+1. `config.NewFile("../gateway.yaml")` loads YAML
 2. `server.NewGateway(cfg)` creates gateway with chi router
-3. `server.NewRoutes(cfg.GetRoutes(), cfg.GetApis())` creates handlers
-4. `gateway.SetRoutes(routes)` registers handlers
+3. `server.NewRoutes(cfg, apis)` creates route handlers
+4. `routes.Register(g.router)` registers handlers
+5. Gateway starts HTTP server

-### Middleware Chain (per route)
+### Middleware Chain

-Middlewares are applied in order via decorator pattern in `server/routes.go:createHandlers`:
-1. StripPrefix (if enabled) - removes prefix from path before proxying
-2. WAF - filters by HTTP method (or `["*"]` for all methods)
-3. Auth - validates presence of auth header
+**Global Middleware** (applied via chi middleware):
+1. RequestID - adds unique request ID
+2. RealIP - determines real client IP
+3. Logger - structured JSON logging
+4. Host - logs host header
+
+**Per-Route Middleware** (applied in order):
+1. StripPrefix - removes prefix from path before proxying (if enabled)

 ### Key Implementation Details

-**Auth Middleware** (`middlewares/auth.go`)
- Checks for presence of configured header (e.g., `X-Api-Key`, `Authorization`)
- Path-based filtering via `include`/`exclude` patterns:
-  - If `include` is set → only those paths require auth
-  - If `include` is empty → all paths require auth except `exclude` patterns
- Supports wildcard patterns (`*`) in path matching
- Deletes the auth header before forwarding to backend
-
-**WAF Configuration** (`middlewares/waf.go`)
- Currently only implements HTTP method filtering
- `methods: ["*"]` allows all methods
- `methods: ["GET"]` only allows GET
+**Strip Prefix Middleware** (`server/routes.go`)
+- Removes specified prefix from request path before proxying
+- Ensures resulting path starts with `/`

 **Route Handler Pattern**
 Each route in `gateway.yaml` must have:
- `id` - must match an API entry
- `path` - chi route pattern (e.g., `/api/v1/dev/*`)
+- `id` - unique route identifier
+- `api` - API ID to use (references an API entry)
+- `path` - chi route pattern (e.g., `/api/v1/*`)
 - `strip_prefix` - optional prefix removal
- `security.auth` - optional auth middleware
- `security.waf` - optional method filtering

 ### Module Structure

 The codebase uses an internal Go module:
 ```
-git.secnex.io/secnex/gateway
+git.secnex.io/secnex/api-gateway
 ```

-Internal imports use this path (e.g., `git.secnex.io/secnex/gateway/config`).
+Internal imports use this path (e.g., `git.secnex.io/secnex/api-gateway/config`).

 ### Logging

@@ -101,3 +103,48 @@ Uses `git.secnex.io/secnex/masterlog` with:
 - JSON encoder
 - Pseudonymizer for sensitive fields (`user_id`, `email`, `ip`)
 - Debug-level logging enabled in main.go
+- Custom `LoggerMiddleware` for structured HTTP request logging
+
+### Dependencies
+
+- `github.com/go-chi/chi/v5` - HTTP router
+- `git.secnex.io/secnex/masterlog` - Structured logging
+- `go.yaml.in/yaml/v3` - YAML configuration parsing
+- `gorm.io/gorm` - Database ORM (for future use)
+- `gorm.io/driver/postgres` - PostgreSQL driver (for future use)
+
+## Configuration Reference
+
+```yaml
+gateway:
+  host: "0.0.0.0"
+  port: 8080
+  features:
+    - request_id
+    - real_ip
+    - logger
+    - host
+
+hosts:
+  - id: "host-001"
+    name: "localhost"
+    domain: "localhost:8080"
+
+targets:
+  - id: "target-001"
+    name: "httpbin"
+    url: "https://httpbin.org"
+
+apis:
+  - id: "api-001"
+    host: "host-001"
+    target: "target-001"
+
+routes:
+  - id: "route-001"
+    api: "api-001"
+    path: "/api/v1/*"
+    strip_prefix:
+      enabled: true
+      prefix: "/api/v1"
+```