104 lines
3.4 KiB
Markdown
104 lines
3.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## 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.
|
|
|
|
## Build and Run
|
|
|
|
```bash
|
|
cd app
|
|
go run main.go
|
|
```
|
|
|
|
The gateway loads configuration from `gateway.yaml` (sibling to the `app/` directory).
|
|
|
|
## Architecture
|
|
|
|
### Directory Structure
|
|
|
|
```
|
|
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
|
|
```
|
|
|
|
### Core Components
|
|
|
|
**Gateway (`server/gateway.go`)**
|
|
- Main server using chi/v5 router
|
|
- Dynamically enables features via config: `request_id`, `real_ip`, `logger`
|
|
- 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)
|
|
|
|
**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
|
|
|
|
**Configuration Flow**
|
|
1. `config.NewFileConfig("../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
|
|
|
|
### Middleware Chain (per route)
|
|
|
|
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
|
|
|
|
### 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
|
|
|
|
**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/*`)
|
|
- `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
|
|
```
|
|
|
|
Internal imports use this path (e.g., `git.secnex.io/secnex/gateway/config`).
|
|
|
|
### Logging
|
|
|
|
Uses `git.secnex.io/secnex/masterlog` with:
|
|
- JSON encoder
|
|
- Pseudonymizer for sensitive fields (`user_id`, `email`, `ip`)
|
|
- Debug-level logging enabled in main.go
|