blobhub-cli 0.1.0__py3-none-any.whl

blobhub_cli/__init__.py

@@ -0,0 +1,8 @@
+"""BlobHub CLI package root.
+
+Contract: this module is the sole source of the package version — hatchling reads
+`__version__` from here via `[tool.hatch.version] path` in pyproject.toml.
+Invariant: no other file in this package defines `__version__`.
+"""
+
+__version__ = "0.1.0"

blobhub_cli/__main__.py

@@ -0,0 +1,11 @@
+"""Process entry point for `python -m blobhub_cli`.
+
+Contract: invoking this module runs the CLI the same way the installed `blobhub`
+console script does.
+Invariant: holds no logic of its own — it only delegates to `cli.app.main`.
+"""
+
+from blobhub_cli.cli.app import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

blobhub_cli/api/__init__.py

@@ -0,0 +1,8 @@
+"""HTTP client and error hierarchy for talking to the BlobHub platform.
+
+Contract: `client.Client` is the only object in this package (and the only one in
+`blobhub_cli`) permitted to perform network I/O; every other module reaches the platform
+through it.
+Invariant: nothing in this package ever logs, echoes, or includes an API key in an
+exception message, output line, or `--json` payload.
+"""

blobhub_cli/api/client.py

@@ -0,0 +1,126 @@
+"""Synchronous HTTP client for the BlobHub API — the only module in this package that performs network I/O.
+
+Contract: `get`, `query`, `command`, and `raw_query` route every response through `_handle`,
+which maps HTTP status and the body's `status` field onto the `api.errors` hierarchy;
+`raw_query` alone skips the status gate, and `probe` skips both the gate and the retry loop.
+`query`/`command`/`raw_query` take a required keyword-only `engine` -- the engine a data request
+targets is the caller's to supply, never this class's to assume, because one command can
+legitimately span both: a scheduler `deploy` writes schedules against `scheduler_blobhub` and
+validates its targets with `workflow_blobhub` calls against the target revision, so a client
+fixed to one engine could not do that.
+Invariant: `Content-Type: application/json` is sent on every request, and the API key is
+never logged, echoed, or included in any exception message. This module is the only one that
+performs I/O against the BlobHub API -- the single sanctioned exception elsewhere is `doctor`'s
+PyPI version probe, which must NOT go through this class precisely because this class attaches
+`X-API-Key` to every request and the key must never reach a third-party host.
+"""
+
+import random
+import time
+
+import httpx
+
+from blobhub_cli.api.errors import (
+    ApiAuthError,
+    ApiCommandError,
+    ApiNetworkError,
+    ApiRateLimited,
+    ApiTransientError,
+)
+
+WORKFLOW_ENGINE = "workflow_blobhub"
+SCHEDULER_ENGINE = "scheduler_blobhub"
+
+_TRANSIENT = (ApiRateLimited, ApiTransientError, ApiNetworkError)
+_ATTEMPTS = 3
+_BASE_DELAY = 0.5
+_MAX_DELAY = 8.0
+
+
+class Client:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        *,
+        transport: httpx.BaseTransport | None = None,
+        timeout: float = 30.0,
+        sleep=time.sleep,
+    ) -> None:
+        self._sleep = sleep
+        self._http = httpx.Client(
+            base_url=base_url,
+            headers={"X-API-Key": api_key, "Content-Type": "application/json"},
+            transport=transport,
+            timeout=timeout,
+        )
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self._http.close()
+
+    def get(self, path: str) -> dict:
+        return self._send("GET", path, gate_status=True)
+
+    def probe(self, path: str = "/users/me") -> tuple[int, float]:
+        """One unretried request, returning (status_code, elapsed_ms) without gating the body.
+
+        `doctor` uses this to prove reachability independently of credentials: every route needs
+        auth, so a 401 is a perfectly good proof that the host answered. Deliberately unretried --
+        a diagnostic wants a fast honest answer, not three backoffs.
+        """
+        start = time.monotonic()
+        try:
+            resp = self._http.request("GET", path)
+        except httpx.TransportError as exc:
+            raise ApiNetworkError(str(exc)) from exc
+        return resp.status_code, (time.monotonic() - start) * 1000
+
+    def query(self, revision_id: str, command: str, *, engine: str, **args: object) -> dict:
+        return self._data_request(revision_id, "query", command, engine=engine, gate_status=True, **args)
+
+    def command(self, revision_id: str, command: str, *, engine: str, **args: object) -> dict:
+        return self._data_request(revision_id, "command", command, engine=engine, gate_status=True, **args)
+
+    def raw_query(self, revision_id: str, command: str, *, engine: str, **args: object) -> dict:
+        return self._data_request(revision_id, "query", command, engine=engine, gate_status=False, **args)
+
+    def _data_request(
+        self, revision_id: str, channel: str, command: str, *, engine: str, gate_status: bool, **args: object
+    ) -> dict:
+        path = f"/revisions/{revision_id}/data/{channel}"
+        body = {"engine": engine, "command": command, **args}
+        return self._send("POST", path, gate_status=gate_status, json=body)
+
+    def _send(self, method: str, path: str, *, gate_status: bool, **kwargs: object) -> dict:
+        last_error: Exception
+        for attempt in range(_ATTEMPTS):
+            try:
+                resp = self._http.request(method, path, **kwargs)
+            except httpx.TransportError as exc:
+                last_error = ApiNetworkError(str(exc))
+            else:
+                try:
+                    return self._handle(resp, gate_status=gate_status)
+                except _TRANSIENT as exc:
+                    last_error = exc
+            if attempt < _ATTEMPTS - 1:
+                self._sleep(random.random() * min(_MAX_DELAY, _BASE_DELAY * 2**attempt))
+        raise last_error
+
+    def _handle(self, resp: httpx.Response, *, gate_status: bool) -> dict:
+        if resp.status_code in (401, 403):
+            raise ApiAuthError(f"auth failed: HTTP {resp.status_code}")
+        if resp.status_code == 429:
+            raise ApiRateLimited("HTTP 429")
+        if resp.status_code >= 500:
+            raise ApiTransientError(f"HTTP {resp.status_code}")
+        try:
+            data = resp.json()
+        except ValueError as exc:
+            raise ApiTransientError(f"non-JSON response: HTTP {resp.status_code}") from exc
+        if gate_status and data.get("status") != "success":
+            raise ApiCommandError(data.get("error", "unknown"), data.get("message", ""))
+        return data

