httpapi

Documentation

Index

• func Forbidden(rw http.ResponseWriter)
• func ParseCustom[T any](parser *QueryParamParser, vals url.Values, def T, queryParam string, ...) T
• func Read(rw http.ResponseWriter, r *http.Request, value interface{}) bool
• func ResourceNotFound(rw http.ResponseWriter)
• func WebsocketCloseSprintf(format string, vars ...any) string
• func Write(rw http.ResponseWriter, status int, response interface{})
• type Error
• type QueryParamParser
  • func NewQueryParamParser() *QueryParamParser
  • func (p *QueryParamParser) Int(vals url.Values, def int, queryParam string) int
  • func (*QueryParamParser) String(vals url.Values, def string, queryParam string) string
  • func (*QueryParamParser) Strings(vals url.Values, def []string, queryParam string) []string
  • func (p *QueryParamParser) UUID(vals url.Values, def uuid.UUID, queryParam string) uuid.UUID
  • func (p *QueryParamParser) UUIDorMe(vals url.Values, def uuid.UUID, me uuid.UUID, queryParam string) uuid.UUID
  • func (p *QueryParamParser) UUIDs(vals url.Values, def []uuid.UUID, queryParam string) []uuid.UUID
• type Response

Functions

func Forbidden

func Forbidden(rw http.ResponseWriter)

func ParseCustom

func ParseCustom[T any](parser *QueryParamParser, vals url.Values, def T, queryParam string, parseFunc func(v string) (T, error)) T

ParseCustom has to be a function, not a method on QueryParamParser because generics cannot be used on struct methods.

func Read

func Read(rw http.ResponseWriter, r *http.Request, value interface{}) bool

Read decodes JSON from the HTTP request into the value provided. It uses go-validator to validate the incoming request body.

func ResourceNotFound

func ResourceNotFound(rw http.ResponseWriter)

ResourceNotFound is intentionally vague. All 404 responses should be identical to prevent leaking existence of resources.

func WebsocketCloseSprintf

func WebsocketCloseSprintf(format string, vars ...any) string

WebsocketCloseSprintf formats a websocket close message and ensures it is truncated to the maximum allowed length.

func Write

func Write(rw http.ResponseWriter, status int, response interface{})

Write outputs a standardized format to an HTTP response body.

Types

type Error

type Error struct {
	Field  string `json:"field" validate:"required"`
	Detail string `json:"detail" validate:"required"`
}

Error represents a scoped error to a user input.

type QueryParamParser

type QueryParamParser struct {
	// Errors is the set of errors to return via the API. If the length
	// of this set is 0, there are no errors!.
	Errors []Error
}

QueryParamParser is a helper for parsing all query params and gathering all errors in 1 sweep. This means all invalid fields are returned at once, rather than only returning the first error

func NewQueryParamParser

func NewQueryParamParser() *QueryParamParser

func (*QueryParamParser) Int

func (p *QueryParamParser) Int(vals url.Values, def int, queryParam string) int

func (*QueryParamParser) String

func (*QueryParamParser) String(vals url.Values, def string, queryParam string) string

func (*QueryParamParser) Strings

func (*QueryParamParser) Strings(vals url.Values, def []string, queryParam string) []string

func (*QueryParamParser) UUID

func (p *QueryParamParser) UUID(vals url.Values, def uuid.UUID, queryParam string) uuid.UUID

func (*QueryParamParser) UUIDorMe

func (p *QueryParamParser) UUIDorMe(vals url.Values, def uuid.UUID, me uuid.UUID, queryParam string) uuid.UUID

func (*QueryParamParser) UUIDs

func (p *QueryParamParser) UUIDs(vals url.Values, def []uuid.UUID, queryParam string) []uuid.UUID

type Response

type Response struct {
	// Message is an actionable message that depicts actions the request took.
	// These messages should be fully formed sentences with proper punctuation.
	// Examples:
	// - "A user has been created."
	// - "Failed to create a user."
	Message string `json:"message"`
	// Detail is a debug message that provides further insight into why the
	// action failed. This information can be technical and a regular golang
	// err.Error() text.
	// - "database: too many open connections"
	// - "stat: too many open files"
	Detail string `json:"detail,omitempty"`
	// Validations are form field-specific friendly error messages. They will be
	// shown on a form field in the UI. These can also be used to add additional
	// context if there is a set of errors in the primary 'Message'.
	Validations []Error `json:"validations,omitempty"`
}

Response represents a generic HTTP response.