svcerr

README

svcerr

Typed application errors for Go services: error codes, HTTP status mapping, JSON/HTML response writers, panic-recovery middleware, and stack trace capture. The core package imports no logging library — see "Logging" below.

import "github.com/n-ae/svcerr"

Why

Handlers need to turn an error into the right HTTP status, a safe user-facing message, and a structured log line, without leaking internals (raw SQL, stack traces, third-party error text) into the response. svcerr does that mapping once, centrally, instead of every handler improvising it.

Usage

func (s *Service) GetLeague(id string) (*League, error) {
	var league League
	err := s.db.QueryRow(`SELECT * FROM leagues WHERE id = ?`, id).Scan(&league)
	if err == sql.ErrNoRows {
		return nil, svcerr.NewNotFoundError("league", id)
	}
	if err != nil {
		return nil, svcerr.WrapDatabaseError(err, "query", "SELECT * FROM leagues...")
	}
	return &league, nil
}

func (h *Handler) GetLeague(w http.ResponseWriter, r *http.Request) {
	league, err := h.service.GetLeague(r.URL.Query().Get("id"))
	if err != nil {
		// h.logger implements svcerr.Logger - see "Logging" below
		svcerr.WriteHTTPError(w, err, h.logger) // maps to the right status, logs, writes JSON
		return
	}
	json.NewEncoder(w).Encode(league)
}

WriteHTTPError writes a JSON body:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "league not found: 12345",
    "details": { "resource_type": "league", "resource_id": "12345" }
  }
}

WriteHTTPErrorHTML writes an HTML fragment instead, for HTMX-style endpoints. WriteHTTPProblem writes an RFC 9457 application/problem+json body instead, for clients that expect the standard problem-details shape:

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "league not found: 12345",
  "code": "NOT_FOUND",
  "resource_type": "league",
  "resource_id": "12345"
}

title is the HTTP status's standard reason phrase, per RFC 9457 §4.2.1 (since type is "about:blank" here); detail is specific to this occurrence (and follows the same public/internal message rules as WriteHTTPError - see "Public vs. internal messages" below). Extension members (code, resource_type, resource_id, ...) sit at the top level, per RFC 9457, rather than nested under a sub-object; see "Public details" below for adding to or suppressing them.

SetProblemType/SetProblemInstance/SetProblemTitle override type/instance/title on a specific error instance, for an application with its own stable problem-type URIs instead of about:blank:

err := svcerr.NewNotFoundError("league", id)
err.SetProblemType("https://example.com/problems/resource-not-found")
err.SetProblemInstance(requestURL) // omitted entirely when unset
err.SetProblemTitle("League not found")

title stays the HTTP status's reason phrase absent SetProblemTitle - correct alongside the default about:blank type (per RFC 9457 §4.2.1), but RFC 9457 expects a custom type to define its own, occurrence-invariant title rather than reusing the HTTP status's in general.

UserMessage(err) returns just the sanitized message, for callers embedding it in a custom response.

Check error types with stdlib errors.As — there's no per-type IsXError wrapper. svcerr is a distinct package name (not errors), so both imports coexist without an alias:

import (
	"errors"

	"github.com/n-ae/svcerr"
)

var nfErr *svcerr.NotFoundError
if errors.As(err, &nfErr) {
	log.Printf("missing %s: %s", nfErr.ResourceType(), nfErr.ResourceID())
}

