Documentation
¶
Overview ¶
Package fault is the shared error taxonomy for the funcd platform (ADR-0002). It is stdlib-only and imported "up" by internal/** and pkg/**; it imports nothing beyond the standard library. Every layer builds errors from this package; the API edge maps them to RFC 9457 application/problem+json.
Index ¶
- func LogCause(w http.ResponseWriter, err error)
- func LogCauses(logger *slog.Logger) func(http.Handler) http.Handler
- func StatusOf(err error) int
- func WriteProblem(w http.ResponseWriter, err error)
- type Error
- func Conflictf(op, format string, a ...any) *Error
- func DeadlineExceededf(op, format string, a ...any) *Error
- func Forbiddenf(op, format string, a ...any) *Error
- func InsufficientStoragef(op, format string, a ...any) *Error
- func Internalf(op, format string, a ...any) *Error
- func Invalidf(op, format string, a ...any) *Error
- func NotFoundf(op, format string, a ...any) *Error
- func PayloadTooLargef(op, format string, a ...any) *Error
- func PreconditionFailedf(op, format string, a ...any) *Error
- func ResourceExhaustedf(op, format string, a ...any) *Error
- func Unauthorizedf(op, format string, a ...any) *Error
- func Unavailablef(op, format string, a ...any) *Error
- func Wrapf(err error, k Kind, op, format string, a ...any) *Error
- type Kind
- type KnownCause
- func (c *KnownCause) Error() string
- func (c *KnownCause) Errorf(op, format string, a ...any) *Error
- func (c *KnownCause) Fix() string
- func (c *KnownCause) Kind() Kind
- func (c *KnownCause) Name() string
- func (c *KnownCause) When() string
- func (c *KnownCause) Wrapf(err error, op, format string, a ...any) *Error
- type Problem
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LogCause ¶ added in v0.38.0
func LogCause(w http.ResponseWriter, err error)
LogCause logs err through the logger LogCauses put on w when err's problem detail leaves part of it out: a 500 at Error, any other status at Warn. WriteProblem calls it, and so does a transport that renders ToProblem itself (ADR-0005 §4). Without LogCauses it does nothing: a handler outside it logs what it is handed before it answers.
func LogCauses ¶ added in v0.38.0
LogCauses is the middleware of an HTTP operation's owner, which logs a failure once (ADR-0002 §3): through logger, it logs the error behind each problem whose detail leaves part of it out. It sits inside every other ResponseWriter wrapper, because LogCause finds it on the writer the handler holds.
func WriteProblem ¶
func WriteProblem(w http.ResponseWriter, err error)
WriteProblem writes an error as an RFC 9457 application/problem+json response. It sets Content-Type and writes the JSON body.
Types ¶
type Error ¶
type Error struct {
Kind Kind
Op string // e.g. "store.Get", "blob.Put" — free string, open set
Msg string // human-readable, safe to surface to callers
Detail map[string]string // deliberately flat, key-value diagnostic pairs
Err error // wrapped error
// KnownCause names why the error happened; Error() does not print it, so a problem's detail stays the same.
KnownCause *KnownCause
}
Error is the typed error used throughout the platform. It carries a Kind (for HTTP mapping), an Op (free string describing the operation that failed), a human-readable Msg, optional flat Detail (key-value pairs), the wrapped error via Err, and the KnownCause it was raised from, if any (ADR-0330).
func DeadlineExceededf ¶ added in v0.4.0
DeadlineExceededf builds a DeadlineExceeded error (504) with a formatted message.
func Forbiddenf ¶
Forbiddenf builds a Forbidden error with a formatted message.
func InsufficientStoragef ¶ added in v0.33.0
InsufficientStoragef builds an InsufficientStorage error (507) with a formatted message.
func PayloadTooLargef ¶
PayloadTooLargef builds a PayloadTooLarge error (413) with a formatted message.
func PreconditionFailedf ¶ added in v0.41.0
PreconditionFailedf builds a PreconditionFailed error (412) with a formatted message.
func ResourceExhaustedf ¶
ResourceExhaustedf builds a ResourceExhausted error (429) with a formatted message.
func Unauthorizedf ¶
Unauthorizedf builds an Unauthorized error with a formatted message.
func Unavailablef ¶
Unavailablef builds an Unavailable error with a formatted message.
func Wrapf ¶
Wrapf wraps an existing error with a Kind, Op, and formatted message. It is the primary tool for annotating errors as they propagate up through layers.
type Kind ¶
type Kind string
Kind is the machine-readable error kind — the stable identifier that maps to HTTP status codes and problem+json type URIs. Kinds are an open set but the enumerated constants below cover every case the platform needs.
const ( // Invalid means the request is malformed or a required dependency is missing. Invalid Kind = "invalid" // NotFound means the requested resource does not exist. NotFound Kind = "not_found" // Conflict means the request conflicts with the current state (e.g. duplicate name). Conflict Kind = "conflict" Unauthorized Kind = "unauthorized" // Forbidden means the authenticated identity lacks permission. Forbidden Kind = "forbidden" Unavailable Kind = "unavailable" // ResourceExhausted means a rate/quota limit was exceeded (429 Too Many Requests). ResourceExhausted Kind = "resource_exhausted" // PayloadTooLarge means a payload, key, object or record is over a size cap funcd enforces (413 // Content Too Large when it answers HTTP). PayloadTooLarge Kind = "payload_too_large" // InsufficientStorage means a write would take a store past its quota (507 Insufficient Storage, ADR-0292). InsufficientStorage Kind = "insufficient_storage" // DeadlineExceeded means the upstream did not start its response in time (504 Gateway Timeout, ADR-0151). DeadlineExceeded Kind = "deadline_exceeded" // PreconditionFailed means a conditional write's condition did not hold, so nothing was written (412). PreconditionFailed Kind = "precondition_failed" // Internal means an unexpected internal error occurred. Internal Kind = "internal" )
type KnownCause ¶ added in v0.45.0
type KnownCause struct {
// contains filtered or unexported fields
}
KnownCause is one named reason for an error, made only by NewKnownCause; it is an error, so errors.Is can find it. Each is defined once, beside the code that raises it, as io.EOF is (ADR-0330 Decision 1).
func KnownCauseOf ¶ added in v0.45.0
func KnownCauseOf(err error) *KnownCause
KnownCauseOf returns the known cause of the first Error in err's chain that has one, as KindOf returns the first Error's kind: the outermost cause wins. It returns nil when no Error of the chain has one.
func NewKnownCause ¶ added in v0.45.0
func NewKnownCause(k Kind, name, when, fix string) *KnownCause
NewKnownCause names its known cause "<package>.<name>", e.g. "kvstore.value-over-cap"; when and fix are one sentence each, written for the caller who gets the error.
func (*KnownCause) Error ¶ added in v0.45.0
func (c *KnownCause) Error() string
Error is the cause's name.
func (*KnownCause) Errorf ¶ added in v0.45.0
func (c *KnownCause) Errorf(op, format string, a ...any) *Error
Errorf builds an Error of c's kind whose KnownCause is c, with a formatted message.
func (*KnownCause) Fix ¶ added in v0.45.0
func (c *KnownCause) Fix() string
Fix says what the caller does about it.
func (*KnownCause) Kind ¶ added in v0.45.0
func (c *KnownCause) Kind() Kind
Kind is the kind of every error raised from the cause.
func (*KnownCause) Name ¶ added in v0.45.0
func (c *KnownCause) Name() string
Name is the cause's "<package>.<name>".
func (*KnownCause) When ¶ added in v0.45.0
func (c *KnownCause) When() string
When says when the cause happens.
type Problem ¶
type Problem struct {
Type string `` /* 184-byte string literal not displayed */
Title string `json:"title" doc:"A short summary of the problem type, such as Conflict."`
Status int `json:"status" doc:"The HTTP status code of the answer."`
Detail string `` /* 128-byte string literal not displayed */
Instance string `json:"instance,omitempty" doc:"A URI that names this occurrence of the problem. funcd does not set it."`
}
Problem is an RFC 9457 application/problem+json body. Its doc tags describe the error body of the API reference (ADR-0331 Decision 3.2); they change nothing on the wire.
Source Files