blobhub-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{blobhub_cli-0.2.0 → blobhub_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: blobhub-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: BlobHub command line interface — work with blobs, revisions, and their contents from the terminal
 Project-URL: Homepage, https://blobhub.io/
 Project-URL: Documentation, https://docs.blobhub.io/

{blobhub_cli-0.2.0 → blobhub_cli-0.3.0}/src/blobhub_cli/__init__.py

@@ -5,4 +5,4 @@ Contract: this module is the sole source of the package version — hatchling re
 Invariant: no other file in this package defines `__version__`.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{blobhub_cli-0.2.0 → blobhub_cli-0.3.0}/src/blobhub_cli/api/client.py

@@ -3,11 +3,10 @@
 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.
+Neither `query`, `command`, nor `raw_query` names which component serves a data-channel call --
+the target revision's blob type decides that server-side, so there is nothing for a caller to
+supply here at all, even for a scheduler `deploy` that legitimately writes schedules against one
+blob and validates its targets against another.
 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
@@ -28,9 +27,6 @@ from blobhub_cli.api.errors import (
     ApiTransientError,
 )
 
-WORKFLOW_ENGINE = "workflow_blobhub"
-SCHEDULER_ENGINE = "scheduler_blobhub"
-
 _TRANSIENT = (ApiRateLimited, ApiTransientError, ApiNetworkError)
 _ATTEMPTS = 3
 _BASE_DELAY = 0.5
@@ -78,20 +74,20 @@ class Client:
             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 query(self, revision_id: str, command: str, **args: object) -> dict:
+        return self._data_request(revision_id, "query", command, 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 command(self, revision_id: str, command: str, **args: object) -> dict:
+        return self._data_request(revision_id, "command", command, 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 raw_query(self, revision_id: str, command: str, **args: object) -> dict:
+        return self._data_request(revision_id, "query", command, gate_status=False, **args)
 
     def _data_request(
-        self, revision_id: str, channel: str, command: str, *, engine: str, gate_status: bool, **args: object
+        self, revision_id: str, channel: str, command: str, *, gate_status: bool, **args: object
     ) -> dict:
         path = f"/revisions/{revision_id}/data/{channel}"
-        body = {"engine": engine, "command": command, **args}
+        body = {"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:

{blobhub_cli-0.2.0 → blobhub_cli-0.3.0}/src/blobhub_cli/api/commands.py

@@ -1,4 +1,4 @@
-"""Typed wrappers over `Client`, one method per platform read or engine command.
+"""Typed wrappers over `Client`, one method per platform read or data-channel 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.
@@ -7,7 +7,7 @@ Invariant: `create_definition` includes `layout` in the request body only when i
 400 for a workflow-category definition, which never has a `layout` field.
 """
 
-from blobhub_cli.api.client import SCHEDULER_ENGINE, WORKFLOW_ENGINE, Client
+from blobhub_cli.api.client import Client
 
 
 class Api:
@@ -33,34 +33,26 @@ class Api:
         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"]
+        return self._client.query(revision_id, "list_definitions", 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
-        )
+        body = self._client.query(revision_id, "download_definition", 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"]
+        return self._client.command(revision_id, "create_definition", **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
-        )
+        self._client.command(revision_id, "upload_definition", 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)
+        self._client.command(revision_id, "delete_definition", 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
-        )
+        body = self._client.raw_query(revision_id, "check_definition", 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:
@@ -69,12 +61,12 @@ class Api:
             args["alias"] = alias
         if description is not None:
             args["description"] = description
-        return self._client.command(revision_id, "create_session", engine=WORKFLOW_ENGINE, **args)["session"]
+        return self._client.command(revision_id, "create_session", **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"]
+        return self._client.query(revision_id, "get_session", 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
@@ -84,13 +76,11 @@ class Api:
         # 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
+            revision_id, "create_execution", 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"
-        ]
+        return self._client.query(revision_id, "get_execution", execution_id=execution_id)["execution"]
 
     def list_execution_events(
         self,
@@ -101,16 +91,14 @@ class Api:
         ascending: bool = True,
         limit: int | None = None,
     ) -> list[dict]:
-        # Keys are omitted rather than sent as null: every engine schema is
+        # Keys are omitted rather than sent as null: every command 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"
-        ]
+        return self._client.query(revision_id, "list_execution_events", **args)["execution_events"]
 
     def list_executions(
         self, revision_id: str, session_id: str, *, start_execution_id: str | None = None
@@ -122,24 +110,20 @@ class Api:
         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)
+        body = self._client.query(revision_id, "list_executions", **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"]
+        return self._client.command(revision_id, "create_schedule", **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"]
+        return self._client.command(revision_id, "update_schedule", 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)
+        self._client.command(revision_id, "delete_schedule", 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"
-        ]
+        return self._client.query(revision_id, "get_schedule", schedule_id=schedule)["schedule"]
 
     def list_schedules(
         self, revision_id: str, *, start_schedule_id: str | None = None
@@ -153,5 +137,5 @@ class Api:
         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)
+        body = self._client.query(revision_id, "list_schedules", **args)
         return body["schedules"], body["last_schedule_id"]

{blobhub_cli-0.2.0 → blobhub_cli-0.3.0}/src/blobhub_cli/commands/blob.py

@@ -2,7 +2,7 @@
 
 Contract: each command takes a positional `<org/blob>`, resolves it through `blob.reference`, and
 returns the exact dict `--json` emits; the Typer wrappers only parse arguments.
-Invariant: none of these applies `manifest.resolver`'s workflow-shape or revision-phase gates.
+Invariant: none of these applies `manifest.resolver`'s blob-type or revision-phase gates.
 Those are right for a command about to drive a workflow blob and wrong for an inspector -- a blob
 in an unusable phase is precisely what someone runs `blob show` to diagnose.
 """
@@ -45,8 +45,8 @@ def _render_show(payload: dict) -> None:
     record = payload["record"]
     print(f"{'Blob:':<12} {payload['blob']}")
     for label, key in (
-        ("Alias", "alias"), ("Id", "id"), ("Org", "org_id"), ("Domain", "domain"),
-        ("Type", "type"), ("Format", "format"), ("Visibility", "visibility"), ("Status", "status"),
+        ("Alias", "alias"), ("Id", "id"), ("Org", "org_id"), ("Type", "type"),
+        ("Visibility", "visibility"), ("Status", "status"),
     ):
         print(f"{label + ':':<12} {record.get(key, '')}")
     revision_id = record.get("latest_revision_id")

{blobhub_cli-0.2.0 → blobhub_cli-0.3.0}/src/blobhub_cli/commands/scheduler.py

@@ -385,7 +385,7 @@ def _invocation_target(resolved: references.ResolvedTarget) -> dict:
 
 
 def _schedule_fields(entry: scheduler.ScheduleEntry, resolved: references.ResolvedTarget) -> dict:
-    # Keys omitted rather than sent as null: every engine schema is additionalProperties: false
+    # Keys omitted rather than sent as null: every command schema is additionalProperties: false
     # (api/commands.py), so an explicit start_date/end_date: null would be a 400, not an ignored field.
     # invocation_target_type is a TOP-LEVEL sibling of invocation_target in CREATE_SCHEDULE_SCHEMA /
     # UPDATE_SCHEDULE_SCHEMA (spec §1.2) and required on create -- omitting it 400s every real

blobhub_cli-0.3.0/src/blobhub_cli/ids.py

@@ -0,0 +1,42 @@
+"""Identifier-shape checks shared across domains.
+
+Contract: `looks_like_uuid` is the one syntax check for whether a string is shaped like a UUID,
+factored out here so no single domain module (blob references, sessions, and schedules) owns a
+check every domain needs.
+Invariant: this is a shape check, not an existence check -- a well-formed UUID may still resolve to
+nothing, and callers must still handle a not-found/not-accessible response after this returns True.
+
+There are two predicates here, not one, because they answer different questions. `looks_like_uuid`
+is read-side and permissive on purpose: it delegates to `uuid.UUID`, which also accepts a dashless
+32-hex string, a `{braced}` form, and a `urn:uuid:` form, and every one of the CLI's existing
+"is this an id or an alias" branches wants exactly that leniency -- a caller handing back any spelling
+a UUID can take should be treated as meaning an id. `is_canonical_uuid` is write-side and narrow: it
+is the CLI's local mirror of the platform's own shape-exclusion for a user-supplied alias (a create or
+a rename), which refuses only the *canonical* 8-4-4-4-12 form, because that is the one shape the
+platform's own id generator emits and the one shape an alias could collide with unrecoverably. A
+dashless 32-hex string is `looks_like_uuid`-true but `is_canonical_uuid`-false, and is an entirely
+ordinary alias as far as the platform is concerned -- `is_canonical_uuid` must never be used in place
+of `looks_like_uuid`, or it would reject aliases the platform accepts, and `looks_like_uuid` must
+never be used to gate alias creation, or it would reject aliases the platform accepts for a different
+reason (dashless 32-hex parses as a UUID but is not the canonical shape the platform refuses).
+"""
+
+import re
+import uuid
+
+# The platform's own shape-exclusion for a user-supplied alias (create/rename): canonical
+# 8-4-4-4-12 lowercase hex only. Narrower than `looks_like_uuid` on purpose -- see the module
+# docstring for why a dashless 32-hex string must stay outside this pattern.
+_CANONICAL_UUID = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
+
+
+def looks_like_uuid(value: str) -> bool:
+    try:
+        uuid.UUID(value)
+    except ValueError:
+        return False
+    return True
+
+
+def is_canonical_uuid(value: str) -> bool:
+    return bool(_CANONICAL_UUID.match(value))

{blobhub_cli-0.2.0 → blobhub_cli-0.3.0}/src/blobhub_cli/manifest/resolver.py

@@ -1,11 +1,11 @@
 """General reference resolver: turns a parsed `ManifestBase` into concrete platform coordinates.
 
-Contract: `resolve` checks blob accessibility, the caller-supplied `expect` domain/type/format
-shape (before any engine call, which would otherwise answer an opaque `500`), `latest`
-resolution through `blob.latest_revision_id`, then the status/phase gate, in that fixed order.
-`expect` is a required keyword-only argument -- this module resolves `blob`/`revision`
-coordinates for any blob domain, and a default of the workflow shape would leave that one
-domain's assumption sitting inside a resolver that calls itself general.
+Contract: `resolve` checks blob accessibility, the caller-supplied `expect` blob type (before any
+data-channel call, which would otherwise answer an opaque `500`), `latest` resolution through
+`blob.latest_revision_id`, then the status/phase gate, in that fixed order. `expect` is a required
+keyword-only argument -- this module resolves `blob`/`revision` coordinates for any blob type, and
+a default of the workflow type would leave that one type's assumption sitting inside a resolver
+that calls itself general.
 Invariant: resolves only `blob`/`revision`, with no dependency on any manifest body shape, so a
 later `session`/`workflow` reference-kind extension adds to it rather than rewriting it.
 """
@@ -23,8 +23,8 @@ from blobhub_cli.manifest.base import ManifestBase
 WRITABLE_PHASES = {"draft", "managed"}
 QUERYABLE_PHASES = {"draft", "commit", "managed"}
 READY_STATUS = "ready"
-WORKFLOW_BLOB = {"domain": "workflow", "type": "generic", "format": "blobhub"}
-SCHEDULER_BLOB = {"domain": "scheduler", "type": "generic", "format": "blobhub"}
+WORKFLOW_BLOB = "blobhub.compute.workflow"
+SCHEDULER_BLOB = "blobhub.compute.scheduler"
 
 
 @dataclass(frozen=True)
@@ -37,18 +37,19 @@ class Target:
     latest_revision_id: str
 
 
-def command_group(expect: dict) -> str:
-    """The CLI command group that manages blobs of the expected shape -- `workflow` for a workflow
+def command_group(expect: str) -> str:
+    """The CLI command group that manages blobs of the expected type -- `workflow` for a workflow
     blob, `scheduler` for a scheduler one. Derived from `expect` rather than taken as a second
     argument so the two can never disagree: a hint is contractually a command the user can paste
     (`exit.py`), and `blobhub workflow diff -f <scheduler manifest>` answers MANIFEST_TYPE_MISMATCH.
-    The blob's `domain` *is* the group name in this CLI, by construction of both command trees.
+    The type string's last dotted segment *is* the group name in this CLI
+    (`"blobhub.compute.workflow"` -> `"workflow"`), by construction of both command trees.
     """
-    return expect["domain"]
+    return expect.rsplit(".", 1)[-1]
 
 
 def resolve(
-    api: Api, base: ManifestBase, *, require_writable: bool, expect: dict, default_org: str | None = None
+    api: Api, base: ManifestBase, *, require_writable: bool, expect: str, default_org: str | None = None
 ) -> Target:
     group = command_group(expect)
     org = base.org() or default_org
@@ -69,14 +70,14 @@ def resolve(
     except ApiAuthError as exc:
         raise reference.not_accessible(BlobRef(org=org, name=blob_name)) from exc
 
-    shape = {"domain": blob.get("domain"), "type": blob.get("type"), "format": blob.get("format")}
-    if shape != expect:
+    blob_type = blob.get("type")
+    if blob_type != expect:
         # BLOB_NOT_WORKFLOW is kept as the code name even though this check now serves any
-        # domain: renaming a published error code to gain one word would break `--json`
-        # consumers for no behavioural gain. The message names the expected shape instead.
+        # type: renaming a published error code to gain one word would break `--json`
+        # consumers for no behavioural gain. The message names the expected type instead.
         raise CliExit(
             codes.BLOB_NOT_WORKFLOW,
-            f"blob {org}/{blob_name} is {shape}, not a {expect} blob",
+            f"blob {org}/{blob_name} is {blob_type!r}, not a {expect!r} blob",
         )
 
     revision_id = base.revision

{blobhub_cli-0.2.0 → blobhub_cli-0.3.0}/src/blobhub_cli/manifest/scheduler.py

@@ -17,7 +17,7 @@ import re
 from dataclasses import dataclass
 from pathlib import Path
 
-from blobhub_cli import codes
+from blobhub_cli import codes, ids
 from blobhub_cli.exit import CliExit
 from blobhub_cli.formats import io
 from blobhub_cli.manifest import base
@@ -26,11 +26,16 @@ from blobhub_cli.manifest.base import ManifestBase
 MANIFEST_TYPE = "scheduler_blob_deployment"
 SUPPORTED_VERSIONS = {"1.0"}
 
-# `SCHEDULE_ALIAS_SCHEMA` is `DEFINITION_ALIAS_SCHEMA` verbatim (blobhub-infra
-# `api/storage/scheduler.py` -> `workflow.py`): `^[a-z0-9_-]*$`, minLength 6, maxLength 42 -- the
-# same platform handle grammar `manifest/workflow.py` already enforces on a definition alias, spelt
-# the same way here rather than shared, since the two schemas are equal by coincidence of policy and
-# either could move without the other.
+# `SCHEDULE_ALIAS_SCHEMA` is no longer `DEFINITION_ALIAS_SCHEMA` verbatim. It used to be exactly that
+# schema (blobhub-infra `api/storage/scheduler.py` -> `workflow.py`), spelt the same way here rather
+# than shared since the two were equal only by coincidence of policy. Infra has since moved a
+# schedule's alias onto the *session* schema instead: the same `^[a-z0-9_-]*$`, minLength 6, maxLength
+# 42 grammar `manifest/workflow.py` still enforces for a definition alias, plus the shape exclusion
+# below -- a schedule is one of the five kinds addressed by id-or-alias through one parameter, and a
+# canonical UUID-shaped alias would be unreachable by its own name and permanently spend that id's
+# uniqueness reservation. A definition alias is not shape-resolved (`create_execution` takes
+# `definition_id` and `alias` as separate fields), which is why `manifest/workflow.py`'s `_ALIAS`
+# stays exactly the grammar it always was.
 _ALIAS = re.compile(r"^[a-z0-9_-]{6,42}$")
 
 _REPEAT_KINDS = {"one_time", "recurring_cron"}
@@ -151,6 +156,19 @@ def _parse_schedule(raw: object, index: int, hint: str) -> ScheduleEntry:
             f"schedule alias {alias!r} must match {_ALIAS.pattern!r}",
             hint,
         )
+    # The grammar above admits a canonical UUID (36 lowercase hex-and-hyphen characters), which is
+    # exactly the shape the platform reserves for a generated id. Such an alias would be unreachable
+    # by its own name and would permanently spend that id's uniqueness reservation -- possibly
+    # resolving a lookup to whichever object really owns it. The platform now refuses this at create
+    # and rename with a 400; this mirrors that refusal locally so a manifest with one entry like this
+    # fails before any earlier entry in the same `deploy` is written and already firing.
+    if ids.is_canonical_uuid(alias):
+        raise CliExit(
+            codes.SCHEDULE_ALIAS_INVALID,
+            f"schedule alias {alias!r} looks like a UUID; a schedule alias must not take the shape "
+            "the platform reserves for a generated id",
+            hint,
+        )
 
     repeat = _require_str(raw, "repeat", hint)
     if repeat not in _REPEAT_KINDS:

blobhub_cli-0.2.0/src/blobhub_cli/ids.py

@@ -1,18 +0,0 @@
-"""Identifier-shape checks shared across domains.
-
-Contract: `looks_like_uuid` is the one syntax check for whether a string is shaped like a UUID,
-factored out here so no single domain module (blob references, sessions, and soon schedules) owns a
-check every domain needs.
-Invariant: this is a shape check, not an existence check -- a well-formed UUID may still resolve to
-nothing, and callers must still handle a not-found/not-accessible response after this returns True.
-"""
-
-import uuid
-
-
-def looks_like_uuid(value: str) -> bool:
-    try:
-        uuid.UUID(value)
-    except ValueError:
-        return False
-    return True