turtleware

package module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Jun 7, 2025 License: MIT Imports: 31 Imported by: 3

README

test Go Reference Go Report Card codecov

turtleware

turtleware is an opinionated framework for creating REST services. It provides pluggable middlewares and some utility methods to simplify life. It uses JWT bearer authentication, and relies heavily on caching.

The framework is built on some core libraries:

Download:

go get github.com/kernle32dll/turtleware

Detailed documentation can be found on pkg.go.dev.

State of the project

turtleware is actively used in productive projects by the author.

Still, this project is still pretty much work-in-progress. Bugs happen, and breaking-changes might occur at any time. Also, only the most recent Go version is supported at any time for now. Code coverage is low, and documentation slim, so be warned.

Getting started

turtleware provides three distinct functionalities:

  1. A set of middlewares, which can be chained individually (e.g., auth)
  2. Composition methods for chaining these middlewares together in a meaningful way (e.g. a GET endpoint)
  3. Optional multi tenancy

For a complete example, look at the main.go in the examples folder.

Documentation

Index

Constants

View Source 
const TracerName = "github.com/kernle32dll/turtleware"

Variables

View Source 
var (
	// ErrTokenValidationFailed indicates that the token provided
	// could not be validated.
	ErrTokenValidationFailed = errors.New("failed to validate token signature")

	// ErrMissingAuthHeader indicates that a requested was
	// missing an authentication header.
	ErrMissingAuthHeader = errors.New("authentication header missing")

	// ErrAuthHeaderWrongFormat indicates that a requested contained an a authorization
	// header, but it was in the wrong format.
	ErrAuthHeaderWrongFormat = errors.New("authorization header format must be Bearer {token}")

	// ErrFailedToParsePrivateKey indicates a problem parsing a given private key as a JWK.
	ErrFailedToParsePrivateKey = errors.New("failed to parse private key as JWK")

	// ErrFailedToSetKID indicates a problem setting the KID field of a JWK.
	ErrFailedToSetKID = errors.New("failed to set 'kid' field")

	// ErrFailedToSetAlgorithm indicates a problem setting the alg field of a JWK.
	ErrFailedToSetAlgorithm = errors.New("failed to set 'alg' field")
)
View Source 
var (
	// ErrContextMissingAuthToken is an internal error indicating a missing
	// auth token in the request context, whereas one was expected.
	ErrContextMissingAuthToken = errors.New("missing auth token in context")

	// ErrContextMissingEntityUUID is an internal error indicating a missing
	// entity UUID in the request context, whereas one was expected.
	ErrContextMissingEntityUUID = errors.New("missing entity UUID in context")

	// ErrContextMissingPaging is an internal error indicating missing paging
	// in the request context, whereas one was expected.
	ErrContextMissingPaging = errors.New("missing paging in context")

	// ErrContextMissingAuthClaims is an internal error indicating missing auth
	// claims in the request context, whereas they were expected.
	ErrContextMissingAuthClaims = errors.New("missing auth claims in context")

	// ErrMarshalling signals that an error occurred while marshalling.
	ErrMarshalling = errors.New("failed to parse message body")

	// ErrReceivingResults signals that an error occurred while receiving the results
	// from the database or similar.
	ErrReceivingResults = errors.New("error while receiving results")

	// ErrResourceNotFound indicates that a requested resource was not found.
	ErrResourceNotFound = errors.New("resource not found")

	// ErrReceivingMeta signals that an error occurred while receiving the metadata
	// from the database or remotes.
	ErrReceivingMeta = errors.New("error while receiving metadata")

	// ErrMissingUserUUID signals that a received JWT did not contain an user UUID.
	ErrMissingUserUUID = errors.New("token does not include user UUID")
)
View Source 
var (
	// ErrUnmodifiedSinceHeaderMissing is returned when the If-Unmodified-Since header is missing.
	ErrUnmodifiedSinceHeaderMissing = errors.New("If-Unmodified-Since header missing")

	// ErrUnmodifiedSinceHeaderInvalid is returned when the If-Unmodified-Since header is in an invalid format.
	ErrUnmodifiedSinceHeaderInvalid = errors.New("received If-Unmodified-Since header in invalid format")

	// ErrNoChanges is returned when the patch request did not contain any changes.
	ErrNoChanges = errors.New("patch request did not contain any changes")

	// ErrNoDateTimeLayoutMatched is returned when the If-Unmodified-Since header does not match any known date time layout.
	ErrNoDateTimeLayoutMatched = errors.New("no date time layout matched")
)
View Source 
var (
	// ErrInvalidOffset indicates that the query contained an invalid
	// offset parameter (e.g. non-numeric).
	ErrInvalidOffset = errors.New("invalid offset parameter")

	// ErrInvalidLimit indicates that the query contained an invalid
	// limit parameter (e.g. non-numeric).
	ErrInvalidLimit = errors.New("invalid limit parameter")
)
View Source 
var (

	// EmissioneWriter is the globally used writer for writing out response bodies.
	EmissioneWriter = emissione.New(jsonWriter, emissione.WriterMapping{
		"application/json":                jsonWriter,
		"application/json;charset=utf-8":  jsonWriter,
		"application/json; charset=utf-8": jsonWriter,
		"application/xml":                 xmlWriter,
		"application/xml;charset=utf-8":   xmlWriter,
		"application/xml; charset=utf-8":  xmlWriter,
	})
)

