How pietroagazzi/gater works
1. What this repository is
- gater is a Go-based API gateway, not a business service. Its job is to accept inbound HTTP requests, match them to configured routes, discover upstream instances, apply resilience rules, and proxy the request onward.
2. Process entrypoint and composition root
- The executable lives in cmd/gater/main.go.
- The internal/app package is the composition layer: it assembles configuration, discovery, load balancing, circuit breaking, and the HTTP gateway into one running process.
- This is the place where the application is wired together before the server starts.
3. Configuration boundary
- Runtime behavior is driven by YAML files in config/:
- config/routes.yml defines path prefixes, allowed methods, target service names, and route priority.
- config/services.yml defines per-service resilience settings, especially circuit breaker recovery timeouts.
- The internal/config package parses and validates these files, keeping routing policy and service policy outside the code.
4. Request routing subsystem
- internal/gateway is the core HTTP gateway layer.
- It is responsible for taking an inbound request, selecting the correct route based on path/method/priority, and turning that into a call to the target service.
- This package is the main boundary between external clients and internal service discovery / upstream transport.
5. Service discovery subsystem
- internal/discovery abstracts where service instances come from.
- There are at least two providers:
- consul.go for dynamic discovery from Consul
- static.go for fixed, local, or test-friendly discovery
- factory.go selects/constructs the provider, which makes discovery pluggable rather than hard-coded.
6. Load balancing
- internal/loadbalancer/roundrobin.go chooses among discovered instances.
- The repository uses deterministic round-robin selection, which aligns with the project’s “deterministic” design goal.
- This sits between discovery and transport: discovery yields instances, load balancing picks one instance for a request.
7. Resilience layer
- internal/circuitbreaker wraps upstream calls with a circuit breaker policy.
- The README and service config indicate per-service recovery timeouts, so resilience is configured per backend rather than globally.
- This layer is intended to fail fast when a service is unhealthy instead of retrying indefinitely or blocking requests.
8. Service model
- internal/service defines the domain objects used across routing, discovery, and resilience, such as service definitions and instances.
- These types act as the shared contract between the config parser, discovery provider, and gateway runtime.
9. Upstream call pipeline
- The README describes the architecture as composable http.RoundTripper decorators.
- In practice, the outbound request path is layered: validation/guardrails, circuit breaker, then actual transport to the chosen upstream instance.
- This means the gateway is designed as a proxy pipeline rather than a monolithic handler.
10. External dependency on Consul
- Consul is the only major external infrastructure component visible in the repo.
- In local deployment, docker/consul/ plus docker-compose.yml provide a Consul instance and its bootstrap config.
- In architecture terms, Consul is the dynamic source of truth for service instances when the Consul discovery provider is used.
11. Local and containerized runtime
- The repository is built for container-first operation: Dockerfile, Dockerfile.dev, and docker-compose*.yml support production, development, and test flows.
- Air hot reload is configured via .air.toml, indicating a fast local development loop for the Go process.
12. Health and operational surface
- The README shows a /health endpoint, implying the gateway exposes at least a basic liveness/readiness surface.
- GitHub Actions cover CI, security scanning, and Docker publishing, so the repo includes production-oriented build and release automation.
13. How the main data flows connect
- Startup flow: YAML config → config validation → discovery provider initialization → route/service policy assembly → gateway construction → HTTP server.
- Request flow: client request → route match → service lookup → instance selection → circuit breaker check → proxied upstream call → response back to client.
14. Architecture summary for a diagram
- The important boxes are: HTTP entrypoint, route/config loader, discovery provider, load balancer, circuit breaker, and upstream services.
- The key arrows are: configuration into runtime, request path through gateway logic, and service instance resolution through Consul or static definitions.
Main entry points: app.go App wire-up · gateway.go Gateway · factory.go Discovery factory · instance.go Instance model
Components 17
Entrypoint
Process startup and wiring
- Main · Executable startup
cmd/gater/main.go - App wire-up · Assembles runtime dependencies
internal/app/app.go
Config
Externalized routing and service policy
- Config parser · Loads and validates runtime config
internal/config/config.go - Routes · Path, method, target, priority
config/routes.yml - Services · Per-service resilience settings
config/services.yml
Gateway runtime
Request handling and upstream proxy pipeline
- Gateway · Matches routes and forwards requests
internal/gateway/gateway.go - Service model · Shared service definitions
internal/service/service.go - Instance model · Upstream instance representation
internal/service/instance.go - Round robin · Deterministic instance selection
internal/loadbalancer/roundrobin.go - Circuit breaker · Fails fast on unhealthy upstreams
internal/circuitbreaker/circuit_breaker.go
Discovery
Pluggable service instance sources
- Discovery factory · Builds the discovery backend
internal/discovery/factory.go - Consul provider · Loads instances from Consul
internal/discovery/consul.go - Static provider · Fixed instance source
internal/discovery/static.go
Operations
Container and local infrastructure
- Compose · Containerized gateway and dependencies
docker-compose.yml - Consul bootstrap · Local Consul bootstrap data
docker/consul/config/local.json - Dockerfile · Production build image
Dockerfile - Dev image · Development container image
Dockerfile.dev
Connections 20
- Main → App wire-up: starts · Entrypoint creates the composed application
- App wire-up → Config parser: loads · Reads and validates runtime configuration
- App wire-up → Discovery factory: wires · Selects a discovery provider
- App wire-up → Gateway: builds · Constructs the HTTP gateway
- App wire-up → Circuit breaker: adds · Installs resilience into upstream calls
- Config parser → Routes: parses · Route definitions come from YAML
- Config parser → Services: parses · Service policies come from YAML
- Gateway → Service model: uses · Routes resolve to service definitions
- Gateway → Discovery factory: resolves · Looks up instance sources through discovery
- Gateway → Round robin: selects · Chooses an upstream instance
- Gateway → Circuit breaker: guards · Wraps upstream traffic with breaker policy
- Discovery factory → Consul provider: selects · Can build the Consul-backed provider
- Discovery factory → Static provider: selects · Can build the static provider
- Consul provider → Instance model: returns · Converts Consul data into instances
- Static provider → Instance model: returns · Exposes fixed instances
- Round robin → Instance model: chooses · Picks one instance for a request
- Circuit breaker → Instance model: protects · Applies per-upstream resilience
- Compose → Consul bootstrap: boots · Local compose brings up Consul bootstrap data
- Compose → Dockerfile: builds · Compose can run the production image
- Compose → Dev image: builds · Compose can run the dev image