Buf Tooling

Sonata uses Buf for protobuf schema management, providing linting, breaking change detection, and code generation.

Overview

Buf is a modern build tool for Protocol Buffers that replaces the traditional protoc compiler with a more developer-friendly experience.

Configuration

buf.yaml

Defines the module and linting rules:

version: v2
modules:
  - path: proto
lint:
  use:
    - DEFAULT
breaking:
  use:
    - FILE

buf.gen.yaml

Configures code generation plugins:

version: v2
plugins:
  - remote: buf.build/connectrpc/go:v1.18.1
    out: gen
    opt: paths=source_relative
  - remote: buf.build/protocolbuffers/go:v1.33.0
    out: gen
    opt: paths=source_relative

Common Commands

Generate Code

buf generate

Generates Go code from all .proto files into the gen/ directory.

Lint Schemas

buf lint

Checks schemas against style and correctness rules.

Check Breaking Changes

buf breaking --against '.git#branch=main'

Detects breaking changes compared to a reference (e.g., main branch).

Format Schemas

buf format -w

Formats all .proto files consistently.

Generated Output

The gen/ directory mirrors the proto/ structure:

gen/
├── account/v1/v1.pb.go
├── api/v1/
│   ├── account.pb.go
│   ├── chain.pb.go
│   └── v1connect/
│       ├── account.connect.go
│       └── chain.connect.go
├── chain/v1/
│   ├── account.pb.go
│   ├── tx.pb.go
│   └── ...
└── ...

• *.pb.go — Message types and serialization
• *connect/*.connect.go — Service client/server stubs

Remote Plugins

Buf uses remote plugins from buf.build, eliminating the need to install local protoc plugins:

Workflow

1. Edit .proto files in proto/
2. Run buf lint to check for issues
3. Run buf generate to update gen/
4. Commit both proto/ and gen/ changes together