# mailgun/gubernator architecture

> Architecture diagram of the GitHub repository mailgun/gubernator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mailgun/gubernator
- Repository: https://github.com/mailgun/gubernator

## Overview

#### Purpose and Entry Points
Gubernator is a Go-based, distributed, stateless rate-limiting service and embeddable library. Clients supply rate-limit configuration on each request; nodes keep active bucket state in memory and distribute ownership across a cluster. The primary server binary is `cmd/gubernator/main.go`; related operational binaries are cluster tooling in `cmd/gubernator-cluster/main.go`, a CLI in `cmd/gubernator-cli/main.go`, and health checking in `cmd/healthcheck/main.go`.

#### Public API and Transport Boundary
The API contract is defined in `gubernator.proto`, with generated Go gRPC and HTTP/gRPC-Gateway bindings in `gubernator_grpc.pb.go` and `gubernator.pb.gw.go`. `gubernator.go` implements public rate-limit and health operations. Clients can use gRPC directly or HTTP endpoints translated by grpc-gateway; generated Python bindings under `python/gubernator/` support Python consumers.

#### Request Routing and Cluster Ownership
Each rate-limit key is assigned to a cluster member via consistent/replicated hashing, so requests reach a single coordinating owner:
- `replicated_hash.go`
- `region_picker.go`
- `cluster/cluster.go`

A receiving node evaluates locally owned limits or forwards work to the owner through peer RPC clients in `peer_client.go`. Peer protocol definitions and generated stubs are `peers.proto` and `peers_grpc.pb.go`. This ownership boundary lets nodes scale horizontally without Redis or memcached.

#### Rate-Limit Evaluation and State
Core evaluation selects token-bucket or leaky-bucket behavior and handles request options such as batching, global behavior, Gregorian intervals, reset, and draining. The algorithm and service orchestration are centered in:
- `algorithms.go`
- `gubernator.go`
- `interval.go`

In-memory state is maintained through cache abstractions in `cache.go` and `lrucache.go`. The service is normally diskless, but `store.go` exposes Loader/Store interfaces for embedders that need startup/shutdown or ongoing persistence.

#### Batching, Replication, and Global Limits
Workers batch compatible peer-bound requests for throughput, then dispatch and reconcile responses; this is implemented in `workers.go` and coordinated from `gubernator.go`. Optional globally distributed rate limits use eventually consistent sharing rather than strict single-node handling, with global coordination in `global.go`. These modes trade latency, throughput, and consistency while retaining the same client API.

#### Membership and Discovery
Cluster membership is abstracted behind discovery implementations. Nodes can discover peers from etcd, Kubernetes, or round-robin DNS:
- `etcd.go`
- `kubernetes.go`
- `dns.go`

`memberlist.go` and `daemon.go` manage peer lifecycle and server operation. Configuration is environment-driven or loaded from a config file via `config.go` and `flags.go`; networking and TLS boundaries are handled by `net.go` and `tls.go`.

#### Runtime, Deployment, and Observability
The service runs as a Go process, containerized by `Dockerfile`, and can be deployed standalone, as a sidecar, or embedded as a library. Kubernetes deployment artifacts include `contrib/k8s-deployment.yaml` and Helm templates in `contrib/charts/gubernator/templates/deployment.yaml`; an AWS ECS service-discovery example is under `contrib/aws-ecs-service-discovery-deployment/`. Prometheus metrics and OpenTelemetry instrumentation are represented by `grpc_stats.go`, `docs/prometheus.md`, and `docs/tracing.md`.

