analogcloud-common 0.2.0__tar.gz → 0.2.1__tar.gz

{analogcloud_common-0.2.0 → analogcloud_common-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: analogcloud-common
-Version: 0.2.0
+Version: 0.2.1
 Summary: Common data models and storage components for Analog Cloud
 Author-Email: Anabrid <info@anabrid.com>
 Requires-Python: <4.0,>=3.11

{analogcloud_common-0.2.0 → analogcloud_common-0.2.1}/pyproject.toml

@@ -62,7 +62,7 @@ dependencies = [
     "aioboto3>=15.5.0",
 ]
 name = "analogcloud-common"
-version = "0.2.0"
+version = "0.2.1"
 description = "Common data models and storage components for Analog Cloud"
 readme = "README.md"
 

{analogcloud_common-0.2.0 → analogcloud_common-0.2.1}/src/anabrid/cloud/models/api/v1.py

@@ -30,6 +30,43 @@ class SystemStatusResponse(BaseModel):
     uptime: int
 
 
+class ComponentVersion(BaseModel):
+    """Build identity of one running component (server or worker)."""
+
+    component: str
+    version: str
+    git_sha: str | None = None
+    git_tag: str | None = None
+    environment: str | None = None
+    hostname: str | None = None
+
+
+class WorkerVersion(ComponentVersion):
+    """Build identity of one worker process, as reported over Celery remote control.
+
+    ``dependencies`` carries the installed versions of the worker's notable
+    third-party packages (the compiler and the device library).
+    """
+
+    worker_type: str | None = None
+    queue: str | None = None
+    dependencies: dict[str, str | None] = Field(default_factory=dict)
+    error: str | None = None
+
+
+class SystemVersionResponse(BaseModel):
+    """GET /api/v1/system/version response.
+
+    ``workers`` lists every worker that answered the broadcast within the
+    timeout; ``workers_reachable`` is ``False`` when the broker could not be
+    asked at all, which is different from no worker answering.
+    """
+
+    server: ComponentVersion
+    workers: list[WorkerVersion]
+    workers_reachable: bool
+
+
 class DeviceResponse(BaseModel):
     """Device information for GET /api/v1/devices responses.
 

{analogcloud_common-0.2.0 → analogcloud_common-0.2.1}/src/anabrid/cloud/models/celery.py

@@ -5,6 +5,9 @@ COMPILE_QUEUE = "compilation"
 RUN_TASK_NAME = "run"
 # Run queue is the device name (dynamic, no constant).
 
+# Celery remote-control command every worker answers with its build identity.
+WORKER_VERSION_COMMAND = "analogcloud_version"
+
 RABBIT_MAX_PRIORITY = 10
 RABBIT_DEFAULT_PRIORITY = 1
 

analogcloud_common-0.2.1/src/anabrid/cloud/storage/metrics.py

@@ -0,0 +1,160 @@
+"""Aggregate task statistics for the metrics endpoint.
+
+Everything here is derived from the ``task_states`` history table, which
+records one timestamped row per state transition. Waiting time is the
+distance from a task's QUEUED row to its first INPROGRESS row; working
+time is the distance from that INPROGRESS row to the task's last terminal
+row. Totals are cumulative over the whole table, which makes them
+monotonic as long as history is kept and lets a scraper take rates.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from sqlalchemy import and_, extract, func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ..models.db import (
+    RunTask,
+    Task,
+    TaskState,
+    latest_task_state_subquery,
+    queued_task_state_subquery,
+)
+from ..models.enums import TaskStateEnum
+
+ACTIVE_STATES: tuple[TaskStateEnum, ...] = (
+    TaskStateEnum.QUEUED,
+    TaskStateEnum.INPROGRESS,
+)
+TERMINAL_STATES: tuple[TaskStateEnum, ...] = (
+    TaskStateEnum.SUCCEEDED,
+    TaskStateEnum.FAILED,
+    TaskStateEnum.CANCELLED,
+)
+TASK_TYPES: tuple[str, ...] = ("compile", "run")
+
+
+@dataclass(frozen=True)
+class DurationStats:
+    """Count and summed seconds of one group of durations."""
+
+    count: int
+    total_seconds: float
+
+
+@dataclass
+class TaskStatistics:
+    """Snapshot of task counts and durations, keyed by label tuples.
+
+    ``device`` is the run task's device name, or ``""`` for compile tasks.
+    """
+
+    current: dict[tuple[str, str], int] = field(default_factory=dict)
+    """``(type, state)`` -> number of tasks currently in that active state."""
+
+    finished: dict[tuple[str, str], int] = field(default_factory=dict)
+    """``(type, state)`` -> number of terminal transitions recorded."""
+
+    wait: dict[tuple[str, str], DurationStats] = field(default_factory=dict)
+    """``(type, device)`` -> QUEUED to INPROGRESS durations."""
+
+    work: dict[tuple[str, str, str], DurationStats] = field(default_factory=dict)
+    """``(type, device, terminal state)`` -> INPROGRESS to terminal durations."""
+
+
+def _state_value(state: object) -> str:
+    return state.value if isinstance(state, TaskStateEnum) else str(state)
+
+
+async def collect_task_statistics(session: AsyncSession) -> TaskStatistics:
+    """Run the aggregate queries and return a :class:`TaskStatistics`."""
+    stats = TaskStatistics()
+    latest = latest_task_state_subquery()
+    # The run_tasks table itself rather than the RunTask entity: the entity
+    # shares the tasks table through joined inheritance, and joining it to
+    # Task makes SQLAlchemy alias it, which the GROUP BY cannot follow.
+    run_tasks = RunTask.__table__
+    device = func.coalesce(run_tasks.c.device_name, "")
+
+    current_stmt = (
+        select(Task.type, latest.c.state, func.count())
+        .join(latest, latest.c.task_id == Task.id)
+        .where(latest.c.rn == 1, latest.c.state.in_(ACTIVE_STATES))
+        .group_by(Task.type, latest.c.state)
+    )
+    for task_type, state, count in (await session.execute(current_stmt)).all():
+        stats.current[(task_type, _state_value(state))] = int(count)
+
+    finished_stmt = (
+        select(Task.type, TaskState.state, func.count())
+        .join(TaskState, TaskState.task_id == Task.id)
+        .where(TaskState.state.in_(TERMINAL_STATES))
+        .group_by(Task.type, TaskState.state)
+    )
+    for task_type, state, count in (await session.execute(finished_stmt)).all():
+        stats.finished[(task_type, _state_value(state))] = int(count)
+
+    queued = queued_task_state_subquery()
+    started = (
+        select(
+            TaskState.task_id.label("task_id"),
+            func.min(TaskState.timestamp).label("started_at"),
+        )
+        .where(TaskState.state == TaskStateEnum.INPROGRESS)
+        .group_by(TaskState.task_id)
+        .subquery("started_states")
+    )
+    ended = (
+        select(
+            TaskState.task_id.label("task_id"),
+            func.max(TaskState.timestamp).label("ended_at"),
+        )
+        .where(TaskState.state.in_(TERMINAL_STATES))
+        .group_by(TaskState.task_id)
+        .subquery("ended_states")
+    )
+
+    wait_stmt = (
+        select(
+            Task.type,
+            device,
+            func.count(),
+            func.coalesce(
+                func.sum(extract("epoch", started.c.started_at - queued.c.created_at)),
+                0.0,
+            ),
+        )
+        .join(queued, queued.c.task_id == Task.id)
+        .join(started, started.c.task_id == Task.id)
+        .outerjoin(run_tasks, run_tasks.c.id == Task.id)
+        .group_by(Task.type, device)
+    )
+    for task_type, dev, count, total in (await session.execute(wait_stmt)).all():
+        stats.wait[(task_type, dev)] = DurationStats(int(count), float(total))
+
+    work_stmt = (
+        select(
+            Task.type,
+            device,
+            latest.c.state,
+            func.count(),
+            func.coalesce(
+                func.sum(extract("epoch", ended.c.ended_at - started.c.started_at)),
+                0.0,
+            ),
+        )
+        .join(started, started.c.task_id == Task.id)
+        .join(ended, ended.c.task_id == Task.id)
+        .join(latest, and_(latest.c.task_id == Task.id, latest.c.rn == 1))
+        .outerjoin(run_tasks, run_tasks.c.id == Task.id)
+        .where(latest.c.state.in_(TERMINAL_STATES))
+        .group_by(Task.type, device, latest.c.state)
+    )
+    for task_type, dev, state, count, total in (await session.execute(work_stmt)).all():
+        stats.work[(task_type, dev, _state_value(state))] = DurationStats(
+            int(count), float(total)
+        )
+
+    return stats

analogcloud_common-0.2.1/src/anabrid/cloud/version.py

@@ -0,0 +1,89 @@
+"""Build identity of a running component: version, git revision, environment.
+
+The package version is stamped at build time (``X.Y.Z`` on a release tag,
+``X.Y.Z.devN+g<sha>`` otherwise). The git revision and tag are baked into
+the container images as ``ANALOGCLOUD_GIT_SHA`` / ``ANALOGCLOUD_GIT_TAG``;
+the deployment names itself through ``ANALOGCLOUD_ENVIRONMENT``. When an
+environment variable is absent, what can be derived from the version
+string is derived, and the rest is reported as unknown (``None``).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Callable, Mapping
+from dataclasses import asdict, dataclass
+from importlib import metadata
+
+_LOCAL_SHA = re.compile(r"\+g([0-9a-f]{6,40})")
+_RELEASE = re.compile(r"^\d+\.\d+\.\d+$")
+
+
+@dataclass(frozen=True)
+class BuildInfo:
+    """Identity of one running component."""
+
+    component: str
+    version: str
+    git_sha: str | None
+    git_tag: str | None
+    environment: str | None
+
+    def as_dict(self) -> dict[str, str | None]:
+        """Return the fields as a plain dict (JSON- and label-friendly)."""
+        return asdict(self)
+
+
+def distribution_version(
+    distribution: str,
+    *,
+    version_lookup: Callable[[str], str] = metadata.version,
+) -> str | None:
+    """Return the installed version of ``distribution`` or ``None`` if absent."""
+    try:
+        return version_lookup(distribution)
+    except metadata.PackageNotFoundError:
+        return None
+
+
+def build_info(
+    component: str,
+    *,
+    distribution: str | None = None,
+    env: Mapping[str, str] | None = None,
+    version_lookup: Callable[[str], str] = metadata.version,
+) -> BuildInfo:
+    """Return the :class:`BuildInfo` of ``component``.
+
+    Args:
+        component: Short component name (``server``, ``worker``).
+        distribution: Installed distribution to read the version from;
+            defaults to ``analogcloud-<component>``.
+        env: Environment mapping; defaults to ``os.environ``.
+        version_lookup: ``importlib.metadata.version`` or a stand-in.
+    """
+    env = os.environ if env is None else env
+    version = (
+        distribution_version(
+            distribution or f"analogcloud-{component}", version_lookup=version_lookup
+        )
+        or "unknown"
+    )
+
+    git_sha = env.get("ANALOGCLOUD_GIT_SHA") or None
+    if git_sha is None:
+        match = _LOCAL_SHA.search(version)
+        git_sha = match.group(1) if match else None
+
+    git_tag = env.get("ANALOGCLOUD_GIT_TAG") or None
+    if git_tag is None and _RELEASE.match(version):
+        git_tag = f"v{version}"
+
+    return BuildInfo(
+        component=component,
+        version=version,
+        git_sha=git_sha,
+        git_tag=git_tag,
+        environment=env.get("ANALOGCLOUD_ENVIRONMENT") or None,
+    )

analogcloud_common-0.2.1/tests/test_storage_metrics.py

@@ -0,0 +1,109 @@
+"""Tests for anabrid.cloud.storage.metrics.collect_task_statistics (real Postgres)."""
+
+from datetime import datetime, timedelta
+from uuid import uuid4
+
+import pytest
+
+from anabrid.cloud.models.db import CompileTask, Device, RunTask, TaskState
+from anabrid.cloud.models.enums import DeviceTypeEnum, TaskStateEnum
+from anabrid.cloud.storage import BlobHandle
+from anabrid.cloud.storage.metrics import DurationStats, collect_task_statistics
+
+T0 = datetime(2026, 1, 1, 12, 0, 0)
+
+
+def _compile_task() -> CompileTask:
+    return CompileTask(
+        user_id="u", ode_source="x' = -x", backend="redac", k0=None, module=BlobHandle(uuid4())
+    )
+
+
+def _run_task(device: str) -> RunTask:
+    return RunTask(user_id="u", device_name=device, module=BlobHandle(uuid4()))
+
+
+async def _insert(session_factory, task, transitions):
+    """Insert ``task`` with one TaskState per ``(state, seconds_after_T0)``."""
+    async with session_factory() as session:
+        session.add(task)
+        await session.flush()
+        for state, offset in transitions:
+            session.add(
+                TaskState(task_id=task.id, state=state, timestamp=T0 + timedelta(seconds=offset))
+            )
+        await session.commit()
+
+
+async def _device(session_factory, name="lucidac0"):
+    async with session_factory() as session:
+        session.add(Device(name=name, type=DeviceTypeEnum.LUCIDAC, host="10.0.0.5", available=True))
+        await session.commit()
+
+
+@pytest.mark.asyncio
+async def test_empty_database(session_factory):
+    """No tasks: every mapping is empty and nothing raises."""
+    async with session_factory() as session:
+        stats = await collect_task_statistics(session)
+    assert stats.current == {} and stats.finished == {}
+    assert stats.wait == {} and stats.work == {}
+
+
+@pytest.mark.asyncio
+async def test_current_counts_latest_state_only(session_factory):
+    """A task is counted once, under its latest state."""
+    Q, P = TaskStateEnum.QUEUED, TaskStateEnum.INPROGRESS
+    await _insert(session_factory, _compile_task(), [(Q, 0)])
+    await _insert(session_factory, _compile_task(), [(Q, 0), (P, 5)])
+    await _insert(session_factory, _compile_task(), [(Q, 0), (P, 5), (TaskStateEnum.SUCCEEDED, 9)])
+    async with session_factory() as session:
+        stats = await collect_task_statistics(session)
+    assert stats.current == {("compile", "queued"): 1, ("compile", "inprogress"): 1}
+
+
+@pytest.mark.asyncio
+async def test_finished_counts_by_type_and_outcome(session_factory):
+    """Terminal transitions are counted per task type and outcome."""
+    await _device(session_factory)
+    Q, P = TaskStateEnum.QUEUED, TaskStateEnum.INPROGRESS
+    await _insert(session_factory, _compile_task(), [(Q, 0), (P, 1), (TaskStateEnum.SUCCEEDED, 2)])
+    await _insert(session_factory, _compile_task(), [(Q, 0), (P, 1), (TaskStateEnum.FAILED, 2)])
+    await _insert(session_factory, _run_task("lucidac0"), [(Q, 0), (TaskStateEnum.CANCELLED, 1)])
+    await _insert(session_factory, _run_task("lucidac0"), [(Q, 0), (P, 1), (TaskStateEnum.SUCCEEDED, 4)])
+    async with session_factory() as session:
+        stats = await collect_task_statistics(session)
+    assert stats.finished == {
+        ("compile", "succeeded"): 1,
+        ("compile", "failed"): 1,
+        ("run", "cancelled"): 1,
+        ("run", "succeeded"): 1,
+    }
+
+
+@pytest.mark.asyncio
+async def test_wait_and_work_durations(session_factory):
+    """Wait is QUEUED->INPROGRESS, work is INPROGRESS->terminal; run tasks carry the device."""
+    await _device(session_factory)
+    Q, P, S, F = (
+        TaskStateEnum.QUEUED,
+        TaskStateEnum.INPROGRESS,
+        TaskStateEnum.SUCCEEDED,
+        TaskStateEnum.FAILED,
+    )
+    await _insert(session_factory, _compile_task(), [(Q, 0), (P, 2), (S, 12)])  # wait 2, work 10
+    await _insert(session_factory, _compile_task(), [(Q, 0), (P, 4), (F, 5)])  # wait 4, work 1
+    await _insert(session_factory, _run_task("lucidac0"), [(Q, 0), (P, 30), (S, 31.5)])
+    await _insert(session_factory, _run_task("lucidac0"), [(Q, 0), (P, 1)])  # still running
+    await _insert(session_factory, _compile_task(), [(Q, 0), (TaskStateEnum.CANCELLED, 3)])  # never started
+    async with session_factory() as session:
+        stats = await collect_task_statistics(session)
+    assert stats.wait == {
+        ("compile", ""): DurationStats(2, 6.0),
+        ("run", "lucidac0"): DurationStats(2, 31.0),
+    }
+    assert stats.work == {
+        ("compile", "", "succeeded"): DurationStats(1, 10.0),
+        ("compile", "", "failed"): DurationStats(1, 1.0),
+        ("run", "lucidac0", "succeeded"): DurationStats(1, 1.5),
+    }

analogcloud_common-0.2.1/tests/test_version.py

@@ -0,0 +1,68 @@
+"""Tests for anabrid.cloud.version.build_info."""
+
+from importlib import metadata
+
+import pytest
+
+from anabrid.cloud.version import BuildInfo, build_info, distribution_version
+
+
+def _lookup(version: str):
+    def lookup(name: str) -> str:
+        assert name == "analogcloud-server"
+        return version
+
+    return lookup
+
+
+def test_release_version_derives_tag_and_has_no_sha():
+    """A plain X.Y.Z version is a release: tag is vX.Y.Z, sha unknown."""
+    info = build_info("server", env={}, version_lookup=_lookup("0.2.0"))
+    assert info == BuildInfo("server", "0.2.0", None, "v0.2.0", None)
+
+
+def test_dev_version_parses_sha_and_has_no_tag():
+    """The +g<sha> local segment of a dev version yields the short sha."""
+    info = build_info("server", env={}, version_lookup=_lookup("0.2.1.dev17+g1234abcd"))
+    assert info.git_sha == "1234abcd"
+    assert info.git_tag is None
+
+
+def test_environment_overrides_win():
+    """Explicit ANALOGCLOUD_GIT_* / ENVIRONMENT values take precedence."""
+    env = {
+        "ANALOGCLOUD_GIT_SHA": "deadbeef",
+        "ANALOGCLOUD_GIT_TAG": "v9.9.9",
+        "ANALOGCLOUD_ENVIRONMENT": "prod",
+    }
+    info = build_info("server", env=env, version_lookup=_lookup("0.2.1.dev17+g1234abcd"))
+    assert (info.git_sha, info.git_tag, info.environment) == ("deadbeef", "v9.9.9", "prod")
+
+
+def test_empty_environment_values_count_as_absent():
+    """Empty strings (unset Docker build args) do not override derived values."""
+    env = {"ANALOGCLOUD_GIT_SHA": "", "ANALOGCLOUD_GIT_TAG": "", "ANALOGCLOUD_ENVIRONMENT": ""}
+    info = build_info("server", env=env, version_lookup=_lookup("0.2.0"))
+    assert info == BuildInfo("server", "0.2.0", None, "v0.2.0", None)
+
+
+def test_unknown_distribution():
+    """A missing distribution reports version 'unknown' instead of raising."""
+
+    def missing(name: str) -> str:
+        raise metadata.PackageNotFoundError(name)
+
+    info = build_info("server", env={}, version_lookup=missing)
+    assert info.version == "unknown"
+    assert distribution_version("nope", version_lookup=missing) is None
+
+
+def test_as_dict_roundtrip():
+    """as_dict exposes exactly the dataclass fields."""
+    info = build_info("server", env={}, version_lookup=_lookup("0.2.0"))
+    assert set(info.as_dict()) == {"component", "version", "git_sha", "git_tag", "environment"}
+
+
+def test_real_distribution_is_installed():
+    """The common package itself is resolvable through importlib.metadata."""
+    assert build_info("common", env={}).version != "unknown"