Identity is read through same-name methods (nfErr.ResourceType(), vErr.Field(), rlErr.RetryAfter(), ...) and is fixed at construction - every projection of an error (response details, headers, log fields, Context()) derives from that one canonical state, so they can never disagree. Fixation is by reference, not deep copy: a mutable object passed to a constructor (e.g. a validation error's value) stays shared, so mutating it afterward is visible through Value() and Context() - pass a snapshot if the original will change (this never affects wire output or logs; validation values are excluded from both). Presentation (public message, details, problem members, authentication challenges) is configured through the Set* methods before the error is returned.

Recover panics in HTTP handlers and turn them into a proper error response:

router.Use(svcerr.RecoveryMiddleware(h.logger))

RecoveryMiddleware tracks whether the handler already wrote a response before panicking, and won't write an error body over one that's already committed - it logs, then re-panics with http.ErrAbortHandler, which closes the HTTP/1 connection (or resets the HTTP/2 stream) instead of letting net/http treat whatever partial bytes the handler wrote as a complete, successful response. An outer panic-recovery layer, if any, must not swallow http.ErrAbortHandler - RecoveryMiddleware should normally be the outermost one. It also passes through http.Flusher and http.Hijacker when (and only when) the underlying ResponseWriter supports them, so SSE handlers and WebSocket upgrades still work for handlers wrapped by the middleware, and a handler's own w.(http.Flusher)/w.(http.Hijacker) checks (or an http.ResponseController) get a truthful answer instead of the wrapper always claiming both regardless of what's underneath. A successful hijack is itself treated as committing the response.

After a successful Hijack, the connection is yours - per net/http, the server no longer manages it, and neither does this middleware: recovery will not write to it (correct) and will not close it either, because handlers legitimately hand the connection to another goroutine and a close from panic recovery would race that transfer. Take ownership immediately, before any code that might panic:

conn, rw, err := w.(http.Hijacker).Hijack()
if err != nil {
	return
}
defer conn.Close()
// only now do work that might panic

A panic after a hijack is still logged (with hijacked=true in the log fields - no HTTP status applies to a hijacked response) and re-panics with http.ErrAbortHandler, but a connection the handler never arranged to close stays open.

Flushing, hijacking, and the error-reporting FlushError() error form (which http.ResponseController prefers) are the only optional interfaces the wrapper preserves - http.Pusher and io.ReaderFrom in particular are dropped, so HTTP/2 server push and sendfile-style copy optimizations aren't available to handlers behind the middleware. One deliberate asymmetry: an underlying writer implementing only FlushError() error (not plain Flush()) gains a Flush() method through the wrapper, since the flush capability genuinely exists and http.Flusher is how handlers conventionally probe for it.

Transparent, eagerly-header-setting compression wrappers need a HeaderPolicy. By default every writer in this package (WriteJSON, WriteHTML, WriteProblem, WriteHTTPError/WriteHTTPErrorHTML/WriteHTTPProblem, and RecoveryMiddleware) deletes any pre-existing Content-Encoding on the ResponseWriter before writing its own always-plaintext body - this is what stops a panic replaced mid-gzip-response from leaving a stale Content-Encoding: gzip on a body that's actually plain JSON. The tradeoff: if the ResponseWriter you pass in belongs to a compression middleware that sets Content-Encoding once up front and then transparently gzips everything written through it (a common pattern), that header gets deleted while the body is compressed anyway, and the client receives gzip bytes labeled as plain text. There's no way for this package to tell a stale header (left over from whatever the handler intended before erroring out) apart from a live one a wrapper is about to honor - but you know your middleware topology, so declare it once, at startup:

svcerr.SetHeaderPolicy(svcerr.HeaderPolicy{KeepContentEncoding: true})

That covers the normal error path - error bodies a handler writes into the compression-wrapped ResponseWriter it was given. It deliberately does not cover RecoveryMiddleware's panic replacement, which is written to the writer recovery itself wraps, underneath any compression middleware sitting between recovery and the handler - there the same header really is stale even though it's live for the normal path. SetRecoveryHeaderPolicy configures that path separately, for topologies (e.g. compression outside recovery) where the replacement body does go through the compressor. Without any policy, the previous guidance still holds: put this kind of compression middleware inside (called before) any of this package's writers, not outside/wrapping them.

ETag, Last-Modified, and Accept-Ranges are left alone by default, unlike Content-Length/Content-Encoding/Trailer/Retry-After/ WWW-Authenticate, which every writer clears. Those three describe a specific successful representation - if a handler set one in anticipation of the response it never got to send (an ETag for content that won't match the error body, say), it can still be present on the error response that replaces it. This is deliberate: unlike a wrong Content-Length or Content-Encoding, a stale conditional-request header doesn't actively mislead a client about the body it's receiving, and a plain WriteJSON call may legitimately want to preserve headers a handler set for reasons unrelated to the error. It's most likely to matter for RecoveryMiddleware specifically, where the response is replacing an abandoned success path rather than being the request's only response. A deployment that would rather no abandoned-representation metadata ever ride along on an error response can opt into clearing them:

svcerr.SetHeaderPolicy(svcerr.HeaderPolicy{ClearValidators: true})
svcerr.SetRecoveryHeaderPolicy(svcerr.HeaderPolicy{ClearValidators: true})

Error types

ValidationError, DatabaseError, ExternalAPIError, AuthenticationError, NotFoundError, ConflictError, RateLimitError, InternalError — each has a New*/Wrap* constructor, carries an ErrorCode, and supports stdlib errors.Is/errors.As/errors.Unwrap in the usual way. See the ErrorCode constants in errors.go for the full list of codes and HTTPStatusCode in status.go for their HTTP status mapping.

For a code with no dedicated constructor (e.g. ErrCodeDatabaseConnection, ErrCodeMissingRequired, ErrCodeResourceConflict, ErrCodeQuotaExceeded), use the generic New/Wrap:

err := svcerr.New(svcerr.ErrCodeDatabaseConnection, "could not reach the database")
err := svcerr.Wrap(dbErr, svcerr.ErrCodeDatabaseConnection, "could not reach the database")

For an application-specific code entirely outside this package's built-in set, register its HTTP status once, at startup:

const ErrCodeOutOfStock svcerr.ErrorCode = "OUT_OF_STOCK"

func init() {
	if err := svcerr.RegisterStatusCode(ErrCodeOutOfStock, http.StatusConflict); err != nil {
		panic(err) // a bad registration at startup should fail loudly, not later inside an error handler
	}
}

RegisterStatusCode can also override a built-in code's mapping, for a deployment that wants different semantics than the default. It rejects any status outside 400-599, since this package only ever maps error codes to error responses.

Note that a custom code registers a status, not a message policy: it's not in the built-in safe-category list (see "Public vs. internal messages" below), so its response message falls back to the generic "An unexpected error occurred." rather than the message passed to New/Wrap. That's deliberate - this package can't know whether an unfamiliar code's messages are client-safe - so pair custom codes with SetPublicMessage:

err := svcerr.New(ErrCodeOutOfStock, "sku WIDGET-42 depleted, restock ETA unknown")
err.SetPublicMessage("This item is out of stock.")

Joined errors

Classification follows stdlib errors.As traversal order - pre-order, depth-first - so for a joined error (errors.Join, or any tree whose Unwrap returns []error) the first coded error wins:

svcerr.GetErrorCode(errors.Join(notFoundErr, internalErr)) // NOT_FOUND  -> 404
svcerr.GetErrorCode(errors.Join(internalErr, notFoundErr)) // INTERNAL_ERROR -> 500

Merely reversing the arguments changes the client's response. When aggregating errors of different severities - a client-facing error joined with an operational cleanup failure, say - don't rely on argument order; classify the aggregate explicitly:

return svcerr.Wrap(errors.Join(notFoundErr, cleanupErr),
	svcerr.ErrCodeInternal, "request processing failed")

Custom error types

You don't have to embed BaseError to plug into this package - implement just the capability you need:

type Coder interface {
	Code() ErrorCode // GetErrorCode, HTTPStatusCode
}

type StackTracer interface {
	StackTrace() []string // GetStackTrace
}

type PublicMessager interface {
	PublicMessage() (string, bool) // getUserFriendlyMessage / UserMessage overrides
}

type PublicDetailer interface {
	PublicDetails() (add map[string]any, remove map[string]struct{}) // extractErrorDetails overrides
}

type ProblemTyper interface {
	ProblemType() (string, bool) // WriteHTTPProblem's "type", instead of "about:blank"
}

type ProblemInstancer interface {
	ProblemInstance() (string, bool) // WriteHTTPProblem's "instance"
}

type ProblemTitler interface {
	ProblemTitle() (string, bool) // WriteHTTPProblem's "title", instead of http.StatusText(status)
}

type Authenticator interface {
	AuthenticateChallenge() (string, bool) // WWW-Authenticate on a 401 response
}

A minimal type implementing Coder (and error) is enough to get correct status-code mapping from WriteHTTPError/WriteHTTPProblem; add Unwrap() error if you also want the "don't leak a wrapped cause" safety property. ErrorWithCode is the full combination BaseError-derived types implement (plus StackTracer), kept as a single name for convenience - it's not a requirement for participating in the package's functions.

Public vs. internal messages

By default, whether the client-facing message is the error's own message depends on its category, not on whether it wraps a cause:

• Validation, not-found, conflict, auth, and rate-limit codes are client-input-shaped - the message you pass to NewValidationError, WrapValidationError, NewNotFoundError, etc. is always an explicit argument you chose, never text derived from a wrapped cause, so it's shown by default even when the error wraps one.
• Database, external-API, and internal codes fall back to a generic per-code message instead, whether or not they wrap a cause - Error() text in these categories often carries operational detail (a raw query, an internal hostname, third-party response text, a secret) that must never reach a client without an explicit opt-in.

SetPublicMessage overrides the client-facing text explicitly, for either category:

err := svcerr.WrapDatabaseError(dbErr, "query", "SELECT * FROM leagues...")
err.SetPublicMessage("We're having trouble reaching the database. Please try again shortly.")
return err // WriteHTTPError/UserMessage now send the override; logs still get err.Error()

Public details

Built-in types automatically contribute a few structured fields to the response's details map - NotFoundError's resource_type/resource_id, ValidationError's field, RateLimitError's limit/retry_after, and so on (never anything caller-supplied and unbounded, like ValidationError.Value - see the source for the exact list per type). SetPublicDetail/RemovePublicDetail let you add to or suppress that on a specific error instance, and are the only way to get structured details at all for a code built with the generic New/Wrap (which have no built-in type to extract from). Calling either again for the same key later - even after the other one - changes your mind: whichever call was most recent wins.

err := svcerr.New(svcerr.ErrCodeConstraintViolation, "out of stock")
err.SetPublicDetail("sku", sku)
err.SetPublicDetail("available", 0)

Six names are reserved in problem-details output. The JSON writers nest details under error.details, where any key is fine - but WriteHTTPProblem/WriteProblem flatten details to the top level of the RFC 9457 object, where type, title, status, detail, instance, and code are registered (or package-owned) members. A public detail with one of those names is silently omitted from problem-details output (it still appears in the plain-JSON shape), so the same error can render different details depending on the writer. Use SetProblemType, SetProblemTitle, and SetProblemInstance for the real members; status, detail, and code always come from the error's own classification.

RemovePublicDetail only touches the details map - not the message. NewNotFoundError(resourceType, resourceID)'s own message embeds resourceID directly ("user not found: secret@example.com"), and NOT_FOUND is a category mayExposeOwnMessage shows by default (see "Public vs. internal messages" above) - so RemovePublicDetail alone still leaves the identifier in message. If the identifier itself is sensitive, pair it with SetPublicMessage:

err := svcerr.NewNotFoundError("user", customerEmail)
err.RemovePublicDetail("resource_id")     // removes it from details...
err.SetPublicMessage("user was not found") // ...and this removes it from message

Authentication challenges

RFC 9110 §11.6.1 requires a server generating a 401 response to include at least one WWW-Authenticate challenge. This package has no way to know an application's authentication scheme or realm on its own, so it never invents one - configure an application-wide default once, at startup (like RegisterStatusCode):

func init() {
	svcerr.SetDefaultAuthenticateChallenge(`Bearer realm="api"`)
}

Every 401 from WriteHTTPError/WriteHTTPErrorHTML/WriteHTTPProblem (and the WriteJSON/WriteHTML/WriteProblem variants) now carries that challenge, without each authentication-error construction site having to remember an HTTP protocol rule. A specific error instance can still override it via SetAuthenticateChallenge, which always wins over the default:

err := svcerr.NewAuthenticationError("token_expired", "session expired")
err.SetAuthenticateChallenge(`Bearer realm="api", error="invalid_token", error_description="the access token expired"`)
svcerr.WriteHTTPError(w, err, logger) // sends the error-specific challenge

Both are only applied when the response status is 401 - set on an error whose code maps elsewhere and they're silently unused. Without either, a bare 401 (no WWW-Authenticate) is still possible; the package won't guess a scheme for you. SetDefaultAuthenticateChallenge("") clears the default.

Instance configuration: Renderer

Everything the package-level configuration controls - status-code mapping, the default WWW-Authenticate challenge, both header policies - plus the logger can be scoped to an instance instead of the globals:

r, err := svcerr.NewRenderer(svcerr.RendererConfig{
	StatusCodes:                  map[svcerr.ErrorCode]int{ErrCodeOutOfStock: http.StatusConflict},
	DefaultAuthenticateChallenge: `Bearer realm="api"`,
	HeaderPolicy:                 svcerr.HeaderPolicy{KeepContentEncoding: true},
	RecoveryHeaderPolicy:         svcerr.HeaderPolicy{},
	Logger:                       logger,
})
if err != nil {
	panic(err) // invalid config (e.g. a status outside 400-599) fails at startup
}

res := r.JSON(w, err)      // logs via the config Logger AND returns the WriteResult
r.HTML(w, err)             // the WriteHTML rendering
r.Problem(w, err)          // the RFC 9457 rendering
router.Use(r.Middleware()) // RecoveryMiddleware under this config

Because each method both logs and reports, a Renderer collapses the package-level WriteHTTPError/WriteJSON/WriteJSONResult split into one call. Use it for tests, for processes hosting two differently configured services, or simply to avoid global state - the zero RendererConfig reproduces the package defaults with no logging.

A Renderer is fully self-contained. The global configuration (RegisterStatusCode, SetDefaultAuthenticateChallenge, SetHeaderPolicy, SetRecoveryHeaderPolicy) does not affect it, and its own configuration never leaks to the package-level writers. If a library registers codes globally that this renderer should know, mirror them into RendererConfig.StatusCodes. The config is copied at construction and immutable from then on.

Wrapping constructors in your own helper

Every New*/Wrap* constructor assumes it's called directly from the site its stack trace should point at. If you wrap one in your own helper (e.g. a project-wide validation function), the trace ends up pointing at the helper instead of its caller. Fix that with RecaptureStackTrace, called from inside the helper right after construction:

func validateTeamID(id string) error {
	if id == "" {
		err := svcerr.NewValidationError("team_id is required", "team_id", nil)
		svcerr.RecaptureStackTrace(err, 1) // point past this helper
		return err
	}
	return nil
}

Concurrency

Errors aren't safe for concurrent mutation. SetPublicMessage, SetPublicDetail, RemovePublicDetail, SetProblemType, SetProblemInstance, SetProblemTitle, SetAuthenticateChallenge, and RecaptureStackTrace all mutate the receiver in place with no locking. That's fine for the normal pattern - construct an error, configure it, return it - but don't call these once an error might be read or mutated from another goroutine.

Logging

WriteHTTPError, WriteHTTPErrorHTML, WriteHTTPProblem, and RecoveryMiddleware log through a minimal Logger interface, not a specific logging library:

type Logger interface {
	Log(level Level, err error, fields map[string]any, msg string)
}

Using zerolog? Wrap it with the zerologadapter subpackage instead of writing your own adapter:

import "github.com/n-ae/svcerr/zerologadapter"

svcerr.WriteHTTPError(w, err, zerologadapter.New(logger))

zerologadapter is a separate Go module (its own go.mod, nested in this repo at zerologadapter/) - it's the one depending on zerolog, not the core svcerr module. go get github.com/n-ae/svcerr never pulls in zerolog; only go get github.com/n-ae/svcerr/zerologadapter does, and only for callers who use it.

Adapter versioning: the adapter is tagged independently (zerologadapter/vX.Y.Z) and only when the adapter itself changes - not on every root release, so its latest tag lagging the root's is expected, not an oversight. Compatibility is carried by the Logger interface, not by version lockstep: the adapter's go.mod requires whatever root version was current at its last change, and Go's module resolution picks the higher of that and your own requirement, so an older adapter tag works fine with newer root releases. The adapter's minimum Go version is also dictated by zerolog's dependency chain rather than by this repo, so it can sit higher than the root module's own floor.

For any other logger, implement the one-method Logger interface directly. A nil Logger is also fine - WriteHTTPError/WriteHTTPErrorHTML/ WriteHTTPProblem/RecoveryMiddleware simply skip logging rather than panicking, so you don't have to plumb through a no-op implementation just to render a response without logging it.

If you want response rendering with no Logger involvement at all - e.g. you're reporting errors through something other than this package's Logger contract - use WriteJSON, WriteHTML, or WriteProblem directly. Each writes the same body as its WriteHTTP* counterpart and returns the status code used, without touching a logger:

statusCode := svcerr.WriteJSON(w, err) // no logging, no Logger argument
myReporter.Report(r.Context(), err, statusCode)

That discards whether the body actually rendered and reached the client. Use WriteJSONResult (or WriteHTMLResult/WriteProblemResult) instead to see that too, so your reporter doesn't claim success when the client never got a valid response:

result := svcerr.WriteJSONResult(w, err)
myReporter.Report(r.Context(), err, result.Status, result.RenderErr, result.WriteErr)

Origin

Extracted from an application's internal/errors package once it had no callers left depending on app-specific behavior — see the release notes for what changed along the way. Note: zerologadapter/v0.4.0 shipped with a go.mod that made it unfetchable outside this repo; use zerologadapter/v0.4.1 or later instead (the root svcerr module's own v0.4.0 tag is unaffected).

Documentation

Overview

Package svcerr provides custom error types for consistent error handling.

Error types: ValidationError, DatabaseError, ExternalAPIError, AuthenticationError, NotFoundError, ConflictError, RateLimitError, InternalError.

All types implement ErrorWithCode interface and support error wrapping. A custom error type doesn't need to embed BaseError to participate - implementing just Coder, StackTracer, or PublicMessager independently is enough for the corresponding functions (GetErrorCode/HTTPStatusCode, GetStackTrace, and the public-message overrides) to recognize it.

This package's own code imports no logging library: WriteHTTPError, WriteHTTPErrorHTML, and RecoveryMiddleware log through the Logger interface instead - pass an adapter for whatever logger the caller uses. (The zerologadapter subpackage, which does depend on zerolog, is a separate Go module nested in this repo; only importing it pulls zerolog into a caller's build, not this package - this module has zero dependencies of its own.)