Main entry points: [`gubernator.go`](https://github.com/mailgun/gubernator/blob/master/gubernator.go) (Rate-limit service), [`gubernator.pb.gw.go`](https://github.com/mailgun/gubernator/blob/master/gubernator.pb.gw.go) (gRPC / HTTP transport), [`cmd/gubernator/main.go`](https://github.com/mailgun/gubernator/blob/master/cmd/gubernator/main.go) (Server binary), [`replicated_hash.go`](https://github.com/mailgun/gubernator/blob/master/replicated_hash.go) (Key ownership)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API & Clients"]
  node_transport{{"gRPC / HTTP transport<br/>transport boundary"}}
  node_api_contract["Rate-limit API contract<br/>protobuf<br/>[gubernator.proto]"]
  node_python_client["Python bindings<br/>client SDK"]
end

subgraph group_service["Rate Limit Service"]
  node_service_api["Rate-limit service<br/>service orchestration<br/>[gubernator.go]"]
  node_algorithms["Bucket algorithms<br/>rate-limit engine<br/>[algorithms.go]"]
  node_intervals["Interval handling<br/>time semantics<br/>[interval.go]"]
  node_state_cache[("In-memory bucket state<br/>LRU cache<br/>[lrucache.go]")]
  node_persistence["Optional persistence<br/>embedder interface<br/>[store.go]"]
  node_workers["Peer request batching<br/>worker pipeline<br/>[workers.go]"]
  node_global["Global limits<br/>eventual coordination<br/>[global.go]"]
end

subgraph group_cluster["Cluster &amp; Ownership"]
  node_ownership["Key ownership<br/>replicated hashing<br/>[replicated_hash.go]"]
  node_peer_rpc{{"Peer RPC client<br/>cluster transport<br/>[peer_client.go]"}}
  node_membership["Membership lifecycle<br/>cluster manager<br/>[memberlist.go]"]
  node_discovery["Discovery providers<br/>peer discovery<br/>[etcd.go]"]
end

subgraph group_runtime["Runtime &amp; Operations"]
  node_server["Server binary<br/>Go entry point<br/>[main.go]"]
  node_config["Configuration<br/>config loading<br/>[config.go]"]
  node_observability["Metrics &amp; tracing<br/>instrumentation<br/>[grpc_stats.go]"]
  node_deployment["Kubernetes deployment<br/>deployment manifest"]
end

node_api_contract -->|"generates bindings"| node_transport
node_python_client -->|"calls"| node_transport
node_server -->|"loads"| node_config
node_server -->|"starts"| node_transport
node_transport -->|"dispatches"| node_service_api
node_service_api -->|"evaluates through"| node_algorithms
node_algorithms -->|"uses"| node_intervals
node_service_api -->|"reads and updates"| node_state_cache
node_persistence -.->|"loads or stores"| node_state_cache
node_service_api -->|"routes key by"| node_ownership
node_ownership -->|"selects remote owner"| node_peer_rpc
node_service_api -->|"queues remote work"| node_workers
node_workers -->|"dispatches batches"| node_peer_rpc
node_service_api -.->|"coordinates optional limits"| node_global
node_membership -->|"supplies member set"| node_ownership
node_discovery -->|"finds peers"| node_membership
node_server -->|"runs cluster node"| node_membership
node_transport -.->|"emits telemetry"| node_observability
node_deployment -->|"deploys"| node_server

click node_server "https://github.com/mailgun/gubernator/blob/master/cmd/gubernator/main.go"
click node_config "https://github.com/mailgun/gubernator/blob/master/config.go"
click node_transport "https://github.com/mailgun/gubernator/blob/master/gubernator.pb.gw.go"
click node_api_contract "https://github.com/mailgun/gubernator/blob/master/gubernator.proto"
click node_service_api "https://github.com/mailgun/gubernator/blob/master/gubernator.go"
click node_algorithms "https://github.com/mailgun/gubernator/blob/master/algorithms.go"
click node_intervals "https://github.com/mailgun/gubernator/blob/master/interval.go"
click node_state_cache "https://github.com/mailgun/gubernator/blob/master/lrucache.go"
click node_persistence "https://github.com/mailgun/gubernator/blob/master/store.go"
click node_workers "https://github.com/mailgun/gubernator/blob/master/workers.go"
click node_global "https://github.com/mailgun/gubernator/blob/master/global.go"
click node_ownership "https://github.com/mailgun/gubernator/blob/master/replicated_hash.go"
click node_peer_rpc "https://github.com/mailgun/gubernator/blob/master/peer_client.go"
click node_membership "https://github.com/mailgun/gubernator/blob/master/memberlist.go"
click node_discovery "https://github.com/mailgun/gubernator/blob/master/etcd.go"
click node_observability "https://github.com/mailgun/gubernator/blob/master/grpc_stats.go"
click node_deployment "https://github.com/mailgun/gubernator/blob/master/contrib/k8s-deployment.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_transport,node_api_contract,node_python_client toneBlue
class node_service_api,node_algorithms,node_intervals,node_state_cache,node_persistence,node_workers,node_global toneAmber
class node_ownership,node_peer_rpc,node_membership,node_discovery toneMint
class node_server,node_config,node_observability,node_deployment toneRose
```

## Components

### API & Clients

- [gRPC / HTTP transport](https://github.com/mailgun/gubernator/blob/master/gubernator.pb.gw.go): transport boundary · Serves gRPC and grpc-gateway HTTP requests. · `gubernator.pb.gw.go`
- [Rate-limit API contract](https://github.com/mailgun/gubernator/blob/master/gubernator.proto): protobuf · `gubernator.proto`
- **Python bindings**: client SDK

### Rate Limit Service

- [Rate-limit service](https://github.com/mailgun/gubernator/blob/master/gubernator.go): service orchestration · Implements public rate-limit and health operations. · `gubernator.go`
- [Bucket algorithms](https://github.com/mailgun/gubernator/blob/master/algorithms.go): rate-limit engine · Evaluates token and leaky buckets plus request options. · `algorithms.go`
- [Interval handling](https://github.com/mailgun/gubernator/blob/master/interval.go): time semantics · Supports Gregorian intervals and reset timing. · `interval.go`
- [In-memory bucket state](https://github.com/mailgun/gubernator/blob/master/lrucache.go): LRU cache · Holds active rate-limit buckets on each node. · `lrucache.go`
- [Optional persistence](https://github.com/mailgun/gubernator/blob/master/store.go): embedder interface · Loader and Store interfaces allow state persistence. · `store.go`
- [Peer request batching](https://github.com/mailgun/gubernator/blob/master/workers.go): worker pipeline · Batches compatible remote requests and reconciles responses. · `workers.go`
- [Global limits](https://github.com/mailgun/gubernator/blob/master/global.go): eventual coordination · Shares distributed global-limit state with eventual consistency. · `global.go`

### Cluster & Ownership

- [Key ownership](https://github.com/mailgun/gubernator/blob/master/replicated_hash.go): replicated hashing · Maps each rate-limit key to a coordinating member. · `replicated_hash.go`
- [Peer RPC client](https://github.com/mailgun/gubernator/blob/master/peer_client.go): cluster transport · Forwards work to the owning node. · `peer_client.go`
- [Membership lifecycle](https://github.com/mailgun/gubernator/blob/master/memberlist.go): cluster manager · Maintains peers and server lifecycle. · `memberlist.go`
- [Discovery providers](https://github.com/mailgun/gubernator/blob/master/etcd.go): peer discovery · Supports etcd, Kubernetes, and DNS discovery. · `etcd.go`

### Runtime & Operations

- [Server binary](https://github.com/mailgun/gubernator/blob/master/cmd/gubernator/main.go): Go entry point · `cmd/gubernator/main.go`
- [Configuration](https://github.com/mailgun/gubernator/blob/master/config.go): config loading · Environment and file-driven server configuration. · `config.go`
- [Metrics & tracing](https://github.com/mailgun/gubernator/blob/master/grpc_stats.go): instrumentation · Exports Prometheus metrics and OpenTelemetry signals. · `grpc_stats.go`
- [Kubernetes deployment](https://github.com/mailgun/gubernator/blob/master/contrib/k8s-deployment.yaml): deployment manifest · `contrib/k8s-deployment.yaml`

## Connections

- Rate-limit API contract → gRPC / HTTP transport: generates bindings
- Python bindings → gRPC / HTTP transport: calls
- Server binary → Configuration: loads
- Server binary → gRPC / HTTP transport: starts
- gRPC / HTTP transport → Rate-limit service: dispatches
- Rate-limit service → Bucket algorithms: evaluates through
- Bucket algorithms → Interval handling: uses
- Rate-limit service → In-memory bucket state: reads and updates
- Optional persistence → In-memory bucket state: loads or stores
- Rate-limit service → Key ownership: routes key by
- Key ownership → Peer RPC client: selects remote owner
- Rate-limit service → Peer request batching: queues remote work
- Peer request batching → Peer RPC client: dispatches batches
- Rate-limit service → Global limits: coordinates optional limits
- Membership lifecycle → Key ownership: supplies member set
- Discovery providers → Membership lifecycle: finds peers
- Server binary → Membership lifecycle: runs cluster node
- gRPC / HTTP transport → Metrics & tracing: emits telemetry
- Kubernetes deployment → Server binary: deploys