wxcli 1.2.0__py3-none-any.whl

wxcli/migration/preflight/runner.py

@@ -0,0 +1,293 @@
+"""Preflight runner — orchestrates all checks and manages shared data.
+
+Fetches shared Webex data once (licenses, locations, numbers, people, trunks),
+runs all checks, merges decisions, and stores results in state.json.
+
+(from 05a-preflight-checks.md, PreflightRunner class)
+(from phase-10-preflight.md, runner orchestrator)
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from wxcli.migration.preflight import (
+    CheckResult,
+    CheckStatus,
+    PreflightError,
+    PreflightResult,
+    _run_wxcli,
+)
+from wxcli.migration.preflight.checks import (
+    check_bulk_device_job_support,
+    check_duplicate_users,
+    check_e911_readiness,
+    check_feature_entitlements,
+    check_licenses,
+    check_locations,
+    check_number_conflicts,
+    check_rate_limit_budget,
+    check_trunks,
+    check_workspace_licenses,
+)
+from wxcli.migration.store import MigrationStore
+
+
+# Priority order for overall result (worst wins)
+_STATUS_PRIORITY = {
+    CheckStatus.FAIL: 3,
+    CheckStatus.WARN: 2,
+    CheckStatus.PASS: 1,
+    CheckStatus.SKIP: 0,
+}
+
+
+def _worst_status(results: list[CheckResult]) -> CheckStatus:
+    """Return the worst status across all results."""
+    worst = CheckStatus.SKIP
+    for r in results:
+        if _STATUS_PRIORITY.get(r.status, 0) > _STATUS_PRIORITY.get(worst, 0):
+            worst = r.status
+    return worst
+
+
+class PreflightRunner:
+    """Orchestrates all 7 preflight checks + DUPLICATE_USER detection.
+
+    Fetches shared data once before running individual checks.
+    (from 05a-preflight-checks.md, Shared Data Between Checks)
+    """
+
+    def __init__(self, config: dict | None = None):
+        self.config = config or {}
+
+    def run(
+        self,
+        store: MigrationStore,
+        check_filter: str | None = None,
+        dry_run: bool = False,
+    ) -> PreflightResult:
+        """Run all preflight checks (or a single check by name).
+
+        Args:
+            store: Migration store with planned objects.
+            check_filter: Run only this check (e.g., "numbers", "licenses").
+            dry_run: Show what would be checked without querying Webex.
+        """
+        if dry_run:
+            return self._dry_run(store, check_filter)
+
+        # Fetch shared data — only what's needed for the filtered check
+        # (from 05a-preflight-checks.md, Shared Data Between Checks)
+        def _needs(*checks: str) -> bool:
+            return check_filter is None or check_filter in checks
+
+        licenses = self._fetch("licenses", ["licenses-api", "list", "--output", "json"]) if _needs("licenses", "workspace-licenses") else []
+        locations = self._fetch("locations", ["locations", "list"]) if _needs("locations") else []
+        numbers = self._fetch("numbers", ["numbers", "list", "--limit", "0"]) if _needs("numbers") else []
+        people = self._fetch("people", ["users", "list", "--calling-data", "true", "--limit", "0"]) if _needs("users") else []
+        trunks = self._fetch("trunks", ["call-routing", "list-trunks"]) if _needs("trunks") else []
+
+        # Fetch PSTN connection data per location
+        pstn_by_loc: dict[str, dict] = {}
+        if locations and _needs("locations"):
+            for loc in locations:
+                loc_id = loc.get("id")
+                if loc_id:
+                    conn = self._fetch(f"pstn-{loc_id}",
+                                       ["pstn", "list-connection", loc_id, "--output", "json"])
+                    if conn:
+                        pstn_by_loc[loc_id] = conn[0] if isinstance(conn, list) and conn else conn if isinstance(conn, dict) else {}
+
+        existing_features: dict[str, int] = {}
+        if _needs("features"):
+            existing_features = self._count_existing_features()
+
+        # Build bulk-job probe only when the plan contains bulk ops
+        # (avoids initialising a WebexSimpleApi session otherwise).
+        probe_fn = None
+        if _needs("bulk-job-support"):
+            probe_fn = self._build_bulk_job_probe()
+
+        # Run checks
+        all_checks = {
+            "licenses": lambda: check_licenses(store, licenses),
+            "workspace-licenses": lambda: check_workspace_licenses(store, licenses),
+            "locations": lambda: check_locations(store, locations, pstn_connections=pstn_by_loc if locations else None),
+            "trunks": lambda: check_trunks(store, trunks),
+            "features": lambda: check_feature_entitlements(store, existing_features),
+            "numbers": lambda: self._run_number_check(store, numbers),
+            "users": lambda: self._run_duplicate_check(store, people),
+            "rate-limit": lambda: check_rate_limit_budget(store, self.config),
+            "e911-readiness": lambda: check_e911_readiness(store),
+            "bulk-job-support": lambda: check_bulk_device_job_support(store, probe_fn),
+        }
+
+        results: list[CheckResult] = []
+        all_decisions: list[dict] = []
+        self._number_decisions: list[dict] = []
+        self._user_decisions: list[dict] = []
+
+        if check_filter:
+            if check_filter not in all_checks:
+                valid = ", ".join(sorted(all_checks.keys()))
+                raise PreflightError(f"Unknown check '{check_filter}'. Valid: {valid}")
+            result = all_checks[check_filter]()
+            results.append(result)
+        else:
+            for name, check_fn in all_checks.items():
+                try:
+                    result = check_fn()
+                    results.append(result)
+                except PreflightError as e:
+                    results.append(CheckResult(
+                        name=name,
+                        status=CheckStatus.FAIL,
+                        detail=str(e),
+                    ))
+
+        all_decisions = self._number_decisions + self._user_decisions
+
+        # Merge decisions into store — scoped to preflight types only
+        # to avoid stale-marking analyzer decisions
+        # (from 05a-preflight-checks.md lines 920-929)
+        merge_result: dict[str, int] = {}
+        new_decision_ids: list[str] = []
+        if all_decisions:
+            merge_result = store.merge_decisions(
+                all_decisions,
+                decision_types=["NUMBER_CONFLICT", "DUPLICATE_USER"],
+                stage="preflight",
+            )
+            new_decision_ids = [d["decision_id"] for d in all_decisions]
+
+        overall = _worst_status(results)
+
+        return PreflightResult(
+            overall=overall,
+            checks=results,
+            new_decision_ids=new_decision_ids,
+            merge_result=merge_result,
+        )
+
+    def _run_number_check(self, store: MigrationStore, numbers: list[dict]) -> CheckResult:
+        """Run number conflict check and capture decisions."""
+        result, decisions = check_number_conflicts(store, numbers)
+        self._number_decisions = decisions
+        return result
+
+    def _run_duplicate_check(self, store: MigrationStore, people: list[dict]) -> CheckResult:
+        """Run duplicate user check and capture decisions."""
+        result, decisions = check_duplicate_users(store, people)
+        self._user_decisions = decisions
+        return result
+
+    def _fetch(self, label: str, args: list[str]) -> list[dict]:
+        """Fetch data from wxcli, returning empty list on failure."""
+        try:
+            return _run_wxcli(args)
+        except PreflightError:
+            return []
+
+    def _build_bulk_job_probe(self):
+        """Return a zero-arg callable that probes the bulk device job endpoint.
+
+        Returns ``None`` if auth is unavailable — the check then SKIPs.
+        On invocation the callable returns ``(status_code, error_message)``.
+        Uses ``WebexSimpleApi`` so auth/orgId injection matches the rest of
+        the CLI.
+
+        Design note (Finding #11): this preflight module's convention is
+        **subprocess, not import** — checks normally shell out to ``wxcli``
+        via ``_run_wxcli`` to reuse the CLI's auth, pagination, and error
+        handling (see the module CLAUDE.md). This probe deliberately deviates
+        and calls ``api.session.get`` directly because there is no equivalent
+        ``wxcli`` subcommand that lists bulk device jobs — generating one
+        just to satisfy the convention would be overkill for a single
+        read-only probe. If ``wxcli`` ever gains a
+        ``bulk-device-jobs list --job-type callDeviceSettings --max 1``
+        command, this probe should be re-routed through ``_run_wxcli`` to
+        restore convention parity.
+        (Wave 4, Issue #9)
+        """
+        try:
+            from wxcli.auth import get_api
+        except Exception:
+            return None
+
+        try:
+            api = get_api()
+        except SystemExit:
+            # get_api raises typer.Exit when no token is configured
+            return None
+        except Exception:
+            return None
+
+        def _probe() -> tuple[int, str]:
+            import requests
+
+            url = api.session.ep("telephony/config/jobs/devices/callDeviceSettings")
+            params: dict[str, str] = {"max": "1"}
+            org_id = self.config.get("orgId") if isinstance(self.config, dict) else None
+            if org_id:
+                params["orgId"] = org_id
+            try:
+                resp = api.session.get(url, params=params)
+            except requests.RequestException as exc:
+                return 0, str(exc)
+            return resp.status_code, getattr(resp, "text", "") or ""
+
+        return _probe
+
+    def _count_existing_features(self) -> dict[str, int]:
+        """Count existing features in the Webex org."""
+        counts = {}
+        cmd_map = {
+            "auto_attendant": ["auto-attendant", "list"],
+            "call_queue": ["call-queue", "list"],
+            "hunt_group": ["hunt-group", "list"],
+            "paging_group": ["paging-group", "list"],
+        }
+        for obj_type, args in cmd_map.items():
+            try:
+                data = _run_wxcli(args)
+                counts[obj_type] = len(data)
+            except PreflightError:
+                counts[obj_type] = 0
+        return counts
+
+    def _dry_run(
+        self,
+        store: MigrationStore,
+        check_filter: str | None,
+    ) -> PreflightResult:
+        """Show what would be checked without querying Webex."""
+        checks_info = [
+            ("licenses", "User licenses", f"{store.count_by_type('user')} users to check"),
+            ("workspace-licenses", "Workspace licenses", f"{store.count_by_type('workspace')} workspaces to check"),
+            ("locations", "Locations", f"{len(store.get_objects('location'))} locations to verify"),
+            ("trunks", "Trunks", f"{len(store.get_objects('trunk'))} trunks to verify"),
+            ("features", "Feature entitlements", "AA, CQ, HG, Paging counts"),
+            ("numbers", "Number conflicts", "E.164 and extension collision check"),
+            ("users", "Duplicate users", f"{store.count_by_type('user')} users to check against Webex"),
+            ("rate-limit", "Rate limit budget", "API call estimate from plan_operations"),
+            ("e911-readiness", "E911 readiness", f"{store.count_by_type('user')} users ECBN candidate check"),
+            ("bulk-job-support", "Bulk device job support", "Probe for FedRAMP bulk device job support"),
+        ]
+
+        results = []
+        for key, name, detail in checks_info:
+            if check_filter and check_filter != key:
+                continue
+            results.append(CheckResult(
+                name=name,
+                status=CheckStatus.SKIP,
+                detail=f"[dry-run] Would check: {detail}",
+            ))
+
+        return PreflightResult(
+            overall=CheckStatus.SKIP,
+            checks=results,
+        )

wxcli/migration/rate_limiter.py

@@ -0,0 +1,144 @@
+"""Per-endpoint rate limiter with exponential backoff.
+
+Enforces max concurrent requests and handles 429 (Too Many Requests) responses
+with exponential backoff. Configurable via migration settings.
+
+(from cucm-wxc-migration.md lines 443-444,
+ 05-dependency-graph.md rate limit budget section)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+
+
+@dataclass
+class RateLimitConfig:
+    """Configuration for the rate limiter."""
+    max_concurrent: int = 5
+    base_delay: float = 1.0         # seconds
+    max_delay: float = 60.0         # seconds
+    backoff_factor: float = 2.0
+    max_retries: int = 5
+
+
+@dataclass
+class _EndpointState:
+    """Tracks backoff state for a single endpoint."""
+    consecutive_429s: int = 0
+    next_allowed_at: float = 0.0
+
+
+class RateLimiter:
+    """Per-endpoint rate limiter with exponential backoff on 429 responses.
+
+    Usage (sync):
+        limiter = RateLimiter()
+        with limiter.acquire("/v1/people"):
+            response = make_api_call()
+        if response.status_code == 429:
+            limiter.record_429("/v1/people")
+
+    Usage (async):
+        limiter = RateLimiter()
+        async with limiter.acquire_async("/v1/people"):
+            response = await make_api_call()
+        if response.status_code == 429:
+            limiter.record_429("/v1/people")
+    """
+
+    def __init__(self, config: RateLimitConfig | None = None) -> None:
+        self.config = config or RateLimitConfig()
+        self._semaphore = asyncio.Semaphore(self.config.max_concurrent)
+        self._sync_count: int = 0
+        self._sync_count_lock = None  # lazy init for threading
+        self._endpoints: dict[str, _EndpointState] = {}
+
+    def _get_endpoint(self, endpoint: str) -> _EndpointState:
+        if endpoint not in self._endpoints:
+            self._endpoints[endpoint] = _EndpointState()
+        return self._endpoints[endpoint]
+
+    def record_429(self, endpoint: str) -> float:
+        """Record a 429 response. Returns the delay (seconds) before next retry."""
+        state = self._get_endpoint(endpoint)
+        state.consecutive_429s += 1
+        delay = min(
+            self.config.base_delay * (self.config.backoff_factor ** state.consecutive_429s),
+            self.config.max_delay,
+        )
+        state.next_allowed_at = time.monotonic() + delay
+        return delay
+
+    def record_success(self, endpoint: str) -> None:
+        """Record a successful response, resetting backoff."""
+        state = self._get_endpoint(endpoint)
+        state.consecutive_429s = 0
+        state.next_allowed_at = 0.0
+
+    def should_retry(self, endpoint: str) -> bool:
+        """Check if retries are still allowed for this endpoint."""
+        state = self._get_endpoint(endpoint)
+        return state.consecutive_429s < self.config.max_retries
+
+    def wait_time(self, endpoint: str) -> float:
+        """Seconds to wait before the next request to this endpoint."""
+        state = self._get_endpoint(endpoint)
+        remaining = state.next_allowed_at - time.monotonic()
+        return max(0.0, remaining)
+
+    # -- Sync context manager --
+
+    class _SyncSlot:
+        """Sync concurrency slot.
+
+        Note: The sync acquire path uses a simple counter and is NOT
+        thread-safe.  For threaded usage, use ``acquire_async`` with an
+        asyncio event loop.  The executor uses the async path for
+        concurrent API requests.
+        """
+
+        def __init__(self, limiter: RateLimiter, endpoint: str) -> None:
+            self._limiter = limiter
+            self._endpoint = endpoint
+
+        def __enter__(self) -> _SyncSlot:
+            # Wait for per-endpoint backoff
+            wait = self._limiter.wait_time(self._endpoint)
+            if wait > 0:
+                time.sleep(wait)
+            # Enforce concurrency (simple counter — not thread-safe)
+            while self._limiter._sync_count >= self._limiter.config.max_concurrent:
+                time.sleep(0.05)
+            self._limiter._sync_count += 1
+            return self
+
+        def __exit__(self, *args: object) -> None:
+            self._limiter._sync_count -= 1
+
+    def acquire(self, endpoint: str) -> _SyncSlot:
+        """Sync context manager that enforces rate limits."""
+        return self._SyncSlot(self, endpoint)
+
+    # -- Async context manager --
+
+    class _AsyncSlot:
+        def __init__(self, limiter: RateLimiter, endpoint: str) -> None:
+            self._limiter = limiter
+            self._endpoint = endpoint
+
+        async def __aenter__(self) -> _AsyncSlot:
+            wait = self._limiter.wait_time(self._endpoint)
+            if wait > 0:
+                await asyncio.sleep(wait)
+            await self._limiter._semaphore.acquire()
+            return self
+
+        async def __aexit__(self, *args: object) -> None:
+            self._limiter._semaphore.release()
+
+    def acquire_async(self, endpoint: str) -> _AsyncSlot:
+        """Async context manager that enforces rate limits."""
+        return self._AsyncSlot(self, endpoint)