FaultEngine — Aquilia Documentation
Comprehensive guide and documentation for FaultEngine in the Aquilia framework. View API reference, examples, and implementation patterns.
FAULTS / FAULT ENGINE FaultEngine Execution The FaultEngine orchestrates runtime error resolution. It converts raw exceptions, coordinates scoped handlers, and enforces fallback policies. Engine Processing Stages When an uncaught exception is intercepted by the framework, FaultEngine executes four sequential stages: 1. Context Capture Wraps the exception inside a FaultContext object, capturing traceback frames, timestamp offsets, request identifiers, and trace IDs. 2. Scoped Handler Lookup Searches for matching handlers in a strict topological order: Route-specific handlers → App-specific handlers → Global handlers. 3. Execution Loop Runs candidate handlers in priority order. If a handler returns Resolved(response), execution halts and the response returns. If it returns Transformed(new_fault), the engine replaces the error and restarts the resolution loop. 4. ASGI Fallback If all handlers return Escalate() or decline (raising uncaught errors), the exception escapes to the ASGI FaultMiddleware, returning a masked 500 JSON response or rendering a debug traceback page. Wiring Handlers from aquilia.faults import FaultEngine engine = FaultEngine() # 1. Register a handler globally engine.register_global(CustomGlobalHandler()) # 2. Register an app-specific handler (app name must match manifest name) engine.register_app("auth", AuthModuleHandler()) Taxonomy Fault Handlers )
Go to Homepage