vibeinfra-sdk 0.1.0__tar.gz

vibeinfra_sdk-0.1.0/.gitignore

@@ -0,0 +1,102 @@
+# macOS system files
+.DS_Store
+.AppleDouble
+.LSOverride
+Thumbs.db
+
+# Environment variables & secrets
+.env
+.env.local
+.env.production
+*.pem
+*.key
+*.crt
+vps-ssh.txt
+
+# Go build binaries & logs
+/labs-system/backend/labs-api
+/labs-system/cmd/vibelab/vibelab
+backend/backend/bin/
+/bin/
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+go.work
+
+# Node & Cloudflare Wrangler
+node_modules/
+.wrangler/
+dist/
+build/
+out/
+.next/
+_next/
+frontend-mockup/out/
+frontend-mockup/.next/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Docker & Database Data
+pgdata/
+docker-data/
+*.db
+*.sqlite
+benchmark_results/
+
+# Cloudflare Tunnel credentials
+cloudflared/
+
+# Secrets and machine-local tool state.
+#
+# This section previously ignored *.json wholesale with a hand-maintained list of `!` exceptions.
+# That is backwards: every NEW json file in the repo -- course data, a config, a fixture -- was
+# silently untracked until somebody noticed and added another exception. It had already bitten:
+# frontend-mockup/public/labs/incident_blueprints.json was untracked while the root copy of the
+# same file was tracked, so the static-mirror build source was missing its blueprint data.
+# Ignore the specific things that must not be committed instead.
+.mcp.json
+.claude/settings.local.json
+.claude/launch.json
+.agentsroom/*.json
+.agents/mcp_config.json
+.obsidian/
+signature-mapping.json
+
+# Generated Lighthouse audit output (one-off artifacts, not source).
+lighthouse-report*.json
+
+!openspec.yaml
+!.openspec.yaml
+
+# IDE & Editor files
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+dump.rdb
+
+# Python bytecode & cache
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.venv/
+venv/
+
+# External tools & standalone repos
+dockscope/
+public-repos/
+
+.mcp.json
+.agentsroom/handoff-transcript-*.txt
+.agentsroom/handoff-summary-*.md
+.agents/mcp_config.json
+
+# Local research books and PDFs
+books/

vibeinfra_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VibeInfra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vibeinfra_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: vibeinfra-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the VibeInfra API - browse the SRE incident catalog, read live sandbox capacity and track learner progress.
+Project-URL: Homepage, https://vibeinfra.id
+Project-URL: Documentation, https://vibeinfra.id/docs/api/
+Project-URL: Developer Portal, https://vibeinfra.id/developers/
+Project-URL: OpenAPI Description, https://vibeinfra.id/openapi.json
+Project-URL: Source, https://github.com/ridwansswnto/vibeinfraid
+Project-URL: Issues, https://github.com/ridwansswnto/vibeinfraid/issues
+Author-email: VibeInfra <hello@vibeinfra.id>
+License: MIT
+License-File: LICENSE
+Keywords: api-client,devops,incident-response,infrastructure,kubernetes,observability,sdk,sre,vibeinfra
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Education
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# vibeinfra
+
+Official Python client for the [VibeInfra](https://vibeinfra.id) API.
+
+VibeInfra is a learn-by-doing infrastructure engineering platform: engineers troubleshoot
+realistic production incidents — Linux kernel, Docker, Kubernetes, Nginx, PostgreSQL, Kafka,
+AWS — inside live disposable multi-container sandboxes with automated grading.
+
+The entire catalog surface is **unauthenticated**, so reading it needs no credentials.
+
+## Install
+
+```bash
+pip install vibeinfra
+```
+
+Requires Python 3.9+. Standard library only — no transitive dependencies.
+
+## Quick start
+
+```python
+from vibeinfra import VibeInfra
+
+vibe = VibeInfra()
+
+# Every incident and course in the catalog.
+for course in vibe.list_courses():
+    print(course["id"], course["title"])
+
+# One blueprint, including objectives and tech stack.
+incident = vibe.get_course("incident-22-k8s-crashloop")
+
+# Find something to work on.
+kafka = vibe.search_courses(query="kafka", difficulty="Expert")
+
+# Is the platform busy right now?
+print(vibe.get_capacity()["queue_length"])
+```
+
+## Authenticated calls
+
+Learner-scoped endpoints take the session JWT minted by the GitHub/Google OAuth callback:
+
+```python
+import os
+
+vibe = VibeInfra(token=os.environ["VIBEINFRA_TOKEN"])
+vibe.list_completions()
+```
+
+## Constructor arguments
+
+| Argument   | Default                    | Purpose                                       |
+| ---------- | -------------------------- | --------------------------------------------- |
+| `base_url` | `https://api.vibeinfra.id` | Point at a local backend during development.   |
+| `token`    | `None`                     | Session JWT, sent as `Authorization: Bearer`.  |
+| `timeout`  | `15.0`                     | Per-request timeout, in seconds.               |
+| `opener`   | default urllib opener      | Injected transport, for tests and proxies.     |
+
+## Errors
+
+- `VibeInfraApiError` — the server answered with a non-2xx status. Carries `status`, `url`,
+  the decoded `body`, and the `is_unauthorized` / `is_rate_limited` properties.
+- `VibeInfraNetworkError` — the request never reached the server, or the timeout fired. The
+  original failure is on `__cause__`.
+
+Both subclass `VibeInfraError`, so `except VibeInfraError` catches everything this client raises.
+
+## Methods
+
+**Catalog** — `list_courses`, `get_course`, `search_courses`, `get_glossary`, `list_credit_packs`
+**Platform** — `get_health`, `get_capacity`, `get_public_settings`, `get_public_telemetry`, `get_leaderboard`
+**Labs & account** — `start_lab`, `get_session`, `get_profile`, `list_completions`
+
+`search_courses` filters client-side: the API has no search endpoint because the catalog is
+small enough to fetch whole.
+
+## Related
+
+- API reference — <https://vibeinfra.id/docs/api/>
+- OpenAPI description — <https://vibeinfra.id/openapi.json>
+- MCP server (`@vibeinfra/mcp-server`) — <https://vibeinfra.id/docs/mcp/>
+- Developer portal — <https://vibeinfra.id/developers/>
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

vibeinfra_sdk-0.1.0/README.md

@@ -0,0 +1,94 @@
+# vibeinfra
+
+Official Python client for the [VibeInfra](https://vibeinfra.id) API.
+
+VibeInfra is a learn-by-doing infrastructure engineering platform: engineers troubleshoot
+realistic production incidents — Linux kernel, Docker, Kubernetes, Nginx, PostgreSQL, Kafka,
+AWS — inside live disposable multi-container sandboxes with automated grading.
+
+The entire catalog surface is **unauthenticated**, so reading it needs no credentials.
+
+## Install
+
+```bash
+pip install vibeinfra
+```
+
+Requires Python 3.9+. Standard library only — no transitive dependencies.
+
+## Quick start
+
+```python
+from vibeinfra import VibeInfra
+
+vibe = VibeInfra()
+
+# Every incident and course in the catalog.
+for course in vibe.list_courses():
+    print(course["id"], course["title"])
+
+# One blueprint, including objectives and tech stack.
+incident = vibe.get_course("incident-22-k8s-crashloop")
+
+# Find something to work on.
+kafka = vibe.search_courses(query="kafka", difficulty="Expert")
+
+# Is the platform busy right now?
+print(vibe.get_capacity()["queue_length"])
+```
+
+## Authenticated calls
+
+Learner-scoped endpoints take the session JWT minted by the GitHub/Google OAuth callback:
+
+```python
+import os
+
+vibe = VibeInfra(token=os.environ["VIBEINFRA_TOKEN"])
+vibe.list_completions()
+```
+
+## Constructor arguments
+
+| Argument   | Default                    | Purpose                                       |
+| ---------- | -------------------------- | --------------------------------------------- |
+| `base_url` | `https://api.vibeinfra.id` | Point at a local backend during development.   |
+| `token`    | `None`                     | Session JWT, sent as `Authorization: Bearer`.  |
+| `timeout`  | `15.0`                     | Per-request timeout, in seconds.               |
+| `opener`   | default urllib opener      | Injected transport, for tests and proxies.     |
+
+## Errors
+
+- `VibeInfraApiError` — the server answered with a non-2xx status. Carries `status`, `url`,
+  the decoded `body`, and the `is_unauthorized` / `is_rate_limited` properties.
+- `VibeInfraNetworkError` — the request never reached the server, or the timeout fired. The
+  original failure is on `__cause__`.
+
+Both subclass `VibeInfraError`, so `except VibeInfraError` catches everything this client raises.
+
+## Methods
+
+**Catalog** — `list_courses`, `get_course`, `search_courses`, `get_glossary`, `list_credit_packs`
+**Platform** — `get_health`, `get_capacity`, `get_public_settings`, `get_public_telemetry`, `get_leaderboard`
+**Labs & account** — `start_lab`, `get_session`, `get_profile`, `list_completions`
+
+`search_courses` filters client-side: the API has no search endpoint because the catalog is
+small enough to fetch whole.
+
+## Related
+
+- API reference — <https://vibeinfra.id/docs/api/>
+- OpenAPI description — <https://vibeinfra.id/openapi.json>
+- MCP server (`@vibeinfra/mcp-server`) — <https://vibeinfra.id/docs/mcp/>
+- Developer portal — <https://vibeinfra.id/developers/>
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

vibeinfra_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vibeinfra-sdk"
+version = "0.1.0"
+description = "Official Python SDK for the VibeInfra API - browse the SRE incident catalog, read live sandbox capacity and track learner progress."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "VibeInfra", email = "hello@vibeinfra.id" }]
+keywords = [
+  "vibeinfra",
+  "sre",
+  "incident-response",
+  "infrastructure",
+  "devops",
+  "kubernetes",
+  "observability",
+  "api-client",
+  "sdk",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Education",
+  "Topic :: System :: Systems Administration",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://vibeinfra.id"
+Documentation = "https://vibeinfra.id/docs/api/"
+"Developer Portal" = "https://vibeinfra.id/developers/"
+"OpenAPI Description" = "https://vibeinfra.id/openapi.json"
+Source = "https://github.com/ridwansswnto/vibeinfraid"
+Issues = "https://github.com/ridwansswnto/vibeinfraid/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vibeinfra"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/vibeinfra", "README.md", "LICENSE", "tests"]

vibeinfra_sdk-0.1.0/src/vibeinfra/__init__.py

@@ -0,0 +1,41 @@
+"""Official Python client for the VibeInfra API.
+
+VibeInfra is a learn-by-doing infrastructure engineering platform: engineers troubleshoot
+realistic production incidents inside live disposable multi-container sandboxes with automated
+grading.
+
+The whole public surface of ``https://api.vibeinfra.id`` is unauthenticated, so the common
+case -- an agent or a script reading the incident catalog -- needs no credentials::
+
+    from vibeinfra import VibeInfra
+
+    vibe = VibeInfra()
+    for course in vibe.list_courses():
+        print(course["id"], course["title"])
+
+The client uses only the standard library, so it adds no transitive dependencies to whatever
+it is embedded in. The API description it mirrors lives at https://vibeinfra.id/openapi.json.
+"""
+
+from .client import (
+    API_VERSION,
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    VibeInfra,
+    VibeInfraApiError,
+    VibeInfraError,
+    VibeInfraNetworkError,
+)
+
+__all__ = [
+    "API_VERSION",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT",
+    "VibeInfra",
+    "VibeInfraApiError",
+    "VibeInfraError",
+    "VibeInfraNetworkError",
+    "__version__",
+]
+
+__version__ = "0.1.0"

vibeinfra_sdk-0.1.0/src/vibeinfra/client.py

@@ -0,0 +1,259 @@
+"""HTTP client for the VibeInfra API.
+
+Deliberately standard-library only: ``requests`` would be more idiomatic, but this package is
+meant to be dropped into agent runtimes and CI images where every added dependency is another
+thing to pin, audit and resolve. ``urllib`` is enough for a JSON API with no streaming.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Iterable, List, Mapping, Optional
+
+#: Default production origin. Override with ``base_url`` to point at a local backend.
+DEFAULT_BASE_URL = "https://api.vibeinfra.id"
+
+#: API version prefix, so a contract bump does not require editing every method here.
+API_VERSION = "v1"
+
+#: Per-request timeout in seconds.
+DEFAULT_TIMEOUT = 15.0
+
+_USER_AGENT = "vibeinfra-python/0.1.0 (+https://vibeinfra.id/developers/)"
+
+
+class VibeInfraError(Exception):
+    """Base class for every error this client raises."""
+
+
+class VibeInfraApiError(VibeInfraError):
+    """The call reached the server and came back with a non-2xx status.
+
+    ``body`` holds the decoded response when the server sent one, because the API reports
+    failures as ``{"error": "..."}`` and callers should not have to re-read the response to
+    find out why the request was rejected.
+    """
+
+    def __init__(self, status: int, url: str, message: str, body: Any = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.url = url
+        self.body = body
+
+    @property
+    def is_unauthorized(self) -> bool:
+        """True when the caller is not signed in, or the session has expired."""
+        return self.status == 401
+
+    @property
+    def is_rate_limited(self) -> bool:
+        """True when this caller exceeded the endpoint's rate limit."""
+        return self.status == 429
+
+
+class VibeInfraNetworkError(VibeInfraError):
+    """The request never reached the server, or the timeout fired."""
+
+    def __init__(self, url: str, cause: BaseException) -> None:
+        super().__init__(f"request to {url} failed")
+        self.url = url
+        self.__cause__ = cause
+
+
+def _build_query(query: Optional[Mapping[str, Any]]) -> str:
+    """Encode a query string, dropping empty values instead of sending ``None``."""
+    if not query:
+        return ""
+    pairs = [(k, str(v)) for k, v in query.items() if v is not None and v != ""]
+    if not pairs:
+        return ""
+    return "?" + urllib.parse.urlencode(pairs)
+
+
+class VibeInfra:
+    """A VibeInfra API client.
+
+    :param base_url: API origin. Defaults to production.
+    :param token: Session JWT, sent as ``Authorization: Bearer``. Only the learner-account
+        methods need one; every catalog method works without it.
+    :param timeout: Per-request timeout in seconds.
+    :param opener: Injected ``urllib`` opener, for tests and custom transports.
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        token: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        opener: Optional[urllib.request.OpenerDirector] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self._opener = opener or urllib.request.build_opener()
+
+    def url(self, path: str, query: Optional[Mapping[str, Any]] = None) -> str:
+        """Absolute URL for a version-relative path. Exposed so callers can log or cache by URL."""
+        suffix = path if path.startswith("/") else f"/{path}"
+        return f"{self.base_url}/api/{API_VERSION}{suffix}{_build_query(query)}"
+
+    def request(
+        self,
+        path: str,
+        method: str = "GET",
+        query: Optional[Mapping[str, Any]] = None,
+        json_body: Optional[Any] = None,
+    ) -> Any:
+        """Perform one request.
+
+        Every method below funnels through here so that timeouts, error shaping and auth are
+        decided once rather than per endpoint.
+        """
+        url = self.url(path, query)
+        data = None
+        headers = {"Accept": "application/json", "User-Agent": _USER_AGENT}
+        if json_body is not None:
+            data = json.dumps(json_body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+
+        request = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with self._opener.open(request, timeout=self.timeout) as response:
+                return _decode(response.read())
+        except urllib.error.HTTPError as error:  # a real response, just not a 2xx
+            body = _decode(error.read())
+            message = body.get("error") if isinstance(body, dict) else None
+            raise VibeInfraApiError(
+                error.code, url, message or f"{method} {url} failed with {error.code}", body
+            ) from error
+        except (urllib.error.URLError, OSError) as error:
+            raise VibeInfraNetworkError(url, error) from error
+
+    # -- Catalog ---------------------------------------------------------------------------
+
+    def list_courses(self, locale: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Every course and incident in the catalog."""
+        return self.request("/courses", query={"locale": locale})
+
+    def get_course(self, course_id: str, locale: Optional[str] = None) -> Dict[str, Any]:
+        """One course blueprint by catalog ID, e.g. ``incident-22-k8s-crashloop``."""
+        if not course_id:
+            raise ValueError("course_id is required")
+        return self.request(
+            f"/courses/{urllib.parse.quote(course_id, safe='')}", query={"locale": locale}
+        )
+
+    def search_courses(
+        self,
+        query: Optional[str] = None,
+        difficulty: Optional[str] = None,
+        category: Optional[str] = None,
+        domain: Optional[str] = None,
+        tech: Optional[str] = None,
+        status: Optional[str] = None,
+        free_only: bool = False,
+        locale: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """Filter the catalog client-side.
+
+        The API has no search endpoint -- the catalog is small enough to fetch whole -- so
+        this filters the list rather than pretending a server-side query exists.
+        """
+        needle = query.strip().lower() if query else None
+        results = []
+        for course in self.list_courses(locale=locale):
+            if difficulty and course.get("difficulty") != difficulty:
+                continue
+            if category and course.get("category") != category:
+                continue
+            if domain and course.get("domain") != domain:
+                continue
+            if status and course.get("status") != status:
+                continue
+            if free_only and not course.get("is_free"):
+                continue
+            stack: Iterable[str] = course.get("tech_stack") or []
+            if tech and not any(t.lower() == tech.lower() for t in stack):
+                continue
+            if needle and needle not in _haystack(course):
+                continue
+            results.append(course)
+        return results
+
+    def get_glossary(self, lang: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Localised glossary of the infrastructure terms used across the catalog."""
+        return self.request("/glossary", query={"lang": lang})
+
+    def list_credit_packs(self) -> List[Dict[str, Any]]:
+        """Purchasable VibeCredits packs, priced in IDR."""
+        return self.request("/credits/packs")
+
+    # -- Platform --------------------------------------------------------------------------
+
+    def get_health(self) -> Dict[str, Any]:
+        """Liveness probe."""
+        return self.request("/health")
+
+    def get_capacity(self) -> Dict[str, Any]:
+        """How much sandbox capacity is in use right now, and how many learners are queued."""
+        return self.request("/labs/capacity")
+
+    def get_public_settings(self) -> Dict[str, Any]:
+        """Public feature flags and the live early-access seat counters."""
+        return self.request("/settings/public")
+
+    def get_public_telemetry(self) -> Dict[str, Any]:
+        """Aggregate, non-personal platform counters."""
+        return self.request("/telemetry/public")
+
+    def get_leaderboard(self) -> Dict[str, Any]:
+        """XP leaderboard and hall of fame."""
+        return self.request("/labs/leaderboard")
+
+    # -- Labs and account ------------------------------------------------------------------
+
+    def start_lab(self, course_id: str) -> Dict[str, Any]:
+        """Provision the sandbox for one incident.
+
+        Works anonymously for the free teaser lab; pass ``token`` to the constructor to start
+        any lab the learner's tier allows. When the platform is saturated the response reports
+        a queued status instead of a session, so check :meth:`get_capacity` first.
+        """
+        if not course_id:
+            raise ValueError("course_id is required")
+        return self.request("/labs/start", method="POST", json_body={"course_id": course_id})
+
+    def get_session(self) -> Dict[str, Any]:
+        """Describe the current session. Returns ``{"authenticated": False}`` when there is none."""
+        return self.request("/auth/me")
+
+    def get_profile(self) -> Dict[str, Any]:
+        """The signed-in learner's profile. Requires a token."""
+        return self.request("/user/profile")
+
+    def list_completions(self) -> List[Dict[str, Any]]:
+        """Incidents this learner has completed. Requires a token."""
+        return self.request("/user/completions")
+
+
+def _haystack(course: Mapping[str, Any]) -> str:
+    """Lower-cased text of a course, for substring search."""
+    parts = [course.get("title"), course.get("description"), course.get("category"), course.get("domain")]
+    parts.extend(course.get("tech_stack") or [])
+    return " ".join(str(p) for p in parts if p).lower()
+
+
+def _decode(raw: bytes) -> Any:
+    """Decode a response body, falling back to text when it is not JSON."""
+    if not raw:
+        return None
+    text = raw.decode("utf-8", errors="replace")
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return text

vibeinfra_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,188 @@
+"""The client is exercised against a stub opener rather than the live API.
+
+These assertions are about the client's own contract -- URL shaping, error mapping, filtering
+-- and a test that needs the network is a test that fails in CI for reasons that are not the
+code's fault.
+"""
+
+import io
+import json
+import urllib.error
+
+import pytest
+
+from vibeinfra import VibeInfra, VibeInfraApiError, VibeInfraNetworkError
+
+
+class StubResponse(io.BytesIO):
+    """Minimal stand-in for the object urllib's opener yields."""
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+        return False
+
+
+class StubOpener:
+    """Records every request and replays a canned response."""
+
+    def __init__(self, body=None, status=200, raises=None):
+        self.body = body if body is not None else {}
+        self.status = status
+        self.raises = raises
+        self.calls = []
+
+    def open(self, request, timeout=None):
+        self.calls.append(request)
+        if self.raises is not None:
+            raise self.raises
+        payload = self.body if isinstance(self.body, (bytes, str)) else json.dumps(self.body)
+        if isinstance(payload, str):
+            payload = payload.encode("utf-8")
+        if self.status >= 400:
+            raise urllib.error.HTTPError(
+                request.full_url, self.status, "error", {}, io.BytesIO(payload)
+            )
+        return StubResponse(payload)
+
+
+CATALOG = [
+    {
+        "id": "incident-22-k8s-crashloop",
+        "title": "Kubernetes Microservices CrashLoopBackOff",
+        "description": "Trace and fix pod CrashLoopBackOff at the Ingress gateway.",
+        "category": "Kubernetes",
+        "domain": "Kubernetes",
+        "difficulty": "Advanced",
+        "status": "enabled",
+        "tech_stack": ["Kubernetes", "Ingress", "kubectl"],
+        "is_free": False,
+    },
+    {
+        "id": "incident-31-disk-full",
+        "title": "Disk Full: Silent Write Failures",
+        "description": "Recover from 100% disk usage and unlinked open file descriptors.",
+        "category": "Linux",
+        "domain": "Linux Kernel & OS",
+        "difficulty": "Intermediate",
+        "status": "enabled",
+        "tech_stack": ["Linux Filesystem", "df", "du"],
+        "is_free": True,
+    },
+]
+
+
+def client(**kwargs):
+    opener = kwargs.pop("opener", StubOpener())
+    return VibeInfra(opener=opener, **kwargs), opener
+
+
+def test_builds_versioned_urls_against_production_by_default():
+    vibe, _ = client()
+    assert vibe.url("/courses") == "https://api.vibeinfra.id/api/v1/courses"
+
+
+def test_trims_a_trailing_slash_from_a_custom_base_url():
+    vibe, _ = client(base_url="http://localhost:8080/")
+    assert vibe.url("/health") == "http://localhost:8080/api/v1/health"
+
+
+def test_omits_empty_query_values():
+    vibe, _ = client()
+    assert vibe.url("/courses", {"locale": None}) == "https://api.vibeinfra.id/api/v1/courses"
+    assert vibe.url("/courses", {"locale": "id"}) == "https://api.vibeinfra.id/api/v1/courses?locale=id"
+
+
+def test_list_courses_returns_the_parsed_catalog():
+    vibe, opener = client(opener=StubOpener(body=CATALOG))
+    courses = vibe.list_courses()
+    assert [c["id"] for c in courses] == [c["id"] for c in CATALOG]
+    assert opener.calls[0].get_method() == "GET"
+
+
+def test_get_course_percent_encodes_the_id():
+    vibe, opener = client(opener=StubOpener(body={"id": "a/b"}))
+    vibe.get_course("a/b")
+    assert opener.calls[0].full_url.endswith("/courses/a%2Fb")
+
+
+def test_get_course_rejects_a_missing_id_before_touching_the_network():
+    vibe, opener = client()
+    with pytest.raises(ValueError):
+        vibe.get_course("")
+    assert opener.calls == []
+
+
+def test_start_lab_posts_the_course_id_as_json():
+    vibe, opener = client(opener=StubOpener(body={"status": "ok"}))
+    vibe.start_lab("incident-31-disk-full")
+    request = opener.calls[0]
+    assert request.get_method() == "POST"
+    assert request.get_header("Content-type") == "application/json"
+    assert json.loads(request.data) == {"course_id": "incident-31-disk-full"}
+
+
+def test_a_token_is_sent_as_a_bearer_header():
+    vibe, opener = client(token="jwt-123", opener=StubOpener(body={"authenticated": True}))
+    vibe.get_session()
+    assert opener.calls[0].get_header("Authorization") == "Bearer jwt-123"
+
+
+def test_no_token_means_no_authorization_header():
+    vibe, opener = client(opener=StubOpener(body=[]))
+    vibe.list_courses()
+    assert opener.calls[0].get_header("Authorization") is None
+
+
+def test_a_non_2xx_response_raises_with_the_servers_message():
+    vibe, _ = client(opener=StubOpener(status=404, body={"error": "Course not found"}))
+    with pytest.raises(VibeInfraApiError) as caught:
+        vibe.get_course("nope")
+    assert caught.value.status == 404
+    assert str(caught.value) == "Course not found"
+    assert caught.value.is_rate_limited is False
+
+
+def test_a_429_is_flagged_as_rate_limited():
+    vibe, _ = client(opener=StubOpener(status=429, body=""))
+    with pytest.raises(VibeInfraApiError) as caught:
+        vibe.start_lab("incident-31-disk-full")
+    assert caught.value.is_rate_limited is True
+
+
+def test_a_401_is_flagged_as_unauthorized():
+    vibe, _ = client(opener=StubOpener(status=401, body=""))
+    with pytest.raises(VibeInfraApiError) as caught:
+        vibe.get_profile()
+    assert caught.value.is_unauthorized is True
+
+
+def test_a_transport_failure_raises_a_network_error_not_the_raw_cause():
+    cause = urllib.error.URLError("ECONNREFUSED")
+    vibe, _ = client(opener=StubOpener(raises=cause))
+    with pytest.raises(VibeInfraNetworkError) as caught:
+        vibe.get_health()
+    assert caught.value.__cause__ is cause
+
+
+def test_a_non_json_body_is_returned_as_text():
+    vibe, _ = client(opener=StubOpener(body="plain text"))
+    assert vibe.get_health() == "plain text"
+
+
+def test_search_matches_title_description_and_tech_stack():
+    vibe, _ = client(opener=StubOpener(body=CATALOG))
+    assert [c["id"] for c in vibe.search_courses(query="crashloop")] == ["incident-22-k8s-crashloop"]
+    assert [c["id"] for c in vibe.search_courses(query="unlinked")] == ["incident-31-disk-full"]
+    assert [c["id"] for c in vibe.search_courses(query="kubectl")] == ["incident-22-k8s-crashloop"]
+
+
+def test_search_filters_combine_and_an_empty_query_matches_everything():
+    vibe, _ = client(opener=StubOpener(body=CATALOG))
+    assert len(vibe.search_courses()) == 2
+    assert len(vibe.search_courses(difficulty="Advanced")) == 1
+    assert len(vibe.search_courses(free_only=True)) == 1
+    assert len(vibe.search_courses(tech="KUBERNETES")) == 1
+    assert len(vibe.search_courses(difficulty="Advanced", free_only=True)) == 0