feat(BA-5830): add AppConfigFragment REST v2 endpoints

Mounts the Fragment adapter as REST v2 under `/v2/app-config-fragments`
(BEP-1052 §4). Shares v2 DTOs with the GraphQL surface added in
BA-5829 (#11285).

Endpoints:
- `POST /v2/app-config-fragments/get`                              — auth_required (body-carried natural key)
- `POST /v2/app-config-fragments/{scope_type}/{scope_id}/search`   — auth_required (scoped)
- `POST /v2/app-config-fragments/search`                           — superadmin_required (cross-scope)
- `POST /v2/app-config-fragments`                                  — superadmin_required (create)
- `POST /v2/app-config-fragments/update`                           — superadmin_required
- `POST /v2/app-config-fragments/purge`                            — superadmin_required

Scoped search uses the project's `{scope_type}/{scope_id}` nested
URL convention; `get` takes the three-part natural key via the body
since a three-field path segment is noisier than a body DTO.

Adds:
- `api/rest/v2/app_config_fragment/handler.V2AppConfigFragmentHandler`
  + `registry.register_v2_app_config_fragment_routes`.
- `AppConfigFragmentScopePathParam` in the shared path-params module.
- Handler instantiation + sub-registry wiring in `rest/v2/tree.py`.

The scope handler converts the DTO `AppConfigScopeType` to the
data-layer enum so the adapter signature stays data-typed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jopemachine

src/ai/backend/manager/api/rest/v2/app_config_fragment/__init__.py

@@ -0,0 +1,94 @@
+"""REST v2 handler for the app-config fragment domain (BEP-1052 §2)."""
+
+from __future__ import annotations
+
+import logging
+from http import HTTPStatus
+from typing import TYPE_CHECKING, Final
+
+from ai.backend.common.api_handlers import APIResponse, BodyParam, PathParam
+from ai.backend.common.dto.manager.v2.app_config_fragment.request import (
+    AppConfigFragmentKeyInput,
+    CreateAppConfigFragmentInput,
+    PurgeAppConfigFragmentInput,
+    SearchAppConfigFragmentsInput,
+    UpdateAppConfigFragmentInput,
+)
+from ai.backend.common.dto.manager.v2.app_config_fragment.types import AppConfigScopeType
+from ai.backend.logging import BraceStyleAdapter
+from ai.backend.manager.api.rest.v2.path_params import AppConfigFragmentScopePathParam
+from ai.backend.manager.data.app_config_fragment.types import (
+    AppConfigScopeType as DataAppConfigScopeType,
+)
+
+if TYPE_CHECKING:
+    from ai.backend.manager.api.adapters.app_config_fragment import AppConfigFragmentAdapter
+
+log: Final = BraceStyleAdapter(logging.getLogger(__spec__.name))
+
+
+class V2AppConfigFragmentHandler:
+    """REST v2 handler for app-config fragment operations."""
+
+    def __init__(self, *, adapter: AppConfigFragmentAdapter) -> None:
+        self._adapter = adapter
+
+    async def get(
+        self,
+        body: BodyParam[AppConfigFragmentKeyInput],
+    ) -> APIResponse:
+        """Read a single fragment by natural key (any authenticated user)."""
+        result = await self._adapter.get(body.parsed)
+        return APIResponse.build(status_code=HTTPStatus.OK, response_model=result)
+
+    async def scoped_search(
+        self,
+        path: PathParam[AppConfigFragmentScopePathParam],
+        body: BodyParam[SearchAppConfigFragmentsInput],
+    ) -> APIResponse:
+        """Scope-bound fragment search — caller is pinned to a specific
+        `(scope_type, scope_id)` pair via the URL path.
+        """
+        result = await self._adapter.search(
+            scope_type=DataAppConfigScopeType(path.parsed.scope_type),
+            scope_id=path.parsed.scope_id,
+            input=body.parsed,
+        )
+        return APIResponse.build(status_code=HTTPStatus.OK, response_model=result)
+
+    async def admin_search(
+        self,
+        body: BodyParam[SearchAppConfigFragmentsInput],
+    ) -> APIResponse:
+        """Cross-scope admin search (admin only)."""
+        result = await self._adapter.admin_search(body.parsed)
+        return APIResponse.build(status_code=HTTPStatus.OK, response_model=result)
+
+    async def admin_create(
+        self,
+        body: BodyParam[CreateAppConfigFragmentInput],
+    ) -> APIResponse:
+        """Create a new fragment (admin only)."""
+        result = await self._adapter.create(body.parsed)
+        return APIResponse.build(status_code=HTTPStatus.CREATED, response_model=result)
+
+    async def admin_update(
+        self,
+        body: BodyParam[UpdateAppConfigFragmentInput],
+    ) -> APIResponse:
+        """Update a fragment's `extra_config` (admin only)."""
+        result = await self._adapter.update(body.parsed)
+        return APIResponse.build(status_code=HTTPStatus.OK, response_model=result)
+
+    async def admin_purge(
+        self,
+        body: BodyParam[PurgeAppConfigFragmentInput],
+    ) -> APIResponse:
+        """Hard-delete a fragment (admin only)."""
+        result = await self._adapter.purge(body.parsed)
+        return APIResponse.build(status_code=HTTPStatus.OK, response_model=result)
+
+
+# ``AppConfigScopeType`` is imported for OpenAPI schema visibility of the
+# string-form path parameter; keep the import alive.
+_ = AppConfigScopeType

src/ai/backend/manager/api/rest/v2/app_config_fragment/handler.py

@@ -0,0 +1,46 @@
+"""Route registration for v2 app-config fragment endpoints."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ai.backend.manager.api.rest.middleware.auth import auth_required, superadmin_required
+from ai.backend.manager.api.rest.routing import RouteRegistry
+
+from .handler import V2AppConfigFragmentHandler
+
+if TYPE_CHECKING:
+    from ai.backend.manager.api.rest.types import RouteDeps
+
+
+def register_v2_app_config_fragment_routes(
+    handler: V2AppConfigFragmentHandler,
+    route_deps: RouteDeps,
+) -> RouteRegistry:
+    """Register all v2 app-config fragment routes (BEP-1052 §4).
+
+    - `POST /v2/app-config-fragments/get` reads a single row via body
+      (the natural key has three fields, so a body DTO is cleaner than
+      a long path).
+    - Scoped search mounts at
+      `/v2/app-config-fragments/{scope_type}/{scope_id}/search` per the
+      project's scoped-search URL convention.
+    - Admin cross-scope search, create / update / purge are admin-only.
+    """
+    reg = RouteRegistry.create("app-config-fragments", route_deps.cors_options)
+
+    # Read
+    reg.add("POST", "/get", handler.get, middlewares=[auth_required])
+    reg.add(
+        "POST",
+        "/{scope_type}/{scope_id}/search",
+        handler.scoped_search,
+        middlewares=[auth_required],
+    )
+    reg.add("POST", "/search", handler.admin_search, middlewares=[superadmin_required])
+    # Write
+    reg.add("POST", "", handler.admin_create, middlewares=[superadmin_required])
+    reg.add("POST", "/update", handler.admin_update, middlewares=[superadmin_required])
+    reg.add("POST", "/purge", handler.admin_purge, middlewares=[superadmin_required])
+
+    return reg

src/ai/backend/manager/api/rest/v2/app_config_fragment/registry.py

@@ -9,6 +9,11 @@
 from ai.backend.common.api_handlers import BaseRequestModel
 
 
+class AppConfigFragmentScopePathParam(BaseRequestModel):
+    scope_type: str = Field(description="App-config scope type (public/domain/user/...).")
+    scope_id: str = Field(description="Scope id (domain name, user id, or `public`).")
+
+
 class DomainNamePathParam(BaseRequestModel):
     domain_name: str = Field(description="Domain name")
 

src/ai/backend/manager/api/rest/v2/path_params.py

@@ -28,6 +28,8 @@ def build_v2_routes(
     # Lazy imports to avoid circular dependencies at module level
     from .agent.handler import V2AgentHandler
     from .agent.registry import register_v2_agent_routes
+    from .app_config_fragment.handler import V2AppConfigFragmentHandler
+    from .app_config_fragment.registry import register_v2_app_config_fragment_routes
     from .artifact.handler import V2ArtifactHandler
     from .artifact.registry import register_v2_artifact_routes
     from .artifact_registry.handler import V2ArtifactRegistryHandler
@@ -111,6 +113,7 @@ def build_v2_routes(
 
     # Build all handlers (each takes its individual adapter)
     agent_handler = V2AgentHandler(adapter=adapters.agent)
+    app_config_fragment_handler = V2AppConfigFragmentHandler(adapter=adapters.app_config_fragment)
     artifact_handler = V2ArtifactHandler(adapter=adapters.artifact)
     artifact_registry_handler = V2ArtifactRegistryHandler(adapter=adapters.artifact_registry)
     audit_log_handler = V2AuditLogHandler(adapter=adapters.audit_log)
@@ -165,6 +168,9 @@ def build_v2_routes(
 
     # Add all domain sub-registries
     v2_reg.add_subregistry(register_v2_agent_routes(agent_handler, route_deps))
+    v2_reg.add_subregistry(
+        register_v2_app_config_fragment_routes(app_config_fragment_handler, route_deps)
+    )
     v2_reg.add_subregistry(register_v2_artifact_routes(artifact_handler, route_deps))
     v2_reg.add_subregistry(
         register_v2_artifact_registry_routes(artifact_registry_handler, route_deps)