transport

Documentation

Index

• Variables
• type Codec
• type Context
• type Decoder
• type DecoderFunc
  • func NewDecoderChain(decoders ...Decoder) DecoderFunc
  • func (d DecoderFunc) Decode(ctx context.Context, request Request, target any) (err error)
• type Encoder
• type EncoderFunc
  • func (e EncoderFunc) Encode(ctx context.Context, writer Response, response any) error
• type Endpoint
  • func NewEndpoint[Req, Res any](endpointFunc EndpointFunc[Req, Res]) (ep *Endpoint[Req, Res])
  • func (endpoint Endpoint[Req, Res]) Serve(tctx Context) (err error)
  • func (endpoint Endpoint[Req, Res]) WithMiddleware(middleware ...Middleware) Endpoint[Req, Res]
  • func (endpoint Endpoint[Req, Res]) WithValidator(validator Validator) Endpoint[Req, Res]
• type EndpointFunc
• type ErrorEncoder
• type ErrorEncoderFunc
  • func (e ErrorEncoderFunc) EncodeError(ctx context.Context, writer Response, err error) error
• type ErrorResponse
• type Handler
  • func ApplyMiddleware(handler Handler, middleware ...Middleware) Handler
• type HandlerFunc
  • func (h HandlerFunc) Serve(tctx Context) error
• type Middleware
  • func NewMiddleware(middlewareFunc MiddlewareFunc) Middleware
• type MiddlewareFunc
• type Operation
• type PayloadValidator
• type RawEndpoint
  • func NewRawEndpoint(endpointFunc HandlerFunc) *RawEndpoint
  • func (endpoint *RawEndpoint) Serve(tctx Context) (err error)
  • func (endpoint *RawEndpoint) WithMiddleware(middleware ...Middleware) *RawEndpoint
• type Registry
• type Request
• type Response
• type Server
• type Service
• type Validator
• type ValidatorFunc

Variables

var ContextStore = ctxutil.NewStore[Context, contextKey]()

var ErrResponseIntercepted = errors.New("raw response")

ErrResponseIntercepted should be returned by any endpoint that wants to overload the default response behavior

Types

type Codec

type Codec interface {
	Decoder
	Encoder
	ErrorEncoder
}

type Context

type Context interface {
	Codec() Codec
	Request() Request
	Response() Response
}

type Decoder

type Decoder interface {
	Decode(ctx context.Context, request Request, target any) (err error)
}

Decoder is a function that decodes a transport specific request into a concrete type accepted by an EndpointFunc. Use these functions to bind protobuf, json, xml, query params, headers, and cookies to your EndpointFunc.

type DecoderFunc

type DecoderFunc func(ctx context.Context, request Request, target any) (err error)

DecoderFunc is a functional implementation to the Decoder interface

func NewDecoderChain

func NewDecoderChain(decoders ...Decoder) DecoderFunc

func (DecoderFunc) Decode

func (d DecoderFunc) Decode(ctx context.Context, request Request, target any) (err error)

Decode implements Decoder

type Encoder

type Encoder interface {
	Encode(ctx context.Context, writer Response, response any) error
}

Encoder is a function that transforms a concrete response type from an EndpointFunc into a raw byte stream. Typically, this is used to serialize data raw byte data like JSON or Protobuf. This can also be used to map data back on a transport specific response (i.e. headers, cookies, etc).

type EncoderFunc

type EncoderFunc func(ctx context.Context, writer Response, response any) error

EncoderFunc is a functional implementation to the Encoder interface

func (EncoderFunc) Encode

func (e EncoderFunc) Encode(ctx context.Context, writer Response, response any) error

Encode implements Encoder

type Endpoint

type Endpoint[Req, Res any] struct {
	Func       EndpointFunc[Req, Res]
	Validator  Validator
	Middleware []Middleware
}

Endpoint is any function that can be modeled as service call. These should remain transport agnostic and are used to implement business logic.

func NewEndpoint

func NewEndpoint[Req, Res any](
	endpointFunc EndpointFunc[Req, Res],
) (ep *Endpoint[Req, Res])

func (Endpoint[Req, Res]) Serve

func (endpoint Endpoint[Req, Res]) Serve(tctx Context) (err error)

Serve implements transport.Handler TODO: benchmark value receiver vs pointer receiver (maybe have request overhead)

func (Endpoint[Req, Res]) WithMiddleware

func (endpoint Endpoint[Req, Res]) WithMiddleware(middleware ...Middleware) Endpoint[Req, Res]

func (Endpoint[Req, Res]) WithValidator

func (endpoint Endpoint[Req, Res]) WithValidator(validator Validator) Endpoint[Req, Res]

type EndpointFunc

type EndpointFunc[Req, Res any] func(ctx context.Context, request Req) (response Res, err error)

EndpointFunc is a functional implementation of Endpoint

type ErrorEncoder

type ErrorEncoder interface {
	EncodeError(ctx context.Context, writer Response, err error) error
}

ErrorEncoder encodes an error uses Response to send the error to the client

type ErrorEncoderFunc

type ErrorEncoderFunc func(ctx context.Context, writer Response, err error) error

ErrorEncoderFunc is a functional implementation to the ErrorEncoder interface

func (ErrorEncoderFunc) EncodeError

func (e ErrorEncoderFunc) EncodeError(ctx context.Context, writer Response, err error) error

EncodeError implements ErrorEncoder