Functions

func AuthBearerHeaderMiddleware 

func AuthBearerHeaderMiddleware(h http.Handler) http.Handler

AuthBearerHeaderMiddleware is a http middleware for extracting the bearer token from the authorization header, and passing it down. If the header is not existing, the WWW-Authenticate header is set and the handler bails out.

func AuthClaimsFromRequestContext 

func AuthClaimsFromRequestContext(ctx context.Context) (map[string]interface{}, error)

func AuthClaimsMiddleware 

func AuthClaimsMiddleware(keySet jwk.Set) func(http.Handler) http.Handler

AuthClaimsMiddleware is a http middleware for extracting authentication claims, and passing them down.

func AuthTokenFromRequestContext 

func AuthTokenFromRequestContext(ctx context.Context) (string, error)

func CountHeaderMiddleware 

func CountHeaderMiddleware(
	countFetcher ListCountFunc,
	errorHandler ErrorHandlerFunc,
) func(http.Handler) http.Handler

CountHeaderMiddleware is a middleware for injecting an X-Total-Count header into the response, by the provided ListCountFunc. If an error is encountered, the provided ErrorHandlerFunc is called.

func DefaultCreateErrorHandler 

func DefaultCreateErrorHandler(ctx context.Context, w http.ResponseWriter, r *http.Request, err error)

DefaultCreateErrorHandler is a default error handler, which sensibly handles errors known by turtleware.

func DefaultErrorHandler 

func DefaultErrorHandler(ctx context.Context, w http.ResponseWriter, r *http.Request, err error)

DefaultErrorHandler is a default error handler, which sensibly handles errors known by turtleware.

func DefaultFileUploadErrorHandler 

func DefaultFileUploadErrorHandler(ctx context.Context, w http.ResponseWriter, r *http.Request, err error)

DefaultFileUploadErrorHandler is a default error handler, which sensibly handles errors known by turtleware.

func DefaultPatchErrorHandler 

func DefaultPatchErrorHandler(ctx context.Context, w http.ResponseWriter, r *http.Request, err error)

DefaultPatchErrorHandler is a default error handler, which sensibly handles errors known by turtleware.

func EntityUUIDFromRequestContext 

func EntityUUIDFromRequestContext(ctx context.Context) (string, error)

func EntityUUIDMiddleware 

func EntityUUIDMiddleware(entityFunc ResourceEntityFunc) func(h http.Handler) http.Handler

EntityUUIDMiddleware is a http middleware for extracting the UUID of the resource requested, and passing it down.

func ExtractCacheHeader 

func ExtractCacheHeader(r *http.Request) (string, time.Time)

ExtractCacheHeader extracts the Etag (If-None-Match) and last modification (If-Modified-Since) headers from a given request.

func FileUploadMiddleware 

func FileUploadMiddleware(fileHandleFunc FileHandleFunc, errorHandler ErrorHandlerFunc) func(http.Handler) http.Handler

FileUploadMiddleware is a middleware that handles uploads of one or multiple files. Uploads are parsed from the request via HandleFileUpload, and then passed to the provided FileHandleFunc. Errors encountered during the process are passed to the provided ErrorHandlerFunc.

func FromAuthHeader 

