fleetpull 0.1.0__py3-none-any.whl

fleetpull/network/classifiers/samsara.py

@@ -0,0 +1,80 @@
+# src/fleetpull/network/classifiers/samsara.py
+"""Samsara response classifier (sources: scrubbed provider-behavior
+verification, June 2026; rate-limit contract from official Samsara
+documentation).
+
+Classification reads status codes and structured fields, never
+human-readable message text; ``detail`` carries messages for humans,
+decisions never read them. Branch logic deliberately resembles sibling
+classifiers without sharing code: provider classifiers evolve
+independently (blast-radius over DRY).
+"""
+
+import json
+from collections.abc import Mapping
+from http import HTTPStatus
+
+from fleetpull.network.contract import (
+    SERVER_ERROR_FLOOR,
+    SUCCESS_STATUS_RANGE,
+    ClassifiedResponse,
+    ResponseClassifier,
+    body_snippet,
+    retry_after_seconds_from_headers,
+)
+from fleetpull.vocabulary import JsonValue, ResponseCategory
+
+__all__: list[str] = ['SamsaraResponseClassifier']
+
+
+def _auth_failure_detail(body_text: str) -> str:
+    """Extract the body's ``message`` when JSON, else a snippet."""
+    try:
+        parsed_body: JsonValue = json.loads(body_text)
+    except json.JSONDecodeError:
+        return body_snippet(body_text)
+    if isinstance(parsed_body, dict):
+        message: JsonValue = parsed_body.get('message')
+        if isinstance(message, str):
+            return message
+    return body_snippet(body_text)
+
+
+class SamsaraResponseClassifier(ResponseClassifier):
+    """Classifies Samsara REST responses (observed shape:
+    ``{"message": "invalid token", "requestId": ...}`` on 401)."""
+
+    def classify_response(
+        self,
+        status_code: int,
+        headers: Mapping[str, str],
+        body_text: str,
+    ) -> ClassifiedResponse:
+        """Classify one Samsara response by status code."""
+        match status_code:
+            case code if code in SUCCESS_STATUS_RANGE:
+                return ClassifiedResponse(category=ResponseCategory.SUCCESS)
+            case HTTPStatus.TOO_MANY_REQUESTS:
+                # Retry-After is documented as fractional seconds
+                # (e.g. 0.40235).
+                return ClassifiedResponse(
+                    category=ResponseCategory.RATE_LIMITED,
+                    retry_after_seconds=retry_after_seconds_from_headers(headers),
+                )
+            case HTTPStatus.UNAUTHORIZED | HTTPStatus.FORBIDDEN:
+                return ClassifiedResponse(
+                    category=ResponseCategory.AUTH_FAILURE,
+                    detail=_auth_failure_detail(body_text),
+                )
+            case code if code >= SERVER_ERROR_FLOOR:
+                # Documented Samsara behavior: 5xx bodies are plain
+                # strings, not JSON — never attempt JSON parsing here.
+                return ClassifiedResponse(
+                    category=ResponseCategory.TRANSIENT,
+                    detail=f'HTTP {status_code}: {body_snippet(body_text)}',
+                )
+            case _:
+                return ClassifiedResponse(
+                    category=ResponseCategory.FATAL,
+                    detail=f'HTTP {status_code}: {body_snippet(body_text)}',
+                )

fleetpull/network/client/__init__.py

@@ -0,0 +1,25 @@
+# src/fleetpull/network/client/__init__.py
+"""The transport client face: the assembled HTTP fetch loop and its inputs.
+
+``TransportClient`` runs the per-attempt pipeline and page loop against a
+per-provider ``ProviderProfile`` (auth + classifier) and a process-global
+``ClientRuntime`` (configs, limiter registry, jitter, sleeper), emitting
+``FetchedPage`` objects. ``ProviderClientRegistry`` owns one open client per
+provider, keyed by ``Provider``, and hands the right one to the run executor.
+External callers import these names here."""
+
+from fleetpull.network.client.page import FetchedPage
+from fleetpull.network.client.profile import ProviderProfile
+from fleetpull.network.client.registry import ProviderClientRegistry
+from fleetpull.network.client.registry_base import ProviderResourceRegistry
+from fleetpull.network.client.runtime import ClientRuntime
+from fleetpull.network.client.transport import TransportClient
+
+__all__: list[str] = [
+    'ClientRuntime',
+    'FetchedPage',
+    'ProviderClientRegistry',
+    'ProviderProfile',
+    'ProviderResourceRegistry',
+    'TransportClient',
+]

