ocmo-api 0.8.19__py3-none-any.whl

core/api/audit.py

@@ -0,0 +1,244 @@
+from datetime import datetime
+from uuid import UUID
+
+from ninja import Query, Router
+from ninja.pagination import paginate
+
+from ..managers.audit import AuditListFilters, AuditManager
+from ..managers.auth import AuthManager
+from ..managers.namespace import NamespaceManager
+from ..operation_ids import (
+    GET_GLOBAL_AUDIT_EVENT,
+    GET_NAMESPACE_AUDIT_EVENT,
+    LIST_GLOBAL_AUDIT,
+    LIST_NAMESPACE_AUDIT,
+    NAMESPACE_AUDIT_RESOLVE_SERIES,
+    NAMESPACE_AUDIT_TIMELINE,
+)
+from ..schemas import ErrorSchema
+from ..schemas.audit import AuditEventSchema, AuditTimelineEntrySchema, ResolveSeriesSchema
+
+router = Router()
+
+
+@router.get(
+    "/audit/",
+    response=list[AuditEventSchema],
+    tags=["Audit"],
+    operation_id=LIST_GLOBAL_AUDIT,
+)
+@paginate
+def list_global_audit(
+    request,
+    auth_id: str | None = None,
+    auth_email: str | None = None,
+    auth_type: str | None = None,
+    object_type: str | None = None,
+    object_id: str | None = None,
+    http_method: str | None = None,
+    api_endpoint: str | None = None,
+    permission_ok: bool | None = None,
+    resolve_type: str | None = None,
+    from_cache: bool | None = None,
+    event_kind: str | None = None,
+    category: str | None = None,
+    parent_event_id: UUID | None = None,
+    client_ip: str | None = None,
+    user_agent: str | None = None,
+    token_number: int | None = None,
+    object_version: int | None = None,
+    operation: str | None = None,
+    subresource_type: str | None = None,
+    subresource: str | None = None,
+    event_id: UUID | None = None,
+    error: str | None = None,
+    namespace: str | None = None,
+    search: str | None = None,
+    occurred_from: datetime | None = Query(None, alias="from"),
+    occurred_to: datetime | None = Query(None, alias="to"),
+):
+    """Cross-namespace audit log (global admin only)."""
+    auth = AuthManager.from_request(request)
+    AuditManager.bind(request, auth)
+    filters = AuditListFilters(
+        auth_id=auth_id,
+        auth_email=auth_email,
+        auth_type=auth_type,
+        object_type=object_type,
+        object_id=object_id,
+        http_method=http_method,
+        api_endpoint=api_endpoint,
+        permission_ok=permission_ok,
+        resolve_type=resolve_type,
+        from_cache=from_cache,
+        event_kind=event_kind,
+        category=category,
+        parent_event_id=parent_event_id,
+        client_ip=client_ip,
+        user_agent=user_agent,
+        token_number=token_number,
+        object_version=object_version,
+        operation=operation,
+        subresource_type=subresource_type,
+        subresource=subresource,
+        event_id=event_id,
+        error=error,
+        namespace_name=namespace,
+        occurred_from=occurred_from,
+        occurred_to=occurred_to,
+    )
+    return AuditManager(auth=auth).list(filters, search=search)
+
+
+@router.get(
+    "/audit/{event_id}",
+    response={200: AuditEventSchema, 404: ErrorSchema},
+    tags=["Audit"],
+    operation_id=GET_GLOBAL_AUDIT_EVENT,
+)
+def get_global_audit_event(request, event_id: str):
+    """Get a single audit event (global admin only)."""
+    auth = AuthManager.from_request(request)
+    AuditManager.bind(request, auth)
+    return AuditManager(auth=auth).get(event_id)
+
+
+@router.get(
+    "/ns/{namespace}/~audit/",
+    response={200: list[AuditEventSchema], 404: ErrorSchema},
+    tags=["Audit"],
+    operation_id=LIST_NAMESPACE_AUDIT,
+)
+@paginate
+def list_namespace_audit(
+    request,
+    namespace: str,
+    auth_id: str | None = None,
+    auth_email: str | None = None,
+    auth_type: str | None = None,
+    object_type: str | None = None,
+    object_id: str | None = None,
+    http_method: str | None = None,
+    api_endpoint: str | None = None,
+    permission_ok: bool | None = None,
+    resolve_type: str | None = None,
+    from_cache: bool | None = None,
+    event_kind: str | None = None,
+    category: str | None = None,
+    parent_event_id: UUID | None = None,
+    client_ip: str | None = None,
+    user_agent: str | None = None,
+    token_number: int | None = None,
+    object_version: int | None = None,
+    operation: str | None = None,
+    subresource_type: str | None = None,
+    subresource: str | None = None,
+    event_id: UUID | None = None,
+    error: str | None = None,
+    search: str | None = None,
+    occurred_from: datetime | None = Query(None, alias="from"),
+    occurred_to: datetime | None = Query(None, alias="to"),
+):
+    """Namespace-scoped audit log (requires namespace:audit or global admin)."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    filters = AuditListFilters(
+        auth_id=auth_id,
+        auth_email=auth_email,
+        auth_type=auth_type,
+        object_type=object_type,
+        object_id=object_id,
+        http_method=http_method,
+        api_endpoint=api_endpoint,
+        permission_ok=permission_ok,
+        resolve_type=resolve_type,
+        from_cache=from_cache,
+        event_kind=event_kind,
+        category=category,
+        parent_event_id=parent_event_id,
+        client_ip=client_ip,
+        user_agent=user_agent,
+        token_number=token_number,
+        object_version=object_version,
+        operation=operation,
+        subresource_type=subresource_type,
+        subresource=subresource,
+        event_id=event_id,
+        error=error,
+        namespace_name=namespace,
+        occurred_from=occurred_from,
+        occurred_to=occurred_to,
+    )
+    return AuditManager(auth=auth, namespace=ns).list(filters, search=search)
+
+
+@router.get(
+    "/ns/{namespace}/~audit/timeline/",
+    response={200: list[AuditTimelineEntrySchema], 404: ErrorSchema},
+    tags=["Audit"],
+    operation_id=NAMESPACE_AUDIT_TIMELINE,
+)
+@paginate
+def namespace_audit_timeline(
+    request,
+    namespace: str,
+    object_id: str,
+    object_type: str,
+    search: str | None = None,
+):
+    """Item-scoped audit timeline (requires ``<object_type>:audit`` on ``object_id``)."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    return AuditManager(auth=auth, namespace=ns).item_timeline(
+        object_id,
+        object_type,
+        search=search,
+    )
+
+
+@router.get(
+    "/ns/{namespace}/~audit/resolve-series/",
+    response={200: ResolveSeriesSchema, 404: ErrorSchema},
+    tags=["Audit"],
+    operation_id=NAMESPACE_AUDIT_RESOLVE_SERIES,
+)
+def namespace_audit_resolve_series(
+    request,
+    namespace: str,
+    object_id: str,
+    object_type: str,
+    occurred_from: datetime = Query(..., alias="from"),
+    occurred_to: datetime = Query(..., alias="to"),
+    bucket_seconds: int = Query(..., ge=1800),
+):
+    """Time-bucketed direct vs nested resolve counts for a tree object."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    buckets = AuditManager(auth=auth, namespace=ns).resolve_stats_series(
+        object_id=object_id,
+        object_type=object_type,
+        since=occurred_from,
+        until=occurred_to,
+        bucket_seconds=bucket_seconds,
+    )
+    return {
+        "bucket_seconds": bucket_seconds,
+        "buckets": buckets,
+    }
+
+
+@router.get(
+    "/ns/{namespace}/~audit/{event_id}",
+    response={200: AuditEventSchema, 404: ErrorSchema},
+    tags=["Audit"],
+    operation_id=GET_NAMESPACE_AUDIT_EVENT,
+)
+def get_namespace_audit_event(request, namespace: str, event_id: str):
+    """Get a single audit event within a namespace."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    return AuditManager(auth=auth, namespace=ns).get(event_id)

