codegenerator

README

codegenerator

codegenerator is an implementation of remote code generation for custom plugins to integrate with the buf CLI.

It implements the buf.alpha.registry.v1alpha1.CodeGenerationService service interface.

It expects a locally executable registry to be available at CODEGENERATOR_REGISTRY_PATH.

The format of this path must be <owner>/<plugin>/<version>/<plugin>

• plugin is the name of the binary (e.g. protoc-gen-doc).
• version must be of the from v\d+\.\d+\.\d+

Assuming you host this service at codegenerator.build you can reference your plugins in buf.gen.yaml as follows:

version: v2

plugins:
 - remote: codegenerator.build/<owner>/<plugin>:<version>
   out: generated

Documentation

Index

• func ImageFileToDescriptor(img *imagev1.ImageFile) *descriptorpb.FileDescriptorProto
• func ImageToCodeGeneratorRequest(image *imagev1.Image, plug *v1alpha1.PluginGenerationRequest) (*pluginpb.CodeGeneratorRequest, error)
• func IsWellKnownType(name string) bool
• type Plugin
  • func (p *Plugin) Generate(ctx context.Context, req *pluginpb.CodeGeneratorRequest) (*pluginpb.CodeGeneratorResponse, error)
• type Registry
  • func LocalRegistry(path string) *Registry
  • func (r *Registry) Get(ref *v1alpha1.CuratedPluginReference) (*Plugin, error)
• type Service
  • func (s *Service) GenerateCode(ctx context.Context, req *connect.Request[v1alpha1.GenerateCodeRequest]) (*connect.Response[v1alpha1.GenerateCodeResponse], error)

Functions

func ImageFileToDescriptor

func ImageFileToDescriptor(img *imagev1.ImageFile) *descriptorpb.FileDescriptorProto

ImageFileToDescriptor maps a buf.ImageFile to it's FileDescriptorProto.

A buf.ImageFile is essentially just a wrapper around FileDescriptorProto, but with some additional buf specific extensions, which aren't relevant for us here (they are relevant in ImageToCodeGenerationRequest).

func ImageToCodeGeneratorRequest

func ImageToCodeGeneratorRequest(image *imagev1.Image, plug *v1alpha1.PluginGenerationRequest) (*pluginpb.CodeGeneratorRequest, error)

ImageToCodeGeneratorRequest builds a CodeGeneratorRequest from an Image (FileDescriptorSet, with extra bits) and a PluginGenerationRequest, which contains the plugin configuration (i.e. opts, include_imports, include_well_known_types).

func IsWellKnownType

func IsWellKnownType(name string) bool

IsWellKnownType marks a proto file as a well-known type, based on its filepath.

Types

type Plugin

type Plugin struct {
	Path    string
	Name    string
	Version string
}

Plugin wraps a plugin binary for local execution.

func (*Plugin) Generate

func (p *Plugin) Generate(ctx context.Context, req *pluginpb.CodeGeneratorRequest) (*pluginpb.CodeGeneratorResponse, error)

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry is the container which points to all available plugins.

func LocalRegistry

func LocalRegistry(path string) *Registry

LocalRegistry reads the available plugins from the folder structure at "path".

It will panic if the folder structure does not match our expectations.

The expectation is that for a remote plugin request of `<host>/<owner>/<plugin>:<version>`

e.g. ``` # buf.gen.yaml plugins: - remote: <host>/<owner>/<plugin>:<version> ```

There is an executable file at `<owner>/<plugin>/<version>/<plugin>`

<version> is required to match `v1.2.3` (or `/v\d+\.\d+\.\d+`).

func (*Registry) Get

func (r *Registry) Get(ref *v1alpha1.CuratedPluginReference) (*Plugin, error)

Get gets a plugin, if registered.

* Version must be set. * Revision must not be set.

type Service

type Service struct {
	Registry *Registry
}

func (*Service) GenerateCode

func (s *Service) GenerateCode(
	ctx context.Context,
	req *connect.Request[v1alpha1.GenerateCodeRequest],
) (*connect.Response[v1alpha1.GenerateCodeResponse], error)