Refactored Owncast clients to share a private HTTP transport helper instead of inheritance.

owlbot/owncast_http.py

@@ -0,0 +1,167 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Shared HTTP transport helpers for the Owncast API clients."""
+
+from __future__ import annotations
+
+from http import HTTPStatus
+from typing import TYPE_CHECKING, Any
+
+import aiohttp
+import orjson
+from aiohttp import ContentTypeError
+
+if TYPE_CHECKING:
+    import logging
+
+    from owlbot.api.http_client import HttpClient
+
+
+class OwncastError(Exception):
+    """Raised when an Owncast API request fails."""
+
+    def __init__(self, status: int, message: str) -> None:
+        """Initialize the error.
+
+        :param status: HTTP status code from the failed request, or 0 if the
+            request failed due to a connection error before receiving a response.
+        :param message: Error message or response body from the server.
+        """
+        self.status = status
+        self.message = message
+        super().__init__(f"Owncast error {status}: {message}")
+
+
+def _extract_error(text: str) -> str:
+    """Extract a human-readable error from an Owncast response body.
+
+    Owncast may return ``{"error": "..."}`` or
+    ``{"success": false, "message": "..."}``, or plain text.  This helper
+    unwraps the JSON envelope when present.
+    """
+    try:
+        data = orjson.loads(text)
+    except (ValueError, TypeError):
+        return text
+    if isinstance(data, dict):
+        if "error" in data:
+            return str(data["error"])
+        if "message" in data:
+            return str(data["message"])
+    return text
+
+
+async def post_with_envelope(
+    http: HttpClient,
+    base_url: str,
+    endpoint: str,
+    data: dict[str, Any] | None = None,
+    *,
+    logger: logging.Logger,
+    auth: aiohttp.BasicAuth | None = None,
+    headers: dict[str, str] | None = None,
+) -> str:
+    """Send a POST and unwrap the Owncast ``{"success", "message"}`` envelope.
+
+    :raises OwncastError: If the request fails or the server reports failure.
+    """
+    url = f"{base_url}{endpoint}"
+    logger.debug("POST %s", endpoint)
+    try:
+        async with http.session.post(
+            url,
+            json=data,
+            headers=headers,
+            auth=auth,
+            allow_redirects=False,
+        ) as response:
+            if response.status >= HTTPStatus.BAD_REQUEST:
+                text = await response.text()
+                message = _extract_error(text)
+                logger.error(
+                    "Error %d on POST %s: %s", response.status, endpoint, message
+                )
+                raise OwncastError(response.status, message)
+            logger.debug("POST %s -> %d", endpoint, response.status)
+            if response.content_type == "application/json":
+                try:
+                    result = await response.json(loads=orjson.loads)
+                except (ValueError, ContentTypeError):
+                    text = await response.text()
+                    logger.exception("Invalid JSON on POST %s: %s", endpoint, text)
+                    raise OwncastError(response.status, text) from None
+                if isinstance(result, dict):
+                    if "error" in result:
+                        logger.error("Error on POST %s: %s", endpoint, result["error"])
+                        raise OwncastError(response.status, result["error"])
+                    if "success" in result and not result["success"]:
+                        message = result.get("message", "unknown error")
+                        logger.error("Error on POST %s: %s", endpoint, message)
+                        raise OwncastError(response.status, message)
+                    if "success" in result:
+                        return str(result.get("message", ""))
+                logger.warning("Unknown response on POST %s: %s", endpoint, result)
+                return ""
+            return ""
+    except aiohttp.ClientError as e:
+        logger.exception("Connection error on POST %s.", endpoint)
+        raise OwncastError(0, str(e)) from e
+
+
+async def get_json(
+    http: HttpClient,
+    base_url: str,
+    endpoint: str,
+    params: dict[str, Any] | None = None,
+    *,
+    logger: logging.Logger,
+    auth: aiohttp.BasicAuth | None = None,
+    headers: dict[str, str] | None = None,
+) -> Any:
+    """Send a GET and return the parsed JSON body.
+
+    :raises OwncastError: If the request fails or the response cannot be parsed.
+    """
+    url = f"{base_url}{endpoint}"
+    logger.debug("GET %s", endpoint)
+    try:
+        async with http.session.get(
+            url,
+            params=params,
+            headers=headers,
+            auth=auth,
+            allow_redirects=False,
+        ) as response:
+            if response.status >= HTTPStatus.BAD_REQUEST:
+                text = await response.text()
+                message = _extract_error(text)
+                logger.error(
+                    "Error %d on GET %s: %s", response.status, endpoint, message
+                )
+                raise OwncastError(response.status, message)
+            logger.debug("GET %s -> %d", endpoint, response.status)
+            try:
+                result = await response.json(loads=orjson.loads)
+            except (ValueError, ContentTypeError):
+                text = await response.text()
+                logger.exception("Invalid JSON on GET %s: %s", endpoint, text)
+                raise OwncastError(response.status, text) from None
+            if isinstance(result, dict) and "error" in result:
+                logger.error("Error on GET %s: %s", endpoint, result["error"])
+                raise OwncastError(response.status, result["error"])
+            return result
+    except aiohttp.ClientError as e:
+        logger.exception("Connection error on GET %s.", endpoint)
+        raise OwncastError(0, str(e)) from e