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, but must be re-specified in KrakenD JSON
• KrakenD zero-trust model amplifies this — by default KrakenD forwards nothing (no headers, no query strings). Every parameter must be explicitly allowlisted. Forgetting one breaks auth, pagination, or filtering silently

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

Dual output: .json + .tmpl

The plugin produces two outputs per invocation:

Output	Purpose	Format
krakend.json	Visual verification, PR diffs, schema validation	Full KrakenD config with $schema, version, endpoints[]
{service}_endpoints.tmpl	Production use with KrakenD Flexible Config	Per-service fragments with Go template syntax

Template (.tmpl) features

The .tmpl output conventions are documented in CLAUDE.md under "Flexible Config Template Conventions":

• Host variables: {{ .vars.user_service_host }} — environment-specific via settings files
• JWT auth: {{ template "jwt_auth_validator.tmpl" . }} — shared partial maintained by gateway team
• Recaptcha: {{ include "recpatcha_validator.tmpl" }} — bot protection via shared partial
• Header partials: {{ include "trading_input_headers.tmpl" }} — centralized header management
• Backend defaults: sd:static, disable_host_sanitize:false, return_error_code:true
• Timeout: Only emitted for method-level overrides; service timeout via root settings
• QoS: Rate limiting, circuit breaker, cache in .json only — gateway team manages these separately

Proto annotations

Two annotation levels:

service UserService {
  option (sebuf.krakend.gateway_config) = {
    host: ["http://users-backend:8080"]
    timeout: "3s"
    jwt: { alg: JWT_ALGORITHM_RS256, jwk_url: "..." }
    input_headers_partial: "trading_input_headers.tmpl"  // header partial for .tmpl
  };

  rpc CreateUser(CreateUserRequest) returns (User) {
    option (sebuf.http.config) = { path: "/users", method: HTTP_METHOD_POST };
    option (sebuf.krakend.endpoint_config) = {
      recaptcha: true  // bot protection for .tmpl
    };
  };
}

What is included

• Phase 12: Proto annotations, plugin scaffold, core endpoint generation, header/query forwarding, route validation
• Phase 13: Rate limiting, JWT auth with claim propagation, circuit breaker, caching, concurrent calls
• Phase 14: Proto documentation, krakend-gateway example, README/CLAUDE.md updates
• Quick task 4: .tmpl Flexible Config generation

Files overview