fleetpull/network/client/page.py

@@ -0,0 +1,32 @@
+# src/fleetpull/network/client/page.py
+"""The client's emit type: one page of records plus resume progress."""
+
+from dataclasses import dataclass
+
+from fleetpull.vocabulary import JsonObject
+
+__all__: list[str] = ['FetchedPage']
+
+
+@dataclass(frozen=True, slots=True)
+class FetchedPage:
+    """
+    One page emitted by the transport client: its records and the opaque
+    resume cursor.
+
+    The records are the page decoder's wire-shape extraction — a list of JSON
+    objects, validated as record-bearing but not yet validated into the
+    per-record response model (that is the records layer's job). Attempt counts
+    and timings are not here until a consumer demands them — the client is
+    state-blind.
+
+    Attributes:
+        records: The page's records, each a JSON object, as extracted by the
+            endpoint's page decoder. Per-record model validation is downstream.
+        durable_progress: Opaque resume cursor that must outlive the fetch
+            (GeoTab ``toVersion``), or None for fetch-private cursors
+            (Motive, Samsara). The orchestrator owns its interpretation.
+    """
+
+    records: list[JsonObject]
+    durable_progress: str | None

fleetpull/network/client/profile.py

@@ -0,0 +1,27 @@
+# src/fleetpull/network/client/profile.py
+"""The per-provider strategy bundle the client receives at construction."""
+
+from dataclasses import dataclass
+
+from fleetpull.network.contract import AuthStrategy, ResponseClassifier
+
+__all__: list[str] = ['ProviderProfile']
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderProfile:
+    """
+    The per-provider, per-construction dependencies of a transport client.
+
+    Auth strategy and classifier are shared across all of a provider's
+    endpoints (one session auth, one classifier). The page decoder and
+    quota scope are deliberately NOT here — they are per-endpoint and arrive
+    on each ``fetch_pages`` call.
+
+    Attributes:
+        auth: Credential injection for this provider.
+        classifier: Response and transport classification for this provider.
+    """
+
+    auth: AuthStrategy
+    classifier: ResponseClassifier

fleetpull/network/client/registry.py

@@ -0,0 +1,103 @@
+# src/fleetpull/network/client/registry.py
+"""Provider-keyed registry of transport clients: one open pool per provider.
+
+The seam between endpoint execution and provider transport identity. A
+``TransportClient`` is provider-scoped (it carries a provider's ``ProviderProfile``
+and owns that provider's pooled ``httpx.Client``); an endpoint run is
+endpoint-scoped. This registry lets the run executor ask for the client of
+``definition.provider`` without owning a single client or pretending one client can
+authenticate every provider. It owns the clients' lifecycle -- open every configured
+provider's client on enter, close every pool on exit -- and nothing else; it builds
+no profiles and reads no credentials, which is the composition root's job. The
+lifecycle machinery itself (publish-on-success enter, closed-before-release
+exit, the RuntimeError-vs-ConfigurationError lookup split) is the generic
+``ProviderResourceRegistry``'s (``registry_base.py``); this subclass supplies
+client construction and the error nouns.
+
+The one shared ``ClientRuntime`` passed to every client is what keeps cross-provider
+quota enforced: every page attempt routes through that runtime's single
+``RateLimiterRegistry`` (DESIGN §7, §14).
+"""
+
+from collections.abc import Mapping
+from contextlib import ExitStack
+from typing import ClassVar
+
+from fleetpull.network.client.profile import ProviderProfile
+from fleetpull.network.client.registry_base import ProviderResourceRegistry
+from fleetpull.network.client.runtime import ClientRuntime
+from fleetpull.network.client.transport import TransportClient
+from fleetpull.vocabulary import Provider
+
+__all__: list[str] = ['ProviderClientRegistry']
+
+
+class ProviderClientRegistry(ProviderResourceRegistry[TransportClient]):
+    """Owns one open ``TransportClient`` per provider, keyed by ``Provider``.
+
+    A resource-owning context manager (the generic base's semantics).
+    ``client_for`` returns a provider's client; use it only inside the
+    ``with`` block::
+
+        with ProviderClientRegistry(profiles, runtime) as clients:
+            client = clients.client_for(definition.provider)
+    """
+
+    _resource_noun: ClassVar[str] = 'transport client'
+    _lookup_description: ClassVar[str] = 'client_for'
+
+    def __init__(
+        self,
+        profiles: Mapping[Provider, ProviderProfile],
+        runtime: ClientRuntime,
+    ) -> None:
+        """
+        Args:
+            profiles: The per-provider auth/classifier bundle for each configured
+                provider. A provider absent here has no client and is rejected by
+                ``client_for`` while the registry is open.
+            runtime: The one process-global transport runtime shared by every
+                client (its limiter registry enforces cross-provider quota).
+
+        Side Effects:
+            None -- clients are opened on ``__enter__``, not here.
+        """
+        super().__init__(profiles)
+        self._profiles: dict[Provider, ProviderProfile] = dict(profiles)
+        self._runtime: ClientRuntime = runtime
+
+    def _open_resource(self, stack: ExitStack, provider: Provider) -> TransportClient:
+        """Open one provider's transport client (its pooled ``httpx.Client``).
+
+        Args:
+            stack: The enter's unwind stack; the client's pool close registers
+                here.
+            provider: The provider whose client to open.
+
+        Returns:
+            The provider's open ``TransportClient``.
+
+        Side Effects:
+            Constructs one pooled ``httpx.Client``.
+        """
+        return stack.enter_context(
+            TransportClient(self._profiles[provider], self._runtime)
+        )
+
+    def client_for(self, provider: Provider) -> TransportClient:
+        """Return the transport client for a provider.
+
+        Args:
+            provider: The provider whose client to return (e.g.
+                ``definition.provider``).
+
+        Returns:
+            The provider's open ``TransportClient``.
+
+        Raises:
+            RuntimeError: The registry is not open -- ``client_for`` was called
+                outside an active ``with`` block (a caller bug).
+            ConfigurationError: The registry is open but the provider has no
+                configured client.
+        """
+        return self._resource_for(provider)

