problem.go

// 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.

package httpproblem

import (

	"encoding/json"

	"errors"

	"net/http"

	"go.bigb.es/auxilia/culpa"

)

// ContentType is the media type for RFC 7807 problem documents.

const ContentType = "application/problem+json"

// defaultType is the placeholder URI per RFC 7807 §4.2 when no Type is set.

const defaultType = "about:blank"

// 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.

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"`

}

// Error implements the error interface.

func (p Problem) Error() string {

	if p.Detail != "" {

		return p.Title + ": " + p.Detail

	}

	return p.Title

}

// 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.

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

	out := p

	if out.Type == "" {

		out.Type = defaultType

	}

	w.Header().Set("Content-Type", ContentType)

	w.WriteHeader(out.Status)

	_ = json.NewEncoder(w).Encode(out)

}

// 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:

//

//   - [culpa.CodeDetail] (when Code is a non-empty string) overrides Code.

//   - [culpa.PublicDetail] (when Message is non-empty) overrides Detail.

//

// 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.

func FromError(err error) Problem {

	if err == nil {

		return Problem{}

	}

	var p Problem

	matched := false

	// 1. Pre-existing Problem in the chain.

	var existing Problem

	if errors.As(err, &existing) {

		p = existing

		matched = true

	}

	// 2. Typed sentinels.

	if !matched {

		matched = matchSentinel(err, &p)

	}

	// 3. Default to opaque 500.

	if !matched {

		p = Problem{

			Status: http.StatusInternalServerError,

			Title:  "Internal Server Error",

		}

	}

	// Overrides from culpa details. The override pass never widens what is

	// already set on a sentinel-derived problem (Code/Detail can be

	// replaced) but for the opaque 500 case Detail starts empty so only an

	// explicit PublicDetail can populate it.

	for _, code := range culpa.FindDetails[culpa.CodeDetail](err) {

		s, ok := code.Code.(string)

		if !ok || s == "" {

			continue

		}

		p.Code = s

		break

	}

	for _, pub := range culpa.FindDetails[culpa.PublicDetail](err) {

		if pub.Message == "" {

			continue

		}

		p.Detail = pub.Message

		break

	}

	return p

}

// matchSentinel checks the chain for one of the typed sentinel errors and,

// if found, populates p with the corresponding status/title/code.

func matchSentinel(err error, p *Problem) bool {

	var (

		nf  NotFoundError

		br  BadRequestError

		cf  ConflictError

		un  UnauthorizedError

		fb  ForbiddenError

		up  UnprocessableError

		tmr TooManyRequestsError

		in  InternalError

	)

	switch {

	case errors.As(err, &nf):

		*p = Problem{Status: http.StatusNotFound, Title: "Not Found", Code: "NOT_FOUND", Detail: nf.detail()}

	case errors.As(err, &br):

		*p = Problem{Status: http.StatusBadRequest, Title: "Bad Request", Code: "BAD_REQUEST", Detail: br.Detail}

	case errors.As(err, &cf):

		*p = Problem{Status: http.StatusConflict, Title: "Conflict", Code: "CONFLICT", Detail: cf.Detail}

	case errors.As(err, &un):

		*p = Problem{Status: http.StatusUnauthorized, Title: "Unauthorized", Code: "UNAUTHORIZED", Detail: un.Detail}

	case errors.As(err, &fb):

		*p = Problem{Status: http.StatusForbidden, Title: "Forbidden", Code: "FORBIDDEN", Detail: fb.Detail}

	case errors.As(err, &up):

		*p = Problem{Status: http.StatusUnprocessableEntity, Title: "Unprocessable Entity", Code: "UNPROCESSABLE", Detail: up.Detail}

	case errors.As(err, &tmr):

		*p = Problem{Status: http.StatusTooManyRequests, Title: "Too Many Requests", Code: "TOO_MANY_REQUESTS", Detail: tmr.Detail}

	case errors.As(err, &in):

		// InternalError carries a detail string but FromError still

		// blanks it out: 500 responses must not leak internals unless

		// an explicit PublicDetail is attached. We keep the code so the

		// caller can switch on it.

		*p = Problem{Status: http.StatusInternalServerError, Title: "Internal Server Error", Code: "INTERNAL"}

	default:

		return false

	}

	return true

}