Path	What
proto/sebuf/krakend/krakend.proto	Annotation definitions (gateway_config, endpoint_config, enums)
krakend/krakend.pb.go	Generated Go code from proto
cmd/protoc-gen-krakend/main.go	Plugin entry point — writes .json + per-service .tmpl
internal/krakendgen/generator.go	Core generation: reads annotations, builds Endpoint structs
internal/krakendgen/tmpl_generator.go	Template generation: Endpoint -> .tmpl fragment
internal/krakendgen/types.go	Endpoint/Backend structs with template metadata
internal/krakendgen/testdata/golden/*.json	11 JSON golden files
internal/krakendgen/testdata/golden/*.tmpl	12 template golden files
examples/krakend-gateway/	Full example with Flexible Config

Test plan

• make build produces bin/protoc-gen-krakend
• make lint-fix — 0 issues
• 11 JSON golden file tests pass (zero regression)
• 12 template golden file tests pass
• 6 validation error tests pass (duplicate routes, missing config, invalid QoS)
• KrakenD schema validation tests pass (krakend check -c)
• 10 unit tests for template generator (snake_case, host vars, JWT, recaptcha, partials)
• ./scripts/run_tests.sh --fast — all 10 packages pass

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 18.95652% with 466 lines in your changes missing coverage. Please review.
✅ Project coverage is 4.08%. Comparing base (610ccbd) to head (e8d8ad2).

Files with missing lines	Patch %	Lines
internal/krakendgen/generator.go	0.00%	360 Missing ⚠️
internal/krakendgen/validation.go	0.00%	94 Missing ⚠️
internal/krakendgen/tmpl_generator.go	89.65%	8 Missing and 4 partials ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##            main    #123      +/-   ##
========================================
+ Coverage   3.05%   4.08%   +1.03%     
========================================
  Files         47      50       +3     
  Lines       7803    8373     +570     
========================================
+ Hits         238     342     +104     
- Misses      7561    8023     +462     
- Partials       4       8       +4     

Flag	Coverage Δ
unittests	4.08% <18.95%> (+1.03%)	⬆️

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.

[SebastienMelki]

DevOps Review Guide

Hey! This PR adds KrakenD Flexible Config template generation to protoc-gen-krakend. Here is what to look at and how to verify it matches our gateway patterns.

What changed for you

The plugin now generates two files when you run protoc:

1. krakend.json — same as before, full static config for diffing and krakend check validation
2. {service}_endpoints.tmpl — new, one per service, ready to drop into your Flexible Config setup

Key files to review

Start here — the template conventions are documented in CLAUDE.md under "Flexible Config Template Conventions". Verify the generator output matches those rules.

Then check the generated output matches your patterns:

• internal/krakendgen/testdata/golden/full_gateway_service.krakend.tmpl — the most complete example (JWT + headers + concurrent calls). Compare with your existing hand-written templates.
• internal/krakendgen/testdata/golden/jwt_auth_service.krakend.tmpl — JWT-protected service with claim propagation headers
• internal/krakendgen/testdata/golden/simple_service.krakend.tmpl — minimal service (no JWT, no extras)

The template generator code:

• internal/krakendgen/tmpl_generator.go — ~200 lines, straightforward string building. This is where the output format is defined.

The new proto annotations (for you to use):

• proto/sebuf/krakend/krakend.proto — look for input_headers_partial (field 9 on GatewayConfig) and recaptcha (field 8 on EndpointConfig)

What to verify

1. Template structure — Does the generated .tmpl look like your existing hand-written KrakenD templates? Check:

   • "sd": "static" on every backend
   • "disable_host_sanitize": false on every backend
   • "backend/http": { "return_error_code": true } always in backend extra_config
   • "encoding": "json" and "output_encoding": "json" present

2. Host variables — {{ .vars.user_service_host }} derived from proto service name. Would these names work in your settings/*/vars.json files?

3. JWT directive — {{ template "jwt_auth_validator.tmpl" . }} (with dot context). Is this the right directive for your JWT partial? (vs {{ include }})

4. Recaptcha directive — {{ include "recpatcha_validator.tmpl" }} (no dot context). Matches the spelling in your existing partials.

5. Header partials — When input_headers_partial: "trading_input_headers.tmpl" is set on the service, the generator emits {{ include "trading_input_headers.tmpl" }} instead of inline headers. When not set, it falls back to explicit "input_headers": [...]. Is this the right default?

6. Timeout behavior — Service-level timeout is NOT emitted in .tmpl (it lives in your root settings). Only method-level overrides show up. Correct?

7. QoS absence — Rate limiting, circuit breaker, and cache configs are intentionally not in the .tmpl output (they are in .json for reference). The gateway team manages these outside of generated code. Is this the right split?

How to test locally

make build

# Generate for any proto with KrakenD annotations
protoc --plugin=protoc-gen-krakend=./bin/protoc-gen-krakend \
       --krakend_out=./output \
       --proto_path=examples/krakend-gateway/proto \
       --proto_path=proto \
       examples/krakend-gateway/proto/services/user_service.proto

# Check output
cat output/user_service_endpoints.tmpl
cat output/krakend.json

What is NOT in scope yet

• JSON-schema validation (validation/json-schema blocks) — deferred, will discuss separately
• Martian header injection (modifier/martian) — low priority per spec
• Custom extra_config passthrough — if you need arbitrary extra_config keys in .tmpl, that is a follow-up