loom

package
v1.0.3 Latest Latest
Warning

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

 Go to latest Published: Mar 22, 2026 License: MIT Imports: 17 Imported by: 6

Documentation

Overview

Package loom contains the core runtime types and helpers for the Loom framework.

Loom is a fork of Goa built for AI-first service development and stronger machine-consumable contracts. It generates transport, endpoint, and service scaffolding from a DSL so that business logic, client code, and published contracts stay aligned. The loom package provides the runtime pieces shared by generated code, including service errors, validation helpers, and transport-neutral interfaces used across HTTP, gRPC, and JSON-RPC.

Compared to upstream Goa, Loom intentionally puts more weight on OpenAPI 3.1 quality, reusable public contract components, direct client-generation compatibility, and framework-owned transport/auth glue that would otherwise be reimplemented in applications. It was pushed in that direction in part to support the creation of Auto-K and similar AI-assisted systems.

Visit https://github.com/CaliLuke/loom for the current repository, releases, and migration notes.

Index

Constants

View Source 
const (
	// MethodKey is the request context key used to store the name of the
	// method as defined in the design. The generated transport code
	// initializes the corresponding value prior to invoking the endpoint.
	MethodKey contextKey = iota + 1

	// ServiceKey is the request context key used to store the name of the
	// service as defined in the design. The generated transport code
	// initializes the corresponding value prior to invoking the endpoint.
	ServiceKey
)
View Source 
const (
	// InvalidFieldType is the error name for invalid field type errors.
	InvalidFieldType = "invalid_field_type"
	// MissingField is the error name for missing field errors.
	MissingField = "missing_field"
	// InvalidEnumValue is the error name for invalid enum value errors.
	InvalidEnumValue = "invalid_enum_value"
	// InvalidFormat is the error name for invalid format errors.
	InvalidFormat = "invalid_format"
	// InvalidPattern is the error name for invalid pattern errors.
	InvalidPattern = "invalid_pattern"
	// InvalidRange is the error name for invalid range errors.
	InvalidRange = "invalid_range"
	// InvalidLength is the error name for invalid length errors.
	InvalidLength = "invalid_length"
	// UnsupportedMediaType is the error name returned by the Loom decoder
	// when the content type of the HTTP request body is not supported.
	UnsupportedMediaType = "unsupported_media_type"
	// DecodePayload is the error name for decode payload errors.
	DecodePayload = "decode_payload"
	// MissingPayload is the error name for missing payload errors.
	MissingPayload = "missing_payload"
)
View Source 
const (
	// FormatDate describes RFC3339 date values.
	FormatDate Format = "date"

	// FormatDateTime describes RFC3339 date time values.
	FormatDateTime Format = "date-time"

	// FormatUUID describes RFC4122 UUID values.
	FormatUUID = "uuid"

	// FormatEmail describes RFC5322 email addresses.
	FormatEmail = "email"

	// FormatHostname describes RFC1035 Internet hostnames.
	FormatHostname = "hostname"

	// FormatIPv4 describes RFC2373 IPv4 address values.
	FormatIPv4 = "ipv4"

	// FormatIPv6 describes RFC2373 IPv6 address values.
	FormatIPv6 = "ipv6"

	// FormatIP describes RFC2373 IPv4 or IPv6 address values.
	FormatIP = "ip"

	// FormatURI describes RFC3986 URI values.
	FormatURI = "uri"

	// FormatMAC describes IEEE 802 MAC-48, EUI-48 or EUI-64 MAC address values.
	FormatMAC = "mac"

	// FormatCIDR describes RFC4632 and RFC4291 CIDR notation IP address values.
	FormatCIDR = "cidr"

	// FormatRegexp describes regular expression syntax accepted by RE2.
	FormatRegexp = "regexp"

	// FormatJSON describes JSON text.
	FormatJSON = "json"

	// FormatRFC1123 describes RFC1123 date time values.
	FormatRFC1123 = "rfc1123"
)
View Source 
const (
	// Major version number
	Major = 1
	// Minor version number
	Minor = 0
	// Build number
	Build = 2
	// Suffix - set to empty string in release tag commits.
	Suffix = ""
)

Variables

This section is empty.

Functions

func Compatible 

func Compatible(v string) (bool, error)

Compatible returns true if Major matches the major version of the given version string. It returns an error if the given string is not a valid version string.

func DecodePayloadError 

func DecodePayloadError(msg string) error

DecodePayloadError is the error produced by the generated code when a request body cannot be decoded successfully.

func ErrorRemedyCode 

func ErrorRemedyCode(err error) string

ErrorRemedyCode returns the stable remediation code associated with err.

func ErrorRetryHint 

func ErrorRetryHint(err error) string

ErrorRetryHint returns retry or correction guidance associated with err.

func ErrorSafeMessage 

func ErrorSafeMessage(err error) string

ErrorSafeMessage returns the safe, user-facing message associated with err. It falls back to err.Error when no safe message was declared.

func ErrorStatusCode 

func ErrorStatusCode(err error) (int, bool)

