mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/deploy_target.py

@@ -0,0 +1,312 @@
+"""Go-live target resolution: explicit-only, read-and-refuse.
+
+A deploy target says where a live dataset would be published: which cloud project, which region,
+which Studio service account and worker job, and which cloud endpoint verifies API keys. Getting
+that answer wrong spends real money in a real project, so this module is deliberately unable to
+guess it.
+
+Two rules hold everywhere in this module:
+
+* Nothing is inferred. Every field comes from a mapping a human named explicitly. The module
+  never consults ambient ``gcloud`` configuration, never reads an environment variable for target
+  identity, and never shells out.
+* Nothing is created. The module never creates a project, never enables billing, and never
+  touches IAM. It reads a descriptor and either resolves it or refuses it.
+
+A refusal is a typed, quiet outcome that names its reasons, not a crash.
+
+Why the corroboration step exists
+---------------------------------
+
+The rule for this project is that live staging happens only against an unambiguously verified
+target, and that ambiguity means skip with a reason. On the machine this was written for, the
+target is ambiguous, measured rather than assumed:
+
+* ``gcloud config`` reports ``core/project=mostly-light``.
+* ``gcloud config`` reports ``billing/quota_project=mostlyright-backend``.
+* ``gcloud projects list`` returns PERMISSION_DENIED, so no third signal can break the tie.
+* The active account is a personal one, with an inactive company account also credentialed.
+
+Two config keys naming two different projects is exactly the case where a helpful default would
+be a costly one. So :func:`preflight` compares the explicit descriptor against a corroborating
+signal the caller supplies, and returns a refusal naming both values when they disagree. It never
+picks a winner.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlsplit
+
+REQUIRED_FIELDS: tuple[str, ...] = (
+    "gcp_project_id",
+    "region",
+    "studio_service_account",
+    "studio_worker_job",
+    "cloud_verify_url",
+)
+
+CORROBORATION_FIELDS: tuple[str, ...] = ("source", "gcp_project_id", "unreadable_reason")
+
+MAX_FIELD_LENGTH = 2048
+
+# GCP's documented project-id shape: 6 to 30 characters, a lowercase letter first, then lowercase
+# letters, digits, or hyphens, and never a trailing hyphen.
+_PROJECT_ID = re.compile(r"^[a-z][a-z0-9-]{4,28}[a-z0-9]$")
+
+# Cloud Run region shape, for example us-central1, europe-west4, asia-northeast1.
+_REGION = re.compile(r"^[a-z]{2,}-[a-z]{2,}[1-9][0-9]?$")
+
+
+class DeployTargetError(RuntimeError):
+    """A typed go-live target failure."""
+
+
+class TargetAmbiguityError(DeployTargetError, ValueError):
+    """The target could not be established beyond doubt, so it is refused."""
+
+
+def _https_url(value: str, label: str) -> str:
+    """Return ``value`` when it is a plain absolute https URL, otherwise refuse it.
+
+    This mirrors ``hosted_bootstrap._https_url`` (hosted_bootstrap.py:147) instead of importing
+    it. Importing that module pulls the entire hosted-worker stack (pyarrow, pandas, numpy,
+    cryptography) into a module whose whole job is to refuse quickly, and it raises
+    ``HostedWorkerError`` with a bootstrap-specific code that means nothing here. The URL policy
+    itself must stay identical to the bootstrap one: https only, an absolute URL, no user
+    information, no fragment, no trailing slash.
+    """
+
+    if not isinstance(value, str) or not 1 <= len(value) <= MAX_FIELD_LENGTH:
+        raise TargetAmbiguityError(f"{label} is not a usable URL")
+    if value.endswith("/"):
+        raise TargetAmbiguityError(f"{label} must not end with a slash")
+    parsed = urlsplit(value)
+    if (
+        parsed.scheme != "https"
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.fragment
+    ):
+        raise TargetAmbiguityError(
+            f"{label} must be an absolute https URL without user information or fragment"
+        )
+    return value
+
+
+@dataclass(frozen=True)
+class DeployTarget:
+    """One fully named go-live target; callers may narrow a target but never widen it.
+
+    Every field was named explicitly by a human. No field was inferred from ambient state, and no
+    field may be filled in later from a default, because a partially known target is exactly the
+    condition this module exists to refuse.
+    """
+
+    gcp_project_id: str
+    region: str
+    studio_service_account: str
+    studio_worker_job: str
+    cloud_verify_url: str
+
+    def __post_init__(self) -> None:
+        for name in REQUIRED_FIELDS:
+            value = getattr(self, name)
+            if type(value) is not str:
+                raise TargetAmbiguityError(f"{name} must be text that names one value")
+            if not value or value != value.strip():
+                raise TargetAmbiguityError(f"{name} is missing")
+            if len(value) > MAX_FIELD_LENGTH:
+                raise TargetAmbiguityError(f"{name} is longer than {MAX_FIELD_LENGTH} characters")
+        if not _PROJECT_ID.fullmatch(self.gcp_project_id):
+            raise TargetAmbiguityError(
+                "gcp_project_id is not a valid cloud project id: it must be 6 to 30 characters, "
+                "start with a lowercase letter, use only lowercase letters, digits, or hyphens, "
+                "and not end with a hyphen"
+            )
+        if not _REGION.fullmatch(self.region):
+            raise TargetAmbiguityError(
+                "region is not a valid cloud region, for example us-central1"
+            )
+        _https_url(self.cloud_verify_url, "cloud_verify_url")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a plain JSON-safe mapping of the named target."""
+
+        return {name: getattr(self, name) for name in REQUIRED_FIELDS}
+
+
+def resolve_deploy_target(descriptor: Mapping[str, object]) -> DeployTarget:
+    """Resolve an explicit descriptor into a :class:`DeployTarget`, or refuse it by name.
+
+    Load-bearing rule: this function reads only the mapping it is handed. It never consults
+    ambient ``gcloud`` configuration, never reads an environment variable for target identity,
+    never shells out, and never creates a project, enables billing, or touches IAM. It is
+    read-and-refuse only.
+
+    Unknown keys are refused rather than ignored, because a typo in a target descriptor is the
+    cheapest way to deploy into the wrong project.
+
+    Raises:
+        TargetAmbiguityError: when any field is absent, blank, malformed, or unrecognized.
+    """
+
+    if not isinstance(descriptor, Mapping):
+        raise TargetAmbiguityError(
+            "the deployment descriptor must be a mapping of field names to named values"
+        )
+
+    unknown = sorted(str(key) for key in descriptor if key not in REQUIRED_FIELDS)
+    if unknown:
+        raise TargetAmbiguityError(
+            "the deployment descriptor names fields this resolver does not know: "
+            + ", ".join(unknown)
+        )
+
+    values: dict[str, str] = {}
+    for name in REQUIRED_FIELDS:
+        if name not in descriptor:
+            raise TargetAmbiguityError(f"the deployment descriptor does not name {name}")
+        raw = descriptor[name]
+        if type(raw) is not str:
+            raise TargetAmbiguityError(f"{name} must be text that names one value")
+        value = raw.strip()
+        if not value:
+            raise TargetAmbiguityError(f"the deployment descriptor does not name {name}")
+        values[name] = value
+
+    return DeployTarget(**values)
+
+
+@dataclass(frozen=True)
+class DeployPreflight:
+    """The verdict on whether a go-live target is known beyond doubt.
+
+    Invariant: ``ok`` is true if and only if ``refusals`` is empty and ``target`` is not None.
+    Only two shapes exist. An ok verdict carries a resolved target and no reasons; a refusal
+    carries at least one named reason and no target at all. A refused verdict never hands back a
+    target, because a target in hand is the thing a caller acts on.
+    """
+
+    ok: bool
+    refusals: tuple[str, ...]
+    target: DeployTarget | None
+
+    def __post_init__(self) -> None:
+        if type(self.ok) is not bool:
+            raise DeployTargetError("ok must be a boolean verdict")
+        if type(self.refusals) is not tuple or any(
+            type(item) is not str or not item.strip() for item in self.refusals
+        ):
+            raise DeployTargetError("refusals must be a tuple of non-empty reasons")
+        if self.target is not None and not isinstance(self.target, DeployTarget):
+            raise DeployTargetError("target must be a resolved DeployTarget or None")
+        clean = not self.refusals and self.target is not None
+        if self.ok is not clean:
+            raise DeployTargetError(
+                "a preflight is ok only when there are no refusals and a target was resolved"
+            )
+        if not self.ok and (not self.refusals or self.target is not None):
+            raise DeployTargetError(
+                "a refused preflight must name at least one reason and carry no target"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a plain JSON-safe mapping of the verdict.
+
+        The verdict carries the named target values and the refusal reasons only. This module
+        accepts no credential of any kind, so a verdict cannot leak one.
+        """
+
+        return {
+            "ok": self.ok,
+            "refusals": list(self.refusals),
+            "target": None if self.target is None else self.target.to_dict(),
+        }
+
+
+def _corroborating_project(corroboration: Mapping[str, object]) -> tuple[str | None, str, str]:
+    """Return the corroborated project id (or None), its source, and why it was unreadable."""
+
+    if not isinstance(corroboration, Mapping):
+        raise TargetAmbiguityError(
+            "corroboration must be a mapping describing what an independent signal reports"
+        )
+    unknown = sorted(str(key) for key in corroboration if key not in CORROBORATION_FIELDS)
+    if unknown:
+        raise TargetAmbiguityError(
+            "corroboration names fields this resolver does not know: " + ", ".join(unknown)
+        )
+    for name in ("source", "unreadable_reason"):
+        value = corroboration.get(name)
+        if value is not None and type(value) is not str:
+            raise TargetAmbiguityError(f"corroboration {name} must be text")
+    project = corroboration.get("gcp_project_id")
+    if project is not None and type(project) is not str:
+        raise TargetAmbiguityError("corroboration gcp_project_id must be text or absent")
+
+    source = str(corroboration.get("source") or "").strip() or "no corroborating signal"
+    reason = str(corroboration.get("unreadable_reason") or "").strip() or "nothing readable"
+    named = None if project is None else project.strip() or None
+    return named, source, reason
+
+
+def preflight(
+    descriptor: Mapping[str, object],
+    *,
+    corroboration: Mapping[str, object],
+) -> DeployPreflight:
+    """Judge whether a go-live target is known beyond doubt, and refuse quietly when it is not.
+
+    ``corroboration`` describes what an independent signal reports about the target: a
+    ``gcp_project_id`` read from a deployment config, plus an optional ``source`` naming where
+    it came
+    from and an optional ``unreadable_reason`` when no signal could be read at all.
+
+    The caller supplies that signal. This module refuses to be the thing that learns the answer,
+    because a component that can discover a target can also silently pick the wrong one. It runs
+    no ``gcloud`` command, creates no project, enables no billing, and touches no IAM.
+
+    An ambiguous input is never an exception; it is a verdict with named reasons. Only a
+    structurally invalid call raises.
+
+    Raises:
+        TargetAmbiguityError: when ``descriptor`` or ``corroboration`` is not a well-formed
+            mapping of the fields this resolver knows.
+    """
+
+    if not isinstance(descriptor, Mapping):
+        raise TargetAmbiguityError(
+            "the deployment descriptor must be a mapping of field names to named values"
+        )
+    corroborated, source, reason = _corroborating_project(corroboration)
+
+    refusals: list[str] = []
+    target: DeployTarget | None
+    try:
+        target = resolve_deploy_target(descriptor)
+    except TargetAmbiguityError as error:
+        target = None
+        refusals.append(str(error))
+
+    if corroborated is None:
+        refusals.append(
+            f"the target project could not be corroborated: {source} reported {reason}; "
+            "go-live is refused until an independent signal names the target project"
+        )
+    elif target is not None and corroborated != target.gcp_project_id:
+        refusals.append(
+            "target project is ambiguous: the deployment descriptor names "
+            f"{target.gcp_project_id}, "
+            f"the corroborating signal ({source}) names {corroborated}; "
+            "name one explicitly before going live"
+        )
+
+    if refusals:
+        # A refused verdict never carries a target: the caller must have nothing to act on.
+        return DeployPreflight(ok=False, refusals=tuple(refusals), target=None)
+    return DeployPreflight(ok=True, refusals=(), target=target)