Engine — Aquilia Documentation
Comprehensive guide and documentation for Engine in the Aquilia framework. View API reference, examples, and implementation patterns.
Sessions / Engine SessionEngine The SessionEngine orchestrates the entire session lifecycle, running a deterministic 7-phase execution pipeline, validating timeouts, enforcing concurrency, and broadcasting events. Creating the Engine The engine binds a policy, a storage backend, and a transport adapter together. It is typically registered as a singleton in the dependency injection container. from aquilia.sessions import ( SessionEngine, SessionPolicyBuilder, MemoryStore, CookieTransport ) # 1. Build a policy policy = ( SessionPolicyBuilder() .web_defaults() # Setup web defaults first .lasting(hours=2) # Customize values afterward .build() ) # 2. Setup store and transport store = MemoryStore.web_optimized() transport = CookieTransport.for_web_browsers() # 3. Instantiate the engine engine = SessionEngine( policy=policy, store=store, transport=transport, ) The 7-Phase Lifecycle Every request is resolved and committed through a structured, multi-phase pipeline in the session middleware: , , , , , , , ].map((item, i) => ( Phase : ))} Core Lifecycle APIs resolve() Resolves a session from the request context. This executes phases 1–4 of the lifecycle. session = await engine.resolve(request, container) commit() Runs ID rotation, checks concurrency limits, and persists modifications. This executes phases 6–7. await engine.commit(session, response, privilege_changed=True) destroy() Wipes the session from store and deletes the cookie/header references. await engine.destroy(session, response) Concurrency Control The engine queries active sessions from the store to check concurrency constraints. This check is executed before the session is saved during commit. await engine.check_concurrency(session) # Governed by policy concurrency configurations: # - ConcurrencyPolicy.behavior_on_limit = "reject" # Raises SessionConcurrencyViolationFault # - ConcurrencyPolicy.behavior_on_limit = "evict_oldest" # Automatically deletes oldest session # - ConcurrencyPolicy.behavior_on_limit = "evict_all" # Deletes all other active sessions for user Observability & Event Hooking Observe session state changes by registering a callable event handler. The engine broadcasts events for loading, timeout, hijacking, rotation, and destruction: def my_observability_observer(event_data: dict): print(f"Session Event: (Policy= )") engine.on_event(my_observability_observer) # Sample event payload: # , # "request_path": "/auth/refresh", # "request_method": "POST", # "client_ip": "127.0.0.1" # } )
Go to Homepage