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 features including path-based routing, prefix stripping, and structured logging.

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, 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, 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 handler with optional strip prefix middleware
  3. Registers with chi router using r.Handle() (method-agnostic)

API (server/api.go)

• Links hosts to backend targets
• Implements http.Handler interface
• Delegates to the reverse proxy

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, apis) creates route handlers
4. routes.Register(g.router) registers handlers
5. Gateway starts HTTP server

Middleware Chain

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

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 - 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

Module Structure

The codebase uses an internal Go module:

git.secnex.io/secnex/api-gateway

Internal imports use this path (e.g., git.secnex.io/secnex/api-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
• 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

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"