ErrorStatusCode returns the status code associated with err when the error exposes one via a generic status interface.

func InvalidEnumValueError 

func InvalidEnumValueError(name string, val any, allowed []any) error

InvalidEnumValueError is the error produced by the generated code when the value of a payload field does not match one the values defined in the design Enum validation.

func InvalidFieldTypeError 

func InvalidFieldTypeError(name string, val any, expected string) error

InvalidFieldTypeError is the error produced by the generated code when the type of a payload field does not match the type defined in the design.

func InvalidFormatError 

func InvalidFormatError(name, target string, format Format, formatError error) error

InvalidFormatError is the error produced by the generated code when the value of a payload field does not match the format validation defined in the design.

func InvalidLengthError 

func InvalidLengthError(name string, target any, ln, value int, min bool) error

InvalidLengthError is the error produced by the generated code when the value of a payload field does not match the length validation defined in the design.

func InvalidPatternError 

func InvalidPatternError(name, target, pattern string) error

InvalidPatternError is the error produced by the generated code when the value of a payload field does not match the pattern validation defined in the design.

func InvalidRangeError 

func InvalidRangeError(name string, target, value any, min bool) error

InvalidRangeError is the error produced by the generated code when the value of a payload field does not match the range validation defined in the design. value may be an int or a float64.

func MergeErrors 

func MergeErrors(err, other error) error

MergeErrors updates an error by merging another into it. It first converts other into a ServiceError if not already one. The merge algorithm then:

* uses the name of err if a ServiceError, the name of other otherwise.

* appends both error messages.

* computes Timeout and Temporary by "and"ing the fields of both errors.

Merge returns the updated error. This makes it possible to return other when err is nil.

func MissingFieldError 

func MissingFieldError(name, context string) error

MissingFieldError is the error produced by the generated code when a payload is missing a required field.

func MissingPayloadError 

func MissingPayloadError() error

MissingPayloadError is the error produced by the generated code when a request is missing a required payload.

func NewErrorID 

func NewErrorID() string

NewErrorID creates a unique 8 character ID that is well suited to use as an error identifier.

func SkipResponseWriter 

func SkipResponseWriter(wt io.WriterTo) io.ReadCloser

SkipResponseWriter converts an io.WriterTo into a io.ReadCloser. The Read/Close methods this function returns will pipe the Write calls that wt makes, to implement a Reader that has the written bytes. If Read is called Close must also be called to avoid leaking memory. The returned value implements io.WriterTo as well, so the generated handler will call that instead of the Read method.

Server handlers that use SkipResponseBodyEncodeDecode() io.ReadCloser as a return type.

func UnsupportedMediaTypeError 

func UnsupportedMediaTypeError(ct string) error

UnsupportedMediaTypeError is the error produced by the Loom decoder when the content type of the HTTP request body is not supported.

func ValidateFormat 

func ValidateFormat(name string, val string, f Format) error

ValidateFormat validates val against f. It returns nil if the string conforms to the format, an error otherwise. name is the name of the variable used in error messages. where in a data structure the error occurred if any. The format specification follows the json schema draft 4 validation extension. see http://json-schema.org/latest/json-schema-validation.html#anchor105 Supported formats are:

  • "date": RFC3339 date value
  • "date-time": RFC3339 date time value
  • "email": RFC5322 email address
  • "hostname": RFC1035 Internet host name
  • "ipv4", "ipv6", "ip": RFC2673 and RFC2373 IP address values
  • "uri": RFC3986 URI value
  • "mac": IEEE 802 MAC-48, EUI-48 or EUI-64 MAC address value
  • "cidr": RFC4632 and RFC4291 CIDR notation IP address value
  • "regexp": Regular expression syntax accepted by RE2
  • "rfc1123": RFC1123 date time value

func ValidatePattern 

func ValidatePattern(name, val, p string) error

ValidatePattern returns an error if val does not match the regular expression p. It makes an effort to minimize the number of times the regular expression needs to be compiled. name is the name of the variable used in error messages.

func Version 

func Version() string

Version returns the complete version number.

Types

type Endpoint 

type Endpoint func(ctx context.Context, request any) (response any, err error)

Endpoint exposes service methods to remote clients independently of the underlying transport.

type ErrorRemedy 

type ErrorRemedy struct {
	// Code is the stable remediation code consumers may use to classify the
	// failure.
	Code string `json:"code,omitempty" xml:"code,omitempty" form:"code,omitempty"`
	// SafeMessage is the safe, user-facing message to surface without
	// leaking internal details.
	SafeMessage string `json:"safe_message,omitempty" xml:"safe_message,omitempty" form:"safe_message,omitempty"`
	// RetryHint is concise guidance on how to correct the request or retry.
	RetryHint string `json:"retry_hint,omitempty" xml:"retry_hint,omitempty" form:"retry_hint,omitempty"`
}

ErrorRemedy describes machine-consumable remediation guidance attached to an error.

func ExtractErrorRemedy 

func ExtractErrorRemedy(err error) *ErrorRemedy

ExtractErrorRemedy returns the remediation guidance associated with err, if any.

