pb

Documentation

Overview

Package pb encapsulates the protoc execution logic.

Index

• Constants
• func CheckVersionGreaterThanOrEqualTo(version, required string) bool
• func IsInternalProto(fname string) bool
• func Protoc(protodirs []string, protofile, lang, outputdir string, opts ...Option) error
• type Option
  • func WithDescriptorSetIn(descriptorSetIn string) Option
  • func WithPb2ImportPath(m map[string]string) Option
  • func WithPkg2ImportPath(m map[string]string) Option
  • func WithSecvEnabled(enabled bool) Option
  • func WithValidateEnabled(enabled bool) Option

Constants

const (
	ProtoTRPC              = "trpc/proto/trpc_options.proto"
	ProtoValidate          = "trpc/validate/validate.proto"
	ProtoProtocGenValidate = "validate/validate.proto" // https://github.com/bufbuild/protoc-gen-validate
	ProtoSwagger           = "trpc/swagger/swagger.proto"

	ProtoDir         = "protobuf"
	TrpcImportPrefix = "trpc/"
)

Constants definition.

Functions

func CheckVersionGreaterThanOrEqualTo

func CheckVersionGreaterThanOrEqualTo(version, required string) bool

CheckVersionGreaterThanOrEqualTo check if version meet the requirement

func IsInternalProto

func IsInternalProto(fname string) bool

IsInternalProto tests if `fname` is internal.

func Protoc

func Protoc(protodirs []string, protofile, lang, outputdir string, opts ...Option) error

Protoc process `protofile` to generate *.pb.go, which is specified by `language`

When using protoc, the following should also be taken into consideration: 1. The pb file being processed may import other pb files, e.g., a.proto imports b.proto, and the resulting a.pb.go file will call the initialization function in b.pb.go, typically named file_${path_to}b_proto_init(); 2. When executing protoc, the options passed can have an impact on the generated code. For instance, protoc -I path-to a.proto and protoc path-to/a.proto will generate different code, with the difference being reflected in the function name file${path_to}_b_proto_init(). The former will generate an empty ${path_to} part, leading to compilation failure.

How to avoid this problem?

• The import statements in pb files may contain virtual path information, which needs to be determined based on the search path specified with -I.
• When processing pb files with protoc, the pb file names must contain virtual path information. For example, it should be protoc path-to/a.proto instead of protoc -I path-to a.proto.
• Additionally, it is essential that there exists a search path in protoc's search path list that is the parent path of the pb file being processed. This is because of how protoc resolves paths.

About the use of optional labels in proto syntax3: Compatibility logic needs to be implemented for different versions of protoc:

• protoc (~, v3.12.0), pb syntax3 does not support optional labels
• protoc [v3.12.0, v3.15.0), pb syntax3 supports optional labels, but the option --experimental_allow_proto3_optional needs to be added.
• protoc v3.15.0+, optional labels in pb syntax3 syntax are parsed by default.

------------------------------------------------------------------------------------------------------------------

Regarding the issue of output paths for pb.go files: The paths=source_relative option controls the output filenames, not the import paths. The proto compiler associates an import path with each .proto file. When a.proto imports b.proto, the import path is used to determine what (if any) import statement to put in a.pb.go. You can set the import paths with go_package options in the .proto files, or with --go_opt=M<filename>=<import_path> on the command line.

The proto compiler generates a .pb.go file for each .proto file. There are several ways in which the output directory may be determined. For example, if source/a.proto has an import path of example.com/m/foo:

--go_opt=paths=import: Import path; e.g., example.com/m/foo/a.pb.go --go_opt=paths=source_relative: Source path; e.g., source/a.pb.go --go_opt=module=example.com/m: Path relative to the module flag; e.g., foo/a.pb.go

In the worst case, if none of these suit your needs, you can always generate into a temporary directory and copy the file into the desired location. Neither the paths nor module flags have any effect on the contents of the generated files.

Types

type Option

type Option func(*options)

Option is used to store the content of the relevant options.

func WithDescriptorSetIn

func WithDescriptorSetIn(descriptorSetIn string) Option

WithDescriptorSetIn adds the descriptor_set_in option to the command.

func WithPb2ImportPath

func WithPb2ImportPath(m map[string]string) Option

WithPb2ImportPath adds mapping between pb file and import path.

func WithPkg2ImportPath

func WithPkg2ImportPath(m map[string]string) Option

WithPkg2ImportPath adds the mapping between package name and import path.

func WithSecvEnabled

func WithSecvEnabled(enabled bool) Option

WithSecvEnabled enables validation and generates stub code using protoc-gen-secv. Note: protoc-gen-secv is a modified version of protoc-gen-validate. protoc-gen-secv is still not opensourced. Please use WithValidationEnabled instead.

func WithValidateEnabled

func WithValidateEnabled(enabled bool) Option

WithValidateEnabled enables validation and generates stub code using protoc-gen-validate. https://github.com/bufbuild/protoc-gen-validate/tree/v1.0.2