README
¶
proto companion
The codefly proto companion bundles buf, protoc, protoc-gen-*,
swagger, grpcio-tools, and the JS/TS generators into one OCI
image. Used by codefly generate proto and the
codefly generate openAPI pipeline.
Build
There are two source-of-truth options today:
Nix (preferred — reproducible, layered cache)
# From core/companions/proto/, with a Linux build target.
# On macOS, requires nix-darwin's linux-builder configured.
nix build .#dockerImage
nix run .#streamDockerImage | docker load
The Nix flake pins every transitive dependency by content hash via
flake.lock. The dev shell (nix develop) uses the same package set
the image ships — no drift between "works on my dev machine" and
"the agent's image." Image tag is read from info.codefly.yaml so
the existing tag.sh version-bump flow continues to work.
Dockerfile (legacy — kept for parity until the Nix path is
default)
codefly companion build proto
The Dockerfile assembles the same set via apk + go install. Less
reproducible than Nix (apk packages vary across Alpine releases) but
needs no Linux builder VM. Will be retired once Phase 1's flake-based
build is the canonical path.
What's in the image
| Tool | Purpose |
|---|---|
buf |
Modern proto compilation + linting |
protoc + libprotoc |
Classic proto compiler (some plugins still need it) |
protoc-gen-go / -go-grpc |
Go bindings + gRPC |
protoc-gen-grpc-gateway |
REST-from-gRPC |
protoc-gen-openapiv2 |
OpenAPI from gRPC |
protoc-gen-connect-go |
Connect-RPC bindings |
swagger (go-swagger) |
OpenAPI client generation |
go + gofmt |
Required at runtime by swagger for source formatting |
grpcio-tools (python) |
grpc_python_plugin for Python bindings |
node + npm |
TypeScript generators |
Versioning
info.codefly.yaml carries the image version (0.0.10 at time of
writing). Bump via scripts/tag.sh — same convention as every other
companion. Both the Dockerfile build and the Nix build read this
value so the tag stays consistent.
Documentation
¶
Index ¶
- Constants
- func CompanionImage(ctx context.Context) (*resources.DockerImage, error)
- func CreateBufConfiguration(ctx context.Context, bufDir string, service string, ...) error
- func GenerateGRPC(ctx context.Context, language languages.Language, destination string, ...) error
- func GenerateOpenAPI(ctx context.Context, language languages.Language, destination string, _ string, ...) error
- type Buf
- type GoConfiguration
- type Info
- type PythonConfiguration
- type RustConfiguration
- type TypeScriptConfiguration
Constants ¶
const InfoConfigurationName = "info.codefly.yaml"
Variables ¶
This section is empty.
Functions ¶
func CompanionImage ¶
func CompanionImage(ctx context.Context) (*resources.DockerImage, error)
func CreateBufConfiguration ¶
func GenerateGRPC ¶
func GenerateGRPC(ctx context.Context, language languages.Language, destination string, service string, endpoints ...*basev0.Endpoint) error
GenerateGRPC runs buf in a companion (Docker/Nix/local via golden wrapper) to generate gRPC client code for the given language and endpoints.
Types ¶
type Buf ¶ added in v0.1.83
type Buf struct {
Dir string
// contains filtered or unexported fields
}
func (*Buf) Generate ¶ added in v0.1.83
Generate runs buf in a companion (golden wrapper) to regenerate code from local proto files.
func (*Buf) WithGeneratedDirs ¶ added in v0.2.24
WithGeneratedDirs declares output directories that are wholly owned by Buf generation. Directories must be strict descendants of the generated root; this invariant keeps regeneration cleanup scoped to the managed service.
func (*Buf) WithGeneratedRoot ¶ added in v0.2.29
WithGeneratedRoot declares the service root that owns generated outputs. This is distinct from Dir for nested protocol layouts such as code/proto: Buf runs from code/, while generated OpenAPI may still live at the service root. cleanGeneratedDirs continues to reject every path outside this root.
type GoConfiguration ¶
type PythonConfiguration ¶ added in v0.1.139
type PythonConfiguration struct {
Destination string
}
type RustConfiguration ¶ added in v0.2.2
type RustConfiguration struct {
Destination string
}
type TypeScriptConfiguration ¶ added in v0.1.155
type TypeScriptConfiguration struct {
Destination string
}
Source Files