service

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: May 12, 2026 License: MIT Imports: 16 Imported by: 3

Documentation

Overview

Package service is the base stage of the Loom codegen pipeline. It turns the evaluated DSL (expr.RootExpr) into a transport-neutral data model (ServicesData) consumed by every transport codegen.

Pipeline position 

DSL functions (github.com/CaliLuke/loom/dsl)
        |
        v
eval.Run -> expr.RootExpr                     [eval package]
        |
        v
service.NewServicesData(root) -> *ServicesData  (this package)
        |
        +--> http/codegen.NewServicesData(svc, HTTP)
        +--> grpc/codegen.NewServicesData(svc)
        +--> jsonrpc/codegen uses http/codegen with JSONRPC.HTTPExpr
        |
        v
codegen/generator emits *codegen.File per transport

Each transport's ServicesData embeds *service.ServicesData, so anything computed here is visible to every transport without duplication.

What this package owns

  • Service-level shape: name, API info, package names, scopes.
  • Method-level shape: payload/result/streaming/transport/security descriptors (MethodData and its embedded *Data sub-structs).
  • User types, error init data, and union types.
  • View projections and projected/viewed-result type data (ProjectedTypeData, ViewedResultTypeData).
  • Interceptor data.

Transports MUST NOT re-derive any of the above. They consume it via the embedded *service.ServicesData.

What this package does NOT own

  • HTTP/gRPC/JSON-RPC wire framing, status codes, routes, metadata, or streaming transport details — those live in the respective transport codegen packages.
  • File emission or templates — those live in codegen/generator and the transport codegen packages.

Lazy evaluation

ServicesData computes a service's Data lazily on first ServicesData.Get. Once computed it is cached in the ServicesData.Services map. Callers can rely on referential stability: Get returns the same *Data pointer on repeat calls.

