codegen

package
v3.19.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 23, 2024 License: MIT Imports: 19 Imported by: 1

Documentation

Overview

Package codegen contains the code generation logic to generate gRPC service definitions (.proto files) from the design DSLs and the corresponding server and client code that wraps the goa-generated endpoints with the protocol buffer compiler (protoc) generated clients and servers.

The code generator uses "proto3" syntax for generating the proto files.

The code generator compiles the proto files using the protocol buffer compiler (protoc) with the gRPC in Go plugin. It hooks up the generated protocol buffer types to the goa generated types as follows:

  • It generates a server that implements the protoc-generated gRPC server interface.
  • It generates a client that invokes the protoc-generated gRPC client.
  • It generates encoders and decoders that transforms the protocol buffer types and gRPC metadata into goa types and vice versa.
  • It generates validations to validate the protocol buffer message types and gRPC metadata fields with the validations set in the design.

Index

Constants

View Source 
const (
	// ProtoVersion is the protocol buffer version used to generate .proto files
	ProtoVersion = "proto3"

	// ProtoPrefix is the prefix added to the proto package name.
	ProtoPrefix = "goagen"
)

Variables

View Source 
var GRPCServices = make(ServicesData)

GRPCServices holds the data computed from the design needed to generate the transport code of the gRPC services.

Functions

func ClientCLIFiles 

func ClientCLIFiles(genpkg string, root *expr.RootExpr) []*codegen.File

ClientCLIFiles returns the CLI files to generate a command-line client that makes gRPC requests.

func ClientFiles 

func ClientFiles(genpkg string, root *expr.RootExpr) []*codegen.File

ClientFiles returns the client implementation for every gRPC service. The files include the client which invokes the protoc-generated gRPC client and encoders and decoders to transform protocol buffer types and gRPC metadata into goa types and vice versa.

func ClientTypeFiles 

func ClientTypeFiles(genpkg string, root *expr.RootExpr) []*codegen.File

ClientTypeFiles returns the types file for every gRPC service that contain constructors to transform:

  • service payload types into protocol buffer request message types
  • protocol buffer response message types into service result types

func ExampleCLIFiles 

func ExampleCLIFiles(genpkg string, root *expr.RootExpr) []*codegen.File

ExampleCLIFiles returns an example gRPC client tool implementation.

func ExampleServerFiles 

func ExampleServerFiles(genpkg string, root *expr.RootExpr) []*codegen.File

ExampleServerFiles returns an example gRPC server implementation.

func ProtoFiles 

func ProtoFiles(genpkg string, root *expr.RootExpr) []*codegen.File

ProtoFiles returns a *.proto file for each gRPC service.

func RunGRPCDSL 

func RunGRPCDSL(t *testing.T, dsl func()) *expr.RootExpr

RunGRPCDSL returns the GRPC DSL root resulting from running the given DSL. It is used only in tests.

func ServerFiles 

func ServerFiles(genpkg string, root *expr.RootExpr) []*codegen.File

ServerFiles returns all the server files for every gRPC service. The files contain the server which implements the generated gRPC server interface and encoders and decoders to transform protocol buffer types and gRPC metadata into goa types and vice versa.

func ServerTypeFiles 

func ServerTypeFiles(genpkg string, root *expr.RootExpr) []*codegen.File

ServerTypeFiles returns the types file for every gRPC service that contain constructors to transform:

  • protocol buffer request message types into service payload types
  • service result types into protocol buffer response message types

Types

type ConvertData 

type ConvertData struct {
	// SrcName is the fully qualified name of the source type.
	SrcName string
	// SrcRef is the fully qualified reference to the source type.
	SrcRef string
	// TgtName is the fully qualified name of the target type.
	TgtName string
	// TgtRef is the fully qualified reference to the target type.
	TgtRef string
	// Inits contain the data required to render the constructor if any
	// to transform the source type to a target type. If the source or target
	// type is a goa result type, we generate one constructor for every view
	// defined in the result type.
	Init *InitData
	// Validation contains the data required to render the validation function
	// to validate the initialized type.
	Validation *ValidationData
}

ConvertData contains the data to convert source type to a target type. For request type, it contains data to transform gRPC request type to the corresponding payload type (server) and vice versa (client). For response type, it contains data to transform gRPC response type to the corresponding result type (client) and vice versa (server).

type EndpointData 

