Contract-definition mechanism: buf v2 + protoc-gen-go/grpc-go toolchain #110

Closed
opened 2026-10-27 13:34:59 +00:00 by sam · 0 comments
Owner

Groundwork for all service-decomposition contracts (resolved open
question #2 in docs/prds/service-decomposition.md). Every later phase
(starting with Phase 0's ChatContract seam) needs this toolchain in place
before it can define a wire contract.

Decision (already made, not open for redesign here): buf v2 driving
protoc-gen-go + protoc-gen-go-grpc, targeting grpc-go -- NOT connect-go,
because connect-go's net/http-based client breaks the service-discovery
research's gRPC resolver plumbing for K8s DNS and NATS-KV custom
resolvers. google.golang.org/grpc becomes a direct dependency (today only
google.golang.org/protobuf is an indirect one, go.mod:59).

Layout: one committed proto//v1/ tree (one buf module, not
per-service modules), directory name matching the canonical
service/registry/DNS/chart name. Generated Go is committed (not
build-time generated) to internal/contracts//v1/, produced via
buf's managed mode (go_package_prefix) + paths=source_relative, per
docs/architecture/dependencies-and-contracts.md:55's per-domain
wire-contract ownership rule.

Versioning: directory versioning (v1, v2, ...); a breaking change gets a
new vN directory, never an in-place edit. Enforced by
buf breaking --against '.git#branch=main,subdir=proto'.

Full reasoning, scratch-verified buf/connect-go toolchain results, and
the CI shallow-checkout gotcha: see
docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#2

Acceptance criteria

  • buf v2 config (buf.yaml / buf.gen.yaml) committed at the proto/ tree
    root; protoc-gen-go and protoc-gen-go-grpc wired as buf plugins
    targeting grpc-go.
  • Empty proto//v1/ tree scaffolded (at minimum a placeholder or
    the first real service's .proto once Phase 0 needs it) with the
    directory-versioning convention documented.
  • Generated Go lands at internal/contracts//v1/ and is committed
    (gofumpt-clean, matching the "generated assets are LAW" precedent).
  • New task proto:generate, task proto:lint, task proto:check tasks
    in Taskfile.yml; proto:check regenerates then git diff --exit-code -- internal/contracts.
  • task proto:generate/lint/check wired into task check, inserted
    after go fix ./... and before vet/lint/build.
  • The same proto:lint/proto:check steps (or their direct buf/git-diff
    equivalents) mirrored into .github/workflows/deploy.yml's Quality gate
    step, since CI does not invoke task check today -- with fetch-depth:0
    (or an explicit git fetch origin main) so buf breaking --against
    has a local main ref to diff against.
  • buf breaking demonstrably fails the gate on a deliberately introduced
    breaking change (deleted RPC, renamed/removed field) in a smoke test or
    manual verification note.

Close reason

Buf v2 protobuf/grpc-go toolchain, generated Gateway contract, proto tasks, CI gate, and breaking-change smoke verification implemented.


Imported from beads archie-core-8cda.1 · GitHub #723 · type task · priority P1 · created 2026-09-05 · closed 2026-09-05

Groundwork for all service-decomposition contracts (resolved open question #2 in docs/prds/service-decomposition.md). Every later phase (starting with Phase 0's ChatContract seam) needs this toolchain in place before it can define a wire contract. Decision (already made, not open for redesign here): buf v2 driving protoc-gen-go + protoc-gen-go-grpc, targeting grpc-go -- NOT connect-go, because connect-go's net/http-based client breaks the service-discovery research's gRPC resolver plumbing for K8s DNS and NATS-KV custom resolvers. google.golang.org/grpc becomes a direct dependency (today only google.golang.org/protobuf is an indirect one, go.mod:59). Layout: one committed proto/<service>/v1/ tree (one buf module, not per-service modules), directory name matching the canonical service/registry/DNS/chart name. Generated Go is committed (not build-time generated) to internal/contracts/<service>/v1/, produced via buf's managed mode (go_package_prefix) + paths=source_relative, per docs/architecture/dependencies-and-contracts.md:55's per-domain wire-contract ownership rule. Versioning: directory versioning (v1, v2, ...); a breaking change gets a new vN directory, never an in-place edit. Enforced by `buf breaking --against '.git#branch=main,subdir=proto'`. Full reasoning, scratch-verified buf/connect-go toolchain results, and the CI shallow-checkout gotcha: see docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#2 ### Acceptance criteria - buf v2 config (buf.yaml / buf.gen.yaml) committed at the proto/ tree root; protoc-gen-go and protoc-gen-go-grpc wired as buf plugins targeting grpc-go. - Empty proto/<service>/v1/ tree scaffolded (at minimum a placeholder or the first real service's .proto once Phase 0 needs it) with the directory-versioning convention documented. - Generated Go lands at internal/contracts/<service>/v1/ and is committed (gofumpt-clean, matching the "generated assets are LAW" precedent). - New `task proto:generate`, `task proto:lint`, `task proto:check` tasks in Taskfile.yml; proto:check regenerates then `git diff --exit-code -- internal/contracts`. - `task proto:generate/lint/check` wired into `task check`, inserted after `go fix ./...` and before vet/lint/build. - The same proto:lint/proto:check steps (or their direct buf/git-diff equivalents) mirrored into .github/workflows/deploy.yml's Quality gate step, since CI does not invoke `task check` today -- with fetch-depth:0 (or an explicit `git fetch origin main`) so `buf breaking --against` has a local main ref to diff against. - `buf breaking` demonstrably fails the gate on a deliberately introduced breaking change (deleted RPC, renamed/removed field) in a smoke test or manual verification note. ### Close reason Buf v2 protobuf/grpc-go toolchain, generated Gateway contract, proto tasks, CI gate, and breaking-change smoke verification implemented. --- _Imported from beads `archie-core-8cda.1` · GitHub #723 · type task · priority P1 · created 2026-09-05 · closed 2026-09-05_
sam added the hightask labels 2026-10-27 13:34:59 +00:00
sam self-assigned this 2026-10-27 13:34:59 +00:00
sam closed this issue 2026-10-27 13:34:59 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#110