File layout

  • service_data.go — top-level types + ServicesData/Data/MethodData methods.
  • service_data_view_types.go — view-related data types (projected / viewed).
  • service_data_types.go — user types, unions, and scope helpers.
  • service_data_methods.go — per-method analysis (payload/result/streaming).
  • service_data_analysis.go — ServicesData.analyze (Get's computation backend).
  • service_data_interceptors.go — interceptor data collection.
  • service_data_views.go / _init.go / _validation.go — projected type builders.
  • convert*.go, endpoint*.go, interceptor*.go, security*.go, example*.go — section renderers and helpers.

Extension points

  • Add a new method-level field: put the declaration in one of the Method*Data sub-structs in service_data.go, populate it from service_data_methods.go or service_data_analysis.go.
  • Add a new user-type transformation: extend service_data_types.go.
  • Add a new transport: create a sibling `codegen` package that embeds *service.ServicesData and adds transport-specific data + section renderers. Do not reach into private fields — add accessors here instead.

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

This section is empty.

Functions

func AddServiceDataMetaTypeImports 

func AddServiceDataMetaTypeImports(header *codegen.SectionTemplate, svcExpr *expr.ServiceExpr, svcData *Data)

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

func AddUserTypeImports 

func AddUserTypeImports(genpkg string, header *codegen.SectionTemplate, d *Data)

AddUserTypeImports sets the import paths for the user types defined in the service. User types may be declared in multiple packages when defined with the Meta key "struct:pkg:path".

func BuildRequirementsData added in v1.0.4 

func BuildRequirementsData(requirements []*expr.SecurityExpr, method *expr.MethodExpr) (RequirementsData, SchemesData)

BuildRequirementsData projects expression security requirements into generator-facing requirement and scheme data for the given method.

func ClientFile 

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

ClientFile returns the client file for the given service.

func ConvertFile 

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

ConvertFile returns the legacy single convert.go file for the default service path when any conversions or creations are defined.

func ConvertFiles 

func ConvertFiles(root *expr.RootExpr, service *expr.ServiceExpr, services *ServicesData) ([]*codegen.File, error)

ConvertFiles returns multiple files containing conversion and creation functions, grouped by target package as specified by struct:pkg:path metadata.

func DefaultPackageName added in v1.0.8 

func DefaultPackageName(loc *codegen.Location, def string) string

DefaultPackageName returns loc package when present, otherwise def.

func EndpointFile 

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

EndpointFile returns the endpoint file for the given service.

func ExampleInterceptorsFiles 

func ExampleInterceptorsFiles(genpkg string, r *expr.RootExpr, services *ServicesData) []*codegen.File

ExampleInterceptorsFiles returns the files for the example server and client interceptors.

func ExampleServiceFiles 

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

ExampleServiceFiles returns a basic service implementation for every service expression.

func Files 

func Files(genpkg string, service *expr.ServiceExpr, services *ServicesData, 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 InterceptorsFiles 

func InterceptorsFiles(_ string, service *expr.ServiceExpr, services *ServicesData) []*codegen.File

InterceptorsFiles returns the interceptors files for the given service.

func PartitionSchemesByIn added in v1.0.8 

func PartitionSchemesByIn(schemes SchemesData) (*SchemeData, map[string]SchemesData, SchemesData)

PartitionSchemesByIn groups schemes by their transport location and returns non-location schemes separately.

func ViewsFile 

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

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

Types

type AttributeData 

type AttributeData struct {
	// Name is the name of the attribute.
	Name string
	// TypeRef is the reference to the attribute type.
	TypeRef string
	// Pointer is true if the attribute is a pointer.
	Pointer bool
}

AttributeData describes a single attribute.

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
	// ServerInterceptors contains the data needed to render the server-side
	// interceptors code.
	ServerInterceptors []*InterceptorData
	// ClientInterceptors contains the data needed to render the client-side
	// interceptors code.
	ClientInterceptors []*InterceptorData
	// 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
	// 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 

type EndpointMethodData struct {
	*MethodData
	// ArgName is the name of the argument used to initialize the client
	// struct method field.
	ArgName string
	// StreamArgName is the name of the argument used to initialize the client
	// struct stream endpoint field when the method defines mixed results.
	//
	// It is only set when HasMixedResults is true.
	StreamArgName 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 

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
	// HasServerInterceptors indicates that the service has server-side
	// interceptors.
	HasServerInterceptors bool
	// HasClientInterceptors indicates that the service has client-side
	// interceptors.
	HasClientInterceptors bool
}

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

type ErrorDescriptor added in v1.0.8 

type ErrorDescriptor struct {
	// Name is the method error name.
	Name string
	// Type is the resolved error type descriptor.
	Type TypeDescriptor
}

ErrorDescriptor describes a method error type together with its resolved package and Go references.

func BuildErrorDescriptor added in v1.0.8 

func BuildErrorDescriptor(svc *Data, method *MethodData, name string, errAttr *expr.AttributeExpr) ErrorDescriptor

BuildErrorDescriptor returns the resolved error type information for a method error.

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
	// RemedyCode is the stable remediation code for the error if declared.
	RemedyCode string
	// SafeMessage is the safe, user-facing message for the error if declared.
	SafeMessage string
	// RetryHint is the retry or correction guidance for the error if declared.
	RetryHint string
}

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 InterceptorData 

type InterceptorData struct {
	// Name is the name of the interceptor used in the generated code.
	Name string
	// DesignName is the name of the interceptor as defined in the design.
	DesignName string
	// Description is the description of the interceptor from the design.
	Description string
	// Methods
	Methods []*MethodInterceptorData
	// ReadPayload contains payload attributes that the interceptor can
	// read.
	ReadPayload []*AttributeData
	// WritePayload contains payload attributes that the interceptor can
	// write.
	WritePayload []*AttributeData
	// ReadResult contains result attributes that the interceptor can read.
	ReadResult []*AttributeData
	// WriteResult contains result attributes that the interceptor can
	// write.
	WriteResult []*AttributeData
	// ReadStreamingPayload contains streaming payload attributes that the interceptor can read.
	ReadStreamingPayload []*AttributeData
	// WriteStreamingPayload contains streaming payload attributes that the interceptor can write.
	WriteStreamingPayload []*AttributeData
	// ReadStreamingResult contains streaming result attributes that the interceptor can read.
	ReadStreamingResult []*AttributeData
	// WriteStreamingResult contains streaming result attributes that the interceptor can write.
	WriteStreamingResult []*AttributeData
	// HasPayloadAccess indicates that the interceptor info object has a
	// payload access interface.
	HasPayloadAccess bool
	// HasResultAccess indicates that the interceptor info object has a
	// result access interface.
	HasResultAccess bool
	// HasStreamingPayloadAccess indicates that the interceptor info object has a
	// streaming payload access interface.
	HasStreamingPayloadAccess bool
	// HasStreamingResultAccess indicates that the interceptor info object has a
	// streaming result access interface.
	HasStreamingResultAccess bool
}

InterceptorData contains the data required to render the service-level interceptor code. interceptors.go.tpl

type MethodCapabilityDescriptor added in v1.0.8 

type MethodCapabilityDescriptor struct {
	// HasPayload reports whether the method accepts a regular payload.
	HasPayload bool
	// HasResult reports whether the method returns a regular result.
	HasResult bool
	// HasViewedResult reports whether the effective result uses a viewed
	// wrapper type.
	HasViewedResult bool
	// HasStreamingPayload reports whether the method accepts a payload stream.
	HasStreamingPayload bool
	// HasStreamingResult reports whether the method produces a result stream.
	HasStreamingResult bool
	// HasMixedResults reports whether the method has both unary and streaming
	// results.
	HasMixedResults bool
	// HasRequestStruct reports whether transport code uses the generated
	// request wrapper struct.
	HasRequestStruct bool
	// HasResponseStruct reports whether transport code uses the generated
	// response wrapper struct.
	HasResponseStruct bool
	// Stream contains the stream capability descriptor.
	Stream StreamDescriptor
}

MethodCapabilityDescriptor captures transport-agnostic method capability flags used by HTTP and gRPC analyzers.

func DescribeMethodCapabilities added in v1.0.8 

func DescribeMethodCapabilities(method *MethodData) MethodCapabilityDescriptor

DescribeMethodCapabilities returns shared transport capability flags for the given method.

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 contains the payload type metadata.
	MethodPayloadData
	// Result contains the result and viewed-result metadata.
	MethodResultData
	// Security contains the error, auth, and interceptor metadata.
	MethodSecurityData
	// Transport contains the transport and client endpoint-field metadata.
	MethodTransportData
	// Streaming contains the streaming type and stream-interface metadata.
	MethodStreamingData
}