type EndpointData struct {
	// ServiceName is the name of the service.
	ServiceName string
	// PkgName is the name of the generated package in *.pb.go.
	PkgName string
	// ServicePkgName is the name of the service package name.
	ServicePkgName string
	// Method is the data for the underlying method expression.
	Method *service.MethodData
	// PayloadType is the type of the payload.
	PayloadType expr.DataType
	// PayloadRef is the fully qualified reference to the method payload.
	PayloadRef string
	// ResultRef is the fully qualified reference to the method result.
	ResultRef string
	// ViewedResultRef is the fully qualified reference to the viewed result.
	ViewedResultRef string
	// Request is the gRPC request data.
	Request *RequestData
	// Response is the gRPC response data.
	Response *ResponseData
	// MetadataSchemes lists all the security requirement schemes that
	// apply to the method and are encoded in the request metadata.
	MetadataSchemes service.SchemesData
	// MessageSchemes lists all the security requirement schemes that
	// apply to the method and are encoded in the request message.
	MessageSchemes service.SchemesData
	// Errors describes the method gRPC errors.
	Errors []*ErrorData

	// ServerStruct is the name of the gRPC server struct.
	ServerStruct string
	// ServerInterface is the name of the gRPC server interface implemented
	// by the service.
	ServerInterface string
	// ServerStream is the server stream data.
	ServerStream *StreamData

	// ClientMethodName is the name of the gRPC method generated by protoc-gen-go.
	ClientMethodName string
	// ClientStruct is the name of the gRPC client struct,
	ClientStruct string
	// ClientInterface is the name of the gRPC client interface implemented
	// by the service.
	ClientInterface string
	// ClientStream is the client stream data.
	ClientStream *StreamData
}

EndpointData contains the data used to render the code related to gRPC endpoint.

type ErrorData 

type ErrorData struct {
	// StatusCode is the response gRPC status code.
	StatusCode string
	// Name is the error name.
	Name string
	// Ref is a reference to the error type.
	Ref string
	// Response is the error response data.
	Response *ResponseData
}

ErrorData contains the error information required to generate the transport decode (client) and encode (server) code.

type InitArgData 

type InitArgData struct {
	// Name is the argument name.
	Name string
	// Description is the argument description.
	Description string
	// Reference to the argument, e.g. "&body".
	Ref string
	// FieldName is the name of the data structure field that should
	// be initialized with the argument if any.
	FieldName string
	// FieldType is the type of the data structure field that should be
	// initialized with the argument if any.
	FieldType expr.DataType
	// TypeName is the argument type name.
	TypeName string
	// TypeRef is the argument type reference.
	TypeRef string
	// Type is the argument type. It is never an aliased user type.
	Type expr.DataType
	// Pointer is true if a pointer to the arg should be used.
	Pointer bool
	// Required is true if the arg is required to build the payload.
	Required bool
	// DefaultValue is the default value of the arg.
	DefaultValue any
	// Validate contains the validation code for the argument
	// value if any.
	Validate string
	// Example is a example value
	Example any
}

InitArgData represents a single constructor argument.

type InitData 

type InitData struct {
	// Name is the constructor function name.
	Name string
	// Description is the function description.
	Description string
	// Args is the list of constructor arguments.
	Args []*InitArgData
	// ReturnVarName is the name of the variable to be returned.
	ReturnVarName string
	// ReturnTypeRef is the qualified (including the package name)
	// reference to the return type.
	ReturnTypeRef string
	// ReturnTypePkg is the package where the return type is present.
	ReturnTypePkg string
	// ReturnIsStruct is true if the return type is a struct.
	ReturnIsStruct bool
	// Code is the transformation code.
	Code string
}

InitData contains the data required to render a constructor.

type MetadataData 

type MetadataData struct {
	// Name is the name of the metadata key.
	Name string
	// AttributeName is the name of the corresponding attribute.
	AttributeName string
	// Description is the metadata description.
	Description string
	// FieldName is the name of the struct field that holds the
	// metadata value if any, empty string otherwise.
	FieldName string
	// FieldType is the type of the struct field.
	FieldType expr.DataType
	// VarName is the name of the Go variable used to read or
	// convert the metadata value.
	VarName string
	// TypeName is the name of the type.
	TypeName string
	// TypeRef is the reference to the type.
	TypeRef string
	// Required is true if the metadata is required.
	Required bool
	// Pointer is true if and only the metadata variable is a pointer.
	Pointer bool
	// StringSlice is true if the metadata value type is array of strings.
	StringSlice bool
	// Slice is true if the metadata value type is an array.
	Slice bool
	// MapStringSlice is true if the metadata value type is a map of string
	// slice.
	MapStringSlice bool
	// Map is true if the metadata value type is a map.
	Map bool
	// Type describes the datatype of the variable value. Mainly
	// used for conversion.
	Type expr.DataType
	// Validate contains the validation code if any.
	Validate string
	// DefaultValue contains the default value if any.
	DefaultValue any
	// Example is an example value.
	Example any
}

MetadataData describes a gRPC metadata field.

type RequestData 

type RequestData struct {
	// Description is the request description.
	Description string
	// Message is the gRPC request message.
	Message *service.UserTypeData
	// Metadata is the request metadata.
	Metadata []*MetadataData
	// ServerConvert is the request data with constructor function to
	// initialize the method payload type from the generated payload type in
	// *.pb.go.
	ServerConvert *ConvertData
	// ClientConvert is the request data with constructor function to
	// initialize the generated payload type in *.pb.go from the
	// method payload.
	ClientConvert *ConvertData
	// CLIArgs is the list of arguments for the command-line client.
	// This is set only for the client side.
	CLIArgs []*InitArgData
}

