Transport — Aquilia Documentation
Comprehensive guide and documentation for Transport in the Aquilia framework. View API reference, examples, and implementation patterns.
Sessions / Transport Session Transport Transport layers manage how session identifiers travel over HTTP requests and responses. They isolate network details from session state using the SessionTransport protocol. SessionTransport Protocol All transport adapters implement the synchronous SessionTransport protocol: from typing import Protocol from aquilia.request import Request from aquilia.response import Response from aquilia.sessions import Session class SessionTransport(Protocol): """Protocol for session ID transport mechanisms (synchronous methods).""" def extract(self, request: Request) -> str | None: """Extract a session ID string from the incoming request.""" ... def inject(self, response: Response, session: Session) -> None: """Inject the session ID into the outgoing response.""" ... def clear(self, response: Response) -> None: """Remove the session ID from the outgoing response (on logout/destroy).""" ... CookieTransport (HTTP Cookies) Sends the session ID as an HTTP cookie. Highly recommended for web browsers as it provides HttpOnly (XSS block), Secure (HTTPS enforce), and SameSite (CSRF block) security parameters via CookieTransport . from aquilia.sessions import CookieTransport, TransportPolicy # Constructor accepts a TransportPolicy policy = TransportPolicy( adapter="cookie", cookie_name="aquilia_web_session", cookie_httponly=True, cookie_secure=True, cookie_samesite="strict", cookie_path="/", ) transport = CookieTransport(policy) # Factory methods for pre-configured defaults: transport_web = CookieTransport.for_web_browsers() transport_spa = CookieTransport.for_spa_applications() transport_mobile = CookieTransport.for_mobile_webviews() transport_default = CookieTransport.with_aquilia_defaults() HeaderTransport (Custom Headers) Transports the session ID using custom headers. Best suited for stateless REST APIs, mobile apps, or inter-service communications where cookies are difficult to handle, implemented via HeaderTransport . from aquilia.sessions import HeaderTransport, TransportPolicy # Constructor accepts a TransportPolicy policy = TransportPolicy(adapter="header", header_name="X-Session-ID") transport = HeaderTransport(policy) # Factory methods for pre-configured defaults: transport_rest = HeaderTransport.for_rest_apis() transport_graphql = HeaderTransport.for_graphql_apis() transport_mobile = HeaderTransport.for_mobile_apis() transport_service = HeaderTransport.for_microservices() transport_default = HeaderTransport.with_aquilia_defaults() create_transport() Factory Helper utility function to initialize transport adapters directly from policy configurations: from aquilia.sessions import create_transport, TransportPolicy policy = TransportPolicy(adapter="cookie", cookie_name="my_custom_cookie") transport = create_transport(policy) Building a Custom Transport Create custom transport layers (for example, reading token properties from custom JSON payloads or Authorization headers) by matching the protocol: from aquilia.request import Request from aquilia.response import Response from aquilia.sessions import Session class BearerTokenTransport: """Custom transport for extracting session IDs from the Authorization Bearer header.""" def extract(self, request: Request) -> str | None: auth = request.header("authorization") or "" if auth.startswith("Bearer "): return auth[7:] return None def inject(self, response: Response, session: Session) -> None: response.headers["Authorization"] = f"Bearer " def clear(self, response: Response) -> None: if "Authorization" in response.headers: del response.headers["Authorization"] )
Go to Homepage