Classification of a joined error (errors.Join, or any tree whose Unwrap returns []error) follows stdlib errors.As traversal order: pre-order, depth-first, so the first coded error wins - for errors.Join, the earliest coded argument. Join(notFoundErr, internalErr) therefore classifies as NOT_FOUND/404 while Join(internalErr, notFoundErr) classifies as INTERNAL_ERROR/500. When aggregating errors of different severities (e.g. a client-facing error with an operational cleanup failure), don't rely on argument order - classify the aggregate explicitly:

return svcerr.Wrap(errors.Join(notFoundErr, cleanupErr),
	svcerr.ErrCodeInternal, "request processing failed")

The semantic types' identity - a validation error's field, a not-found error's resource ID, a rate limit's retry delay - is fixed at construction and read through same-name accessor methods (ValidationError.Field(), NotFoundError.ResourceID(), RateLimitError.RetryAfter(), ...). Every projection of an error - response details, headers, log fields, Context() - derives from that one canonical state, so they can never disagree. The one identity-adjacent value legitimately learned after construction - an upstream retry hint - has a dedicated clamping setter, ExternalAPIError.SetRetryAfter. (Before v1 these were exported writable fields; the migration is mechanical - x.Field becomes x.Field(). See docs/v1-design-pass.md.)

Identity fixation is by reference, not deep copy: a mutable object a constructor is given (e.g. the map or slice passed as NewValidationError's value) stays shared, so mutating it afterward is visible through Value() and Context() - pass a snapshot if the original will change. This never affects wire output or logs (validation values are deliberately excluded from both); it is the same shallow-ownership rule PublicDetails documents for detail values.

Errors are not safe for concurrent mutation. SetPublicMessage, SetPublicDetail, RemovePublicDetail, SetProblemType, SetProblemInstance, SetProblemTitle, SetAuthenticateChallenge, SetRetryAfter, and RecaptureStackTrace all mutate the receiver in place with no locking. This is fine for the normal pattern of constructing and configuring an error locally before returning it, but don't call these once an error might be read or mutated from another goroutine (e.g. after handing it to a shared error-collection type). Identity accessors (Field(), ResourceID(), ...) are safe to call concurrently once construction and configuration are done.

Index

• func GetStackTrace(err error) []string
• func HTTPStatusCode(code ErrorCode) int
• func RecaptureStackTrace(err error, extraSkip int)
• func RecoveryMiddleware(logger Logger) func(http.Handler) http.Handler
• func RegisterStatusCode(code ErrorCode, status int) error
• func SetDefaultAuthenticateChallenge(challenge string)
• func SetHeaderPolicy(p HeaderPolicy)
• func SetRecoveryHeaderPolicy(p HeaderPolicy)
• func UserMessage(err error) string
• func WriteHTML(w http.ResponseWriter, err error) int
• func WriteHTTPError(w http.ResponseWriter, err error, logger Logger)
• func WriteHTTPErrorHTML(w http.ResponseWriter, err error, logger Logger)
• func WriteHTTPProblem(w http.ResponseWriter, err error, logger Logger)
• func WriteJSON(w http.ResponseWriter, err error) int
• func WriteProblem(w http.ResponseWriter, err error) int
• type AuthenticationError
  • func NewAuthenticationError(reason, message string) *AuthenticationError
  • func WrapAuthenticationError(err error, reason, message string) *AuthenticationError
  • func (e *AuthenticationError) Context() map[string]any
  • func (e *AuthenticationError) Reason() string
• type Authenticator
• type BaseError
  • func New(code ErrorCode, message string) *BaseError
  • func Wrap(err error, code ErrorCode, message string) *BaseError
  • func (e *BaseError) AuthenticateChallenge() (string, bool)
  • func (e *BaseError) Code() ErrorCode
  • func (e *BaseError) Context() map[string]any
  • func (e *BaseError) Error() string
  • func (e *BaseError) ProblemInstance() (string, bool)
  • func (e *BaseError) ProblemTitle() (string, bool)
  • func (e *BaseError) ProblemType() (string, bool)
  • func (e *BaseError) PublicDetails() (add map[string]any, remove map[string]struct{})
  • func (e *BaseError) PublicMessage() (string, bool)
  • func (e *BaseError) RemovePublicDetail(key string)
  • func (e *BaseError) SetAuthenticateChallenge(challenge string)
  • func (e *BaseError) SetProblemInstance(uri string)
  • func (e *BaseError) SetProblemTitle(title string)
  • func (e *BaseError) SetProblemType(uri string)
  • func (e *BaseError) SetPublicDetail(key string, value any)
  • func (e *BaseError) SetPublicMessage(msg string)
  • func (e *BaseError) StackTrace() []string
  • func (e *BaseError) Unwrap() error
• type Coder
• type ConflictError
  • func NewConflictError(resourceType, conflictKey, message string) *ConflictError
  • func WrapConflictError(err error, resourceType, conflictKey, message string) *ConflictError
  • func (e *ConflictError) ConflictKey() string
  • func (e *ConflictError) Context() map[string]any
  • func (e *ConflictError) ResourceType() string
• type DatabaseError
  • func NewDatabaseError(operation, message string) *DatabaseError
  • func WrapDatabaseError(err error, operation, query string) *DatabaseError
  • func (e *DatabaseError) Context() map[string]any
  • func (e *DatabaseError) Operation() string
  • func (e *DatabaseError) Query() string
• type ErrorCode
  • func GetErrorCode(err error) ErrorCode
• type ErrorDetail
• type ErrorWithCode
• type ExternalAPIError
  • func NewExternalAPIError(service, message string, statusCode int, url string) *ExternalAPIError
  • func WrapExternalAPIError(err error, service, url string, statusCode int) *ExternalAPIError
  • func (e *ExternalAPIError) Context() map[string]any
  • func (e *ExternalAPIError) RetryAfter() (seconds int, ok bool)
  • func (e *ExternalAPIError) Service() string
  • func (e *ExternalAPIError) SetRetryAfter(seconds int)
  • func (e *ExternalAPIError) StatusCode() int
  • func (e *ExternalAPIError) URL() string
• type HTTPErrorResponse
• type HeaderPolicy
• type InternalError
  • func NewInternalError(component, message string) *InternalError
  • func WrapInternalError(err error, component, message string) *InternalError
  • func (e *InternalError) Component() string
  • func (e *InternalError) Context() map[string]any
• type Level
• type Logger
• type NotFoundError
  • func NewNotFoundError(resourceType, resourceID string) *NotFoundError
  • func WrapNotFoundError(err error, resourceType, resourceID string) *NotFoundError
  • func (e *NotFoundError) Context() map[string]any
  • func (e *NotFoundError) ResourceID() string
  • func (e *NotFoundError) ResourceType() string
• type ProblemDetails
  • func (p ProblemDetails) MarshalJSON() ([]byte, error)
• type ProblemInstancer
• type ProblemTitler
• type ProblemTyper
• type PublicDetailer
• type PublicMessager
• type RateLimitError
  • func NewRateLimitError(service string, limit, retryAfter int) *RateLimitError
  • func WrapRateLimitError(err error, service string, limit, retryAfter int) *RateLimitError
  • func (e *RateLimitError) Context() map[string]any
  • func (e *RateLimitError) Limit() int
  • func (e *RateLimitError) RetryAfter() int
  • func (e *RateLimitError) Service() string
• type Renderer
  • func NewRenderer(cfg RendererConfig) (*Renderer, error)
  • func (r *Renderer) HTML(w http.ResponseWriter, err error) WriteResult
  • func (r *Renderer) JSON(w http.ResponseWriter, err error) WriteResult
  • func (r *Renderer) Middleware() func(http.Handler) http.Handler
  • func (r *Renderer) Problem(w http.ResponseWriter, err error) WriteResult
• type RendererConfig
• type StackTracer
• type ValidationError
  • func NewValidationError(message string, field string, value any) *ValidationError
  • func WrapValidationError(err error, message string, field string) *ValidationError
  • func (e *ValidationError) Context() map[string]any
  • func (e *ValidationError) Field() string
  • func (e *ValidationError) Value() any
• type WriteResult
  • func WriteHTMLResult(w http.ResponseWriter, err error) WriteResult
  • func WriteJSONResult(w http.ResponseWriter, err error) WriteResult
  • func WriteProblemResult(w http.ResponseWriter, err error) WriteResult

Examples

• BaseError.SetPublicMessage
• NewNotFoundError
• NewRenderer
• RecoveryMiddleware
• RegisterStatusCode
• SetDefaultAuthenticateChallenge
• SetHeaderPolicy
• UserMessage
• Wrap
• WriteHTML
• WriteJSON
• WriteProblem

Functions

func GetStackTrace

func GetStackTrace(err error) []string

GetStackTrace extracts the stack trace from an error. It only requires StackTracer, not the full ErrorWithCode. A typed-nil StackTracer (see isNilValue) is treated the same as no match at all, matching outermostCoded/GetErrorCode's handling of the same footgun - without this guard, a *BaseError-derived nil pointer assigned to a plain error variable would panic here instead of degrading gracefully.

func HTTPStatusCode

func HTTPStatusCode(code ErrorCode) int

HTTPStatusCode maps error codes to HTTP status codes: the RegisterStatusCode registry first, then the built-in mapping. This is the mapping the package-level writers use; a Renderer consults its own StatusCodes instead of the registry (see RendererConfig).

func RecaptureStackTrace

func RecaptureStackTrace(err error, extraSkip int)

RecaptureStackTrace re-captures err's stack trace starting extraSkip frames higher than the normal New*/Wrap* capture point. Every constructor in this package assumes it's called directly from the site the trace should point at; if you wrap a constructor in your own helper function, the trace ends up pointing at that helper instead of its caller. Call RecaptureStackTrace(err, 1) from inside such a helper, immediately after constructing err, to fix that - err must be one of this package's error types (or wrap one); otherwise this is a no-op. A typed-nil err (see isNilValue) is also a no-op rather than a panic, matching outermostCoded's treatment of the same case.

func RecoveryMiddleware

func RecoveryMiddleware(logger Logger) func(http.Handler) http.Handler

Middleware for error recovery and logging, using the package-level configuration (global status registry, challenge default, and recovery header policy, read at response time). A Renderer's Middleware method provides the same behavior under that renderer's own immutable configuration and logger.

Example

RecoveryMiddleware turns a handler panic into a proper 500 JSON response (when nothing was committed yet) and one structured log record; a nil logger disables logging without changing the response.

package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"

	"github.com/n-ae/svcerr"
)