core/api/auth.py

@@ -0,0 +1,50 @@
+from datetime import UTC, datetime
+
+from ninja import Router
+
+from ocmoapi.auth import resolver_auth
+from ocmoapi.oauth2_provider import oauth2_auth
+
+from ..managers.audit import client_ip_from_request
+from ..managers.auth import AuthManager
+from ..managers.namespace import NamespaceManager
+from ..operation_ids import CAN_I, WHOAMI
+from ..schemas import CanIRequestSchema, CanIResponseSchema, WhoAmISchema
+
+router = Router()
+
+_auth = [resolver_auth, oauth2_auth]
+
+
+@router.get("/auth/whoami/", response=WhoAmISchema, tags=["Auth"], auth=_auth, operation_id=WHOAMI)
+def who_are_me(request):
+    """Return information about current authenticated user or resolver."""
+    return AuthManager.from_request(request).to_whoami()
+
+
+@router.post(
+    "/auth/can-i/",
+    response=CanIResponseSchema,
+    tags=["Auth"],
+    auth=_auth,
+    operation_id=CAN_I,
+)
+def can_i(request, payload: CanIRequestSchema):
+    """Probe whether the current identity may perform requested operations."""
+    auth = AuthManager.from_request(request)
+
+    namespace = None
+    if payload.namespace:
+        namespace = NamespaceManager(payload.namespace, auth=auth).get_or_raise()
+
+    allowed = auth.probe_permissions(
+        payload.operations,
+        namespace_name=payload.namespace,
+        namespace=namespace,
+        resource=payload.resource,
+        request_ctx={
+            "time": datetime.now(UTC),
+            "ip": client_ip_from_request(request),
+        },
+    )
+    return {"allowed": allowed}

