errors
Package errors provides structured error handling for the Drift framework.
func CaptureStack
func CaptureStack() string
CaptureStack returns the current call stack as a string. It skips the first few frames to exclude the CaptureStack call itself.
func Recover
func Recover(op string)
Recover is a helper for deferred panic recovery. Usage: defer errors.Recover("operation.name")
func RecoverWithCallback
func RecoverWithCallback(op string, callback func(r any))
RecoverWithCallback is like Recover but also calls the provided callback with the panic value after reporting it.
func Report
func Report(err *DriftError)
Report sends an error to the global handler. If err.Timestamp is zero, it is set to the current time.
func ReportBoundaryError
func ReportBoundaryError(err *BoundaryError)
ReportBoundaryError sends a boundary error to the global handler. This is called automatically when an [ErrorBoundary] catches a panic, or when the engine's global panic recovery captures an error. Use this to report errors to your logging/analytics infrastructure by implementing a custom ErrorHandler.
func ReportPanic
func ReportPanic(err *PanicError)
ReportPanic sends a panic error to the global handler.
func SetHandler
func SetHandler(h ErrorHandler)
SetHandler configures the global error handler. Pass nil to restore the default LogHandler.
type BoundaryError
BoundaryError represents a failure caught by an ErrorBoundary or the global panic recovery in the engine. This is a unified error type that covers all phases.
Possible Phase values:
- "build": panic during widget Build()
- "layout": panic during RenderObject layout
- "paint": panic during RenderObject paint
- "hittest": panic during hit testing
- "frame": panic during frame processing (dispatch callbacks, animations, etc.)
- "pointer": panic during pointer/gesture event handling
type BoundaryError struct {
// Phase is the phase where the error occurred.
Phase string
// Widget is the type name of the widget that failed (for build errors).
Widget string
// RenderObject is the type name of the render object that failed (for layout/paint/hittest errors).
RenderObject string
// IsLayoutIssue indicates this is a developer layout mistake, not a crash.
IsLayoutIssue bool
// Recovered is the panic value (nil for regular errors).
Recovered any
// Err is the underlying error (nil for panics).
Err error
// StackTrace contains the call stack at the time of the error.
StackTrace string
// Timestamp is when the error occurred.
Timestamp time.Time
}
func (*BoundaryError) Error
func (e *BoundaryError) Error() string
func (*BoundaryError) Unwrap
func (e *BoundaryError) Unwrap() error
type DriftError
DriftError represents a structured error in the Drift framework.
type DriftError struct {
// Op is the operation that failed (e.g., "graphics.DefaultFontManager").
Op string
// Kind categorizes the error.
Kind ErrorKind
// Err is the underlying error.
Err error
// Channel is the platform channel name, if applicable.
Channel string
// StackTrace contains the call stack at the time of the error.
StackTrace string
// Timestamp is when the error occurred.
Timestamp time.Time
}
func (*DriftError) Error
func (e *DriftError) Error() string
func (*DriftError) Unwrap
func (e *DriftError) Unwrap() error
type ErrorHandler
ErrorHandler receives errors reported by the Drift framework.
type ErrorHandler interface {
// HandleError is called when an error occurs.
HandleError(err *DriftError)
// HandlePanic is called when a panic is recovered.
HandlePanic(err *PanicError)
// HandleBoundaryError is called when an ErrorBoundary catches an error
// or a panic is caught by global recovery.
HandleBoundaryError(err *BoundaryError)
}
var (
// DefaultHandler is the global error handler.
// It defaults to LogHandler with verbose=false.
DefaultHandler ErrorHandler = &LogHandler{}
)
type ErrorKind
ErrorKind identifies the category of an error.
type ErrorKind int
const (
// KindUnknown indicates an error of unknown type.
KindUnknown ErrorKind = iota
// KindPlatform indicates a platform channel or native bridge error.
KindPlatform
// KindParsing indicates an event parsing failure.
KindParsing
// KindInit indicates an initialization error.
KindInit
// KindRender indicates a rendering error.
KindRender
// KindPanic indicates a recovered panic.
KindPanic
// KindBuild indicates a build-time widget error.
KindBuild
)
func (ErrorKind) String
func (k ErrorKind) String() string
type LayoutIssue
LayoutIssue is a panic value used for constraint violations and other developer-facing layout mistakes. Recovery code detects this type and presents a calmer "layout issue" screen instead of a crash error.
type LayoutIssue struct {
Message string
}
func (LayoutIssue) Error
func (e LayoutIssue) Error() string
type LogHandler
LogHandler is an ErrorHandler that logs errors to stderr.
type LogHandler struct {
// Verbose enables detailed output including stack traces.
Verbose bool
}
func (*LogHandler) HandleBoundaryError
func (h *LogHandler) HandleBoundaryError(err *BoundaryError)
HandleBoundaryError logs a BoundaryError to stderr.
func (*LogHandler) HandleError
func (h *LogHandler) HandleError(err *DriftError)
HandleError logs a DriftError to stderr.
func (*LogHandler) HandlePanic
func (h *LogHandler) HandlePanic(err *PanicError)
HandlePanic logs a PanicError to stderr.
type PanicError
PanicError represents a recovered panic.
type PanicError struct {
// Op is the operation that panicked (e.g., "engine.HandlePointer").
Op string
// Value is the value passed to panic().
Value any
// StackTrace contains the call stack at the time of the panic.
StackTrace string
// Timestamp is when the panic occurred.
Timestamp time.Time
}
func (*PanicError) Error
func (e *PanicError) Error() string
type ParseError
ParseError represents a failure to parse event data.
type ParseError struct {
// Channel is the platform channel that received the event.
Channel string
// DataType is the expected type name.
DataType string
// Got is the actual data received.
Got any
}
func (*ParseError) Error
func (e *ParseError) Error() string
Generated by gomarkdoc