fleetpull/network/client/registry_base.py

@@ -0,0 +1,150 @@
+# src/fleetpull/network/client/registry_base.py
+"""The generic provider-keyed resource registry the concrete registries subclass.
+
+One resource per provider, owned as a context manager: the publish-on-success
+enter (resources built off to the side on an ``ExitStack`` and assigned only
+after every provider's opened, so a mid-open failure unwinds what opened and
+leaves the registry unentered), the closed-before-release exit (the instance
+is marked closed before the stack unwinds, so a close error still leaves the
+registry unusable rather than apparently-open), and the two-way lookup split
+-- ``RuntimeError`` for a lookup outside the ``with`` block (a caller bug),
+``ConfigurationError`` for an unconfigured provider while open -- are each
+stated once here. ``ProviderClientRegistry`` (transport clients) and the
+orchestrator's ``FetchPoolRegistry`` (fetch worker pools) are thin
+subclasses supplying construction and the error nouns.
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+from contextlib import ExitStack
+from types import TracebackType
+from typing import ClassVar, Self
+
+from fleetpull.exceptions import ConfigurationError
+from fleetpull.vocabulary import Provider
+
+__all__: list[str] = ['ProviderResourceRegistry']
+
+
+class ProviderResourceRegistry[ResourceT](ABC):
+    """Owns one open resource per provider, keyed by ``Provider``.
+
+    A resource-owning context manager: ``__enter__`` opens every configured
+    provider's resource and returns self; ``__exit__`` releases them all.
+    Subclasses bind the vocabulary (``_resource_noun`` for the unconfigured-
+    provider error, ``_lookup_description`` for the not-open error), open one
+    provider's resource in ``_open_resource``, and expose their named lookup
+    over ``_resource_for``.
+
+    Attributes:
+        _resource_noun: The resource's error noun (e.g. ``'transport
+            client'``), completing ``'no <noun> configured for provider'``.
+        _lookup_description: The public lookup method's name (e.g.
+            ``'client_for'``), naming the misuse in the not-open error.
+    """
+
+    _resource_noun: ClassVar[str]
+    _lookup_description: ClassVar[str]
+
+    def __init__(self, providers: Iterable[Provider]) -> None:
+        """
+        Args:
+            providers: The providers to open a resource for on ``__enter__``.
+                A provider absent here has no resource and is rejected by the
+                lookup while the registry is open.
+
+        Side Effects:
+            None -- resources are opened on ``__enter__``, not here.
+        """
+        self._providers: tuple[Provider, ...] = tuple(providers)
+        self._resources: dict[Provider, ResourceT] = {}
+        self._stack: ExitStack = ExitStack()
+        self._open: bool = False
+
+    @abstractmethod
+    def _open_resource(self, stack: ExitStack, provider: Provider) -> ResourceT:
+        """Open one provider's resource, registering its release on ``stack``.
+
+        Args:
+            stack: The enter's unwind stack; register whatever must release
+                on exit (or on a later provider's open failure) here.
+            provider: The provider whose resource to open.
+
+        Returns:
+            The opened resource.
+        """
+        ...
+
+    def __enter__(self) -> Self:
+        """Open one resource per configured provider; publish only on full success.
+
+        Builds the provider-to-resource map in a local dict and assigns it to
+        the instance only after every resource has opened, so a mid-open
+        failure unwinds the resources already opened and leaves the registry
+        unentered (``_resources`` untouched, ``_open`` false).
+
+        Side Effects:
+            Opens one resource per provider via ``_open_resource``. On a later
+            open failure, the earlier resources are released before
+            propagating.
+        """
+        resources: dict[Provider, ResourceT] = {}
+        with ExitStack() as stack:
+            for provider in self._providers:
+                resources[provider] = self._open_resource(stack, provider)
+            self._stack = stack.pop_all()
+        self._resources = resources
+        self._open = True
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> bool:
+        """Release every provider's resource, forwarding the exit context.
+
+        Forwards ``exc_*`` to the owned ``ExitStack`` so each resource's
+        ``__exit__`` receives the exit context and the suppression decision
+        passes through. The instance is marked closed before the resources
+        are released, so a release error still leaves the registry unusable
+        rather than apparently-open.
+
+        Side Effects:
+            Releases every resource opened in ``__enter__``.
+        """
+        self._open = False
+        self._resources = {}
+        return bool(self._stack.__exit__(exc_type, exc_value, traceback))
+
+    def _resource_for(self, provider: Provider) -> ResourceT:
+        """Return the provider's open resource -- the shared lookup body.
+
+        Args:
+            provider: The provider whose resource to return.
+
+        Returns:
+            The provider's open resource.
+
+        Raises:
+            RuntimeError: The registry is not open -- the lookup was called
+                outside an active ``with`` block (a caller bug), kept distinct
+                from a genuinely unconfigured provider.
+            ConfigurationError: The registry is open but the provider has no
+                configured resource.
+        """
+        if not self._open:
+            raise RuntimeError(
+                f'{type(self).__name__} is not open; call '
+                f'{self._lookup_description} inside its `with` block'
+            )
+        resource = self._resources.get(provider)
+        if resource is None:
+            configured = ', '.join(sorted(p.value for p in self._resources)) or 'none'
+            raise ConfigurationError(
+                f'no {self._resource_noun} configured for provider',
+                provider=provider.value,
+                detail=f'configured providers: {configured}',
+            )
+        return resource

fleetpull/network/client/runtime.py

@@ -0,0 +1,44 @@
+# src/fleetpull/network/client/runtime.py
+"""Process-global transport infrastructure, shared by every provider's client."""
+
+import random
+from dataclasses import dataclass, field
+
+from fleetpull.config import HttpConfig, RetryConfig
+from fleetpull.network.limits import RateLimiterRegistry
+from fleetpull.network.retry import RandomFractionGenerator
+from fleetpull.timing import Sleeper, SystemSleeper
+
+__all__: list[str] = ['ClientRuntime']
+
+
+@dataclass(frozen=True, slots=True)
+class ClientRuntime:
+    """
+    The process-global dependencies a transport client runs against.
+
+    Built once per composition root and shared across every per-provider
+    client that root constructs — only the ``ProviderProfile`` varies per
+    provider. Bundled because these always travel together at the sites
+    that construct clients, and no module-level singletons are permitted.
+
+    Attributes:
+        http_config: Connect/read timeouts and TLS posture (consumed once to
+            build the client's connection pool).
+        retry_config: Per-category failure budgets, backoff shape, fallback
+            penalty.
+        limiter_registry: Shared rate limiters, keyed by quota scope.
+        random_source: Jitter seam for retry backoff. Defaults to the
+            production ``random.Random``; injectable so tests make every
+            jittered delay exact arithmetic. No composition root needs to
+            know the seam exists.
+        sleeper: Sleep seam for TRANSIENT backoff. Defaults to the
+            production ``SystemSleeper``; injectable so tests record delays
+            instead of waiting. Same stance as ``random_source``.
+    """
+
+    http_config: HttpConfig
+    retry_config: RetryConfig
+    limiter_registry: RateLimiterRegistry
+    random_source: RandomFractionGenerator = field(default_factory=random.Random)
+    sleeper: Sleeper = field(default_factory=SystemSleeper)