func FromAuthHeader(r *http.Request) (string, error)

FromAuthHeader is a "TokenExtractor" that takes a give request and extracts the JWT token from the Authorization header.

Copied from https://github.com/auth0/go-jwt-middleware/blob/master/jwtmiddleware.go

func GetIfUnmodifiedSince 

func GetIfUnmodifiedSince(r *http.Request) (time.Time, error)

GetIfUnmodifiedSince tries to parse a time.Time from the If-Unmodified-Since header of a given request. It tries the following formats (in that order):

- time.RFC1123 - time.RFC3339Nano - time.RFC3339

func HandleFileUpload 

func HandleFileUpload(ctx context.Context, r *http.Request, fileHandleFunc FileHandleFunc) error

HandleFileUpload is a helper function for handling file uploads. It parses upload metadata from the request, and then calls the provided FileHandleFunc for each file part. Errors encountered during the process are passed to the caller.

func IsHandledByDefaultCreateErrorHandler 

func IsHandledByDefaultCreateErrorHandler(err error) bool

IsHandledByDefaultCreateErrorHandler indicates if the DefaultCreateErrorHandler has any special handling for the given error, or if it defaults to handing it out as-is.

func IsHandledByDefaultErrorHandler 

func IsHandledByDefaultErrorHandler(err error) bool

IsHandledByDefaultErrorHandler indicates if the DefaultErrorHandler has any special handling for the given error, or if it defaults to handing it out as-is.

func IsHandledByDefaultFileUploadErrorHandler 

func IsHandledByDefaultFileUploadErrorHandler(err error) bool

IsHandledByDefaultFileUploadErrorHandler indicates if the DefaultFileUploadErrorHandler has any special handling for the given error, or if it defaults to handing it out as-is.

func IsHandledByDefaultPatchErrorHandler 

func IsHandledByDefaultPatchErrorHandler(err error) bool

IsHandledByDefaultPatchErrorHandler indicates if the DefaultPatchErrorHandler has any special handling for the given error, or if it defaults to handing it out as-is.

func JWKFromPrivateKey 

func JWKFromPrivateKey(privateKey crypto.PrivateKey, kid string) (jwk.Key, error)

JWKFromPrivateKey parses a given crypto.PrivateKey as a JWK, and tries to set the KID field of it. It also tries to guess the algorithm for signing with the JWK.

func JWKFromPublicKey 

func JWKFromPublicKey(publicKey crypto.PublicKey, kid string) (jwk.Key, error)

JWKFromPublicKey parses a given crypto.PublicKey as a JWK, and tries to set the KID field of it.

func ListCacheMiddleware 

func ListCacheMiddleware(
	hashFetcher ListHashFunc,
	errorHandler ErrorHandlerFunc,
) func(h http.Handler) http.Handler

ListCacheMiddleware is a middleware for transparently handling caching via the provided ListHashFunc. The next handler of the middleware is only called on a cache miss. That is, if the If-None-Match header and the fetched hash differ. If the ListHashFunc returns either sql.ErrNoRows or os.ErrNotExist, the sha256 hash of an empty string is assumed as the hash. If an error is encountered, the provided ErrorHandlerFunc is called.

func ListSQLHandler 

func ListSQLHandler[T any](
	keySet jwk.Set,
	listEndpoint GetSQLListEndpoint[T],
) http.Handler

ListSQLHandler composes a full http.Handler for retrieving a list of resources via SQL. This includes authentication, caching, and data retrieval.

func ListSQLxHandler 

func ListSQLxHandler[T any](
	keySet jwk.Set,
	listEndpoint GetSQLxListEndpoint[T],
) http.Handler

ListSQLxHandler composes a full http.Handler for retrieving a list of resources via SQL. This includes authentication, caching, and data retrieval.

func PagingMiddleware 

func PagingMiddleware(h http.Handler) http.Handler

PagingMiddleware is a http middleware for extracting paging information, and passing it down.

func ReadKeySetFromFolder 

func ReadKeySetFromFolder(ctx context.Context, path string) (jwk.Set, error)

ReadKeySetFromFolder recursively reads a folder for public keys to assemble a JWK set from.

func RequestLoggerMiddleware 

func RequestLoggerMiddleware(opts ...LoggingOption) func(next http.Handler) http.Handler

