python-platform 0.1.1__py3-none-any.whl

python_platform/fastapi/application_services.py

@@ -0,0 +1,647 @@
+"""ApplicationServiceCatalog 驱动的约定式 FastAPI route 生成。"""
+
+from __future__ import annotations
+
+import inspect
+import re
+import types
+from collections.abc import Awaitable, Callable, Coroutine, Mapping
+from dataclasses import dataclass, is_dataclass
+from datetime import date, datetime, time
+from decimal import Decimal
+from enum import Enum
+from typing import Annotated, Any, Literal, Union, cast, get_args, get_origin, get_type_hints
+from uuid import UUID
+
+from dishka import AsyncContainer
+from dishka.integrations.fastapi import DishkaRoute, FromDishka
+from fastapi import APIRouter, Depends
+from fastapi.params import Body, Param, Path
+from fastapi.security import HTTPBearer
+from pydantic import BaseModel
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.routing import compile_path
+
+from ..application import Application
+from ..application_services import (
+    ApplicationServiceRegistration,
+)
+from ..application_services.catalog import _CompiledApplicationService, _CompiledMethod
+from ..application_services.dispatcher import _ApplicationServiceDispatcher
+from ..diagnostics import SourceLocation
+from ..modularity import AppModule, ModuleDescriptor, ModuleKey
+from .action import _HttpActionOwner, _request_parameter
+from .contracts import (
+    ApplicationServiceRouteOverride,
+    _application_service_exposure_for,
+    _ApplicationServiceExposure,
+)
+from .errors import FastApiAdapterError
+from .filters import _filters_for, _ordered_filters, _validate_filters
+from .http import _metadata, _remote
+from .http_router import _compile_parameter
+from .parameters import _HttpParameterValidator
+from .transfer import _manage_stream
+from .uploads import _prepare_upload
+
+_APPLICATION_SERVICE_SUFFIX = "ApplicationService"
+_PATH_PARAMETER = re.compile(r"\{(?P<name>[^{}:]+)(?::[^{}]+)?\}")
+_WORD_BOUNDARY_1 = re.compile(r"(.)([A-Z][a-z]+)")
+_WORD_BOUNDARY_2 = re.compile(r"([a-z0-9])([A-Z])")
+_ROUTE_SOURCE_ATTRIBUTE = "__python_platform_fastapi_route_source__"
+_INVOCATION_IDENTITY_ATTRIBUTE = "__python_platform_fastapi_invocation_identity__"
+_VERB_PREFIXES: tuple[tuple[str, str], ...] = (
+    ("get_list", "GET"),
+    ("get_all", "GET"),
+    ("get", "GET"),
+    ("create", "POST"),
+    ("add", "POST"),
+    ("insert", "POST"),
+    ("post", "POST"),
+    ("update", "PUT"),
+    ("put", "PUT"),
+    ("delete", "DELETE"),
+    ("remove", "DELETE"),
+    ("patch", "PATCH"),
+)
+_SCALAR_TYPES = (str, int, float, bool, UUID, Decimal, date, datetime, time)
+
+
+@dataclass(frozen=True, slots=True)
+class _GeneratedApplicationServiceRouter:
+    owner: ModuleKey
+    router: APIRouter
+
+
+@dataclass(frozen=True, slots=True)
+class _RouteMethod:
+    signature: inspect.Signature
+    parameters: tuple[inspect.Parameter, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class _ApplicationServiceRouteIdentity:
+    service: _CompiledApplicationService
+    method: _CompiledMethod
+
+
+class _ApplicationServiceRoute(DishkaRoute):
+    """在 native FastAPI binding 前建立 catalog-identity invocation boundary。"""
+
+    __slots__ = ("_compiled_method", "_compiled_service")
+
+    def __init__(
+        self,
+        path: str,
+        endpoint: Callable[..., Any],
+        **kwargs: Any,
+    ) -> None:
+        identity = getattr(endpoint, _INVOCATION_IDENTITY_ATTRIBUTE, None)
+        if not isinstance(identity, _ApplicationServiceRouteIdentity):
+            raise FastApiAdapterError("generated Application Service route lost its identity")
+        self._compiled_service = identity.service
+        self._compiled_method = identity.method
+        sources = getattr(endpoint, "__python_platform_http_sources__", None)
+        super().__init__(path, endpoint, **kwargs)
+        cast(Any, self.endpoint).__python_platform_http_sources__ = sources
+        # include_router 会以已注入 endpoint 重建 route；显式把 identity 传递给下一次构造。
+        setattr(self.endpoint, _INVOCATION_IDENTITY_ATTRIBUTE, identity)
+
+    def get_route_handler(
+        self,
+    ) -> Callable[[Request], Coroutine[Any, Any, Response]]:
+        native_handler = super().get_route_handler()
+        service = self._compiled_service
+        method = self._compiled_method
+
+        async def route_handler(request: Request) -> Response:
+            owner = await _HttpActionOwner.install(request)
+            container = cast(AsyncContainer, request.state.dishka_container)
+            dispatcher = await container.get(_ApplicationServiceDispatcher)
+
+            async def bind() -> Response:
+                await _prepare_upload(request, method.implementation_method, self)
+                return await native_handler(request)
+
+            try:
+                result = await dispatcher.invoke_http_request(
+                    service,
+                    method,
+                    bind,
+                    is_short_circuited=lambda: owner.short_circuited,
+                    defer_audit=owner.audits.append,
+                )
+                owner.response_ready = isinstance(result, Response)
+            except BaseException as error:
+                owner.failure = error
+                raise
+            if not isinstance(result, Response):
+                raise FastApiAdapterError(
+                    "an interceptor outside HTTP binding must return a native Response"
+                )
+            _manage_stream(request, result)
+            return result
+
+        return route_handler
+
+
+def _application_service_routers(
+    application: Application,
+) -> tuple[_GeneratedApplicationServiceRouter, ...]:
+    """按 live Module graph 顺序生成 Router，不保存进程级 exposure registry。"""
+
+    descriptors_by_type = {
+        descriptor.module_type: descriptor for descriptor in application.modules.dependency_order
+    }
+    generated: list[_GeneratedApplicationServiceRouter] = []
+    for http_descriptor in application.modules.dependency_order:
+        exposure = _application_service_exposure_for(http_descriptor.module_type)
+        if exposure is None:
+            continue
+        router = _create_exposure_router(
+            application,
+            http_descriptor=http_descriptor,
+            exposure=exposure,
+            descriptors_by_type=descriptors_by_type,
+        )
+        generated.append(
+            _GeneratedApplicationServiceRouter(owner=http_descriptor.key, router=router)
+        )
+    return tuple(generated)
+
+
+def _create_exposure_router(
+    application: Application,
+    *,
+    http_descriptor: ModuleDescriptor,
+    exposure: _ApplicationServiceExposure,
+    descriptors_by_type: Mapping[type[AppModule], ModuleDescriptor],
+) -> APIRouter:
+    target_descriptors = _exposure_targets(http_descriptor, exposure, descriptors_by_type)
+
+    # metadata 决定稳定基序；最终仅按路径段具体性排序，避免参数路径遮蔽动作。
+    registrations = tuple(
+        registration
+        for target in target_descriptors
+        for registration in application.application_service_catalog.registrations
+        if registration.is_public_service and registration.owner == target.key
+    )
+    overrides = _index_overrides(exposure, registrations)
+    router = APIRouter(route_class=_ApplicationServiceRoute)
+    for registration in registrations:
+        if registration.is_integration_service:
+            continue
+        compiled_service = application.application_service_catalog._for_registration(registration)
+        service_override = overrides.get((registration.contract, None))
+        if service_override is not None:
+            continue
+        service_path = _service_path(exposure.root_path, registration.contract)
+        for method_registration in registration.methods:
+            compiled_method = compiled_service.methods[method_registration.name]
+            contract_method = cast(
+                Callable[..., Awaitable[object]],
+                getattr(registration.contract, method_registration.name),
+            )
+            method_override = overrides.get((registration.contract, contract_method))
+            if method_override is not None and not method_override.enabled:
+                continue
+            enabled, visible = _remote(
+                registration.implementation, compiled_method.implementation_method
+            )
+            if not enabled and method_override is None:
+                continue
+            projection, provenance = _route_projection(
+                compiled_method.implementation_method, method_override
+            )
+            route_method = _inspect_route_method(
+                registration.contract,
+                compiled_method.implementation_method,
+                method_registration.name,
+            )
+            path = _route_path(
+                service_path,
+                route_method.parameters,
+                projection.pop("path", None),
+                contract=registration.contract,
+                method_name=method_registration.name,
+            )
+            for parameter in route_method.parameters:
+                _compile_parameter(
+                    parameter,
+                    parameter.annotation,
+                    compile_path(path)[2],
+                    application._container_for_integration(),
+                    infer_services=False,
+                )
+            verb = projection.pop("verb", _conventional_verb(method_registration.name))
+            operation_id = projection.pop(
+                "operation_id", _operation_id(registration.contract, method_registration.name)
+            )
+            status_code = projection.pop("status_code", None)
+            projection.setdefault("include_in_schema", visible)
+            _validate_filters(
+                _filters_for(
+                    *reversed(registration.implementation.__mro__),
+                    compiled_method.implementation_method,
+                ),
+                application._container_for_integration(),
+            )
+            endpoint = _create_endpoint(
+                compiled_service,
+                compiled_method,
+                route_method,
+                method_registration.source,
+            )
+            from types import MappingProxyType
+
+            cast(Any, endpoint).__python_platform_http_sources__ = MappingProxyType(
+                {
+                    key: provenance.get(key, "convention")
+                    for key in ("path", "verb", "operation_id", "status_code", *projection)
+                }
+            )
+            try:
+                router.add_api_route(
+                    path,
+                    endpoint,
+                    methods=[verb],
+                    operation_id=operation_id,
+                    status_code=status_code,
+                    # 原生 dependency 声明 Bearer；认证和权限仍由正式 invocation 管线执行。
+                    dependencies=[
+                        *projection.pop("dependencies", ()),
+                        *(
+                            [Depends(HTTPBearer(auto_error=False))]
+                            if compiled_method.authorization.requires_authenticated_user
+                            else []
+                        ),
+                    ],
+                    **projection,
+                )
+            except (AssertionError, TypeError, ValueError) as original_error:
+                raise FastApiAdapterError(
+                    f"FastAPI rejected convention route {verb} {path} for "
+                    f"{registration.contract.__module__}.{registration.contract.__qualname__}."
+                    f"{method_registration.name}: {type(original_error).__name__}"
+                ) from original_error
+    # Starlette 采用首次匹配：静态动作段必须先于参数段，否则 get_count 会落进 get(id)。
+    # 相同路径结构使用稳定排序，保留声明顺序及 endpoint 的 invocation identity。
+    router.routes.sort(
+        key=lambda route: tuple(
+            "{" in segment for segment in cast(_ApplicationServiceRoute, route).path.split("/")
+        )
+    )
+    return router
+
+
+def _index_overrides(
+    exposure: _ApplicationServiceExposure,
+    registrations: tuple[ApplicationServiceRegistration, ...],
+) -> Mapping[
+    tuple[type[object], Callable[..., Awaitable[object]] | None],
+    ApplicationServiceRouteOverride,
+]:
+    """用 Protocol/method identity 建索引，避免字符串方法名形成第二份 API 清单。"""
+
+    registrations_by_contract = {item.contract: item for item in registrations}
+    indexed: dict[
+        tuple[type[object], Callable[..., Awaitable[object]] | None],
+        ApplicationServiceRouteOverride,
+    ] = {}
+    service_exclusions: set[type[object]] = set()
+    service_method_overrides: set[type[object]] = set()
+    for override in exposure.overrides:
+        registration = registrations_by_contract.get(override.service)
+        if registration is None:
+            raise FastApiAdapterError(
+                "route override targets an ApplicationServiceContract not owned by the "
+                f"declared target Modules: {override.service.__module__}."
+                f"{override.service.__qualname__}"
+            )
+        method = override.method
+        if registration.is_integration_service and override.enabled:
+            raise FastApiAdapterError("IntegrationService cannot be exposed over HTTP")
+        if method is not None:
+            method_names = {
+                item.name: cast(
+                    Callable[..., Awaitable[object]],
+                    getattr(registration.contract, item.name),
+                )
+                for item in registration.methods
+            }
+            if method not in method_names.values():
+                raise FastApiAdapterError(
+                    f"route override method is not owned by {override.service.__module__}."
+                    f"{override.service.__qualname__}"
+                )
+            service_method_overrides.add(override.service)
+        else:
+            service_exclusions.add(override.service)
+        key = (override.service, method)
+        if key in indexed:
+            raise FastApiAdapterError(
+                f"duplicate route override for {override.service.__module__}."
+                f"{override.service.__qualname__}"
+            )
+        indexed[key] = override
+    overlap = service_exclusions & service_method_overrides
+    if overlap:
+        contract = min(overlap, key=lambda item: (item.__module__, item.__qualname__))
+        raise FastApiAdapterError(
+            f"excluded service {contract.__module__}.{contract.__qualname__} cannot also "
+            "declare method overrides"
+        )
+    return indexed
+
+
+def _inspect_route_method(
+    contract: type[object],
+    method: Callable[..., Awaitable[object]],
+    method_name: str,
+) -> _RouteMethod:
+    """在真实 FastAPI app 变更前解析并收窄动态 typing boundary。"""
+
+    try:
+        annotations = get_type_hints(method, include_extras=True)
+    except (NameError, TypeError) as original_error:
+        raise FastApiAdapterError(
+            f"HTTP method annotations cannot be resolved for {contract.__module__}."
+            f"{contract.__qualname__}.{method_name}: {type(original_error).__name__}"
+        ) from original_error
+    signature = inspect.signature(method)
+    resolved_parameters = tuple(
+        parameter.replace(annotation=annotations.get(name, parameter.annotation))
+        for name, parameter in signature.parameters.items()
+    )
+    signature = signature.replace(
+        parameters=resolved_parameters,
+        return_annotation=annotations.get("return", signature.return_annotation),
+    )
+    parameters = resolved_parameters[1:]
+    for parameter in parameters:
+        if parameter.kind in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        ):
+            raise FastApiAdapterError(
+                f"HTTP method {contract.__module__}.{contract.__qualname__}.{method_name} "
+                "cannot use positional-only, *args, or **kwargs parameters"
+            )
+        if parameter.annotation is inspect.Signature.empty:
+            raise FastApiAdapterError(
+                f"HTTP method {contract.__module__}.{contract.__qualname__}.{method_name} "
+                f"parameter {parameter.name!r} requires a type annotation"
+            )
+    if signature.return_annotation is inspect.Signature.empty:
+        raise FastApiAdapterError(
+            f"HTTP method {contract.__module__}.{contract.__qualname__}.{method_name} "
+            "requires a return type annotation"
+        )
+    return _RouteMethod(signature=signature, parameters=parameters)
+
+
+def _uses_non_path_binding(parameter: inspect.Parameter) -> bool:
+    metadata = (
+        get_args(parameter.annotation)[1:] if get_origin(parameter.annotation) is Annotated else ()
+    )
+    return any(
+        isinstance(item, (Param, Body)) and not isinstance(item, Path)
+        for item in (*metadata, parameter.default)
+    )
+
+
+def _route_path(
+    service_path: str,
+    parameters: tuple[inspect.Parameter, ...],
+    override_path: str | None,
+    *,
+    contract: type[object],
+    method_name: str,
+) -> str:
+    # 只有唯一 required scalar id 才能无歧义进入 convention path；
+    # 其余情况保持 query 或要求 override。
+    id_candidates = tuple(
+        parameter
+        for parameter in parameters
+        if _is_required_path_parameter(parameter)
+        and (parameter.name == "id" or parameter.name.endswith("_id"))
+        and _is_scalar_annotation(parameter.annotation)
+        and not _uses_non_path_binding(parameter)
+    )
+    if override_path is None:
+        if len(id_candidates) > 1:
+            raise FastApiAdapterError(
+                f"HTTP method {contract.__module__}.{contract.__qualname__}.{method_name} "
+                "has ambiguous required id parameters and requires an explicit path override"
+            )
+        path = service_path
+        if len(id_candidates) == 1:
+            path = f"{path}/{{{id_candidates[0].name}}}"
+        # 只有集中定义的 CRUD 名称省略动作；审批/取消等领域动作保持其 contract 名称。
+        if method_name not in {prefix for prefix, _ in _VERB_PREFIXES}:
+            path = f"{path}/{method_name.replace('_', '-')}"
+        return path
+
+    if "?" in override_path or "#" in override_path:
+        raise FastApiAdapterError("route override path cannot contain query or fragment syntax")
+    rendered_parameters = tuple(
+        match.group("name") for match in _PATH_PARAMETER.finditer(override_path)
+    )
+    if override_path.count("{") != len(rendered_parameters) or override_path.count("}") != len(
+        rendered_parameters
+    ):
+        raise FastApiAdapterError(f"route override path {override_path!r} is malformed")
+    parameters_by_name = {parameter.name: parameter for parameter in parameters}
+    for name in rendered_parameters:
+        parameter = parameters_by_name.get(name)
+        if (
+            parameter is None
+            or not _is_required_path_parameter(parameter)
+            or not _is_scalar_annotation(parameter.annotation)
+            or _uses_non_path_binding(parameter)
+        ):
+            raise FastApiAdapterError(
+                f"route override path parameter {name!r} must name a required scalar "
+                f"Protocol parameter on {contract.__qualname__}.{method_name}"
+            )
+    if len(set(rendered_parameters)) != len(rendered_parameters):
+        raise FastApiAdapterError(f"route override path {override_path!r} repeats a path parameter")
+    return override_path
+
+
+def _is_required_path_parameter(parameter: inspect.Parameter) -> bool:
+    return parameter.default is inspect.Signature.empty or isinstance(parameter.default, Path)
+
+
+def _is_scalar_annotation(annotation: object) -> bool:
+    current = annotation
+    if get_origin(current) is Annotated:
+        current = get_args(current)[0]
+    origin = get_origin(current)
+    if origin in (types.UnionType, Union):
+        members = tuple(item for item in get_args(current) if item is not type(None))
+        return len(members) == 1 and _is_scalar_annotation(members[0])
+    if origin is Literal:
+        return all(isinstance(item, (str, int, float, bool)) for item in get_args(current))
+    if not isinstance(current, type):
+        return False
+    if issubclass(current, BaseModel) or is_dataclass(current):
+        return False
+    return issubclass(current, (*_SCALAR_TYPES, Enum))
+
+
+def _service_path(root_path: str, contract: type[object]) -> str:
+    service_name = contract.__name__
+    if service_name.endswith(_APPLICATION_SERVICE_SUFFIX):
+        service_name = service_name[: -len(_APPLICATION_SERVICE_SUFFIX)]
+    if not service_name:
+        raise FastApiAdapterError("application service contract has no routable name")
+    return f"/api/{root_path}/{_kebab_case(service_name)}"
+
+
+def _operation_id(contract: type[object], method_name: str) -> str:
+    service_path = _service_path("app", contract).rsplit("/", maxsplit=1)[-1]
+    return f"{service_path.replace('-', '_')}_{method_name}"
+
+
+def _kebab_case(value: str) -> str:
+    first_pass = _WORD_BOUNDARY_1.sub(r"\1-\2", value)
+    return _WORD_BOUNDARY_2.sub(r"\1-\2", first_pass).lower().replace("_", "-")
+
+
+def _conventional_verb(method_name: str) -> str:
+    for prefix, verb in _VERB_PREFIXES:
+        if method_name == prefix or method_name.startswith(f"{prefix}_"):
+            return verb
+    return "POST"
+
+
+def _create_endpoint(
+    service: _CompiledApplicationService,
+    method: _CompiledMethod,
+    route_method: _RouteMethod,
+    source: SourceLocation,
+) -> Callable[..., Awaitable[object]]:
+    """保留 Protocol 原签名供 FastAPI binding，并注入同一 REQUEST dispatcher。"""
+
+    contract = service.registration.contract
+    method_name = method.name
+    parameter_names = {parameter.name for parameter in route_method.parameters}
+    dispatcher_parameter_name = "_python_platform_application_service_dispatcher"
+    while dispatcher_parameter_name in parameter_names:
+        dispatcher_parameter_name = f"_{dispatcher_parameter_name}"
+
+    declared_filters = _ordered_filters(
+        _filters_for(*reversed(service.registration.implementation.__mro__)),
+        _filters_for(method.implementation_method),
+    )
+    validator = _HttpParameterValidator(
+        route_method.signature.replace(parameters=route_method.parameters)
+    )
+
+    async def endpoint(**values: object) -> object:
+        dispatcher = cast(_ApplicationServiceDispatcher, values.pop(dispatcher_parameter_name))
+        request = cast(
+            Request,
+            values.pop(request_parameter_name)
+            if injected_request
+            else values[request_parameter_name],
+        )
+        owner: _HttpActionOwner = request.state.python_platform_action
+        await owner.activate(
+            method.descriptor.unit_of_work, method.name, service.registration.connection_name
+        )
+        filters = _ordered_filters(
+            getattr(request.app.state, "python_platform_filters", ()), declared_filters
+        )
+        snapshots = validator.capture(values)
+
+        async def invoke(actual: dict[str, object]) -> object:
+            if filters:
+                validator.validate_changes(actual, snapshots)
+            return await dispatcher.invoke_http(service, method, actual)
+
+        return await owner.invoke(
+            method.implementation_method,
+            values,
+            filters,
+            invoke,
+        )
+
+    request_parameter, injected_request = _request_parameter(route_method.parameters)
+    request_parameter_name = request_parameter.name
+    http_parameters = (
+        (*route_method.parameters, request_parameter)
+        if injected_request
+        else route_method.parameters
+    )
+
+    dispatcher_parameter = inspect.Parameter(
+        dispatcher_parameter_name,
+        kind=inspect.Parameter.KEYWORD_ONLY,
+        annotation=cast(Any, FromDishka)[_ApplicationServiceDispatcher],
+    )
+    # 动态 endpoint 的 signature/annotations 同时发布，兼容 FastAPI 与 postponed annotations。
+    signature = route_method.signature.replace(parameters=(*http_parameters, dispatcher_parameter))
+    endpoint_name = f"{contract.__name__}_{method_name}"
+    endpoint.__name__ = endpoint_name
+    endpoint.__qualname__ = endpoint_name
+    endpoint.__module__ = contract.__module__
+    cast(Any, endpoint).__signature__ = signature
+    endpoint.__annotations__ = {
+        **{
+            parameter.name: parameter.annotation
+            for parameter in (*http_parameters, dispatcher_parameter)
+        },
+        "return": signature.return_annotation,
+    }
+    setattr(endpoint, _ROUTE_SOURCE_ATTRIBUTE, source)
+    setattr(
+        endpoint,
+        _INVOCATION_IDENTITY_ATTRIBUTE,
+        _ApplicationServiceRouteIdentity(service, method),
+    )
+    return endpoint
+
+
+def _route_projection(
+    method: object, override: ApplicationServiceRouteOverride | None
+) -> tuple[dict[str, Any], dict[str, str]]:
+    projection = dict(_metadata(method))
+    provenance = {key: "method" for key in projection}
+    if override is not None:
+        from dataclasses import fields
+
+        for field in fields(override):
+            if field.name in ("service", "method", "enabled"):
+                continue
+            value = getattr(override, field.name)
+            if value is not None:
+                projection[field.name] = value
+                provenance[field.name] = "module_override"
+    return projection, provenance
+
+
+def _exposure_targets(
+    http_descriptor: ModuleDescriptor,
+    exposure: _ApplicationServiceExposure,
+    descriptors_by_type: Mapping[type[AppModule], ModuleDescriptor],
+) -> list[ModuleDescriptor]:
+    target_descriptors: list[ModuleDescriptor] = []
+    for target_type in exposure.target_modules:
+        target = descriptors_by_type.get(target_type)
+        if target is None:
+            raise FastApiAdapterError(
+                f"{http_descriptor.key} exposes unloaded target Module "
+                f"{target_type.__module__}:{target_type.__qualname__}"
+            )
+        if target.key not in http_descriptor.dependencies:
+            raise FastApiAdapterError(
+                f"{http_descriptor.key} may only expose a directly depended-on target Module; "
+                f"got {target.key}"
+            )
+        target_descriptors.append(target)
+
+    return target_descriptors

