Response — Aquilia Documentation
Comprehensive guide and documentation for Response in the Aquilia framework. View API reference, examples, and implementation patterns.
Core Response The Response class is the core HTTP response builder for Aquilia, designed for performance-critical streaming and flexible serialization. It supports content negotiation, block compression (Gzip/Brotli), Range requests (HTTP 206), cookie signing, and background tasks. Response Transmission Pipeline The following low-level system design diagram illustrates how outbound data is negotiated, encoded, and dispatched to the ASGI channel: Handler Yield Dict / Model / Bytes Content Negotiation JSON / XML / SURP molding Compression / Range Gzip/Brotli/Range headers ASGI Send Background Tasks run Response Faults Fault Class Fault Code Description , , , , ].map((row, i) => ( ))} Constructor Response( content: Any = b"", # Response payload (bytes, str, list/dict, iterator) status: int = 200, # HTTP status code headers: Mapping | None = None, # Key-value response headers media_type: str | None = None, # Media type override *, background: BackgroundTask | None = None, # Task to run post-transmission encoding: str = "utf-8", # Text body encoding validate_headers: bool = True, # Guard against header injection ) Factory Methods Standard Formats # JSON (optimized using orjson/ujson automatically) Response.json( , status=200) # HTML Response.html(" Welcome ", status=200) # Plain Text Response.text("OK", status=200) # Redirect Response.redirect("/new-location", status=307) Binary & Content Negotiation (SURP) Aquilia supports the SURP binary format. Response.negotiated() automatically parses quality factors from the client's Accept header to choose between SURP and JSON: # Explicit SURP Response (falls back to JSON if surp is missing) Response.surp( , status=200, compression="lz4") # Content-negotiated Response Response.negotiated( , ctx.request) Streaming & SSE # Stream raw bytes from an async generator Response.stream(async_bytes_generator(), media_type="application/octet-stream") # Server-Sent Events (SSE) Response.sse(sse_event_generator()) HLS Media Streaming Aquilia provides native helpers to serve HLS playlists (.m3u8) and MPEG-TS media segments: from aquilia.response import HLSSegment, HLSVariant # Serve HLS Media Playlist Response.hls_playlist( segments=[ HLSSegment(uri="seg1.ts", duration=4.0), HLSSegment(uri="seg2.ts", duration=3.8) ], target_duration=4 ) # Serve HLS Master Playlist Response.hls_master_playlist( variants=[ HLSVariant(uri="low/index.m3u8", bandwidth=800000, resolution="480x270"), HLSVariant(uri="high/index.m3u8", bandwidth=2400000, resolution="1280x720") ] ) Cookie Management Cookies can be signed using CookieSigner to prevent client-side tampering. # Initialize signer with key signer = CookieSigner(secret_key="secure-random-key") response = Response.text("Hello") # Set signed cookie response.set_cookie( "session_id", "value", secure=True, httponly=True, samesite="Lax", signed=True, signer=signer ) # Delete cookie response.delete_cookie("session_id") Background Tasks Background tasks execute sequentially after the response bytes have been completely flushed to the client: from aquilia.response import CallableBackgroundTask async def send_welcome_email(): await email_service.send("Welcome!") response = Response.json( ) response._background_tasks.append( CallableBackgroundTask(send_welcome_email) ) Request Data Structures )
Go to Homepage