go.bigb.es/auxilia

v0.4.0
Doc Versions Source

Documentation

Package httpproblem implements RFC 7807 "Problem Details for HTTP APIs" with a bridge to culpa errors.

The package provides a typed Problem struct, a FromError mapper that extracts culpa.CodeDetail and culpa.PublicDetail from the error chain, and a small set of sentinel constructors for common HTTP statuses.

The package is intentionally a subpackage of culpa rather than a top-level auxilia package so that culpa core remains free of the net/http import. Importers who need HTTP responses opt in by importing this package.

Constants

const ContentType = "application/problem+json"

ContentType is the media type for RFC 7807 problem documents.

Functions

f func BadRequest

src 
func BadRequest(detail string) error

BadRequest returns a BadRequestError with the given detail message.

f func Conflict

src 
func Conflict(detail string) error

Conflict returns a ConflictError with the given detail message.

f func Forbidden

src 
func Forbidden(detail string) error

Forbidden returns a ForbiddenError with the given detail message.

f func Internal

src 
func Internal(detail string) error

Internal returns an InternalError with the given detail message. The detail is for logs only; it does not appear in the HTTP response body.

f func NotFound

src 
func NotFound(resource string) error

NotFound returns a NotFoundError for the given resource name.

f func TooManyRequests

src 
func TooManyRequests(detail string) error

TooManyRequests returns a TooManyRequestsError with the given detail message.

f func Unauthorized

src 
func Unauthorized(detail string) error

Unauthorized returns an UnauthorizedError with the given detail message.

f func Unprocessable

src 
func Unprocessable(detail string) error

Unprocessable returns an UnprocessableError with the given detail message.

Types

T type BadRequestError

src 
type BadRequestError struct{ Detail string }

BadRequestError indicates malformed or invalid input from the caller.

m func (BadRequestError) Error

src 
func (e BadRequestError) Error() string

Error implements error.

T type ConflictError

src 
type ConflictError struct{ Detail string }

ConflictError indicates the request conflicts with current resource state.

m func (ConflictError) Error

src 
func (e ConflictError) Error() string

Error implements error.

T type ForbiddenError

src 
type ForbiddenError struct{ Detail string }

ForbiddenError indicates the request is authenticated but not allowed.

m func (ForbiddenError) Error

src 
func (e ForbiddenError) Error() string

Error implements error.

T type InternalError

src 
type InternalError struct{ Detail string }

InternalError indicates an unrecoverable server-side failure. The Detail field is for internal logging only — it never appears in the HTTP response body unless an explicit culpa.PublicDetail is attached.

m func (InternalError) Error

src 
func (e InternalError) Error() string

Error implements error.

T type NotFoundError

src 
type NotFoundError struct{ Resource string }

NotFoundError indicates the requested resource does not exist.

m func (NotFoundError) Error

src 
func (e NotFoundError) Error() string

Error implements error.

T type Problem

src 
type Problem struct {
	// Type is a URI identifying the problem. Defaults to "about:blank".
	Type string `json:"type"`
	// Title is a short human-readable summary.
	Title string `json:"title"`
	// Status is the HTTP status code.
	Status int `json:"status"`
	// Detail is a user-safe explanation. Empty for opaque internal errors.
	Detail string `json:"detail,omitempty"`
	// Code is a machine-readable slug.
	Code string `json:"code,omitempty"`
}

Problem is RFC 7807 Problem Details for HTTP APIs.

A Problem is itself an error so that handlers can return it through the usual error chain and rely on FromError to pass it through unchanged.

f func FromError

src 
func FromError(err error) Problem

FromError maps any error onto a Problem.

Resolution order:

  1. If the error chain contains a Problem, that value is used as the base (so callers can return one directly even when wrapped).
  2. If the chain contains one of the typed sentinel errors (NotFoundError, BadRequestError, ...), the matching status and code are used.
  3. Anything else collapses to a Status 500 problem with Title "Internal Server Error" and empty Detail/Code so internal error messages do not leak into responses.

After picking a base, FromError applies culpa overrides discovered in the chain:

The override pass also runs for the default 500 case but only sets fields that are still zero, so a culpa.PublicDetail message can opt in to surfacing a user-safe string while the inner error text still does not leak.

FromError(nil) returns the zero Problem (Status 0). Callers should not invoke it on a nil error.

m func (Problem) Error

src 
func (p Problem) Error() string

Error implements the error interface.

m func (Problem) Write

src 
func (p Problem) Write(w http.ResponseWriter)

Write serializes the Problem as JSON, sets the Content-Type to application/problem+json, and writes the status code.

If Type is empty, it is replaced with "about:blank" in the response body without mutating the receiver.

Encoding errors are silently dropped: by the time encoding fails the response has already been partially written and there is nothing useful to do.

T type TooManyRequestsError

src 
type TooManyRequestsError struct{ Detail string }

TooManyRequestsError indicates the caller has hit a rate limit.

m func (TooManyRequestsError) Error

src 
func (e TooManyRequestsError) Error() string

Error implements error.

T type UnauthorizedError

src 
type UnauthorizedError struct{ Detail string }

UnauthorizedError indicates the request lacks valid authentication.

m func (UnauthorizedError) Error

src 
func (e UnauthorizedError) Error() string

Error implements error.

T type UnprocessableError

src 
type UnprocessableError struct{ Detail string }

UnprocessableError indicates a syntactically valid request that cannot be processed (RFC 4918 §11.2).

m func (UnprocessableError) Error

src 
func (e UnprocessableError) Error() string

Error implements error.

Source Files