Protobuf Codegen Across Services

go_package vs package

package voltnet.iam.v1;                                          // protobuf namespace, language-agnostic
option go_package = "github.com/beep/voltnet-protos/gen/go/iam/v1";  // Go import path

go_package must match your actual Go module structure — it’s what Go imports resolve to.

Why .proto files are the source of truth

• Single contract both client and server agree on — prevents mismatch
• Generates client stubs and server interfaces automatically
• Language agnostic (IAM in Go, Omni in Python — same proto)
• Binary serialization and REST gateway for free

Without proto: manually write and keep client/server code in sync. With proto: define once, generate everywhere.

Codegen is service-specific

Each service generates its own .pb.go files from the shared .proto — you can’t generate once and share, because each service has different import paths and needs.

voltnet-protos is a git submodule, not a Go dep

# Update the submodule (not go get)
cd voltnet-protos && git pull
 
# Then update Go deps separately
go get github.com/some/other-dep

During dev: can point to feature branches. Before merging: must point to main.

Both go.mod (version) and go.sum (checksums) change together — commit both.

Dependency chain order

If Service A depends on Service B: merge B to main first, update A’s deps to point at main, then merge A.

See also

• field-numbers — binary encoding, field numbering rules
• json-tag — controlling JSON serialization with jsontag
• swagger — generating OpenAPI docs from .proto files