api-gateway/CLAUDE.md

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

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