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: 20 Imported by: 7

Documentation

Overview

Package codegen contains code generation algorithms that produce HTTP servers and clients meant to call - or wrap - the Goa endpoints generated by the service package.

Index

Constants

This section is empty.

Variables

View Source 
var HTTPServices = make(ServicesData)

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

Functions

func AddMarshalTags added in v3.2.0 

func AddMarshalTags(att *expr.AttributeExpr, seen map[string]struct{})

AddMarshalTags adds JSON, XML and Form tags to all inline object attributes recursively.

func ClientCLIFiles 

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

ClientCLIFiles returns the client HTTP CLI support file.

func ClientFiles 

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

ClientFiles returns the generated HTTP client files.

func ClientTypeFiles 

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

ClientTypeFiles returns the HTTP transport client types files.

func ExampleCLIFiles 

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

ExampleCLIFiles returns an example client tool HTTP implementation for each server expression.

func ExampleServerFiles 

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

ExampleServerFiles returns an example http service implementation.

func OpenAPIFiles 

func OpenAPIFiles(root *expr.RootExpr) ([]*codegen.File, error)

OpenAPIFiles returns the files for the OpenAPIFile spec of the given HTTP API.

func PathFiles 

func PathFiles(root *expr.RootExpr) []*codegen.File

PathFiles returns the service path files.

func RunHTTPDSL 

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

RunHTTPDSL returns the HTTP DSL root resulting from running the given DSL.

func ServerFiles 

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

ServerFiles returns the generated HTTP server files.

func ServerTypeFiles 

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

ServerTypeFiles returns the HTTP transport type files.

Types

type AttributeData added in v3.2.0 

type AttributeData struct {
	// Name is the name of the attribute.
	Name string
	// VarName is the name of the variable that holds the attribute value.
	VarName string
	// Pointer is true if the attribute value is a pointer.
	Pointer bool
	// Required is true if the attribute is required in the parent attribute.
	Required bool
	// Type is the attribute type.
	Type expr.DataType
	// TypeName is the generated attribute type name.
	TypeName string
	// TypeRef is the generated attribute type reference.
	TypeRef string
	// Description is the attribute description as defined in the design.
	Description string
	// FieldName is the name of the data structure field that should
	// be initialized with the value if any.
	FieldName string
	// FieldType is the type of the data structure field that should be
	// initialized with the attribute value or read into the attribute value.
	FieldType expr.DataType
	// FieldPointer if true indicates that the data structure field is a
	// pointer.
	FieldPointer bool
	// DefaultValue is the default value of the attribute if any.
	DefaultValue any
	// Validate contains the validation code for the attribute value if any.
	Validate string
	// Example is an example attribute value
	Example any
}

AttributeData contains the information needed to generate the code related to a specific payload or result attribute.

type CookieData added in v3.2.0 

type CookieData struct {
	*Element
	// MaxAge is the cookie "max-age" attribute.
	MaxAge string
	// Path is the cookie "path" attribute.
	Path string
	// Domain is the cookie "domain" attribute.
	Domain string
	// Secure sets the cookie "secure" attribute to "Secure" if true.
	Secure bool
	// HTTPOnly sets the cookie "http-only" attribute to "HttpOnly" if true.
	HTTPOnly bool
	// SameSite sets the cookie "same-site" attribute to the given value.
	SameSite string
}

CookieData describes a HTTP request or response cookie.

type Element added in v3.2.0 

type Element struct {
	*AttributeData
	// HTTPName is the name of the HTTP element (header name, query string name
	// or cookie name)
	HTTPName string
	// AttributeName is the name of the corresponding attribute.
	AttributeName string
	// StringSlice is true if the attribute type is array of strings.
	StringSlice bool
	// Slice is true if the attribute type is an array.
	Slice bool
}

Element defines the common fields needed to generate HTTP request and response elements including headers, parameters and cookies.

type EndpointData 