func main() {
	handler := svcerr.RecoveryMiddleware(nil)(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {
		panic("something broke")
	}))

	rec := httptest.NewRecorder()
	handler.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/leagues", nil))

	fmt.Println(rec.Code)
	fmt.Println(rec.Body.String())
}

Output:
500
{"error":{"code":"INTERNAL_ERROR","message":"An internal error occurred. Please contact support if the problem persists."}}

func RegisterStatusCode

func RegisterStatusCode(code ErrorCode, status int) error

RegisterStatusCode adds or overrides the HTTP status HTTPStatusCode returns for code. Use it to extend the built-in mapping with an application's own ErrorCode values (constructed via New/Wrap), or to override a built-in mapping for a deployment that wants different semantics. Safe for concurrent use.

status must be a valid error status (400-599, since this package only ever maps error codes to error responses) - an out-of-range value (0, 200, 999, ...) is rejected here rather than surfacing later as a WriteHeader panic from inside an error handler, which is a far harder place to diagnose it. code must be non-empty: New/Wrap already normalize an empty code to ErrCodeInternal, so a registration entry keyed on "" could never be reached by this package's own errors and would only ever be reachable by a caller-supplied Coder that skips New/Wrap's normalization, silently shadowing ErrCodeInternal's own mapping instead of a real code's.

Example

An application-specific code outside the built-in set registers its HTTP status once, at startup. Custom codes aren't in the built-in safe-message categories, so pair them with SetPublicMessage.

package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"

	"github.com/n-ae/svcerr"
)

func main() {
	const errCodeOutOfStock svcerr.ErrorCode = "OUT_OF_STOCK"
	if err := svcerr.RegisterStatusCode(errCodeOutOfStock, http.StatusConflict); err != nil {
		panic(err) // a bad registration should fail loudly at startup
	}

	err := svcerr.New(errCodeOutOfStock, "sku WIDGET-42 depleted, restock ETA unknown")
	err.SetPublicMessage("This item is out of stock.")

	rec := httptest.NewRecorder()
	status := svcerr.WriteJSON(rec, err)

	fmt.Println(status)
	fmt.Println(rec.Body.String())
}

Output:
409
{"error":{"code":"OUT_OF_STOCK","message":"This item is out of stock."}}

func SetDefaultAuthenticateChallenge

func SetDefaultAuthenticateChallenge(challenge string)

SetDefaultAuthenticateChallenge sets an application-wide WWW-Authenticate challenge (e.g. `Bearer realm="api"`) that every 401 response from this package's writers carries when the error itself doesn't provide one via SetAuthenticateChallenge - an error-specific challenge always wins over this default. RFC 9110 §11.6.1 requires at least one WWW-Authenticate challenge on every server-generated 401 response; this package can't invent an application's authentication scheme or realm on its own, so without this call (or per-error challenges) a bare 401 remains possible. Set it once at startup, like RegisterStatusCode; the empty string clears it. Safe for concurrent use.

Example

An application-wide default WWW-Authenticate challenge, configured once at startup, covers every 401 whose error doesn't carry its own via SetAuthenticateChallenge - RFC 9110 §11.6.1 requires a challenge on every server-generated 401, and this saves each authentication-error construction site from having to remember that. (The deferred clear here is only to isolate this example from the rest of the test binary; real applications set it once and leave it.)

package main

import (
	"fmt"
	"net/http/httptest"

	"github.com/n-ae/svcerr"
)

func main() {
	svcerr.SetDefaultAuthenticateChallenge(`Bearer realm="api"`)
	defer svcerr.SetDefaultAuthenticateChallenge("")

	rec := httptest.NewRecorder()
	status := svcerr.WriteJSON(rec, svcerr.NewAuthenticationError("token_expired", "session expired"))

	fmt.Println(status)
	fmt.Println(rec.Header().Get("WWW-Authenticate"))
}

Output:
401
Bearer realm="api"

func SetHeaderPolicy

func SetHeaderPolicy(p HeaderPolicy)

SetHeaderPolicy sets the HeaderPolicy for the normal error path - WriteHTTPError/WriteHTTPErrorHTML/WriteHTTPProblem and the WriteJSON/ WriteHTML/WriteProblem variants. It does not affect RecoveryMiddleware's panic replacement; see SetRecoveryHeaderPolicy. Set it once at startup, like RegisterStatusCode; the zero value restores the default behavior. Safe for concurrent use.

Example

A deployment whose ResponseWriter is wrapped by a transparent compression middleware - one that sets Content-Encoding once and gzips everything written through it - declares that header live rather than stale, so error bodies written through the wrapper stay correctly labeled. RecoveryMiddleware's panic replacement has its own separate policy (SetRecoveryHeaderPolicy), since it writes underneath any such middleware. (The deferred reset only isolates this example; real applications set the policy once at startup.)

package main

import (
	"fmt"
	"net/http/httptest"

	"github.com/n-ae/svcerr"
)

func main() {
	svcerr.SetHeaderPolicy(svcerr.HeaderPolicy{KeepContentEncoding: true})
	defer svcerr.SetHeaderPolicy(svcerr.HeaderPolicy{})

	rec := httptest.NewRecorder()
	rec.Header().Set("Content-Encoding", "gzip") // set by the compression wrapper

	svcerr.WriteJSON(rec, svcerr.NewNotFoundError("league", "12345"))

	fmt.Println(rec.Header().Get("Content-Encoding"))
}

Output:
gzip

func SetRecoveryHeaderPolicy

func SetRecoveryHeaderPolicy(p HeaderPolicy)

SetRecoveryHeaderPolicy sets the HeaderPolicy for RecoveryMiddleware's panic-replacement response. Separate from SetHeaderPolicy because the two paths write to different points in the middleware stack: a normal error body goes through whatever wraps the handler's ResponseWriter (e.g. a compression middleware, whose Content-Encoding is then live), while a panic replacement is written to the writer recovery wraps directly, underneath any such middleware (the same header is then stale). Set it once at startup; the zero value restores the default behavior. Safe for concurrent use.

func UserMessage

func UserMessage(err error) string

UserMessage returns the safe, user-facing message for an error - the same sanitized text WriteHTTPError/WriteHTTPErrorHTML send (e.g. a wrapped database error's raw cause is never included), for callers that need to embed it in a custom response fragment instead of one of those two standard bodies.

Example

Operational categories never leak their own text to clients: UserMessage returns the sanitized message the response writers send, while Error() keeps the full detail for logs.

package main

import (
	"errors"
	"fmt"

	"github.com/n-ae/svcerr"
)

func main() {
	cause := errors.New("dial tcp 10.0.0.5:5432: connection refused")
	err := svcerr.WrapDatabaseError(cause, "query", "SELECT id FROM leagues")

	fmt.Println(svcerr.UserMessage(err))
	fmt.Println(err.Error())
}

Output:
Database error occurred. Please try again.
database query failed: dial tcp 10.0.0.5:5432: connection refused

func WriteHTML

func WriteHTML(w http.ResponseWriter, err error) int

WriteHTML mirrors WriteJSON for the HTML rendering WriteHTTPErrorHTML writes. Use WriteHTMLResult instead to also see a write failure this discards.

Example

The HTML fragment rendering for HTMX-style endpoints. Rate-limit errors carry Retry-After on every rendering, HTML included.

package main

import (
	"fmt"
	"net/http/httptest"

	"github.com/n-ae/svcerr"
)

func main() {
	err := svcerr.NewRateLimitError("api", 100, 30)

	rec := httptest.NewRecorder()
	status := svcerr.WriteHTML(rec, err)

	fmt.Println(status, rec.Header().Get("Retry-After"))
	fmt.Println(rec.Body.String())
}

Output:
429 30
<div class="error-message" role="alert"><h3>Error</h3><p>rate limit exceeded for api: 100 requests</p></div>

func WriteHTTPError

func WriteHTTPError(w http.ResponseWriter, err error, logger Logger)

WriteHTTPError writes a standardized error response to the HTTP response writer, logging through logger.

Prefer a Renderer, whose JSON method both logs (via the config Logger) and returns the WriteResult in one call - this function remains fully supported, but new code shouldn't need the split logging/result variants it exists for.

func WriteHTTPErrorHTML

func WriteHTTPErrorHTML(w http.ResponseWriter, err error, logger Logger)

WriteHTTPErrorHTML writes an HTML error response (for non-API endpoints), logging through logger.

Prefer a Renderer, whose HTML method both logs (via the config Logger) and returns the WriteResult in one call - this function remains fully supported, but new code shouldn't need the split logging/result variants it exists for.

func WriteHTTPProblem

func WriteHTTPProblem(w http.ResponseWriter, err error, logger Logger)

WriteHTTPProblem writes an RFC 9457 "application/problem+json" error response - an alternative body shape to WriteHTTPError's own {"error": {...}} for callers whose clients expect the standard problem-details format. Status mapping, message safety (Detail never includes a wrapped cause's text without an explicit SetPublicMessage), and logging behave identically to WriteHTTPError.

