feat(BA-5830): add AppConfigFragment + AppConfig REST v2 surface

REST endpoints for the Fragment domain and the merged AppConfig view
(BEP-1052 §2 / §5). Service / adapter foundation lands in BA-5827
(Fragment bulk) and BA-5829 (merged-view actions); this PR only wires
the REST entry points on top.

REST v2 (`/v2/app-config-fragments`):
- `GET /{scope_type}/{scope_id}/{name}` — auth_required.
- `POST /{scope_type}/{scope_id}/search` — scope-bound search.
- `POST /search` — superadmin cross-scope search.
- `POST /bulk-create` / `bulk-update` / `bulk-purge` — superadmin only.
- `POST /my/bulk-create` / `my/bulk-update` — self-service USER scope.

REST v2 (`/v2/app-configs`, merged view):
- `GET /my/{name}` / `POST /my/search` — auth_required.
- `GET /{user_id}/{name}` / `POST /search` — superadmin only.

Adds the path-param classes for the new URL segments and wires the
handlers into `rest/v2/tree.py`.

Resolves BA-5830.

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

Author: jopemachine

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

@@ -0,0 +1,74 @@
+"""REST v2 handler for the AppConfig merged-view domain (BEP-1052 §5)."""
+
+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.request import (
+    GetUserAppConfigInput,
+    SearchAppConfigsInput,
+    SearchMyAppConfigsInput,
+)
+from ai.backend.logging import BraceStyleAdapter
+from ai.backend.manager.api.rest.v2.path_params import (
+    AppConfigMyNamePathParam,
+    AppConfigUserNamePathParam,
+)
+
+if TYPE_CHECKING:
+    from ai.backend.manager.api.adapters.app_config_fragment import AppConfigFragmentAdapter
+
+log: Final = BraceStyleAdapter(logging.getLogger(__spec__.name))
+
+
+class V2AppConfigHandler:
+    """REST v2 handler for the merged-view `AppConfig` surface.
+
+    Mounted at `/v2/app-configs/...`. The adapter lives on the Fragment
+    domain (`app_config_fragment`) because the merged view is computed
+    from fragment rows joined against `app_config_policies`.
+    """
+
+    def __init__(self, *, adapter: AppConfigFragmentAdapter) -> None:
+        self._adapter = adapter
+
+    # ── My (self-service) ────────────────────────────────────────
+
+    async def my_get(
+        self,
+        path: PathParam[AppConfigMyNamePathParam],
+    ) -> APIResponse:
+        """Read the caller's own merged AppConfig for `name`."""
+        result = await self._adapter.my_app_config(path.parsed.name)
+        return APIResponse.build(status_code=HTTPStatus.OK, response_model=result)
+
+    async def my_search(
+        self,
+        body: BodyParam[SearchMyAppConfigsInput],
+    ) -> APIResponse:
+        """Paginated merged-view search over the caller's own AppConfigs."""
+        result = await self._adapter.my_search_app_configs(body.parsed)
+        return APIResponse.build(status_code=HTTPStatus.OK, response_model=result)
+
+    # ── Admin ────────────────────────────────────────────────────
+
+    async def admin_get(
+        self,
+        path: PathParam[AppConfigUserNamePathParam],
+    ) -> APIResponse:
+        """Read a specific user's merged AppConfig (admin only)."""
+        result = await self._adapter.admin_get_user_app_config(
+            GetUserAppConfigInput(user_id=path.parsed.user_id, name=path.parsed.name)
+        )
+        return APIResponse.build(status_code=HTTPStatus.OK, response_model=result)
+
+    async def admin_search(
+        self,
+        body: BodyParam[SearchAppConfigsInput],
+    ) -> APIResponse:
+        """Cross-user merged-view search (admin only)."""
+        result = await self._adapter.admin_search_app_configs(body.parsed)
+        return APIResponse.build(status_code=HTTPStatus.OK, response_model=result)

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

@@ -0,0 +1,36 @@
+"""Route registration for v2 AppConfig merged-view endpoints (BEP-1052 §5)."""
+
+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 V2AppConfigHandler
+
+if TYPE_CHECKING:
+    from ai.backend.manager.api.rest.types import RouteDeps
+
+
+def register_v2_app_config_routes(
+    handler: V2AppConfigHandler,
+    route_deps: RouteDeps,
+) -> RouteRegistry:
+    """Register all v2 `/v2/app-configs/*` routes (BEP-1052 §4).
+
+    Read-only surface — writes go through `/v2/app-config-fragments/...`
+    (§4). Self-service routes land under the `/my/...` prefix so the
+    adapter can pin `(USER, current_user)` internally; admin routes
+    allow targeting any user id.
+    """
+    reg = RouteRegistry.create("app-configs", route_deps.cors_options)
+
+    # Self-service
+    reg.add("GET", "/my/{name}", handler.my_get, middlewares=[auth_required])
+    reg.add("POST", "/my/search", handler.my_search, middlewares=[auth_required])
+    # Admin
+    reg.add("POST", "/search", handler.admin_search, middlewares=[superadmin_required])
+    reg.add("GET", "/{user_id}/{name}", handler.admin_get, middlewares=[superadmin_required])
+
+    return reg

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

