mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/thin/approvals.py

@@ -0,0 +1,617 @@
+"""``mr-data approve`` and ``mr-data recipe-approve``, answered from Studio -- without deciding.
+
+WHAT CHANGED, AND WHAT DID NOT. Studio PR #95 did not give a hosted command line the authority to
+approve anything, and this module does not take any. A decision still needs a human: a run
+candidate is decided only against a freshly verified, operation-bound step-up, and a Table recipe
+only from an ordinary signed-in editor session. A Cloud-minted Studio token resolves to the
+organization's *service* principal, which both of those gates refuse by design, and lending that
+signing authority to a stored credential would dismantle the property the gates exist for.
+
+What was missing was never authority. It was everything between "open a request" and "wait
+forever": no way to say which decision was wanted or why, no way to tell the person who must settle
+it where to go, and no way to read what they decided. Those three are what this module adds.
+
+THE THREE CALLS, IN ORDER.
+
+1. ``GET /v3/approvals/{id}`` -- read the request, its ``version``, its ``subject_digest`` and its
+   ``ETag``. The ask is pinned to exactly that reading, so it can never be mistaken for an ask
+   about a later state of the same approval.
+2. ``POST /v3/approvals/{id}:approve`` with ``If-Match`` and ``Idempotency-Key`` -- record the ask.
+   Studio answers with ``human_action``: the one path this subject actually takes, and the address
+   a person opens to take it. Studio is the only party that knows which of the two it is, and a
+   client that guessed would send half its users to a page that cannot do what they were told.
+3. ``GET /v3/approvals/{id}`` on ``poll_after_seconds`` until the status is no longer pending, then
+   ``GET /v3/approvals/{id}/decision`` -- the receipt: who decided, when, under which step-up, and
+   against which audit digest.
+
+⚠ THE NEVER-DECIDES PROPERTY IS STRUCTURAL HERE, NOT A PROMISE IN A COMMENT. The only mutation
+this module can make is :data:`APPROVE_PATH`, and :data:`DECIDE_PATH` is written down precisely so
+a reader can see it is never called: ``tests/test_thin_parity.py`` asserts no request this lane
+makes reaches it. Every other call below is a GET.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import time
+from collections.abc import Callable, Mapping
+from typing import Any
+from uuid import UUID
+
+from mostlyright.data_harness.thin import THIN_SCHEMA_PREFIX
+
+# `_no_effect` is the accepted-but-inert flag reporter, imported rather than written a second
+# time: `thin.parity` already owns the one rule about telling a default apart from an argument
+# somebody typed, and two copies of that rule is how `--wait-seconds 0` starts being read as
+# absent.
+from mostlyright.data_harness.thin.parity import _no_effect
+from mostlyright.data_harness.thin.runs import StudioApiClient, new_idempotency_key
+from mostlyright.data_harness.thin.session import (
+    StudioSession,
+    open_studio_session,
+    run_dashboard_url,
+)
+from mostlyright.data_harness.thin.transport import ThinLaneError
+from mostlyright.data_harness.ux.credentials import resolve_cloud_credentials
+
+APPROVE_SCHEMA = f"{THIN_SCHEMA_PREFIX}-approval.v1"
+
+#: The routes. ``APPROVE_PATH`` is the only one this lane may POST to.
+GET_APPROVAL_PATH = "/v3/approvals/{approval_request_id}"
+APPROVE_PATH = "/v3/approvals/{approval_request_id}:approve"
+APPROVAL_DECISION_PATH = "/v3/approvals/{approval_request_id}/decision"
+
+#: The route that records a decision, written down so that "this lane never calls it" is an
+#: assertion a test can make rather than a sentence somebody has to believe. Nothing in this
+#: module formats it.
+DECIDE_PATH = "/v3/approvals/{approval_request_id}:decide"
+
+#: ``approval.schema.json#/$defs/grant_request_command/properties/decision``.
+DECISIONS = ("approved", "rejected")
+
+#: ``approval.schema.json#/$defs/request/properties/status``. ``pending`` is the one that means
+#: "keep waiting"; the other four all settle it, and three of them settle it as a no.
+APPROVAL_STATUSES = ("pending", "approved", "rejected", "expired", "cancelled")
+
+#: The two human paths, and the sentence each one gets. Studio names the kind; this names what a
+#: person does about it, because ``dashboard_confirmation`` is not an instruction.
+HUMAN_ACTION_SENTENCE = {
+    "interactive_step_up": (
+        "open this address and complete the step-up there; a run-candidate approval is recorded "
+        "only against a freshly verified, operation-bound step-up"
+    ),
+    "dashboard_confirmation": (
+        "open this address and confirm it in the dashboard; a Table recipe is confirmed from an "
+        "ordinary signed-in editor session, which deliberately refuses a step-up credential"
+    ),
+}
+
+#: The one sentence this lane says about itself in every answer it prints, whatever the outcome.
+#: It is a payload key rather than a docstring because the property it states -- that nothing here
+#: decided anything -- is the property somebody reading the output needs to be able to check.
+NEVER_DECIDES = (
+    "this command asked; it did not decide. Studio records an approval decision only from a "
+    "human, through the operation named under human_action"
+)
+
+#: How long a `--wait-seconds` may ask for. Above this a person is not waiting at a terminal, and
+#: a command line holding a socket open for a day is a command line somebody kills.
+MAX_WAIT_SECONDS = 86_400
+
+#: What to wait when Studio's own ``poll_after_seconds`` is missing or out of contract. The
+#: contract bounds it at 1..3600; a value outside that is Studio saying something this lane does
+#: not understand, and guessing small would turn one unreadable field into a poll storm.
+DEFAULT_POLL_SECONDS = 15
+MAX_POLL_SECONDS = 3_600
+
+#: How long ``approve`` waits for a person by default. Fifteen minutes is long enough for somebody
+#: who is at their desk and short enough that a CI job pointed at an approval nobody is watching
+#: fails on its own rather than holding a runner until the job timeout kills it. ``0`` records the
+#: ask, prints where it is settled, and returns.
+DEFAULT_WAIT_SECONDS = 900
+
+_ETAG = re.compile(r'^(?:W/)?"[\x21\x23-\x7e]{1,128}"$')
+
+
+class StudioApprovalClient(StudioApiClient):
+    """The three approval calls, and no fourth one.
+
+    ``approve`` is a POST and is the only mutation in this class. It writes an ask and cannot write
+    a decision: Studio's handler creates one immutable grant-request row, never sets ``status``,
+    and never reaches the decision path -- which the upstream suite asserts directly, and which
+    this lane relies on rather than restates.
+    """
+
+    def get_approval(self, approval_request_id: str) -> tuple[dict[str, Any], str | None]:
+        """One approval request, with the ETag a later ``If-Match`` has to carry.
+
+        The ETag is returned beside the body rather than folded into it, because it is a transport
+        fact about this reading and not a field of the resource: putting it in the payload would
+        make it look like something Studio said about the approval.
+        """
+
+        headers: dict[str, str] = {}
+        record = self._call(
+            "GET",
+            GET_APPROVAL_PATH.format(approval_request_id=approval_request_id),
+            expected=(200,),
+            response_headers=headers,
+        )
+        etag = headers.get("etag")
+        return record, etag if isinstance(etag, str) and _ETAG.fullmatch(etag) else None
+
+    def request_grant(
+        self,
+        approval_request_id: str,
+        *,
+        body: Mapping[str, Any],
+        if_match: str,
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        """Record what the caller wants, pinned to the exact request version it read."""
+
+        return self._call(
+            "POST",
+            APPROVE_PATH.format(approval_request_id=approval_request_id),
+            body=body,
+            extra_headers={
+                "If-Match": if_match,
+                "Idempotency-Key": idempotency_key or new_idempotency_key("mr-data-approve"),
+            },
+            expected=(201,),
+        )
+
+    def get_decision(self, approval_request_id: str) -> dict[str, Any]:
+        """The immutable decision that settled one approval. A read, and it grants nothing."""
+
+        return self._call(
+            "GET",
+            APPROVAL_DECISION_PATH.format(approval_request_id=approval_request_id),
+            expected=(200,),
+        )
+
+
+def grant_request_body(
+    *,
+    workspace_id: UUID,
+    decision: str,
+    expected_request_version: int,
+    subject_digest: str,
+    reason: str | None = None,
+) -> dict[str, Any]:
+    """The ``ApprovalGrantRequestCommand`` this lane sends, with the contract applied here.
+
+    Every field is refused locally before it can become a 422 from Studio, and ``reason`` is the
+    one field a person types freely: it is bounded and its control characters are refused by the
+    same pattern the schema declares, because a sentence that lands in somebody else's approval
+    queue is attacker-controlled text wherever it came from.
+    """
+
+    if decision not in DECISIONS:
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID", "the decision to ask for must be approved or rejected"
+        )
+    if type(expected_request_version) is not int or expected_request_version < 1:
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID", "Studio's approval carries no version to pin the ask to"
+        )
+    if not isinstance(subject_digest, str) or not subject_digest:
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID", "Studio's approval carries no subject digest to pin the ask to"
+        )
+    body: dict[str, Any] = {
+        "schema_version": "3.0.0",
+        "workspace_id": str(workspace_id),
+        "decision": decision,
+        "expected_request_version": expected_request_version,
+        "subject_digest": subject_digest,
+    }
+    if reason is not None:
+        if not 1 <= len(reason) <= 2000 or re.search(r"[\x00-\x1f\x7f]", reason):
+            raise ThinLaneError(
+                "THIN_REQUEST_INVALID",
+                "--reason is one line of at most 2000 characters, with no control characters",
+            )
+        body["reason"] = reason
+    return body
+
+
+def _session(args: argparse.Namespace) -> StudioSession:
+    return open_studio_session(resolve_cloud_credentials())
+
+
+def _client(args: argparse.Namespace) -> StudioApprovalClient:
+    return StudioApprovalClient(_session(args))
+
+
+def _approval_id(value: Any) -> str:
+    """Refuse anything that is not an approval identifier before it reaches a URL path.
+
+    Checked before a credential is resolved and a token minted, and the sentence names the
+    substitution: a path to a Recipe file is exactly what somebody moving over from the local lane
+    types here first, because that is what ``--recipe`` means there.
+    """
+
+    try:
+        return str(UUID(str(value)))
+    except (ValueError, AttributeError) as error:
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            f"{value!r} is not an approval identifier; the hosted lane names the approval Studio "
+            f"holds, not a Recipe file on this computer",
+        ) from error
+
+
+def _human_action(grant: Mapping[str, Any]) -> dict[str, Any]:
+    """Where a person settles this, said in their words as well as Studio's.
+
+    ⚠ Mandatory. An ask whose answer carries no human action is an ask nobody can act on, and
+    reporting one as a success would be the "wait forever" this whole lane exists to end.
+    """
+
+    action = grant.get("human_action")
+    if not isinstance(action, Mapping):
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID",
+            "Studio recorded the ask without saying where a human settles it",
+        )
+    kind = action.get("kind")
+    url = action.get("url")
+    if not isinstance(kind, str) or not isinstance(url, str) or not url.startswith("https://"):
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID", "Studio named a human action with no usable address"
+        )
+    roles = action.get("roles")
+    return {
+        "kind": kind,
+        "url": url,
+        "operation_id": action.get("operation_id"),
+        "roles": list(roles) if isinstance(roles, list) else [],
+        "what_to_do": HUMAN_ACTION_SENTENCE.get(
+            kind, "open this address; Studio named a human path this client has no sentence for"
+        ),
+    }
+
+
+def _poll_seconds(grant: Mapping[str, Any]) -> int:
+    declared = grant.get("poll_after_seconds")
+    if type(declared) is int and 1 <= declared <= MAX_POLL_SECONDS:
+        return declared
+    return DEFAULT_POLL_SECONDS
+
+
+def _decision_receipt(decision: Mapping[str, Any]) -> dict[str, Any]:
+    """The decision coordinates a person reads, exactly as Studio reported them."""
+
+    return {
+        key: decision[key]
+        for key in (
+            "approval_decision_id",
+            "approval_request_id",
+            "run_id",
+            "decision",
+            "actor_principal_id",
+            "actor_kind",
+            "actor_role",
+            "interactive",
+            "step_up",
+            "expected_request_version",
+            "subject_digest",
+            "decided_at",
+            "audit_digest",
+        )
+        if key in decision
+    }
+
+
+def _request_receipt(record: Mapping[str, Any]) -> dict[str, Any]:
+    return {
+        key: record[key]
+        for key in (
+            "approval_request_id",
+            "subject_kind",
+            "subject_id",
+            "recipe_proposal_id",
+            "run_id",
+            "approval_type",
+            "status",
+            "subject_digest",
+            "version",
+            "created_at",
+            "expires_at",
+            "approval_decision_id",
+            "decided_at",
+        )
+        if key in record
+    }
+
+
+#: Every local flag whose meaning does not survive the move, and the sentence it gets. Accepted and
+#: reported, never refused, for the reason the rest of this lane already gives: a flag that errors
+#: is a script that breaks on a machine that installed a different extra.
+#:
+#: The first four are the same argument in four spellings -- who decided, when, under what -- and
+#: every one of them is a fact Studio records about the human who actually decided. A hosted lane
+#: that accepted a caller's word for any of them would be recording an approval's provenance from
+#: the party that is not allowed to grant it.
+_APPROVAL_NO_EFFECT = (
+    (
+        "approved_by",
+        "--approved-by",
+        "Studio records who decided, from the human session that decided; a caller cannot name "
+        "the approver of a decision it is not allowed to make",
+    ),
+    (
+        "approved_at",
+        "--approved-at",
+        "Studio records when the decision was made, from its own clock at the moment it was made",
+    ),
+    (
+        "approval_id",
+        "--approval-id",
+        "the approval already has an identifier here: it is the one this command names",
+    ),
+    (
+        "approval_policy",
+        "--approval-policy",
+        "the policy a hosted approval is decided under is the workspace's, and Studio applies it",
+    ),
+    (
+        "approval_policy_digest",
+        "--approval-policy-digest",
+        "the policy a hosted approval is decided under is the workspace's, and Studio applies it",
+    ),
+    (
+        "output",
+        "--output",
+        "the decision is Studio's immutable record and is read back from it; writing a second "
+        "copy here would be a local file that says approved and proves nothing",
+    ),
+)
+
+
+def approve(
+    args: argparse.Namespace,
+    *,
+    client: StudioApprovalClient | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+    clock: Callable[[], float] = time.monotonic,
+) -> dict[str, Any]:
+    """``mr-data approve``: ask for the decision, say where a person makes it, read what they did.
+
+    The local command freezes a Recipe on this computer by writing an approval file beside it.
+    There is no file here and no Recipe here: a hosted approval is a record Studio holds and a
+    decision a person makes in a browser, so this names the approval, records what was asked for,
+    prints where it is settled, and then reads the receipt back.
+
+    ⚠ WHAT ``approved`` MEANS IN THIS PAYLOAD. It means a human recorded that decision and Studio
+    returned its receipt. It never means this command approved anything, and the payload says so
+    under ``never_decides`` whatever the outcome.
+    """
+
+    approval_id = _approval_id(getattr(args, "recipe", None))
+    selected = client or _client(args)
+    record, etag = selected.get_approval(approval_id)
+    if etag is None:
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID",
+            "Studio answered the approval without an ETag, and the ask must be pinned to the "
+            "exact version it was made against",
+        )
+    grant = selected.request_grant(
+        approval_id,
+        body=grant_request_body(
+            workspace_id=selected.session.workspace_id,
+            decision=getattr(args, "decision", None) or "approved",
+            expected_request_version=record.get("version"),
+            subject_digest=record.get("subject_digest"),
+            reason=getattr(args, "reason", None),
+        ),
+        if_match=etag,
+    )
+    action = _human_action(grant)
+    payload: dict[str, Any] = {
+        "schema_version": APPROVE_SCHEMA,
+        "status": "approval_requested",
+        "lane": "hosted",
+        "approval_request_id": approval_id,
+        "workspace_id": str(selected.session.workspace_id),
+        "asked_for": grant.get("decision"),
+        "requested_by_principal_id": grant.get("requested_by_principal_id"),
+        "requested_by_kind": grant.get("requested_by_kind"),
+        "approval_grant_request_id": grant.get("approval_grant_request_id"),
+        "human_action": action,
+        "never_decides": NEVER_DECIDES,
+        "request": _request_receipt(record),
+        "flags_without_effect": _no_effect(args, _APPROVAL_NO_EFFECT),
+    }
+    if getattr(args, "json", False) is False:
+        # Printed before the wait rather than after it. The whole point of `human_action` is that
+        # somebody has to go and do something, and a line that arrives when the waiting is over is
+        # a line that arrived too late to be the reason it ended.
+        print(f"{action['what_to_do']}:", flush=True)
+        print(action["url"], flush=True)
+    settled = _wait_for_decision(
+        selected,
+        approval_id,
+        poll_seconds=_poll_seconds(grant),
+        wait_seconds=_wait_seconds(args),
+        sleep=sleep,
+        clock=clock,
+    )
+    if settled is None:
+        payload["settled"] = False
+        payload["note"] = (
+            "Still waiting on a person. Nothing was decided, and running this command again "
+            "records the same ask rather than a second one."
+        )
+        return payload
+    payload["status"] = "approval_settled"
+    payload["settled"] = True
+    payload["request"] = _request_receipt(settled)
+    payload["approval_status"] = settled.get("status")
+    payload["decision"] = _decision_receipt(selected.get_decision(approval_id))
+    return payload
+
+
+def recipe_approve(
+    args: argparse.Namespace,
+    *,
+    client: StudioApprovalClient | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+    clock: Callable[[], float] = time.monotonic,
+) -> dict[str, Any]:
+    """``mr-data recipe-approve``: the same act, about one Table recipe.
+
+    The two names stay distinct here for the reason they are distinct locally -- one binds an
+    approval to an exact recipe fingerprint, the other is the general approval -- and the hosted
+    route is the same one, because Studio's approval request already carries which kind of subject
+    it is about. What differs is the human path Studio names in the answer, and this command says
+    so when the approval it was pointed at is not about a recipe at all.
+    """
+
+    payload = approve(args, client=client, sleep=sleep, clock=clock)
+    subject = payload.get("request", {}).get("subject_kind")
+    if subject is None or subject == "table_recipe":
+        if subject == "table_recipe" and approve_exit_code(payload) == 0:
+            payload["build"] = _what_follows_an_approved_recipe(client or _client(args), payload)
+        return payload
+    # ⚠ APPENDED, NEVER ASSIGNED. `approve` writes its own note when nobody has settled the
+    # approval yet, and that note is the one thing a caller acts on; overwriting it to say
+    # something about the subject kind would answer a question nobody asked with the answer to
+    # the one they did.
+    said = (
+        f"This approval is about a {subject}, not a Table recipe. The ask was recorded and the "
+        "human path above is the right one for it; mr-data approve is its name."
+    )
+    existing = payload.get("note")
+    payload["note"] = f"{existing} {said}" if isinstance(existing, str) and existing else said
+    return payload
+
+
+def _what_follows_an_approved_recipe(
+    client: StudioApprovalClient, payload: Mapping[str, Any]
+) -> dict[str, Any]:
+    """Whether the approval already started the Build, or the build command that will.
+
+    Since Studio #124 a person confirming a Table recipe in the dashboard can start its first
+    hosted Build in the same transaction. Once a decision is approved, the question a caller acts
+    on is therefore "is there a run already, or do I queue one" -- and ``POST /v3/runs`` refuses
+    the first case rather than replaying it, so the answer has to be read from the approval's own
+    start projection: a run means nothing is left to queue; its absence means ``mr-data build``
+    with the coordinates the approval carries.
+    """
+
+    request = payload.get("request", {})
+    approval_id = str(payload.get("approval_request_id"))
+    started = client.approval_start(approval_id)
+    if started is not None:
+        run = started.get("run") if isinstance(started.get("run"), Mapping) else {}
+        run_id = run.get("run_id")
+        if not isinstance(run_id, str):
+            raise ThinLaneError(
+                "THIN_RESPONSE_INVALID", "Studio named a started Build without a run"
+            )
+        return {
+            "state": "run_already_queued",
+            "run_id": run_id,
+            "dashboard_url": run_dashboard_url(client.session.cloud_url, run_id),
+            "watch_command": f"mr-data watch {run_id} --hosted",
+            "note": (
+                "The confirmation started the first hosted Build in the same act; there is "
+                "nothing to queue. Follow this run."
+            ),
+        }
+    proposal_id = request.get("recipe_proposal_id")
+    digest = request.get("subject_digest")
+    return {
+        "state": "build_not_started",
+        "build_command": (
+            f"mr-data build --recipe-proposal {proposal_id} --recipe-digest {digest} --hosted"
+        ),
+        "note": (
+            "The recipe is approved and no Build has been started for it; queue the first hosted "
+            "Build with the command above. It replays to the same run if one is started meanwhile."
+        ),
+    }
+
+
+def _wait_seconds(args: argparse.Namespace) -> int:
+    declared = getattr(args, "wait_seconds", None)
+    if declared is None:
+        return DEFAULT_WAIT_SECONDS
+    if type(declared) is not int or not 0 <= declared <= MAX_WAIT_SECONDS:
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            f"--wait-seconds is from 0 to {MAX_WAIT_SECONDS}; 0 records the ask and returns",
+        )
+    return declared
+
+
+def _wait_for_decision(
+    client: StudioApprovalClient,
+    approval_id: str,
+    *,
+    poll_seconds: int,
+    wait_seconds: int,
+    sleep: Callable[[float], None],
+    clock: Callable[[], float],
+) -> dict[str, Any] | None:
+    """Poll until the approval is no longer pending, or until the caller's patience runs out.
+
+    ``None`` when it is still pending at the deadline, which is an answer and not a failure: the
+    ask was recorded, and a person has simply not got to it yet. The cadence is Studio's own
+    ``poll_after_seconds`` rather than a number chosen here, so a backend under load can slow every
+    client down by saying so once.
+    """
+
+    deadline = clock() + wait_seconds
+    while True:
+        record, _etag = client.get_approval(approval_id)
+        status = record.get("status")
+        if status != "pending":
+            return record
+        remaining = deadline - clock()
+        if remaining <= 0:
+            return None
+        sleep(min(float(poll_seconds), remaining))
+
+
+def approve_exit_code(payload: Mapping[str, Any]) -> int:
+    """``2`` unless a human recorded the decision that was asked for.
+
+    Three different outcomes exit 2 here -- rejected, expired or cancelled, and still pending --
+    and that is deliberate: a script gating on an approval must not read any of them as a yes, and
+    the payload is where the difference between them is stated.
+    """
+
+    if payload.get("settled") is not True:
+        return 2
+    decision = payload.get("decision")
+    asked = payload.get("asked_for")
+    if not isinstance(decision, Mapping) or decision.get("decision") != asked:
+        return 2
+    return 0
+
+
+__all__ = [
+    "APPROVAL_DECISION_PATH",
+    "APPROVAL_STATUSES",
+    "APPROVE_PATH",
+    "APPROVE_SCHEMA",
+    "DECIDE_PATH",
+    "DECISIONS",
+    "DEFAULT_POLL_SECONDS",
+    "DEFAULT_WAIT_SECONDS",
+    "GET_APPROVAL_PATH",
+    "HUMAN_ACTION_SENTENCE",
+    "MAX_POLL_SECONDS",
+    "MAX_WAIT_SECONDS",
+    "NEVER_DECIDES",
+    "StudioApprovalClient",
+    "approve",
+    "approve_exit_code",
+    "grant_request_body",
+    "recipe_approve",
+]