feat: add protoc-gen-krakend API gateway config generator

[SebastienMelki]

Summary

Adds protoc-gen-krakend — a new protoc plugin that generates KrakenD API gateway endpoint configurations directly from protobuf service definitions.

Why this matters

The problem: KrakenD configuration is handwritten JSON that must stay perfectly in sync with your backend API definitions. Every time you add an endpoint, change a path parameter, add a required header, or introduce a query filter, you must manually update the gateway config. This creates:

• Configuration drift — the gateway config diverges from the actual API, causing silent request failures at the gateway layer (blocked headers, missing query params, wrong paths)
• Duplicated source of truth — HTTP routing, header requirements, and query parameters are already defined in proto annotations (sebuf.http.config, sebuf.http.service_headers, sebuf.http.query), but must be re-specified in KrakenD JSON
• KrakenD's zero-trust model amplifies this — by default KrakenD forwards nothing (no headers, no query strings). Every parameter must be explicitly allowlisted in input_headers and input_query_strings. Forgetting one breaks authentication, pagination, or filtering silently

The solution: protoc-gen-krakend reads the proto annotations you've already written and generates correct, minimal KrakenD endpoint fragments automatically:

• sebuf.http.config → endpoint path and HTTP method
• sebuf.http.service_headers + method_headers → input_headers (auto-derived, never wildcards)
• sebuf.http.query → input_query_strings (auto-derived from request message fields)
• sebuf.krakend.gateway_config → backend host and default timeout
• sebuf.krakend.endpoint_config → per-RPC overrides

The benefit: Proto definitions remain the single source of truth. Add an endpoint or header annotation once, regenerate, and the gateway config updates automatically. Route conflicts (duplicate paths, static vs parameterized collisions) are caught at generation time, not at gateway startup.

What's included (Phase 12 — in progress)

• Plan 01 — Proto annotation package (sebuf.krakend), plugin scaffold, KrakenD JSON types
• Plan 02 — Core endpoint/backend generation with host and timeout config
• Plan 03 — Auto-derived header and query string forwarding from existing sebuf.http annotations
• Plan 04 — Route validation (duplicate endpoints, static vs param conflicts) and golden file test suite

What's coming next (Phases 13-14)

• Phase 13: Gateway features — rate limiting, JWT auth, circuit breaker, caching, concurrent calls
• Phase 14: Documentation — example proto and Flexible Config integration guide

Test plan

• make build produces bin/protoc-gen-krakend
• go vet ./cmd/protoc-gen-krakend/... ./internal/krakendgen/... passes
• make lint-fix passes
• Golden file tests cover endpoint routing, timeouts, host config, forwarding, and validation errors (Plan 04)
• ./scripts/run_tests.sh --fast — full project test suite passes with no regressions

🤖 Generated with Claude Code

[github-actions]

🔍 CI Pipeline Status

✅ Lint: success
✅ Test: success
✅ Coverage: success
✅ Build: success
✅ Integration: success

---

📊 Coverage Report: Available in checks above
🔗 Artifacts: Test results and coverage reports uploaded

[codecov]

Codecov Report

❌ Patch coverage is 1.10132% with 449 lines in your changes missing coverage. Please review.
✅ Project coverage is 2.48%. Comparing base (871b387) to head (91d4e0f).

Files with missing lines	Patch %	Lines
internal/krakendgen/generator.go	0.00%	355 Missing ⚠️
internal/krakendgen/validation.go	0.00%	94 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##            main    #123      +/-   ##
========================================
- Coverage   2.64%   2.48%   -0.16%     
========================================
  Files         45      47       +2     
  Lines       7082    7531     +449     
========================================
  Hits         187     187              
- Misses      6892    7341     +449     
  Partials       3       3              