RequestLoggerMiddleware is a http middleware for logging non-sensitive properties about the request.

func RequestNotAllowedHandler 

func RequestNotAllowedHandler(opts ...LoggingOption) http.Handler

RequestNotAllowedHandler is a http handler for logging requests which were url matched, but using an invalid method. This is mostly useful for gorilla/mux with its MethodNotAllowedHandler.

func RequestNotFoundHandler 

func RequestNotFoundHandler(opts ...LoggingOption) http.Handler

RequestNotFoundHandler is a http handler for logging requests which were not matched. This is mostly useful for gorilla/mux with its NotFoundHandler.

func RequestTimingMiddleware 

func RequestTimingMiddleware() func(next http.Handler) http.Handler

RequestTimingMiddleware is a http middleware for timing the response time of a request.

func ResourceCacheMiddleware 

func ResourceCacheMiddleware(
	lastModFetcher ResourceLastModFunc,
	errorHandler ErrorHandlerFunc,
) func(h http.Handler) http.Handler

ResourceCacheMiddleware is a middleware for transparently handling caching of a single entity (or resource) via the provided ResourceLastModFunc. The next handler of the middleware is only called when the If-Modified-Since header and the fetched last modification date differ. If an error is encountered, the provided ErrorHandlerFunc is called.

func ResourceCreateHandler 

func ResourceCreateHandler[T CreateDTO](
	keySet jwk.Set,
	createEndpoint CreateEndpoint[T],
	nextHandler http.Handler,
) http.Handler

ResourceCreateHandler composes a full http.Handler for creating a new resource. This includes authentication, and delegation of resource creation.

func ResourceCreateMiddleware 

func ResourceCreateMiddleware[T CreateDTO](createFunc CreateFunc[T], errorHandler ErrorHandlerFunc) func(http.Handler) http.Handler

ResourceCreateMiddleware is a middleware for creating a new resource. It parses a turtleware.CreateDTO from the request body, validates it, and then calls the provided CreateFunc. Errors encountered during the process are passed to the provided turtleware.ErrorHandlerFunc.

func ResourceDataHandler 

func ResourceDataHandler[T any](dataFetcher ResourceDataFunc[T], errorHandler ErrorHandlerFunc) http.Handler

ResourceDataHandler is a handler for serving a single resource. Data is retrieved from the given ResourceDataFunc, and then serialized to the http.ResponseWriter. If the response is an io.Reader, the response is streamed to the client via StreamResponse. Otherwise, the entire result set is read before writing the response. Errors encountered during the process are passed to the provided ErrorHandlerFunc.

func ResourceHandler 

func ResourceHandler[T any](
	keySet jwk.Set,
	getEndpoint GetEndpoint[T],
) http.Handler

ResourceHandler composes a full http.Handler for retrieving a single resource. This includes authentication, caching, and data retrieval.

func ResourcePatchHandler 

func ResourcePatchHandler[T PatchDTO](
	keySet jwk.Set,
	patchEndpoint PatchEndpoint[T],
	nextHandler http.Handler,
) http.Handler

ResourcePatchHandler composes a full http.Handler for updating an existing resource. This includes authentication, and delegation of resource updating.

func ResourcePatchMiddleware 

func ResourcePatchMiddleware[T PatchDTO](patchFunc PatchFunc[T], errorHandler ErrorHandlerFunc) func(http.Handler) http.Handler

ResourcePatchMiddleware is a middleware for patching or updating an existing resource. It parses a PatchDTO from the request body, validates it, and then calls the provided PatchFunc. Errors encountered during the process are passed to the provided ErrorHandlerFunc.

func SQLListDataHandler 

func SQLListDataHandler[T any](dataFetcher ListSQLDataFunc, dataTransformer SQLResourceFunc[T], errorHandler ErrorHandlerFunc) http.Handler

SQLListDataHandler is a handler for serving a list of resources from a SQL source. Data is retrieved via a sql.Rows iterator retrieved from the given ListSQLDataFunc, scanned into a struct via the SQLResourceFunc, and then serialized to the http.ResponseWriter. Serialization is buffered, so the entire result set is read before writing the response. Errors encountered during the process are passed to the provided ErrorHandlerFunc.

func SQLxListDataHandler 

