imbi-api 2.12.2__tar.gz → 2.13.0__tar.gz

{imbi_api-2.12.2 → imbi_api-2.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imbi-api
-Version: 2.12.2
+Version: 2.13.0
 Summary: Imbi is a DevOps Service Management Platform designed to provide an efficient way to manage a large environment that contains many services and applications.
 Author-email: Alex Campbell <alexc@aweber.com>, Dave Shawley <daves@aweber.com>, "Gavin M. Roy" <gavinr@aweber.com>
 License: BSD-3-Clause
@@ -20,7 +20,7 @@ Requires-Dist: cyclonedx-python-lib<12,>=11.7
 Requires-Dist: fastapi
 Requires-Dist: filetype
 Requires-Dist: httpx<1,>=0.28.1
-Requires-Dist: imbi-common[databases,llm,sentry,server]==2.12.2
+Requires-Dist: imbi-common[databases,llm,sentry,server]==2.13.0
 Requires-Dist: jinja2
 Requires-Dist: jsonpatch>=1.33
 Requires-Dist: mcp>=1.26.0

{imbi_api-2.12.2 → imbi_api-2.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "imbi-api"
-version = "2.12.2"
+version = "2.13.0"
 description = "Imbi is a DevOps Service Management Platform designed to provide an efficient way to manage a large environment that contains many services and applications."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -28,7 +28,7 @@ dependencies = [
   "fastapi",
   "filetype",
   "httpx>=0.28.1,<1",
-  "imbi-common[databases,llm,sentry,server]==2.12.2",
+  "imbi-common[databases,llm,sentry,server]==2.13.0",
   "jinja2",
   "jsonpatch>=1.33",
   "mcp>=1.26.0",

{imbi_api-2.12.2 → imbi_api-2.13.0}/src/imbi_api/app.py

@@ -27,6 +27,7 @@ def create_app() -> fastapi.FastAPI:
             lifespans.score_worker_hook,
             lifespans.commit_sync_worker_hook,
             lifespans.pr_sync_worker_hook,
+            lifespans.maintenance_worker_hook,
             lifespans.identity_refresh_hook,
         ),
         version=version,

{imbi_api-2.12.2 → imbi_api-2.13.0}/src/imbi_api/auth/seed.py

@@ -378,6 +378,19 @@ STANDARD_PERMISSIONS: list[tuple[str, str, str, str]] = [
         'plugins:manage',
         'Install and uninstall plugins',
     ),
+    # Global maintenance operations
+    (
+        'admin:maintenance:read',
+        'admin',
+        'maintenance:read',
+        'View global maintenance operations',
+    ),
+    (
+        'admin:maintenance:manage',
+        'admin',
+        'maintenance:manage',
+        'Run and cancel global maintenance operations',
+    ),
     # Project plugin access
     (
         'project:configuration:read',

{imbi_api-2.12.2 → imbi_api-2.13.0}/src/imbi_api/endpoints/__init__.py

@@ -16,6 +16,7 @@ from .dashboard import dashboard_router
 from .events import events_router
 from .graph_query import graph_query_router
 from .local_auth import local_auth_router
+from .maintenance import maintenance_router
 from .mcp_servers import mcp_servers_router
 from .mfa import mfa_router
 from .oauth_metadata import oauth_metadata_router
@@ -46,6 +47,7 @@ prefixed_routers: list[fastapi.APIRouter] = [
     events_router,
     graph_query_router,
     local_auth_router,
+    maintenance_router,
     mcp_servers_router,
     me_identities_router,
     mfa_router,

imbi_api-2.13.0/src/imbi_api/endpoints/maintenance.py

@@ -0,0 +1,218 @@
+"""Global maintenance operation endpoints (admin Maintenance page).
+
+The operation list is registry-driven (:mod:`imbi_api.maintenance`):
+the UI renders whatever this returns, so adding an operation to the
+registry is all that is required for a new button to appear.
+"""
+
+import datetime
+import logging
+import typing
+
+import fastapi
+import pydantic
+from imbi_common import graph
+
+from imbi_api.auth import permissions
+from imbi_api.maintenance import (
+    OPERATIONS,
+    MaintenanceSlug,
+    OperationDefinition,
+    state,
+)
+from imbi_api.scoring import OptionalValkeyClient
+
+LOGGER = logging.getLogger(__name__)
+
+maintenance_router = fastapi.APIRouter(
+    prefix='/maintenance', tags=['Admin: Maintenance']
+)
+
+RequireRead = typing.Annotated[
+    permissions.AuthContext,
+    fastapi.Depends(
+        permissions.require_permission('admin:maintenance:read'),
+    ),
+]
+RequireManage = typing.Annotated[
+    permissions.AuthContext,
+    fastapi.Depends(
+        permissions.require_permission('admin:maintenance:manage'),
+    ),
+]
+
+
+class MaintenanceProgress(pydantic.BaseModel):
+    """Counters for an operation's current or last run."""
+
+    total: int = 0
+    remaining: int = 0
+    in_flight: int = 0
+    succeeded: int = 0
+    failed: int = 0
+    skipped: int = 0
+
+
+class MaintenanceOperation(pydantic.BaseModel):
+    """One registry operation merged with its run state."""
+
+    slug: str
+    label: str
+    description: str
+    running: bool
+    state: state.RunState
+    progress: MaintenanceProgress | None = None
+    started_at: datetime.datetime | None = None
+    started_by: str | None = None
+    completed_at: datetime.datetime | None = None
+    #: Per-project failure detail; only populated on the per-operation
+    #: GET to keep the list response small.
+    failures: dict[str, str] | None = None
+
+
+class MaintenanceRunResponse(pydantic.BaseModel):
+    """Acknowledgement that a run was started."""
+
+    run_id: str
+    total: int
+
+
+def _to_operation(
+    definition: OperationDefinition,
+    status: state.RunStatus,
+    failures: dict[str, str] | None = None,
+) -> MaintenanceOperation:
+    progress: MaintenanceProgress | None = None
+    if status.state != 'idle':
+        progress = MaintenanceProgress(
+            total=status.total,
+            remaining=status.remaining,
+            in_flight=status.in_flight,
+            succeeded=status.succeeded,
+            failed=status.failed,
+            skipped=status.skipped,
+        )
+    return MaintenanceOperation(
+        slug=definition.slug,
+        label=definition.label,
+        description=definition.description,
+        running=status.state == 'running',
+        state=status.state,
+        progress=progress,
+        started_at=status.started_at,
+        started_by=status.started_by,
+        completed_at=status.completed_at,
+        failures=failures,
+    )
+
+
+def _definition_or_404(slug: str) -> OperationDefinition:
+    definition = OPERATIONS.get(typing.cast('MaintenanceSlug', slug))
+    if definition is None:
+        raise fastapi.HTTPException(
+            status_code=404, detail=f'Unknown maintenance operation {slug!r}'
+        )
+    return definition
+
+
+@maintenance_router.get('/operations')
+async def list_maintenance_operations(
+    auth: RequireRead,
+    client: OptionalValkeyClient,
+) -> list[MaintenanceOperation]:
+    """The operation registry merged with each operation's run state."""
+    _ = auth
+    if client is None:
+        raise fastapi.HTTPException(
+            status_code=503,
+            detail='Maintenance state is unavailable '
+            '(Valkey is not connected).',
+        )
+    results: list[MaintenanceOperation] = []
+    for definition in OPERATIONS.values():
+        status = await state.read_status(client, definition.slug)
+        results.append(_to_operation(definition, status))
+    return results
+
+
+@maintenance_router.get('/operations/{slug}')
+async def get_maintenance_operation(
+    slug: str,
+    auth: RequireRead,
+    client: OptionalValkeyClient,
+) -> MaintenanceOperation:
+    """One operation's run state, including per-project failures."""
+    _ = auth
+    definition = _definition_or_404(slug)
+    if client is None:
+        raise fastapi.HTTPException(
+            status_code=503,
+            detail='Maintenance state is unavailable '
+            '(Valkey is not connected).',
+        )
+    status = await state.read_status(client, definition.slug)
+    failures = await state.read_failures(client, definition.slug)
+    return _to_operation(definition, status, failures or None)
+
+
+@maintenance_router.post('/operations/{slug}/run', status_code=202)
+async def run_maintenance_operation(
+    slug: str,
+    auth: RequireManage,
+    db: graph.Pool,
+    client: OptionalValkeyClient,
+) -> MaintenanceRunResponse:
+    """Start a global run of the operation across all projects."""
+    definition = _definition_or_404(slug)
+    if client is None:
+        raise fastapi.HTTPException(
+            status_code=503,
+            detail='Queueing is unavailable (Valkey is not connected).',
+        )
+    project_ids = await definition.enumerate(db)
+    status = await state.start_run(
+        client, definition.slug, project_ids, auth.principal_name
+    )
+    if status is None:
+        raise fastapi.HTTPException(
+            status_code=409,
+            detail=f'{definition.label} is already running.',
+        )
+    LOGGER.info(
+        'maintenance %s run %s started by %s (%d projects)',
+        definition.slug,
+        status.run_id,
+        auth.principal_name,
+        status.total,
+    )
+    return MaintenanceRunResponse(
+        run_id=status.run_id or '', total=status.total
+    )
+
+
+@maintenance_router.post('/operations/{slug}/cancel')
+async def cancel_maintenance_operation(
+    slug: str,
+    auth: RequireManage,
+    client: OptionalValkeyClient,
+) -> MaintenanceOperation:
+    """Cancel the operation's in-progress run."""
+    definition = _definition_or_404(slug)
+    if client is None:
+        raise fastapi.HTTPException(
+            status_code=503,
+            detail='Queueing is unavailable (Valkey is not connected).',
+        )
+    cancelled = await state.cancel_run(client, definition.slug)
+    if not cancelled:
+        raise fastapi.HTTPException(
+            status_code=409,
+            detail=f'{definition.label} is not running.',
+        )
+    LOGGER.info(
+        'maintenance %s run cancelled by %s',
+        definition.slug,
+        auth.principal_name,
+    )
+    status = await state.read_status(client, definition.slug)
+    return _to_operation(definition, status)

{imbi_api-2.12.2 → imbi_api-2.13.0}/src/imbi_api/endpoints/project_analysis.py

@@ -499,7 +499,7 @@ async def _collect_results(
     return results
 
 
-async def _run_and_persist(
+async def run_and_persist(
     db: graph.Graph,
     org_slug: str,
     project_id: str,
@@ -526,7 +526,7 @@ async def run_project_analysis(
         fastapi.Depends(permissions.require_permission('project:write')),
     ],
 ) -> AnalysisReport:
-    return await _run_and_persist(db, org_slug, project_id, auth)
+    return await run_and_persist(db, org_slug, project_id, auth)
 
 
 class RemediateRequest(pydantic.BaseModel):
@@ -659,7 +659,7 @@ async def remediate_project_finding(
     result = await _remediate_one(
         db, org_slug, project_id, body.plugin_id, body.remediation_id, auth
     )
-    report = await _run_and_persist(db, org_slug, project_id, auth)
+    report = await run_and_persist(db, org_slug, project_id, auth)
     return RemediateResponse(result=result, report=report)
 
 
@@ -728,5 +728,5 @@ async def remediate_all_project_findings(
                 result=result,
             )
         )
-    fresh = await _run_and_persist(db, org_slug, project_id, auth)
+    fresh = await run_and_persist(db, org_slug, project_id, auth)
     return RemediateAllResponse(outcomes=outcomes, report=fresh)

{imbi_api-2.12.2 → imbi_api-2.13.0}/src/imbi_api/lifespans.py

@@ -18,6 +18,7 @@ from imbi_api.commit_sync import queue as commit_sync_queue
 from imbi_api.email.client import EmailClient
 from imbi_api.email.templates import TemplateManager
 from imbi_api.identity import sweeper as identity_sweeper
+from imbi_api.maintenance import worker as maintenance_worker
 from imbi_api.plugins import lifecycle as plugin_lifecycle
 from imbi_api.pr_sync import queue as pr_sync_queue
 from imbi_api.scoring import queue as score_queue
@@ -199,6 +200,39 @@ async def pr_sync_worker_hook() -> abc.AsyncGenerator[None]:
             )
 
 
+@contextlib.asynccontextmanager
+async def maintenance_worker_hook() -> abc.AsyncGenerator[None]:
+    """Run the global maintenance operation consumer loop."""
+    try:
+        client = valkey.get_client()
+    except RuntimeError:
+        LOGGER.warning('Valkey unavailable; maintenance worker not started')
+        yield None
+        return
+    if _graph is None:
+        LOGGER.warning('Graph not ready; maintenance worker not started')
+        yield None
+        return
+    stop = asyncio.Event()
+    LOGGER.info('Maintenance worker starting')
+    consumer_task = asyncio.create_task(
+        maintenance_worker.run_worker(client, _graph, stop=stop)
+    )
+    try:
+        yield None
+    finally:
+        stop.set()
+        consumer_task.cancel()
+        try:
+            await consumer_task
+        except asyncio.CancelledError:
+            pass
+        except Exception:  # noqa: BLE001
+            LOGGER.warning(
+                'Maintenance worker task exited with error', exc_info=True
+            )
+
+
 @contextlib.asynccontextmanager
 async def score_worker_hook() -> abc.AsyncGenerator[None]:
     """Run the score-recompute consumer and the daily tick."""

imbi_api-2.13.0/src/imbi_api/maintenance/__init__.py

@@ -0,0 +1,9 @@
+"""Global maintenance operations (admin Maintenance page)."""
+
+from imbi_api.maintenance.registry import (
+    OPERATIONS,
+    MaintenanceSlug,
+    OperationDefinition,
+)
+
+__all__ = ['OPERATIONS', 'MaintenanceSlug', 'OperationDefinition']

imbi_api-2.13.0/src/imbi_api/maintenance/operations.py

@@ -0,0 +1,241 @@
+"""Per-project execute functions for global maintenance operations.
+
+Each ``execute_*`` runs one project's slice of a global run by reusing
+the same service code the per-project Doctor endpoints call.  Outcomes:
+
+- return ``'succeeded'`` / ``'skipped'`` (skipped means the operation
+  does not apply -- e.g. no integration provides the capability);
+- raise :class:`MaintenanceItemFailed` with a user-safe message for
+  recordable failures (raw detail belongs in logs only);
+- let :class:`~imbi_common.plugins.errors.PluginRateLimited` propagate
+  so the worker can requeue the project and pause the operation.
+
+Endpoint modules are imported inside function bodies (the
+``commit_sync.service`` pattern) so this module never pulls the
+endpoints package at import time.
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+import typing
+
+import fastapi
+from imbi_common import graph
+from imbi_common.plugins.errors import PluginRateLimited
+from valkey import asyncio as valkey
+
+from imbi_api import models
+from imbi_api.auth import permissions
+from imbi_api.scoring import queue as score_queue
+
+LOGGER = logging.getLogger(__name__)
+
+#: ``requested_by`` / ``principal_name`` recorded on work this runs.
+REQUESTED_BY = 'maintenance'
+
+ExecuteOutcome = typing.Literal['succeeded', 'skipped']
+
+_ORG_SLUG_QUERY: typing.LiteralString = (
+    'MATCH (p:Project {{id: {project_id}}})-[:OWNED_BY]->(:Team)'
+    '-[:BELONGS_TO]->(o:Organization) RETURN o.slug AS slug'
+)
+
+
+class MaintenanceItemFailed(Exception):
+    """One project's operation failed; the message is user-safe."""
+
+
+@functools.cache
+def _system_auth() -> permissions.AuthContext:
+    """Synthetic principal for background maintenance work.
+
+    Never persisted; exists so service functions that record
+    ``principal_name`` attribute the work to ``'maintenance'``.
+    """
+    return permissions.AuthContext(
+        auth_method='client_credentials',
+        service_account=models.ServiceAccount(
+            slug=REQUESTED_BY, display_name='Imbi Maintenance'
+        ),
+    )
+
+
+async def enumerate_all_projects(db: graph.Graph) -> list[str]:
+    """Every project id -- maintenance operations self-classify
+    inapplicable projects as skipped rather than pre-filtering (which
+    would cost a capability resolution per project up front)."""
+    return await score_queue.all_project_ids(db)
+
+
+async def _org_slug_for(db: graph.Graph, project_id: str) -> str | None:
+    rows = await db.execute(
+        _ORG_SLUG_QUERY, {'project_id': project_id}, ['slug']
+    )
+    if not rows:
+        return None
+    value = graph.parse_agtype(rows[0].get('slug'))
+    return str(value) if value else None
+
+
+async def execute_analysis(
+    db: graph.Graph, client: valkey.Valkey, project_id: str
+) -> ExecuteOutcome:
+    """Run the Doctor analysis and persist the report.
+
+    Per-plugin errors already surface as synthetic ``fail`` findings
+    inside the report, so an exception here is infrastructural.
+    """
+    from imbi_api.endpoints import project_analysis
+
+    org_slug = await _org_slug_for(db, project_id)
+    if org_slug is None:
+        return 'skipped'
+    await project_analysis.run_and_persist(
+        db, org_slug, project_id, _system_auth()
+    )
+    return 'succeeded'
+
+
+async def execute_commit_sync(
+    db: graph.Graph, client: valkey.Valkey, project_id: str
+) -> ExecuteOutcome:
+    """Full commit/tag backfill, mirroring the queue consumer's status
+    transitions so the per-project Doctor status stays truthful."""
+    from imbi_api.commit_sync import service
+
+    org_slug = await _org_slug_for(db, project_id)
+    if org_slug is None:
+        return 'skipped'
+    await service.set_status(
+        db, project_id, status='running', requested_by=REQUESTED_BY
+    )
+    try:
+        commits, tags = await service.run_sync(db, org_slug, project_id)
+    except service.CommitSyncUnavailable as exc:
+        await service.set_status(
+            db,
+            project_id,
+            status='failed',
+            requested_by=REQUESTED_BY,
+            error=str(exc),
+        )
+        return 'skipped'
+    except PluginRateLimited:
+        # Leave the project requeue-able; the worker pauses the op.
+        await service.set_status(
+            db, project_id, status='queued', requested_by=REQUESTED_BY
+        )
+        raise
+    except Exception as exc:
+        LOGGER.exception('maintenance commit-sync failed for %s', project_id)
+        message = 'Commit sync failed. See server logs for details.'
+        await service.set_status(
+            db,
+            project_id,
+            status='failed',
+            requested_by=REQUESTED_BY,
+            error=message,
+        )
+        raise MaintenanceItemFailed(message) from exc
+    await service.set_status(
+        db,
+        project_id,
+        status='success',
+        requested_by=REQUESTED_BY,
+        commits=commits,
+        tags=tags,
+    )
+    return 'succeeded'
+
+
+async def execute_pr_sync(
+    db: graph.Graph, client: valkey.Valkey, project_id: str
+) -> ExecuteOutcome:
+    """Full PR-history backfill; same shape as commit sync."""
+    from imbi_api.pr_sync import service
+
+    org_slug = await _org_slug_for(db, project_id)
+    if org_slug is None:
+        return 'skipped'
+    await service.set_status(
+        db, project_id, status='running', requested_by=REQUESTED_BY
+    )
+    try:
+        prs = await service.run_sync(db, org_slug, project_id)
+    except service.PRSyncUnavailable as exc:
+        await service.set_status(
+            db,
+            project_id,
+            status='failed',
+            requested_by=REQUESTED_BY,
+            error=str(exc),
+        )
+        return 'skipped'
+    except PluginRateLimited:
+        # Leave the project requeue-able; the worker pauses the op.
+        await service.set_status(
+            db, project_id, status='queued', requested_by=REQUESTED_BY
+        )
+        raise
+    except Exception as exc:
+        LOGGER.exception('maintenance pr-sync failed for %s', project_id)
+        message = 'PR sync failed. See server logs for details.'
+        await service.set_status(
+            db,
+            project_id,
+            status='failed',
+            requested_by=REQUESTED_BY,
+            error=message,
+        )
+        raise MaintenanceItemFailed(message) from exc
+    await service.set_status(
+        db,
+        project_id,
+        status='success',
+        requested_by=REQUESTED_BY,
+        prs=prs,
+    )
+    return 'succeeded'
+
+
+async def execute_deployment_resync(
+    db: graph.Graph, client: valkey.Valkey, project_id: str
+) -> ExecuteOutcome:
+    """Backfill recent remote deployments via the deployment plugin."""
+    from imbi_api.endpoints import project_deployments
+
+    org_slug = await _org_slug_for(db, project_id)
+    if org_slug is None:
+        return 'skipped'
+    try:
+        await project_deployments.resync_for_project(
+            db,
+            org_slug=org_slug,
+            project_id=project_id,
+            auth=_system_auth(),
+            limit=1,
+        )
+    except fastapi.HTTPException as exc:
+        # 404: no deployment capability bound; 400: the plugin doesn't
+        # support deployment sync. Neither is a failure of this run.
+        if exc.status_code in (400, 404):
+            return 'skipped'
+        raise MaintenanceItemFailed(str(exc.detail)) from exc
+    return 'succeeded'
+
+
+async def execute_rescore(
+    db: graph.Graph, client: valkey.Valkey, project_id: str
+) -> ExecuteOutcome:
+    """Enqueue a score recompute onto the existing scoring stream.
+
+    Succeeded means enqueued -- the scoring workers do the computation
+    with their own debounce/DLQ/history handling. Skipped means the
+    project was debounced (a recompute is already queued).
+    """
+    enqueued = await score_queue.enqueue_recompute(
+        client, project_id, 'bulk_rescore', REQUESTED_BY
+    )
+    return 'succeeded' if enqueued else 'skipped'