kctl-api 0.2.0__py3-none-any.whl

kctl_api/commands/workflows.py

@@ -0,0 +1,127 @@
+"""Workflow commands for kctl-api.
+
+Start, check status, and list workflows.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_api.core.callbacks import AppContext
+from kctl_api.core.exceptions import APIError, AuthenticationError
+from kctl_api.core.exceptions import ConnectionError as KctlConnectionError
+
+app = typer.Typer(name="workflows", help="Workflow management — start, status, list.", no_args_is_help=True)
+
+
+# ---------------------------------------------------------------------------
+# start
+# ---------------------------------------------------------------------------
+@app.command()
+def start(
+    ctx: typer.Context,
+    workflow_name: Annotated[str, typer.Argument(help="Workflow name to start.")],
+    data_json: Annotated[str | None, typer.Option("--data", "-d", help="JSON payload for the workflow.")] = None,
+) -> None:
+    """Start a new workflow run via POST /api/v1/workflows/start."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    import json
+
+    payload: dict = {"name": workflow_name}
+    if data_json:
+        try:
+            payload["data"] = json.loads(data_json)
+        except json.JSONDecodeError as e:
+            out.error(f"Invalid JSON: {e}")
+            raise typer.Exit(1) from None
+
+    try:
+        result = actx.client.post("/api/v1/workflows/start", json=payload)
+    except (AuthenticationError, KctlConnectionError, APIError) as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+
+    out.success(f"Workflow started: {workflow_name}")
+    if actx.json_mode:
+        out.raw_json(result)
+
+
+# ---------------------------------------------------------------------------
+# status
+# ---------------------------------------------------------------------------
+@app.command()
+def status(
+    ctx: typer.Context,
+    run_id: Annotated[str, typer.Argument(help="Workflow run ID.")],
+) -> None:
+    """Check workflow run status via GET /api/v1/workflows/{run_id}."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    try:
+        data = actx.client.get(f"/api/v1/workflows/{run_id}")
+    except (AuthenticationError, KctlConnectionError, APIError) as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+
+    if not data:
+        out.error(f"Workflow run not found: {run_id}")
+        raise typer.Exit(1)
+
+    out.detail(
+        title=f"Workflow Run: {run_id}",
+        sections=[
+            ("Details", [(k, str(v)) for k, v in data.items()]),
+        ],
+        data_for_json=data,
+    )
+
+
+# ---------------------------------------------------------------------------
+# list
+# ---------------------------------------------------------------------------
+@app.command(name="list")
+def list_workflows(
+    ctx: typer.Context,
+    page: Annotated[int, typer.Option("--page", "-p", help="Page number.")] = 1,
+    per_page: Annotated[int, typer.Option("--per-page", "-n", help="Items per page.")] = 20,
+) -> None:
+    """List workflow runs via GET /api/v1/workflows."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    try:
+        data = actx.client.get("/api/v1/workflows", params={"page": page, "per_page": per_page})
+    except (AuthenticationError, KctlConnectionError, APIError) as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+
+    items = data if isinstance(data, list) else data.get("items", []) if isinstance(data, dict) else []
+    total = len(items) if isinstance(data, list) else data.get("total", len(items)) if isinstance(data, dict) else 0
+
+    rows: list[list[str]] = []
+    for w in items:
+        rows.append(
+            [
+                str(w.get("id", "")),
+                w.get("name", ""),
+                w.get("status", ""),
+                str(w.get("created_at", "")),
+            ]
+        )
+
+    out.table(
+        title=f"Workflow Runs (page {page}, {total} total)",
+        columns=[
+            ("ID", "bold"),
+            ("Name", ""),
+            ("Status", ""),
+            ("Created", "dim"),
+        ],
+        rows=rows,
+        data_for_json=items,
+    )

kctl_api/commands/ws.py