core/api/config.py

@@ -0,0 +1,96 @@
+from typing import Any
+
+from ninja import Body, Query, Router
+
+from ocmoapi.oauth2_provider import oauth2_auth
+
+from ..managers.audit import AuditManager
+from ..managers.auth import AuthManager
+from ..managers.namespace import NamespaceManager
+from ..managers.tree import TreeManager
+from ..operation_ids import (
+    CREATE_CONFIG,
+    GET_CONFIG_DATA_SCHEMA,
+    GET_CONFIG_METADATA_SCHEMA,
+    UPDATE_CONFIG,
+)
+from ..schemas import AnyExtendedNodeSchema, ErrorSchema
+from ..schemas.metadata_json_schema import build_config_metadata_json_schema
+from ..schemas.requests import ConfigDocument
+from ._common import root_model_openapi_extension
+
+router = Router()
+
+
+@router.get(
+    "/~config-metadata-schema",
+    response=dict[str, Any],
+    tags=["Config"],
+    auth=oauth2_auth,
+    summary="Config metadata block JSON Schema",
+    operation_id=GET_CONFIG_METADATA_SCHEMA,
+)
+def get_config_metadata_schema(request):
+    """Return JSON Schema for the top-level config metadata block (e.g. ``_ocmo``)."""
+    return build_config_metadata_json_schema()
+
+
+@router.get(
+    "/ns/{namespace}/~config-schema/{path:path}",
+    response={200: dict[str, Any], 404: ErrorSchema},
+    tags=["Config"],
+    auth=oauth2_auth,
+    summary="Config data JSON Schema",
+    operation_id=GET_CONFIG_DATA_SCHEMA,
+)
+def get_config_data_schema(
+    request,
+    namespace: str,
+    path: str,
+    version: str = Query("latest"),
+):
+    """Return JSON Schema for a config's data body, if one is defined."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    return TreeManager(ns, path, auth=auth).get_config_data_json_schema(version=version)
+
+
+@router.post(
+    "/ns/{namespace}/~config/~create/{path:path}",
+    response={201: AnyExtendedNodeSchema, 409: ErrorSchema, 413: ErrorSchema, 422: ErrorSchema},
+    tags=["Config"],
+    openapi_extra=root_model_openapi_extension(ConfigDocument),
+    operation_id=CREATE_CONFIG,
+)
+def create_config(
+    request,
+    namespace: str,
+    path: str,
+    document: ConfigDocument = Body(...),
+):
+    """Create a new Config at the specified path."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    item = TreeManager(ns, path, auth=auth).create_item(document.root, "config")
+    return 201, item
+
+
+@router.put(
+    "/ns/{namespace}/~config/~update/{path:path}",
+    response={200: AnyExtendedNodeSchema, 404: ErrorSchema, 413: ErrorSchema, 422: ErrorSchema},
+    tags=["Config"],
+    openapi_extra=root_model_openapi_extension(ConfigDocument),
+    operation_id=UPDATE_CONFIG,
+)
+def update_config(
+    request,
+    namespace: str,
+    path: str,
+    document: ConfigDocument = Body(...),
+):
+    """Update an existing Config. Creates a new version only when content changes."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    return TreeManager(ns, path, auth=auth).update_item(document.root)

core/api/errors.py

@@ -0,0 +1,65 @@
+"""Shared helpers for API error responses."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.core.exceptions import ValidationError as DjangoValidationError
+
+from ..validation_errors import (
+    format_ninja_validation_errors,
+    format_pydantic_validation_error,
+    is_response_validation_error,
+)
+
+__all__ = [
+    "create_error_response",
+    "error_payload",
+    "format_django_validation_error",
+    "format_ninja_validation_errors",
+    "format_pydantic_validation_error",
+    "is_response_validation_error",
+]
+
+
+def format_django_validation_error(exc: DjangoValidationError) -> list[str]:
+    """Return human-readable validation messages with field names when available."""
+    message_dict = getattr(exc, "message_dict", None)
+    if message_dict:
+        lines: list[str] = []
+        for field, messages in message_dict.items():
+            for message in messages:
+                if field in (None, "__all__"):
+                    lines.append(str(message))
+                else:
+                    lines.append(f"{field}: {message}")
+        return lines
+    return [str(message) for message in exc.messages]
+
+
+def audit_event_id_from_exception(exc: BaseException) -> str | None:
+    """Return audit event UUID attached to *exc*, if any."""
+    audit_id = getattr(exc, "audit_event_id", None)
+    if audit_id is None:
+        return None
+    return str(audit_id)
+
+
+def error_payload(exc: BaseException, error: Any, **extra: Any) -> dict[str, Any]:
+    """Build a JSON error body, including audit_event_id when present on *exc*."""
+    payload: dict[str, Any] = {"error": error, **extra}
+    if isinstance(error, list):
+        payload["errors"] = error
+    audit_id = audit_event_id_from_exception(exc)
+    if audit_id:
+        payload["audit_event_id"] = audit_id
+    return payload
+
+
+def create_error_response(api, request, exc: BaseException, error: Any, status: int, **extra: Any):
+    """Create a Ninja response for an application error."""
+    return api.create_response(
+        request,
+        error_payload(exc, error, **extra),
+        status=status,
+    )