blobhub_cli/api/commands.py

@@ -0,0 +1,157 @@
+"""Typed wrappers over `Client`, one method per platform read or engine command.
+
+Contract: each method sends exactly one request and returns only the envelope key(s) the
+platform documents for that command, adding no caching, retries, or aggregation of its own.
+Invariant: `create_definition` includes `layout` in the request body only when it is not
+`None` — the server's `additionalProperties: false` schema turns an explicit `null` into a
+400 for a workflow-category definition, which never has a `layout` field.
+"""
+
+from blobhub_cli.api.client import SCHEDULER_ENGINE, WORKFLOW_ENGINE, Client
+
+
+class Api:
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def users_me(self) -> dict:
+        return self._client.get("/users/me")["user"]
+
+    def users_me_orgs(self) -> list[dict]:
+        return self._client.get("/users/me/orgs")["organizations"]
+
+    def get_blob(self, org: str, blob: str) -> dict:
+        return self._client.get(f"/blobs/{org}/{blob}")["blob"]
+
+    def get_revision(self, revision_id: str) -> dict:
+        return self._client.get(f"/revisions/{revision_id}")["revision"]
+
+    def list_revisions(self, org: str, blob: str) -> list[dict]:
+        return self._client.get(f"/blobs/{org}/{blob}/revisions")["revisions"]
+
+    def get_blob_limits(self, org: str, blob: str) -> dict:
+        return self._client.get(f"/blobs/{org}/{blob}/limits")["limits"]
+
+    def list_definitions(self, revision_id: str, category: str) -> list[dict]:
+        return self._client.query(
+            revision_id, "list_definitions", engine=WORKFLOW_ENGINE, category=category
+        )["definitions"]
+
+    def download_definition(self, revision_id: str, definition_id: str) -> tuple[dict, dict]:
+        body = self._client.query(
+            revision_id, "download_definition", engine=WORKFLOW_ENGINE, definition_id=definition_id
+        )
+        return body["definition"], body["definition_object"]
+
+    def create_definition(self, revision_id: str, alias: str, category: str, layout: dict | None = None) -> dict:
+        args: dict[str, object] = {"alias": alias, "category": category}
+        if layout is not None:
+            args["layout"] = layout
+        return self._client.command(revision_id, "create_definition", engine=WORKFLOW_ENGINE, **args)["definition"]
+
+    def upload_definition(self, revision_id: str, definition_id: str, document: dict) -> None:
+        self._client.command(
+            revision_id, "upload_definition", engine=WORKFLOW_ENGINE, definition_id=definition_id, definition=document
+        )
+
+    def delete_definition(self, revision_id: str, definition_id: str) -> None:
+        self._client.command(revision_id, "delete_definition", engine=WORKFLOW_ENGINE, definition_id=definition_id)
+
+    def check_definition(self, revision_id: str, definition_id: str) -> tuple[str, list[dict]]:
+        body = self._client.raw_query(
+            revision_id, "check_definition", engine=WORKFLOW_ENGINE, definition_id=definition_id
+        )
+        return body.get("status"), body.get("events", [])
+
+    def create_session(self, revision_id: str, *, alias: str | None = None, description: str | None = None) -> dict:
+        args: dict[str, object] = {}
+        if alias is not None:
+            args["alias"] = alias
+        if description is not None:
+            args["description"] = description
+        return self._client.command(revision_id, "create_session", engine=WORKFLOW_ENGINE, **args)["session"]
+
+    def get_session(self, revision_id: str, session: str) -> dict:
+        # Accepts an id OR an alias -- `get_session_by_session_id_or_alias` server-side. Unlike
+        # `create_execution`, which resolves the id only (spec §1.1).
+        return self._client.query(revision_id, "get_session", engine=WORKFLOW_ENGINE, session_id=session)["session"]
+
+    def create_execution(self, revision_id: str, session_id: str, *, definition_id: str) -> dict:
+        # Addressed by id, not alias: `CREATE_EXECUTION_SCHEMA` accepts either, but the server
+        # resolves `alias` via a `(revision_id, alias)` query with no category filter, taking
+        # whichever definition comes back first. Alias uniqueness is scoped per `(category, alias)`
+        # (F1 spec §1.3), so the same alias can legally name both a workflow and a playground
+        # definition -- an alias-addressed execution could resolve to either, unpredictably. The
+        # caller already has the id from `load_set`, so there is no reason to take that risk.
+        return self._client.command(
+            revision_id, "create_execution", engine=WORKFLOW_ENGINE, session_id=session_id, definition_id=definition_id
+        )["execution"]
+
+    def get_execution(self, revision_id: str, execution_id: str) -> dict:
+        return self._client.query(revision_id, "get_execution", engine=WORKFLOW_ENGINE, execution_id=execution_id)[
+            "execution"
+        ]
+
+    def list_execution_events(
+        self,
+        revision_id: str,
+        execution_id: str,
+        *,
+        created_since: str | None = None,
+        ascending: bool = True,
+        limit: int | None = None,
+    ) -> list[dict]:
+        # Keys are omitted rather than sent as null: every engine schema is
+        # additionalProperties: false, so one stray key is a 400, not an ignored field.
+        args: dict[str, object] = {"execution_id": execution_id, "ascending": ascending}
+        if created_since is not None:
+            args["created_since"] = created_since
+        if limit is not None:
+            args["limit"] = limit
+        return self._client.query(revision_id, "list_execution_events", engine=WORKFLOW_ENGINE, **args)[
+            "execution_events"
+        ]
+
+    def list_executions(
+        self, revision_id: str, session_id: str, *, start_execution_id: str | None = None
+    ) -> tuple[list[dict], str | None]:
+        # start_execution_id is omitted rather than sent as null, same reason list_schedules omits
+        # start_schedule_id: LIST_EXECUTIONS_SCHEMA is additionalProperties: false. One page and the
+        # next cursor -- this method deliberately does not loop; the loop belongs to the caller that
+        # knows why it's paging (deploy's saturation count stops early on purpose).
+        args: dict[str, object] = {"session_id": session_id}
+        if start_execution_id is not None:
+            args["start_execution_id"] = start_execution_id
+        body = self._client.query(revision_id, "list_executions", engine=WORKFLOW_ENGINE, **args)
+        return body["executions"], body["last_execution_id"]
+
+    def create_schedule(self, revision_id: str, **fields: object) -> dict:
+        return self._client.command(revision_id, "create_schedule", engine=SCHEDULER_ENGINE, **fields)["schedule"]
+
+    def update_schedule(self, revision_id: str, schedule: str, **fields: object) -> dict:
+        return self._client.command(
+            revision_id, "update_schedule", engine=SCHEDULER_ENGINE, schedule_id=schedule, **fields
+        )["schedule"]
+
+    def delete_schedule(self, revision_id: str, schedule: str) -> None:
+        self._client.command(revision_id, "delete_schedule", engine=SCHEDULER_ENGINE, schedule_id=schedule)
+
+    def get_schedule(self, revision_id: str, schedule: str) -> dict:
+        return self._client.query(revision_id, "get_schedule", engine=SCHEDULER_ENGINE, schedule_id=schedule)[
+            "schedule"
+        ]
+
+    def list_schedules(
+        self, revision_id: str, *, start_schedule_id: str | None = None
+    ) -> tuple[list[dict], str | None]:
+        # start_schedule_id is omitted rather than sent as null: LIST_SCHEDULES_SCHEMA is
+        # additionalProperties: false, so a stray null key is a 400, not an ignored field. Returns
+        # one page and the next cursor -- it deliberately does not loop. A method that looped would
+        # hide the paging from every test that uses it; the loop belongs one layer up, where a
+        # caller that forgets it would otherwise silently recreate every unseen schedule as a
+        # duplicate on the next run.
+        args: dict[str, object] = {}
+        if start_schedule_id is not None:
+            args["start_schedule_id"] = start_schedule_id
+        body = self._client.query(revision_id, "list_schedules", engine=SCHEDULER_ENGINE, **args)
+        return body["schedules"], body["last_schedule_id"]

