Implement governed tabular source snapshots

2026-07-28 11:13:22 +02:00
parent dd45d9bd36
commit ba5ccea5b0
17 changed files with 1332 additions and 2 deletions
@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from govoplan_core.core.access import (
+    CAPABILITY_AUTH_PERMISSION_EVALUATOR,
+    CAPABILITY_AUTH_PRINCIPAL_RESOLVER,
+)
+from govoplan_core.core.module_guards import (
+    drop_table_retirement_provider,
+    persistent_table_uninstall_guard,
+)
+from govoplan_core.core.modules import (
+    DocumentationTopic,
+    MigrationSpec,
+    ModuleInterfaceProvider,
+    ModuleManifest,
+    PermissionDefinition,
+    RoleTemplate,
+)
+from govoplan_core.core.tabular_sources import (
+    CAPABILITY_CONNECTORS_TABULAR_SNAPSHOT_WRITER,
+    CAPABILITY_CONNECTORS_TABULAR_SOURCES,
+)
+from govoplan_core.db.base import Base
+from govoplan_connectors.backend.db.models import ConnectorTabularSource
+from govoplan_connectors.backend.tabular_sources import (
+    ADMIN_SCOPE,
+    READ_SCOPE,
+    WRITE_SCOPE,
+    SqlTabularSourceProvider,
+)
+
+
+MODULE_ID = "connectors"
+MODULE_VERSION = "0.1.14"
+TABULAR_SOURCE_INTERFACE_VERSION = "0.1.0"
+
+
+def _permission(scope: str, label: str, description: str) -> PermissionDefinition:
+    module_id, resource, action = scope.split(":", 2)
+    return PermissionDefinition(
+        scope=scope,
+        label=label,
+        description=description,
+        category="Connectors",
+        level="tenant",
+        module_id=module_id,
+        resource=resource,
+        action=action,
+    )
+
+
+PERMISSIONS = (
+    _permission(
+        READ_SCOPE,
+        "View tabular sources",
+        "Discover and preview policy-visible tabular connector sources.",
+    ),
+    _permission(
+        WRITE_SCOPE,
+        "Manage tabular sources",
+        "Import and retire bounded tabular snapshots.",
+    ),
+    _permission(
+        ADMIN_SCOPE,
+        "Administer connector sources",
+        "Manage every tenant connector source and future source policies.",
+    ),
+)
+
+ROLE_TEMPLATES = (
+    RoleTemplate(
+        slug="connector_source_manager",
+        name="Connector source manager",
+        description="Discover, import, preview, and retire tabular sources.",
+        permissions=(READ_SCOPE, WRITE_SCOPE),
+    ),
+    RoleTemplate(
+        slug="connector_source_reader",
+        name="Connector source reader",
+        description="Discover and preview tabular connector sources.",
+        permissions=(READ_SCOPE,),
+    ),
+)
+
+
+def _router(_context):
+    from govoplan_connectors.backend.router import router
+
+    return router
+
+
+def _provider(_context) -> SqlTabularSourceProvider:
+    return SqlTabularSourceProvider()
+
+
+def _tenant_summary(session, tenant_id: str) -> dict[str, int]:
+    return {
+        "connector_tabular_sources": (
+            session.query(ConnectorTabularSource)
+            .filter(
+                ConnectorTabularSource.tenant_id == tenant_id,
+                ConnectorTabularSource.deleted_at.is_(None),
+            )
+            .count()
+        )
+    }
+
+
+manifest = ModuleManifest(
+    id=MODULE_ID,
+    name="Connectors",
+    version=MODULE_VERSION,
+    optional_dependencies=("access", "audit", "files", "policy"),
+    required_capabilities=(
+        CAPABILITY_AUTH_PRINCIPAL_RESOLVER,
+        CAPABILITY_AUTH_PERMISSION_EVALUATOR,
+    ),
+    provides_interfaces=(
+        ModuleInterfaceProvider(
+            name="connectors.tabular_sources",
+            version=TABULAR_SOURCE_INTERFACE_VERSION,
+        ),
+        ModuleInterfaceProvider(
+            name="connectors.tabular_snapshot_writer",
+            version=TABULAR_SOURCE_INTERFACE_VERSION,
+        ),
+    ),
+    permissions=PERMISSIONS,
+    role_templates=ROLE_TEMPLATES,
+    route_factory=_router,
+    capability_factories={
+        CAPABILITY_CONNECTORS_TABULAR_SOURCES: _provider,
+        CAPABILITY_CONNECTORS_TABULAR_SNAPSHOT_WRITER: _provider,
+    },
+    tenant_summary_providers=(_tenant_summary,),
+    migration_spec=MigrationSpec(
+        module_id=MODULE_ID,
+        metadata=Base.metadata,
+        script_location=str(Path(__file__).with_name("migrations") / "versions"),
+        retirement_supported=True,
+        retirement_provider=drop_table_retirement_provider(
+            ConnectorTabularSource,
+            label="Connectors",
+        ),
+        retirement_notes=(
+            "Destructive retirement drops connector-owned source snapshots after "
+            "the installer captures a database snapshot."
+        ),
+    ),
+    uninstall_guard_providers=(
+        persistent_table_uninstall_guard(
+            ConnectorTabularSource,
+            label="Connectors",
+        ),
+    ),
+    documentation=(
+        DocumentationTopic(
+            id="connectors.tabular-sources",
+            title="Governed tabular sources",
+            summary="Provider-neutral source discovery and bounded reads for Dataflow.",
+            body=(
+                "Connectors owns source configuration, access checks, schema discovery, "
+                "fingerprints, and bounded reads. Dataflow stores only opaque source "
+                "references and expected fingerprints. The first executable provider "
+                "imports immutable JSON or CSV snapshots; database and API providers "
+                "can implement the same capability without changing Dataflow."
+            ),
+            layer="available",
+            documentation_types=("admin", "user"),
+            audience=("operator", "module_admin", "power_user"),
+            related_modules=("dataflow", "files", "reporting", "risk_compliance"),
+            order=40,
+        ),
+    ),
+)
+
+
+def get_manifest() -> ModuleManifest:
+    return manifest
+
+
+__all__ = [
+    "MODULE_ID",
+    "MODULE_VERSION",
+    "TABULAR_SOURCE_INTERFACE_VERSION",
+    "get_manifest",
+    "manifest",
+]