Overview — Aquilia Documentation
Comprehensive guide and documentation for Overview in the Aquilia framework. View API reference, examples, and implementation patterns.
function SessionArchitecture() = useTheme() const isDark = theme === 'dark' return ( DETECTION Cookie/Header extraction RESOLUTION Store lookup by ID VERIFICATION TTL & Fingerprint checks DI BINDING Register request-scope MUTATION Route logic & Dirty flag COMMIT ID rotate & Save store ) } Security / Sessions / Overview Session System Aquilia provides an explicit, policy-driven session subsystem featuring cryptographically secure identifiers, pluggable storage backends, transport-agnostic delivery, and deep integration with the Dependency Injection (DI) system. Architecture Components The session subsystem consists of multiple decoupled interfaces working together to manage server-side user state: , , , , , , , , ].map((item, i) => ( ))} Core Data Primitives SessionID A SessionID does not encode any identity or timestamps (preventing info leaks). It has 256 bits of entropy and is encoded into a URL-safe Base64 string: from aquilia.sessions import SessionID # Generate a new cryptographic session ID sid = SessionID() print(str(sid)) # sess_A1b2C3d4E5f6G7h8... print(len(str(sid))) # 49 characters (5 prefix + 44 base64) # Reconstruct from string (enforces length & structure guards) sid2 = SessionID.from_string("sess_A1b2C3d4E5f6G7h8...") Session Object The Session is a dataclass storing session data. It uses custom dictionary tracking to detect when nested properties change, automatically flagging the session as dirty for persistence. from datetime import timedelta from aquilia.sessions import Session, SessionID, SessionScope, SessionFlag, SessionPrincipal # Session stores user-specific state session = Session( id=SessionID(), data= , scope=SessionScope.USER, flags= , ) # Dict-like access (triggers dirty tracking automatically) session["theme"] = "light" session["cart"].append( ) # Lifecycle checking session.touch() session.extend_expiry(ttl=timedelta(minutes=30)) print(session.is_expired()) # False # Bind principal identity (for audits and concurrency) principal = SessionPrincipal(kind="user", id="user_99", attributes= ) session.mark_authenticated(principal) print(session.is_dirty) # True (marks dirty on principal change or data mutation) Lifetimes & Boundaries SessionScope SessionScope defines the lifecycle and persistence rules. Ephemeral scopes reside in memory and do not write to persistent stores. Scope Requires Persistence Description ))} SessionFlag Flags provide fine-grained status indicators used by components to toggle locking, expiration rotation, and read-only status. Flag Behavior & Purpose ))} Quick Start Setup To enable sessions, register the session integration and declare policies on your Workspace builder in workspace.py: from datetime import timedelta from aquilia import Workspace from aquilia.sessions import SessionPolicy, PersistencePolicy, ConcurrencyPolicy, TransportPolicy # Configure the workspace with custom session policies workspace = ( Workspace("my-app") .sessions( policies=[ SessionPolicy( name="default", ttl=timedelta(days=7), idle_timeout=timedelta(hours=1), absolute_timeout=timedelta(days=30), rotate_on_use=False, rotate_on_privilege_change=True, fingerprint_binding=False, scope="user", persistence=PersistencePolicy( enabled=True, store_name="default", write_through=True, compress=False, ), concurrency=ConcurrencyPolicy( max_sessions_per_principal=5, behavior_on_limit="evict_oldest", ), transport=TransportPolicy( cookie_name="workspace_session", cookie_secure=False, cookie_httponly=True, cookie_samesite="lax", ), ), ], ) .build() ) Inject and require sessions inside your controllers using decorators: from aquilia import Controller, Get, Post from aquilia.sessions import session, Session class ShoppingController(Controller): prefix = "/shop" @Get("/cart") @session.require() async def view_cart(self, ctx, session: Session): """Require an existing session.""" return ctx.json( ) @Post("/cart") @session.ensure() async def add_item(self, ctx, session: Session): """Creates session if missing, then writes item.""" body = await ctx.request.json() cart = session.get("cart", []) cart.append(body) session["cart"] = cart # Triggers dirty state return ctx.json( ) )
Go to Homepage