redfish-python-sdk 1.0.0__py3-none-any.whl

redfish_sdk/exceptions.py

@@ -0,0 +1,56 @@
+"""
+Custom exceptions for the Redfish Python SDK.
+"""
+
+
+class RedfishException(Exception):
+    """
+    Base exception for all Redfish SDK errors.
+
+    Raised when a Redfish API call returns a non-successful HTTP status code.
+    """
+
+    def __init__(self, status_code: int, message: str, body: str = ""):
+        self.status_code = status_code
+        self.message = message
+        self.body = body
+        super().__init__(f"[HTTP {status_code}] {message}")
+
+    def __repr__(self) -> str:
+        return f"RedfishException(status_code={self.status_code}, message={self.message!r})"
+
+
+class RedfishNotFoundError(RedfishException):
+    """Raised when a resource is not found (HTTP 404)."""
+
+    def __init__(self, path: str):
+        super().__init__(404, f"Resource not found: {path}")
+
+
+class RedfishAuthError(RedfishException):
+    """Raised when authentication fails (HTTP 401 / 403)."""
+
+    def __init__(self, status_code: int = 401):
+        super().__init__(status_code, "Authentication failed. Check username and password.")
+
+
+class RedfishConnectionError(RedfishException):
+    """Raised when unable to connect to the BMC."""
+
+    def __init__(self, host: str, cause: Exception = None):
+        super().__init__(0, f"Unable to connect to host: {host}. Cause: {cause}")
+        self.cause = cause
+
+
+class RedfishTimeoutError(RedfishException):
+    """Raised when a request times out."""
+
+    def __init__(self, host: str):
+        super().__init__(0, f"Request timed out connecting to: {host}")
+
+
+class RedfishValidationError(RedfishException):
+    """Raised for invalid input parameters (e.g., unsupported reset type)."""
+
+    def __init__(self, message: str):
+        super().__init__(400, message)

redfish_sdk/http_client.py