type EndpointData struct {
	// Method contains the related service method data.
	Method *service.MethodData
	// ServiceName is the name of the service exposing the endpoint.
	ServiceName string
	// ServiceVarName is the goified service name (first letter
	// lowercase).
	ServiceVarName string
	// ServicePkgName is the name of the service package.
	ServicePkgName string
	// Payload describes the method HTTP payload.
	Payload *PayloadData
	// Result describes the method HTTP result.
	Result *ResultData
	// Errors describes the method HTTP errors.
	Errors []*ErrorGroupData
	// Routes describes the possible routes for this endpoint.
	Routes []*RouteData
	// BasicScheme is the basic auth security scheme if any.
	BasicScheme *service.SchemeData
	// HeaderSchemes lists all the security requirement schemes that
	// apply to the method and are encoded in the request header.
	HeaderSchemes service.SchemesData
	// BodySchemes lists all the security requirement schemes that
	// apply to the method and are encoded in the request body.
	BodySchemes service.SchemesData
	// QuerySchemes lists all the security requirement schemes that
	// apply to the method and are encoded in the request query
	// string.
	QuerySchemes service.SchemesData
	// Requirements contains the security requirements for the
	// method.
	Requirements service.RequirementsData

	// MountHandler is the name of the mount handler function.
	MountHandler string
	// HandlerInit is the name of the constructor function for the
	// http handler function.
	HandlerInit string
	// RequestDecoder is the name of the request decoder function.
	RequestDecoder string
	// ResponseEncoder is the name of the response encoder function.
	ResponseEncoder string
	// ErrorEncoder is the name of the error encoder function.
	ErrorEncoder string
	// MultipartRequestDecoder indicates the request decoder for
	// multipart content type.
	MultipartRequestDecoder *MultipartData
	// ServerWebSocket holds the data to render the server struct which
	// implements the server stream interface.
	ServerWebSocket *WebSocketData
	// Redirect defines a redirect for the endpoint.
	Redirect *RedirectData

	// ClientStruct is the name of the HTTP client struct.
	ClientStruct string
	// EndpointInit is the name of the constructor function for the
	// client endpoint.
	EndpointInit string
	// RequestInit is the request builder function.
	RequestInit *InitData
	// RequestEncoder is the name of the request encoder function.
	RequestEncoder string
	// ResponseDecoder is the name of the response decoder function.
	ResponseDecoder string
	// MultipartRequestEncoder indicates the request encoder for
	// multipart content type.
	MultipartRequestEncoder *MultipartData
	// ClientWebSocket holds the data to render the client struct which
	// implements the client stream interface.
	ClientWebSocket *WebSocketData
	// BuildStreamPayload is the name of the function used to create the
	// payload for endpoints that use SkipRequestBodyEncodeDecode.
	BuildStreamPayload string
}

EndpointData contains the data used to render the code related to a single service HTTP endpoint.

type ErrorData 

type ErrorData struct {
	// 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 ErrorGroupData 

type ErrorGroupData struct {
	// StatusCode is the response HTTP status code.
	StatusCode string
	// Errors contains the information for each error.
	Errors []*ErrorData
}

ErrorGroupData contains the error information required to generate the transport decode (client) and encode (server) code for all errors with responses using a given HTTP status code.

type FileServerData 

type FileServerData struct {
	// MountHandler is the name of the mount handler function.
	MountHandler string
	// RequestPaths is the set of HTTP paths to the server.
	RequestPaths []string
	// Root is the root server file path.
	FilePath string
	// Dir is true if the file server servers files under a
	// directory, false if it serves a single file.
	IsDir bool
	// PathParam is the name of the parameter used to capture the
	// path for file servers that serve files under a directory.
	PathParam string
	// Redirect defines a redirect for the endpoint.
	Redirect *RedirectData
	// VarName is the name of the variable that holds the file server.
	VarName string
	// ArgName is the name of the argument used to initialize the
	// file server.
	ArgName string
}

FileServerData lists the data needed to generate file servers.

type HeaderData 

type HeaderData struct {
	*Element
	// CanonicalName is the canonical header key.
	CanonicalName string
}

HeaderData describes a HTTP request or response header.

type InitArgData 

type InitArgData struct {
	*AttributeData
	// Reference to the argument, e.g. "&body".
	Ref string
}

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
	// ServerArgs is the list of constructor arguments for server
	// side code.
	ServerArgs []*InitArgData
	// ClientArgs is the list of constructor arguments for client
	// side code.
	ClientArgs []*InitArgData
	// CLIArgs is the list of arguments that should be initialized
	// from CLI flags. This is used for implicit attributes which
	// as the time of writing is only used for the basic auth
	// username and password.
	CLIArgs []*InitArgData
	// ServerCode is the code that builds the payload from the
	// request on the server when it contains user types.
	ServerCode string
	// ClientCode is the code that builds the payload or result type
	// from the request or response state on the client when it
	// contains user types.
	ClientCode string
	// ReturnTypePkg is the package where the return type is present.
	ReturnTypePkg string
	// ReturnTypeName is the qualified (including the package name)
	// name of the payload, result or error type.
	ReturnTypeName string
	// ReturnTypeRef is the qualified (including the package name)
	// reference to the payload, result or error type.
	ReturnTypeRef string
	// ReturnTypeAttribute is the name of the attribute initialized by this
	// constructor when it only initializes one attribute (i.e. body was
	// defined with Body("name") syntax).
	ReturnTypeAttribute string
	// ReturnIsStruct is true if the payload, result or error type is a struct.
	ReturnIsStruct bool
	// ReturnIsPrimitivePointer indicates whether the payload, result or error
	// type is a primitive pointer.
	ReturnIsPrimitivePointer bool
}