blobhub_cli/api/errors.py

@@ -0,0 +1,51 @@
+"""Error hierarchy raised by `client.Client`.
+
+Contract: every failure raised is one of these classes, each carrying a `code` class attribute
+from `blobhub_cli.codes`; `ApiCommandError` additionally carries `.error`, the server's
+machine-readable failure string, kept separate from the human-readable `.message`.
+Invariant: no instance of any of these classes ever carries the API key — the client that
+raises them holds the only copy, and it is never included in a message here.
+"""
+
+from blobhub_cli import codes
+
+
+class ApiError(Exception):
+    """Base class for every error `Client` raises."""
+
+    code = "API_ERROR"
+
+
+class ApiAuthError(ApiError):
+    """The API key was rejected or the resource is forbidden (HTTP 401/403)."""
+
+    code = codes.AUTH_INVALID
+
+
+class ApiRateLimited(ApiError):
+    """The server asked the caller to slow down (HTTP 429). Retried."""
+
+    code = codes.API_RATE_LIMITED
+
+
+class ApiTransientError(ApiError):
+    """A server-side or malformed-response failure (HTTP 5xx, non-JSON body). Retried."""
+
+    code = codes.API_TRANSIENT_ERROR
+
+
+class ApiNetworkError(ApiError):
+    """The request never reached the server (DNS, connection, timeout). Retried."""
+
+    code = codes.API_NETWORK_ERROR
+
+
+class ApiCommandError(ApiError):
+    """A successful HTTP response whose body reports `status` other than `success`."""
+
+    code = codes.API_COMMAND_FAILED
+
+    def __init__(self, error: str, message: str = "") -> None:
+        super().__init__(message or error)
+        self.error = error
+        self.message = message or error

