qodalis-cli-server-plugin-jobs 1.0.0b3__tar.gz

qodalis_cli_server_plugin_jobs-1.0.0b3/.gitignore

@@ -0,0 +1,43 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Environment variables
+.env
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+TestResults/
+
+# Type checking / linting
+.mypy_cache/
+.ruff_cache/
+
+# C extensions
+*.so
+
+# IDEs and editors
+.idea/
+.vscode/*
+!.vscode/settings.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+# System files
+.DS_Store
+Thumbs.db

qodalis_cli_server_plugin_jobs-1.0.0b3/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: qodalis-cli-server-plugin-jobs
+Version: 1.0.0b3
+Summary: Background job scheduler plugin for Qodalis CLI servers
+Project-URL: Homepage, https://github.com/qodalis-solutions/cli-server-python
+Project-URL: Repository, https://github.com/qodalis-solutions/cli-server-python
+Project-URL: Issues, https://github.com/qodalis-solutions/cli-server-python/issues
+Author-email: Nicolae Lupei <nicolae.lupei@qodalis.com>
+License-Expression: MIT
+Keywords: cli,jobs,plugin,qodalis,scheduler
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: croniter>=1.3.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: qodalis-cli-server-abstractions

qodalis_cli_server_plugin_jobs-1.0.0b3/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qodalis-cli-server-plugin-jobs"
+version = "1.0.0b3"
+description = "Background job scheduler plugin for Qodalis CLI servers"
+readme = { text = "", content-type = "text/plain" }
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Nicolae Lupei", email = "nicolae.lupei@qodalis.com" },
+]
+keywords = ["cli", "qodalis", "jobs", "scheduler", "plugin"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "qodalis-cli-server-abstractions",
+    "croniter>=1.3.0",
+    "fastapi>=0.100.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/qodalis-solutions/cli-server-python"
+Repository = "https://github.com/qodalis-solutions/cli-server-python"
+Issues = "https://github.com/qodalis-solutions/cli-server-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["qodalis_cli_jobs"]
+
+[tool.hatch.build.targets.sdist]
+include = ["qodalis_cli_jobs/**"]

qodalis_cli_server_plugin_jobs-1.0.0b3/qodalis_cli_jobs/__init__.py

@@ -0,0 +1,22 @@
+"""Qodalis CLI jobs plugin — background job scheduler."""
+
+from .cli_job_execution_context import CliJobExecutionContext
+from .cli_job_logger import CliJobLogger
+from .cli_job_scheduler import CliJobScheduler, InvalidOperationError, BroadcastFn
+from .cli_jobs_builder import CliJobsBuilder, CliJobsPlugin
+from .cli_jobs_controller import create_cli_jobs_router
+from .in_memory_job_storage_provider import InMemoryJobStorageProvider
+from .interval_parser import parse_interval
+
+__all__ = [
+    "BroadcastFn",
+    "CliJobExecutionContext",
+    "CliJobLogger",
+    "CliJobScheduler",
+    "CliJobsBuilder",
+    "CliJobsPlugin",
+    "InMemoryJobStorageProvider",
+    "InvalidOperationError",
+    "create_cli_jobs_router",
+    "parse_interval",
+]

qodalis_cli_server_plugin_jobs-1.0.0b3/qodalis_cli_jobs/cli_job_execution_context.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from qodalis_cli_server_abstractions.jobs import ICliJobExecutionContext, ICliJobLogger
+
+from .cli_job_logger import CliJobLogger
+
+
+class CliJobExecutionContext(ICliJobExecutionContext):
+    """Concrete execution context wrapping a per-execution logger."""
+
+    def __init__(self) -> None:
+        self._logger = CliJobLogger()
+
+    @property
+    def logger(self) -> ICliJobLogger:
+        return self._logger
+
+    @property
+    def log_entries(self) -> list:
+        """Convenience accessor for the captured log entries."""
+        return self._logger.entries

qodalis_cli_server_plugin_jobs-1.0.0b3/qodalis_cli_jobs/cli_job_logger.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import datetime
+
+from qodalis_cli_server_abstractions.jobs import ICliJobLogger, JobLogEntry
+
+
+class CliJobLogger(ICliJobLogger):
+    """Concrete logger that captures log entries in a list."""
+
+    def __init__(self) -> None:
+        self._entries: list[JobLogEntry] = []
+
+    @property
+    def entries(self) -> list[JobLogEntry]:
+        return self._entries
+
+    def debug(self, message: str) -> None:
+        self._entries.append(
+            JobLogEntry(
+                timestamp=datetime.datetime.now(datetime.UTC),
+                level="debug",
+                message=message,
+            )
+        )
+
+    def info(self, message: str) -> None:
+        self._entries.append(
+            JobLogEntry(
+                timestamp=datetime.datetime.now(datetime.UTC),
+                level="info",
+                message=message,
+            )
+        )
+
+    def warning(self, message: str) -> None:
+        self._entries.append(
+            JobLogEntry(
+                timestamp=datetime.datetime.now(datetime.UTC),
+                level="warning",
+                message=message,
+            )
+        )
+
+    def error(self, message: str) -> None:
+        self._entries.append(
+            JobLogEntry(
+                timestamp=datetime.datetime.now(datetime.UTC),
+                level="error",
+                message=message,
+            )
+        )

qodalis_cli_server_plugin_jobs-1.0.0b3/qodalis_cli_jobs/cli_job_scheduler.py

@@ -0,0 +1,472 @@
+from __future__ import annotations
+
+import asyncio
+import datetime
+import json
+import logging
+import uuid
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Any, Callable, Awaitable
+
+from croniter import croniter
+
+from qodalis_cli_server_abstractions.jobs import (
+    CliJobOptions,
+    ICliJob,
+    ICliJobStorageProvider,
+    JobExecution,
+    JobState,
+)
+
+from .cli_job_execution_context import CliJobExecutionContext
+from .interval_parser import parse_interval
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class _JobRegistration:
+    """Internal runtime state for a registered job."""
+
+    id: str
+    job: ICliJob
+    options: CliJobOptions
+    status: str = "active"  # 'active' | 'paused' | 'stopped'
+    current_execution_id: str | None = None
+    current_cancellation: asyncio.Event | None = None
+    next_run_at: datetime.datetime | None = None
+    last_run_at: datetime.datetime | None = None
+    last_run_status: str | None = None
+    last_run_duration: float | None = None  # ms
+    timer_task: asyncio.Task[Any] | None = None
+    queue: deque[int] = field(default_factory=deque)  # queued retry_attempt values
+
+
+# Type alias for the broadcast callback.
+BroadcastFn = Callable[[str], Awaitable[None]]
+
+
+class CliJobScheduler:
+    """Background job scheduler using asyncio tasks."""
+
+    def __init__(
+        self,
+        storage: ICliJobStorageProvider,
+        broadcast_fn: BroadcastFn | None = None,
+    ) -> None:
+        self._storage = storage
+        self._broadcast_fn = broadcast_fn
+        self._registrations: dict[str, _JobRegistration] = {}
+        self._running = False
+
+    # ------------------------------------------------------------------
+    # Public properties
+    # ------------------------------------------------------------------
+
+    @property
+    def registrations(self) -> dict[str, _JobRegistration]:
+        return self._registrations
+
+    @property
+    def storage(self) -> ICliJobStorageProvider:
+        return self._storage
+
+    # ------------------------------------------------------------------
+    # Registration
+    # ------------------------------------------------------------------
+
+    def register(self, job: ICliJob, options: CliJobOptions) -> str:
+        """Register a job. Returns the job id."""
+        job_id = str(uuid.uuid4())
+        if not options.name:
+            options.name = type(job).__name__
+        if not options.description:
+            options.description = options.name
+        reg = _JobRegistration(
+            id=job_id,
+            job=job,
+            options=options,
+            status="active" if options.enabled else "stopped",
+        )
+        self._registrations[job_id] = reg
+        return job_id
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def start(self) -> None:
+        """Load persisted states and start timers for active jobs."""
+        self._running = True
+        persisted = await self._storage.get_all_job_states()
+
+        for reg in self._registrations.values():
+            # Apply persisted state if available
+            state = persisted.get(reg.id)
+            if state:
+                reg.status = state.status
+                reg.last_run_at = state.last_run_at
+
+            if reg.status == "active":
+                self._schedule_next(reg)
+
+    async def stop(self) -> None:
+        """Cancel all running executions, stop timers, persist states."""
+        self._running = False
+        for reg in list(self._registrations.values()):
+            # Cancel running execution
+            if reg.current_cancellation is not None:
+                reg.current_cancellation.set()
+            # Cancel timer
+            if reg.timer_task is not None and not reg.timer_task.done():
+                reg.timer_task.cancel()
+                try:
+                    await reg.timer_task
+                except (asyncio.CancelledError, Exception):
+                    pass
+            # Persist state
+            await self._storage.save_job_state(
+                reg.id,
+                JobState(
+                    status=reg.status,
+                    last_run_at=reg.last_run_at,
+                    updated_at=datetime.datetime.now(datetime.UTC),
+                ),
+            )
+
+    # ------------------------------------------------------------------
+    # Control methods
+    # ------------------------------------------------------------------
+
+    async def trigger(self, job_id: str) -> None:
+        reg = self._get_registration(job_id)
+        if reg.current_execution_id is not None:
+            policy = reg.options.overlap_policy
+            if policy == "skip":
+                raise InvalidOperationError("Job is already running")
+            elif policy == "cancel":
+                if reg.current_cancellation:
+                    reg.current_cancellation.set()
+            elif policy == "queue":
+                reg.queue.append(0)
+                return
+        asyncio.create_task(self._execute_job(reg, retry_attempt=0))
+
+    async def pause(self, job_id: str) -> None:
+        reg = self._get_registration(job_id)
+        if reg.status == "paused":
+            raise InvalidOperationError("Job is already paused")
+        reg.status = "paused"
+        self._cancel_timer(reg)
+        await self._persist_state(reg)
+        await self._broadcast({"type": "job:paused", "jobId": job_id})
+
+    async def resume(self, job_id: str) -> None:
+        reg = self._get_registration(job_id)
+        if reg.status != "paused":
+            raise InvalidOperationError("Job is not paused")
+        reg.status = "active"
+        self._schedule_next(reg)
+        await self._persist_state(reg)
+        await self._broadcast({"type": "job:resumed", "jobId": job_id})
+
+    async def stop_job(self, job_id: str) -> None:
+        reg = self._get_registration(job_id)
+        reg.status = "stopped"
+        self._cancel_timer(reg)
+        if reg.current_cancellation is not None:
+            reg.current_cancellation.set()
+        await self._persist_state(reg)
+        await self._broadcast({"type": "job:stopped", "jobId": job_id})
+
+    async def cancel_current(self, job_id: str) -> None:
+        reg = self._get_registration(job_id)
+        if reg.current_execution_id is None or reg.current_cancellation is None:
+            raise InvalidOperationError("No execution is currently running")
+        reg.current_cancellation.set()
+
+    async def update_options(
+        self,
+        job_id: str,
+        *,
+        description: str | None = None,
+        group: str | None = None,
+        schedule: str | None = None,
+        interval: str | None = None,
+        max_retries: int | None = None,
+        retry_delay: str | None = None,
+        retry_strategy: str | None = None,
+        timeout: str | None = None,
+        overlap_policy: str | None = None,
+    ) -> None:
+        reg = self._get_registration(job_id)
+        opts = reg.options
+
+        if description is not None:
+            opts.description = description
+        if group is not None:
+            opts.group = group
+        if schedule is not None and interval is not None:
+            raise ValueError("Cannot provide both schedule and interval")
+        if schedule is not None:
+            if not croniter.is_valid(schedule):
+                raise ValueError(f"Invalid cron expression: {schedule!r}")
+            opts.schedule = schedule
+            opts.interval = None
+        if interval is not None:
+            parse_interval(interval)  # validate
+            opts.interval = interval
+            opts.schedule = None
+        if max_retries is not None:
+            opts.max_retries = max_retries
+        if retry_delay is not None:
+            parse_interval(retry_delay)  # validate
+            opts.retry_delay = retry_delay
+        if retry_strategy is not None:
+            if retry_strategy not in ("fixed", "linear", "exponential"):
+                raise ValueError(f"Invalid retry strategy: {retry_strategy!r}")
+            opts.retry_strategy = retry_strategy
+        if timeout is not None:
+            parse_interval(timeout)  # validate
+            opts.timeout = timeout
+        if overlap_policy is not None:
+            if overlap_policy not in ("skip", "queue", "cancel"):
+                raise ValueError(f"Invalid overlap policy: {overlap_policy!r}")
+            opts.overlap_policy = overlap_policy
+
+        # Reschedule if active
+        if reg.status == "active":
+            self._cancel_timer(reg)
+            self._schedule_next(reg)
+
+    # ------------------------------------------------------------------
+    # Internal scheduling
+    # ------------------------------------------------------------------
+
+    def _schedule_next(self, reg: _JobRegistration) -> None:
+        """Compute next run time and create timer task."""
+        if not self._running:
+            return
+
+        now = datetime.datetime.now(datetime.UTC)
+        delay: float
+
+        if reg.options.schedule:
+            cron = croniter(reg.options.schedule, now)
+            next_dt = cron.get_next(datetime.datetime)
+            if next_dt.tzinfo is None:
+                next_dt = next_dt.replace(tzinfo=datetime.UTC)
+            reg.next_run_at = next_dt
+            delay = max((next_dt - now).total_seconds(), 0.1)
+        elif reg.options.interval:
+            delay = parse_interval(reg.options.interval)
+            reg.next_run_at = now + datetime.timedelta(seconds=delay)
+        else:
+            # No schedule configured — job can only be triggered manually
+            reg.next_run_at = None
+            return
+
+        reg.timer_task = asyncio.create_task(self._timer_fire(reg, delay))
+
+    async def _timer_fire(self, reg: _JobRegistration, delay: float) -> None:
+        """Wait for the delay, then execute the job and reschedule."""
+        try:
+            await asyncio.sleep(delay)
+        except asyncio.CancelledError:
+            return
+
+        if not self._running or reg.status != "active":
+            return
+
+        # Overlap check
+        if reg.current_execution_id is not None:
+            policy = reg.options.overlap_policy
+            if policy == "skip":
+                pass  # skip this firing
+            elif policy == "cancel":
+                if reg.current_cancellation:
+                    reg.current_cancellation.set()
+                asyncio.create_task(self._execute_job(reg, retry_attempt=0))
+            elif policy == "queue":
+                reg.queue.append(0)
+        else:
+            asyncio.create_task(self._execute_job(reg, retry_attempt=0))
+
+        # Reschedule
+        if reg.status == "active":
+            self._schedule_next(reg)
+
+    # ------------------------------------------------------------------
+    # Job execution
+    # ------------------------------------------------------------------
+
+    async def _execute_job(self, reg: _JobRegistration, retry_attempt: int) -> None:
+        exec_id = str(uuid.uuid4())
+        cancel_event = asyncio.Event()
+        now = datetime.datetime.now(datetime.UTC)
+
+        reg.current_execution_id = exec_id
+        reg.current_cancellation = cancel_event
+
+        execution = JobExecution(
+            id=exec_id,
+            job_id=reg.id,
+            job_name=reg.options.name or type(reg.job).__name__,
+            status="running",
+            started_at=now,
+            retry_attempt=retry_attempt,
+        )
+        await self._storage.save_execution(execution)
+
+        await self._broadcast({
+            "type": "job:started",
+            "jobId": reg.id,
+            "executionId": exec_id,
+            "timestamp": now.isoformat(),
+        })
+
+        ctx = CliJobExecutionContext()
+
+        try:
+            timeout_seconds: float | None = None
+            if reg.options.timeout:
+                timeout_seconds = parse_interval(reg.options.timeout)
+
+            if timeout_seconds:
+                await asyncio.wait_for(
+                    reg.job.execute_async(ctx, cancel_event),
+                    timeout=timeout_seconds,
+                )
+            else:
+                await reg.job.execute_async(ctx, cancel_event)
+
+            # Check if cancellation was requested (cooperative)
+            if cancel_event.is_set():
+                execution.status = "cancelled"
+                await self._broadcast({
+                    "type": "job:cancelled",
+                    "jobId": reg.id,
+                    "executionId": exec_id,
+                })
+            else:
+                execution.status = "completed"
+
+        except asyncio.TimeoutError:
+            cancel_event.set()
+            execution.status = "timed_out"
+            execution.error = f"Timed out after {reg.options.timeout}"
+            await self._broadcast({
+                "type": "job:timed_out",
+                "jobId": reg.id,
+                "executionId": exec_id,
+                "timeout": reg.options.timeout,
+            })
+        except asyncio.CancelledError:
+            execution.status = "cancelled"
+            await self._broadcast({
+                "type": "job:cancelled",
+                "jobId": reg.id,
+                "executionId": exec_id,
+            })
+        except Exception as exc:
+            execution.status = "failed"
+            execution.error = str(exc)
+            await self._broadcast({
+                "type": "job:failed",
+                "jobId": reg.id,
+                "executionId": exec_id,
+                "error": str(exc),
+            })
+
+        # Finalize
+        end_time = datetime.datetime.now(datetime.UTC)
+        execution.completed_at = end_time
+        execution.duration = round((end_time - execution.started_at).total_seconds() * 1000)
+        execution.logs = list(ctx.log_entries)
+        await self._storage.save_execution(execution)
+
+        reg.last_run_at = execution.started_at
+        reg.last_run_status = execution.status
+        reg.last_run_duration = execution.duration
+        reg.current_execution_id = None
+        reg.current_cancellation = None
+
+        if execution.status == "completed":
+            await self._broadcast({
+                "type": "job:completed",
+                "jobId": reg.id,
+                "executionId": exec_id,
+                "duration": execution.duration,
+            })
+
+        # Retry on failure
+        if execution.status == "failed" and retry_attempt < reg.options.max_retries:
+            base_delay = parse_interval(reg.options.retry_delay) if reg.options.retry_delay else 5.0
+            strategy = reg.options.retry_strategy or "exponential"
+            if strategy == "fixed":
+                delay = base_delay
+            elif strategy == "linear":
+                delay = base_delay * (retry_attempt + 1)
+            else:  # exponential
+                delay = base_delay * (2 ** retry_attempt)
+            logger.info(
+                "Retrying job %s in %.1fs (attempt %d/%d)",
+                reg.options.name,
+                delay,
+                retry_attempt + 1,
+                reg.options.max_retries,
+            )
+            await self._broadcast({
+                "type": "job:retrying",
+                "jobId": reg.id,
+                "executionId": exec_id,
+                "attempt": retry_attempt + 1,
+                "maxRetries": reg.options.max_retries,
+                "delayMs": round(delay * 1000),
+            })
+            await asyncio.sleep(delay)
+            asyncio.create_task(self._execute_job(reg, retry_attempt + 1))
+            return
+
+        # Process queue
+        if reg.queue:
+            queued_attempt = reg.queue.popleft()
+            asyncio.create_task(self._execute_job(reg, queued_attempt))
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _get_registration(self, job_id: str) -> _JobRegistration:
+        reg = self._registrations.get(job_id)
+        if reg is None:
+            raise KeyError(f"Job not found: {job_id}")
+        return reg
+
+    def _cancel_timer(self, reg: _JobRegistration) -> None:
+        if reg.timer_task is not None and not reg.timer_task.done():
+            reg.timer_task.cancel()
+        reg.timer_task = None
+        reg.next_run_at = None
+
+    async def _persist_state(self, reg: _JobRegistration) -> None:
+        await self._storage.save_job_state(
+            reg.id,
+            JobState(
+                status=reg.status,
+                last_run_at=reg.last_run_at,
+                updated_at=datetime.datetime.now(datetime.UTC),
+            ),
+        )
+
+    async def _broadcast(self, message: dict[str, Any]) -> None:
+        if self._broadcast_fn is not None:
+            try:
+                await self._broadcast_fn(json.dumps(message))
+            except Exception:
+                logger.debug("Failed to broadcast job event", exc_info=True)
+
+
+class InvalidOperationError(Exception):
+    """Raised when a job control operation is not valid in the current state."""

qodalis_cli_server_plugin_jobs-1.0.0b3/qodalis_cli_jobs/cli_jobs_builder.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Awaitable
+
+from fastapi import APIRouter
+
+from qodalis_cli_server_abstractions.jobs import (
+    CliJobOptions,
+    ICliJob,
+    ICliJobStorageProvider,
+)
+
+from .cli_job_scheduler import CliJobScheduler, BroadcastFn
+from .cli_jobs_controller import create_cli_jobs_router
+from .in_memory_job_storage_provider import InMemoryJobStorageProvider
+
+
+@dataclass
+class CliJobsPlugin:
+    """Result of building the jobs plugin — contains the router and scheduler."""
+
+    router: APIRouter
+    scheduler: CliJobScheduler
+
+
+class CliJobsBuilder:
+    """Fluent builder for configuring and creating the jobs plugin."""
+
+    def __init__(self) -> None:
+        self._registrations: list[tuple[ICliJob, CliJobOptions]] = []
+        self._storage_provider: ICliJobStorageProvider | None = None
+
+    def add_job(self, job: ICliJob, options: CliJobOptions) -> CliJobsBuilder:
+        """Register a background job with the given options."""
+        self._registrations.append((job, options))
+        return self
+
+    def set_storage_provider(self, provider: ICliJobStorageProvider) -> CliJobsBuilder:
+        """Set a custom storage provider for job execution history."""
+        self._storage_provider = provider
+        return self
+
+    def build(self, broadcast_fn: BroadcastFn | None = None) -> CliJobsPlugin:
+        """Build the plugin, returning the router and scheduler."""
+        storage = self._storage_provider or InMemoryJobStorageProvider()
+        scheduler = CliJobScheduler(storage, broadcast_fn=broadcast_fn)
+
+        for job, opts in self._registrations:
+            scheduler.register(job, opts)
+
+        router = create_cli_jobs_router(scheduler, storage)
+
+        return CliJobsPlugin(router=router, scheduler=scheduler)

qodalis_cli_server_plugin_jobs-1.0.0b3/qodalis_cli_jobs/cli_jobs_controller.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+import datetime
+from typing import Any
+
+from fastapi import APIRouter, Query
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field
+
+from qodalis_cli_server_abstractions.jobs import ICliJobStorageProvider
+
+from .cli_job_scheduler import CliJobScheduler, InvalidOperationError
+from .interval_parser import parse_interval
+
+
+# ---------------------------------------------------------------------------
+# Request / Response models
+# ---------------------------------------------------------------------------
+
+
+class UpdateJobRequest(BaseModel):
+    description: str | None = None
+    group: str | None = None
+    schedule: str | None = None
+    interval: str | None = None
+    max_retries: int | None = Field(None, alias="maxRetries")
+    retry_delay: str | None = Field(None, alias="retryDelay")
+    retry_strategy: str | None = Field(None, alias="retryStrategy")
+    timeout: str | None = None
+    overlap_policy: str | None = Field(None, alias="overlapPolicy")
+
+    model_config = {"populate_by_name": True}
+
+
+def _serialize_dt(dt: datetime.datetime | None) -> str | None:
+    if dt is None:
+        return None
+    return dt.isoformat().replace("+00:00", "Z") if dt.tzinfo else dt.isoformat() + "Z"
+
+
+def _job_dto(reg: Any) -> dict[str, Any]:
+    return {
+        "id": reg.id,
+        "name": reg.options.name,
+        "description": reg.options.description,
+        "group": reg.options.group,
+        "status": reg.status,
+        "schedule": reg.options.schedule,
+        "interval": reg.options.interval,
+        "enabled": reg.status != "stopped",
+        "maxRetries": reg.options.max_retries,
+        "retryDelay": reg.options.retry_delay,
+        "retryStrategy": reg.options.retry_strategy,
+        "timeout": reg.options.timeout,
+        "overlapPolicy": reg.options.overlap_policy,
+        "currentExecutionId": reg.current_execution_id,
+        "nextRunAt": _serialize_dt(reg.next_run_at),
+        "lastRunAt": _serialize_dt(reg.last_run_at),
+        "lastRunStatus": reg.last_run_status,
+        "lastRunDuration": reg.last_run_duration,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Router factory
+# ---------------------------------------------------------------------------
+
+
+def create_cli_jobs_router(
+    scheduler: CliJobScheduler,
+    storage: ICliJobStorageProvider,
+) -> APIRouter:
+    router = APIRouter()
+
+    # GET / — list all jobs
+    @router.get("")
+    async def list_jobs() -> list[dict[str, Any]]:
+        return [_job_dto(reg) for reg in scheduler.registrations.values()]
+
+    # GET /{job_id}
+    @router.get("/{job_id}")
+    async def get_job(job_id: str) -> Any:
+        reg = scheduler.registrations.get(job_id)
+        if reg is None:
+            return JSONResponse(
+                status_code=404,
+                content={"error": "Job not found", "code": "JOB_NOT_FOUND"},
+            )
+        return _job_dto(reg)
+
+    # POST /{job_id}/trigger
+    @router.post("/{job_id}/trigger")
+    async def trigger_job(job_id: str) -> Any:
+        try:
+            await scheduler.trigger(job_id)
+            return {"message": "Job triggered"}
+        except KeyError:
+            return JSONResponse(
+                status_code=404,
+                content={"error": "Job not found", "code": "JOB_NOT_FOUND"},
+            )
+        except InvalidOperationError as exc:
+            return JSONResponse(
+                status_code=409,
+                content={"error": str(exc), "code": "JOB_ALREADY_RUNNING"},
+            )
+
+    # POST /{job_id}/pause
+    @router.post("/{job_id}/pause")
+    async def pause_job(job_id: str) -> Any:
+        try:
+            await scheduler.pause(job_id)
+            return {"message": "Job paused"}
+        except KeyError:
+            return JSONResponse(
+                status_code=404,
+                content={"error": "Job not found", "code": "JOB_NOT_FOUND"},
+            )
+        except InvalidOperationError as exc:
+            return JSONResponse(
+                status_code=409,
+                content={"error": str(exc), "code": "JOB_ALREADY_PAUSED"},
+            )
+
+    # POST /{job_id}/resume
+    @router.post("/{job_id}/resume")
+    async def resume_job(job_id: str) -> Any:
+        try:
+            await scheduler.resume(job_id)
+            return {"message": "Job resumed"}
+        except KeyError:
+            return JSONResponse(
+                status_code=404,
+                content={"error": "Job not found", "code": "JOB_NOT_FOUND"},
+            )
+        except InvalidOperationError as exc:
+            return JSONResponse(
+                status_code=409,
+                content={"error": str(exc), "code": "JOB_NOT_PAUSED"},
+            )
+
+    # POST /{job_id}/stop
+    @router.post("/{job_id}/stop")
+    async def stop_job(job_id: str) -> Any:
+        try:
+            await scheduler.stop_job(job_id)
+            return {"message": "Job stopped"}
+        except KeyError:
+            return JSONResponse(
+                status_code=404,
+                content={"error": "Job not found", "code": "JOB_NOT_FOUND"},
+            )
+
+    # POST /{job_id}/cancel
+    @router.post("/{job_id}/cancel")
+    async def cancel_job(job_id: str) -> Any:
+        try:
+            await scheduler.cancel_current(job_id)
+            return {"message": "Execution cancelled"}
+        except KeyError:
+            return JSONResponse(
+                status_code=404,
+                content={"error": "Job not found", "code": "JOB_NOT_FOUND"},
+            )
+        except InvalidOperationError as exc:
+            return JSONResponse(
+                status_code=409,
+                content={"error": str(exc), "code": "JOB_NOT_RUNNING"},
+            )
+
+    # PUT /{job_id} — update options (patch semantics)
+    @router.put("/{job_id}")
+    async def update_job(job_id: str, body: UpdateJobRequest) -> Any:
+        try:
+            await scheduler.update_options(
+                job_id,
+                description=body.description,
+                group=body.group,
+                schedule=body.schedule,
+                interval=body.interval,
+                max_retries=body.max_retries,
+                retry_delay=body.retry_delay,
+                retry_strategy=body.retry_strategy,
+                timeout=body.timeout,
+                overlap_policy=body.overlap_policy,
+            )
+            return {"message": "Job updated"}
+        except KeyError:
+            return JSONResponse(
+                status_code=404,
+                content={"error": "Job not found", "code": "JOB_NOT_FOUND"},
+            )
+        except ValueError as exc:
+            return JSONResponse(
+                status_code=400,
+                content={"error": str(exc), "code": "INVALID_SCHEDULE"},
+            )
+
+    # GET /{job_id}/history
+    @router.get("/{job_id}/history")
+    async def get_history(
+        job_id: str,
+        limit: int = Query(20, le=100),
+        offset: int = Query(0, ge=0),
+        status: str | None = Query(None),
+    ) -> Any:
+        if job_id not in scheduler.registrations:
+            return JSONResponse(
+                status_code=404,
+                content={"error": "Job not found", "code": "JOB_NOT_FOUND"},
+            )
+        items, total = await storage.get_executions(
+            job_id, limit=limit, offset=offset, status=status
+        )
+        return {
+            "items": [
+                {
+                    "id": e.id,
+                    "jobId": e.job_id,
+                    "jobName": e.job_name,
+                    "status": e.status,
+                    "startedAt": _serialize_dt(e.started_at),
+                    "completedAt": _serialize_dt(e.completed_at),
+                    "duration": e.duration,
+                    "error": e.error,
+                    "retryAttempt": e.retry_attempt,
+                    "logCount": len(e.logs),
+                }
+                for e in items
+            ],
+            "total": total,
+            "limit": limit,
+            "offset": offset,
+        }
+
+    # GET /{job_id}/history/{exec_id}
+    @router.get("/{job_id}/history/{exec_id}")
+    async def get_execution(job_id: str, exec_id: str) -> Any:
+        execution = await storage.get_execution(exec_id)
+        if execution is None or execution.job_id != job_id:
+            return JSONResponse(
+                status_code=404,
+                content={"error": "Execution not found", "code": "EXECUTION_NOT_FOUND"},
+            )
+        return {
+            "id": execution.id,
+            "jobId": execution.job_id,
+            "jobName": execution.job_name,
+            "status": execution.status,
+            "startedAt": _serialize_dt(execution.started_at),
+            "completedAt": _serialize_dt(execution.completed_at),
+            "duration": execution.duration,
+            "error": execution.error,
+            "retryAttempt": execution.retry_attempt,
+            "logs": [
+                {
+                    "timestamp": _serialize_dt(log.timestamp),
+                    "level": log.level,
+                    "message": log.message,
+                }
+                for log in execution.logs
+            ],
+        }
+
+    return router

qodalis_cli_server_plugin_jobs-1.0.0b3/qodalis_cli_jobs/in_memory_job_storage_provider.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from qodalis_cli_server_abstractions.jobs import (
+    ICliJobStorageProvider,
+    JobExecution,
+    JobState,
+)
+
+
+class InMemoryJobStorageProvider(ICliJobStorageProvider):
+    """In-memory implementation — data is lost on server restart."""
+
+    def __init__(self) -> None:
+        # job_id -> list of executions (newest first)
+        self._executions: dict[str, list[JobExecution]] = {}
+        # execution_id -> execution
+        self._executions_by_id: dict[str, JobExecution] = {}
+        # job_id -> JobState
+        self._states: dict[str, JobState] = {}
+
+    async def save_execution(self, execution: JobExecution) -> None:
+        self._executions_by_id[execution.id] = execution
+        job_list = self._executions.setdefault(execution.job_id, [])
+        # Update if existing, else prepend
+        for i, existing in enumerate(job_list):
+            if existing.id == execution.id:
+                job_list[i] = execution
+                return
+        job_list.insert(0, execution)
+
+    async def get_executions(
+        self,
+        job_id: str,
+        *,
+        limit: int = 20,
+        offset: int = 0,
+        status: str | None = None,
+    ) -> tuple[list[JobExecution], int]:
+        all_items = self._executions.get(job_id, [])
+        if status:
+            all_items = [e for e in all_items if e.status == status]
+        total = len(all_items)
+        items = all_items[offset : offset + limit]
+        return items, total
+
+    async def get_execution(self, execution_id: str) -> JobExecution | None:
+        return self._executions_by_id.get(execution_id)
+
+    async def save_job_state(self, job_id: str, state: JobState) -> None:
+        self._states[job_id] = state
+
+    async def get_job_state(self, job_id: str) -> JobState | None:
+        return self._states.get(job_id)
+
+    async def get_all_job_states(self) -> dict[str, JobState]:
+        return dict(self._states)

qodalis_cli_server_plugin_jobs-1.0.0b3/qodalis_cli_jobs/interval_parser.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import re
+
+_PATTERN = re.compile(r"^(\d+)(s|m|h|d)$")
+
+_MULTIPLIERS = {
+    "s": 1.0,
+    "m": 60.0,
+    "h": 3600.0,
+    "d": 86400.0,
+}
+
+
+def parse_interval(value: str) -> float:
+    """Parse an interval string like ``"30s"``, ``"5m"``, ``"1h"``, ``"1d"``
+    and return the number of **seconds** as a float.
+
+    Raises ``ValueError`` on invalid format.
+    """
+    match = _PATTERN.match(value.strip())
+    if not match:
+        raise ValueError(
+            f"Invalid interval format: {value!r}. "
+            "Expected a number followed by s, m, h, or d (e.g. '30s', '5m')."
+        )
+    amount = int(match.group(1))
+    unit = match.group(2)
+    return amount * _MULTIPLIERS[unit]