InitData contains the data required to render a constructor.

type MultipartData 

type MultipartData struct {
	// FuncName is the name used to generate function type.
	FuncName string
	// InitName is the name of the constructor.
	InitName string
	// VarName is the name of the variable referring to the function.
	VarName string
	// ServiceName is the name of the service.
	ServiceName string
	// MethodName is the name of the method.
	MethodName string
	// Payload is the payload data required to generate
	// encoder/decoder.
	Payload *PayloadData
}

MultipartData contains the data needed to render multipart encoder/decoder.

type ParamData 

type ParamData struct {
	*Element
	// MapStringSlice is true if the param type is a map of string
	// slice.
	MapStringSlice bool
	// Map is true if the param type is a map.
	Map bool
	// MapQueryParams indicates that the query params must be mapped
	// to the entire payload (empty string) or a payload attribute
	// (attribute name).
	MapQueryParams *string
}

ParamData describes a HTTP request parameter (query string or path parameter).

type PayloadData 

type PayloadData struct {
	// Name is the name of the payload type.
	Name string
	// Ref is the fully qualified reference to the payload type.
	Ref string
	// Request contains the data for the corresponding HTTP request.
	Request *RequestData
	// DecoderReturnValue is a reference to the decoder return value
	// if there is no payload constructor (i.e. if Init is nil).
	DecoderReturnValue string
}

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

type RedirectData added in v3.4.0 

type RedirectData struct {
	// URL is the URL that is being redirected to.
	URL string
	// StatusCode is the HTTP status code.
	StatusCode string
}

RedirectData lists the data needed to generate a redirect.

type RequestData 

type RequestData struct {
	// PathParams describes the information about params that are
	// present in the request path.
	PathParams []*ParamData
	// QueryParams describes the information about the params that
	// are present in the request query string.
	QueryParams []*ParamData
	// Headers contains the HTTP request headers used to build the
	// method payload.
	Headers []*HeaderData
	// Cookies contains the HTTP request cookies used to build the
	// method payload.
	Cookies []*CookieData
	// ServerBody describes the request body type used by server
	// code. The type is generated using pointers for all fields so
	// that it can be validated.
	ServerBody *TypeData
	// ClientBody describes the request body type used by client
	// code. The type does NOT use pointers for every fields since
	// no validation is required.
	ClientBody *TypeData
	// PayloadInit contains the data required to render the
	// payload constructor used by server code if any.
	PayloadInit *InitData
	// PayloadType is the type of the payload.
	PayloadType expr.DataType
	// PayloadAttr sets the request body from the specified payload type
	// attribute. This field is set when the design uses Body("name") syntax
	// to set the request body and the payload type is an object.
	PayloadAttr string
	// MustHaveBody is true if the request body cannot be empty.
	MustHaveBody bool
	// MustValidate is true if the request body or at least one
	// parameter or header requires validation.
	MustValidate bool
	// Multipart if true indicates the request is a multipart
	// request.
	Multipart bool
}

