service

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: 14 Imported by: 9

Documentation

Overview

Package service contains the code generation algorithms to produce code for the service and views packages and dummy implementation for the services defined in the design.

Index

Constants

This section is empty.

Variables

View Source 
var Services = make(ServicesData)

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

Functions

func AddServiceDataMetaTypeImports added in v3.0.1 

func AddServiceDataMetaTypeImports(header *codegen.SectionTemplate, serviceE *expr.ServiceExpr)

AddServiceDataMetaTypeImports Adds all imports defined by struct:field:type from the service expr and the service data

func ClientFile 

func ClientFile(_ string, service *expr.ServiceExpr) *codegen.File

ClientFile returns the client file for the given service.

func ConvertFile 

func ConvertFile(root *expr.RootExpr, service *expr.ServiceExpr) (*codegen.File, error)

ConvertFile returns the file containing the conversion and creation functions if any.

func EndpointFile 

func EndpointFile(genpkg string, service *expr.ServiceExpr) *codegen.File

EndpointFile returns the endpoint file for the given service.

func ExampleServiceFiles 

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

ExampleServiceFiles returns a basic service implementation for every service expression.

func Files added in v3.6.0 

func Files(genpkg string, service *expr.ServiceExpr, userTypePkgs map[string][]string) []*codegen.File

Files returns the generated files for the given service as well as a map indexing user type names by custom path as defined by the "struct:pkg:path" metadata. The map is built over each invocation of Files to avoid duplicate type definitions.

func ViewsFile 

func ViewsFile(_ string, service *expr.ServiceExpr) *codegen.File

ViewsFile returns the views file for the given service which contains logic to render result types using the defined views.

Types

type Data 

type Data struct {
	// Name is the service name.
	Name string
	// Description is the service description.
	Description string
	// APIName is the name of the API the service belongs to.
	APIName string
	// APIVersion is the API version.
	APIVersion string
	// StructName is the service struct name.
	StructName string
	// VarName is the service variable name (first letter in lowercase).
	VarName string
	// PathName is the service name as used in file and import paths.
	PathName string
	// PkgName is the name of the package containing the generated service
	// code.
	PkgName string
	// ViewsPkg is the name of the package containing the projected and viewed
	// result types.
	ViewsPkg string
	// Methods lists the service interface methods.
	Methods []*MethodData
	// Schemes is the list of security schemes required by the service methods.
	Schemes SchemesData
	// Scope initialized with all the service types.
	Scope *codegen.NameScope
	// ViewScope initialized with all the viewed types.
	ViewScope *codegen.NameScope
	// UserTypeImports lists the import specifications for the user
	// types used by the service.
	UserTypeImports []*codegen.ImportSpec
	// ProtoImports lists the import specifications for the custom
	// proto types used by the service.
	ProtoImports []*codegen.ImportSpec
	// contains filtered or unexported fields
}

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

func (*Data) Method 

func (d *Data) Method(name string) *MethodData

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

type EndpointMethodData added in v3.12.0 

type EndpointMethodData struct {
	*MethodData
	// ArgName is the name of the argument used to initialize the client
	// struct method field.
	ArgName string
	// ClientVarName is the corresponding client struct field name.
	ClientVarName string
	// ServiceName is the name of the owner service.
	ServiceName string
	// ServiceVarName is the name of the owner service Go interface.
	ServiceVarName string
}

EndpointMethodData describes a single endpoint method.

type EndpointsData added in v3.12.0 

type EndpointsData struct {
	// Name is the service name.
	Name string
	// Description is the service description.
	Description string
	// VarName is the endpoint struct name.
	VarName string
	// ClientVarName is the client struct name.
	ClientVarName string
	// ServiceVarName is the service interface name.
	ServiceVarName string
	// Methods lists the endpoint struct methods.
	Methods []*EndpointMethodData
	// ClientInitArgs lists the arguments needed to instantiate the client.
	ClientInitArgs string
	// Schemes contains the security schemes types used by the
	// all the endpoints.
	Schemes SchemesData
}

EndpointsData contains the data necessary to render the service endpoints struct template.