RequestData describes a gRPC request.

type ResponseData 

type ResponseData struct {
	// StatusCode is the return code of the response.
	StatusCode string
	// Description is the response description.
	Description string
	// Message is the gRPC response message.
	Message *service.UserTypeData
	// Headers is the response header metadata.
	Headers []*MetadataData
	// Trailers is the response trailer metadata.
	Trailers []*MetadataData
	// ServerConvert is the type data with constructor function to
	// initialize the generated response type in *.pb.go from the
	// method result type or the projected result type.
	ServerConvert *ConvertData
	// ClientConvert is the type data with constructor function to
	// initialize the method result type or the projected result type
	// from the generated response type in *.pb.go.
	ClientConvert *ConvertData
}

ResponseData describes a gRPC success or error response.

type ServiceData 

type ServiceData struct {
	// Service contains the related service data.
	Service *service.Data
	// PkgName is the name of the generated package in *.pb.go.
	PkgName string
	// ProtoImports is the list of proto package imports.
	ProtoImports []string
	// Name is the service name.
	Name string
	// Description is the service description.
	Description string
	// Endpoints describes the gRPC service endpoints.
	Endpoints []*EndpointData
	// Messages describes the message data for this service.
	Messages []*service.UserTypeData
	// ServerStruct is the name of the gRPC server struct.
	ServerStruct string
	// ClientStruct is the name of the gRPC client struct,
	ClientStruct string
	// ServerInit is the name of the constructor of the server struct.
	ServerInit string
	// ClientInit is the name of the constructor of the client struct.
	ClientInit string
	// ServerInterface is the name of the gRPC server interface implemented
	// by the service.
	ServerInterface string
	// ClientInterface is the name of the gRPC client interface implemented
	// by the service.
	ClientInterface string
	// ClientInterfaceInit is the name of the client constructor function in
	// the generated pb.go package.
	ClientInterfaceInit string
	// Scope is the name scope for protocol buffers
	Scope *codegen.NameScope
	// contains filtered or unexported fields
}

ServiceData contains the data used to render the code related to a single service.

func (*ServiceData) Endpoint 

func (sd *ServiceData) Endpoint(name string) *EndpointData

Endpoint returns the endoint data for the endpoint with the given name, nil if there isn't one.

func (*ServiceData) HasStreamingEndpoint 

func (sd *ServiceData) HasStreamingEndpoint() bool

HasStreamingEndpoint returns true if the service has at least one streaming endpoint.

func (*ServiceData) HasUnaryEndpoint 

func (sd *ServiceData) HasUnaryEndpoint() bool

HasUnaryEndpoint returns true if the service has at least one unary endpoint.

type ServicesData 

type ServicesData map[string]*ServiceData

ServicesData contains the data computed from the gRPC service expressions indexed by service name.

func (ServicesData) Get 

func (d ServicesData) Get(name string) *ServiceData

Get retrieves the transport data for the service with the given name computing it if needed. It returns nil if there is no service with the given name.

type StreamData 

type StreamData struct {
	// VarName is the name of the struct type.
	VarName string
	// Type is the stream type (client or server).
	Type string
	// ServiceInterface is the service interface that the struct implements.
	ServiceInterface string
	// Interface is the stream interface in *.pb.go stored in the struct.
	Interface string
	// Endpoint is the streaming endpoint data.
	Endpoint *EndpointData
	// SendName is the name of the send function.
	SendName string
	// SendDesc is the description for the send function.
	SendDesc string
	// SendRef is the fully	qualified reference to the type sent across the
	// stream.
	SendRef string
	// SendConvert is the type sent through the stream. It contains the
	// constructor to convert the service send type to the type expected by
	// the gRPC send type (in *.pb.go)
	SendConvert *ConvertData
	// RecvConvert is the type received through the stream. It contains the
	// constructor to convert the gRPC type (in *.pb.go) to the service receive
	// type.
	RecvConvert *ConvertData
	// RecvName is the name of the receive function.
	RecvName string
	// RecvDesc is the description for the recv function.
	RecvDesc string
	// RecvRef is the fully	qualified reference to the type received from the
	// stream.
	RecvRef string
	// MustClose indicates whether to generate the Close() function
	// for the stream.
	MustClose bool
}

StreamData contains data to render the stream struct type that implements the service stream interface.

type ValidationData 

type ValidationData struct {
	// Name is the validation function name.
	Name string
	// Def is the validation function definition.
	Def string
	// VarName is the name of the argument.
	ArgName string
	// SrcName is the fully qualified name of the type being validated.
	SrcName string
	// SrcRef is the fully qualified reference to the type being validated.
	SrcRef string
	// Kind indicates that the validation is for request (server-side),
	// response (client-side), or both (server and client side) messages.
	// It is used to generate validation code in the server and client packages.
	Kind validateKind
}

ValidationData contains the data necessary to render the validation function.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.