RequestData describes a request.

type ResponseData 

type ResponseData struct {
	// StatusCode is the return code of the response.
	StatusCode string
	// Description is the response description.
	Description string
	// Headers provides information about the HTTP response headers.
	Headers []*HeaderData
	// Cookies provides information about the HTTP response cookies.
	Cookies []*CookieData
	// ContentType contains the value of the response
	// "Content-Type" header.
	ContentType string
	// ErrorHeader contains the value of the response "goa-error"
	// header if any.
	ErrorHeader string
	// ServerBody is the type of the response body used by server
	// code, nil if body should be empty. The type does NOT use
	// pointers for all fields. If the method result is a result
	// type and the response data describes a success response, then
	// this field contains a type for every view in the result type.
	// The type name is suffixed with the name of the view (except
	// for "default" view where no suffix is added). A constructor
	// is also generated server side for each view to transform the
	// result type to the corresponding response body type. If
	// method result is not a result type or if the response
	// describes an error response, then this field contains at most
	// one item.
	ServerBody []*TypeData
	// ClientBody is the type of the response body used by client
	// code, nil if body should be empty. The type uses pointers for
	// all fields so they can be validated.
	ClientBody *TypeData
	// Init contains the data required to render the result or error
	// constructor if any.
	ResultInit *InitData
	// TagName is the name of the attribute used to test whether the
	// response is the one to use.
	TagName string
	// TagValue is the value the result attribute named by TagName
	// must have for this response to be used.
	TagValue string
	// TagPointer is true if the tag attribute is a pointer.
	TagPointer bool
	// MustValidate is true if at least one header requires validation.
	MustValidate bool
	// ResultAttr sets the response body from the specified result
	// type attribute. This field is set when the design uses
	// Body("name") syntax to set the response body and the result
	// type is an object.
	ResultAttr string
	// ViewedResult indicates whether the response body type is a
	// result type.
	ViewedResult *service.ViewedResultTypeData
}

ResponseData describes a response.

type ResultData 

type ResultData struct {
	// Name is the name of the result type.
	Name string
	// Ref is the reference to the result type.
	Ref string
	// IsStruct is true if the result type is a user type defining
	// an object.
	IsStruct bool
	// Inits contains the data required to render the result
	// constructors if any.
	Inits []*InitData
	// Responses contains the data for the corresponding HTTP
	// responses.
	Responses []*ResponseData
	// View is the view used to render the result.
	View string
	// MustInit indicates if a variable holding the result type must be
	// initialized. It is used by server response encoder to initialize
	// the result variable only if there are multiple responses, or the
	// response has a body, a header or a cookie.
	MustInit bool
}

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

type RouteData 

type RouteData struct {
	// Verb is the HTTP method.
	Verb string
	// Path is the fullpath including wildcards.
	Path string
	// PathInit contains the information needed to render and call
	// the path constructor for the route.
	PathInit *InitData
}

RouteData describes a route.

type ServiceData 

type ServiceData struct {
	// Service contains the related service data.
	Service *service.Data
	// Endpoints describes the endpoint data for this service.
	Endpoints []*EndpointData
	// FileServers lists the file servers for this service.
	FileServers []*FileServerData
	// ServerStruct is the name of the HTTP server struct.
	ServerStruct string
	// MountPointStruct is the name of the mount point struct.
	MountPointStruct string
	// ServerInit is the name of the constructor of the server
	// struct.
	ServerInit string
	// MountServer is the name of the mount function.
	MountServer string
	// ServerService is the name of service function.
	ServerService string
	// ClientStruct is the name of the HTTP client struct.
	ClientStruct string
	// ServerBodyAttributeTypes is the list of user types used to
	// define the request, response and error response type
	// attributes in the server code.
	ServerBodyAttributeTypes []*TypeData
	// ClientBodyAttributeTypes is the list of user types used to
	// define the request, response and error response type
	// attributes in the client code.
	ClientBodyAttributeTypes []*TypeData
	// ServerTypeNames records the user type names used to define
	// the endpoint request and response bodies for server code.
	// The type name is used as the key and a bool as the value
	// which if true indicates that the type has been generated
	// in the server package.
	ServerTypeNames map[string]bool
	// ClientTypeNames records the user type names used to define
	// the endpoint request and response bodies for client code.
	// The type name is used as the key and a bool as the value
	// which if true indicates that the type has been generated
	// in the client package.
	ClientTypeNames map[string]bool
	// ServerTransformHelpers is the list of transform functions
	// required by the various server side constructors.
	ServerTransformHelpers []*codegen.TransformFunctionData
	// ClientTransformHelpers is the list of transform functions
	// required by the various client side constructors.
	ClientTransformHelpers []*codegen.TransformFunctionData
	// Scope initialized with all the server and client types.
	Scope *codegen.NameScope
}

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