type Format 

type Format string

Format defines a validation format.

type InterceptorCallType 

type InterceptorCallType int

InterceptorCallType is the type of call the interceptor is handling 

const (
	// InterceptorUnary indicates the interceptor is handling a unary call
	InterceptorUnary InterceptorCallType = iota
	// InterceptorStreamingSend indicates the interceptor is handling a streaming Send
	InterceptorStreamingSend
	// InterceptorStreamingRecv indicates the interceptor is handling a streaming Recv
	InterceptorStreamingRecv
)

type InterceptorInfo 

type InterceptorInfo interface {
	// Service returns the name of the service handling the request.
	Service() string
	// Method returns the name of the method handling the request.
	Method() string
	// CallType returns the type of call the interceptor is handling.
	CallType() InterceptorCallType
	// RawPayload returns the raw payload of the request.
	RawPayload() any
}

InterceptorInfo contains information about the request shared between all interceptors in the service chain. It provides access to the service name, method name, the type of call the interceptor is handling (unary, streaming send, or streaming receive), and the request payload.

type LoomErrorNamer 

type LoomErrorNamer interface {
	LoomErrorName() string
}

LoomErrorNamer is an interface implemented by generated error structs that exposes the name of the error as defined in the design.

type LoomErrorRemedier 

type LoomErrorRemedier interface {
	LoomErrorRemedy() *ErrorRemedy
}

LoomErrorRemedier is implemented by errors that expose remediation guidance defined in the design.

type LoomErrorStatusReporter 

type LoomErrorStatusReporter interface {
	Status() int
}

LoomErrorStatusReporter is implemented by errors that expose an HTTP status code via Status.

type LoomErrorStatuser 

type LoomErrorStatuser interface {
	StatusCode() int
}

LoomErrorStatuser is implemented by errors that expose an HTTP status code.

type ServiceError 

type ServiceError struct {
	// Name is a name for that class of errors.
	Name string
	// ID is a unique value for each occurrence of the error.
	ID string
	// Pointer to the field that caused this error, if appropriate
	Field *string
	// Message contains the specific error details.
	Message string
	// Is the error a timeout?
	Timeout bool
	// Is the error temporary?
	Temporary bool
	// Is the error a server-side fault?
	Fault bool
	// Remedy contains optional remediation guidance for the error.
	Remedy *ErrorRemedy
	// contains filtered or unexported fields
}

ServiceError is the default error type used by the Loom package to encode and decode error responses.

func Fault 

func Fault(format string, v ...any) *ServiceError

Fault creates an error given a format and values a la fmt.Printf. The error has the Fault field set to true.

func NewServiceError 

func NewServiceError(err error, name string, timeout, temporary, fault bool) *ServiceError

NewServiceError creates an error.

func PermanentError 

func PermanentError(name, format string, v ...any) *ServiceError

PermanentError creates an error given a name and a format and values a la fmt.Printf.

func PermanentTimeoutError 

func PermanentTimeoutError(name, format string, v ...any) *ServiceError

PermanentTimeoutError creates an error given a name and a format and values a la fmt.Printf. The error has the Timeout field set to true.

func TemporaryError 

func TemporaryError(name, format string, v ...any) *ServiceError

TemporaryError is an error class that indicates that the error is temporary and that retrying the request may be successful. TemporaryError creates an error given a name and a format and values a la fmt.Printf. The error has the Temporary field set to true.

func TemporaryTimeoutError 

func TemporaryTimeoutError(name, format string, v ...any) *ServiceError

TemporaryTimeoutError creates an error given a name and a format and values a la fmt.Printf. The error has both the Timeout and Temporary fields set to true.

func WithErrorRemedy 

func WithErrorRemedy(err *ServiceError, remedy *ErrorRemedy) *ServiceError

WithErrorRemedy attaches remediation guidance to the given service error and returns it.

func (*ServiceError) Error 

func (e *ServiceError) Error() string

Error returns the error message.

func (*ServiceError) ErrorName deprecated 

func (e *ServiceError) ErrorName() string

ErrorName returns the error name.

Deprecated: Use LoomErrorName.

func (*ServiceError) History 

func (e *ServiceError) History() []*ServiceError

History returns the history of error revisions, ignoring the result of any merges.

func (*ServiceError) LoomErrorName 

func (e *ServiceError) LoomErrorName() string

LoomErrorName returns the error name.

func (*ServiceError) LoomErrorRemedy 

func (e *ServiceError) LoomErrorRemedy() *ErrorRemedy

LoomErrorRemedy returns the remediation guidance attached to the error, if any.

func (*ServiceError) Unwrap 

func (e *ServiceError) Unwrap() error

type WriterToFunc 

type WriterToFunc func(w io.Writer) (err error)

WriterToFunc implements io.WriterTo. The io.Writer passed to the function will be wrapped.

func (WriterToFunc) WriteTo 

func (fn WriterToFunc) WriteTo(w io.Writer) (n int64, err error)

WriteTo writes to w.

The value in w is wrapped when passed to fn keeping track of how bytes are written by fn.

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.