Faults — Aquilia Documentation
Comprehensive guide and documentation for Faults in the Aquilia framework. View API reference, examples, and implementation patterns.
Sessions / Faults Session Faults All session errors are structured faults belonging to the SECURITY domain. They provide precise status codes, severity indicators, and privacy-safe parameters. SessionFault Hierarchy SessionFault (base class) ├── SessionExpiredFault # Session TTL duration has expired ├── SessionIdleTimeoutFault # Session inactive too long ├── SessionAbsoluteTimeoutFault # Absolute total session lifetime reached ├── SessionInvalidFault # Session ID is malformed or invalid ├── SessionNotFoundFault # Session ID not found in storage ├── SessionPolicyViolationFault # Custom policy/guard check failed ├── SessionConcurrencyViolationFault # Max concurrent sessions exceeded ├── SessionLockedFault # Session is locked in transaction ├── SessionStoreUnavailableFault # Persistent store is unreachable ├── SessionStoreCorruptedFault # Session data is corrupted ├── SessionRotationFailedFault # Session ID rotation failed ├── SessionTransportFault # HTTP transport extraction error ├── SessionForgeryAttemptFault # Malformed/traversing ID token format └── SessionHijackAttemptFault # Fingerprint mismatch (IP/UA mismatch) Fault Registry Reference The session subsystem throws these structured faults. Each has a specific default HTTP code, severity, and retryable flag: , , , , , , , , , , , , , , ].map((item, i) => ( : } HTTP ))} Handling Session Faults Register fault handlers using the @fault_handler decorator. Important: Exception objects do not store a reference to the Session object. Use the request context (ctx.session) to fetch session details inside handlers. from aquilia.faults import fault_handler from aquilia.sessions.faults import ( SessionFault, SessionExpiredFault, SessionHijackAttemptFault, SessionStoreUnavailableFault, ) # Catch generic session faults @fault_handler(SessionFault) async def handle_session_fault(ctx, fault): return ctx.json( , status=fault.http_status) # Catch specific fault (graceful redirect) @fault_handler(SessionExpiredFault) async def handle_expired(ctx, fault): return ctx.redirect("/login?reason=expired") # Catch security hijacking fault (terminate user sessions) @fault_handler(SessionHijackAttemptFault) async def handle_hijack(ctx, fault): # Retrieve active session from RequestCtx (fault has no .session property) session = ctx.session if session and session.principal: # Delete user sessions to mitigate attack active_sessions = await ctx.store.list_by_principal(session.principal.id) for s in active_sessions: await ctx.store.delete(s.id) return ctx.json( , status=403) Fault Properties Session faults expose standardized diagnostic attributes. Session IDs are automatically hashed to prevent leaking secret keys in server logging trails: from aquilia.sessions.faults import SessionExpiredFault fault = SessionExpiredFault(session_id="sess_ABC123...") # Inherited from Fault: print(fault.message) # "Session has expired" print(fault.domain) # FaultDomain.SECURITY print(fault.severity) # Severity.WARN print(fault.public) # True (safe to return to browser) print(fault.retryable) # False print(fault.http_status) # 401 # Session-specific properties: print(fault.session_id_hash) # Hashed ID: "sha256:f124c..." (for safe logging) )
Go to Homepage