@@ -0,0 +1,452 @@
+"""
+Redfish HTTP client — the core transport layer.
+
+Provides low-level GET/POST/PATCH/DELETE operations against a Redfish BMC endpoint.
+
+Design notes:
+- Uses Basic Auth (base64-encoded "username:password") in Authorization header
+- Skips SSL certificate verification (Redfish BMCs use self-signed certs)
+- Supports HTTP proxy
+- Extracts ETag from GET responses and sends If-Match on PATCH requests
+- Raises RedfishException for non-2xx responses
+- Connection timeout: 10s, Read timeout: 30s (configurable)
+
+"""
+from __future__ import annotations
+
+import base64
+import logging
+from typing import Any, Dict, Optional, Type, TypeVar
+
+import requests
+import urllib3
+from pydantic import BaseModel
+
+from .exceptions import (
+    RedfishAuthError,
+    RedfishConnectionError,
+    RedfishException,
+    RedfishNotFoundError,
+    RedfishTimeoutError,
+)
+
+# Suppress InsecureRequestWarning for self-signed certs
+urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T", bound=BaseModel)
+
+# HTTP status codes that indicate success
+_SUCCESS_CODES = {200, 201, 202, 204, 302}
+
+
+class RedfishHttpClient:
+    """
+    Low-level HTTP client for Redfish API calls.
+
+    Usage:
+        import os
+        client = RedfishHttpClient(
+            host=os.environ["BMC_IP"],
+            username=os.environ["BMC_USERNAME"],
+            password=os.environ["BMC_PASSWORD"],
+            verify_ssl=False,
+        )
+        root = client.get("/redfish/v1/", RootService)
+    """
+
+    def __init__(
+        self,
+        host: str,
+        username: str,
+        password: str,
+        verify_ssl: bool = False,
+        proxy: Optional[str] = None,
+        connect_timeout: int = 10,
+        read_timeout: int = 30,
+        scheme: str = "https",
+    ):
+        """
+        Initialize the Redfish HTTP client.
+
+        Args:
+            host: BMC IP address or hostname (e.g., "192.0.2.10")
+            username: BMC username
+            password: BMC password
+            verify_ssl: Whether to verify SSL certificates. Default False (BMCs use self-signed).
+            proxy: Optional HTTP/HTTPS proxy URL (e.g., "http://127.0.0.1:8080")
+            connect_timeout: Connection timeout in seconds
+            read_timeout: Read timeout in seconds
+            scheme: URL scheme, "https" (default) or "http"
+        """
+        self.host = host
+        self.scheme = scheme
+        self.verify_ssl = verify_ssl
+        self.connect_timeout = connect_timeout
+        self.read_timeout = read_timeout
+
+        # Pre-compute Basic Auth header (same as Java's base64 encoding)
+        credentials = f"{username}:{password}"
+        self._basic_auth = "Basic " + base64.b64encode(credentials.encode()).decode()
+
+        # Session with proxy and default headers
+        self._session = requests.Session()
+        self._session.verify = verify_ssl
+        self._session.headers.update({
+            "Authorization": self._basic_auth,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        })
+
+        if proxy:
+            self._session.proxies = {"http": proxy, "https": proxy}
+
+        # Track the last ETag received for use in subsequent PATCH requests
+        self._last_etag: Dict[str, str] = {}
+
+    def _build_url(self, path: str) -> str:
+        """Build a full URL from a Redfish path."""
+        path = path if path.startswith("/") else f"/{path}"
+        return f"{self.scheme}://{self.host}{path}"
+
+    def _get_etag(self, path: str, data: Optional[BaseModel]) -> str:
+        """
+        Get the ETag for a resource.
+        If the model has an odata_etag attribute, use that; otherwise use '*' (wildcard).
+
+
+        """
+        if data is not None and hasattr(data, "odata_etag") and data.odata_etag:
+            return data.odata_etag
+        return self._last_etag.get(path, "*")
+
+    def _store_etag(self, path: str, response: requests.Response) -> None:
+        """
+        Extract and store ETag from response headers.
+
+
+        """
+        etag = response.headers.get("ETag") or response.headers.get("etag")
+        if etag:
+            self._last_etag[path] = etag
+
+    def _raise_for_status(self, response: requests.Response, path: str) -> None:
+        """
+        Raise a typed RedfishException for non-2xx responses.
+        """
+        code = response.status_code
+        if code in _SUCCESS_CODES:
+            return
+
+        body = ""
+        try:
+            body = response.text
+        except Exception:
+            pass
+
+        logger.error("Request failed: %s %s -> HTTP %d, body: %s",
+                     response.request.method, path, code, body[:500])
+
+        if code in (401, 403):
+            raise RedfishAuthError(code)
+        if code == 404:
+            raise RedfishNotFoundError(path)
+        raise RedfishException(code, f"Request to {path} failed", body)
+
+    def _parse(self, response: requests.Response, model_class: Type[T]) -> T:
+        """Parse JSON response into a pydantic model."""
+        try:
+            data = response.json()
+            return model_class.model_validate(data)
+        except Exception as exc:
+            logger.error("Failed to parse response as %s: %s", model_class.__name__, exc)
+            raise RedfishException(
+                response.status_code,
+                f"Failed to parse response as {model_class.__name__}: {exc}",
+                response.text[:1000],
+            ) from exc
+
+    # ------------------------------------------------------------------
+    # Public HTTP methods
+    # ------------------------------------------------------------------
+
+    def get(self, path: str, model_class: Type[T]) -> T:
+        """
+        Send a GET request and return the parsed response.
+
+        Args:
+            path: Redfish resource path (e.g., "/redfish/v1/Systems/1")
+            model_class: Pydantic model class to deserialize the response into
+
+        Returns:
+            Parsed model instance
+
+        Raises:
+            RedfishException: On non-2xx HTTP responses
+            RedfishConnectionError: On network errors
+            RedfishTimeoutError: On timeout
+        """
+        url = self._build_url(path)
+        logger.debug("GET %s", url)
+
+        try:
+            response = self._session.get(
+                url, timeout=(self.connect_timeout, self.read_timeout)
+            )
+        except requests.exceptions.Timeout as exc:
+            raise RedfishTimeoutError(self.host) from exc
+        except requests.exceptions.ConnectionError as exc:
+            raise RedfishConnectionError(self.host, exc) from exc
+
+        logger.debug("GET %s -> HTTP %d", url, response.status_code)
+        self._store_etag(path, response)
+        self._raise_for_status(response, path)
+        result = self._parse(response, model_class)
+
+        # Store etag on the model itself if it's an Entity
+        if hasattr(result, "odata_etag") and not result.odata_etag:
+            etag = self._last_etag.get(path)
+            if etag:
+                result.odata_etag = etag
+
+        return result
+
+    def get_raw(self, path: str) -> Any:
+        """
+        Send a GET request and return the raw JSON dict (for dynamic structures).
+        """
+        url = self._build_url(path)
+        logger.debug("GET (raw) %s", url)
+        try:
+            response = self._session.get(
+                url, timeout=(self.connect_timeout, self.read_timeout)
+            )
+        except requests.exceptions.Timeout as exc:
+            raise RedfishTimeoutError(self.host) from exc
+        except requests.exceptions.ConnectionError as exc:
+            raise RedfishConnectionError(self.host, exc) from exc
+
+        self._store_etag(path, response)
+        self._raise_for_status(response, path)
+        return response.json()
+
+    def post(self, path: str, model_class: Type[T], body: Optional[BaseModel] = None,
+             raw_body: Optional[Dict] = None) -> T:
+        """
+        Send a POST request and return the parsed response.
+
+        Args:
+            path: Redfish resource path
+            model_class: Pydantic model to deserialize response into
+            body: Optional pydantic model to serialize as request body
+            raw_body: Optional raw dict as request body (alternative to body)
+
+        Returns:
+            Parsed model instance
+
+        Raises:
+            RedfishException: On non-2xx HTTP responses
+        """
+        url = self._build_url(path)
+        json_payload = None
+        if body is not None:
+            json_payload = body.model_dump(by_alias=True, exclude_none=True)
+        elif raw_body is not None:
+            json_payload = raw_body
+
+        logger.info("POST %s, payload: %s", url, json_payload)
+
+        try:
+            response = self._session.post(
+                url,
+                json=json_payload,
+                timeout=(self.connect_timeout, self.read_timeout),
+            )
+        except requests.exceptions.Timeout as exc:
+            raise RedfishTimeoutError(self.host) from exc
+        except requests.exceptions.ConnectionError as exc:
+            raise RedfishConnectionError(self.host, exc) from exc
+
+        logger.info("POST %s -> HTTP %d", url, response.status_code)
+        self._store_etag(path, response)
+        self._raise_for_status(response, path)
+
+        # 204 No Content — return empty model
+        if response.status_code == 204 or not response.text.strip():
+            return model_class.model_construct()
+
+        return self._parse(response, model_class)
+
+    def post_raw(self, path: str, body: Optional[Dict] = None) -> requests.Response:
+        """
+        Send a POST request and return the raw Response object.
+        Useful when the caller needs response headers (e.g., X-Auth-Token).
+        """
+        url = self._build_url(path)
+        logger.info("POST (raw) %s, payload: %s", url, body)
+        try:
+            response = self._session.post(
+                url,
+                json=body,
+                timeout=(self.connect_timeout, self.read_timeout),
+            )
+        except requests.exceptions.Timeout as exc:
+            raise RedfishTimeoutError(self.host) from exc
+        except requests.exceptions.ConnectionError as exc:
+            raise RedfishConnectionError(self.host, exc) from exc
+
+        logger.info("POST (raw) %s -> HTTP %d", url, response.status_code)
+        self._store_etag(path, response)
+        self._raise_for_status(response, path)
+        return response
+
+    def patch(self, path: str, model_class: Type[T], body: BaseModel,
+              extra_headers: Optional[Dict[str, str]] = None) -> T:
+        """
+        Send a PATCH request and return the parsed response.
+
+        Automatically sets the If-Match header using the ETag from the entity
+        (or '*' if no ETag is available).
+
+        Args:
+            path: Redfish resource path
+            model_class: Pydantic model to deserialize response into
+            body: Pydantic model to serialize as request body (must be Entity for ETag)
+            extra_headers: Additional headers to include (e.g., Content-Type overrides)
+
+        Returns:
+            Parsed model instance
+
+        Raises:
+            RedfishException: On non-2xx HTTP responses
+        """
+        url = self._build_url(path)
+        etag = self._get_etag(path, body)
+        json_payload = body.model_dump(by_alias=True, exclude_none=True)
+
+        headers = {"If-Match": etag}
+        if extra_headers:
+            headers.update(extra_headers)
+
+        logger.info("PATCH %s, If-Match: %s, payload: %s", url, etag, json_payload)
+
+        try:
+            response = self._session.patch(
+                url,
+                json=json_payload,
+                headers=headers,
+                timeout=(self.connect_timeout, self.read_timeout),
+            )
+        except requests.exceptions.Timeout as exc:
+            raise RedfishTimeoutError(self.host) from exc
+        except requests.exceptions.ConnectionError as exc:
+            raise RedfishConnectionError(self.host, exc) from exc
+
+        logger.info("PATCH %s -> HTTP %d", url, response.status_code)
+        self._store_etag(path, response)
+        self._raise_for_status(response, path)
+
+        # 204 No Content
+        if response.status_code == 204 or not response.text.strip():
+            return model_class.model_construct()
+
+        return self._parse(response, model_class)
+
+    def patch_raw(self, path: str, body: Dict, extra_headers: Optional[Dict[str, str]] = None) -> requests.Response:
+        """
+        Send a PATCH request with a raw dict body and return the raw Response object.
+
+        Automatically sets the If-Match header using the cached ETag
+        (or '*' if no ETag is available).
+
+        Args:
+            path: Redfish resource path
+            body: Raw dict to serialize as JSON request body
+            extra_headers: Additional headers to include
+
+        Returns:
+            Raw Response object
+
+        Raises:
+            RedfishException: On non-2xx HTTP responses
+        """
+        url = self._build_url(path)
+        etag = self._last_etag.get(path, "*")
+
+        headers = {"If-Match": etag}
+        if extra_headers:
+            headers.update(extra_headers)
+
+        logger.info("PATCH (raw) %s, If-Match: %s, payload: %s", url, etag, body)
+
+        try:
+            response = self._session.patch(
+                url,
+                json=body,
+                headers=headers,
+                timeout=(self.connect_timeout, self.read_timeout),
+            )
+        except requests.exceptions.Timeout as exc:
+            raise RedfishTimeoutError(self.host) from exc
+        except requests.exceptions.ConnectionError as exc:
+            raise RedfishConnectionError(self.host, exc) from exc
+
+        logger.info("PATCH (raw) %s -> HTTP %d", url, response.status_code)
+        self._store_etag(path, response)
+        self._raise_for_status(response, path)
+        return response
+
+    def delete(self, path: str) -> str:
+        """
+        Send a DELETE request.
+
+        Args:
+            path: Redfish resource path
+
+        Returns:
+            Response body as string (usually empty for 204)
+
+        Raises:
+            RedfishException: On non-2xx HTTP responses
+        """
+        url = self._build_url(path)
+        logger.info("DELETE %s", url)
+
+        try:
+            response = self._session.delete(
+                url, timeout=(self.connect_timeout, self.read_timeout)
+            )
+        except requests.exceptions.Timeout as exc:
+            raise RedfishTimeoutError(self.host) from exc
+        except requests.exceptions.ConnectionError as exc:
+            raise RedfishConnectionError(self.host, exc) from exc
+
+        logger.info("DELETE %s -> HTTP %d", url, response.status_code)
+        self._raise_for_status(response, path)
+        return response.text
+
+    def set_auth_token(self, token: str) -> None:
+        """
+        Switch from Basic Auth to Session-based auth (X-Auth-Token).
+        Called after successfully creating a session.
+        """
+        self._session.headers.pop("Authorization", None)
+        self._session.headers["X-Auth-Token"] = token
+        logger.debug("Switched to X-Auth-Token authentication")
+
+    def reset_basic_auth(self) -> None:
+        """Switch back to Basic Auth (e.g., after session deletion)."""
+        self._session.headers.pop("X-Auth-Token", None)
+        self._session.headers["Authorization"] = self._basic_auth
+        logger.debug("Switched back to Basic Auth")
+
+    def close(self) -> None:
+        """Close the underlying HTTP session."""
+        self._session.close()
+
+    def __enter__(self) -> RedfishHttpClient:
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()

