0
# Core Plugin System
1

2
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.
3

4
## Entry Points
5

6
### Main Plugin Entry Point
7

8
```go { .api }
9
func main()
10
```
11

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

14
Usage in main.go:
15
```go
16
optional := uint64(pluginpb.CodeGeneratorResponse_FEATURE_PROTO3_OPTIONAL)
17
pgs.
18
  Init(pgs.DebugEnv("DEBUG_PGV"), pgs.SupportedFeatures(&optional)).
19
  RegisterModule(module.Validator()).
20
  RegisterPostProcessor(pgsgo.GoFmt()).
21
  Render()
22
```
23

24
### Language-Specific Entry Points
25

26
```go { .api }
27
func main() // in cmd/protoc-gen-validate-go/main.go
28
func main() // in cmd/protoc-gen-validate-java/main.go  
29
func main() // in cmd/protoc-gen-validate-cpp/main.go
30
```
31

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

34
Example for Go-specific plugin:
35
```go
36
pgs.
37
  Init(pgs.DebugEnv("DEBUG_PGV"), pgs.SupportedFeatures(&optional)).
38
  RegisterModule(module.ValidatorForLanguage("go")).
39
  RegisterPostProcessor(pgsgo.GoFmt()).
40
  Render()
41
```
42

43
## Module System
44

45
### Core Module Type
46

47
```go { .api }
48
type Module struct {
49
  *pgs.ModuleBase
50
  ctx pgsgo.Context
51
  lang string
52
}
53
```
54

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

57
**Fields:**
58
- `*pgs.ModuleBase`: Embedded PGS base module functionality
59
- `ctx pgsgo.Context`: Go language-specific context for code generation
60
- `lang string`: Target language ("go", "java", "cc")
61

62
### Module Constructors
63

64
```go { .api }
65
func Validator() pgs.Module
66
```
67

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

70
**Returns:** Module interface for PGS framework
71

72
```go { .api }
73
func ValidatorForLanguage(lang string) pgs.Module
74
```
75

76
Creates a validator module for a specific target language.
77

78
**Parameters:**
79
- `lang string`: Target language ("go", "java", "cc")
80

81
**Returns:** Module interface with pre-configured language
82

83
### Module Methods
84

85
```go { .api }
86
func (m *Module) Name() string
87
```
88

89
Returns the module name identifier used by the PGS framework.
90

91
**Returns:** "validator"
92

93
```go { .api }
94
func (m *Module) InitContext(ctx pgs.BuildContext)
95
```
96

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

99
**Parameters:**
100
- `ctx pgs.BuildContext`: PGS build context containing parameters and environment
101

102
```go { .api }
103
func (m *Module) Execute(targets map[string]pgs.File, pkgs map[string]pgs.Package) []pgs.Artifact
104
```
105

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

108
**Parameters:**
109
- `targets map[string]pgs.File`: Map of target proto files to process
110
- `pkgs map[string]pgs.Package`: Map of packages involved in generation
111

112
**Returns:** `[]pgs.Artifact` - Generated artifacts for output
113

114
**Process:**
115
1. Determines target language from parameters or pre-configuration
116
2. Validates all messages for rule consistency using `CheckRules`
117
3. Applies language-specific templates to generate code
118
4. Handles special cases like Java multiple file generation
119
5. Returns generated artifacts for writing
120

121
## Parameters
122

123
The plugin accepts several parameters to control generation:
124

125
### Language Parameter
126
- **Name**: `lang`
127
- **Values**: `"go"`, `"java"`, `"cc"`
128
- **Description**: Specifies target language for code generation
129

130
### Module Parameter
131
- **Name**: `module`
132
- **Description**: Go module path for import generation
133
- **Example**: `"github.com/example/project"`
134

135
## Rule Checking
136

137
```go { .api }
138
func (m *Module) CheckRules(msg pgs.Message)
139
```
140

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

143
**Parameters:**
144
- `msg pgs.Message`: Protocol buffer message to validate rules for
145

146
**Behavior:**
147
- Ensures numeric ranges don't contradict (e.g., `gt: 10, lt: 5`)
148
- Validates string length constraints are consistent
149
- Checks enum value constraints
150
- Reports errors for invalid rule combinations
151

152
## Usage Examples
153

154
### Basic Plugin Usage
155

156
```bash
157
protoc \
158
  -I . \
159
  -I path/to/validate/ \
160
  --go_out="./generated" \
161
  --validate_out="lang=go:./generated" \
162
  example.proto
163
```
164

165
### With Module Parameter
166

167
```bash
168
protoc \
169
  --validate_out="lang=go,module=github.com/example/project:./generated" \
170
  example.proto
171
```
172

173
### Using Buf CLI
174

175
```yaml
176
# buf.gen.yaml
177
version: v1
178
plugins:
179
  - plugin: buf.build/bufbuild/validate-go
180
    out: gen
181
```
182

183
## Error Handling
184

185
The plugin will fail with descriptive errors for:
186
- Missing `lang` parameter when not pre-configured
187
- Contradictory validation rules in proto files
188
- Template processing errors
189
- File generation failures
190

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