MethodData describes a single service method.

func (*MethodData) AppendInterceptorName added in v1.0.10 

func (m *MethodData) AppendInterceptorName(name string, server bool)

AppendInterceptorName records an interceptor name on the server or client side of the method.

func (*MethodData) AssignEndpointFields added in v1.0.10 

func (m *MethodData) AssignEndpointFields(scope *codegen.NameScope)

AssignEndpointFields computes the generated client endpoint field names for the method.

func (*MethodData) SetViewedResult added in v1.0.10 

func (m *MethodData) SetViewedResult(viewed *ViewedResultTypeData)

SetViewedResult records the viewed-result wrapper metadata for the method.

type MethodInterceptorData 

type MethodInterceptorData struct {
	// MethodName is the name of the method.
	MethodName string
	// PayloadAccess is the name of the payload access struct.
	PayloadAccess string
	// ResultAccess is the name of the result access struct.
	ResultAccess string
	// StreamingPayloadAccess is the name of the streaming payload access struct.
	StreamingPayloadAccess string
	// StreamingResultAccess is the name of the streaming result access struct.
	StreamingResultAccess string
	// PayloadRef is the reference to the method payload type.
	PayloadRef string
	// ResultRef is the reference to the method result type.
	ResultRef string
	// StreamingPayloadRef is the reference to the streaming payload type.
	StreamingPayloadRef string
	// StreamingResultRef is the reference to the streaming result type.
	StreamingResultRef string
	// ServerStream is the stream data if the endpoint defines a server stream.
	ServerStream *StreamInterceptorData
	// ClientStream is the stream data if the endpoint defines a client stream.
	ClientStream *StreamInterceptorData
}

MethodInterceptorData contains the data required to render the method-level interceptor code.

type MethodPayloadData added in v1.0.10 

type MethodPayloadData struct {
	// 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
}

MethodPayloadData contains the request payload type metadata for a method.

type MethodResultData added in v1.0.10 

type MethodResultData struct {
	// 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
	// ViewedResult contains the data required to generate the code handling
	// views if any.
	ViewedResult *ViewedResultTypeData
}

MethodResultData contains the result type metadata for a method.

type MethodSecurityData added in v1.0.10 

type MethodSecurityData struct {
	// 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
	// ServerInterceptors list the server interceptors that apply to this
	// method.
	ServerInterceptors []string
	// ClientInterceptors list the client interceptors that apply to this
	// method.
	ClientInterceptors []string
}

MethodSecurityData contains error, auth, and interceptor metadata.

type MethodStreamingData added in v1.0.10 

type MethodStreamingData struct {
	// 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
	// StreamingResult is the name of the streaming result type if any (when different from Result).
	StreamingResult string
	// StreamingResultDef is the streaming result type definition if any.
	StreamingResultDef string
	// StreamingResultRef is the reference to the streaming result type if any.
	StreamingResultRef string
	// StreamingResultDesc is the streaming result type description if any.
	StreamingResultDesc string
	// StreamingResultEx is an example of a valid streaming result value.
	StreamingResultEx any
	// 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
	// HasMixedResults indicates whether the method defines both Result and
	// StreamingResult with different types, enabling content negotiation at
	// the transport layer (e.g. JSON vs SSE over HTTP).
	HasMixedResults bool
}