func SQLxListDataHandler[T any](dataFetcher ListSQLxDataFunc, dataTransformer SQLxResourceFunc[T], errorHandler ErrorHandlerFunc) http.Handler

SQLxListDataHandler is a handler for serving a list of resources from a SQL source via sqlx. Data is retrieved via a sqlx.Rows iterator retrieved from the given ListSQLxDataFunc, scanned into a struct via the SQLxResourceFunc, and then serialized to the http.ResponseWriter. Serialization is buffered, so the entire result set is read before writing the response. Errors encountered during the process are passed to the provided ErrorHandlerFunc.

func StaticListDataHandler 

func StaticListDataHandler[T any](dataFetcher ListStaticDataFunc[T], errorHandler ErrorHandlerFunc) http.Handler

StaticListDataHandler is a handler for serving a list of resources from a static list. Data is retrieved from the given ListStaticDataFunc, and then serialized to the http.ResponseWriter. Errors encountered during the process are passed to the provided ErrorHandlerFunc.

func StaticListHandler 

func StaticListHandler[T any](
	keySet jwk.Set,
	listEndpoint GetStaticListEndpoint[T],
) http.Handler

StaticListHandler composes a full http.Handler for retrieving a list of resources from a static list. This includes authentication, caching, and data retrieval.

func StreamResponse 

func StreamResponse(reader io.Reader, w http.ResponseWriter, r *http.Request, errorHandler ErrorHandlerFunc)

StreamResponse streams the provided io.Reader to the http.ResponseWriter. The function tries to determine the content type of the stream by reading the first 512 bytes, and sets the content-type HTTP header accordingly. Errors encountered during the process are passed to the provided ErrorHandlerFunc.

func TagContextSpanWithError 

func TagContextSpanWithError(ctx context.Context, err error) error

TagContextSpanWithError tries to retrieve an open telemetry span from the given context, and sets some error attributes, signaling that the current span has failed. If no span exists, this function does nothing. This function returns the error as provided, to facilitate easy error returning in using functions.

func TracingMiddleware 

func TracingMiddleware(name string, traceProvider trace.TracerProvider) func(http.Handler) http.Handler

TracingMiddleware is a http middleware for injecting a new named open telemetry span into the request context. If tracer is nil, otel.GetTracerProvider() is used.

func UserUUIDFromRequestContext 

func UserUUIDFromRequestContext(ctx context.Context) (string, error)

func ValidateTokenBySet 

func ValidateTokenBySet(
	tokenString string, keySet jwk.Set,
) (map[string]interface{}, error)

ValidateTokenBySet validates the given token with the given key set. If a key matches, the containing claims are returned.

func WrapZerologTracing 

func WrapZerologTracing(ctx context.Context) zerolog.Logger

WrapZerologTracing fetches the zerolog.Logger attached with the context (if existing), and creates a new logger with the context's spanID and traceID fields set.

func WriteError 

func WriteError(
	ctx context.Context,
	w http.ResponseWriter,
	r *http.Request,
	code int,
	errors ...error,
)

WriteError sets the given status code, and writes a nicely formatted json errors to the response body - if the request type is not HEAD.

Types

type CreateDTO 

type CreateDTO interface {
	Validate() []error
}

CreateDTO defines the contract for validating a DTO used for creating a new resource.

type CreateEndpoint 

type CreateEndpoint[T CreateDTO] interface {
	EntityUUID(r *http.Request) (string, error)
	CreateEntity(ctx context.Context, entityUUID, userUUID string, create T) error
	HandleError(ctx context.Context, w http.ResponseWriter, r *http.Request, err error)
}

CreateEndpoint defines the contract for a ResourceCreateHandler composition.

type CreateFunc 

type CreateFunc[T CreateDTO] func(ctx context.Context, entityUUID, userUUID string, create T) error

CreateFunc is a function called for delegating the handling of the creation of a new resource.

type ErrorHandlerFunc 

type ErrorHandlerFunc func(ctx context.Context, w http.ResponseWriter, r *http.Request, err error)

ErrorHandlerFunc is a function for handling arbitrary errors, that can happen during and turtleware middleware. If in doubt, use turtleware.DefaultErrorHandler, which handles many errors with meaningful error output.

type FileHandleFunc 

type FileHandleFunc func(ctx context.Context, entityUUID, userUUID string, fileName string, file multipart.File) error