@@ -0,0 +1,323 @@
+"""WebSocket testing commands for kctl-api.
+
+Connect, send, listen, and load test WebSocket endpoints.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Annotated
+
+import typer
+
+from kctl_api.core.callbacks import AppContext
+
+app = typer.Typer(name="ws", help="WebSocket testing — connect, send, listen, load-test.", no_args_is_help=True)
+
+
+def _build_ws_url(actx: AppContext, endpoint: str) -> str:
+    """Convert HTTP base URL to WebSocket URL."""
+    base = actx.client.base_url.rstrip("/")
+    ws_base = base.replace("https://", "wss://").replace("http://", "ws://")
+    if not endpoint.startswith("/"):
+        endpoint = f"/{endpoint}"
+    return f"{ws_base}{endpoint}"
+
+
+# ---------------------------------------------------------------------------
+# connect
+# ---------------------------------------------------------------------------
+@app.command()
+def connect(
+    ctx: typer.Context,
+    endpoint: Annotated[str, typer.Argument(help="WebSocket endpoint path (e.g. /api/v1/ws/chat).")],
+    token: Annotated[str | None, typer.Option("--token", help="Bearer token for auth.")] = None,
+) -> None:
+    """Open a WebSocket connection and show the handshake."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    ws_url = _build_ws_url(actx, endpoint)
+    out.info(f"Connecting to {ws_url} ...")
+
+    async def _run() -> dict:
+        try:
+            import websockets  # type: ignore[import-untyped]
+        except ImportError:
+            raise RuntimeError("websockets not installed. Run: uv add websockets") from None
+
+        headers = {}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        elif actx.client.api_key:
+            headers["Authorization"] = f"Bearer {actx.client.api_key}"
+
+        start = time.monotonic()
+        try:
+            async with websockets.connect(ws_url, additional_headers=headers) as ws:
+                elapsed_ms = round((time.monotonic() - start) * 1000)
+                return {
+                    "url": ws_url,
+                    "connected": True,
+                    "handshake_ms": elapsed_ms,
+                    "subprotocol": ws.subprotocol,
+                    "remote_address": str(ws.remote_address),
+                }
+        except Exception as e:
+            elapsed_ms = round((time.monotonic() - start) * 1000)
+            return {"url": ws_url, "connected": False, "error": str(e), "handshake_ms": elapsed_ms}
+
+    try:
+        result = asyncio.run(_run())
+    except RuntimeError as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+    except Exception as e:
+        out.error(f"Connection failed: {e}")
+        raise typer.Exit(1) from None
+
+    if result.get("connected"):
+        out.success(f"Connected in {result['handshake_ms']}ms")
+        sections = [
+            (
+                "Handshake",
+                [
+                    ("URL", result["url"]),
+                    ("Latency", f"{result['handshake_ms']}ms"),
+                    ("Subprotocol", str(result.get("subprotocol") or "none")),
+                    ("Remote", str(result.get("remote_address", ""))),
+                ],
+            )
+        ]
+        out.detail(title="WebSocket Connection", sections=sections, data_for_json=result)
+    else:
+        out.error(f"Connection failed: {result.get('error')}")
+        if actx.json_mode:
+            out.raw_json(result)
+        raise typer.Exit(1)
+
+
+# ---------------------------------------------------------------------------
+# send
+# ---------------------------------------------------------------------------
+@app.command()
+def send(
+    ctx: typer.Context,
+    endpoint: Annotated[str, typer.Argument(help="WebSocket endpoint path.")],
+    message: Annotated[str, typer.Argument(help="Message to send (string or JSON).")],
+    token: Annotated[str | None, typer.Option("--token", help="Bearer token.")] = None,
+    timeout: Annotated[int, typer.Option("--timeout", help="Wait N seconds for response.")] = 5,
+) -> None:
+    """Send a message over WebSocket and show the response."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    ws_url = _build_ws_url(actx, endpoint)
+    out.info(f"Sending to {ws_url} ...")
+
+    async def _run() -> dict:
+        try:
+            import websockets  # type: ignore[import-untyped]
+        except ImportError:
+            raise RuntimeError("websockets not installed. Run: uv add websockets") from None
+
+        headers = {}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        elif actx.client.api_key:
+            headers["Authorization"] = f"Bearer {actx.client.api_key}"
+
+        async with websockets.connect(ws_url, additional_headers=headers) as ws:
+            await ws.send(message)
+            try:
+                response = await asyncio.wait_for(ws.recv(), timeout=timeout)
+                return {"sent": message, "received": response, "success": True}
+            except TimeoutError:
+                return {"sent": message, "received": None, "success": False, "error": f"No response within {timeout}s"}
+
+    try:
+        result = asyncio.run(_run())
+    except RuntimeError as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+    except Exception as e:
+        out.error(f"WebSocket error: {e}")
+        raise typer.Exit(1) from None
+
+    if result.get("success"):
+        out.success("Message sent and response received.")
+        out.text(f"  Sent:     {result['sent']}")
+        out.text(f"  Received: {result['received']}")
+    else:
+        out.warn(f"Sent message but: {result.get('error', 'no response')}")
+
+    if actx.json_mode:
+        out.raw_json(result)
+
+
+# ---------------------------------------------------------------------------
+# listen
+# ---------------------------------------------------------------------------
+@app.command()
+def listen(
+    ctx: typer.Context,
+    endpoint: Annotated[str, typer.Argument(help="WebSocket endpoint path.")],
+    duration: Annotated[int, typer.Option("--duration", help="Listen for N seconds.")] = 30,
+    token: Annotated[str | None, typer.Option("--token", help="Bearer token.")] = None,
+) -> None:
+    """Listen for incoming WebSocket messages for a duration."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    ws_url = _build_ws_url(actx, endpoint)
+    out.info(f"Listening on {ws_url} for {duration}s (Ctrl+C to stop) ...")
+
+    async def _run() -> list[str]:
+        try:
+            import websockets  # type: ignore[import-untyped]
+        except ImportError:
+            raise RuntimeError("websockets not installed. Run: uv add websockets") from None
+
+        headers = {}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        elif actx.client.api_key:
+            headers["Authorization"] = f"Bearer {actx.client.api_key}"
+
+        messages: list[str] = []
+        deadline = time.monotonic() + duration
+
+        async with websockets.connect(ws_url, additional_headers=headers) as ws:
+            while time.monotonic() < deadline:
+                remaining = deadline - time.monotonic()
+                try:
+                    msg = await asyncio.wait_for(ws.recv(), timeout=min(remaining, 1.0))
+                    messages.append(str(msg))
+                    typer.echo(f"  [{len(messages)}] {msg}")
+                except TimeoutError:
+                    continue
+
+        return messages
+
+    try:
+        messages = asyncio.run(_run())
+    except RuntimeError as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+    except KeyboardInterrupt:
+        out.info("Listening stopped.")
+        return
+    except Exception as e:
+        out.error(f"WebSocket error: {e}")
+        raise typer.Exit(1) from None
+
+    out.success(f"Received {len(messages)} messages in {duration}s.")
+    if actx.json_mode:
+        out.raw_json({"messages": messages, "count": len(messages)})
+
+
+# ---------------------------------------------------------------------------
+# load-test
+# ---------------------------------------------------------------------------
+@app.command(name="load-test")
+def load_test(
+    ctx: typer.Context,
+    endpoint: Annotated[str, typer.Argument(help="WebSocket endpoint path.")],
+    connections: Annotated[int, typer.Option("--connections", help="Number of concurrent connections.")] = 10,
+    duration: Annotated[int, typer.Option("--duration", help="Test duration in seconds.")] = 10,
+    token: Annotated[str | None, typer.Option("--token", help="Bearer token.")] = None,
+) -> None:
+    """Concurrent WebSocket connection load test."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    ws_url = _build_ws_url(actx, endpoint)
+    out.info(f"Load testing {ws_url} — {connections} connections for {duration}s ...")
+
+    async def _single_connection(conn_id: int, results: list[dict]) -> None:
+        try:
+            import websockets  # type: ignore[import-untyped]
+        except ImportError:
+            return
+
+        headers = {}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        elif actx.client.api_key:
+            headers["Authorization"] = f"Bearer {actx.client.api_key}"
+
+        start = time.monotonic()
+        messages_received = 0
+        error: str | None = None
+
+        try:
+            async with websockets.connect(ws_url, additional_headers=headers) as ws:
+                connected_ms = round((time.monotonic() - start) * 1000)
+                deadline = start + duration
+                while time.monotonic() < deadline:
+                    remaining = deadline - time.monotonic()
+                    try:
+                        await asyncio.wait_for(ws.recv(), timeout=min(remaining, 0.5))
+                        messages_received += 1
+                    except TimeoutError:
+                        continue
+        except Exception as e:
+            error = str(e)
+            connected_ms = round((time.monotonic() - start) * 1000)
+
+        results.append(
+            {
+                "connection": conn_id,
+                "connected": error is None,
+                "connect_ms": connected_ms,
+                "messages_received": messages_received,
+                "error": error,
+            }
+        )
+
+    async def _run() -> list[dict]:
+        try:
+            import websockets  # type: ignore[import-untyped]
+
+            _ = websockets
+        except ImportError:
+            raise RuntimeError("websockets not installed. Run: uv add websockets") from None
+
+        results: list[dict] = []
+        tasks = [_single_connection(i + 1, results) for i in range(connections)]
+        await asyncio.gather(*tasks, return_exceptions=True)
+        return results
+
+    try:
+        results = asyncio.run(_run())
+    except RuntimeError as e:
+        out.error(str(e))
+        raise typer.Exit(1) from None
+    except Exception as e:
+        out.error(f"Load test failed: {e}")
+        raise typer.Exit(1) from None
+
+    successful = sum(1 for r in results if r.get("connected"))
+    failed = len(results) - successful
+    avg_connect_ms = round(sum(r.get("connect_ms", 0) for r in results) / max(len(results), 1))
+    total_messages = sum(r.get("messages_received", 0) for r in results)
+
+    out.text("")
+    out.text(f"  Connections:       {connections}")
+    out.text(f"  Successful:        [green]{successful}[/green]")
+    out.text(f"  Failed:            [red]{failed}[/red]")
+    out.text(f"  Avg connect:       {avg_connect_ms}ms")
+    out.text(f"  Total messages:    {total_messages}")
+
+    if actx.json_mode:
+        out.raw_json(
+            {
+                "connections": connections,
+                "successful": successful,
+                "failed": failed,
+                "avg_connect_ms": avg_connect_ms,
+                "total_messages": total_messages,
+                "results": results,
+            }
+        )

kctl_api/core/__init__.py

@@ -0,0 +1 @@
+"""Core infrastructure for kctl-api."""

kctl_api/core/async_client.py

@@ -0,0 +1,120 @@
+"""Async REST API client using httpx.
+
+Mirror of :class:`kctl_api.core.client.ApiClient` with ``async`` methods
+and :class:`httpx.AsyncClient` under the hood.
+
+Subclasses :class:`kctl_lib.async_api_client.AsyncAPIClient` and keeps
+dual-auth (JWT + API key) as a service-specific override.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import httpx
+from kctl_lib.async_api_client import AsyncAPIClient
+from kctl_lib.exceptions import AuthenticationError
+from kctl_lib.exceptions import ConnectionError as KctlConnectionError
+
+from kctl_api.core.exceptions import APIError
+
+
+class AsyncApiClient(AsyncAPIClient):
+    """Asynchronous httpx client for Kodemeio REST APIs.
+
+    Extends the kctl-lib async base with dual-auth support (JWT bearer
+    token **or** API key via ``X-API-Key`` header) and service-specific helpers.
+    """
+
+    AUTH_HEADER: str = "Authorization"
+    AUTH_PREFIX: str = "Bearer"
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str = "",
+        jwt_token: str = "",
+        timeout: float = 30.0,
+    ):
+        # Resolve the primary credential for the base class.
+        credential = jwt_token or api_key or "none"
+
+        # Store extras *before* super().__init__ since _build_auth_header
+        # is called during construction.
+        self._api_key = api_key
+        self._jwt_token = jwt_token
+
+        if not base_url:
+            raise KctlConnectionError(
+                "(not configured)",
+                ValueError("No API URL configured. Run: kctl-api config init"),
+            )
+
+        super().__init__(
+            base_url=base_url,
+            credential=credential,
+            timeout=timeout,
+        )
+
+        # Override with follow_redirects (base class doesn't set it)
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers=self._build_auth_header(),
+            timeout=timeout,
+            follow_redirects=True,
+        )
+
+    # ------------------------------------------------------------------
+    # Auth override — dual-auth (JWT or API key)
+    # ------------------------------------------------------------------
+
+    def _build_auth_header(self) -> dict[str, str]:
+        """Build authentication headers supporting JWT and API key."""
+        if self._jwt_token:
+            return {"Authorization": f"Bearer {self._jwt_token}"}
+        if self._api_key:
+            return {"X-API-Key": self._api_key}
+        return {}
+
+    # ------------------------------------------------------------------
+    # Error mapping override
+    # ------------------------------------------------------------------
+
+    async def _request(self, method: str, endpoint: str, **kwargs: Any) -> httpx.Response:
+        """Override to use kctl-api's APIError (wraps httpx.Response)."""
+        try:
+            return await super()._request(method, endpoint, **kwargs)
+        except KctlConnectionError:
+            raise
+        except AuthenticationError:
+            raise
+        except Exception as exc:
+            from kctl_lib.exceptions import APIError as BaseAPIError
+
+            if isinstance(exc, BaseAPIError):
+                raise APIError(detail=exc.detail) from exc
+            raise
+
+    # ------------------------------------------------------------------
+    # Service-specific methods
+    # ------------------------------------------------------------------
+
+    async def health_check(self) -> tuple[bool, dict]:
+        """Check API health."""
+        try:
+            data = await self.get("/api/v1/health")
+            return data.get("status") == "ok", data
+        except Exception as e:
+            return False, {"status": "error", "error": str(e)}
+
+
+async def async_batch(*coroutines: Any, max_concurrent: int = 10) -> list[Any]:
+    """Run multiple async operations with a concurrency limit."""
+    semaphore = asyncio.Semaphore(max_concurrent)
+
+    async def bounded(coro: Any) -> Any:
+        async with semaphore:
+            return await coro
+
+    return list(await asyncio.gather(*(bounded(c) for c in coroutines)))

