Documentation
¶
Index ¶
- Constants
- func DiscoverProtoFiles(projectDir string, patterns, excludePatterns []string) ([]string, error)
- func FindGeneratedFilesForProto(protoFile, projectDir, modulePath string) ([]string, error)
- func GetGeneratedFiles(protoFile, projectDir, modulePath string, hasGo, hasTS bool) []string
- func GetGoModule(projectDir string) (string, error)
- func GetPackageKey(modulePath, protoFile string) string
- type Cache
- func (c *Cache) CleanOrphanedPackages(currentPackages map[string]struct{})
- func (c *Cache) NeedsRegeneration(packageKey string, protoFiles []string, projectDir string, flagsHash string, ...) (bool, error)
- func (c *Cache) Save(path string) error
- func (c *Cache) SetProtocFlags(flags []string)
- func (c *Cache) SetToolVersions(versions string)
- func (c *Cache) UpdatePackage(packageKey string, protoFiles []string, generatedFiles []string, ...) error
- type Config
- type Generator
- type NativePluginHandler
- type PackageInfo
- type Plugin
- type PluginType
- type Plugins
- type PostProcessor
- func (p *PostProcessor) ProcessAllCppFiles(dir string) error
- func (p *PostProcessor) ProcessAllTsFiles(dir string) error
- func (p *PostProcessor) ProcessCppFile(filePath string) error
- func (p *PostProcessor) ProcessGeneratedFiles(protoFile string) error
- func (p *PostProcessor) ProcessGoFile(filePath string) error
- func (p *PostProcessor) ProcessRustFiles(protoFile string) error
- func (p *PostProcessor) ProcessTsFile(filePath string) error
Constants ¶
const CacheVersion = 2
CacheVersion is the current cache format version.
const (
// CppBuildTag is the build tag prepended to C++ files.
CppBuildTag = "//go:build deps_only && cgo"
)
const DefaultCacheFile = ".protoc-manifest.json"
DefaultCacheFile is the default cache file name.
const DefaultGoLiteFeatures = "marshal+unmarshal+size+equal+json+clone+text"
DefaultGoLiteFeatures is the default set of go-lite features to enable.
Variables ¶
This section is empty.
Functions ¶
func DiscoverProtoFiles ¶
DiscoverProtoFiles finds proto files matching the given patterns. Uses git ls-files to find tracked proto files. excludePatterns allows excluding files that match certain patterns.
func FindGeneratedFilesForProto ¶
FindGeneratedFilesForProto finds actual generated files for a proto file using glob.
func GetGeneratedFiles ¶
GetGeneratedFiles returns the expected generated file paths for a proto file.
func GetGoModule ¶
GetGoModule reads the module path from go.mod in the given directory.
func GetPackageKey ¶
GetPackageKey generates a cache key for a proto file. Uses the format: "module/path/to/dir;package_name"
Types ¶
type Cache ¶
type Cache struct {
// Version is the cache format version.
Version int `json:"version"`
// ProtocFlagsHash is the hash of the protoc flags.
ProtocFlagsHash string `json:"protocFlagsHash"`
// ToolVersions stores tool version strings for cache invalidation.
ToolVersions string `json:"toolVersions,omitempty"`
// Packages maps package identifiers to package info.
Packages map[string]*PackageInfo `json:"packages"`
}
Cache represents the protoc manifest cache.
func LoadCache ¶
LoadCache loads the cache from a file. Returns an empty cache if the file doesn't exist.
func (*Cache) CleanOrphanedPackages ¶
CleanOrphanedPackages removes packages from the cache that no longer have proto files.
func (*Cache) NeedsRegeneration ¶
func (c *Cache) NeedsRegeneration(packageKey string, protoFiles []string, projectDir string, flagsHash string, force bool) (bool, error)
NeedsRegeneration checks if a proto file needs regeneration. Returns true if: - The file is not in the cache - The file content hash has changed - The protoc flags have changed - Force is true
func (*Cache) SetProtocFlags ¶
SetProtocFlags sets the protoc flags hash.
func (*Cache) SetToolVersions ¶
SetToolVersions sets the tool versions string.
type Config ¶
type Config struct {
// ProjectDir is the project directory.
// If empty, uses the current working directory.
ProjectDir string
// Targets is the list of proto file glob patterns to process.
// Default: ["./*.proto"]
Targets []string
// Exclude is a list of proto file glob patterns to exclude.
// Files matching any of these patterns will be skipped.
Exclude []string
// Force regenerates all files regardless of cache.
Force bool
// CacheFile is the path to the cache file.
// Default: ".protoc-manifest.json"
CacheFile string
// Verbose enables verbose output.
Verbose bool
// GoLiteFeatures is the go-lite features to enable.
// Default: "marshal+unmarshal+size+equal+json+clone+text"
GoLiteFeatures string
// ToolsDir is the tools directory containing plugin binaries.
// Default: ".tools"
ToolsDir string
// ExtraArgs contains any additional protoc arguments.
ExtraArgs []string
}
Config contains the configuration for proto generation.
func (*Config) GetCacheFilePath ¶
GetCacheFilePath returns the absolute path to the cache file.
func (*Config) GetGoModule ¶
GetGoModule returns the Go module path from go.mod.
func (*Config) GetProjectDir ¶
GetProjectDir returns the project directory, defaulting to cwd.
func (*Config) GetToolsDir ¶
GetToolsDir returns the absolute path to the tools directory.
func (*Config) HasPackageJSON ¶
HasPackageJSON checks if package.json exists in the project directory.
type Generator ¶
type Generator struct {
// Config is the generator configuration.
Config *Config
// Plugins contains the discovered plugins.
Plugins *Plugins
// Cache is the manifest cache.
Cache *Cache
// ProjectDir is the resolved project directory.
ProjectDir string
// ModulePath is the Go module path.
ModulePath string
// VendorDir is the vendor directory.
VendorDir string
// OutDir is the output directory (same as VendorDir).
OutDir string
// Verbose enables verbose output.
Verbose bool
// Stdout is where to write standard output.
Stdout io.Writer
// Stderr is where to write error output.
Stderr io.Writer
}
Generator handles protobuf code generation.
func NewGenerator ¶
NewGenerator creates a new Generator.
type NativePluginHandler ¶
type NativePluginHandler struct {
// Plugins is the configured plugins.
Plugins *Plugins
// Verbose enables verbose output.
Verbose bool
// contains filtered or unexported fields
}
NativePluginHandler implements go-protoc-wasi's PluginHandler interface. It spawns native plugin processes and handles IPC. For protoc-gen-prost, it uses the embedded WASM module instead of a native binary.
func NewNativePluginHandler ¶
func NewNativePluginHandler(plugins *Plugins, verbose bool) *NativePluginHandler
NewNativePluginHandler creates a new NativePluginHandler.
func (*NativePluginHandler) CloseProstWASM ¶ added in v0.30.0
func (h *NativePluginHandler) CloseProstWASM(ctx context.Context) error
CloseProstWASM closes the prost WASM plugin if initialized.
func (*NativePluginHandler) Communicate ¶
func (h *NativePluginHandler) Communicate(ctx context.Context, program string, searchPath bool, input []byte) ([]byte, error)
Communicate implements the PluginHandler interface. It spawns a plugin process, sends the CodeGeneratorRequest via stdin, and returns the CodeGeneratorResponse from stdout. For protoc-gen-prost, it uses the embedded WASM module if initialized.
func (*NativePluginHandler) InitProstWASM ¶ added in v0.30.0
InitProstWASM initializes the prost WASM plugin with the given wazero runtime. The runtime must already have WASI instantiated (e.g., by protoc). This should be called after protoc.Init() and before running protoc.
type PackageInfo ¶
type PackageInfo struct {
// Hash is the content hash of all proto files in this package.
Hash string `json:"hash"`
// GeneratedFiles is the list of generated output files.
GeneratedFiles []string `json:"generatedFiles"`
// ProtoFiles is the list of source proto file paths.
ProtoFiles []string `json:"protoFiles"`
}
PackageInfo contains cached information about a proto package.
type Plugin ¶
type Plugin struct {
// Name is the plugin name (e.g., "go-lite", "es-lite").
Name string
// BinaryName is the executable name (e.g., "protoc-gen-go-lite").
BinaryName string
// Path is the full path to the plugin binary.
Path string
// Type is the plugin type.
Type PluginType
// OutFlag is the output flag name (e.g., "go-lite_out").
OutFlag string
// Options are the plugin options.
Options map[string]string
}
Plugin represents a protoc plugin configuration.
type PluginType ¶
type PluginType int
PluginType represents the type of protoc plugin.
const ( PluginTypeGo PluginType = iota PluginTypeTypeScript PluginTypeCpp PluginTypeRust )
type Plugins ¶
type Plugins struct {
// GoLite is the protoc-gen-go-lite plugin.
GoLite *Plugin
// GoStarpc is the protoc-gen-go-starpc plugin.
GoStarpc *Plugin
// ESLite is the protoc-gen-es-lite plugin.
ESLite *Plugin
// ESStarpc is the protoc-gen-es-starpc plugin.
ESStarpc *Plugin
// CppStarpc is the protoc-gen-starpc-cpp plugin.
CppStarpc *Plugin
// RustStarpc is the protoc-gen-starpc-rust plugin.
RustStarpc *Plugin
// RustProst is the protoc-gen-prost plugin for Rust protobuf types.
// This uses an embedded WASM module, no external binary required.
RustProst *Plugin
}
Plugins holds the configured plugins for a project.
func DiscoverPlugins ¶
DiscoverPlugins finds and configures available plugins.
func (*Plugins) GetProtocArgs ¶
GetProtocArgs returns the protoc arguments for all configured plugins. Note: We don't pass --plugin=<path> because the WASI protoc can't access host binaries. Instead, the PluginHandler intercepts plugin calls by name.
func (*Plugins) HasGoPlugins ¶
HasGoPlugins returns true if Go plugins are configured.
func (*Plugins) HasTSPlugins ¶
HasTSPlugins returns true if TypeScript plugins are configured.
type PostProcessor ¶
type PostProcessor struct {
// ProjectDir is the project directory.
ProjectDir string
// ModulePath is the Go module path.
ModulePath string
// VendorDir is the vendor directory path.
VendorDir string
// Verbose enables verbose output.
Verbose bool
}
PostProcessor handles post-processing of generated files.
func NewPostProcessor ¶
func NewPostProcessor(projectDir, modulePath string, verbose bool) *PostProcessor
NewPostProcessor creates a new PostProcessor.
func (*PostProcessor) ProcessAllCppFiles ¶
func (p *PostProcessor) ProcessAllCppFiles(dir string) error
ProcessAllCppFiles finds and processes all C++ files in a directory.
func (*PostProcessor) ProcessAllTsFiles ¶
func (p *PostProcessor) ProcessAllTsFiles(dir string) error
ProcessAllTsFiles finds and processes all TypeScript files in a directory.
func (*PostProcessor) ProcessCppFile ¶
func (p *PostProcessor) ProcessCppFile(filePath string) error
ProcessCppFile processes a C++ file. - Prepends the Go build tag if not present. - Rewrites include paths from absolute to relative.
func (*PostProcessor) ProcessGeneratedFiles ¶
func (p *PostProcessor) ProcessGeneratedFiles(protoFile string) error
ProcessGeneratedFiles processes all generated files for a proto file.
func (*PostProcessor) ProcessGoFile ¶ added in v0.26.10
func (p *PostProcessor) ProcessGoFile(filePath string) error
ProcessGoFile processes a Go file. Rewrites standard protobuf imports to protobuf-go-lite equivalents.
func (*PostProcessor) ProcessRustFiles ¶ added in v0.30.0
func (p *PostProcessor) ProcessRustFiles(protoFile string) error
ProcessRustFiles moves and processes generated Rust .pb.rs files. Prost generates files at vendor/{package_path}/{basename}.pb.rs based on the protobuf package hierarchy, but we need them at vendor/{module_path}/{proto_dir}/ to match other generated files.
func (*PostProcessor) ProcessTsFile ¶
func (p *PostProcessor) ProcessTsFile(filePath string) error
ProcessTsFile processes a TypeScript file. Rewrites relative import paths to @go/ format for vendor dependencies.
The generated TypeScript files contain relative imports based on the proto file paths. For example, a file generated from "github.com/aperturerobotics/bifrost/daemon/api/api.proto" might import from "../../../controllerbus/bus/api/api.pb.js" which needs to be rewritten to "@go/github.com/aperturerobotics/controllerbus/bus/api/api.pb.js".
Source Files