FileHandleFunc is a function that handles a single file upload.

type GetEndpoint 

type GetEndpoint[T any] interface {
	EntityUUID(r *http.Request) (string, error)
	LastModification(ctx context.Context, entityUUID string) (time.Time, error)
	FetchEntity(ctx context.Context, entityUUID string) (T, error)
	HandleError(ctx context.Context, w http.ResponseWriter, r *http.Request, err error)
}

GetEndpoint defines the contract for a ResourceHandler composition.

type GetSQLListEndpoint 

type GetSQLListEndpoint[T any] interface {
	ListHash(ctx context.Context, paging Paging) (string, error)
	TotalCount(ctx context.Context) (uint, error)
	FetchRows(ctx context.Context, paging Paging) (*sql.Rows, error)
	TransformEntity(ctx context.Context, r *sql.Rows) (T, error)
	HandleError(ctx context.Context, w http.ResponseWriter, r *http.Request, err error)
}

GetSQLListEndpoint defines the contract for a ListSQLHandler composition.

type GetSQLxListEndpoint 

type GetSQLxListEndpoint[T any] interface {
	ListHash(ctx context.Context, paging Paging) (string, error)
	TotalCount(ctx context.Context) (uint, error)
	FetchRows(ctx context.Context, paging Paging) (*sqlx.Rows, error)
	TransformEntity(ctx context.Context, r *sqlx.Rows) (T, error)
	HandleError(ctx context.Context, w http.ResponseWriter, r *http.Request, err error)
}

GetSQLxListEndpoint defines the contract for a ListSQLxHandler composition.

type GetStaticListEndpoint 

type GetStaticListEndpoint[T any] interface {
	ListHash(ctx context.Context, paging Paging) (string, error)
	TotalCount(ctx context.Context) (uint, error)
	FetchEntities(ctx context.Context, paging Paging) ([]T, error)
	HandleError(ctx context.Context, w http.ResponseWriter, r *http.Request, err error)
}

GetStaticListEndpoint defines the contract for a StaticListHandler composition.

type ListCountFunc 

type ListCountFunc func(ctx context.Context) (uint, error)

ListCountFunc is a function for returning the total amount of entities for a list endpoint. The function may return sql.ErrNoRows or os.ErrNotExist to indicate that there are not elements, for easier handling.

type ListHashFunc 

type ListHashFunc func(ctx context.Context, paging Paging) (string, error)

ListHashFunc is a function for returning a calculated hash for a given subset of entities via the given paging, for a list endpoint. The function may return sql.ErrNoRows or os.ErrNotExist to indicate that there are not elements, for easier handling.

type ListSQLDataFunc 

type ListSQLDataFunc func(ctx context.Context, paging Paging) (*sql.Rows, error)

ListSQLDataFunc is a function for retrieving a sql.Rows iterator, scoped to the provided paging.

type ListSQLxDataFunc 

type ListSQLxDataFunc func(ctx context.Context, paging Paging) (*sqlx.Rows, error)

ListSQLxDataFunc is a function for retrieving a sqlx.Rows iterator, scoped to the provided paging.

type ListStaticDataFunc 

type ListStaticDataFunc[T any] func(ctx context.Context, paging Paging) ([]T, error)

ListStaticDataFunc is a function for retrieving a slice of data, scoped to the provided paging.

type LoggingOption 

type LoggingOption func(*loggingOptions)

LoggingOption represents an option for the logging parameters.

func LogHeaderBlacklist 

func LogHeaderBlacklist(headerBlacklist ...string) LoggingOption

LogHeaderBlacklist sets a blacklist of headers to disallow. Automatically replaces the whitelist if used. The default is not set, which means "allow all".

func LogHeaderWhitelist 

func LogHeaderWhitelist(headerWhitelist ...string) LoggingOption

LogHeaderWhitelist sets a whitelist of headers to allow. Automatically replaces the blacklist if used. The default is not set, which means "allow all".

func LogHeaders 

func LogHeaders(logHeaders bool) LoggingOption

LogHeaders sets whether headers should be logged. The default is false.

type Paging 

type Paging struct {
	Offset uint32
	Limit  uint16
}

Paging is a simple holder for applying offsets and limits.

func PagingFromRequestContext 

func PagingFromRequestContext(ctx context.Context) (Paging, error)

