plugsync-cli 0.3.0__tar.gz → 0.5.0__tar.gz

{plugsync_cli-0.3.0 → plugsync_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugsync-cli
-Version: 0.3.0
+Version: 0.5.0
 Summary: Command-line client for plugsync HubSpot connectors -- manage connectors and plugins like code, no repo checkout required
 Author-email: Exelab <hello@plugsync.com>
 License: Proprietary
@@ -75,6 +75,8 @@ override the config file, handy for CI.
 | `plugsync preview <name>` | Preview a publish's effects and its preflight findings |
 | `plugsync log <name>` | Show a connector's published version history |
 | `plugsync rollback <name>` | Restore a published version into the draft |
+| `plugsync connector breakers <name>` | List the connector's flows whose circuit breaker is open |
+| `plugsync connector flow retry <name> <flow>` | Retry one blocked flow now, instead of waiting for its automatic attempt |
 | `plugsync plugin init/push/list/status/logs/metrics/invoke/promote/publish/rollback` | Author and manage plugins (Enterprise tier) |
 
 Run `plugsync --help` or `plugsync <command> --help` for the full option list.

{plugsync_cli-0.3.0 → plugsync_cli-0.5.0}/README.md

@@ -44,6 +44,8 @@ override the config file, handy for CI.
 | `plugsync preview <name>` | Preview a publish's effects and its preflight findings |
 | `plugsync log <name>` | Show a connector's published version history |
 | `plugsync rollback <name>` | Restore a published version into the draft |
+| `plugsync connector breakers <name>` | List the connector's flows whose circuit breaker is open |
+| `plugsync connector flow retry <name> <flow>` | Retry one blocked flow now, instead of waiting for its automatic attempt |
 | `plugsync plugin init/push/list/status/logs/metrics/invoke/promote/publish/rollback` | Author and manage plugins (Enterprise tier) |
 
 Run `plugsync --help` or `plugsync <command> --help` for the full option list.

{plugsync_cli-0.3.0 → plugsync_cli-0.5.0}/plugsync_cli/__init__.py

@@ -1,2 +1,2 @@
 """PluSync CLI — git-like connector management."""
-__version__ = "0.1.0"
+__version__ = "0.5.0"

{plugsync_cli-0.3.0 → plugsync_cli-0.5.0}/plugsync_cli/client.py

@@ -1,5 +1,6 @@
 """HTTP client wrapper for PluSync REST API."""
 import json
+from urllib.parse import quote
 
 import httpx
 
@@ -120,6 +121,30 @@ class PlugSyncClient:
             r.raise_for_status()
             return r.json()
 
+    def retry_flow(self, connector_id: str, flow_name: str) -> dict:
+        """Retry one flow whose circuit breaker is open, returning the
+        refreshed connector.
+
+        The API moves the breaker to `half_open`, which makes the next message
+        through that flow the recovery probe: it is not a close, and a failed
+        probe re-opens the breaker with a longer cooldown. Idempotent when the
+        breaker is already half-open; 404 when the flow has no open breaker at
+        all, which the command translates into "nothing to retry".
+
+        The flow name is a config value, not a URL-safe token, so it is quoted
+        with no safe characters: a flow called `orders/eu` has to reach the API
+        as one path segment rather than two.
+        """
+        with self._client() as c:
+            r = c.post(
+                self._url(
+                    f"/connectors/{connector_id}/flows/"
+                    f"{quote(flow_name, safe='')}/retry"
+                )
+            )
+            r.raise_for_status()
+            return r.json()
+
     def get_draft(self, connector_id: str) -> dict:
         """The connector's editable config (backend DraftResponse).
 
@@ -154,6 +179,19 @@ class PlugSyncClient:
             r.raise_for_status()
             return r.json()
 
+    def config_surface(self) -> dict:
+        """The config catalogue: actions, transforms, when, sources, json_schema.
+
+        `json_schema` is `ConnectorConfigV3.model_json_schema()`, defaults
+        included: it is how `plugsync diff` knows which values the server wrote
+        from a schema default rather than the operator (#1259). Org-scoped
+        auth only -- the catalogue itself is the same for every org.
+        """
+        with self._client() as c:
+            r = c.get(self._url("/config-surface"))
+            r.raise_for_status()
+            return r.json()
+
     def get_version(self, connector_id: str, version: int) -> dict:
         """One published config version, config included (backend VersionResponse)."""
         with self._client() as c:
@@ -175,11 +213,19 @@ class PlugSyncClient:
             r.raise_for_status()
             return r.json()
 
-    def publish(self, connector_id: str, change_summary: str | None = None) -> dict:
+    def publish(
+        self, connector_id: str, change_summary: str | None = None, force: bool = False,
+    ) -> dict:
+        """`force` (#1367, DX-61): publish a new version even when the draft
+        is identical to the active one - the values a publish resolves (plugin
+        ARN/version, HubSpot schema) can drift without any draft edit. Unrelated
+        to `plugsync push --force`, which discards a concurrent DRAFT edit."""
         with self._client() as c:
             body = {}
             if change_summary:
                 body["change_summary"] = change_summary
+            if force:
+                body["force"] = True
             r = c.post(self._url(f"/connectors/{connector_id}/publish"), json=body)
             r.raise_for_status()
             return r.json()
@@ -255,12 +301,38 @@ class PlugSyncClient:
             r.raise_for_status()
             return r.json()
 
-    def plugin_invoke(self, plugin_id: str, payload: dict) -> dict:
-        """Proxy an invocation to the plugin's Lambda function."""
+    def plugin_invoke(
+        self,
+        plugin_id: str,
+        payload: dict,
+        config: dict | None = None,
+        auth_credential: str | None = None,
+        auth_key: str | None = None,
+    ) -> dict:
+        """Proxy an invocation to the plugin's Lambda function.
+
+        `payload` is the event BODY only -- it lands at `event.payload` on
+        the Lambda side, not the whole PluginPayload envelope (issue #1365).
+        `config` mirrors `event.config`.
+
+        `auth_credential` is a name, never a secret in the clear: the server
+        reads it as an event source name and resolves that source's outbound
+        auth exactly as a real flow does (its credential, auth_type and
+        auth_header), falling back to a stored credential name when the org
+        has no source called that. The event.auth KEY those headers land
+        under is `auth_key` when given, else `auth_credential` itself; that
+        key is also the `auth` capability grant the server requires on the
+        plugin, mirroring what the runtime hands a plugin.
+        """
         with self._client() as c:
             r = c.post(
                 self._url(f"/plugins/{plugin_id}/invoke"),
-                json={"payload": payload},
+                json={
+                    "payload": payload,
+                    "config": config or {},
+                    "auth_credential": auth_credential,
+                    "auth_key": auth_key,
+                },
             )
             r.raise_for_status()
             return r.json()

plugsync_cli-0.5.0/plugsync_cli/commands/connector.py

@@ -0,0 +1,253 @@
+"""plugsync connector -- read a connector's flow circuit breakers, retry one.
+
+Self-service only, with the same org-scoped auth as every other command: the
+owner of a connector lists the flows whose circuit breaker is open and retries
+one of them, from a script or from CI, without opening the dashboard. The
+platform-side force-close is a different operation with a different
+authentication contract (it refuses an org API key) and deliberately has no
+command here.
+"""
+import uuid
+from datetime import datetime, timezone
+
+import click
+import httpx
+from rich.console import Console
+from rich.table import Table
+
+from plugsync_cli.client import PlugSyncClient
+from plugsync_cli.context import build_client, fail
+
+console = Console()
+
+_CONNECTOR_NOT_FOUND = (
+    "Connector '{label}' not found, or it does not belong to this organization."
+)
+
+
+def _looks_like_a_connector_id(reference: str) -> bool:
+    try:
+        uuid.UUID(reference)
+    except ValueError:
+        return False
+    return True
+
+
+def _resolve_connector(client: PlugSyncClient, reference: str) -> tuple[str, str]:
+    """A connector reference (name or id) as `(connector_id, label)`.
+
+    A UUID is taken as the id and used as-is: resolving it through the
+    connector listing would cost a round trip to learn a name the endpoints
+    already return in their own response.
+    """
+    if _looks_like_a_connector_id(reference):
+        return reference, reference
+    connector = client.find_connector(reference)
+    if not connector:
+        fail(f"Connector '{reference}' not found")
+    return connector["id"], connector.get("name") or reference
+
+
+def _detail(exc: httpx.HTTPStatusError) -> str:
+    """The API's `detail` string, or "" when the body carries none."""
+    try:
+        payload = exc.response.json()
+    except ValueError:
+        return ""
+    detail = payload.get("detail") if isinstance(payload, dict) else None
+    return detail if isinstance(detail, str) else ""
+
+
+def _open_breakers(connector: dict) -> list[dict]:
+    """The connector's non-closed flow breakers, one shape for two payloads.
+
+    `health.flows` is the richer form and the one to read. An API that predates
+    it answers only the legacy list, which carries the same flows under other
+    key names: normalizing it here keeps such a backend from reading as a
+    connector with nothing blocked.
+    """
+    flows = (connector.get("health") or {}).get("flows")
+    if flows:
+        return flows
+    return [
+        {
+            "name": flow.get("flow_name"),
+            "state": flow.get("state"),
+            "detail": flow.get("reason"),
+            "opened_at": flow.get("tripped_at"),
+        }
+        for flow in connector.get("tripped_flows") or []
+    ]
+
+
+def _breaker_for(connector: dict, flow_name: str) -> dict | None:
+    for breaker in _open_breakers(connector):
+        if breaker.get("name") == flow_name:
+            return breaker
+    return None
+
+
+def _reason(breaker: dict) -> str:
+    """The human-readable diagnostic, falling back to the machine code."""
+    return str(breaker.get("detail") or breaker.get("reason") or "")
+
+
+def _relative(value, *, now: datetime | None = None) -> str:
+    """An ISO timestamp as a short relative time, past or future.
+
+    Both directions matter in one table: a breaker opened in the past, and a
+    cooldown that expires in the future. An unparseable value is printed as it
+    arrived rather than dropped.
+    """
+    if not value:
+        return ""
+    try:
+        moment = datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except ValueError:
+        return str(value)
+    if moment.tzinfo is None:
+        moment = moment.replace(tzinfo=timezone.utc)
+
+    delta = (moment - (now or datetime.now(timezone.utc))).total_seconds()
+    seconds = int(abs(delta))
+    if seconds < 60:
+        return "now"
+    if seconds < 3600:
+        magnitude = f"{seconds // 60}m"
+    elif seconds < 86400:
+        magnitude = f"{seconds // 3600}h"
+    else:
+        magnitude = f"{seconds // 86400}d"
+    return f"in {magnitude}" if delta > 0 else f"{magnitude} ago"
+
+
+@click.group()
+def connector():
+    """Inspect a connector's operational state."""
+    pass
+
+
+@connector.group()
+def flow():
+    """Act on one event flow of a connector."""
+    pass
+
+
+@flow.command("retry")
+@click.argument("connector_reference", metavar="CONNECTOR")
+@click.argument("flow_name", metavar="FLOW")
+def flow_retry(connector_reference: str, flow_name: str):
+    """Retry a flow whose circuit breaker is open.
+
+    CONNECTOR is a connector name or id, FLOW the event flow name. The breaker
+    moves to half-open: the next message through the flow is the recovery
+    probe. It is not a force-close, and a failed probe re-opens the breaker
+    with a longer cooldown.
+
+    Examples:
+        plugsync connector flow retry my-connector shop-orders
+    """
+    client = build_client()
+    connector_id, label = _resolve_connector(client, connector_reference)
+
+    try:
+        updated = client.retry_flow(connector_id, flow_name)
+    except httpx.HTTPStatusError as exc:
+        if exc.response.status_code != 404:
+            raise
+        if "connector not found" in _detail(exc).lower():
+            fail(_CONNECTOR_NOT_FOUND.format(label=label))
+        fail(
+            f"Flow '{flow_name}' has no open circuit breaker on '{label}': "
+            f"nothing to retry. Run 'plugsync connector breakers {label}' to "
+            "list the flows that are blocked."
+        )
+
+    name = updated.get("name") or label
+    breaker = _breaker_for(updated, flow_name)
+    if breaker is None:
+        console.print(
+            f"Retry accepted for flow '{flow_name}' on connector '{name}', but "
+            "the flow no longer appears among its open circuit breakers: there "
+            "is no breaker state left to report.",
+            soft_wrap=True,
+        )
+        return
+
+    state = breaker.get("state") or "unknown"
+    console.print(
+        f"[green]Flow '{flow_name}' on connector '{name}': breaker is now "
+        f"{state}.[/green]",
+        soft_wrap=True,
+    )
+    if state == "half_open":
+        console.print(
+            "The next message through this flow is the recovery probe: if it "
+            "succeeds the breaker closes, if it fails the breaker re-opens "
+            "with a longer cooldown.",
+            soft_wrap=True,
+        )
+
+
+@connector.command("breakers")
+@click.argument("connector_reference", metavar="CONNECTOR")
+def connector_breakers(connector_reference: str):
+    """List the flows of a connector whose circuit breaker is open.
+
+    CONNECTOR is a connector name or id. Read-only, and always exits 0 when it
+    could read the connector: a blocked flow is not a command failure.
+
+    Examples:
+        plugsync connector breakers my-connector
+    """
+    client = build_client()
+    connector_id, label = _resolve_connector(client, connector_reference)
+
+    try:
+        data = client.get_connector(connector_id)
+    except httpx.HTTPStatusError as exc:
+        if exc.response.status_code != 404:
+            raise
+        fail(_CONNECTOR_NOT_FOUND.format(label=label))
+
+    name = data.get("name") or label
+    breakers = _open_breakers(data)
+    if not breakers:
+        console.print(f"[green]No open circuit breaker on '{name}'.[/green]")
+        return
+
+    table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+    # `overflow="fold"` on the flow name: rich shrinks the widest column when
+    # the table outgrows the terminal, and the default is an ellipsis. The
+    # name is exactly what the operator has to retype into `flow retry`, so it
+    # wraps rather than being cut. `Reason` comes last for the same reason --
+    # it is the column the wrapping should land on.
+    table.add_column("Flow", overflow="fold")
+    table.add_column("State")
+    table.add_column("Opened")
+    table.add_column("Retry after")
+    table.add_column("Opens", justify="right")
+    table.add_column("Reason", overflow="fold")
+
+    for breaker in breakers:
+        opens = breaker.get("opens")
+        table.add_row(
+            str(breaker.get("name") or ""),
+            str(breaker.get("state") or ""),
+            _relative(breaker.get("opened_at")),
+            _relative(breaker.get("retry_after_at")),
+            "" if opens is None else str(opens),
+            _reason(breaker),
+        )
+
+    console.print(f"\n[bold]Open circuit breakers: {name}[/bold]\n")
+    console.print(table)
+    console.print(
+        f"\nRetry one now with: plugsync connector flow retry {name} <flow>",
+        soft_wrap=True,
+    )
+    console.print(
+        "A flow whose retry window has already passed is probed automatically "
+        "by the next message it receives.\n",
+        soft_wrap=True,
+    )