MethodStreamingData contains streaming type and stream-interface metadata.

type MethodTransportData added in v1.0.10 

type MethodTransportData struct {
	// IsJSONRPC indicates if the endpoint is a JSON-RPC endpoint.
	IsJSONRPC bool
	// IsJSONRPCSSE indicates if the JSON-RPC endpoint uses SSE transport.
	IsJSONRPCSSE bool
	// IsJSONRPCWebSocket indicates if the JSON-RPC endpoint uses WebSocket transport.
	IsJSONRPCWebSocket bool
	// 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
	// EndpointField is the unique field name used in the generated client
	// struct to store the loom.Endpoint for this method. It is computed with a
	// scope that includes method names to avoid field/method name collisions.
	EndpointField string
	// StreamEndpointField is the unique field name used in the generated client
	// struct to store the "streaming mode" loom.Endpoint for mixed results. The
	// transport endpoint forces server streaming (e.g. sets "Accept:
	// text/event-stream") and returns the client stream interface.
	//
	// It is only set when HasMixedResults is true.
	StreamEndpointField string
}

MethodTransportData contains transport and client-endpoint metadata.

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 ResultDescriptor added in v1.0.8 

type ResultDescriptor struct {
	// Declared is the service method result as declared on the method.
	Declared TypeDescriptor
	// Effective is the result shape transports should use. It is the
	// projected result when the method uses viewed results, otherwise it is
	// the same as Declared.
	Effective TypeDescriptor
	// View is the default result view name when available.
	View string
	// ViewedRef is the fully qualified viewed-result wrapper reference when
	// the method uses viewed results.
	ViewedRef string
	// UsesViewedResult reports whether Effective comes from a viewed result.
	UsesViewedResult bool
}

ResultDescriptor describes both the declared method result and the effective result type used by transports after view projection.

func BuildResultDescriptor added in v1.0.8 

func BuildResultDescriptor(svc *Data, method *MethodData, result *expr.AttributeExpr) ResultDescriptor

BuildResultDescriptor returns the declared and effective result type information for a method.

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
	// TransportOwned is true when the credential is supplied by transport
	// state rather than a payload field.
	TransportOwned bool
}

SchemeData describes a single security scheme.

func BuildSchemeData 

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 ExpandRequirementSchemes added in v1.0.8 

func ExpandRequirementSchemes(requirements []*expr.SecurityExpr, base RequirementsData) SchemesData

ExpandRequirementSchemes clones the scheme data referenced by the transport requirements while preserving transport-specific location overrides.

func (SchemesData) Append 

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

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

func (SchemesData) DedupeByType 

func (s SchemesData) DedupeByType() SchemesData

DedupeByType returns a new SchemesData slice that is deduplicated by scheme type.

type ServicesData 

type ServicesData struct {
	Root     *expr.RootExpr
	Services map[string]*Data
	// Ctx carries the codegen context used for structured logging and
	// (future) error attribution. A nil Ctx is treated as a silent
	// context; analyze populates it lazily on first use.
	Ctx *codegen.Context
}

ServicesData encapsulates the data computed from the service designs.

func NewServicesData 

func NewServicesData(root *expr.RootExpr) *ServicesData

NewServicesData creates a new ServicesData instance for the given root. The returned ServicesData has a codegen context whose logger honors the DEBUG_LOOM environment variable (silent when unset). Callers that want to force silence regardless of environment can assign codegen.NewSilentContext to the Ctx field.

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
	// SendWithContextName is the name of the send function with context.
	SendWithContextName string
	// SendWithContextDesc is the description for the send function with context.
	SendWithContextDesc 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
	// SendAndCloseName is the name of the send and close function (SSE only).
	SendAndCloseName string
	// SendAndCloseDesc is the description for the send and close function.
	SendAndCloseDesc string
	// SendAndCloseWithContextName is the name of the send and close function with context.
	SendAndCloseWithContextName string
	// SendAndCloseWithContextDesc is the description for the send and close function with context.
	SendAndCloseWithContextDesc string
	// RecvName is the name of the receive function.
	RecvName string
	// RecvDesc is the description for the recv function.
	RecvDesc string
	// RecvWithContextName is the name of the receive function with context.
	RecvWithContextName string
	// RecvWithContextDesc is the description for the recv function with context.
	RecvWithContextDesc 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.
	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 StreamDescriptor added in v1.0.8 

