Files

T

riotpiaole c42a5df536 feat: extract kafkamgmt.v1 proto contract from kafaka_management_service

Single source of truth for the wire contract shared by the server,
kmsvc-sdk, and kmsvc-cli. Ships proto source + buf lint/breaking-change
config only; consumers submodule this repo and codegen independently
with their own go_package override (see README.md).

2026-06-21 19:05:13 -07:00

4.3 KiB

Raw Permalink Blame History

kmsvc-proto — shared proto contract implementation plan

Context

Third sibling repo alongside kafaka_management_service (server), kmsvc-sdk (Go client SDK), and kmsvc-cli (CLI). Holds the kafkamgmt.v1 proto definitions as the single source of truth, so the server and the SDK don't generate code from two independently-drifting copies of the same .proto file.

Scope is intentionally narrow: this repo ships .proto source + buf lint/breaking-change config only — no generated code, no language-specific runtime deps. Each consumer (server, SDK) submodules this repo and runs its own buf generate into its own internal package, using its own pinned plugin/runtime versions. This avoids forcing the server and the SDK to agree on the same generated-code/runtime version (protobuf-go, grpc-gateway) — only the wire contract is shared, not the generated artifacts.

Repo layout

kmsvc-proto/
  buf.yaml                         # lint (DEFAULT) + breaking-change (FILE) rules, same as today's server config
  proto/kafkamgmt/v1/queue_service.proto
  CHANGELOG.md                      # human-readable log of wire-contract changes, one entry per tag
  .forgejo/workflows/ci.yaml        # buf lint + buf breaking against the previous tag

No buf.gen.yaml here — codegen output/plugins are each consumer's concern, not this repo's.

Implementation steps

Step 1 — Seed the repo

Move kafaka_management_service/proto/kafkamgmt/v1/queue_service.proto and buf.yaml into this repo verbatim (git history doesn't follow across repos; note the origin commit in the first commit message for traceability).
Verify: buf lint and buf build run clean from this repo's root.

Step 2 — Breaking-change gate

Forgejo Actions workflow: on every PR, buf breaking --against '.git#branch=main' so an accidental incompatible field/RPC change is caught before merge, not discovered by a downstream consumer.
Verify: a real PR introducing a breaking change (e.g. renumbering a field) fails the check; a compatible addition (new optional field) passes.

Step 3 — Tagging convention

Semantic version tags (v1.0.0, v1.1.0, ...): minor bump for additive/compatible changes, major bump for anything buf breaking would have flagged (only ever done deliberately, never silently). CHANGELOG.md gets one entry per tag.
Verify: tag v1.0.0 once Step 1+2 are in place and the current contract (the 6 data-plane RPCs already defined) is confirmed stable.

Step 4 — Wire into the server repo

In kafaka_management_service: replace the in-repo proto/ directory with a git submodule at the same path, pointed at this repo's v1.0.0 tag; buf.gen.yaml and the existing make proto/buf generate flow are otherwise unchanged (still generates into internal/api/v1).
Verify: git submodule update --init && buf generate && go build ./... in the server repo produces identical generated output to what's committed today (diff should be empty other than the submodule pointer file).

Step 5 — Wire into kmsvc-sdk

kmsvc-sdk adds this repo as a submodule at proto/, pinned to the same tag the server currently uses, with its own buf.gen.yaml generating into internal/genapi/ (per kmsvc-sdk/PLAN.md step 1).
Verify: both repos' generated code, despite being produced independently, satisfy the same wire format — confirmed implicitly by an SDK-vs-server integration test (SDK client talks to a real running server) once both exist.

Acceptance criteria

buf lint/buf build pass from a clean checkout.
buf breaking CI gate blocks incompatible changes on PRs, verified by a real failing PR.
v1.0.0 tag exists and matches the contract currently live in kafaka_management_service.
Server repo's submodule swap (step 4) produces byte-identical generated code to its current committed output.
kmsvc-sdk's codegen against the same tag succeeds (step 5 of this plan / step 1 of kmsvc-sdk/PLAN.md).

Sequencing note

Do this repo's steps 1–3 before starting kmsvc-sdk step 1 (SDK needs something to submodule). Step 4 (migrating the server repo) can happen any time after step 3 — it's a refactor of already-working code, not a blocker for the SDK/CLI work, so it can be deferred or done opportunistically without holding up kmsvc-sdk/kmsvc-cli progress.

4.3 KiB Raw Permalink Blame History Unescape Escape