mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/thin/session.py

@@ -0,0 +1,281 @@
+"""The device credential this machine stores, exchanged for a short-lived Studio token.
+
+The flow is the one ADR 0015 settled and ``mr-data login`` already writes half of: a durable
+``mr_cli_`` device key lives at ``~/.mostlyright/credentials`` at mode 0600, and every
+cloud-touching command trades it at Cloud's ``/api/cli/studio-token`` for a token that expires in
+minutes and names the workspace it is good for. The device key never reaches Studio and the
+Studio token is never written to disk.
+
+⚠ THE 503 RETRY IS NOT OPTIONAL POLISH. Studio scales to zero, and Cloud provisions this
+workspace's tenancy on every exchange, so the request that WAKES Studio is the request that has to
+wait for it. Cloud distinguishes the two 503 shapes by stamping ``retry-after`` on the one worth
+retrying and nothing on the one no amount of waiting can fix, so the ABSENCE of the header is the
+signal to stop. This mirrors ``hosted_deploy.exchange_studio_token``, which learned it from eight
+recorded production failures on 2026-08-20.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+from urllib.parse import quote, urlencode
+from uuid import UUID
+
+from mostlyright.data_harness.canonical import CanonicalJSONError, parse_json
+from mostlyright.data_harness.thin.transport import (
+    MAX_JSON_RESPONSE_BYTES,
+    ThinLaneError,
+    Transport,
+    UrlLibTransport,
+    service_origin,
+)
+from mostlyright.data_harness.ux.credentials import ResolvedCloudCredentials
+
+#: Cloud's token-exchange route. Held identical to ``hosted_deploy.CLOUD_TOKEN_PATH`` by a test.
+CLOUD_TOKEN_PATH = "/api/cli/studio-token"
+
+#: The Cloud page a person opens about one run. ADR 0021 makes the live run view the place a
+#: hosted submission points at, and ``mostlyright-cloud`` serves it at this route
+#: (``dashboard/app/dashboard/runs/[runId]/page.tsx``). The origin is never hardcoded beyond the
+#: configured Cloud URL, which ``MOSTLYRIGHT_CLOUD_URL`` overrides and the stored credential
+#: carries.
+CLOUD_RUN_DASHBOARD_PATH = "/dashboard/runs/{run_id}"
+
+#: The durable Cloud home of one Dataset. Research starts here before a session exists, then the
+#: same page follows the exact session run through :func:`dataset_research_dashboard_url`.
+CLOUD_DATASET_DASHBOARD_PATH = "/dashboard/datasets/{dataset_id}"
+
+#: The Cloud page a person opens to settle one approval. ``mostlyright-cloud`` serves it at
+#: ``dashboard/app/dashboard/approvals/[approvalRequestId]/page.tsx`` -- the sibling of the run
+#: page above, and the address ``mr-data propose`` prints for the human who must grant the Table
+#: recipe approval it opened. It is where a person goes; the actual step-up or editor confirmation
+#: is what ``mr-data recipe-approve`` records once they have.
+CLOUD_APPROVAL_DASHBOARD_PATH = "/dashboard/approvals/{approval_request_id}"
+
+MAX_TOKEN_RESPONSE_BYTES = 32 * 1024
+TOKEN_EXCHANGE_RETRY_ATTEMPTS = 2
+TOKEN_EXCHANGE_MAX_RETRY_SECONDS = 30.0
+
+_CLI_KEY = re.compile(r"^mr_cli_[A-Za-z0-9_-]{64}$")
+
+
+@dataclass(frozen=True)
+class StudioSession:
+    """One short-lived Studio authority: where to call, as whom, and until when."""
+
+    studio_base_url: str
+    workspace_id: UUID
+    token: str
+    expires_at: datetime
+    cloud_url: str
+
+    def __repr__(self) -> str:
+        return (
+            "StudioSession("
+            f"studio_base_url={self.studio_base_url!r}, workspace_id={self.workspace_id!r}, "
+            f"token='<redacted>', expires_at={self.expires_at!r}, cloud_url={self.cloud_url!r})"
+        )
+
+    def authorization(self) -> dict[str, str]:
+        """The bearer header every Studio call in this lane carries, and nothing else."""
+
+        return {"Authorization": f"Bearer {self.token}"}
+
+    def to_receipt(self) -> dict[str, Any]:
+        """Everything about this session except the token."""
+
+        return {
+            "studio_base_url": self.studio_base_url,
+            "workspace_id": str(self.workspace_id),
+            "expires_at": self.expires_at.isoformat().replace("+00:00", "Z"),
+        }
+
+
+def run_dashboard_url(cloud_url: str, run_id: str) -> str:
+    """The Cloud live-run page for one run, from one validated origin."""
+
+    origin = service_origin(cloud_url, "Cloud URL", allow_loopback_http=False)
+    return origin + CLOUD_RUN_DASHBOARD_PATH.format(run_id=run_id)
+
+
+def dataset_dashboard_url(cloud_url: str, dataset_id: str) -> str:
+    """The Cloud detail page for one Dataset, with its identifier held to one path segment."""
+
+    origin = service_origin(cloud_url, "Cloud URL", allow_loopback_http=False)
+    encoded_dataset_id = quote(str(dataset_id), safe="")
+    return origin + CLOUD_DATASET_DASHBOARD_PATH.format(dataset_id=encoded_dataset_id)
+
+
+def dataset_research_dashboard_url(cloud_url: str, dataset_id: str, run_id: str) -> str:
+    """The exact research run embedded in one Dataset detail page.
+
+    Path and query coordinates are encoded independently so neither can introduce a sibling path,
+    another query member, or a fragment. The fragment is the fixed UI section identifier.
+    """
+
+    base = dataset_dashboard_url(cloud_url, dataset_id)
+    query = urlencode({"run": str(run_id)}, quote_via=quote, safe="")
+    return f"{base}?{query}#research"
+
+
+def approval_dashboard_url(cloud_url: str, approval_request_id: str) -> str:
+    """The Cloud approvals page for one approval request, from the same validated origin.
+
+    The sibling of :func:`run_dashboard_url`: ``mr-data propose`` opens a Table recipe approval
+    and hands a person this address to settle it, the way ``mr-data approve`` prints the human
+    action Studio names. Both go through :func:`service_origin`, so the origin is checked once and
+    the two surfaces cannot drift into two spellings of one Cloud URL.
+    """
+
+    origin = service_origin(cloud_url, "Cloud URL", allow_loopback_http=False)
+    return origin + CLOUD_APPROVAL_DASHBOARD_PATH.format(approval_request_id=approval_request_id)
+
+
+def require_device_key(credentials: ResolvedCloudCredentials) -> None:
+    """Refuse a credential that is not an ``mr_cli_`` device key.
+
+    A live data key authenticates too, and it has read-only scope, so accepting one here would
+    trade a clear refusal now for an opaque 403 from Studio three calls later.
+    """
+
+    if _CLI_KEY.fullmatch(credentials.raw_key) is None:
+        raise ThinLaneError(
+            "THIN_AUTHENTICATION_FAILED",
+            "the hosted lane requires an mr_cli_ device credential; run mr-data login",
+        )
+
+
+def _text(value: Mapping[str, Any], field: str) -> str:
+    selected = value.get(field)
+    if not isinstance(selected, str) or not selected:
+        raise ThinLaneError("THIN_RESPONSE_INVALID", f"the response omitted {field}")
+    return selected
+
+
+def _uuid(value: str, field: str) -> UUID:
+    try:
+        return UUID(value)
+    except ValueError as error:
+        raise ThinLaneError("THIN_RESPONSE_INVALID", f"{field} is not a UUID") from error
+
+
+def _timestamp(value: str, field: str) -> datetime:
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as error:
+        raise ThinLaneError("THIN_RESPONSE_INVALID", f"{field} is not a timestamp") from error
+    if parsed.tzinfo is None or parsed.utcoffset() != UTC.utcoffset(parsed):
+        raise ThinLaneError("THIN_RESPONSE_INVALID", f"{field} is not UTC")
+    return parsed
+
+
+def _transient_retry_seconds(headers: Mapping[str, str]) -> float | None:
+    """Seconds Cloud asked this command to wait, or ``None`` when it did not ask at all.
+
+    ⚠ The absence of ``retry-after`` is the signal, not a missing detail to paper over: Cloud's
+    cold-start 503 stamps it and its "Studio is not configured here" 503 does not. A malformed or
+    out-of-range value fails toward refusing now rather than sleeping on a number we do not trust.
+    """
+
+    raw = headers.get("retry-after", "")
+    if not raw.isdecimal():
+        return None
+    seconds = int(raw)
+    if not 1 <= seconds <= 3600:
+        return None
+    return float(min(seconds, TOKEN_EXCHANGE_MAX_RETRY_SECONDS))
+
+
+def open_studio_session(
+    credentials: ResolvedCloudCredentials,
+    *,
+    transport: Transport | None = None,
+    now: Callable[[], datetime] = lambda: datetime.now(UTC),
+    sleep: Callable[[float], None] = time.sleep,
+) -> StudioSession:
+    """Exchange the stored device key for a short-lived Studio token."""
+
+    require_device_key(credentials)
+    cloud_url = service_origin(credentials.cloud_url, "Cloud URL", allow_loopback_http=False)
+    selected = transport or UrlLibTransport()
+    attempts_remaining = TOKEN_EXCHANGE_RETRY_ATTEMPTS
+    while True:
+        try:
+            status, raw, headers = selected.request(
+                "POST",
+                f"{cloud_url}{CLOUD_TOKEN_PATH}",
+                {"Accept": "application/json", "x-api-key": credentials.raw_key},
+                b"",
+                MAX_TOKEN_RESPONSE_BYTES,
+            )
+        except ThinLaneError:
+            raise
+        except Exception as error:
+            raise ThinLaneError(
+                "THIN_TOKEN_EXCHANGE_FAILED", "the Cloud token exchange could not be reached"
+            ) from error
+        if status != 503 or attempts_remaining == 0:
+            break
+        delay = _transient_retry_seconds(headers)
+        if delay is None:
+            break
+        attempts_remaining -= 1
+        sleep(delay)
+    if status == 401:
+        raise ThinLaneError(
+            "THIN_AUTHENTICATION_FAILED", "the stored device credential was rejected"
+        )
+    if status == 402:
+        raise ThinLaneError(
+            "THIN_SUBSCRIPTION_REQUIRED", "this workspace has no hosted execution access"
+        )
+    if status == 429:
+        raise ThinLaneError("THIN_RATE_LIMITED", "Cloud asked this command to retry later")
+    if status == 503:
+        raise ThinLaneError(
+            "THIN_STUDIO_UNAVAILABLE",
+            "Studio is not configured, or stayed unavailable across every attempt",
+        )
+    try:
+        parsed = parse_json(raw)
+    except CanonicalJSONError:
+        parsed = None
+    if status != 200 or not isinstance(parsed, dict):
+        raise ThinLaneError(
+            "THIN_TOKEN_EXCHANGE_FAILED", f"the Cloud token exchange failed (HTTP {status})"
+        )
+    expires_at = _timestamp(_text(parsed, "expires_at"), "expires_at")
+    if expires_at <= now():
+        raise ThinLaneError("THIN_TOKEN_EXCHANGE_FAILED", "Cloud returned an expired Studio token")
+    return StudioSession(
+        studio_base_url=service_origin(
+            _text(parsed, "studio_base_url"), "Studio base URL", allow_loopback_http=True
+        ),
+        workspace_id=_uuid(_text(parsed, "workspace_id"), "workspace_id"),
+        token=_text(parsed, "token"),
+        expires_at=expires_at,
+        cloud_url=cloud_url,
+    )
+
+
+__all__ = [
+    "CLOUD_APPROVAL_DASHBOARD_PATH",
+    "CLOUD_DATASET_DASHBOARD_PATH",
+    "CLOUD_RUN_DASHBOARD_PATH",
+    "CLOUD_TOKEN_PATH",
+    "MAX_JSON_RESPONSE_BYTES",
+    "MAX_TOKEN_RESPONSE_BYTES",
+    "TOKEN_EXCHANGE_MAX_RETRY_SECONDS",
+    "TOKEN_EXCHANGE_RETRY_ATTEMPTS",
+    "StudioSession",
+    "approval_dashboard_url",
+    "dataset_dashboard_url",
+    "dataset_research_dashboard_url",
+    "open_studio_session",
+    "require_device_key",
+    "run_dashboard_url",
+]