func (*ServiceData) Endpoint 

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

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

type ServicesData 

type ServicesData map[string]*ServiceData

ServicesData encapsulates the data computed from the design.

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 TypeData 

type TypeData struct {
	// Name is the type name.
	Name string
	// VarName is the Go type name.
	VarName string
	// Description is the type human description.
	Description string
	// Init contains the data needed to render and call the type
	// constructor if any.
	Init *InitData
	// Def is the type definition Go code.
	Def string
	// Ref is the reference to the type.
	Ref string
	// ValidateDef contains the validation code.
	ValidateDef string
	// ValidateRef contains the call to the validation code.
	ValidateRef string
	// Example is an example value for the type.
	Example any
	// View is the view used to render the (result) type if any.
	View string
}

TypeData contains the data needed to render a type definition.

type WebSocketData added in v3.1.0 

type WebSocketData struct {
	// VarName is the name of the struct.
	VarName string
	// Type is type of the stream (server or client).
	Type string
	// Interface is the fully qualified name of the interface that
	// the struct implements.
	Interface string
	// Endpoint is endpoint data that defines streaming
	// payload/result.
	Endpoint *EndpointData
	// Payload is the streaming payload type sent via the stream.
	Payload *TypeData
	// Response is the successful response data for the streaming
	// endpoint.
	Response *ResponseData
	// SendName is the name of the send function.
	SendName string
	// SendDesc is the description for the send function.
	SendDesc string
	// SendTypeName is the fully qualified type name sent through
	// the stream.
	SendTypeName string
	// SendTypeRef is the fully qualified type ref sent through the
	// stream.
	SendTypeRef string
	// RecvName is the name of the receive function.
	RecvName string
	// RecvDesc is the description for the recv function.
	RecvDesc string
	// RecvTypeName is the fully qualified type name received from
	// the stream.
	RecvTypeName string
	// RecvTypeRef is the fully qualified type ref received from the
	// stream.
	RecvTypeRef string
	// RecvTypeIsPointer is true if the type received from the stream is a
	// array or map. This is needed so that the code reading the stream can
	// use a pointer reference when needed to check whether anything was
	// read (check against the nil value) and in this case return EOF.
	RecvTypeIsPointer bool
	// MustClose indicates whether to generate the Close() function
	// for the stream.
	MustClose bool
	// PkgName is the service package name.
	PkgName string
	// Kind is the kind of the stream (payload, result or
	// bidirectional).
	Kind expr.StreamKind
}

WebSocketData contains the data needed to render struct type that implements the server and client stream interfaces.

Source Files

View all Source files

Directories

Path Synopsis
Package openapi provides common algorithms and data structures used to generate both OpenAPI v2 and v3 specifications from Goa designs.
 Package openapi provides common algorithms and data structures used to generate both OpenAPI v2 and v3 specifications from Goa designs.
v2
Package openapiv2 contains the algorithms and data structures used to generate OpenAPI v2 specifications from Goa designs.
 Package openapiv2 contains the algorithms and data structures used to generate OpenAPI v2 specifications from Goa designs.
v3
Package openapiv3 contains the algorithms and data structures used to generate OpenAPI v3 specifications from Goa designs.
 Package openapiv3 contains the algorithms and data structures used to generate OpenAPI v3 specifications from Goa designs.

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.