Core Plugin System

The core plugin system provides the main protoc plugin functionality built on the protoc-gen-star framework. It handles proto file processing, module management, and code generation orchestration.

Entry Points

Main Plugin Entry Point

func main()

Main entry point for the protoc plugin. Initializes the PGS framework with proto3 optional support and registers the validator module.

Usage in main.go:

optional := uint64(pluginpb.CodeGeneratorResponse_FEATURE_PROTO3_OPTIONAL)
pgs.
  Init(pgs.DebugEnv("DEBUG_PGV"), pgs.SupportedFeatures(&optional)).
  RegisterModule(module.Validator()).
  RegisterPostProcessor(pgsgo.GoFmt()).
  Render()

Language-Specific Entry Points

func main() // in cmd/protoc-gen-validate-go/main.go
func main() // in cmd/protoc-gen-validate-java/main.go  
func main() // in cmd/protoc-gen-validate-cpp/main.go

Language-specific plugin entry points that pre-configure the target language.

Example for Go-specific plugin:

pgs.
  Init(pgs.DebugEnv("DEBUG_PGV"), pgs.SupportedFeatures(&optional)).
  RegisterModule(module.ValidatorForLanguage("go")).
  RegisterPostProcessor(pgsgo.GoFmt()).
  Render()

Module System

Core Module Type

type Module struct {
  *pgs.ModuleBase
  ctx pgsgo.Context
  lang string
}

Core PGV module implementing the PGS Module interface. Contains embedded base module, Go language context, and target language configuration.

Fields:

• *pgs.ModuleBase: Embedded PGS base module functionality
• ctx pgsgo.Context: Go language-specific context for code generation
• lang string: Target language ("go", "java", "cc")

Module Constructors

func Validator() pgs.Module

Creates a new validator module instance with language determined by parameters.

Returns: Module interface for PGS framework

func ValidatorForLanguage(lang string) pgs.Module

Creates a validator module for a specific target language.

Parameters:

• lang string: Target language ("go", "java", "cc")

Returns: Module interface with pre-configured language

Module Methods

func (m *Module) Name() string

Returns the module name identifier used by the PGS framework.

Returns: "validator"

func (m *Module) InitContext(ctx pgs.BuildContext)

Initializes the module with the PGS build context and sets up language-specific context.

Parameters:

• ctx pgs.BuildContext: PGS build context containing parameters and environment

func (m *Module) Execute(targets map[string]pgs.File, pkgs map[string]pgs.Package) []pgs.Artifact

Main execution method that processes proto files and generates validation code.

Parameters:

• targets map[string]pgs.File: Map of target proto files to process
• pkgs map[string]pgs.Package: Map of packages involved in generation

Returns: []pgs.Artifact - Generated artifacts for output

Process:

1. Determines target language from parameters or pre-configuration
2. Validates all messages for rule consistency using CheckRules
3. Applies language-specific templates to generate code
4. Handles special cases like Java multiple file generation
5. Returns generated artifacts for writing

Parameters

The plugin accepts several parameters to control generation:

Language Parameter

• Name: lang
• Values: "go", "java", "cc"
• Description: Specifies target language for code generation

Module Parameter

• Name: module
• Description: Go module path for import generation
• Example: "github.com/example/project"

Rule Checking

func (m *Module) CheckRules(msg pgs.Message)

Validates that validation rules applied to message fields are consistent and don't contradict each other. Called automatically during Execute for all messages.

Parameters:

• msg pgs.Message: Protocol buffer message to validate rules for

Behavior:

• Ensures numeric ranges don't contradict (e.g., gt: 10, lt: 5)
• Validates string length constraints are consistent
• Checks enum value constraints
• Reports errors for invalid rule combinations

Usage Examples

Basic Plugin Usage

protoc \
  -I . \
  -I path/to/validate/ \
  --go_out="./generated" \
  --validate_out="lang=go:./generated" \
  example.proto

With Module Parameter

protoc \
  --validate_out="lang=go,module=github.com/example/project:./generated" \
  example.proto

Using Buf CLI

# buf.gen.yaml
version: v1
plugins:
  - plugin: buf.build/bufbuild/validate-go
    out: gen

Error Handling

The plugin will fail with descriptive errors for:

• Missing lang parameter when not pre-configured
• Contradictory validation rules in proto files
• Template processing errors
• File generation failures

Errors are reported through the PGS framework's error handling system and will cause protoc to exit with a non-zero status code.