type ErrorInitData 

type ErrorInitData struct {
	// Name is the name of the init function.
	Name string
	// Description is the error description.
	Description string
	// ErrName is the name of the error.
	ErrName string
	// TypeName is the error struct type name.
	TypeName string
	// TypeRef is the reference to the error type.
	TypeRef string
	// Temporary indicates whether the error is temporary.
	Temporary bool
	// Timeout indicates whether the error is due to timeouts.
	Timeout bool
	// Fault indicates whether the error is server-side fault.
	Fault bool
}

ErrorInitData describes an error returned by a service method of type ErrorResult.

type InitArgData 

type InitArgData struct {
	// Name is the argument name.
	Name string
	// Ref is the reference to the argument type.
	Ref string
}

InitArgData represents a single constructor argument.

type InitData 

type InitData struct {
	// Name is the name of the constructor function.
	Name string
	// Description is the function description.
	Description string
	// Args lists arguments to this function.
	Args []*InitArgData
	// ReturnTypeRef is the reference to the return type.
	ReturnTypeRef string
	// Code is the transformation code.
	Code string
	// Helpers contain the helpers used in the transformation code.
	Helpers []*codegen.TransformFunctionData
}

InitData contains the data to render a constructor to initialize service types from viewed result types and vice versa.

type MethodData 

type MethodData struct {
	// Name is the method name.
	Name string
	// Description is the method description.
	Description string
	// VarName is the Go method name.
	VarName string
	// Payload is the name of the payload type if any,
	Payload string
	// PayloadLoc defines the file and Go package of the payload type
	// if overridden via Meta.
	PayloadLoc *codegen.Location
	// PayloadDef is the payload type definition if any.
	PayloadDef string
	// PayloadRef is a reference to the payload type if any,
	PayloadRef string
	// PayloadDesc is the payload type description if any.
	PayloadDesc string
	// PayloadEx is an example of a valid payload value.
	PayloadEx any
	// PayloadDefault is the default value of the payload if any.
	PayloadDefault any
	// StreamingPayload is the name of the streaming payload type if any.
	StreamingPayload string
	// StreamingPayloadDef is the streaming payload type definition if any.
	StreamingPayloadDef string
	// StreamingPayloadRef is a reference to the streaming payload type if any.
	StreamingPayloadRef string
	// StreamingPayloadDesc is the streaming payload type description if any.
	StreamingPayloadDesc string
	// StreamingPayloadEx is an example of a valid streaming payload value.
	StreamingPayloadEx any
	// Result is the name of the result type if any.
	Result string
	// ResultLoc defines the file and Go package of the result type
	// if overridden via Meta.
	ResultLoc *codegen.Location
	// ResultDef is the result type definition if any.
	ResultDef string
	// ResultRef is the reference to the result type if any.
	ResultRef string
	// ResultDesc is the result type description if any.
	ResultDesc string
	// ResultEx is an example of a valid result value.
	ResultEx any
	// Errors list the possible errors defined in the design if any.
	Errors []*ErrorInitData
	// ErrorLocs lists the file and Go package of the error type
	// if overridden via Meta indexed by error name.
	ErrorLocs map[string]*codegen.Location
	// Requirements contains the security requirements for the
	// method.
	Requirements RequirementsData
	// Schemes contains the security schemes types used by the
	// method.
	Schemes SchemesData
	// ViewedResult contains the data required to generate the code handling
	// views if any.
	ViewedResult *ViewedResultTypeData
	// ServerStream indicates that the service method receives a payload
	// stream or sends a result stream or both.
	ServerStream *StreamData
	// ClientStream indicates that the service method receives a result
	// stream or sends a payload result or both.
	ClientStream *StreamData
	// StreamKind is the kind of the stream (payload or result or
	// bidirectional).
	StreamKind expr.StreamKind
	// SkipRequestBodyEncodeDecode is true if the method payload includes
	// the raw HTTP request body reader.
	SkipRequestBodyEncodeDecode bool
	// SkipResponseBodyEncodeDecode is true if the method result includes
	// the raw HTTP response body reader.
	SkipResponseBodyEncodeDecode bool
	// RequestStruct is the name of the data structure containing the
	// payload and request body reader when SkipRequestBodyEncodeDecode is
	// used.
	RequestStruct string
	// ResponseStruct is the name of the data structure containing the
	// result and response body reader when SkipResponseBodyEncodeDecode is
	// used.
	ResponseStruct string
}

