Request

HTTP request handling and utilities.

Transport-agnostic request system.

This module provides the complete request handling infrastructure: - BaseRequest: Abstract interface for all request types - HttpRequest: ASGI HTTP request adapter - MsgRequest: Message-based request adapter (WSX over WebSocket, NATS) - RequestRegistry: Factory and tracking for active requests

Architecture:

BaseRequest (ABC)

├── HttpRequest # ASGI HTTP scope └── MsgRequest # WSX message (WebSocket, NATS)

Every request: 1. Gets a unique id (correlation ID) 2. Is registered in RequestRegistry 3. Has app_name for per-app metrics 4. Has created_at for age tracking 5. Is unregistered on completion

Example

registry = RequestRegistry() request = await registry.create(scope, receive, send) try:

result = await handler(request)

finally:

registry.unregister(request.id)

class genro_asgi.request.BaseRequest

Bases: ABC

Abstract base class for transport-agnostic requests.

All request implementations (HTTP, Message-based) must implement this interface, allowing handlers to work uniformly across transports.

Properties:

id: Server-generated correlation ID (internal) external_id: Client-provided ID for correlation (optional) method: HTTP method (GET, POST, PUT, DELETE, PATCH) path: Request path (e.g., ‘/users/42’) headers: Request headers as dict cookies: Request cookies as dict query: Query parameters data: Request body/payload transport: Transport type (‘http’, ‘websocket’, ‘nats’) app_name: Name of the app handling this request (for metrics) created_at: Timestamp when request was created (for age tracking) tytx_mode: True if request uses TYTX serialization tytx_transport: TYTX transport type (‘json’, ‘msgpack’) or None

property age: float

Seconds since request was created.

property app_name: str | None

Name of the app handling this request (set after routing).

property auth_tags: list[str]

Auth tags (set from scope during init by AuthMiddleware).

abstract property cookies: dict[str, str]

Request cookies.

property created_at: float

Timestamp when request was created.

abstract property data: Any

Request body/payload.

property env_capabilities: list[str]

Environment capabilities (set from scope during init).

property external_id: str | None

Client-provided ID for correlation (e.g., WSX message id).

abstract property headers: dict[str, str]

Request headers (lowercase keys).

abstract property id: str

Correlation ID for request/response matching.

abstractmethod async init(scope, receive, send=None, **kwargs)

Async initialization - subclasses must override.

Return type:

None

abstract property method: str

GET, POST, PUT, DELETE, PATCH.

Type:

HTTP method

abstract property path: str

Request path (e.g., ‘/users/42’).

abstract property query: dict[str, Any]

Query parameters.

response: Response

abstract property transport: str

‘http’, ‘websocket’, ‘nats’.

Type:

Transport type

property tytx_mode: bool

True if request uses TYTX serialization.

property tytx_transport: str | None

TYTX transport type (‘json’, ‘msgpack’) or None.

class genro_asgi.request.HttpRequest

Bases: BaseRequest

HTTP request adapter wrapping ASGI scope.

property body: bytes

Raw body bytes.

property client: Address | None

Client address (host, port) if available.

property content_type: str | None

Content-Type header value.

property cookies: dict[str, str]

Request cookies.

property data: Any

Request body/payload.

property headers: dict[str, str]

Request headers (lowercase keys).

property headers_obj: Headers

Request headers as Headers object (case-insensitive).

property id: str

Correlation ID for request/response matching.

async init(scope, receive, send=None, **kwargs)

Async initialization - reads body and parses request data.

Return type:

None

property method: str

GET, POST, PUT, DELETE, PATCH.

Type:

HTTP method

property path: str

Request path (e.g., ‘/users/42’).

property query: dict[str, Any]

Query parameters.

property query_params: QueryParams

Query string parameters as QueryParams object.

property scheme: str

http or https.

Type:

URL scheme

property scope: MutableMapping[str, Any]

Raw ASGI scope dict.

property state: State

Request-scoped state container.

property transport: str

‘http’, ‘websocket’, ‘nats’.

Type:

Transport type

property url: URL

Full request URL.

class genro_asgi.request.MsgRequest

Bases: BaseRequest

Message-based request adapter (WSX over WebSocket, NATS, etc.).

Parses WSX:// formatted messages into BaseRequest interface. Transport-agnostic: works with any message-based protocol.

property client: tuple[str, int] | None

Client address as (host, port) tuple.

property cookies: dict[str, str]

Request cookies.

property data: Any

Request body/payload.

property headers: dict[str, str]

Request headers (lowercase keys).

property id: str

Correlation ID for request/response matching.

async init(scope, receive, send=None, **kwargs)

Async initialization - parses WSX message.

Return type:

None

property method: str

GET, POST, PUT, DELETE, PATCH.

Type:

HTTP method

property path: str

Request path (e.g., ‘/users/42’).

property query: dict[str, Any]

Query parameters.

property scope: MutableMapping[str, Any]

Access to raw ASGI scope.

property transport: str

‘http’, ‘websocket’, ‘nats’.

Type:

Transport type

property websocket: WebSocket | None

Access to underlying WebSocket connection (if available).

class genro_asgi.request.RequestRegistry(factories=None)

Bases: object

Registry for creating and tracking active requests.

Responsibilities: - Creates appropriate request based on scope[“type”] using factories dict - Calls async init() on the created request - Tracks active requests for monitoring and metrics - Provides iteration and lookup by request ID

Example

registry = RequestRegistry() request = await registry.create(scope, receive, send) print(f”Active: {len(registry)}”) registry.unregister()

count_by_app(app_name)

Count active requests for a specific app.

Return type:

int

async create(scope, receive, send=None, **kwargs)

Create and register a request from ASGI scope.

Return type:

BaseRequest

property current: BaseRequest | None

Current request from ContextVar.

factories

get(request_id)

Get a request by id.

Return type:

BaseRequest | None

register_factory(scope_type, factory)

Register a factory for a scope type.

Return type:

None

unregister()

Unregister current request.

Return type:

BaseRequest | None

genro_asgi.request.get_current_request()

Get the current request from context. Returns None if not in request context.

Return type:

BaseRequest | None

genro_asgi.request.set_current_request(request)

Set the current request in context. Returns token for reset.

Return type:

Any