core/api/global_permissions.py

@@ -0,0 +1,107 @@
+from ninja import Query, Router
+
+from ..managers.audit import AuditManager
+from ..managers.auth import AuthManager
+from ..managers.global_permissions import GlobalPermissionsManager
+from ..operation_ids import (
+    CREATE_GLOBAL_PERMISSION,
+    DELETE_GLOBAL_PERMISSION,
+    GET_GLOBAL_PERMISSION,
+    LIST_GLOBAL_PERMISSIONS,
+    MOVE_GLOBAL_PERMISSION,
+    UPDATE_GLOBAL_PERMISSION,
+)
+from ..schemas import (
+    ErrorSchema,
+    GlobalPermissionRuleMovePayload,
+    GlobalPermissionRulePayload,
+    GlobalPermissionRuleSchema,
+    GlobalPermissionRulesListSchema,
+    InfoSchema,
+)
+
+router = Router()
+
+
+@router.get(
+    "/global-permissions/",
+    response=GlobalPermissionRulesListSchema,
+    tags=["Global Permissions"],
+    operation_id=LIST_GLOBAL_PERMISSIONS,
+)
+def list_global_permissions(
+    request,
+    limit: int = Query(100, ge=1),
+    offset: int = Query(0, ge=0),
+):
+    """Return all Global Permission rules in evaluation order."""
+    auth = AuthManager.from_request(request)
+    AuditManager.bind(request, auth)
+    return GlobalPermissionsManager(auth=auth).list(limit=limit, offset=offset)
+
+
+@router.post(
+    "/global-permissions/",
+    response={201: GlobalPermissionRuleSchema, 422: ErrorSchema},
+    tags=["Global Permissions"],
+    operation_id=CREATE_GLOBAL_PERMISSION,
+)
+def create_global_permission(request, payload: GlobalPermissionRulePayload):
+    """Append a new Global Permission rule at the end of the ordered list."""
+    auth = AuthManager.from_request(request)
+    AuditManager.bind(request, auth)
+    rule = GlobalPermissionsManager(auth=auth).create(payload)
+    return 201, rule
+
+
+@router.get(
+    "/global-permissions/{rule_id}",
+    response={200: GlobalPermissionRuleSchema, 404: ErrorSchema},
+    tags=["Global Permissions"],
+    operation_id=GET_GLOBAL_PERMISSION,
+)
+def get_global_permission(request, rule_id: str):
+    """Get a single Global Permission rule."""
+    auth = AuthManager.from_request(request)
+    AuditManager.bind(request, auth)
+    return GlobalPermissionsManager(auth=auth).get(rule_id)
+
+
+@router.put(
+    "/global-permissions/{rule_id}",
+    response={200: GlobalPermissionRuleSchema, 404: ErrorSchema},
+    tags=["Global Permissions"],
+    operation_id=UPDATE_GLOBAL_PERMISSION,
+)
+def update_global_permission(request, rule_id: str, payload: GlobalPermissionRulePayload):
+    """Replace a Global Permission rule."""
+    auth = AuthManager.from_request(request)
+    AuditManager.bind(request, auth)
+    return GlobalPermissionsManager(auth=auth).update(rule_id, payload)
+
+
+@router.delete(
+    "/global-permissions/{rule_id}",
+    response={204: InfoSchema, 404: ErrorSchema},
+    tags=["Global Permissions"],
+    operation_id=DELETE_GLOBAL_PERMISSION,
+)
+def delete_global_permission(request, rule_id: str):
+    """Delete a Global Permission rule."""
+    auth = AuthManager.from_request(request)
+    AuditManager.bind(request, auth)
+    GlobalPermissionsManager(auth=auth).delete(rule_id)
+    return 204, {"details": "Rule deleted"}
+
+
+@router.post(
+    "/global-permissions/{rule_id}/~move/",
+    response={200: GlobalPermissionRuleSchema, 404: ErrorSchema},
+    tags=["Global Permissions"],
+    operation_id=MOVE_GLOBAL_PERMISSION,
+)
+def move_global_permission(request, rule_id: str, payload: GlobalPermissionRuleMovePayload):
+    """Reorder a Global Permission rule by setting a new position."""
+    auth = AuthManager.from_request(request)
+    AuditManager.bind(request, auth)
+    return GlobalPermissionsManager(auth=auth).move(rule_id, payload.position)

