kiba-core 0.5.3.dev61__tar.gz → 0.5.3.dev63__tar.gz

{kiba_core-0.5.3.dev61 → kiba_core-0.5.3.dev63}/CHANGELOG.md

@@ -8,6 +8,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ## [Unreleased]
 
 ### Added
+- [MAJOR] Reworked `route` to compose JSON or streaming transport, application-resolved authorization, and rate limiting
+- [MAJOR] Replaced authorization-decorator sequences with named `RouteAuthResolver` policies
+- [MINOR] Added `authJwt`, `authBasic`, and `originIp` to `KibaApiRequest`
+- [MAJOR] Replaced global request-context accessors with injectable `RequestContextHolder` and `RequestContextMiddleware`
+- [MINOR] Added `RateLimitConfig` for rate-limit windows and request keying
+- [MINOR] Updated `json_route` and `streaming_json_route` to only parse and serialize requests and responses
+- [MINOR] Added OpenAPI tag ordering, `OpenApiSecurityScheme` declarations, and route security metadata
+- [MINOR] Added OpenAPI security-scheme publishing to authorization decorators
+- [MINOR] Added `authorize_token_request` and `authorize_static_token_request` for token validation
 - [MAJOR] Replace `httpx` with `httpx2` for HTTP requests
 - [MINOR] Use `json_util`/`orjson` for API and database JSON serialization
 - [MINOR] Use Pydantic `JsonValue` for JSON type aliases

{kiba_core-0.5.3.dev61 → kiba_core-0.5.3.dev63}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kiba-core
-Version: 0.5.3.dev61
+Version: 0.5.3.dev63
 Summary: Kiba Labs' python utilities
 Project-URL: repository, https://github.com/kibalabs/core-py
 Requires-Python: <4,>=3.12

{kiba_core-0.5.3.dev61 → kiba_core-0.5.3.dev63}/core/api/api_request.py

@@ -9,3 +9,4 @@ class KibaApiRequest[ApiRequestDataType: BaseModel](Request):
     data: ApiRequestDataType
     authJwt: Jwt | None = None
     authBasic: BasicAuthentication | None = None
+    originIp: str | None = None

{kiba_core-0.5.3.dev61 → kiba_core-0.5.3.dev63}/core/api/authorizer.py

@@ -7,6 +7,8 @@ from pydantic import BaseModel
 
 from core import logging
 from core.api.api_request import KibaApiRequest
+from core.api.route_metadata import OpenApiSecurityScheme
+from core.api.route_metadata import update_route_metadata
 from core.exceptions import ForbiddenException
 from core.exceptions import UnauthorizedException
 from core.http.basic_authentication import BasicAuthentication
