Documentation
¶
Overview ¶
Package apperr turns internal errors into stable, reportable numeric codes.
A service wraps an internal cause with Coded(code, cause). The code travels with the error through the normal error chain, so errors.Is and errors.As keep working, and Code(err) recovers the nearest code at any boundary. At the edge, a Registry the consumer builds at startup maps each code to a sanitized, client-safe message: the caller learns a code they can quote in a bug report, never the raw internal detail.
The package is dependency-free: it imports no logging, tracing, or third-party package, only the standard library. Observability is pluggable through two small interfaces, Recorder and Logger, wired with WithRecorder and WithLogger and defaulting to no-ops. Bring any stack -- log/slog, OpenTelemetry, zap -- by writing a few-line adapter that implements them (see the examples). Nothing is bundled, so a consumer's go.mod stays free of any dependency they did not choose.
Codes are the consumer's own namespace. The service prefix convention (WithService) is one supported way to let each service own a code prefix so a code is easy to attribute at a glance; it is optional. A prefix may be one digit or several, and WithCodeDigits fixes the code width so each prefix owns a single range (WithService(12) with WithCodeDigits(5) owns 12000-12999).
An Entry may also declare a transport-neutral Category (internal by default). Registry.Category looks it up from a coded error, so one mapper per transport can turn any code into a gRPC or HTTP status without this package importing either.
Index ¶
- func Code(err error) (code int, ok bool)
- func Coded(code int, cause error) error
- func ContextWithFields(ctx context.Context, fields ...Field) context.Context
- type Category
- type Entry
- type Field
- type Logger
- type Option
- type Recorder
- type Registry
- func (r *Registry) Category(err error) Category
- func (r *Registry) Describe(code int) (Entry, bool)
- func (r *Registry) Markdown() string
- func (r *Registry) Message(code int) string
- func (r *Registry) Present(err error, defaultCode int) (clientMsg string, code int)
- func (r *Registry) PresentContext(ctx context.Context, err error, defaultCode int) (clientMsg string, code int)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Code ¶
Code returns the code carried by err, walking the error chain with errors.As and returning the nearest coded error's code. It reports (0, false) when err is nil or carries no code, so a caller can distinguish "no code" from a legitimately zero code.
Example ¶
ExampleCode recovers the stable code from a wrapped internal error.
package main
import (
"errors"
"fmt"
apperr "github.com/Bugs5382/go-apperr"
)
func main() {
err := apperr.Coded(1001, errors.New("database unavailable"))
code, ok := apperr.Code(err)
fmt.Println(code, ok)
}
Output: 1001 true
func Coded ¶
Coded wraps cause with a stable numeric code. The returned error's Unwrap returns cause, so errors.Is and errors.As traverse to it unchanged; the code rides alongside and is recovered with Code. A nil cause is allowed -- the result is a bare coded marker whose Error reports only the code.
func ContextWithFields ¶ added in v1.1.0
ContextWithFields returns a child of ctx carrying fields after any fields ctx already has. Order is kept and duplicate keys are not merged: a sink sees every field in the order it was added and decides how to render repeats. The parent context is never modified, so sibling requests do not share fields. With no fields it returns ctx unchanged.
Example ¶
ExampleContextWithFields attaches request metadata at the edge and reads it back the way a sink would, from the ctx it already receives.
package main
import (
"context"
"fmt"
apperr "github.com/Bugs5382/go-apperr"
)
func main() {
ctx := apperr.ContextWithFields(context.Background(),
apperr.Field{Key: "method", Value: "GET"},
apperr.Field{Key: "route", Value: "/widgets/{id}"},
)
for _, f := range apperr.FieldsFromContext(ctx) {
fmt.Printf("%s=%v\n", f.Key, f.Value)
}
}
Output: method=GET route=/widgets/{id}
Types ¶
type Category ¶ added in v1.1.0
type Category int
Category is a transport-neutral class of failure for a registered code. It lets one shared mapper per transport (a gRPC status, an HTTP status) turn any coded error into the right response, instead of every service keeping its own code-to-status table. The package never imports a transport; see the Registry.Category examples for gRPC and HTTP mappers.
The zero value is CategoryInternal, so an Entry that sets no Category is internal, exactly as before categories existed.
const ( // CategoryInternal is an unexpected server-side failure. It is the default. CategoryInternal Category = iota // CategoryNotFound means the requested resource does not exist. CategoryNotFound // CategoryInvalid means the caller sent a malformed or invalid request. CategoryInvalid // caller may retry later. CategoryUnavailable // CategoryPermissionDenied means the caller is known but not allowed to do // this. CategoryPermissionDenied )
type Entry ¶
Entry describes one code the consumer registers. Title is a short area/label for the code; Cause is a one-line internal description. Both are for the consumer's own error-codes documentation (see Markdown) and are never shown to a client -- only the code and the rendered message template are.
Category is optional and transport-neutral; left unset it is CategoryInternal. Registry.Category reads it back from a coded error.
type Field ¶ added in v1.1.0
Field is one request-scoped key/value pair for the sinks, such as the request method or route. Attach fields to a context with ContextWithFields at the edge of a request; a Recorder or Logger reads them back with FieldsFromContext from the ctx it already receives, so the sink signatures do not change.
func FieldsFromContext ¶ added in v1.1.0
FieldsFromContext returns the request fields attached to ctx, in the order they were added. It returns nil when ctx carries none (or is nil). The result is a copy, so a sink may modify it freely.
type Logger ¶
Logger is the neutral logging sink the observability-aware present path calls. An implementation emits one structured line carrying the code and, when the backend correlates traces, the trace_id. As with Recorder, this package ships only a no-op; a small custom shim over the consumer's logger (log/slog, zap, etc.) provides the real thing.
Both sinks can read request-scoped fields (method, route, and so on) the caller attached with ContextWithFields by calling FieldsFromContext on ctx.
type Option ¶
type Option func(*Registry)
Option configures a Registry at construction. All options are optional; the zero configuration is a plain code table with the default message template and no-op observability.
func WithCodeDigits ¶ added in v1.1.0
WithCodeDigits requires every registered code to have exactly n decimal digits (sign ignored). With WithService it fixes each service's code range from the prefix length: a prefix of length L owns the n-L trailing digits, so WithService(12) with WithCodeDigits(5) accepts 12000 through 12999 and rejects anything outside it. NewRegistry fails when n is not positive or leaves no digit after the prefix.
Example ¶
ExampleWithCodeDigits gives a service a two-digit prefix and fixed-width codes, so it owns 12000 through 12999 and anything else fails registration.
package main
import (
"fmt"
apperr "github.com/Bugs5382/go-apperr"
)
func main() {
_, err := apperr.NewRegistry([]apperr.Entry{
{Code: 12001, Title: "database", Cause: "database unavailable"},
}, apperr.WithService(12), apperr.WithCodeDigits(5))
fmt.Println(err)
_, err = apperr.NewRegistry([]apperr.Entry{
{Code: 13001, Title: "database", Cause: "database unavailable"},
}, apperr.WithService(12), apperr.WithCodeDigits(5))
fmt.Println(err)
}
Output: <nil> apperr: code 13001 does not start with service prefix 12
func WithLogger ¶
WithLogger installs a logging sink invoked by PresentContext. A nil Logger is ignored, leaving the no-op default in place.
func WithMessageTemplate ¶
WithMessageTemplate overrides the sanitized client message. tmpl is a fmt-style template that receives the code (include a %d), e.g. "Something went wrong (ref %d)". The default is "Code %d: Internal Error".
func WithRecorder ¶
WithRecorder installs a tracing sink invoked by PresentContext. A nil Recorder is ignored, leaving the no-op default in place.
func WithService ¶
WithService validates that every registered code starts with the decimal digits of prefix. It expresses the "each service owns a code prefix" convention: an app claims a prefix so any code it emits is attributable to it at a glance.
A one-digit prefix behaves as it always has: WithService(1) accepts any code whose first digit is 1 (1, 12, 1001, ...). A longer prefix works the same way on more digits, so WithService(12) accepts 12001 and rejects 1001 and 13001. The sign of a code is ignored. Pair it with WithCodeDigits to pin every code to one fixed-width range derived from the prefix length.
type Recorder ¶
Recorder is the neutral tracing sink the observability-aware present path calls. An implementation records the resolved code (and, if it wants, the error) on the active span or whatever backend it wraps. This package ships only a no-op; a real Recorder is a few lines of the consumer's own code over their tracer of choice (OpenTelemetry, etc.) -- see the examples.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry is the consumer's own set of codes plus the presentation and observability policy around them. Build one at startup with NewRegistry and share it; it is read-only afterward and safe for concurrent use.
func NewRegistry ¶
NewRegistry builds a Registry from the consumer's codes and options. It fails on a duplicate code, on any code outside the service prefix when WithService is set, on any code of the wrong width when WithCodeDigits is set, and on an unknown Category value.
func (*Registry) Category ¶ added in v1.1.0
Category returns the category registered for the code carried by err. It walks the error chain the same way Code does. An uncoded error, a nil error, or a code that is not registered is CategoryInternal, so a mapper always has a safe answer.
Example (Grpc) ¶
ExampleRegistry_Category_grpc shows one shared gRPC mapper: the handler looks up the category from the coded error and turns it into a status code, with the sanitized message from Present as the status message.
package main
import (
"errors"
"fmt"
apperr "github.com/Bugs5382/go-apperr"
)
// grpcCode maps a category to a gRPC status code number. The numbers are the
// stable values from the gRPC spec (NotFound is 5, and so on), written out so
// this package never imports a transport. A real mapper would return
// codes.Code from google.golang.org/grpc/codes instead of an int.
func grpcCode(c apperr.Category) int {
switch c {
case apperr.CategoryNotFound:
return 5
case apperr.CategoryInvalid:
return 3
case apperr.CategoryUnavailable:
return 14
case apperr.CategoryPermissionDenied:
return 7
default:
return 13
}
}
func main() {
reg, err := apperr.NewRegistry([]apperr.Entry{
{Code: 1002, Title: "widget", Cause: "widget not found", Category: apperr.CategoryNotFound},
})
if err != nil {
panic(err)
}
internal := apperr.Coded(1002, errors.New("select widget: no rows"))
msg, _ := reg.Present(internal, 1000)
// In a real server: status.Error(codes.Code(grpcCode(...)), msg)
fmt.Printf("grpc code %d: %s\n", grpcCode(reg.Category(internal)), msg)
}
Output: grpc code 5: Code 1002: Internal Error
Example (Http) ¶
ExampleRegistry_Category_http shows the same idea for HTTP: one mapper from category to status, shared by every handler.
package main
import (
"errors"
"fmt"
apperr "github.com/Bugs5382/go-apperr"
)
// httpStatus maps a category to an HTTP status. A real mapper would use the
// net/http constants (http.StatusNotFound, and so on).
func httpStatus(c apperr.Category) int {
switch c {
case apperr.CategoryNotFound:
return 404
case apperr.CategoryInvalid:
return 400
case apperr.CategoryUnavailable:
return 503
case apperr.CategoryPermissionDenied:
return 403
default:
return 500
}
}
func main() {
reg, err := apperr.NewRegistry([]apperr.Entry{
{Code: 1005, Title: "auth", Cause: "caller lacks role", Category: apperr.CategoryPermissionDenied},
})
if err != nil {
panic(err)
}
internal := apperr.Coded(1005, errors.New("role check failed"))
msg, _ := reg.Present(internal, 1000)
// In a real handler: http.Error(w, msg, httpStatus(...))
fmt.Printf("http %d: %s\n", httpStatus(reg.Category(internal)), msg)
}
Output: http 403: Code 1005: Internal Error
func (*Registry) Describe ¶
Describe returns the registered Entry for code and whether it was found.
func (*Registry) Markdown ¶
Markdown renders the registry as a "Code | Area | Cause" table, sorted by code so the output is deterministic. It is meant to be written into a consumer's error-codes reference document.
Example ¶
ExampleRegistry_Markdown renders the registry as a docs table, sorted by code.
package main
import (
"fmt"
apperr "github.com/Bugs5382/go-apperr"
)
func main() {
reg, err := apperr.NewRegistry([]apperr.Entry{
{Code: 1002, Title: "upstream", Cause: "upstream timeout"},
{Code: 1001, Title: "database", Cause: "database unavailable"},
})
if err != nil {
panic(err)
}
fmt.Print(reg.Markdown())
}
Output: | Code | Area | Cause | | --- | --- | --- | | 1001 | database | database unavailable | | 1002 | upstream | upstream timeout |
func (*Registry) Message ¶
Message renders the sanitized client message for code via the template. It works for any code, registered or not, so an unexpected code still yields a safe, quotable message rather than leaking internals.
func (*Registry) Present ¶
Present resolves the code from err (the nearest coded error) or falls back to defaultCode when err carries none, and returns the sanitized client message and the resolved code. It has no side effects; use PresentContext to also drive the Recorder and Logger.
Example ¶
ExampleRegistry_Present turns an internal error into a sanitized, quotable client message and its code.
package main
import (
"errors"
"fmt"
apperr "github.com/Bugs5382/go-apperr"
)
func main() {
reg, err := apperr.NewRegistry([]apperr.Entry{
{Code: 1002, Title: "upstream", Cause: "upstream timeout"},
})
if err != nil {
panic(err)
}
msg, code := reg.Present(apperr.Coded(1002, errors.New("i/o timeout")), 1000)
fmt.Printf("%s | %d\n", msg, code)
}
Output: Code 1002: Internal Error | 1002
func (*Registry) PresentContext ¶
func (r *Registry) PresentContext(ctx context.Context, err error, defaultCode int) (clientMsg string, code int)
PresentContext is Present plus observability: after resolving the code it calls the configured Recorder and Logger with ctx, the code, and err. With the default no-op sinks it behaves exactly like Present.
Directories
¶
| Path | Synopsis |
|---|---|
|
apperrgrpc
module
|
|
|
examples
|
|
|
coded
command
Command coded shows the core primitives: wrap an internal cause with a stable code, then recover the code at a boundary while errors.Is still traverses to the original cause.
|
Command coded shows the core primitives: wrap an internal cause with a stable code, then recover the code at a boundary while errors.Is still traverses to the original cause. |
|
custom
command
Command custom shows "bring your own" observability.
|
Command custom shows "bring your own" observability. |
|
markdown
command
Command markdown renders a registry as a Markdown table, the kind you commit as an error-codes reference.
|
Command markdown renders a registry as a Markdown table, the kind you commit as an error-codes reference. |
|
registry
command
Command registry shows a consumer registering its own codes and turning internal errors into sanitized, quotable client messages.
|
Command registry shows a consumer registering its own codes and turning internal errors into sanitized, quotable client messages. |