appproto

Documentation

Overview

Package appproto contains helper functionality for protoc plugins.

Note this is currently implicitly tested through buf's protoc command. If this were split out into a separate package, testing would need to be moved to this package.

Index

• func Main(ctx context.Context, handler Handler)
• func Run(ctx context.Context, container app.Container, handler Handler) error
• func ValidatePluginResponses(pluginResponses []*PluginResponse) error
• type Generator
  • func NewGenerator(logger *zap.Logger, handler Handler) Generator
• type Handler
• type HandlerFunc
  • func (h HandlerFunc) Handle(ctx context.Context, container app.EnvStderrContainer, ...) error
• type PluginResponse
  • func NewPluginResponse(response *pluginpb.CodeGeneratorResponse, pluginName string, pluginOut string) *PluginResponse
• type ResponseBuilder
  • func NewResponseBuilder(container app.StderrContainer) ResponseBuilder
• type ResponseWriter
  • func NewResponseWriter(logger *zap.Logger) ResponseWriter
• type WriteResponseOption
  • func WriteResponseWithInsertionPointReadBucket(insertionPointReadBucket storage.ReadBucket) WriteResponseOption

Functions

func Main

func Main(ctx context.Context, handler Handler)

Main runs the plugin using app.Main and the Handler.

func Run

func Run(ctx context.Context, container app.Container, handler Handler) error

Run runs the plugin using app.Main and the Handler.

The exit code can be determined using app.GetExitCode.

func ValidatePluginResponses

func ValidatePluginResponses(pluginResponses []*PluginResponse) error

ValidatePluginResponses validates that each file is only defined by a single *PluginResponse.

Types

type Generator

type Generator interface {
	// Generate generates a CodeGeneratorResponse for the given CodeGeneratorRequests.
	//
	// A new ResponseBuilder is constructed for every invocation of Generate and is
	// used to consolidate all of the CodeGeneratorResponse_Files returned from a single
	// plugin into a single CodeGeneratorResponse.
	Generate(
		ctx context.Context,
		container app.EnvStderrContainer,
		requests []*pluginpb.CodeGeneratorRequest,
	) (*pluginpb.CodeGeneratorResponse, error)
}

Generator executes the Handler using protoc's plugin execution logic.

If multiple requests are specified, these are executed in parallel and the result is combined into one response that is written.

func NewGenerator

func NewGenerator(
	logger *zap.Logger,
	handler Handler,
) Generator

NewGenerator returns a new Generator.

type Handler

type Handler interface {
	// Handle handles the plugin.
	//
	// This function can assume the request is valid.
	// This should only return error on system error.
	// Plugin generation errors should be added with AddError.
	// See https://github.com/protocolbuffers/protobuf/blob/95e6c5b4746dd7474d540ce4fb375e3f79a086f8/src/google/protobuf/compiler/plugin.proto#L100
	Handle(
		ctx context.Context,
		container app.EnvStderrContainer,
		responseWriter ResponseBuilder,
		request *pluginpb.CodeGeneratorRequest,
	) error
}

Handler is a protoc plugin handler.

type HandlerFunc

type HandlerFunc func(
	context.Context,
	app.EnvStderrContainer,
	ResponseBuilder,
	*pluginpb.CodeGeneratorRequest,
) error

HandlerFunc is a handler function.

func (HandlerFunc) Handle

func (h HandlerFunc) Handle(
	ctx context.Context,
	container app.EnvStderrContainer,
	responseWriter ResponseBuilder,
	request *pluginpb.CodeGeneratorRequest,
) error

Handle implements Handler.

type PluginResponse

type PluginResponse struct {
	Response   *pluginpb.CodeGeneratorResponse
	PluginName string
	PluginOut  string
}

PluginResponse encapsulates a CodeGeneratorResponse, along with the name of the plugin that created it.

func NewPluginResponse

func NewPluginResponse(
	response *pluginpb.CodeGeneratorResponse,
	pluginName string,
	pluginOut string,
) *PluginResponse

NewPluginResponse retruns a new *PluginResponse.

type ResponseBuilder

type ResponseBuilder interface {
	// AddFile adds the file to the response.
	//
	// Returns error if nil or the name is empty.
	// Warns to stderr if the name is already added or the name is not normalized.
	AddFile(*pluginpb.CodeGeneratorResponse_File) error
	// AddError adds the error message to the response.
	//
	// If there is an existing error message, this will be concatenated with a newline.
	// If message is empty, a message "error" will be added.
	AddError(message string)
	// SetFeatureProto3Optional sets the proto3 optional feature.
	SetFeatureProto3Optional()
	// contains filtered or unexported methods
}

ResponseBuilder builds CodeGeneratorResponses.

func NewResponseBuilder

func NewResponseBuilder(container app.StderrContainer) ResponseBuilder

NewResponseBuilder returns a new ResponseBuilder.

type ResponseWriter

type ResponseWriter interface {
	// WriteResponse writes to the bucket with the given response. In practice, the
	// WriteBucket is most often an in-memory bucket.
	//
	// CodeGeneratorResponses are consolidated into the bucket, and insertion points
	// are applied in-place so that they can only access the files created in a single
	// generation invocation (just like protoc).
	WriteResponse(
		ctx context.Context,
		writeBucket storage.WriteBucket,
		response *pluginpb.CodeGeneratorResponse,
		options ...WriteResponseOption,
	) error
}

ResponseWriter handles the response and writes it to the given storage.WriteBucket without executing any plugins and handles insertion points as needed.

func NewResponseWriter

func NewResponseWriter(logger *zap.Logger) ResponseWriter

NewResponseWriter returns a new ResponseWriter.

type WriteResponseOption

type WriteResponseOption func(*writeResponseOptions)

WriteResponseOption is an option for WriteResponse.

func WriteResponseWithInsertionPointReadBucket

func WriteResponseWithInsertionPointReadBucket(
	insertionPointReadBucket storage.ReadBucket,
) WriteResponseOption

WriteResponseWithInsertionPointReadBucket returns a new WriteResponseOption that uses the given ReadBucket to read from for insertion points.

If this is not specified, insertion points are not supported.