MethodData describes a single service method.

type ProjectedTypeData 

type ProjectedTypeData struct {
	// the projected type
	*UserTypeData
	// Validations lists the validation functions to run on the projected type.
	// If the projected type corresponds to a result type then a validation
	// function for each view is generated. For user types, only one validation
	// function is generated.
	Validations []*ValidateData
	// Projections contains the code to create a projected type based on
	// views. If the projected type corresponds to a result type, then a
	// function for each view is generated.
	Projections []*InitData
	// TypeInits contains the code to convert a projected type to its
	// corresponding service type. If the projected type corresponds to a
	// result type, then a function for each view is generated.
	TypeInits []*InitData
	// ViewsPkg is the views package name.
	ViewsPkg string
	// Views lists the views defined on the projected type.
	Views []*ViewData
}

ProjectedTypeData contains the data used to generate a projected type for the corresponding user type or result type in the service package. The generated type uses pointers for all fields. It also contains the data to generate view-based validation logic and transformation functions to convert a projected type to its corresponding service type and vice versa.

type RequirementData 

type RequirementData struct {
	// Schemes list the requirement schemes.
	Schemes []*SchemeData
	// Scopes list the required scopes.
	Scopes []string
}

RequirementData lists the schemes and scopes defined by a single security requirement.

type RequirementsData 

type RequirementsData []*RequirementData

RequirementsData is the list of security requirements.

func (RequirementsData) Scheme 

func (r RequirementsData) Scheme(name string) *SchemeData

Scheme returns the scheme data with the given scheme name.

type SchemeData 

type SchemeData struct {
	// Kind is the type of scheme, one of "Basic", "APIKey", "JWT"
	// or "OAuth2".
	Type string
	// SchemeName is the name of the scheme.
	SchemeName string
	// Name refers to a header or parameter name, based on In's
	// value.
	Name string
	// UsernameField is the name of the payload field that should be
	// initialized with the basic auth username if any.
	UsernameField string
	// UsernamePointer is true if the username field is a pointer.
	UsernamePointer bool
	// UsernameAttr is the name of the attribute that contains the
	// username.
	UsernameAttr string
	// UsernameRequired specifies whether the attribute that
	// contains the username is required.
	UsernameRequired bool
	// PasswordField is the name of the payload field that should be
	// initialized with the basic auth password if any.
	PasswordField string
	// PasswordPointer is true if the password field is a pointer.
	PasswordPointer bool
	// PasswordAttr is the name of the attribute that contains the
	// password.
	PasswordAttr string
	// PasswordRequired specifies whether the attribute that
	// contains the password is required.
	PasswordRequired bool
	// CredField contains the name of the payload field that should
	// be initialized with the API key, the JWT token or the OAuth2
	// access token.
	CredField string
	// CredPointer is true if the credential field is a pointer.
	CredPointer bool
	// CredRequired specifies if the key is a required attribute.
	CredRequired bool
	// KeyAttr is the name of the attribute that contains
	// the security tag (for APIKey, OAuth2, and JWT schemes).
	KeyAttr string
	// Scopes lists the scopes that apply to the scheme.
	Scopes []string
	// Flows describes the OAuth2 flows.
	Flows []*expr.FlowExpr
	// In indicates the request element that holds the credential.
	In string
}

SchemeData describes a single security scheme.

func BuildSchemeData added in v3.1.3 

func BuildSchemeData(s *expr.SchemeExpr, m *expr.MethodExpr) *SchemeData

BuildSchemeData builds the scheme data for the given scheme and method expr.

func (*SchemeData) Dup 

func (s *SchemeData) Dup() *SchemeData

Dup creates a copy of the scheme data.

type SchemesData 

type SchemesData []*SchemeData

