Documentation
¶
Overview ¶
Package response is the single shape every HTTP response in an inceptools service takes, and the single place an outgoing message is scrubbed.
One envelope, always:
{ "data": <payload|null>, "meta": { "success": true, "traceId": "...", ... } }
A client written against one endpoint can read every endpoint: success is a boolean in a fixed place, pagination is in a fixed place, the trace id to quote in a support ticket is in a fixed place. The cost is a wrapper object; the benefit is that no consumer ever has to ask what shape THIS route returns.
The other reason this package is narrow: Send is the funnel. Every response passes through it, so the leak check runs once, here, rather than being remembered at several hundred call sites.
Index ¶
- Constants
- func Accepted(c fiber.Ctx, message string, data any) error
- func BadRequest(c fiber.Ctx, message string, data any) error
- func Conflict(c fiber.Ctx, message string) error
- func Created(c fiber.Ctx, message string, data any) error
- func Fail(c fiber.Ctx, err error) error
- func FailValidation(c fiber.Ctx, details []errs.Detail) error
- func Forbidden(c fiber.Ctx, message string) error
- func InternalError(c fiber.Ctx) error
- func List(c fiber.Ctx, message string, data any, page, pageSize int, total int64) error
- func NoContent(c fiber.Ctx) error
- func NotFound(c fiber.Ctx, message string) error
- func OK(c fiber.Ctx, message string, data any) error
- func PaymentRequired(c fiber.Ctx, message string) error
- func Route(c fiber.Ctx) string
- func Send(c fiber.Ctx, status int, message string, data any) error
- func ServiceUnavailable(c fiber.Ctx, message string) error
- func SetSanitizer(s Sanitizer)
- func StatusFor(kind errs.Kind) int
- func StatusForError(err error) int
- func TooManyRequests(c fiber.Ctx, message string) error
- func TraceID(c fiber.Ctx) string
- func Unauthorized(c fiber.Ctx, message string) error
- func UnprocessableEntity(c fiber.Ctx, message string, data any) error
- type Envelope
- type Meta
- type Sanitizer
Constants ¶
const ( LocalTraceID = "traceId" LocalStartKey = "startTime" )
Keys under which the middleware stores per-request values on fiber.Ctx.
Variables ¶
This section is empty.
Functions ¶
func Accepted ¶
Accepted writes 202 — the right code for work that was queued rather than done. Provisioning a VM is Accepted, not Created: the resource record exists but the thing itself does not yet.
func BadRequest ¶
BadRequest writes 400.
func Fail ¶
Fail writes the HTTP response for any error.
This is what a controller returns on the sad path — `return response.Fail(c, err)` — and what the exception filter calls for anything that escaped. An *errs.Error decides its own status, code and field details. Anything else is a 500 whose message is replaced, because an unclassified error is by definition one nobody checked for leaks.
func FailValidation ¶
FailValidation writes 400 with field-scoped details, the shape a form expects.
func InternalError ¶
InternalError writes 500 with a generic message. The message you pass is NOT sent — log it instead; the client gets the trace id.
func NoContent ¶
NoContent writes 204 with no body. It is the one response that is NOT an envelope, because 204 means exactly that.
func PaymentRequired ¶
PaymentRequired writes 402.
func Send ¶
Send writes the envelope. Every other function in this package goes through it, and so should any responder you add.
func ServiceUnavailable ¶
ServiceUnavailable writes 503.
func SetSanitizer ¶
func SetSanitizer(s Sanitizer)
SetSanitizer installs the outgoing-message filter. Passing nil removes it. Call it once, at boot.
func StatusFor ¶
StatusFor maps an error kind to an HTTP status. It is exported so a custom exception filter can reuse the mapping without re-deriving it.
func StatusForError ¶ added in v1.1.0
StatusForError is the status an error will END UP with once the exception filter has run.
Instrumentation needs this. A middleware observes `c.Next()` returning an error, but the status on the response is still the default at that point: Fiber invokes the error handler after the whole chain has unwound. A collector that reads the status code there records a failed request as a 200 — the route that fails every time looks perfectly healthy.
func TooManyRequests ¶
TooManyRequests writes 429.
Types ¶
type Meta ¶
type Meta struct {
Success bool `json:"success"`
TraceID string `json:"traceId"`
Message string `json:"message"`
RequestTime int64 `json:"requestTime"` // milliseconds spent serving
StatusCode int `json:"statusCode"`
Route string `json:"route"`
// Code is the machine-readable error code, set only on failures that
// carry one. Clients branch on this, never on Message.
Code string `json:"code,omitempty"`
// Errors carries field-scoped detail, set only on failures that have it.
Errors []errs.Detail `json:"errors,omitempty"`
// Set only on list responses.
Page *int `json:"page,omitempty"`
PageSize *int `json:"pageSize,omitempty"`
Total *int64 `json:"total,omitempty"`
Pages *int `json:"pages,omitempty"`
}
Meta is the envelope's second half: everything about the response that is not the payload.
type Sanitizer ¶
Sanitizer inspects an outgoing message and returns what may be sent.
It is the hook for the one thing a response funnel is uniquely able to do: catch infrastructure detail on its way out. Handlers pass err.Error() into these responders by the hundred, and any one of those strings may have come from a database driver, an HTTP client or a message broker. Install a sanitizer and the check happens once, for all of them.
route is "METHOD /path"; scope is "http".
Source Files