Prefer a Renderer, whose Problem method both logs (via the config Logger) and returns the WriteResult in one call - this function remains fully supported, but new code shouldn't need the split logging/result variants it exists for.

func WriteJSON

func WriteJSON(w http.ResponseWriter, err error) int

WriteJSON writes err's standardized JSON error response to w and returns the HTTP status code used - the same body WriteHTTPError writes, minus the logging call, for a caller that wants to own reporting separately (its own Reporter, a nil Logger via WriteHTTPError, or none at all) instead of participating in this package's Logger contract just to render a response. Use WriteJSONResult instead to also see a render/write failure this discards.

Example

The README's primary flow: a service returns a semantic error, the handler renders it. WriteJSON is the logger-free variant of WriteHTTPError with the identical body.

package main

import (
	"fmt"
	"net/http/httptest"

	"github.com/n-ae/svcerr"
)

func main() {
	err := svcerr.NewNotFoundError("league", "12345")

	rec := httptest.NewRecorder()
	status := svcerr.WriteJSON(rec, err)

	fmt.Println(status)
	fmt.Println(rec.Body.String())
}

Output:
404
{"error":{"code":"NOT_FOUND","message":"league not found: 12345","details":{"resource_id":"12345","resource_type":"league"}}}

func WriteProblem

func WriteProblem(w http.ResponseWriter, err error) int

WriteProblem mirrors WriteJSON for the RFC 9457 rendering WriteHTTPProblem writes. Use WriteProblemResult instead to also see a render/write failure this discards.

Example

The RFC 9457 problem-details rendering of the same error: registered members plus this package's extension members, flattened to the top level.

package main

import (
	"fmt"
	"net/http/httptest"

	"github.com/n-ae/svcerr"
)

func main() {
	err := svcerr.NewNotFoundError("league", "12345")

	rec := httptest.NewRecorder()
	svcerr.WriteProblem(rec, err)

	fmt.Println(rec.Header().Get("Content-Type"))
	fmt.Println(rec.Body.String())
}

Output:
application/problem+json
{"code":"NOT_FOUND","detail":"league not found: 12345","resource_id":"12345","resource_type":"league","status":404,"title":"Not Found","type":"about:blank"}

Types

type AuthenticationError

type AuthenticationError struct {
	BaseError
	// contains filtered or unexported fields
}

AuthenticationError represents authentication and authorization errors

func NewAuthenticationError

func NewAuthenticationError(reason, message string) *AuthenticationError

NewAuthenticationError creates a new authentication error

func WrapAuthenticationError

func WrapAuthenticationError(err error, reason, message string) *AuthenticationError

WrapAuthenticationError wraps an existing error as an authentication error. ErrCodeUnauthorized/ErrCodeTokenExpired/ErrCodeTokenInvalid/ ErrCodePermissionDenied are all in mayExposeOwnMessage's safe category, so message is shown to the client the same as NewAuthenticationError's - it's still an explicit caller argument, never derived from err.

func (*AuthenticationError) Context

func (e *AuthenticationError) Context() map[string]any

Context returns this error's identity as a fresh map - reason.

func (*AuthenticationError) Reason

func (e *AuthenticationError) Reason() string

Reason returns the authentication failure reason the constructor derived this error's code from - "token_expired", "token_invalid", "permission_denied", or any other caller-chosen string (which maps to ErrCodeUnauthorized).

type Authenticator

type Authenticator interface {
	AuthenticateChallenge() (string, bool)
}

Authenticator is implemented by any error that specifies its own WWW-Authenticate challenge for a 401 response. RFC 9110 §11.6.1 requires a server generating a 401 to include at least one WWW-Authenticate challenge; this package has no way to know an application's authentication scheme or realm on its own, so the response writers set one only when the error provides it - or, when it doesn't, from the application-wide default configured via SetDefaultAuthenticateChallenge (an error-specific challenge always wins over that default). BaseError implements it via SetAuthenticateChallenge/AuthenticateChallenge. As with ProblemTyper, return true only alongside a non-empty string: a true with "" ships an empty WWW-Authenticate header value instead of falling back to the configured default.

type BaseError

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

BaseError provides common error functionality

func New

func New(code ErrorCode, message string) *BaseError

New creates a generic error with the given code and message. Prefer the semantic constructors below (NewValidationError, NewNotFoundError, ...) when one exists for what you're representing; use New directly for codes that have no dedicated constructor, e.g. ErrCodeMissingRequired, ErrCodeDatabaseConnection, ErrCodeDatabaseTransaction, ErrCodeDatabaseMigration, ErrCodeResourceConflict, or ErrCodeQuotaExceeded. An empty code is normalized to ErrCodeInternal.

func Wrap

func Wrap(err error, code ErrorCode, message string) *BaseError

Wrap wraps err as a generic error with the given code and message. As with the semantic Wrap* constructors, err's text is never shown to clients unless SetPublicMessage is called explicitly. An empty code is normalized to ErrCodeInternal.

Example

Joined errors classify by their first coded child (stdlib errors.As traversal order), so reversing errors.Join's arguments would flip the response between 404 and 500. Classify a mixed-severity aggregate explicitly with Wrap instead of relying on argument order; the joined children stay reachable for errors.Is/errors.As.

package main

import (
	"errors"
	"fmt"

	"github.com/n-ae/svcerr"
)

func main() {
	notFound := svcerr.NewNotFoundError("user", "123")
	cleanupErr := errors.New("temp file cleanup failed")
	joined := errors.Join(notFound, cleanupErr)

	wrapped := svcerr.Wrap(joined, svcerr.ErrCodeInternal, "request processing failed")

	fmt.Println(svcerr.GetErrorCode(joined))
	fmt.Println(svcerr.GetErrorCode(wrapped))
	fmt.Println(errors.Is(wrapped, notFound), errors.Is(wrapped, cleanupErr))
}

Output:
NOT_FOUND
INTERNAL_ERROR
true true

func (*BaseError) AuthenticateChallenge

func (e *BaseError) AuthenticateChallenge() (string, bool)

AuthenticateChallenge returns the challenge set by SetAuthenticateChallenge, and whether one was set at all.

func (*BaseError) Code

func (e *BaseError) Code() ErrorCode

Code returns the error code

func (*BaseError) Context

func (e *BaseError) Context() map[string]any

Context returns the error's identity as a structured map. Since v1 it is derived on demand from the same canonical fields every other projection (details, headers, log fields) uses, rather than snapshotted at construction - each semantic type shadows this method with its own derivation (see e.g. NotFoundError.Context), so the returned map can never disagree with what the response writers report. BaseError itself carries no identity beyond code and message, so for the generic New/ Wrap errors this returns nil, as it always has. Every call builds a fresh map; mutating the result never reaches the error.

func (*BaseError) Error

func (e *BaseError) Error() string

Error implements the error interface

func (*BaseError) ProblemInstance

func (e *BaseError) ProblemInstance() (string, bool)

ProblemInstance returns the URI set by SetProblemInstance, and whether one was set at all.

func (*BaseError) ProblemTitle

func (e *BaseError) ProblemTitle() (string, bool)

ProblemTitle returns the title set by SetProblemTitle, and whether one was set at all.

func (*BaseError) ProblemType

func (e *BaseError) ProblemType() (string, bool)

ProblemType returns the URI set by SetProblemType, and whether one was set at all.

func (*BaseError) PublicDetails

func (e *BaseError) PublicDetails() (add map[string]any, remove map[string]struct{})

PublicDetails returns the keys SetPublicDetail added or overrode, and the keys RemovePublicDetail suppressed - the capability extractErrorDetails needs to apply both on top of a built-in type's automatic extraction. Both returned maps are shallow copies, the same contract as Context(): adding or removing keys through them doesn't reach back into the error - use SetPublicDetail/RemovePublicDetail, which also keep the two maps' last-call-wins bookkeeping intact - but an addition value that's itself a map, slice, or pointer is shared, not copied.

func (*BaseError) PublicMessage

func (e *BaseError) PublicMessage() (string, bool)

PublicMessage returns the message set by SetPublicMessage, and whether one was set at all.

func (*BaseError) RemovePublicDetail

func (e *BaseError) RemovePublicDetail(key string)

RemovePublicDetail suppresses key from the structured "details" map, even if this error's built-in type would otherwise include it - e.g. hiding NotFoundError's resource_id when the identifier itself is sensitive (an email address, say). Whichever of SetPublicDetail/ RemovePublicDetail was called most recently for a given key wins - calling this after SetPublicDetail(key, ...) un-does that addition.

func (*BaseError) SetAuthenticateChallenge

func (e *BaseError) SetAuthenticateChallenge(challenge string)

SetAuthenticateChallenge sets the WWW-Authenticate header WriteHTTPError/WriteHTTPErrorHTML/WriteHTTPProblem send alongside a 401 response - e.g. `Bearer realm="api"`. Only applied when the error's code maps to 401; set on an error whose code maps elsewhere and it's silently unused. Takes precedence over the application-wide SetDefaultAuthenticateChallenge value, which covers 401 errors that don't call this.

func (*BaseError) SetProblemInstance