redfish_sdk/managers/__init__.py

@@ -0,0 +1,21 @@
+from .account import AccountServiceManager
+from .chassis import ChassisManager
+from .event import EventServiceManager
+from .managers import ManagersManager
+from .registries import RegistriesManager
+from .session import SessionServiceManager
+from .systems import SystemsManager
+from .task import TaskServiceManager
+from .update import UpdateServiceManager
+
+__all__ = [
+    "SystemsManager",
+    "ChassisManager",
+    "ManagersManager",
+    "AccountServiceManager",
+    "SessionServiceManager",
+    "EventServiceManager",
+    "UpdateServiceManager",
+    "RegistriesManager",
+    "TaskServiceManager",
+]

redfish_sdk/managers/_log_helpers.py

@@ -0,0 +1,144 @@
+"""
+Shared helpers for fetching log services and their entries.
+
+Used by both :mod:`redfish_sdk.managers.systems` and
+:mod:`redfish_sdk.managers.managers` so the two log services share the
+same behaviour: missing-LogServices guard, dynamic LogService URL
+discovery (no path concatenation), and log_id auto-selection.
+"""
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, List, Optional
+
+from ..exceptions import (
+    RedfishException,
+    RedfishNotFoundError,
+    RedfishValidationError,
+)
+from ..models.logs import Log, LogEntry
+
+if TYPE_CHECKING:
+    from ..client import RedfishClient
+
+logger = logging.getLogger(__name__)
+
+
+def require_log_services_link(
+    parent_resource: object,
+    parent_name: str,
+) -> str:
+    """
+    Extract ``LogServices.@odata.id`` from a System/Manager resource, raising
+    a clear error when the BMC did not advertise a LogServices link at all.
+
+    The ``Optional[Link]`` typing on ``System.log_services`` / ``Manager.log_services``
+    reflects the Redfish spec: ``LogServices`` is an optional sub-resource and
+    some lightweight BMCs (or disabled audit roles) genuinely omit it. Without
+    this guard, callers crash with a bare ``AttributeError: 'NoneType' object``
+    that doesn't reveal which BMC capability is missing.
+
+    Args:
+        parent_resource: A System or Manager instance with a ``log_services`` attr.
+        parent_name: Human label for the error message (e.g. ``"System 1"``).
+
+    Returns:
+        The ``@odata.id`` of the LogServices collection.
+
+    Raises:
+        RedfishException: 404 when the parent resource does not expose
+            LogServices.
+    """
+    link = getattr(parent_resource, "log_services", None)
+    odata_id = getattr(link, "odata_id", None) if link is not None else None
+    if not odata_id:
+        raise RedfishException(
+            404,
+            f"{parent_name} does not expose a LogServices collection "
+            f"(BMC returned no `LogServices` link on the resource)",
+        )
+    return odata_id
+
+
+def resolve_log_service(
+    client: "RedfishClient",
+    log_services_odata_id: str,
+    log_id: Optional[str],
+) -> Log:
+    """
+    Resolve a single :class:`Log` resource by ID or auto-select when only one.
+
+    Both branches discover the real per-LogService ``@odata.id`` by listing
+    the parent ``LogServices`` collection and matching by ``Log.id`` —
+    never assume the URL is ``f"{log_services_odata_id}/{log_id}"``. Some
+    vendors (e.g. Huawei iBMC OEM logs) publish a non-standard child path,
+    so trusting the collection link is the only correct approach.
+
+    Args:
+        client: RedfishClient instance (used to fetch the LogServices collection).
+        log_services_odata_id: ``@odata.id`` of the parent ``LogServices`` collection.
+        log_id: Explicit log service ID, or None to auto-select the sole member.
+
+    Raises:
+        RedfishException: 404 when the collection is empty.
+        RedfishValidationError: When ``log_id`` is None and multiple members exist.
+        RedfishNotFoundError: When the requested ``log_id`` is not present.
+    """
+    services = client._get_collection(log_services_odata_id, Log)
+    if not services:
+        raise RedfishException(
+            404, f"No log services found under {log_services_odata_id}"
+        )
+
+    if log_id is None:
+        if len(services) > 1:
+            ids = [s.id for s in services if s.id]
+            raise RedfishValidationError(
+                f"Multiple log services found, please specify log_id. "
+                f"Available: {ids}"
+            )
+        return services[0]
+
+    # Explicit log_id — look it up by ``Log.id`` in the collection rather
+    # than rebuilding the URL by string concatenation.
+    matches = [s for s in services if s.id == log_id]
+    if not matches:
+        available = [s.id for s in services if s.id]
+        raise RedfishNotFoundError(
+            f"{log_services_odata_id}/{log_id} "
+            f"(no log service with id={log_id!r}; available={available})"
+        )
+    return matches[0]
+
+
+def fetch_log_entries(client: "RedfishClient", log: Log) -> List[LogEntry]:
+    """
+    Fetch all LogEntry items under a Log resource.
+
+    Strategy: always GET the Entries collection link from
+    ``log.entries.odata_id`` (NOT a hard-coded ``/Entries`` suffix) and
+    expand its members one by one via the shared ``_get_collection``
+    helper.
+
+    Returns an empty list when the LogService has no Entries link at all
+    (some BMCs expose log services without entries, e.g. a disabled audit
+    log).
+
+    History — why we don't use ``?$expand=.($levels=1)``:
+        An earlier prototype tried ``$expand`` first and fell back to per-entry
+        GET only on 4xx errors or bare-link responses. Real-world testing
+        against multiple BMCs showed that
+        some servers **silently swallow** the query and return an empty
+        ``Members`` collection with ``Members@odata.count: 0`` even when
+        actual entries exist. There is no reliable wire-level signal that
+        distinguishes "BMC genuinely has no entries" from "BMC broke
+        expand"; both look like the same valid Redfish empty collection.
+        Per-entry GET via ``_get_collection`` is the only behaviour that
+        is correct across every BMC we have seen. Callers needing more
+        throughput can parallelise externally.
+    """
+    if not log.entries or not log.entries.odata_id:
+        logger.debug("Log %s has no Entries link", log.odata_id)
+        return []
+
+    return client._get_collection(log.entries.odata_id, LogEntry)