type ErrorResponse

type ErrorResponse interface {
	GetStatusCode() int
	PrepareResponse() any
}

ErrorResponse is a contract for controlling the status code and response body when an error is raised by an Endpoint Any error that implements this will have the result of PrepareResponse() written to the Response by an Encoder If the transport supports it, the status code will be set to the value returned by GetStatusCode()

type Handler

type Handler interface {
	Serve(tctx Context) (err error)
}

Handler is a transport agnostic handler the request could be cast back

func ApplyMiddleware

func ApplyMiddleware(handler Handler, middleware ...Middleware) Handler

type HandlerFunc

type HandlerFunc func(tctx Context) (err error)

HandlerFunc is a functional alias to the Handler interface

func (HandlerFunc) Serve

func (h HandlerFunc) Serve(tctx Context) error

Serve implements Handler

type Middleware

type Middleware func(Handler) Handler

func NewMiddleware

func NewMiddleware(middlewareFunc MiddlewareFunc) Middleware

NewMiddleware is a convenience method for implementing the function middleware pattern Provide a simple HandlerFunc if it doesn't return an error during a request the next Handler will be called

type MiddlewareFunc

type MiddlewareFunc func(tctx Context, next Handler) error

type Operation

type Operation interface {
	ID() string
	Register(Service)
	WithHandler(Handler)
}

type PayloadValidator

type PayloadValidator interface {
	Validate() error
}

PayloadValidator is an alternative to Validator. If the return value of a Decoder implements PayloadValidator, it will be called. It can be used in lieu of or in tandem with Validator

type RawEndpoint

type RawEndpoint struct {
	HandlerFunc HandlerFunc
	Middleware  []Middleware
}

func NewRawEndpoint

func NewRawEndpoint(
	endpointFunc HandlerFunc,
) *RawEndpoint

func (*RawEndpoint) Serve

func (endpoint *RawEndpoint) Serve(tctx Context) (err error)

func (*RawEndpoint) WithMiddleware

func (endpoint *RawEndpoint) WithMiddleware(middleware ...Middleware) *RawEndpoint

type Registry

type Registry interface {
	Register(Service)
	GetByID(string) (Service, bool)
	Filter(func(Service) bool) []Service
}

type Request

type Request interface {
	URL() *url.URL
	Path() string
	Method() string

	Version() string
	PathParams() url.Values
	QueryParams() url.Values
	Headers() http.Header
	Context() context.Context
	Cookies() []*http.Cookie
	Cookie(name string) (cookie *http.Cookie, err error)
	WithContext(ctx context.Context) Request

	// Body exposes io.ReadCloser from the Underlying request
	// We recommend using http.MaxBytesReader to limit the size of the body
	// Alternatively you can use io.LimitReader to limit the size of the body
	// Consider using a middleware function to limit the maximum size of the body
	Body() io.ReadCloser

	// BodyBuffer returns a buffer that can be used to read the body of the request
	// This should only be used once the body has been read
	// This contains a copy of all the bytes read from the original body
	BodyBuffer() *bytes.Buffer

	// ParseMediaType should forward the return value of mime.ParseMediaType
	ParseMediaType() (mediatype string, params map[string]string, err error)

	// Underlying returns a transport specific request
	// it should return a pointer to the original request (i.e. *http.Request)
	// this should be used with care as it couples your code to a specific transport
	// this is only provided for break glass scenarios where you need raw access
	Underlying() any
}

Request is a transport agnostic interface that maps data from a connection

type Response

type Response interface {
	io.Writer

	// Headers return a set of key value pairs that represent the headers of the underlying transport destination
	// some transports like Kafka, NATs, and temporal share similar header semantics to HTTP
	Headers() http.Header

	// SetStatusCode sets the status code of the response
	SetStatusCode(int)

	// GetStatusCode returns the status code sent to the client of the response
	GetStatusCode() int

	// BytesWritten returns the number of bytes written to the transport destination
	BytesWritten() int64

	// DelCookie deletes a cookie from the response
	DelCookie(cookie http.Cookie) Response

	// DelCookieByName deletes a cookie from the response by name
	DelCookieByName(name string) Response

	// SetCookie sets a cookie on the response
	SetCookie(cookie http.Cookie) Response

	// Redirect redirects the response to a new url with a given status code
	// specifically useful over HTTP using the Location header
	Redirect(req Request, url string, code int)

	// BodyBuffer returns a buffer that can be used to read the body of the response
	// this should only be used after the response has been written
	// once the response has been written; the buffer will contain the bytes written to the response
	BodyBuffer() *bytes.Buffer

	// Underlying returns a transport-specific response
	// it should return an interface or pointer to the original response (i.e. http.ResponseWriter)
	// this should be used with care as it couples your code to a specific transport
	// this is only provided for break glass scenarios where you need raw access
	Underlying() any
}

Response is a transport agnostic interface that maps data to a connection

type Server

type Server interface {
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
	Wait() error
}

type Service

type Service interface {
	ID() string
	Register(Registry)
	WithOperations(...Operation)
}

type Validator

type Validator interface {
	Validate(ctx context.Context, decoded any) error
}

Validator receives a value from a Decoder and validates it. If an error is returned it will be passed to an ErrorEncoder.

type ValidatorFunc

type ValidatorFunc func(ctx context.Context, decoded any) error

ValidatorFunc is a functional implementation to the Validator interface