README.md

Gater

A deterministic, fail-fast API Gateway for modern microservices.

A lightweight, modern API Gateway written in Go. Designed for simplicity, reliability, and ease of use in microservices architectures. Currently in early development — APIs may change.

---

Quick Start

# Clone and start with Docker Compose
git clone https://github.com/pietroagazzi/gater.git
cd gater
docker compose up --build -d

The gateway is available at http://localhost:8080 and the Consul UI at http://localhost:8500.

# Verify the gateway is running
curl http://localhost:8080/health

Configuration

Gater uses two YAML files in the config/ directory.

Routes (config/routes.yml)

Defines how incoming requests map to backend services:

routes:
    - path: /users
      service_name: user-service
      methods: [GET, POST, PUT, DELETE]
      priority: 1

    - path: /v2/users
      service_name: user-service
      methods: [GET, PUT, DELETE]
      priority: 2

    - path: /posts
      service_name: post-service
      methods: [GET, POST, DELETE]

Field	Description
path	URL prefix to match incoming requests
service_name	Service name to route to (must match discovery registry)
methods	Allowed HTTP methods
priority	Route evaluation order (higher = evaluated first)

Services (config/services.yml)

Configures per-service resilience policies:

services:
    user-service:
        service_name: user-service
        resilience:
            circuit_breaker:
                recovery_timeout: 30s

    post-service:
        service_name: post-service
        resilience:
            circuit_breaker:
                recovery_timeout: 20s

Field	Description
service_name	Must match the name in the discovery registry
recovery_timeout	Time the circuit breaker waits before allowing retries

Design Philosophy

• Deterministic — No hidden defaults or magic behavior. Every configuration value is explicit.
• Fail-fast — Invalid configuration, unreachable dependencies, and bad input are caught at startup, not at request time. Constructors verify connectivity and reject incomplete state before returning.
• Interface-driven — Core components (service discovery, load balancing, circuit breaking) are defined as interfaces, making providers pluggable and the entire stack testable with mocks.
• Composable — Infrastructure concerns are layered as http.RoundTripper decorators (validation, circuit breaking, transport), each with a single responsibility.

Development

Prerequisites

• Go 1.26+
• Docker
• pre-commit

Hot Reload with Air

docker compose -f docker-compose.dev.yml up --build

Edit files under cmd/ or internal/ and Air will rebuild and reload automatically.

Pre-commit Hooks

pip install pre-commit
pre-commit install

Runs formatting, linting, and tests automatically on commit.

Testing

Run all tests with:

go test ./...

Or with docker:

docker compose -f docker-compose.test.yml -p gater-test up --build --abort-on-container-exit && \
docker compose -f docker-compose.test.yml -p gater-test down

Deployment

Docker

Pull the pre-built image from GitHub Container Registry:

docker pull ghcr.io/pietroagazzi/gater:latest

The image supports linux/amd64 and linux/arm64 architectures.

Binary Releases

Download pre-built binaries from the Releases page.

Build from Source

go build -o gater ./cmd/gater

Contributing

1. Fork the repository
2. Create a branch following Conventional Branch naming
3. Commit using Conventional Commits
4. Push to the branch
5. Open a Pull Request

Please ensure all tests pass and pre-commit hooks are clean before submitting.

Acknowledgments

Built with:

• Gin — HTTP framework
• Consul API — Service discovery
• gobreaker — Circuit breaker