python_platform/fastapi/background.py

@@ -0,0 +1,42 @@
+"""后台管理 HTTP 复用正式服务暴露、授权和响应准备。"""
+
+from ..background_execution.management import BackgroundManagementApplicationService
+from ..background_execution.module import BackgroundManagementModule
+from ..modularity import AppModule
+from .contracts import ApplicationServiceRouteOverride, exposes_application_services
+
+
+@exposes_application_services(
+    BackgroundManagementModule,
+    root_path="background",
+    overrides=(
+        ApplicationServiceRouteOverride(
+            BackgroundManagementApplicationService,
+            method=BackgroundManagementApplicationService.get_list,
+            path="/api/background/tasks",
+            verb="GET",
+        ),
+        ApplicationServiceRouteOverride(
+            BackgroundManagementApplicationService,
+            method=BackgroundManagementApplicationService.get,
+            path="/api/background/tasks/{task_id}",
+            verb="GET",
+        ),
+        ApplicationServiceRouteOverride(
+            BackgroundManagementApplicationService,
+            method=BackgroundManagementApplicationService.start,
+            path="/api/background/tasks/{task_id}/start",
+            verb="POST",
+            status_code=202,
+        ),
+        ApplicationServiceRouteOverride(
+            BackgroundManagementApplicationService,
+            method=BackgroundManagementApplicationService.stop,
+            path="/api/background/tasks/{task_id}/stop",
+            verb="POST",
+            status_code=202,
+        ),
+    ),
+)
+class BackgroundManagementHttpApiModule(AppModule):
+    dependencies = (BackgroundManagementModule,)