kctl_api/core/callbacks.py

@@ -0,0 +1,88 @@
+"""Typer global callback and shared context for kctl-api."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from kctl_lib.callbacks import AppContextBase
+
+from kctl_api.core.config import resolve_connection
+
+if TYPE_CHECKING:
+    from kctl_api.core.client import ApiClient
+
+
+@dataclass
+class AppContext(AppContextBase):
+    """API-specific application context passed through Typer's ctx.obj."""
+
+    url_override: str | None = None
+    ai_url_override: str | None = None
+    api_key_override: str | None = None
+    database_url_override: str | None = None
+    redis_url_override: str | None = None
+    _client: ApiClient | None = field(default=None, repr=False)
+    _ai_client: ApiClient | None = field(default=None, repr=False)
+    _db_engine: Any = field(default=None, repr=False)
+    _redis_client: Any = field(default=None, repr=False)
+
+    def _resolve(self) -> tuple[str, str, str, str, str]:
+        """Resolve connection params once."""
+        return resolve_connection(
+            profile_name=self.profile,
+            url_override=self.url_override,
+            ai_url_override=self.ai_url_override,
+            api_key_override=self.api_key_override,
+            database_url_override=self.database_url_override,
+            redis_url_override=self.redis_url_override,
+        )
+
+    @property
+    def client(self) -> ApiClient:
+        """Lazy API client for api-main."""
+        if self._client is None:
+            from kctl_api.core.client import ApiClient
+
+            url, _ai_url, api_key, _db_url, _redis_url = self._resolve()
+            self._client = ApiClient(
+                base_url=url,
+                api_key=api_key,
+            )
+        return self._client
+
+    @property
+    def ai_client(self) -> ApiClient:
+        """Lazy API client for ai-main."""
+        if self._ai_client is None:
+            from kctl_api.core.client import ApiClient
+
+            _url, ai_url, api_key, _db_url, _redis_url = self._resolve()
+            if not ai_url:
+                from kctl_api.core.exceptions import ConfigError
+
+                raise ConfigError("No ai_url configured. Set it with: kctl-api config set ai_url <url>")
+            self._ai_client = ApiClient(
+                base_url=ai_url,
+                api_key=api_key,
+            )
+        return self._ai_client
+
+    @property
+    def database_url(self) -> str:
+        """Resolved database URL."""
+        _url, _ai_url, _api_key, db_url, _redis_url = self._resolve()
+        return db_url
+
+    @property
+    def redis_url(self) -> str:
+        """Resolved Redis URL."""
+        _url, _ai_url, _api_key, _db_url, redis_url = self._resolve()
+        return redis_url
+
+    def close(self) -> None:
+        """Close the underlying HTTP clients if they were initialised."""
+        if self._client is not None:
+            self._client.close()
+        if self._ai_client is not None:
+            self._ai_client.close()