func (e *BaseError) SetProblemInstance(uri string)

SetProblemInstance sets the RFC 9457 "instance" URI WriteHTTPProblem sends for this specific occurrence - e.g. a request ID or trace URL. Unset by default, in which case the field is omitted entirely.

func (*BaseError) SetProblemTitle

func (e *BaseError) SetProblemTitle(title string)

SetProblemTitle overrides the RFC 9457 "title" WriteHTTPProblem sends for this error, in place of the default http.StatusText(status). See SetProblemType.

func (*BaseError) SetProblemType

func (e *BaseError) SetProblemType(uri string)

SetProblemType overrides the RFC 9457 "type" URI WriteHTTPProblem sends for this error, in place of the default "about:blank". Per RFC 9457, pair this with SetProblemTitle too - a stable, occurrence-invariant summary of the custom type, since http.StatusText(status) (the default Title, correct only for "about:blank") describes the HTTP status in general, not this specific problem type.

func (*BaseError) SetPublicDetail

func (e *BaseError) SetPublicDetail(key string, value any)

SetPublicDetail adds or overrides a key in the structured "details" map WriteHTTPError/WriteHTTPProblem send to the client, alongside whatever this error's built-in type already contributes (e.g. NotFoundError's resource_type/resource_id) - or, for a code with no dedicated type (New/ Wrap), the only source of details at all. Unlike SetPublicMessage, this can be called more than once to add several keys. Whichever of SetPublicDetail/RemovePublicDetail was called most recently for a given key wins - calling this after RemovePublicDetail(key) un-suppresses it.

The two response shapes place details differently, which matters for six reserved names: WriteHTTPError/WriteJSON nest details under error.details, where any key is fine, but WriteHTTPProblem/WriteProblem flatten them to the top level of the RFC 9457 object, where "type", "title", "status", "detail", "instance", and "code" are registered (or package-owned) members - a detail with one of those names is silently omitted from problem-details output rather than allowed to occupy the member's slot. To set the real members, use SetProblemType, SetProblemTitle, and SetProblemInstance; status, detail, and code always come from the error's own classification.

func (*BaseError) SetPublicMessage

func (e *BaseError) SetPublicMessage(msg string)

