riotpiaole
c42a5df536
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).
52 lines
4.3 KiB
Markdown
52 lines
4.3 KiB
Markdown
# 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.
|