How samber/oops works
Project type and purpose
• This is a Go library (“oops”) for structured error handling.
• It provides a fluent error‐builder API that captures context, stack traces, source fragments, assertions, and panic recovery.
• Integrations include formatters for popular loggers (logrus, zerolog, slog) and a Gin middleware for panic handling.
File structure
• Root files (builder.go, context.go, error.go, utils.go, kv.go, stacktrace.go, etc.) make up the core “oops” package.
• Subdirectories:
– loggers/logrus, loggers/zerolog – formatter implementations for two log libraries
– recovery/gin – a Gin middleware for recovering panics to oops errors
– examples/… – sample apps demonstrating usage with various loggers and panic scenarios
• Supporting files: tests, Makefile, CI workflows, assets (logo, README).
Key insights from the README
• The library wraps or builds errors via methods like .Errorf, .Wrapf, .Recover, .Assert, each returning an OopsError.
• Internally it captures a stack trace (configurable max depth), can read Go source files for fragments, and attaches metadata (code, domain, tags, timing, user/tenant info, hints, owners).
• It integrates with Go’s context.Context, and exposes custom slog/logrus/zerolog formatters.
Main components
A. Consumer Application Code
– Calls oops builder methods in business logic or HTTP handlers.
– May pass or retrieve an OopsErrorBuilder via context.Context.
B. Oops Core Package
1. Builder API – fluent methods (With, In, Code, User, .Errorf/.Wrap/.Recoverf, .Assertf, etc.)
2. Error Implementation – OopsError struct implementing error, holding context map, stack frames, source fragments, metadata fields
3. StackTrace Generator – uses runtime to capture and prune call frames
4. SourceFragment Extractor – reads Go source files based on frame file paths (if enabled)
5. Panic Recovery / Assertion Engine – wrappers for panic interception
6. Context Propagation – attach/retrieve builder via context.Context
C. Logger Integration Modules
– loggers/logrus/formatter.go
– loggers/zerolog/formatter.go
– examples for built-in log and slog
D. Third-Party / External Systems
– Gin HTTP framework (recovery middleware)
– External log sinks (console, JSON file, external services)
Relationships and data flow
1. Application logic → invokes Oops Builder API → returns OopsError
2. Builder API → requests stack trace from StackTrace Generator
3. Builder API → (optionally) reads source fragments via SourceFragment Extractor
4. Application → logs the OopsError → passes it to a logger integration module
5. Logger integration → extracts error fields via ToMap/Format/LogValuer → emits JSON or structured log
6. HTTP handler wraps business logic → uses Gin Recovery Middleware → automatically converts panics into OopsError
Architectural patterns & design principles
• Fluent/builder pattern for error composition
• Separation of concerns: core error builder vs. logging formatters vs. HTTP middleware vs. examples
• Lazy evaluation of context attributes (functions)
• Strict SemVer and zero external dependencies