@@ -0,0 +1,124 @@
+"""REST v2 handler for the app-config fragment domain (BEP-1052 §4).
+
+Writes are **bulk-only** per BEP §3 — the single-item create / update /
+purge endpoints were removed in favour of `/bulk-create`,
+`/bulk-update`, `/bulk-purge` (admin) and `/my/bulk-create`,
+`/my/bulk-update` (self-service).
+"""
+
+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 (
+    AdminBulkCreateAppConfigFragmentsInput,
+    AdminBulkPurgeAppConfigFragmentsInput,
+    AdminBulkUpdateAppConfigFragmentsInput,
+    AppConfigFragmentKeyInput,
+    BulkCreateMyAppConfigFragmentsInput,
+    BulkUpdateMyAppConfigFragmentsInput,
+    SearchAppConfigFragmentsInput,
+)
+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
+
+    # ── Reads ────────────────────────────────────────────────────
+
+    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)
+
+    # ── Admin bulk writes (BEP-1052 §3) ──────────────────────────
+
+    async def admin_bulk_create(
+        self,
+        body: BodyParam[AdminBulkCreateAppConfigFragmentsInput],
+    ) -> APIResponse:
+        """Strict insert across any scope; per-item transactions (admin only)."""
+        result = await self._adapter.admin_bulk_create(body.parsed)
+        return APIResponse.build(status_code=HTTPStatus.OK, response_model=result)
+
+    async def admin_bulk_update(
+        self,
+        body: BodyParam[AdminBulkUpdateAppConfigFragmentsInput],
+    ) -> APIResponse:
+        """Wholesale JSON replacement; per-item transactions (admin only)."""
+        result = await self._adapter.admin_bulk_update(body.parsed)
+        return APIResponse.build(status_code=HTTPStatus.OK, response_model=result)
+
+    async def admin_bulk_purge(
+        self,
+        body: BodyParam[AdminBulkPurgeAppConfigFragmentsInput],
+    ) -> APIResponse:
+        """Cleanup-only deletion; absent keys are no-oped (admin only)."""
+        result = await self._adapter.admin_bulk_purge(body.parsed)
+        return APIResponse.build(status_code=HTTPStatus.OK, response_model=result)
+
+    # ── Self-service bulk writes (BEP-1052 §3) ───────────────────
+
+    async def my_bulk_create(
+        self,
+        body: BodyParam[BulkCreateMyAppConfigFragmentsInput],
+    ) -> APIResponse:
+        """Self-service bulk create on the caller's `USER` row."""
+        result = await self._adapter.my_bulk_create(body.parsed)
+        return APIResponse.build(status_code=HTTPStatus.OK, response_model=result)
+
+    async def my_bulk_update(
+        self,
+        body: BodyParam[BulkUpdateMyAppConfigFragmentsInput],
+    ) -> APIResponse:
+        """Self-service bulk update on the caller's `USER` row."""
+        result = await self._adapter.my_bulk_update(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/__init__.py

@@ -0,0 +1,48 @@
+"""Route registration for v2 app-config fragment endpoints (BEP-1052 §4)."""
+
+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 /get` reads a single row via body (three-field natural key).
+    - Scoped search mounts at `/{scope_type}/{scope_id}/search`.
+    - Admin cross-scope search + bulk writes are admin-only.
+    - `/my/bulk-create` and `/my/bulk-update` are self-service writes
+      on the caller's `USER` row (no `/my/bulk-purge` — admin-only
+      cleanup per BEP-1052 §3).
+    """
+    reg = RouteRegistry.create("app-config-fragments", route_deps.cors_options)
+
+    # Reads
+    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])
+    # Admin bulk writes (BEP-1052 §3 — bulk-only)
+    reg.add("POST", "/bulk-create", handler.admin_bulk_create, middlewares=[superadmin_required])
+    reg.add("POST", "/bulk-update", handler.admin_bulk_update, middlewares=[superadmin_required])
+    reg.add("POST", "/bulk-purge", handler.admin_bulk_purge, middlewares=[superadmin_required])
+    # Self-service bulk writes
+    reg.add("POST", "/my/bulk-create", handler.my_bulk_create, middlewares=[auth_required])
+    reg.add("POST", "/my/bulk-update", handler.my_bulk_update, middlewares=[auth_required])
+
+    return reg

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

@@ -9,6 +9,20 @@
 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 AppConfigMyNamePathParam(BaseRequestModel):
+    name: str = Field(description="Policy / config name.")
+
+
+class AppConfigUserNamePathParam(BaseRequestModel):
+    user_id: UUID = Field(description="Target user's UUID (admin only).")
+    name: str = Field(description="Policy / config name.")
+
+
 class DomainNamePathParam(BaseRequestModel):
     domain_name: str = Field(description="Domain name")
 

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

@@ -28,6 +28,10 @@ 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.handler import V2AppConfigHandler
+    from .app_config.registry import register_v2_app_config_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
@@ -115,6 +119,10 @@ def build_v2_routes(
 
     # Build all handlers (each takes its individual adapter)
     agent_handler = V2AgentHandler(adapter=adapters.agent)
+    # AppConfig merged-view handler reuses the Fragment adapter because the
+    # merged-view methods live on `AppConfigFragmentAdapter`.
+    app_config_handler = V2AppConfigHandler(adapter=adapters.app_config_fragment)
+    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)
@@ -171,6 +179,10 @@ 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_routes(app_config_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)