type StreamDescriptor struct {
	// Kind is the stream kind declared by the service method.
	Kind expr.StreamKind
	// IsStreaming reports whether the method has any stream direction.
	IsStreaming bool
	// HasPayload reports whether the stream carries payload values.
	HasPayload bool
	// HasResult reports whether the stream carries result values.
	HasResult bool
	// IsClient reports whether the client sends stream values.
	IsClient bool
	// IsServer reports whether the server sends stream values.
	IsServer bool
	// IsBidirectional reports whether both sides send stream values.
	IsBidirectional bool
	// Payload is the streaming payload descriptor when the method accepts a
	// payload stream.
	Payload TypeDescriptor
	// Result is the streaming result descriptor when the method produces a
	// result stream.
	Result ResultDescriptor
}

StreamDescriptor captures transport-agnostic stream facts derived from a service method.

func BuildStreamDescriptor added in v1.0.8 

func BuildStreamDescriptor(svc *Data, method *MethodData, payload, result *expr.AttributeExpr) StreamDescriptor

BuildStreamDescriptor returns transport-agnostic stream facts together with the streaming payload and result type descriptors used by transports.

func DescribeStream added in v1.0.8 

func DescribeStream(method *MethodData) StreamDescriptor

DescribeStream returns transport-agnostic stream facts for the given method.

type StreamInterceptorData 

type StreamInterceptorData struct {
	// Interface is the name of the stream interface.
	Interface string
	// SendName is the name of the send function.
	SendName string
	// SendWithContextName is the name of the send function with context.
	SendWithContextName string
	// SendTypeRef is the reference to the type sent through the stream.
	SendTypeRef string
	// RecvName is the name of the recv function.
	RecvName string
	// RecvWithContextName is the name of the recv function with context.
	RecvWithContextName 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.
	EndpointStruct string
}

StreamInterceptorData is the stream data for an interceptor.

type TypeDescriptor added in v1.0.8 

type TypeDescriptor struct {
	// Attribute is the underlying type attribute.
	Attribute *expr.AttributeExpr
	// Package is the resolved Go package name for the type.
	Package string
	// Name is the fully qualified Go type name.
	Name string
	// Ref is the fully qualified Go type reference.
	Ref string
}

TypeDescriptor describes a service-level payload or result type together with its resolved package and Go references.

func BuildPayloadDescriptor added in v1.0.8 

func BuildPayloadDescriptor(svc *Data, method *MethodData, payload *expr.AttributeExpr) TypeDescriptor

BuildPayloadDescriptor returns the resolved payload type information for a method.

type UnionFieldData 

type UnionFieldData struct {
	// Name is the branch name as defined in the DSL.
	Name string
	// KindConst is the Go identifier for the kind constant of this branch.
	KindConst string
	// FieldName is the struct field name in the union.
	FieldName string
	// FieldType is the Go type used in the union struct field and public API.
	FieldType string
	// FlatFormObject is true when the branch value is object-shaped and form
	// encoding should flatten its fields under the current prefix.
	FlatFormObject bool
	// FlatFormObjectAllowsEmpty is true when the flattened object branch may be
	// selected with only the discriminator because it has no required fields.
	FlatFormObjectAllowsEmpty bool
	// EmptyValueExpr is the Go expression that initializes an empty branch
	// value when FlatFormObjectAllowsEmpty is true.
	EmptyValueExpr string
	// EmitPrimitiveAlias is true when the branch uses a generated primitive alias
	// that must be declared in the same file as the union type.
	EmitPrimitiveAlias bool
	// PrimitiveAliasType is the underlying Go type used by the generated branch
	// alias (for example "string" or "float64").
	PrimitiveAliasType string
	// TypeTag is the JSON "type" discriminator value for this branch.
	TypeTag string
}

UnionFieldData describes a single branch of a union.

type UnionTypeData 

type UnionTypeData struct {
	// Name is the Go type name of the union struct.
	Name string
	// KindName is the Go type name of the discriminator kind.
	KindName string
	// Fields describes each union branch.
	Fields []*UnionFieldData
	// Loc defines the file and Go package of the union type if overridden via
	// Meta. When nil the type is generated in the default service file.
	Loc *codegen.Location
	// TypeKey is the discriminator field name for JSON marshaling (defaults to "type").
	TypeKey string
	// ValueKey is the value field name for JSON marshaling (defaults to "value").
	ValueKey string
	// HasScalarFormBranch is true when at least one branch keeps canonical
	// type/value form encoding.
	HasScalarFormBranch bool
}

UnionTypeData describes a generated sum-type union for a service.

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
	// RemedyCode is the stable remediation code for this error type if declared.
	RemedyCode string
	// SafeMessage is the safe, user-facing message for this error type if declared.
	SafeMessage string
	// RetryHint is retry or correction guidance for this error type if declared.
	RetryHint string
}

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.