core/api/lock.py

@@ -0,0 +1,99 @@
+from ninja import Query, Router
+
+from ..managers.audit import AuditManager
+from ..managers.auth import AuthManager
+from ..managers.lock import LockManager
+from ..managers.namespace import NamespaceManager
+from ..operation_ids import (
+    CREATE_LOCK,
+    DELETE_LOCK,
+    GET_LOCK,
+    LIST_LOCKS,
+    REPLACE_LOCK,
+)
+from ..schemas import ErrorSchema, LockSchema, LocksListSchema
+from ..schemas.requests import LockPayload
+
+router = Router()
+
+
+@router.get(
+    "/ns/{namespace}/~lock/",
+    response={200: LocksListSchema, 404: ErrorSchema},
+    tags=["Lock"],
+    operation_id=LIST_LOCKS,
+)
+def list_locks(
+    request,
+    namespace: str,
+    limit: int = Query(100, ge=1),
+    offset: int = Query(0, ge=0),
+):
+    """List all active locks in the namespace."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    return LockManager(ns, "*", auth=auth).list_active(limit=limit, offset=offset)
+
+
+@router.get(
+    "/ns/{namespace}/~lock/{path:path}",
+    response={200: LockSchema, 404: ErrorSchema},
+    tags=["Lock"],
+    operation_id=GET_LOCK,
+)
+def get_lock(request, namespace: str, path: str):
+    """Get lock details for a path."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    return LockManager(ns, path, auth=auth).get()
+
+
+@router.post(
+    "/ns/{namespace}/~lock/{path:path}",
+    response={201: LockSchema, 404: ErrorSchema, 409: ErrorSchema, 422: ErrorSchema},
+    tags=["Lock"],
+    operation_id=CREATE_LOCK,
+)
+def create_lock(request, namespace: str, path: str, payload: LockPayload):
+    """Create a lock on an existing tree path. Returns 409 if already locked."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    return 201, LockManager(ns, path, auth=auth).create(
+        reason=payload.reason,
+        expires_at=payload.expires_at,
+    )
+
+
+@router.put(
+    "/ns/{namespace}/~lock/{path:path}",
+    response={200: LockSchema, 404: ErrorSchema, 422: ErrorSchema},
+    tags=["Lock"],
+    operation_id=REPLACE_LOCK,
+)
+def replace_lock(request, namespace: str, path: str, payload: LockPayload):
+    """Replace an existing lock (extend expiry or update reason)."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    return LockManager(ns, path, auth=auth).replace(
+        reason=payload.reason,
+        expires_at=payload.expires_at,
+    )
+
+
+@router.delete(
+    "/ns/{namespace}/~lock/{path:path}",
+    response={204: None, 404: ErrorSchema},
+    tags=["Lock"],
+    operation_id=DELETE_LOCK,
+)
+def delete_lock(request, namespace: str, path: str):
+    """Remove a lock from a path."""
+    auth = AuthManager.from_request(request)
+    ns = NamespaceManager(namespace, auth=auth).get_or_raise()
+    AuditManager.bind(request, auth, namespace=ns)
+    LockManager(ns, path, auth=auth).delete()
+    return 204, None