blobhub_cli/blob/__init__.py

@@ -0,0 +1,9 @@
+"""Blob-addressing helpers shared by the `blob` command group and the manifest layer.
+
+Contract: `reference` is the sole implementation of how a blob reference splits into an org and
+a name, so both the manifest layer (via `ManifestBase.org()` / `ManifestBase.blob_name()`) and
+the blob command group (via positional `<org/blob>` argument parsing) can reuse it without
+drifting.
+Invariant: nothing in this package performs network I/O, file system I/O, or external calls —
+all functions are pure textual operations on references.
+"""

blobhub_cli/blob/reference.py

@@ -0,0 +1,87 @@
+"""The one definition of how a blob reference splits into an org and a name.
+
+Contract: `split` performs the textual split and nothing else, so `ManifestBase` can reuse it
+without inheriting `parse`'s org-defaulting or its CliExit behaviour; `parse` adds the default-org
+rule and is what positional `<org/blob>` arguments go through; `not_accessible` builds the one
+BLOB_NOT_ACCESSIBLE both `manifest.resolver` and the `blob` commands raise.
+Invariant: a reference has at most one "/" -- `manifest.base.parse` checks that separately for
+manifests (raising MANIFEST_INVALID, since there it really came from a manifest), and `parse`
+checks it here for positional arguments.
+"""
+
+from dataclasses import dataclass
+
+from blobhub_cli import codes, ids
+from blobhub_cli.exit import CliExit
+
+# What a hint names when the caller does not say which command it is running.
+DEFAULT_COMMAND = "blob show"
+
+
+@dataclass(frozen=True)
+class BlobRef:
+    org: str
+    name: str
+
+    def label(self) -> str:
+        return f"{self.org}/{self.name}"
+
+
+def split(text: str) -> tuple[str | None, str]:
+    segments = text.split("/", 1)
+    return (segments[0], segments[1]) if len(segments) == 2 else (None, text)
+
+
+def not_accessible(ref: BlobRef) -> CliExit:
+    """The one BLOB_NOT_ACCESSIBLE, shared by `manifest.resolver` and the `blob` commands.
+
+    The platform answers the same 403 for a blob that is absent and for one this key cannot see,
+    so the message cannot distinguish them. The UUID clause is the only actionable thing the CLI
+    can add: an org-scoped key must address its org by UUID and gets exactly this 403 against an
+    alias -- which is why it belongs to the message rather than to one of the two raise sites.
+    """
+    message = f"blob {ref.label()} is absent or not accessible with this key"
+    if not ids.looks_like_uuid(ref.org):
+        message += f"; if this API key is org-scoped, it must address the org by UUID, not the alias {ref.org!r}"
+    return CliExit(codes.BLOB_NOT_ACCESSIBLE, message, "blobhub whoami")
+
+
+def parse(text: str, default_org: str | None, *, command: str = DEFAULT_COMMAND) -> BlobRef:
+    # `command` is the sub-command the caller is running ("blob revisions", "blob limits", ...),
+    # threaded in only so that every hint below is a command the user can actually paste. It is no
+    # part of the parsing rule, which is why it is keyword-only and defaulted.
+    usage_hint = f"blobhub {command} <org>/<blob>"
+    if not text:
+        raise CliExit(codes.BLOB_REFERENCE_INVALID, "blob reference is empty", usage_hint)
+    if text.count("/") > 1:
+        raise CliExit(
+            codes.BLOB_REFERENCE_INVALID,
+            f"blob reference {text!r} has more than one '/'",
+            usage_hint,
+        )
+    org, name = split(text)
+    if org == "":
+        # A leading "/" leaves an empty org segment. Rejected explicitly rather than left to fall
+        # through to the default org, which would address a blob the user never named -- and, with
+        # no default org, would produce the nonsense advice to qualify it as '<org>//flow'.
+        raise CliExit(
+            codes.BLOB_REFERENCE_INVALID,
+            f"blob reference {text!r} has an empty org before the '/'",
+            usage_hint,
+        )
+    org = org or default_org
+    if not org:
+        # Every way of supplying the org is named, matching `resolver.resolve`'s wording: a user
+        # hitting this has three options and no way to guess the two that aren't on their command
+        # line.
+        raise CliExit(
+            codes.BLOB_REFERENCE_INVALID,
+            f"blob {text!r} has no org: qualify it as '<org>/{text}', pass --org <org>, or "
+            "set BLOBHUB_ORG",
+            f"blobhub --org <org> {command} {text}",
+        )
+    if not name:
+        raise CliExit(
+            codes.BLOB_REFERENCE_INVALID, f"blob reference {text!r} has no blob name", usage_hint
+        )
+    return BlobRef(org=org, name=name)

blobhub_cli/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI subpackage: the Typer application root and its commands.
+
+Contract: `cli.app` exposes `build_app()` and `main()` as the package's only entry points.
+Invariant: no other module outside this subpackage constructs the Typer app directly.
+"""