@@ -41,8 +43,13 @@ async def _authorize_bearer_jwt[ApiRequest: BaseModel](request: KibaApiRequest[A
 
 def authorize_bearer_jwt[ApiRequest: BaseModel](  # type: ignore[explicit-any]
     authorizer: Authorizer,
+    *,
+    securityScheme: OpenApiSecurityScheme | None = None,
 ) -> typing.Callable[[typing.Callable[[KibaApiRequest[ApiRequest]], _AnyReturn]], typing.Callable[[KibaApiRequest[ApiRequest]], typing.Any]]:
     def decorator(func: typing.Callable[[KibaApiRequest[ApiRequest]], _AnyReturn]) -> typing.Callable[[KibaApiRequest[ApiRequest]], typing.Any]:  # type: ignore[explicit-any]
+        if securityScheme is not None:
+            update_route_metadata(func, {'security': [{securityScheme.name: []}]})
+
         @functools.wraps(func)
         async def async_wrapper(request: KibaApiRequest[ApiRequest]) -> typing.Any:  # type: ignore[explicit-any, misc]
             request.authJwt = await _authorize_bearer_jwt(request=request, authorizer=authorizer)
@@ -76,8 +83,13 @@ async def get_basic_authentication_from_authorization_signature[ApiRequest: Base
 
 def authorize_signature[ApiRequest: BaseModel](  # type: ignore[explicit-any]
     authorizer: SignatureAuthorizer,
+    *,
+    securityScheme: OpenApiSecurityScheme | None = None,
 ) -> typing.Callable[[typing.Callable[[KibaApiRequest[ApiRequest]], _AnyReturn]], typing.Callable[[KibaApiRequest[ApiRequest]], typing.Any]]:
     def decorator(func: typing.Callable[[KibaApiRequest[ApiRequest]], _AnyReturn]) -> typing.Callable[[KibaApiRequest[ApiRequest]], typing.Any]:  # type: ignore[explicit-any]
+        if securityScheme is not None:
+            update_route_metadata(func, {'security': [{securityScheme.name: []}]})
+
         @functools.wraps(func)
         async def async_wrapper(request: KibaApiRequest[ApiRequest]) -> typing.Any:  # type: ignore[explicit-any, misc]
             request.authBasic = await get_basic_authentication_from_authorization_signature(request=request, authorizer=authorizer)
@@ -106,18 +118,48 @@ class StaticTokenAuthorizer(TokenAuthorizer):
             raise ForbiddenException(message='AUTH_INVALID')
 
 
+async def authorize_token_request[ApiRequest: BaseModel](request: KibaApiRequest[ApiRequest], authorizer: TokenAuthorizer) -> None:
+    authorization = request.headers.get('Authorization')
+    if not authorization:
+        raise ForbiddenException(message='AUTH_NOT_PROVIDED')
+    if not authorization.startswith('Token '):
+        raise ForbiddenException(message='AUTH_INVALID')
+    await authorizer.validate_token(authorization[6:])
+
+
+async def authorize_static_token_request[ApiRequest: BaseModel](request: KibaApiRequest[ApiRequest], token: str) -> None:
+    authorization = request.headers.get('Authorization')
+    if not authorization:
+        raise ForbiddenException(message='AUTH_NOT_PROVIDED')
+    if not authorization.startswith('Token ') or not hmac.compare_digest(authorization[6:], token):
+        raise ForbiddenException(message='AUTH_INVALID')
+
+
+async def authorize_static_header_request[ApiRequest: BaseModel](
+    request: KibaApiRequest[ApiRequest],
+    *,
+    headerName: str,
+    token: str,
+) -> None:
+    providedToken = request.headers.get(headerName)
+    if providedToken is None:
+        raise ForbiddenException(message='AUTH_NOT_PROVIDED')
+    if not hmac.compare_digest(providedToken, token):
+        raise ForbiddenException(message='AUTH_INVALID')
+
+
 def authorize_token[ApiRequest: BaseModel](  # type: ignore[explicit-any]
     authorizer: TokenAuthorizer,
+    *,
+    securityScheme: OpenApiSecurityScheme | None = None,
 ) -> typing.Callable[[typing.Callable[[KibaApiRequest[ApiRequest]], _AnyReturn]], typing.Callable[[KibaApiRequest[ApiRequest]], typing.Any]]:
     def decorator(func: typing.Callable[[KibaApiRequest[ApiRequest]], _AnyReturn]) -> typing.Callable[[KibaApiRequest[ApiRequest]], typing.Any]:  # type: ignore[explicit-any]
+        if securityScheme is not None:
+            update_route_metadata(func, {'security': [{securityScheme.name: []}]})
+
         @functools.wraps(func)
         async def async_wrapper(request: KibaApiRequest[ApiRequest]) -> typing.Any:  # type: ignore[explicit-any, misc]
-            authorization = request.headers.get('Authorization')
-            if not authorization:
-                raise ForbiddenException(message='AUTH_NOT_PROVIDED')
-            if not authorization.startswith('Token '):
-                raise ForbiddenException(message='AUTH_INVALID')
-            await authorizer.validate_token(authorization[6:])
+            await authorize_token_request(request=request, authorizer=authorizer)
             result = func(request)
             # NOTE(krishan711): this is here to support streaming responses which return an async generator
             if hasattr(result, '__aiter__'):

{kiba_core-0.5.3.dev61 → kiba_core-0.5.3.dev63}/core/api/json_route.py

@@ -37,6 +37,7 @@ def json_route[ApiRequest: BaseModel, ApiResponse: BaseModel](
                 validationErrorMessage = ', '.join([f'{".".join([str(value) for value in error["loc"]])}: {error["msg"]}' for error in exception.errors()])
                 raise BadRequestException(f'Invalid request: {validationErrorMessage}')
             kibaRequest: KibaApiRequest[ApiRequest] = KibaApiRequest(scope=receivedRequest.scope, receive=receivedRequest._receive, send=receivedRequest._send)  # noqa: SLF001
+            kibaRequest.originIp = typing.cast('str | None', receivedRequest.scope.get('originIp'))
             kibaRequest.data = requestParams
             receivedResponse = await func(kibaRequest)
             if not isinstance(receivedResponse, responseType):

kiba_core-0.5.3.dev63/core/api/middleware/origin_ip_middleware.py

@@ -0,0 +1,36 @@
+from collections.abc import Sequence
+
+from starlette.datastructures import Headers
+from starlette.types import ASGIApp
+from starlette.types import Receive
+from starlette.types import Scope
+from starlette.types import Send
+
+from core import logging
+
+
+def _extract_origin_ip(scope: Scope, trustedProxyHeaders: Sequence[str]) -> str | None:
+    headers = Headers(scope=scope)
+    for headerName in trustedProxyHeaders:
+        headerValue = headers.get(headerName)
+        if headerValue:
+            return headerValue.split(',')[0].strip()
+    client = scope.get('client')
+    if client:
+        return str(client[0])
+    return None
+
+
+class OriginIpMiddleware:
+    def __init__(self, app: ASGIApp, trustedProxyHeaders: Sequence[str] = ()) -> None:
+        self.app = app
+        self.trustedProxyHeaders = trustedProxyHeaders
+        if trustedProxyHeaders:
+            logging.info(f'OriginIpMiddleware trusting proxy headers for client IP: {", ".join(trustedProxyHeaders)}. This may be spoofable if requests can reach this service directly.')
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope['type'] != 'http':
+            await self.app(scope, receive, send)
+            return
+        scope['originIp'] = _extract_origin_ip(scope=scope, trustedProxyHeaders=self.trustedProxyHeaders)
+        await self.app(scope, receive, send)

kiba_core-0.5.3.dev63/core/api/openapi.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from collections.abc import Mapping
+from collections.abc import Sequence
+from typing import Protocol
+from typing import cast
+
+from pydantic import BaseModel
+from starlette.requests import Request
+from starlette.routing import BaseRoute
+from starlette.schemas import EndpointInfo
+from starlette.schemas import SchemaGenerator
+
+from core.api.api_response import KibaJSONResponse
+from core.api.route_metadata import OpenApiSecurityScheme
+from core.api.route_metadata import RouteMetadata
+from core.api.route_metadata import get_route_metadata
+
+_PATH_PARAMETER_PATTERN = re.compile(r'{([A-Za-z0-9_]+)(?::[^}]+)?}')
+_RATE_LIMIT_WINDOW_LABELS: dict[str, str] = {
+    'perMinute': 'minute',
+    'perFiveMinutes': '5 minutes',
+    'perHour': 'hour',
+    'perDay': 'day',
+}
+
+
+class OpenApiTag(BaseModel):
+    name: str
+    description: str | None = None
+
+
+class OpenApiExtension(Protocol):
+    def update_document(self, document: dict[str, object]) -> None: ...
+
+    def update_operation(self, *, route: EndpointInfo, metadata: RouteMetadata, operation: dict[str, object]) -> None: ...
+
+
+def _format_rate_limit_text(rateLimit: Mapping[str, int]) -> str:
+    parts = [f'{rateLimit[key]} requests/{label}' for key, label in _RATE_LIMIT_WINDOW_LABELS.items() if key in rateLimit]
+    return f'Rate limited to {", ".join(parts)}.'
+
+
+def _schema_reference(model: type[BaseModel], schemas: dict[str, object]) -> dict[str, str]:
+    modelSchema = cast(dict[str, object], model.model_json_schema(by_alias=True, ref_template='#/components/schemas/{model}'))
+    definitions = modelSchema.pop('$defs', {})
+    schemas.update(cast(dict[str, object], definitions))
+    schemas[model.__name__] = modelSchema
+    return {'$ref': f'#/components/schemas/{model.__name__}'}
+
+
+def _get_path_parameter_names(path: str) -> set[str]:
+    return {match.group(1) for match in _PATH_PARAMETER_PATTERN.finditer(path)}
+
+
+def _get_request_schema(model: type[BaseModel]) -> dict[str, object]:
+    return cast(dict[str, object], model.model_json_schema(by_alias=True))
+
+
+def _get_path_parameters(model: type[BaseModel], path: str) -> list[dict[str, object]]:
+    modelSchema = _get_request_schema(model=model)
+    properties = cast(dict[str, dict[str, object]], modelSchema.get('properties', {}))
+    pathParameterNames = _get_path_parameter_names(path)
+    return [
+        {
+            'name': name,
+            'in': 'path',
+            'required': True,
+            'schema': properties[name],
+        }
+        for name in properties
+        if name in pathParameterNames
+    ]
+
+
+def _get_query_parameters(model: type[BaseModel], path: str) -> list[dict[str, object]]:
+    modelSchema = _get_request_schema(model=model)
+    properties = cast(dict[str, dict[str, object]], modelSchema.get('properties', {}))
+    required = set(cast(list[str], modelSchema.get('required', [])))
+    pathParameterNames = _get_path_parameter_names(path)
+    return [
+        {
+            'name': name,
+            'in': 'query',
+            'required': name in required,
+            'schema': propertySchema,
+        }
+        for name, propertySchema in properties.items()
+        if name not in pathParameterNames
+    ]
+
+
+def _get_request_body_schema(model: type[BaseModel], path: str, schemas: dict[str, object]) -> dict[str, object]:
+    modelSchema = cast(dict[str, object], model.model_json_schema(by_alias=True, ref_template='#/components/schemas/{model}'))
+    definitions = modelSchema.pop('$defs', {})
+    schemas.update(cast(dict[str, object], definitions))
+    properties = cast(dict[str, dict[str, object]], modelSchema.get('properties', {}))
+    pathParameterNames = _get_path_parameter_names(path)
+    modelSchema['properties'] = {name: schema for name, schema in properties.items() if name not in pathParameterNames}
+    required = cast(list[str], modelSchema.get('required', []))
+    modelSchema['required'] = [name for name in required if name not in pathParameterNames]
+    return modelSchema
+
+
+class OpenApiSchemaGenerator(SchemaGenerator):
+    def __init__(
+        self,
+        title: str,
+        version: str,
+        description: str,
+        tags: Sequence[OpenApiTag],
+        securitySchemes: Sequence[OpenApiSecurityScheme],
+        extensions: Sequence[OpenApiExtension] = (),
+    ) -> None:
+        super().__init__({'openapi': '3.0.3', 'info': {'title': title, 'version': version}})
+        self.title = title
+        self.version = version
+        self.description = description
+        self.tags = tags
+        self.securitySchemes = {scheme.name: scheme.definition for scheme in securitySchemes}
+        self.tagOrder = {tag.name: index for index, tag in enumerate(tags)}
+        self.extensions = extensions
+
+    def get_schema(self, routes: list[BaseRoute]) -> dict[str, object]:
+        document: dict[str, object] = {
+            'openapi': '3.0.3',
+            'info': {
+                'title': self.title,
+                'version': self.version,
+                'description': self.description,
+            },
+            'tags': [tag.model_dump(exclude_none=True) for tag in self.tags],
+            'paths': {},
+            'components': {
+                'schemas': {},
+                'securitySchemes': self.securitySchemes,
+            },
+        }
+        paths = cast(dict[str, object], document['paths'])
+        components = cast(dict[str, object], document['components'])
+        schemas = cast(dict[str, object], components['schemas'])
+
+        def sort_key(endpoint: object) -> int:
+            metadata = get_route_metadata(getattr(endpoint, 'func', None))
+            if metadata.get('operationId') is None:
+                return len(self.tagOrder)
+            endpointTags = metadata.get('tags', [])
+            tag = endpointTags[0] if endpointTags else ''
+            return self.tagOrder.get(tag, len(self.tagOrder))
+
+        for endpoint in sorted(self.get_endpoints(routes), key=sort_key):
+            metadata = get_route_metadata(endpoint.func)
+            if metadata.get('operationId') is None:
+                continue
+            requestType = metadata['requestType']
+            responseType = metadata['responseType']
+            operation: dict[str, object] = {
+                'operationId': metadata['operationId'],
+                'summary': metadata['summary'],
+                'tags': metadata['tags'],
+                'responses': {
+                    '200': {
+                        'description': 'Successful response',
+                        'content': {
+                            'application/x-ndjson' if metadata['streamed'] else 'application/json': {
+                                'schema': _schema_reference(model=responseType, schemas=schemas),
+                            },
+                        },
+                    },
+                },
+            }
+            if metadata['description'] is not None:
+                operation['description'] = metadata['description']
+            rateLimit = metadata.get('rateLimit')
+            if rateLimit:
+                rateLimitText = _format_rate_limit_text(rateLimit=cast(Mapping[str, int], rateLimit))
+                existingDescription = cast(str, operation.get('description', ''))
+                operation['description'] = f'{existingDescription}\n\n{rateLimitText}'.strip()
+            security = metadata.get('security')
+            if security is not None:
+                operation['security'] = security
+            if endpoint.http_method in {'get', 'delete'}:
+                parameters = _get_path_parameters(model=requestType, path=endpoint.path) + _get_query_parameters(model=requestType, path=endpoint.path)
+                if parameters:
+                    operation['parameters'] = parameters
+            else:
+                pathParameters = _get_path_parameters(model=requestType, path=endpoint.path)
+                if pathParameters:
+                    operation['parameters'] = pathParameters
+                bodySchema = _get_request_body_schema(model=requestType, path=endpoint.path, schemas=schemas)
+                if bodySchema.get('properties'):
+                    operation['requestBody'] = {
+                        'required': bool(bodySchema.get('required')),
+                        'content': {
+                            'application/json': {
+                                'schema': bodySchema,
+                            },
+                        },
+                    }
+            for extension in self.extensions:
+                extension.update_operation(route=endpoint, metadata=metadata, operation=operation)
+            pathOperations = cast(dict[str, object], paths.setdefault(endpoint.path, {}))
+            pathOperations[endpoint.http_method] = operation
+        for extension in self.extensions:
+            extension.update_document(document=document)
+        return document
+
+
+def create_openapi_response(schemaGenerator: OpenApiSchemaGenerator) -> Callable[[Request], KibaJSONResponse]:
+    def get_openapi_response(request: Request) -> KibaJSONResponse:
+        return KibaJSONResponse(content=schemaGenerator.get_schema(routes=request.app.routes))
+
+    return get_openapi_response

kiba_core-0.5.3.dev63/core/api/rate_limit.py

@@ -0,0 +1,110 @@
+import functools
+import time
+import typing
+from collections.abc import AsyncIterator
+
+from core.api.api_request import KibaApiRequest
+from core.api.route_metadata import RateLimitConfig
+from core.api.route_metadata import update_route_metadata
+from core.exceptions import InternalServerErrorException
+from core.exceptions import TooManyRequestsException
+
+_AnyReturn = typing.Awaitable[typing.Any] | AsyncIterator[typing.Any]  # type: ignore[explicit-any]
+_SWEEP_INTERVAL = 1000
+_MAX_ENTRY_AGE_SECONDS = 25 * 60 * 60
+
+
+class _WindowConfig(typing.NamedTuple):
+    label: str
+    limit: int
+    windowSeconds: int
+
+
+class _WindowState:
+    __slots__ = ('count', 'windowStart')
+
+    def __init__(self, windowStart: float) -> None:
+        self.count = 0
+        self.windowStart = windowStart
+
+
+_store: dict[str, dict[str, _WindowState]] = {}
+_checkCount = 0
+
+
+def _resolve_user_identity(request: KibaApiRequest[typing.Any]) -> str:  # type: ignore[explicit-any]
+    if request.authBasic is not None:
+        return request.authBasic.username
+    if request.authJwt is not None:
+        subject = request.authJwt.payloadDict.get('sub')
+        if subject:
+            return str(subject)
+    raise InternalServerErrorException(message='rate_limit(keyBy="user") requires an auth decorator to run first')
+
+
+def _resolve_ip_identity(request: KibaApiRequest[typing.Any]) -> str:  # type: ignore[explicit-any]
+    if request.originIp is None:
+        raise InternalServerErrorException(message='rate_limit(keyBy="ip") requires OriginIpMiddleware to be installed')
+    return request.originIp
+
+
+def _sweep_expired_entries(now: float) -> None:
+    staleKeys = [storeKey for storeKey, windowStates in _store.items() if all((now - windowState.windowStart) >= _MAX_ENTRY_AGE_SECONDS for windowState in windowStates.values())]
+    for storeKey in staleKeys:
+        del _store[storeKey]
+
+
+def check_rate_limit(*, request: KibaApiRequest[typing.Any], routeKey: str, rateLimit: RateLimitConfig) -> None:  # type: ignore[explicit-any]
+    windows: list[_WindowConfig] = []
+    if 'perMinute' in rateLimit:
+        windows.append(_WindowConfig(label='perMinute', limit=rateLimit['perMinute'], windowSeconds=60))
+    if 'perFiveMinutes' in rateLimit:
+        windows.append(_WindowConfig(label='perFiveMinutes', limit=rateLimit['perFiveMinutes'], windowSeconds=5 * 60))
+    if 'perHour' in rateLimit:
+        windows.append(_WindowConfig(label='perHour', limit=rateLimit['perHour'], windowSeconds=60 * 60))
+    if 'perDay' in rateLimit:
+        windows.append(_WindowConfig(label='perDay', limit=rateLimit['perDay'], windowSeconds=24 * 60 * 60))
+    if not windows:
+        raise ValueError('rate limit requires at least one of perMinute, perFiveMinutes, perHour, perDay')
+    global _checkCount  # noqa: PLW0603
+    keyBy = rateLimit.get('keyBy', 'user')
+    identity = _resolve_user_identity(request) if keyBy == 'user' else _resolve_ip_identity(request)
+    storeKey = f'{routeKey}:{identity}'
+    now = time.monotonic()
+    _checkCount += 1
+    if _checkCount % _SWEEP_INTERVAL == 0:
+        _sweep_expired_entries(now=now)
+    windowStates = _store.setdefault(storeKey, {})
+    retryAfterSeconds = 0
+    for window in windows:
+        windowState = windowStates.get(window.label)
+        if windowState is None or (now - windowState.windowStart) >= window.windowSeconds:
+            windowState = _WindowState(windowStart=now)
+            windowStates[window.label] = windowState
+        if windowState.count >= window.limit:
+            remainingSeconds = window.windowSeconds - (now - windowState.windowStart)
+            retryAfterSeconds = max(retryAfterSeconds, int(remainingSeconds) + 1)
+    if retryAfterSeconds > 0:
+        raise TooManyRequestsException(message='RATE_LIMITED', retryAfterSeconds=retryAfterSeconds)
+    for window in windows:
+        windowStates[window.label].count += 1
+
+
+def rate_limit(  # type: ignore[explicit-any]
+    rateLimit: RateLimitConfig,
+) -> typing.Callable[[typing.Callable[[KibaApiRequest[typing.Any]], _AnyReturn]], typing.Callable[[KibaApiRequest[typing.Any]], typing.Any]]:
+    def decorator(func: typing.Callable[[KibaApiRequest[typing.Any]], _AnyReturn]) -> typing.Callable[[KibaApiRequest[typing.Any]], typing.Any]:  # type: ignore[explicit-any]
+        update_route_metadata(func, {'rateLimit': rateLimit})
+        routeKey = getattr(func, '__qualname__', type(func).__name__)
+
+        @functools.wraps(func)
+        async def async_wrapper(request: KibaApiRequest[typing.Any]) -> typing.Any:  # type: ignore[explicit-any, misc]
+            check_rate_limit(request=request, routeKey=routeKey, rateLimit=rateLimit)
+            result = func(request)
+            if hasattr(result, '__aiter__'):
+                return result
+            return await result
+
+        return async_wrapper
+
+    return decorator

kiba_core-0.5.3.dev63/core/api/request_context.py

@@ -0,0 +1,52 @@
+import contextvars
+import typing
+from collections.abc import Callable
+from contextlib import contextmanager
+from dataclasses import dataclass
+
+from starlette.types import ASGIApp
+from starlette.types import Receive
+from starlette.types import Scope
+from starlette.types import Send
+
+
+@dataclass
+class RequestContext:
+    originIp: str | None
+
+
+def create_request_context(scope: Scope) -> RequestContext:
+    return RequestContext(originIp=typing.cast('str | None', scope.get('originIp')))
+
+
+class RequestContextHolder[RequestContextType: RequestContext]:
+    def __init__(self) -> None:
+        self._valueContext = contextvars.ContextVar[RequestContextType | None]('_valueContext', default=None)
+
+    def get_value(self) -> RequestContextType:
+        value = self._valueContext.get()
+        if value is None:
+            raise RuntimeError('No request context is active')
+        return value
+
+    @contextmanager
+    def use_value(self, value: RequestContextType) -> typing.Iterator[RequestContextType]:
+        token = self._valueContext.set(value)
+        try:
+            yield value
+        finally:
+            self._valueContext.reset(token)
+
+
+class RequestContextMiddleware:
+    def __init__(self, app: ASGIApp, requestContextHolder: RequestContextHolder[typing.Any], requestContextFactory: Callable[[Scope], RequestContext]) -> None:  # type: ignore[explicit-any]
+        self.app = app
+        self.requestContextHolder = requestContextHolder
+        self.requestContextFactory = requestContextFactory
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope['type'] != 'http':
+            await self.app(scope, receive, send)
+            return
+        with self.requestContextHolder.use_value(self.requestContextFactory(scope)):
+            await self.app(scope, receive, send)

kiba_core-0.5.3.dev63/core/api/route.py

@@ -0,0 +1,80 @@
+import functools
+import typing
+from collections.abc import AsyncIterator
+from collections.abc import Mapping
+
+from pydantic import BaseModel
+from starlette.requests import Request
+from starlette.responses import StreamingResponse
+
+from core.api.api_request import KibaApiRequest
+from core.api.api_response import KibaJSONResponse
+from core.api.json_route import json_route
+from core.api.rate_limit import rate_limit
+from core.api.route_auth import RouteAuthResolver
+from core.api.route_metadata import RateLimitConfig
+from core.api.route_metadata import RouteMetadata
+from core.api.route_metadata import update_route_metadata
+from core.api.streaming_json_route import streaming_json_route
+
+_AnyReturn = typing.Awaitable[typing.Any] | AsyncIterator[typing.Any]  # type: ignore[explicit-any]
+
+
+def _authorize_route[ApiRequest: BaseModel](
+    authResolver: RouteAuthResolver,
+    auth: str,
+) -> typing.Callable[[typing.Callable[[KibaApiRequest[ApiRequest]], _AnyReturn]], typing.Callable[[KibaApiRequest[ApiRequest]], typing.Any]]:
+    def decorator(func: typing.Callable[[KibaApiRequest[ApiRequest]], _AnyReturn]) -> typing.Callable[[KibaApiRequest[ApiRequest]], typing.Any]:  # type: ignore[explicit-any]
+        @functools.wraps(func)
+        async def async_wrapper(request: KibaApiRequest[ApiRequest]) -> typing.Any:  # type: ignore[explicit-any, misc]
+            await authResolver.authorize_route(auth=auth, request=request)
+            result = func(request)
+            if hasattr(result, '__aiter__'):
+                return result
+            return await result
+
+        return async_wrapper
+
+    return decorator
+
+
+def route[ApiRequest: BaseModel, ApiResponse: BaseModel](  # type: ignore[explicit-any]
+    requestType: typing.Type[ApiRequest],
+    responseType: typing.Type[ApiResponse],
+    *,
+    authResolver: RouteAuthResolver,
+    isStreaming: bool = False,
+    operationId: str | None = None,
+    summary: str | None = None,
+    description: str | None = None,
+    tags: list[str] | None = None,
+    auth: str | None = None,
+    rateLimit: RateLimitConfig | None = None,
+    extensions: Mapping[str, object] | None = None,
+) -> typing.Callable[[typing.Callable[[KibaApiRequest[ApiRequest]], _AnyReturn]], typing.Callable[[Request], typing.Awaitable[KibaJSONResponse | StreamingResponse]]]:
+    securitySchemeNames = authResolver.get_route_security_schemes(auth=auth) if auth is not None else []
+
+    def decorator(func: typing.Callable[[KibaApiRequest[ApiRequest]], _AnyReturn]) -> typing.Callable[[Request], typing.Awaitable[KibaJSONResponse | StreamingResponse]]:  # type: ignore[explicit-any]
+        handler: typing.Callable[[KibaApiRequest[ApiRequest]], _AnyReturn] = func
+        if rateLimit is not None:
+            handler = rate_limit(rateLimit)(handler)
+        if auth is not None:
+            handler = _authorize_route(authResolver, auth)(handler)
+        endpointDecorator = streaming_json_route if isStreaming else json_route
+        endpoint = endpointDecorator(requestType=requestType, responseType=responseType)(handler)  # type: ignore[arg-type, ty:invalid-argument-type]
+        metadata: RouteMetadata = {
+            'requestType': requestType,
+            'responseType': responseType,
+            'streamed': isStreaming,
+            'operationId': operationId,
+            'summary': summary,
+            'description': description,
+            'tags': tags or [],
+            'extensions': dict(extensions) if extensions else {},
+        }
+        update_route_metadata(endpoint, metadata)
+        if securitySchemeNames:
+            update_route_metadata(endpoint, {'security': [{name: []} for name in securitySchemeNames]})
+        return endpoint
+
+    return decorator

kiba_core-0.5.3.dev63/core/api/route_auth.py

@@ -0,0 +1,11 @@
+from typing import Protocol
+
+from pydantic import BaseModel
+
+from core.api.api_request import KibaApiRequest
+
+
+class RouteAuthResolver(Protocol):
+    async def authorize_route[ApiRequest: BaseModel](self, *, auth: str, request: KibaApiRequest[ApiRequest]) -> None: ...
+
+    def get_route_security_schemes(self, *, auth: str) -> list[str]: ...