func ParsePagingFromRequest 

func ParsePagingFromRequest(r *http.Request) (Paging, error)

ParsePagingFromRequest parses Paging information from a given request.

func (Paging) String 

func (paging Paging) String() string

String provides a simple way of stringifying paging information for requests.

type PatchDTO 

type PatchDTO interface {
	HasChanges() bool
	Validate() []error
}

PatchDTO defines the contract for validating a DTO used for patching a new resource.

type PatchEndpoint 

type PatchEndpoint[T PatchDTO] interface {
	EntityUUID(r *http.Request) (string, error)
	UpdateEntity(ctx context.Context, entityUUID, userUUID string, patch T, ifUnmodifiedSince time.Time) error
	HandleError(ctx context.Context, w http.ResponseWriter, r *http.Request, err error)
}

PatchEndpoint defines the contract for a ResourcePatchHandler composition.

type PatchFunc 

type PatchFunc[T PatchDTO] func(ctx context.Context, entityUUID, userUUID string, patch T, ifUnmodifiedSince time.Time) error

PatchFunc is a function called for delegating the actual updating of an existing resource.

type ResourceDataFunc 

type ResourceDataFunc[T any] func(ctx context.Context, entityUUID string) (T, error)

ResourceDataFunc is a function for retrieving a single resource via its UUID.

type ResourceEntityFunc 

type ResourceEntityFunc func(r *http.Request) (string, error)

type ResourceLastModFunc 

type ResourceLastModFunc func(ctx context.Context, entityUUID string) (time.Time, error)

ResourceLastModFunc is a function for returning the last modification data for a specific entity. The function may return sql.ErrNoRows or os.ErrNotExist to indicate that there are not elements, for easier handling.

type SQLResourceFunc 

type SQLResourceFunc[T any] func(ctx context.Context, r *sql.Rows) (T, error)

SQLResourceFunc is a function for scanning a single row from a sql.Rows iterator, and transforming it into a struct type.

type SQLxResourceFunc 

type SQLxResourceFunc[T any] func(ctx context.Context, r *sqlx.Rows) (T, error)

SQLxResourceFunc is a function for scanning a single row from a sqlx.Rows iterator, and transforming it into a struct type.

type TracingOption 

type TracingOption func(*tracingOptions)

TracingOption represents an option for the tracing parameters.

func TraceHeaderBlacklist 

func TraceHeaderBlacklist(headerBlacklist ...string) TracingOption

TraceHeaderBlacklist sets a blacklist of headers to disallow. Automatically replaces the whitelist if used. The default is not set, which means "deny all".

func TraceHeaderWhitelist 

func TraceHeaderWhitelist(headerWhitelist ...string) TracingOption

TraceHeaderWhitelist sets a whitelist of headers to allow. Automatically replaces the blacklist if used. The default is not set, which means "deny all".

func TracingRoundTripper 

func TracingRoundTripper(roundTripper http.RoundTripper) TracingOption

TracingRoundTripper sets the RoundTripper interface actually used to make requests. The default is nil, which means http.DefaultTransport.

func TracingTracer 

func TracingTracer(tracer trace.TracerProvider) TracingOption

TracingTracer sets the Tracer interface used for tracing. The default is nil, which means otel.GetTracerProvider()

type TracingTransport 

type TracingTransport struct {
	// contains filtered or unexported fields
}

TracingTransport is an implementation of http.RoundTripper that will inject tracing information, and then call the actual Transport.

func NewTracingTransport 

func NewTracingTransport(opts ...TracingOption) *TracingTransport

func (TracingTransport) RoundTrip 

func (c TracingTransport) RoundTrip(req *http.Request) (*http.Response, error)

type ValidationWrapperError 

type ValidationWrapperError struct {
	Errors []error
}

ValidationWrapperError is a wrapper for indicating that the validation for a create or patch endpoint failed, via the containing errors.

func (ValidationWrapperError) As 

func (validationWrapperError ValidationWrapperError) As(target interface{}) bool

func (ValidationWrapperError) Error 

func (validationWrapperError ValidationWrapperError) Error() string

func (ValidationWrapperError) Unwrap 

func (validationWrapperError ValidationWrapperError) Unwrap() []error

Source Files

View all Source files

Directories

Path Synopsis
examples module
tenant module

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.