irusdk 0.1.0__py3-none-any.whl

irusdk/__about__.py

@@ -0,0 +1,2 @@
+__title__ = "irusdk"
+__version__ = "0.1.0"

irusdk/__init__.py

@@ -0,0 +1,35 @@
+"""A Python SDK for the Iru (formerly Kandji) Endpoint Management API."""
+
+from .__about__ import __title__, __version__
+from ._core.config import IruConfig
+from ._core.errors import (
+    APIResponseError,
+    AuthenticationError,
+    ConfigurationError,
+    IruError,
+    NotFoundError,
+    PaginationError,
+    RateLimitError,
+    ServerError,
+)
+from ._core.pagination import Page
+from ._core.urls import Region
+from .client import AsyncIruClient, IruClient
+
+__all__ = [
+    "APIResponseError",
+    "AsyncIruClient",
+    "AuthenticationError",
+    "ConfigurationError",
+    "IruClient",
+    "IruConfig",
+    "IruError",
+    "NotFoundError",
+    "Page",
+    "PaginationError",
+    "RateLimitError",
+    "Region",
+    "ServerError",
+    "__title__",
+    "__version__",
+]

irusdk/_core/config.py

@@ -0,0 +1,52 @@
+"""Client-wide tuning knobs."""
+
+import platform
+import sys
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..__about__ import __version__
+
+# Iru's published tenant limits. The defaults below sit under these deliberately:
+# retries and redirects count against the vendor's tally but not always against ours.
+API_LIMIT_PER_SECOND = 50
+API_LIMIT_PER_HOUR = 10_000
+
+DEFAULT_USER_AGENT = (
+    f"irusdk/{__version__} "
+    f"{platform.system()}/{platform.release()} "
+    f"Python/{sys.version_info.major}.{sys.version_info.minor}"
+)
+
+
+class IruConfig(BaseModel):
+    """
+    Tuning for transport, concurrency, rate limiting, and retries.
+
+    :ivar timeout: Per-request timeout in seconds.
+    :ivar max_concurrency: Ceiling on in-flight requests, used for page prefetch and the httpx
+        connection pool.
+    :ivar requests_per_second: Client-side throttle. Defaults below Iru's published 50/sec.
+    :ivar requests_per_hour: Client-side hourly budget. Defaults below Iru's published 10,000/hr.
+    :ivar max_retries: Retry attempts after the initial request, for 429 and 5xx responses.
+    :ivar backoff_factor: Base for the exponential backoff between retries, in seconds.
+    :ivar max_backoff: Ceiling on any single backoff sleep, in seconds.
+    :ivar max_pages: Safety valve for endpoints that return no total, guarding against an
+        endpoint that ignores its offset parameter and paginates forever.
+    :ivar user_agent: The ``User-Agent`` header sent on every request.
+    :ivar verify: TLS verification. ``True`` uses the OS trust store via truststore; a string is
+        treated as a path to a CA bundle.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    timeout: float = Field(default=30.0, gt=0)
+    max_concurrency: int = Field(default=5, ge=1, le=50)
+    requests_per_second: float = Field(default=45.0, gt=0)
+    requests_per_hour: int = Field(default=9_500, gt=0)
+    max_retries: int = Field(default=3, ge=0)
+    backoff_factor: float = Field(default=0.5, gt=0)
+    max_backoff: float = Field(default=60.0, gt=0)
+    max_pages: int = Field(default=10_000, ge=1)
+    user_agent: str = DEFAULT_USER_AGENT
+    verify: bool | str = True

irusdk/_core/errors.py

@@ -0,0 +1,155 @@
+"""The irusdk exception hierarchy and the shared status-code mapping."""
+
+from typing import Any, Mapping
+
+# Status codes that indicate the tenant's request quota is exhausted.
+RATE_LIMIT_STATUS = 429
+
+# Keys pulled from an error body, in priority order. The Iru API is inconsistent
+# about which one it uses.
+_ERROR_BODY_KEYS = ("detail", "error", "errors", "message")
+
+
+class IruError(Exception):
+    """
+    Base exception for every error raised by this SDK.
+
+    Carries arbitrary keyword context (``status_code=401``, ``url=...``) and renders it into the
+    formatted message as ``message (key1: val1 | key2: val2)``. Each keyword is also set as an
+    instance attribute so callers can branch on it.
+
+    :param message: The human-readable error message. Falls back to :attr:`default_message`.
+    :type message: str | None
+    :param kwargs: Arbitrary context attached to the exception.
+    """
+
+    default_message = "An error occurred"
+
+    def __init__(self, message: str | None = None, **kwargs: Any) -> None:
+        self.message = message or self.default_message
+        self.context = kwargs
+        for key, value in kwargs.items():
+            if not hasattr(self, key):
+                setattr(self, key, value)
+        self.formatted_message = self.format_message()
+        super().__init__(self.formatted_message)
+
+    def format_message(self) -> str:
+        """
+        Render the message with its context appended.
+
+        :return: The message, followed by ``(key: value | ...)`` when context is present.
+        :rtype: str
+        """
+        details = " | ".join(f"{k}: {v}" for k, v in self.context.items() if v is not None)
+        return f"{self.message} ({details})" if details else self.message
+
+    def __str__(self) -> str:
+        return self.formatted_message
+
+
+class ConfigurationError(IruError):
+    """Raised when the client is constructed with invalid or missing configuration."""
+
+    default_message = "Invalid client configuration"
+
+
+class APIResponseError(IruError):
+    """Raised when the API returns an unsuccessful status code."""
+
+    default_message = "The Iru API returned an error"
+
+
+class AuthenticationError(APIResponseError):
+    """Raised on ``401`` or ``403`` — the API token is missing, invalid, or lacks permission."""
+
+    default_message = "Authentication failed"
+
+
+class NotFoundError(APIResponseError):
+    """Raised on ``404`` — the requested resource does not exist."""
+
+    default_message = "Requested resource was not found"
+
+
+class RateLimitError(APIResponseError):
+    """
+    Raised on ``429`` once the retry policy has given up.
+
+    Iru enforces 50 requests/second and 10,000 requests/hour per tenant. Seeing this means the
+    client exhausted its retries; ``retry_after`` carries the server's hint when one was sent.
+    """
+
+    default_message = "Rate limit exceeded"
+
+
+class ServerError(APIResponseError):
+    """Raised on ``5xx`` — the API failed to process an otherwise valid request."""
+
+    default_message = "The Iru API encountered a server error"
+
+
+class PaginationError(IruError):
+    """
+    Raised when pagination cannot terminate safely.
+
+    Guards against an endpoint that ignores its offset parameter, which would otherwise loop
+    forever re-fetching the first page.
+    """
+
+    default_message = "Pagination did not terminate"
+
+
+def extract_error_detail(body: Any) -> str | None:
+    """
+    Pull a human-readable detail string out of an error response body.
+
+    :param body: The decoded JSON body, or ``None`` when the body was not JSON.
+    :return: The first populated known error key, or ``None``.
+    :rtype: str | None
+    """
+    if not isinstance(body, Mapping):
+        return None
+    for key in _ERROR_BODY_KEYS:
+        if value := body.get(key):
+            return str(value)
+    return None
+
+
+def raise_for_response(
+    status_code: int,
+    *,
+    url: str | None = None,
+    body: Any = None,
+    retry_after: float | None = None,
+) -> None:
+    """
+    Map an HTTP status code onto the exception hierarchy. A 2xx status is a no-op.
+
+    This is the single status handler shared by both transports, so the sync and async clients
+    cannot diverge in what they raise.
+
+    :param status_code: The HTTP status code of the response.
+    :type status_code: int
+    :param url: The request URL, attached to the exception as context.
+    :type url: str | None
+    :param body: The decoded JSON body, used to extract an error detail.
+    :param retry_after: Seconds the server asked the client to wait, for ``429`` responses.
+    :type retry_after: float | None
+    :raises APIResponseError: Or one of its subclasses, for any non-2xx status.
+    """
+    if 200 <= status_code < 300:
+        return
+
+    detail = extract_error_detail(body)
+    context: dict[str, Any] = {"status_code": status_code, "url": url, "detail": detail}
+
+    if status_code in (401, 403):
+        raise AuthenticationError(**context)
+    if status_code == 404:
+        raise NotFoundError(**context)
+    if status_code == RATE_LIMIT_STATUS:
+        raise RateLimitError(retry_after=retry_after, **context)
+    if 500 <= status_code < 600:
+        raise ServerError(**context)
+    raise APIResponseError(**context)

irusdk/_core/pagination.py

@@ -0,0 +1,247 @@
+"""Pagination strategies.
+
+The Iru API pages several different ways, so each strategy owns the "what are the next page's
+parameters, are we done, and can the remaining pages be fetched at once" logic. The strategies are
+pure — no I/O — and both transports consume them unchanged.
+
+Envelope shapes in the wild:
+
+===============================================  ==================  ==========================
+Envelope                                         Parameters          Endpoints
+===============================================  ==================  ==========================
+bare JSON array                                  ``limit``/``offset``  ``/devices``
+``{count, next, previous, results}``             ``limit``/``offset``  blueprints, library activity
+``{count, next, previous, results}``             ``page``              custom apps, scripts, ADE
+``{offset, limit, total, cursor, data}``         ``limit``/``offset``  ``/prism/*``
+``{total, page, size, results}``                 ``page``/``size``     vulnerability management
+``{next, previous, results}``                    ``cursor``            users, admins, audit events
+===============================================  ==================  ==========================
+"""
+
+import math
+from dataclasses import dataclass, field
+from typing import Any, Generic, Protocol, TypeVar
+from urllib.parse import parse_qsl, urlparse
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class PageResult:
+    """
+    One decoded page, before its records are validated into models.
+
+    :ivar items: The raw records on this page.
+    :ivar total: The total record count when the envelope reports one, else ``None``.
+    :ivar next_params: Query parameters for the following page, extracted from a ``next`` URL.
+    :ivar raw: The full decoded body, kept so callers can reach envelope extras.
+    """
+
+    items: list[Any]
+    total: int | None = None
+    next_params: dict[str, Any] | None = None
+    raw: Any = None
+
+
+@dataclass(frozen=True)
+class Page(Generic[T]):
+    """
+    A page of validated records, as handed to callers by a paginator.
+
+    :ivar index: Zero-based position of this page in the sequence.
+    :ivar items: The validated records.
+    :ivar total: The total record count when the API reports one, else ``None``.
+    """
+
+    index: int
+    items: list[T]
+    total: int | None = None
+    raw: Any = field(default=None, repr=False)
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+    def __iter__(self):
+        return iter(self.items)
+
+
+class PaginationStrategy(Protocol):
+    """The contract every pagination strategy implements."""
+
+    def first_params(self, page_size: int) -> dict[str, Any]:
+        """Query parameters for the first page."""
+        ...
+
+    def parse(self, body: Any) -> PageResult:
+        """Decode a response body into a :class:`PageResult`."""
+        ...
+
+    def next_params(self, prev: PageResult, page_size: int, fetched: int) -> dict[str, Any] | None:
+        """Parameters for the page after ``prev``, or ``None`` when the sequence is exhausted."""
+        ...
+
+    def plan(self, first: PageResult, page_size: int) -> list[dict[str, Any]] | None:
+        """
+        Parameters for every page after the first, when they can be computed up front.
+
+        Returning ``None`` means the endpoint must be walked serially.
+        """
+        ...
+
+
+def _extract_next_params(body: Any) -> dict[str, Any] | None:
+    """Pull the query parameters out of an envelope's ``next`` URL, if it has one."""
+    if not isinstance(body, dict):
+        return None
+    if not (nxt := body.get("next")):
+        return None
+    return dict(parse_qsl(urlparse(str(nxt)).query)) or None
+
+
+class OffsetPagination:
+    """
+    ``limit`` / ``offset`` paging.
+
+    Covers the bare-array device list, the ``{count, ..., results}`` envelope, and Prism's
+    ``{total, ..., data}`` envelope, which differ only in where the records and the total live.
+
+    :param results_key: Envelope key holding the records. ``None`` means the body is a bare array.
+    :type results_key: str | None
+    :param total_key: Envelope key holding the record count, when the API reports one.
+    :type total_key: str | None
+    """
+
+    def __init__(self, results_key: str | None = None, total_key: str | None = None) -> None:
+        self.results_key = results_key
+        self.total_key = total_key
+
+    def first_params(self, page_size: int) -> dict[str, Any]:
+        return {"limit": page_size, "offset": 0}
+
+    def parse(self, body: Any) -> PageResult:
+        if self.results_key is None:
+            items = body if isinstance(body, list) else []
+            return PageResult(items=list(items), raw=body)
+
+        envelope = body if isinstance(body, dict) else {}
+        total = envelope.get(self.total_key) if self.total_key else None
+        return PageResult(
+            items=list(envelope.get(self.results_key) or []),
+            total=total if isinstance(total, int) else None,
+            next_params=_extract_next_params(envelope),
+            raw=body,
+        )
+
+    def next_params(self, prev: PageResult, page_size: int, fetched: int) -> dict[str, Any] | None:
+        # A short page is the only end-of-sequence signal when no total is reported.
+        if not prev.items or len(prev.items) < page_size:
+            return None
+        if prev.total is not None and fetched >= prev.total:
+            return None
+        return {"limit": page_size, "offset": fetched}
+
+    def plan(self, first: PageResult, page_size: int) -> list[dict[str, Any]] | None:
+        if first.total is None or not first.items:
+            return None
+        stride = len(first.items)
+        return [
+            {"limit": stride, "offset": offset} for offset in range(stride, first.total, stride)
+        ]
+
+
+class PagePagination:
+    """
+    One-based ``page`` paging, optionally with an explicit page-size parameter.
+
+    :param results_key: Envelope key holding the records.
+    :type results_key: str
+    :param total_key: Envelope key holding the record count.
+    :type total_key: str
+    :param size_param: Name of the page-size parameter, or ``None`` when the endpoint has none.
+    :type size_param: str | None
+    """
+
+    def __init__(
+        self,
+        results_key: str = "results",
+        total_key: str = "count",
+        size_param: str | None = None,
+    ) -> None:
+        self.results_key = results_key
+        self.total_key = total_key
+        self.size_param = size_param
+
+    def _page_params(self, page: int, page_size: int) -> dict[str, Any]:
+        params: dict[str, Any] = {"page": page}
+        if self.size_param:
+            params[self.size_param] = page_size
+        return params
+
+    def first_params(self, page_size: int) -> dict[str, Any]:
+        return self._page_params(1, page_size)
+
+    def parse(self, body: Any) -> PageResult:
+        envelope = body if isinstance(body, dict) else {}
+        total = envelope.get(self.total_key)
+        return PageResult(
+            items=list(envelope.get(self.results_key) or []),
+            total=total if isinstance(total, int) else None,
+            next_params=_extract_next_params(envelope),
+            raw=body,
+        )
+
+    def next_params(self, prev: PageResult, page_size: int, fetched: int) -> dict[str, Any] | None:
+        if not prev.items:
+            return None
+        if prev.total is not None and fetched >= prev.total:
+            return None
+        if prev.next_params:
+            return prev.next_params
+        if len(prev.items) < page_size:
+            return None
+        return self._page_params(fetched // len(prev.items) + 1, page_size)
+
+    def plan(self, first: PageResult, page_size: int) -> list[dict[str, Any]] | None:
+        if first.total is None or not first.items:
+            return None
+        size = len(first.items)
+        last_page = math.ceil(first.total / size)
+        return [self._page_params(page, size) for page in range(2, last_page + 1)]
+
+
+class CursorPagination:
+    """
+    Opaque-cursor paging, where the envelope carries a ``next`` URL and no total.
+
+    Inherently serial: the next cursor is only known once the current page has been fetched.
+
+    Also the right choice for an endpoint that returns a ``next`` URL but documents no page
+    parameter — following the server's own link is safer than guessing one it may ignore.
+
+    :param results_key: Envelope key holding the records.
+    :type results_key: str
+    :param size_param: Name of the page-size parameter. The Iru API is inconsistent here:
+        ``/users`` takes ``sizePerPage`` while ``/tags`` documents none at all.
+    :type size_param: str | None
+    """
+
+    def __init__(self, results_key: str = "results", size_param: str | None = "limit") -> None:
+        self.results_key = results_key
+        self.size_param = size_param
+
+    def first_params(self, page_size: int) -> dict[str, Any]:
+        return {self.size_param: page_size} if self.size_param else {}
+
+    def parse(self, body: Any) -> PageResult:
+        envelope = body if isinstance(body, dict) else {}
+        return PageResult(
+            items=list(envelope.get(self.results_key) or []),
+            next_params=_extract_next_params(envelope),
+            raw=body,
+        )
+
+    def next_params(self, prev: PageResult, page_size: int, fetched: int) -> dict[str, Any] | None:
+        return prev.next_params
+
+    def plan(self, first: PageResult, page_size: int) -> list[dict[str, Any]] | None:
+        return None

irusdk/_core/ratelimit.py

@@ -0,0 +1,81 @@
+"""Client-side rate limiting.
+
+Pure arithmetic with an injectable clock: no locks, no sleeping. The transports wrap this in
+their own lock and sleep with their own primitive, so one implementation serves both.
+"""
+
+SECONDS_PER_HOUR = 3600.0
+
+
+class RateLimitPolicy:
+    """
+    A dual-window limiter covering Iru's per-second and per-hour tenant quotas.
+
+    The per-second window paces requests evenly rather than allowing a burst followed by a stall.
+    The per-hour window is a token bucket that refills continuously.
+
+    :param per_second: Sustained requests per second.
+    :type per_second: float
+    :param per_hour: Requests permitted per rolling hour.
+    :type per_hour: int
+    :param now: The current timestamp, from a monotonic clock.
+    :type now: float
+    """
+
+    def __init__(self, per_second: float, per_hour: int, *, now: float = 0.0) -> None:
+        if per_second <= 0 or per_hour <= 0:
+            raise ValueError("Rate limits must be positive")
+
+        self.per_second = per_second
+        self.per_hour = per_hour
+        self._spacing = 1.0 / per_second
+        self._refill_rate = per_hour / SECONDS_PER_HOUR
+        self._next_slot = now
+        self._hour_tokens = float(per_hour)
+        self._hour_updated = now
+
+    def acquire_at(self, now: float) -> float:
+        """
+        Reserve the next request slot and report when it may be sent.
+
+        Mutates the internal counters, so every call must be followed by an actual request.
+
+        :param now: The current timestamp, from a monotonic clock.
+        :type now: float
+        :return: The timestamp at which the caller may send. May be in the past.
+        :rtype: float
+        """
+        send_at = max(now, self._next_slot, self._hour_available_at(now))
+        self._next_slot = send_at + self._spacing
+        self._spend_hour_token(send_at)
+        return send_at
+
+    def penalize(self, retry_after: float, now: float) -> None:
+        """
+        Stall the whole bucket after a ``429``.
+
+        Applied to the shared limiter rather than the one worker that was rejected, so concurrent
+        workers back off together instead of retrying into the same wall.
+
+        :param retry_after: Seconds the server asked the client to wait.
+        :type retry_after: float
+        :param now: The current timestamp, from a monotonic clock.
+        :type now: float
+        """
+        self._next_slot = max(self._next_slot, now + max(0.0, retry_after))
+
+    def _hour_available_at(self, now: float) -> float:
+        """Earliest timestamp at which the hourly bucket holds a whole token."""
+        tokens = self._tokens_at(now)
+        if tokens >= 1.0:
+            return now
+        return now + (1.0 - tokens) / self._refill_rate
+
+    def _tokens_at(self, now: float) -> float:
+        """Hourly tokens available at ``now``, without committing the refill."""
+        elapsed = max(0.0, now - self._hour_updated)
+        return min(float(self.per_hour), self._hour_tokens + elapsed * self._refill_rate)
+
+    def _spend_hour_token(self, at: float) -> None:
+        self._hour_tokens = max(0.0, self._tokens_at(at) - 1.0)
+        self._hour_updated = at

irusdk/_core/retry.py

@@ -0,0 +1,107 @@
+"""Transport-agnostic retry policy.
+
+The policy decides *how long* to wait; the transports own the sleeping, so the sync and async
+paths share one set of rules.
+"""
+
+import random
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Mapping
+
+# Statuses worth retrying: the tenant quota, and the transient server-side failures.
+RETRYABLE_STATUS = frozenset({429, 500, 502, 503, 504})
+
+
+def parse_retry_after(value: str | None, *, now: float | None = None) -> float | None:
+    """
+    Parse a ``Retry-After`` header, which may be a delay in seconds or an HTTP date.
+
+    :param value: The raw header value.
+    :type value: str | None
+    :param now: Unix timestamp to measure an HTTP-date form against. Defaults to the current time.
+    :type now: float | None
+    :return: Seconds to wait, or ``None`` if the header was absent or unparseable.
+    :rtype: float | None
+    """
+    if not value:
+        return None
+
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        pass
+
+    try:
+        when = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if when is None:
+        return None
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=timezone.utc)
+
+    reference = now if now is not None else datetime.now(timezone.utc).timestamp()
+    return max(0.0, when.timestamp() - reference)
+
+
+class RetryPolicy:
+    """
+    Decides whether and how long to wait before replaying a failed request.
+
+    :param max_retries: Attempts after the initial request.
+    :type max_retries: int
+    :param backoff_factor: Base for the exponential backoff, in seconds.
+    :type backoff_factor: float
+    :param max_backoff: Ceiling on any single wait, in seconds.
+    :type max_backoff: float
+    """
+
+    def __init__(
+        self,
+        max_retries: int = 3,
+        backoff_factor: float = 0.5,
+        max_backoff: float = 60.0,
+    ) -> None:
+        self.max_retries = max_retries
+        self.backoff_factor = backoff_factor
+        self.max_backoff = max_backoff
+
+    def delay_for(
+        self,
+        *,
+        attempt: int,
+        idempotent: bool,
+        status: int | None = None,
+        headers: Mapping[str, str] | None = None,
+        exc: Exception | None = None,
+    ) -> float | None:
+        """
+        Compute the wait before the next attempt.
+
+        :param attempt: How many attempts have already been made, starting at 1.
+        :type attempt: int
+        :param idempotent: Whether the request is safe to replay.
+        :type idempotent: bool
+        :param status: The response status code, if a response was received.
+        :type status: int | None
+        :param headers: The response headers, consulted for ``Retry-After``.
+        :param exc: The transport exception raised, if the request never completed.
+        :type exc: Exception | None
+        :return: Seconds to wait, or ``None`` to give up and raise.
+        :rtype: float | None
+        """
+        if not idempotent or attempt > self.max_retries:
+            return None
+        if status is not None and status not in RETRYABLE_STATUS:
+            return None
+        if status is None and exc is None:
+            return None
+
+        retry_after = parse_retry_after((headers or {}).get("Retry-After"))
+        if retry_after is not None:
+            return min(retry_after, self.max_backoff)
+
+        # Full jitter: spreads a thundering herd of concurrent workers across the window.
+        ceiling = min(self.backoff_factor * (2 ** (attempt - 1)), self.max_backoff)
+        return random.uniform(0.0, ceiling)