Sync from dev @ 252c1cf

Source: main (252c1cf)
Excluded: live tenant exports, generated artifacts, and dev-only tooling.

scripts/common.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Shared utilities for Intune / Entra drift backup scripts."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import time
+import urllib.error
+import urllib.request
+from typing import Any
+
+
+def env_text(name: str, default: str = "") -> str:
+    """Read and sanitize an environment variable, treating unresolved Azure DevOps
+    macros $(...) as empty.
+    """
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    value = raw.strip()
+    if re.fullmatch(r"\$\([^)]+\)", value):
+        return default
+    if not value:
+        return default
+    return value
+
+
+def env_bool(name: str, default: bool = False) -> bool:
+    """Interpret an environment variable as a boolean."""
+    raw = env_text(name, "")
+    if not raw:
+        return default
+    return raw.lower() in {"1", "true", "yes", "y", "on"}
+
+
+def normalize_exclude_csv(value: str) -> str:
+    """Normalize an exclude CSV value, treating sentinel values as empty."""
+    normalized = str(value or "").strip()
+    if normalized.lower() in {"", "none", "null", "n/a", "-", "_none_"}:
+        return ""
+    return normalized
+
+
+def normalize_merge_strategy(value: str) -> str:
+    """Normalize a merge strategy string to an Azure DevOps API value."""
+    raw = (value or "").strip().lower().replace("-", "").replace("_", "")
+    aliases = {
+        "nofastforward": "noFastForward",
+        "mergecommit": "noFastForward",
+        "merge": "noFastForward",
+        "squash": "squash",
+        "rebase": "rebase",
+        "rebasefastforward": "rebase",
+        "rebaseff": "rebase",
+        "rebasemerge": "rebaseMerge",
+    }
+    return aliases.get(raw, "rebase")
+
+
+def _get_retry_after_seconds(error: urllib.error.HTTPError) -> float | None:
+    try:
+        retry_after = error.headers.get("Retry-After")
+        if retry_after:
+            return float(retry_after)
+    except Exception:
+        pass
+    return None
+
+
+def request_json(
+    url: str,
+    method: str = "GET",
+    body: dict[str, Any] | None = None,
+    headers: dict[str, str] | None = None,
+    token: str | None = None,
+    timeout: float = 60,
+    max_retries: int = 0,
+) -> Any:
+    """Make a JSON HTTP request and return the parsed response.
+
+    If *token* is provided, an Authorization header is added automatically.
+    If *max_retries* is greater than zero, transient HTTP errors (429, 500,
+    502, 503, 504) are retried with exponential back-off.
+    """
+    req_headers: dict[str, str] = {
+        "Accept": "application/json",
+    }
+    if token is not None:
+        req_headers["Authorization"] = f"Bearer {token}"
+    if headers is not None:
+        req_headers.update(headers)
+
+    payload: bytes | None = None
+    if body is not None:
+        payload = json.dumps(body).encode("utf-8")
+        req_headers.setdefault("Content-Type", "application/json")
+
+    retry_codes = {429, 500, 502, 503, 504}
+    last_error: Exception | None = None
+
+    for attempt in range(max_retries + 1):
+        req = urllib.request.Request(
+            url,
+            data=payload,
+            method=method,
+            headers=req_headers,
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as exc:
+            last_error = exc
+            if exc.code not in retry_codes or attempt == max_retries:
+                raise
+            retry_after = _get_retry_after_seconds(exc)
+            sleep = retry_after if retry_after is not None else (2 ** attempt)
+            time.sleep(sleep)
+        except urllib.error.URLError as exc:
+            last_error = exc
+            if attempt == max_retries:
+                raise
+            time.sleep(2 ** attempt)
+
+    # Should never be reached; satisfy type checker.
+    if last_error is not None:
+        raise last_error
+    raise RuntimeError("request_json exhausted all retries")
+
+
+def run_git(repo_root: str | os.PathLike[str], args: list[str], check: bool = True) -> str:
+    """Run a git command and return stdout as a stripped string."""
+    proc = subprocess.run(
+        ["git", *args],
+        cwd=str(repo_root),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        check=False,
+    )
+    if check and proc.returncode != 0:
+        stderr = (proc.stderr or "").strip()
+        raise RuntimeError(f"git {' '.join(args)} failed ({proc.returncode}): {stderr}")
+    return proc.stdout.strip()
+
+
+def configure_git_identity(
+    repo_root: str | os.PathLike[str],
+    fallback_name: str | None = None,
+    fallback_email: str | None = None,
+) -> None:
+    """Configure git user.name and user.email from pipeline env vars."""
+    requested_for = (os.environ.get("BUILD_REQUESTEDFOR") or "").strip()
+    requested_for_email = (os.environ.get("BUILD_REQUESTEDFOREMAIL") or "").strip()
+    fallback_name = (fallback_name or os.environ.get("USER_NAME") or "ASTRAL Backup Service").strip()
+    fallback_email = (fallback_email or os.environ.get("USER_EMAIL") or "intune-backup@local.invalid").strip()
+
+    author_name = requested_for or fallback_name
+    author_email = requested_for_email if "@" in requested_for_email else fallback_email
+
+    run_git(repo_root, ["config", "user.name", author_name])
+    run_git(repo_root, ["config", "user.email", author_email])