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 ApplyInsertionPoint(ctx context.Context, insertionPointFile *pluginpb.CodeGeneratorResponse_File, ...) (_ []byte, retErr error)
• func Main(ctx context.Context, handler Handler)
• func Run(ctx context.Context, container app.Container, handler Handler) error
• type GenerateOption
  • func GenerateWithInsertionPointReadBucket(insertionPointReadBucket storage.ReadBucket) GenerateOption
• 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 ResponseWriter
  • func NewResponseWriter(container app.StderrContainer) ResponseWriter

Functions

func ApplyInsertionPoint

func ApplyInsertionPoint(
	ctx context.Context,
	insertionPointFile *pluginpb.CodeGeneratorResponse_File,
	targetFile io.Reader,
) (_ []byte, retErr error)

ApplyInsertionPoint applies the insertion point defined in insertionPointFile to the targetFile and returns the result as []byte. The caller must ensure the provided targetFile matches the file requested in insertionPointFile.Name.

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.

Types

type GenerateOption

type GenerateOption func(*generateOptions)

GenerateOption is an option for Generate.

func GenerateWithInsertionPointReadBucket

func GenerateWithInsertionPointReadBucket(
	insertionPointReadBucket storage.ReadBucket,
) GenerateOption

GenerateWithInsertionPointReadBucket returns a new GenerateOption that uses the given ReadBucket to read from for insertion points.

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

type Generator

type Generator interface {
	// Generate generates to the bucket.
	Generate(
		ctx context.Context,
		container app.EnvStderrContainer,
		writeBucket storage.WriteBucket,
		requests []*pluginpb.CodeGeneratorRequest,
		options ...GenerateOption,
	) error
}

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

This invokes a Handler and writes out the response to the output location, additionally accounting for insertion point 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 ResponseWriter,
		request *pluginpb.CodeGeneratorRequest,
	) error
}

Handler is a protoc plugin handler

type HandlerFunc

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

HandlerFunc is a handler function.

func (HandlerFunc) Handle

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

Handle implements Handler.

type ResponseWriter

type ResponseWriter interface {
	// Add 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()
	// ToResponse returns the resulting CodeGeneratorResponse. This must
	// only be called after all writing has been completed.
	ToResponse() *pluginpb.CodeGeneratorResponse
}

ResponseWriter handles CodeGeneratorResponses.

func NewResponseWriter

func NewResponseWriter(container app.StderrContainer) ResponseWriter

NewReponseWriter returns a new ResponseWriter.