SchemesData is the list of security schemes.

func (SchemesData) Append 

func (s SchemesData) Append(d *SchemeData) SchemesData

Append appends a scheme data to schemes only if it doesn't exist.

type ServicesData 

type ServicesData map[string]*Data

ServicesData encapsulates the data computed from the service designs.

func (ServicesData) Get 

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

Get retrieves the 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 {
	// Interface is the name of the stream interface.
	Interface string
	// VarName is the name of the struct type that implements the stream
	// interface.
	VarName string
	// SendName is the name of the send function.
	SendName string
	// SendDesc is the description for the send function.
	SendDesc string
	// SendTypeName is the type name sent through the stream.
	SendTypeName string
	// SendTypeRef is the reference to the type 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 type name received from the stream.
	RecvTypeName string
	// RecvTypeRef is the reference to the type received from the stream.
	RecvTypeRef string
	// MustClose indicates whether the stream should implement the Close()
	// function.
	MustClose bool
	// EndpointStruct is the name of the endpoint struct that holds a payload
	// reference (if any) and the endpoint server stream. It is set only if the
	// client sends a normal payload and server streams a result.
	EndpointStruct string
	// Kind is the kind of the stream (payload, result or bidirectional).
	Kind expr.StreamKind
}

StreamData is the data used to generate client and server interfaces that a streaming endpoint implements. It is initialized if a method defines a streaming payload or result or both.

type UnionValueMethodData added in v3.7.0 

type UnionValueMethodData struct {
	// Name is the name of the function.
	Name string
	// TypeRef is a reference on the target union value type.
	TypeRef string
	// Loc defines the file and Go package of the method if
	// overridden in corresponding union type via Meta.
	Loc *codegen.Location
}

UnionValueMethodData describes a method used on a union value type.

type UserTypeData 

type UserTypeData struct {
	// Name is the type name.
	Name string
	// VarName is the corresponding Go type name.
	VarName string
	// Description is the type human description.
	Description string
	// Def is the type definition Go code.
	Def string
	// Ref is the reference to the type.
	Ref string
	// Loc defines the file and Go package of the type if overridden
	// via Meta.
	Loc *codegen.Location
	// Type is the underlying type.
	Type expr.UserType
}

UserTypeData contains the data describing a user-defined type.

type ValidateData 

type ValidateData struct {
	// Name is the validation function name.
	Name string
	// Ref is the reference to the type on which the validation function
	// is defined.
	Ref string
	// Description is the description for the validation function.
	Description string
	// Validate is the validation code.
	Validate string
}

ValidateData contains data to render a validate function to validate a projected type or a viewed result type based on views.

type ViewData 

type ViewData struct {
	// Name is the view name.
	Name string
	// Description is the view description.
	Description string
	// Attributes is the list of attributes rendered in the view.
	Attributes []string
	// TypeVarName is the Go variable name of the type that defines the view.
	TypeVarName string
}

ViewData contains data about a result type view.

type ViewedResultTypeData 

type ViewedResultTypeData struct {
	// the viewed result type
	*UserTypeData
	// Views lists the views defined on the viewed result type.
	Views []*ViewData
	// Validate is the validation run on the viewed result type.
	Validate *ValidateData
	// Init is the constructor code to initialize a viewed result type from
	// a result type.
	Init *InitData
	// ResultInit is the constructor code to initialize a result type
	// from the viewed result type.
	ResultInit *InitData
	// FullName is the fully qualified name of the viewed result type.
	FullName string
	// FullRef is the complete reference to the viewed result type
	// (including views package name).
	FullRef string
	// IsCollection indicates whether the viewed result type is a collection.
	IsCollection bool
	// ViewName is the view name to use to render the result type. It is set
	// only if the result type has at most one view.
	ViewName string
	// ViewsPkg is the views package name.
	ViewsPkg string
}

ViewedResultTypeData contains the data used to generate a viewed result type (i.e. a method result type with more than one view). The viewed result type holds the projected type and a view based on which it creates the projected type. It also contains the code to validate the viewed result type and the functions to initialize a viewed result type from a result type and vice versa.

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.