SetPublicMessage overrides the message WriteHTTPError, WriteHTTPErrorHTML, and UserMessage show the client for this error instance, so the logged Error() text (which may carry internal detail) and the client-facing text can differ. Unset by default, in which case those functions fall back to their normal behavior (the error's own message, or a default per-code message).

Example

SetPublicMessage opts a specific error instance into a caller-chosen client-facing message, overriding the per-code default - the logged Error() text is unaffected.

package main

import (
	"errors"
	"fmt"
	"net/http/httptest"

	"github.com/n-ae/svcerr"
)

func main() {
	err := svcerr.WrapDatabaseError(errors.New("connection refused"), "query", "SELECT 1")
	err.SetPublicMessage("We're having trouble reaching the database. Please try again shortly.")

	rec := httptest.NewRecorder()
	svcerr.WriteJSON(rec, err)

	fmt.Println(rec.Body.String())
}

Output:
{"error":{"code":"DB_QUERY","message":"We're having trouble reaching the database. Please try again shortly.","details":{"operation":"query"}}}

func (*BaseError) StackTrace

func (e *BaseError) StackTrace() []string

StackTrace resolves and formats the stack trace captured when this error was constructed (or last RecaptureStackTrace'd). Each call builds a fresh []string, so there's no shared internal state for a caller to mutate through the result - but also no caching, so calling it repeatedly re-resolves the frames each time.

func (*BaseError) Unwrap

func (e *BaseError) Unwrap() error

Unwrap implements error unwrapping

type Coder

type Coder interface {
	Code() ErrorCode
}

Coder is implemented by any error that carries an application-specific ErrorCode - the minimal capability GetErrorCode and HTTPStatusCode need. A custom error type only needs this one method to participate in status mapping; unlike ErrorWithCode, it doesn't also require Unwrap or StackTrace. Code should return a non-empty value: GetErrorCode normalizes "" to ErrCodeInternal (the same normalization New and Wrap apply to their code argument), so an empty Code() loses whatever specific classification was intended rather than reaching the wire as-is.

type ConflictError

type ConflictError struct {
	BaseError
	// contains filtered or unexported fields
}

ConflictError represents resource conflict errors

func NewConflictError

func NewConflictError(resourceType, conflictKey, message string) *ConflictError

NewConflictError creates a new conflict error

func WrapConflictError

func WrapConflictError(err error, resourceType, conflictKey, message string) *ConflictError

WrapConflictError wraps an existing error as a conflict error. ErrCodeAlreadyExists is in mayExposeOwnMessage's safe category, so message is shown to the client the same as NewConflictError's - it's still an explicit caller argument, never derived from err.

func (*ConflictError) ConflictKey

func (e *ConflictError) ConflictKey() string

ConflictKey returns the conflicting key or constraint, e.g. "email".

func (*ConflictError) Context

func (e *ConflictError) Context() map[string]any

Context returns this error's identity as a fresh map - resource_type and conflict_key.

func (*ConflictError) ResourceType

func (e *ConflictError) ResourceType() string

ResourceType returns the kind of resource in conflict, e.g. "user".

type DatabaseError

type DatabaseError struct {
	BaseError
	// contains filtered or unexported fields
}

DatabaseError represents database operation errors

func NewDatabaseError

func NewDatabaseError(operation, message string) *DatabaseError

NewDatabaseError creates a new database error

func WrapDatabaseError

func WrapDatabaseError(err error, operation, query string) *DatabaseError

WrapDatabaseError wraps an existing error as a database error

func (*DatabaseError) Context

func (e *DatabaseError) Context() map[string]any

Context returns this error's identity as a fresh map - operation, and query when one was recorded.

func (*DatabaseError) Operation

func (e *DatabaseError) Operation() string

Operation returns the database operation this error describes - "query", "insert", "update", "delete", "transaction", "migration".

func (*DatabaseError) Query

func (e *DatabaseError) Query() string

Query returns the SQL text WrapDatabaseError recorded, or "" - never rendered to clients (see extractErrorDetails and errorLogFields).

type ErrorCode

type ErrorCode string

ErrorCode represents application-specific error codes

const (
	// Validation errors (1xxx)
	ErrCodeInvalidInput        ErrorCode = "INVALID_INPUT"
	ErrCodeMissingRequired     ErrorCode = "MISSING_REQUIRED"
	ErrCodeInvalidFormat       ErrorCode = "INVALID_FORMAT"
	ErrCodeConstraintViolation ErrorCode = "CONSTRAINT_VIOLATION"

	// Database errors (2xxx)
	ErrCodeDatabaseConnection  ErrorCode = "DB_CONNECTION"
	ErrCodeDatabaseQuery       ErrorCode = "DB_QUERY"
	ErrCodeDatabaseTransaction ErrorCode = "DB_TRANSACTION"
	ErrCodeDatabaseMigration   ErrorCode = "DB_MIGRATION"

	// External API errors (3xxx). The specific service is carried in
	// ExternalAPIError.Service, not encoded as a separate code per service.
	ErrCodeExternalAPI ErrorCode = "EXTERNAL_API_ERROR"

	// Authentication errors (4xxx)
	ErrCodeUnauthorized     ErrorCode = "UNAUTHORIZED"
	ErrCodeTokenExpired     ErrorCode = "TOKEN_EXPIRED"
	ErrCodeTokenInvalid     ErrorCode = "TOKEN_INVALID"
	ErrCodePermissionDenied ErrorCode = "PERMISSION_DENIED"

	// Resource errors (5xxx)
	ErrCodeNotFound         ErrorCode = "NOT_FOUND"
	ErrCodeAlreadyExists    ErrorCode = "ALREADY_EXISTS"
	ErrCodeResourceConflict ErrorCode = "RESOURCE_CONFLICT"

	// Rate limiting (6xxx)
	ErrCodeRateLimitExceeded ErrorCode = "RATE_LIMIT_EXCEEDED"
	ErrCodeQuotaExceeded     ErrorCode = "QUOTA_EXCEEDED"

	// Internal errors (9xxx). RecoveryMiddleware reports recovered panics
	// as ErrCodeInternal too - there's no separate panic-specific code.
	ErrCodeInternal       ErrorCode = "INTERNAL_ERROR"
	ErrCodeNotImplemented ErrorCode = "NOT_IMPLEMENTED"
)

func GetErrorCode

func GetErrorCode(err error) ErrorCode

GetErrorCode extracts the error code from an error. It only requires Coder, not the full ErrorWithCode - a custom error type that implements just Code() ErrorCode is picked up here (and so by HTTPStatusCode) even if it doesn't also implement Unwrap or StackTrace.

type ErrorDetail

type ErrorDetail struct {
	Code    ErrorCode      `json:"code"`
	Message string         `json:"message"`
	Details map[string]any `json:"details,omitempty"`
}

ErrorDetail contains detailed error information for API responses

type ErrorWithCode

type ErrorWithCode interface {
	error
	Coder
	Unwrap() error
	StackTracer
}

ErrorWithCode is the full capability set every type in this package implements via BaseError: Coder and StackTracer, plus error and Unwrap. Prefer the narrower Coder, StackTracer, or PublicMessager when writing a custom error type that doesn't want to embed BaseError - GetErrorCode, GetStackTrace, and getUserFriendlyMessage each check the capability they need independently, not this combined interface.

type ExternalAPIError

type ExternalAPIError struct {
	BaseError
	// contains filtered or unexported fields
}

ExternalAPIError represents errors from external APIs

func NewExternalAPIError

func NewExternalAPIError(service, message string, statusCode int, url string) *ExternalAPIError

NewExternalAPIError creates a new external API error

func WrapExternalAPIError

func WrapExternalAPIError(err error, service, url string, statusCode int) *ExternalAPIError

WrapExternalAPIError wraps an existing error as an external API error

func (*ExternalAPIError) Context

func (e *ExternalAPIError) Context() map[string]any

Context returns this error's identity as a fresh map - service, status_code, url, and retry_after when a hint was recorded.

func (*ExternalAPIError) RetryAfter

func (e *ExternalAPIError) RetryAfter() (seconds int, ok bool)

RetryAfter returns the upstream retry hint SetRetryAfter recorded, in seconds, and whether one was recorded at all. The stored value is always a valid non-negative delay-seconds - SetRetryAfter clamps on the way in, and nothing can mutate it afterward.

func (*ExternalAPIError) Service

func (e *ExternalAPIError) Service() string

Service returns the caller-defined upstream service name, e.g. "yahoo", "nba_stats".

func (*ExternalAPIError) SetRetryAfter

func (e *ExternalAPIError) SetRetryAfter(seconds int)

SetRetryAfter records an upstream retry hint of seconds (e.g. parsed from the upstream's own Retry-After), clamped to non-negative per RFC 9110 §10.2.3 - the only way to attach the hint, since no constructor takes it. The response writers then emit it as the Retry-After header and the retry_after details member; RetryAfter() reads it back.

func (*ExternalAPIError) StatusCode

func (e *ExternalAPIError) StatusCode() int

StatusCode returns the upstream's HTTP status, or 0 when unknown.

func (*ExternalAPIError) URL

func (e *ExternalAPIError) URL() string

URL returns the upstream URL the constructor recorded - never rendered to clients (see extractErrorDetails and errorLogFields).

type HTTPErrorResponse

type HTTPErrorResponse struct {
	Error ErrorDetail `json:"error"`
}

HTTPErrorResponse represents a standardized HTTP error response

type HeaderPolicy

type HeaderPolicy struct {
	// KeepContentEncoding preserves a pre-existing Content-Encoding
	// header instead of deleting it. By default it's deleted because the
	// body these writers produce is always plain, uncompressed text - a
	// stale "gzip" left by a handler that never got to write its
	// compressed body would make clients gzip-decode plain JSON. Set this
	// when the ResponseWriter these writers receive belongs to a
	// transparent compression middleware that sets the header once and
	// compresses everything written through it: there the header is live,
	// not stale, and deleting it mislabels a genuinely compressed body as
	// plain text (see the README's compression-ordering section).
	KeepContentEncoding bool
	// ClearValidators additionally deletes ETag, Last-Modified, and
	// Accept-Ranges. By default they're kept: they describe the specific
	// successful representation this error response isn't attempting to
	// be, but - unlike a wrong Content-Length or Content-Encoding - a
	// stale conditional-request header doesn't actively mislead a client
	// about the body it's receiving, and a plain WriteJSON call may
	// legitimately want handler-set headers preserved. Set this for
	// deployments that would rather no abandoned-representation metadata
	// ever ride along on an error response.
	ClearValidators bool
}

HeaderPolicy configures how this package's response writers treat representation headers a handler (or a wrapping middleware) already set before the error body is written. The zero value is the long-standing default behavior: Content-Encoding is cleared, validators are kept. Field polarities follow from that - each false value must mean "what the package always did".

type InternalError

type InternalError struct {
	BaseError
	// contains filtered or unexported fields
}

InternalError represents unexpected internal errors

func NewInternalError

func NewInternalError(component, message string) *InternalError

NewInternalError creates a new internal error

func WrapInternalError

func WrapInternalError(err error, component, message string) *InternalError

WrapInternalError wraps an existing error as an internal error

func (*InternalError) Component

func (e *InternalError) Component() string

Component returns the component the failure is attributed to, e.g. "billing" - also carried into the structured log fields on 5xx responses.

func (*InternalError) Context

func (e *InternalError) Context() map[string]any

Context returns this error's identity as a fresh map - component.

type Level

type Level int

Level is a log severity, independent of any specific logging library.

const (
	LevelInfo Level = iota
	LevelWarn
	LevelError
)

type Logger

type Logger interface {
	// Log records msg at the given level. err may be nil (e.g. when a
	// caller passes a nil error to WriteHTTPError - the record still
	// carries the response fields). fields carries structured context
	// (error_code, http_status, stack_trace, and error-type-specific
	// keys like "field" or "resource_id").
	Log(level Level, err error, fields map[string]any, msg string)
}

Logger is the minimal structured-logging surface this package needs. Nothing in this file imports a logging library - wrap your logger to satisfy this interface. See the zerologadapter subpackage for a zerolog adapter (that subpackage, unlike this one, does depend on zerolog).

type NotFoundError

type NotFoundError struct {
	BaseError
	// contains filtered or unexported fields
}

NotFoundError represents resource not found errors

func NewNotFoundError

func NewNotFoundError(resourceType, resourceID string) *NotFoundError

NewNotFoundError creates a new not found error

Example

Check error types with stdlib errors.As - there's no per-type IsXError wrapper.

package main

import (
	"errors"
	"fmt"

	"github.com/n-ae/svcerr"
)

func main() {
	findLeague := func(id string) error {
		return svcerr.NewNotFoundError("league", id)
	}

	err := findLeague("12345")

	var nfErr *svcerr.NotFoundError
	if errors.As(err, &nfErr) {
		fmt.Println(nfErr.ResourceType(), nfErr.ResourceID())
	}
	fmt.Println(svcerr.GetErrorCode(err), svcerr.HTTPStatusCode(svcerr.GetErrorCode(err)))
}

Output:
league 12345
NOT_FOUND 404

func WrapNotFoundError

func WrapNotFoundError(err error, resourceType, resourceID string) *NotFoundError

WrapNotFoundError wraps an existing error (e.g. sql.ErrNoRows) as a not found error, preserving it in the chain for errors.Is/errors.As while still getting NotFoundError's type, automatic resource_type/resource_id details, and client-facing message - which is generated the same way NewNotFoundError's is, never derived from err's own text.

func (*NotFoundError) Context

func (e *NotFoundError) Context() map[string]any

Context returns this error's identity as a fresh map - resource_type and resource_id.

func (*NotFoundError) ResourceID

func (e *NotFoundError) ResourceID() string

ResourceID returns the identifier that wasn't found. It's included in the response details and the error message by default - see RemovePublicDetail and SetPublicMessage when the identifier itself is sensitive.

func (*NotFoundError) ResourceType

func (e *NotFoundError) ResourceType() string

ResourceType returns the kind of resource that wasn't found, e.g. "league", "user".

type ProblemDetails

type ProblemDetails struct {
	Type       string         // a URI reference identifying the problem type; "about:blank" when none is registered
	Title      string         // a short, occurrence-invariant summary of the problem type
	Status     int            // the HTTP status code for this occurrence
	Detail     string         // a human-readable explanation specific to this occurrence
	Instance   string         // a URI reference identifying this specific occurrence, if known
	Code       ErrorCode      // this package's own error code, as an extension member
	Extensions map[string]any // additional extension members (e.g. resource_id, field)
}

ProblemDetails is the RFC 9457 (https://www.rfc-editor.org/rfc/rfc9457) "application/problem+json" response body written by WriteHTTPProblem. Code and any extractErrorDetails fields are extension members - RFC 9457 says extension members live at the top level alongside the registered ones, which is what MarshalJSON does instead of nesting them.

func (ProblemDetails) MarshalJSON

func (p ProblemDetails) MarshalJSON() ([]byte, error)

MarshalJSON flattens Extensions into the top-level object rather than nesting them under a sub-object, per RFC 9457's extension-member model. Extension entries named after a registered member (or "code") are dropped - see reservedProblemMembers.

type ProblemInstancer

type ProblemInstancer interface {
	ProblemInstance() (string, bool)
}

ProblemInstancer is implemented by any error that specifies its own RFC 9457 "instance" URI for WriteHTTPProblem - e.g. a request ID or trace URL for this specific occurrence. BaseError implements it via SetProblemInstance/ProblemInstance. As with ProblemTyper, return true only alongside a non-empty string.

type ProblemTitler

type ProblemTitler interface {
	ProblemTitle() (string, bool)
}

ProblemTitler is implemented by any error that specifies its own RFC 9457 "title" for WriteHTTPProblem, in place of the default http.StatusText(status) - useful alongside a custom SetProblemType, since RFC 9457 defines title as a short, occurrence-invariant summary of that specific problem type, not of the HTTP status in general. BaseError implements it via SetProblemTitle/ProblemTitle. As with ProblemTyper, return true only alongside a non-empty string: a true with "" ships a blank RFC 9457 title rather than falling back to the computed default.

type ProblemTyper

type ProblemTyper interface {
	ProblemType() (string, bool)
}

ProblemTyper is implemented by any error that specifies its own RFC 9457 "type" URI for WriteHTTPProblem, in place of the default "about:blank". BaseError implements it via SetProblemType/ProblemType. The bool is the contract: return true only alongside a non-empty string, the same guarantee BaseError's own implementation makes. WriteHTTPProblem uses the string as-is whenever the bool is true, so a true with "" ships an empty RFC 9457 "type" rather than falling back to "about:blank".

type PublicDetailer

type PublicDetailer interface {
	PublicDetails() (add map[string]any, remove map[string]struct{})
}

PublicDetailer is implemented by any error that customizes the structured "details" map WriteHTTPError/WriteHTTPProblem send - keys to add or override beyond whatever a built-in type's automatic extraction already contributes (or, for a code with no dedicated type, the only source of details at all), and keys to suppress from that automatic extraction (e.g. hiding NotFoundError's resource_id when the identifier is sensitive). BaseError implements it via SetPublicDetail/ RemovePublicDetail.

type PublicMessager

type PublicMessager interface {
	PublicMessage() (string, bool)
}

PublicMessager is implemented by any error with a client-facing message distinct from its logged Error() text - the minimal capability getUserFriendlyMessage needs to honor SetPublicMessage-style overrides. BaseError (and so every type in this package) implements it via SetPublicMessage/PublicMessage.

type RateLimitError

type RateLimitError struct {
	BaseError
	// contains filtered or unexported fields
}

RateLimitError represents rate limiting errors

func NewRateLimitError

func NewRateLimitError(service string, limit, retryAfter int) *RateLimitError

NewRateLimitError creates a new rate limit error

func WrapRateLimitError

func WrapRateLimitError(err error, service string, limit, retryAfter int) *RateLimitError

WrapRateLimitError wraps an existing error as a rate limit error. ErrCodeRateLimitExceeded is in mayExposeOwnMessage's safe category, so message is generated the same way NewRateLimitError's is, never derived from err's own text.

func (*RateLimitError) Context

func (e *RateLimitError) Context() map[string]any

Context returns this error's identity as a fresh map - service, limit, and retry_after.

func (*RateLimitError) Limit

func (e *RateLimitError) Limit() int

Limit returns the request limit that was exceeded.

func (*RateLimitError) RetryAfter

func (e *RateLimitError) RetryAfter() int

RetryAfter returns the retry delay in seconds. The stored value is always a valid non-negative delay-seconds (RFC 9110 §10.2.3) - the constructors clamp on the way in, and nothing can mutate it afterward.

func (*RateLimitError) Service

func (e *RateLimitError) Service() string

Service returns the rate-limited service name.

type Renderer

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

Renderer renders error responses under a fixed, instance-scoped configuration - for tests, for processes hosting two differently configured services, or simply to avoid global state. Construct with NewRenderer; the configuration is copied and immutable from then on.

A Renderer is fully self-contained: the package-level configuration - RegisterStatusCode's registry, SetDefaultAuthenticateChallenge, SetHeaderPolicy, SetRecoveryHeaderPolicy - does not affect it, and its own configuration never leaks to the package-level writers. If the application (or a library it uses) registers codes globally, mirror the ones this Renderer should know into RendererConfig.StatusCodes. Safe for concurrent use.

func NewRenderer

func NewRenderer(cfg RendererConfig) (*Renderer, error)

NewRenderer builds a Renderer from cfg. The config is deep-copied (mutating cfg or its StatusCodes map afterward has no effect), and every StatusCodes entry is validated against the same 400-599 rule as RegisterStatusCode - an invalid entry is rejected here, at startup, rather than surfacing later as a WriteHeader panic inside an error handler.

Example

A Renderer scopes the package's configuration to an instance - status codes, challenge default, header policies, and the logger in one place - instead of the package-level globals. It's fully self-contained: global configuration doesn't affect it, and two differently configured Renderers can serve in the same process.

package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"

	"github.com/n-ae/svcerr"
)

func main() {
	r, err := svcerr.NewRenderer(svcerr.RendererConfig{
		StatusCodes:                  map[svcerr.ErrorCode]int{"OUT_OF_CREDITS": http.StatusPaymentRequired},
		DefaultAuthenticateChallenge: `Bearer realm="api"`,
	})
	if err != nil {
		panic(err) // invalid config should fail loudly at startup
	}

	rec := httptest.NewRecorder()
	res := r.JSON(rec, svcerr.New("OUT_OF_CREDITS", "credits exhausted"))
	fmt.Println(res.Status)

	rec = httptest.NewRecorder()
	r.JSON(rec, svcerr.NewAuthenticationError("token_expired", "session expired"))
	fmt.Println(rec.Header().Get("WWW-Authenticate"))
}

Output:
402
Bearer realm="api"

func (*Renderer) HTML

func (r *Renderer) HTML(w http.ResponseWriter, err error) WriteResult

HTML mirrors JSON for the HTML fragment rendering WriteHTTPErrorHTML writes. RenderErr is always nil - see WriteResult.

func (*Renderer) JSON

func (r *Renderer) JSON(w http.ResponseWriter, err error) WriteResult

JSON renders err's standardized JSON error response under this Renderer's configuration - the same body WriteHTTPError writes. It both logs (when a Logger is configured) and returns the WriteResult, collapsing the package-level WriteHTTPError/WriteJSON/WriteJSONResult split into one method.

func (*Renderer) Middleware

func (r *Renderer) Middleware() func(http.Handler) http.Handler

Middleware returns RecoveryMiddleware's behavior under this Renderer's configuration and Logger: panic recovery with commit tracking, writing the replacement internal-error response with this Renderer's status mapping, challenge default, and RecoveryHeaderPolicy.

func (*Renderer) Problem

func (r *Renderer) Problem(w http.ResponseWriter, err error) WriteResult

Problem mirrors JSON for the RFC 9457 application/problem+json rendering WriteHTTPProblem writes.

type RendererConfig

type RendererConfig struct {
	// StatusCodes maps application ErrorCodes to HTTP statuses, layered
	// over the built-in mapping (a built-in code may be overridden; an
	// absent code falls through to the built-ins). Each status must be
	// 400-599, the same rule RegisterStatusCode enforces. Note that a
	// Renderer does NOT consult the global RegisterStatusCode registry -
	// see Renderer.
	StatusCodes map[ErrorCode]int
	// DefaultAuthenticateChallenge is the WWW-Authenticate challenge for
	// 401 responses whose error doesn't provide its own via
	// SetAuthenticateChallenge - the per-instance equivalent of
	// SetDefaultAuthenticateChallenge. Empty means no default.
	DefaultAuthenticateChallenge string
	// HeaderPolicy configures representation-header handling for the
	// JSON/HTML/Problem methods - the per-instance equivalent of
	// SetHeaderPolicy.
	HeaderPolicy HeaderPolicy
	// RecoveryHeaderPolicy configures the same for Middleware's panic
	// replacement - the per-instance equivalent of
	// SetRecoveryHeaderPolicy. See SetRecoveryHeaderPolicy for why the
	// two paths are configured separately.
	RecoveryHeaderPolicy HeaderPolicy
	// Logger, when non-nil, receives one structured record per rendered
	// response from JSON/HTML/Problem (the same fields WriteHTTPError
	// logs) and per recovered panic from Middleware. Nil disables
	// logging; the methods still return their WriteResult either way, so
	// a Renderer never forces a choice between logging and result
	// reporting the way the package-level WriteHTTPError/WriteJSONResult
	// split does.
	Logger Logger
}

RendererConfig is the complete configuration for a Renderer - every knob the package-level globals expose, plus the logger, in one struct. The zero value reproduces the package's default behavior with no logging.

type StackTracer

type StackTracer interface {
	StackTrace() []string
}

StackTracer is implemented by any error that can report a captured stack trace - the minimal capability GetStackTrace needs.

type ValidationError

type ValidationError struct {
	BaseError
	// contains filtered or unexported fields
}

ValidationError represents input validation errors

func NewValidationError

func NewValidationError(message string, field string, value any) *ValidationError

NewValidationError creates a new validation error

func WrapValidationError

func WrapValidationError(err error, message string, field string) *ValidationError

WrapValidationError wraps an existing error as a validation error

func (*ValidationError) Context

func (e *ValidationError) Context() map[string]any

Context returns this error's identity as a fresh map - field and value - derived on demand from the same canonical state every other projection uses.

func (*ValidationError) Field

func (e *ValidationError) Field() string

Field returns the input field this validation error describes.

func (*ValidationError) Value

func (e *ValidationError) Value() any

Value returns the offending input value, when the constructor was given one - never rendered to clients (see extractErrorDetails), but available to callers for their own handling. The reference is fixed at construction but not deep-copied: if the caller passed a mutable object and mutates it later, Value (and Context) observe the change.

type WriteResult

type WriteResult struct {
	// Status is the HTTP status code svcerr selected and passed to
	// w.WriteHeader - on a marshal failure, the active mapping's status
	// for ErrCodeInternal (500 by default), not necessarily err's own
	// classification. It's what svcerr chose to
	// send, not a transport confirmation that the client received exactly
	// that status: a custom or third-party ResponseWriter could ignore it,
	// have already committed a different status earlier, transform it, or
	// panic during WriteHeader (see trackingResponseWriter.WriteHeader).
	Status int
	// RenderErr is the marshal error when the real body couldn't be
	// JSON-encoded and a generic fallback was substituted instead (nil
	// otherwise) - including a caller-supplied json.Marshaler that
	// panicked, which is recovered and reported here as an error rather
	// than allowed to escape the response writer (see safeJSONMarshal).
	// Always nil from WriteHTMLResult, whose body is plain string
	// concatenation and can't fail to encode.
	RenderErr error
	// WriteErr is whatever the final w.Write returned (nil on a full
	// write) - a client disconnect, an expired deadline, or any other
	// transport failure during delivery. Unlike RenderErr, it doesn't
	// imply a different body was sent, only that delivery of the
	// intended one may have failed or been truncated.
	WriteErr error
	// BytesWritten is the number of body bytes the final w.Write reported
	// written: the full body length when WriteErr is nil, less on a
	// truncated delivery (WriteErr is then non-nil - the transport's own
	// error, or io.ErrShortWrite for a non-conforming writer that
	// under-reported with a nil error). Body accounting only; status line
	// and header bytes are never counted. Like Status, it's what the
	// ResponseWriter reported, not a transport confirmation the client
	// received those bytes.
	BytesWritten int
}

WriteResult reports what WriteJSONResult/WriteHTMLResult/ WriteProblemResult actually did, for a caller that wants to detect a serialization or delivery failure without participating in this package's Logger contract. WriteHTTPError/WriteHTTPErrorHTML/ WriteHTTPProblem carry the same information into their log fields (response_render_error, response_write_error, response_bytes_written, rendered_error_code) instead of returning it; the plain WriteJSON/ WriteHTML/WriteProblem functions discard it entirely, same as before this type existed.

func WriteHTMLResult

func WriteHTMLResult(w http.ResponseWriter, err error) WriteResult

WriteHTMLResult mirrors WriteJSONResult for the HTML rendering. RenderErr is always nil - see WriteResult.

Prefer a Renderer, whose HTML method both logs (via the config Logger) and returns the WriteResult in one call - this function remains fully supported, but new code shouldn't need the split logging/result variants it exists for.

func WriteJSONResult

func WriteJSONResult(w http.ResponseWriter, err error) WriteResult

WriteJSONResult mirrors WriteJSON, additionally reporting a render or write failure - e.g. so a caller can avoid claiming success to its own caller, or report the failure through its own error-tracking system instead of this package's Logger contract.

Prefer a Renderer, whose JSON method both logs (via the config Logger) and returns the WriteResult in one call - this function remains fully supported, but new code shouldn't need the split logging/result variants it exists for.

func WriteProblemResult

func WriteProblemResult(w http.ResponseWriter, err error) WriteResult

WriteProblemResult mirrors WriteJSONResult for the RFC 9457 rendering.

Prefer a Renderer, whose Problem method both logs (via the config Logger) and returns the WriteResult in one call - this function remains fully supported, but new code shouldn't need the split logging/result variants it exists for.