Flag	Coverage Δ
unittests	2.48% <1.10%> (-0.16%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[SebastienMelki]

How to use protoc-gen-krakend

Hey! Here's a detailed walkthrough of what this plugin does and how to integrate it into our workflow.

The problem it solves

KrakenD operates on a zero-trust model — by default it forwards nothing to backends. No headers, no query strings, no parameters. Every single one must be explicitly allowlisted in input_headers and input_query_strings in the KrakenD JSON config. On top of that, every endpoint path, HTTP method, timeout, rate limit config, JWT config, etc. must also be manually specified.

This means today we maintain two sources of truth: the proto definitions (which define the actual API) and the KrakenD JSON config (which must mirror it exactly). When someone adds a header annotation, a query parameter, or a new endpoint to a proto, they also have to remember to update the KrakenD config. If they forget, the gateway silently drops headers or blocks requests — no build error, no warning, just broken auth or missing pagination at runtime.

What protoc-gen-krakend does

It reads the annotations we've already written in our proto files and generates correct KrakenD JSON automatically:

Proto annotation	KrakenD output
sebuf.http.config (path + method)	endpoint, method, url_pattern
sebuf.http.service_headers + method_headers	input_headers (auto-derived, no wildcards)
sebuf.http.query on request fields	input_query_strings (auto-derived)
sebuf.krakend.gateway_config (service-level)	host, timeout, rate limit, JWT, circuit breaker, cache, concurrent calls
sebuf.krakend.endpoint_config (method-level)	Per-RPC overrides for any of the above

The proto becomes the single source of truth. Add an endpoint or header annotation once, run buf generate, and the gateway config updates automatically. Route conflicts (duplicate paths, static vs parameterized collisions like /users/me vs /users/{id}) are caught at generation time, not at gateway startup.

How to use it

Step 1: Add krakend annotations to your proto

At the service level, set defaults for all endpoints:

import "sebuf/krakend/krakend.proto";

service UserService {
  option (sebuf.krakend.gateway_config) = {
    host: ["http://users-backend:8080"]
    timeout: "3s"
    rate_limit: { max_rate: 100, client_max_rate: 20, strategy: RATE_LIMIT_STRATEGY_IP }
    jwt: {
      alg: JWT_ALGORITHM_RS256
      jwk_url: "https://auth.example.com/.well-known/jwks.json"
      audience: ["https://api.example.com"]
      issuer: "https://auth.example.com/"
      cache: true
      propagate_claims: [
        {claim: "sub", header: "X-User"},
        {claim: "org_id", header: "X-Org-ID"}
      ]
    }
    circuit_breaker: { interval: 60, timeout: 10, max_errors: 3 }
    backend_rate_limit: { max_rate: 80, capacity: 100 }
  };
}

Optionally override per-RPC:

rpc UpdateUser(UpdateUserRequest) returns (User) {
  option (sebuf.http.config) = { path: "/users/{id}", method: HTTP_METHOD_PUT };
  option (sebuf.krakend.endpoint_config) = {
    rate_limit: {
      max_rate: 50
      client_max_rate: 10
      strategy: RATE_LIMIT_STRATEGY_HEADER
      key: "X-API-Key"  // Per-API-key throttling for writes
    }
  };
}

Step 2: Add plugin to buf.gen.yaml

plugins:
  - local: protoc-gen-krakend
    out: gateway

Step 3: Generate

buf generate
# Output: gateway/krakend.json — a complete, valid KrakenD config

That's it. The output is a standalone krakend.json with $schema, version: 3, and all endpoints from all services combined. You can point KrakenD directly at it, or use it as a partial in KrakenD Flexible Config to compose with other settings.

What gets auto-derived (the best part)

You don't need to manually list forwarded headers or query params. The generator reads existing sebuf.http annotations:

• Headers: service_headers required header names + method_headers required header names + JWT propagate_claims mapped headers → all merged, deduped, sorted → input_headers
• Query strings: Fields with (sebuf.http.query) annotation on the request message → input_query_strings

Example: if ListUsersRequest has fields page, per_page, status annotated with (sebuf.http.query), the generated endpoint automatically includes:

"input_query_strings": ["page", "per_page", "status"]

No manual sync needed.

Features supported

Feature	Where configured	KrakenD namespace
Rate limiting (endpoint)	rate_limit	qos/ratelimit/router
Rate limiting (backend)	backend_rate_limit	qos/ratelimit/proxy
JWT authentication	jwt (service-level only)	auth/validator
JWT claim propagation	jwt.propagate_claims	auto-added to input_headers
Circuit breaker	circuit_breaker	qos/circuit-breaker
HTTP caching (shared)	cache: { shared: true }	qos/http-cache
HTTP caching (sized)	cache: { max_items, max_size }	qos/http-cache
Concurrent calls	concurrent_calls: N	top-level endpoint field
Timeout	timeout: "3s"	top-level endpoint field
Multi-host load balancing	host: ["h1", "h2"]	backend host array

All features can be set at service level (gateway_config) and overridden per-RPC (endpoint_config), except JWT which is service-level only (auth should be consistent across all endpoints in a service).

Generation-time validation

The plugin catches errors at build time instead of gateway startup:

• Duplicate routes: Two RPCs resolving to the same METHOD /path → generation error
• Static vs parameterized conflicts: /users/me and /users/{id} on the same method → generation error
• Invalid cache config: shared: true with max_items/max_size (KrakenD's oneOf constraint) → generation error
• Missing rate limit key: RATE_LIMIT_STRATEGY_HEADER without specifying key → generation error

Running the example

There's a full working example in examples/krakend-gateway/ with two services (UserService + ProductService), Docker Compose, and a real KrakenD gateway:

# From repo root
make build
cd examples/krakend-gateway
make demo   # generates config, builds backend, starts KrakenD + backend
make test   # curls the gateway endpoints
make docker-down

Documentation

• KrakenD Gateway Example README — Full walkthrough with architecture diagram, annotation reference, and feature matrix
• Proto annotation definitions — Heavily commented proto file with usage examples for every field
• README KrakenD section — Overview in the main project README

TL;DR

Write your API in proto with sebuf annotations → run buf generate → get a validated, production-ready krakend.json with JWT, rate limiting, circuit breakers, caching, and all headers/query params correctly forwarded. No manual KrakenD JSON maintenance. The proto is the single source of truth.