fleetpull 0.1.0__py3-none-any.whl

fleetpull/network/auth/manager.py

@@ -0,0 +1,223 @@
+# src/fleetpull/network/auth/manager.py
+"""GeoTab session lifecycle manager.
+
+GeoTab authenticates by session: an ``Authenticate`` call returns a
+session id and a resolved host; the session lives ~14 days but can die
+early (password change; a 100-concurrent-session LRU cap per account).
+This module is pure state and thread choreography — it knows nothing
+about HTTP. The actual ``Authenticate`` call is injected as
+``authenticate_fn``; in production that implementation is an HTTP
+attempt and passes through the rate limiter like any other
+(token-per-attempt has no exceptions).
+
+Sessions are never persisted to disk — a deliberate non-goal. A session
+id is a bearer-equivalent secret, and at one process per scheduled run,
+in-memory sessions stay far below GeoTab's 100-session cap.
+"""
+
+import logging
+import threading
+from collections.abc import Callable
+from datetime import datetime, timedelta
+from typing import Final
+
+from fleetpull.config import GeotabAuthConfig
+from fleetpull.network.auth.models import AuthenticationResult, GeotabSession
+from fleetpull.timing import Clock, SystemClock
+
+__all__: list[str] = ['GeotabSessionManager']
+
+logger = logging.getLogger(__name__)
+
+# Documented GeoTab policy, not a server-returned contract — there is no
+# expires_in in the Authenticate response, and the docs reserve the
+# right to change the lifetime.
+_SESSION_LIFETIME: Final[timedelta] = timedelta(days=14)
+
+# Proactive refresh threshold. Generous (a day, not seconds) because the
+# lifetime is assumed, not negotiated: refreshing early costs one
+# Authenticate call; trusting an assumed lifetime to the minute risks a
+# mid-run failure.
+_REFRESH_MARGIN: Final[timedelta] = timedelta(days=1)
+
+
+class GeotabSessionManager:
+    """
+    Single-flight GeoTab session cache: one session per process, shared
+    by all threads.
+
+    Reactive invalidation (a caller reports a server-rejected session
+    via :meth:`invalidate`) is the primary mechanism; proactive refresh
+    near the assumed lifetime is insurance. A generation counter guards
+    against invalidation stampedes: ten workers hitting expiry
+    simultaneously produce one ``Authenticate`` call, not ten.
+
+    The lock is deliberately held across the ``authenticate_fn`` call.
+    That is the single-flight design: concurrent callers needing a
+    refresh block on the lock and receive the just-refreshed session
+    when they acquire it. This is the opposite of the SQLite
+    never-hold-a-transaction-across-HTTP rule, and the difference is
+    the point — do not "fix" it.
+
+    This class never logs ``session_id`` and never touches
+    ``config.password``; only ``authenticate_fn`` reads the secret.
+    """
+
+    def __init__(
+        self,
+        config: GeotabAuthConfig,
+        authenticate_fn: Callable[[GeotabAuthConfig], AuthenticationResult],
+        clock: Clock = SystemClock(),  # noqa: B008 — SystemClock is frozen and stateless; one shared default instance is intentional
+    ) -> None:
+        """
+        Initialize the manager with no cached session.
+
+        Args:
+            config: Validated GeoTab authentication configuration.
+            authenticate_fn: Performs the actual ``Authenticate`` call
+                and resolves the returned host. Injected so the manager
+                stays pure state and choreography (the real
+                implementation in ``network/auth/authenticate.py`` is the
+                one place httpx is imported); in tests it is a stub.
+            clock: Time source; injected so tests can be deterministic.
+        """
+        self._config: GeotabAuthConfig = config
+        self._authenticate_fn: Callable[[GeotabAuthConfig], AuthenticationResult] = (
+            authenticate_fn
+        )
+        self._clock: Clock = clock
+        self._lock: threading.Lock = threading.Lock()
+        self._current_session: GeotabSession | None = None
+        self._generation_counter: int = 0
+
+    def get_session(self) -> GeotabSession:
+        """
+        Return a usable session, authenticating or refreshing as needed.
+
+        Returns:
+            The cached session, or a freshly authenticated one when no
+            session exists yet or the cached session has crossed the
+            proactive refresh threshold.
+
+        Raises:
+            AuthenticationError: Bad credentials (from the real
+                ``authenticate_fn``).
+            ProviderResponseError: A malformed or non-200 Authenticate
+                response.
+            UnknownQuotaScopeError: The Authenticate quota scope is
+                unconfigured.
+            httpx.TransportError: A transport failure during
+                authentication. Cached state is untouched on any raise.
+
+        Side Effects:
+            May call ``authenticate_fn`` (blocking other threads on the
+            internal lock for the duration) and replace the cached
+            session.
+        """
+        with self._lock:
+            if self._current_session is None:
+                logger.debug('No GeoTab session cached; initial authentication.')
+                return self._refresh_holding_lock()
+
+            now_utc: datetime = self._clock.now_utc()
+            refresh_due_at: datetime = self._current_session.acquired_at_utc + (
+                _SESSION_LIFETIME - _REFRESH_MARGIN
+            )
+            # Inclusive >= so the boundary instant refreshes rather than
+            # living in an untestable gap.
+            if now_utc >= refresh_due_at:
+                session_age: timedelta = now_utc - self._current_session.acquired_at_utc
+                logger.debug(
+                    'GeoTab session past proactive refresh threshold '
+                    '(age %s); refreshing.',
+                    session_age,
+                )
+                return self._refresh_holding_lock()
+
+            logger.debug(
+                'GeoTab session cache hit (generation %d).',
+                self._current_session.generation,
+            )
+            return self._current_session
+
+    def invalidate(self, stale_session: GeotabSession) -> GeotabSession:
+        """
+        Report a server-rejected session and receive a replacement.
+
+        Called by a caller whose request failed with a session-invalid
+        error. If another thread already refreshed since the caller read
+        its session (the reported generation is older than the current
+        one), the current session is returned without authenticating —
+        the single-flight stampede guard.
+
+        Args:
+            stale_session: The session the server rejected.
+
+        Returns:
+            The current session: freshly authenticated, or the newer
+            one another thread already obtained.
+
+        Raises:
+            AuthenticationError: Bad credentials (from the real
+                ``authenticate_fn``).
+            ProviderResponseError: A malformed or non-200 Authenticate
+                response.
+            UnknownQuotaScopeError: The Authenticate quota scope is
+                unconfigured.
+            httpx.TransportError: A transport failure during
+                authentication. Cached state is untouched on any raise.
+
+        Side Effects:
+            May call ``authenticate_fn`` and replace the cached
+            session. Logs a WARNING when the current session was
+            genuinely rejected (it died before its assumed lifetime).
+        """
+        with self._lock:
+            current_session: GeotabSession | None = self._current_session
+            if (
+                current_session is not None
+                and stale_session.generation < current_session.generation
+            ):
+                logger.debug(
+                    'Stale invalidation for generation %d; current '
+                    'generation %d is already newer.',
+                    stale_session.generation,
+                    current_session.generation,
+                )
+                return current_session
+
+            # The reported session IS current and the server rejected it:
+            # it died before its assumed lifetime — password change or
+            # LRU eviction, something that happened outside this process.
+            logger.warning(
+                'GeoTab session (generation %d) rejected by the server '
+                'before its assumed lifetime; re-authenticating.',
+                stale_session.generation,
+            )
+            return self._refresh_holding_lock()
+
+    def _refresh_holding_lock(self) -> GeotabSession:
+        """
+        Authenticate and replace the cached session. Caller holds the lock.
+
+        ``issued_at`` is read BEFORE calling ``authenticate_fn`` —
+        pessimistic timestamping, so network latency counts against the
+        session lifetime rather than silently extending it. If
+        ``authenticate_fn`` raises, cached state is untouched and the
+        exception propagates.
+        """
+        issued_at: datetime = self._clock.now_utc()
+        authentication_result: AuthenticationResult = self._authenticate_fn(
+            self._config
+        )
+        self._generation_counter += 1
+        new_session = GeotabSession(
+            session_id=authentication_result.session_id,
+            resolved_host=authentication_result.resolved_host,
+            database=self._config.database,
+            username=self._config.username,
+            generation=self._generation_counter,
+            acquired_at_utc=issued_at,
+        )
+        self._current_session = new_session
+        return new_session

fleetpull/network/auth/models.py

@@ -0,0 +1,57 @@
+# src/fleetpull/network/auth/models.py
+"""Runtime session state for GeoTab authentication.
+
+Internal runtime state, not user YAML — hence frozen dataclasses rather
+than Pydantic models. Pure data: assembling request credentials from a
+session is the auth strategy's job, so nothing here knows JSON-RPC
+payload shapes.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+
+__all__: list[str] = ['AuthenticationResult', 'GeotabSession']
+
+
+@dataclass(frozen=True, slots=True)
+class AuthenticationResult:
+    """
+    What an ``authenticate_fn`` returns to the session manager.
+
+    GeoTab's ``Authenticate`` returns either a server path or the
+    literal ``'ThisServer'``; RESOLVING that to a concrete host is the
+    ``authenticate_fn``'s job (it knows which host it called), so by the
+    time a result reaches the manager, ``resolved_host`` is always a
+    real host.
+
+    Attributes:
+        session_id: The session credential returned by ``Authenticate``.
+        resolved_host: The host all subsequent API calls must target.
+    """
+
+    session_id: str
+    resolved_host: str
+
+
+@dataclass(frozen=True, slots=True)
+class GeotabSession:
+    """
+    The session the manager hands to callers.
+
+    Attributes:
+        session_id: The session credential for request payloads.
+        resolved_host: The host all subsequent API calls must target.
+        database: GeoTab database name, carried from config.
+        username: GeoTab username, carried from config.
+        generation: Monotonically increasing per manager instance; the
+            single-flight staleness check compares generations.
+        acquired_at_utc: When authentication was initiated, from the
+            injected clock's ``now_utc()``.
+    """
+
+    session_id: str
+    resolved_host: str
+    database: str
+    username: str
+    generation: int
+    acquired_at_utc: datetime

fleetpull/network/auth/strategies.py

@@ -0,0 +1,169 @@
+# src/fleetpull/network/auth/strategies.py
+"""The ``AuthStrategy`` implementations, beside the session manager.
+
+``StaticHeaderAuth`` (Motive/Samsara static keys) and
+``GeotabSessionAuth`` (GeoTab sessions) implement the ``AuthStrategy``
+protocol declared in ``network/contract/auth.py``. They live here, in
+``network/auth/``, because ``GeotabSessionAuth`` wraps the
+``GeotabSessionManager`` it sits beside — keeping the implementations
+out of the contract surface is what lets the surface stay free of any
+``network/auth`` dependency.
+
+Provider names appear only at the composition root that constructs
+strategies; the client and everything downstream is provider-blind.
+"""
+
+import threading
+from collections.abc import Mapping
+from dataclasses import replace
+from urllib.parse import urlsplit, urlunsplit
+
+from pydantic import SecretStr
+
+from fleetpull.network.auth.manager import GeotabSessionManager
+from fleetpull.network.auth.models import GeotabSession
+from fleetpull.network.contract import RequestSpec
+from fleetpull.vocabulary import JsonValue
+
+__all__: list[str] = ['GeotabSessionAuth', 'StaticHeaderAuth']
+
+
+class StaticHeaderAuth:
+    """
+    Static API-key auth for Motive and Samsara.
+
+    The composition root pre-formats the header value (e.g.
+    ``'Bearer <token>'`` for Samsara) before wrapping it in
+    ``SecretStr``; the secret is extracted only at the moment of use.
+    """
+
+    def __init__(self, header_name: str, header_value: SecretStr) -> None:
+        """
+        Args:
+            header_name: The header carrying the credential.
+            header_value: The pre-formatted credential value.
+        """
+        self._header_name: str = header_name
+        self._header_value: SecretStr = header_value
+
+    def prepare(self, spec: RequestSpec) -> RequestSpec:
+        """Return a new spec with the credential header injected."""
+        return spec.with_extra_headers(
+            {self._header_name: self._header_value.get_secret_value()}
+        )
+
+    def on_auth_failure(self) -> bool:
+        """A rejected static key cannot be fixed by retrying."""
+        return False
+
+
+class _ThreadLocalSession(threading.local):
+    """Per-thread slot for the last session injected by prepare()."""
+
+    last_prepared: GeotabSession | None = None
+
+
+class GeotabSessionAuth:
+    """
+    Session auth for GeoTab: marries the session manager to the
+    ``AuthStrategy`` protocol.
+
+    The last-prepared session lives in a ``threading.local`` slot
+    because the strategy instance is shared across worker threads.
+    prepare → send → on_auth_failure always executes within one thread,
+    but a plain instance attribute would let thread A's failure
+    invalidate the fresher session thread B just prepared with,
+    triggering a spurious refresh. The thread-local pins each failure
+    to the session that actually failed.
+    """
+
+    def __init__(self, manager: GeotabSessionManager) -> None:
+        """
+        Args:
+            manager: The single-flight session manager for this account.
+        """
+        self._manager: GeotabSessionManager = manager
+        self._thread_local: _ThreadLocalSession = _ThreadLocalSession()
+
+    def prepare(self, spec: RequestSpec) -> RequestSpec:
+        """
+        Inject session credentials into the JSON-RPC body and retarget
+        the URL to the session's resolved host.
+
+        Args:
+            spec: A GeoTab JSON-RPC request spec; ``json_body`` is
+                required.
+
+        Returns:
+            A new spec whose body carries ``params.credentials`` and
+            whose URL host is the session's resolved host (scheme,
+            path, and query untouched). The input spec and its body
+            are never mutated.
+
+        Raises:
+            ValueError: If ``spec.json_body`` is None (every GeoTab
+                request is a JSON-RPC POST with a body), or if the
+                body's ``params`` exists but is not a mapping — both
+                are programming errors in the endpoint layer.
+        """
+        # Validate before the session fetch: a body-less spec is a
+        # programming error and must not trigger a real Authenticate
+        # call (which would burn sessions against GeoTab's LRU cap).
+        if spec.json_body is None:
+            raise ValueError(
+                'GeoTab requests require a JSON-RPC body; '
+                'a body-less spec reaching GeoTab auth is a programming error'
+            )
+        session: GeotabSession = self._manager.get_session()
+
+        # The strategy is the sole authority on credentials: an existing
+        # 'credentials' key left by a caller is overwritten, never kept.
+        credentials: dict[str, JsonValue] = {
+            'database': session.database,
+            'sessionId': session.session_id,
+            'userName': session.username,
+        }
+        if 'params' not in spec.json_body:
+            # Some JSON-RPC methods are parameterless apart from credentials.
+            new_params: dict[str, JsonValue] = {'credentials': credentials}
+        else:
+            existing_params: JsonValue = spec.json_body['params']
+            if not isinstance(existing_params, Mapping):
+                raise ValueError(
+                    f"json_body['params'] must be a mapping, "
+                    f'got {type(existing_params).__name__}'
+                )
+            new_params = {**existing_params, 'credentials': credentials}
+        new_body: dict[str, JsonValue] = {**spec.json_body, 'params': new_params}
+
+        # Authenticate may have redirected the session to a different
+        # server; every subsequent call must target it.
+        url_parts = urlsplit(spec.url)
+        retargeted_url: str = urlunsplit(
+            url_parts._replace(netloc=session.resolved_host)
+        )
+
+        self._thread_local.last_prepared = session
+        return replace(spec, url=retargeted_url, json_body=new_body)
+
+    def on_auth_failure(self) -> bool:
+        """
+        Invalidate the session this thread last prepared with; one
+        retry is worthwhile because fresh credentials are now cached.
+
+        Returns:
+            True, always — the session manager guarantees a usable
+            replacement (or raises trying).
+
+        Raises:
+            RuntimeError: If no session was ever prepared on this
+                thread — on_auth_failure without a prior prepare is a
+                client-logic bug.
+        """
+        failed_session: GeotabSession | None = self._thread_local.last_prepared
+        if failed_session is None:
+            raise RuntimeError(
+                'on_auth_failure called before any prepare on this thread'
+            )
+        self._manager.invalidate(failed_session)
+        return True

fleetpull/network/classifiers/__init__.py

@@ -0,0 +1,11 @@
+"""Per-provider response classifiers."""
+
+from fleetpull.network.classifiers.geotab import GeotabResponseClassifier
+from fleetpull.network.classifiers.motive import MotiveResponseClassifier
+from fleetpull.network.classifiers.samsara import SamsaraResponseClassifier
+
+__all__: list[str] = [
+    'GeotabResponseClassifier',
+    'MotiveResponseClassifier',
+    'SamsaraResponseClassifier',
+]

fleetpull/network/classifiers/geotab.py

@@ -0,0 +1,145 @@
+# src/fleetpull/network/classifiers/geotab.py
+"""GeoTab response classifier (sources: scrubbed provider-behavior
+verification, June 2026).
+
+GeoTab is JSON-RPC: every application-level failure arrives inside
+HTTP 200, so this classifier is envelope-driven — a status-code-only
+client cannot see failure. The discriminator is ``error.data.type``
+(observed present in every captured failure); classification never
+reads human-readable message text. ``detail`` carries
+``error['message']`` for humans, decisions never read it. 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 fleetpull.network.contract import (
+    SERVER_ERROR_FLOOR,
+    ClassifiedResponse,
+    ResponseClassifier,
+    body_snippet,
+    retry_after_seconds_from_headers,
+)
+from fleetpull.vocabulary import JsonValue, ResponseCategory
+
+__all__: list[str] = ['GeotabResponseClassifier']
+
+
+def _detail_with_message(prefix: str, error_message: str | None) -> str:
+    """Append the envelope's human-readable message when present."""
+    if error_message is None:
+        return prefix
+    return f'{prefix} ({error_message})'
+
+
+def _classify_error_envelope(
+    error_envelope: JsonValue, headers: Mapping[str, str]
+) -> ClassifiedResponse:
+    """Classify a JSON-RPC ``error`` member by ``data.type``."""
+    error_message: str | None = None
+    error_type: str | None = None
+    if isinstance(error_envelope, dict):
+        message_value: JsonValue = error_envelope.get('message')
+        if isinstance(message_value, str):
+            error_message = message_value
+        data_value: JsonValue = error_envelope.get('data')
+        if isinstance(data_value, dict):
+            type_value: JsonValue = data_value.get('type')
+            if isinstance(type_value, str):
+                error_type = type_value
+
+    if error_type is None:
+        return ClassifiedResponse(
+            category=ResponseCategory.FATAL,
+            detail=_detail_with_message(
+                'malformed GeoTab error envelope: missing data.type',
+                error_message,
+            ),
+        )
+
+    match error_type:
+        case 'OverLimitException':
+            return ClassifiedResponse(
+                category=ResponseCategory.RATE_LIMITED,
+                retry_after_seconds=retry_after_seconds_from_headers(headers),
+                detail=error_message,
+            )
+        case 'InvalidUserException':
+            # Captured June 2026: bad credentials and dead sessions BOTH
+            # produce InvalidUserException, distinguished only by message
+            # text, which we never match on. Disambiguation is contextual
+            # and already structural: on a data call the auth strategy
+            # invalidates and retries once; on the Authenticate call
+            # itself the failure propagates out of the session manager
+            # as fatal.
+            return ClassifiedResponse(
+                category=ResponseCategory.AUTH_FAILURE,
+                detail=error_message,
+            )
+        case 'DbUnavailableException':
+            # Documented GeoTab transient.
+            return ClassifiedResponse(
+                category=ResponseCategory.TRANSIENT,
+                detail=error_message,
+            )
+        case _:
+            # Fail loud on exception types we have never met rather
+            # than guessing they are retryable.
+            return ClassifiedResponse(
+                category=ResponseCategory.FATAL,
+                detail=_detail_with_message(
+                    f'unrecognized GeoTab exception type: {error_type}',
+                    error_message,
+                ),
+            )
+
+
+class GeotabResponseClassifier(ResponseClassifier):
+    """Classifies GeoTab JSON-RPC responses by envelope inspection."""
+
+    def classify_response(
+        self,
+        status_code: int,
+        headers: Mapping[str, str],
+        body_text: str,
+    ) -> ClassifiedResponse:
+        """Classify one GeoTab response: status first, then envelope."""
+        if status_code >= SERVER_ERROR_FLOOR:
+            # Infrastructure ahead of the API; no body parsing needed.
+            return ClassifiedResponse(
+                category=ResponseCategory.TRANSIENT,
+                detail=f'HTTP {status_code}: {body_snippet(body_text)}',
+            )
+
+        try:
+            parsed_body: JsonValue = json.loads(body_text)
+        except json.JSONDecodeError:
+            # Exactly what the load balancer's HTML error pages look
+            # like from here.
+            return ClassifiedResponse(
+                category=ResponseCategory.FATAL,
+                detail=(
+                    f'HTTP {status_code}: unparseable (non-JSON) body: '
+                    f'{body_snippet(body_text)}'
+                ),
+            )
+
+        if isinstance(parsed_body, dict):
+            if 'error' in parsed_body:
+                return _classify_error_envelope(parsed_body['error'], headers)
+            if 'result' in parsed_body:
+                # The parse already paid for classification is handed
+                # forward; the client must not parse the body again.
+                return ClassifiedResponse(
+                    category=ResponseCategory.SUCCESS, parsed_body=parsed_body
+                )
+
+        return ClassifiedResponse(
+            category=ResponseCategory.FATAL,
+            detail=(
+                'malformed GeoTab JSON-RPC envelope: neither result nor '
+                f'error present: {body_snippet(body_text)}'
+            ),
+        )

fleetpull/network/classifiers/motive.py

@@ -0,0 +1,79 @@
+# src/fleetpull/network/classifiers/motive.py
+"""Motive response classifier (sources: scrubbed provider-behavior
+verification, June 2026; rate limiting probed and never observed —
+generic HTTP posture).
+
+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] = ['MotiveResponseClassifier']
+
+
+def _auth_failure_detail(body_text: str) -> str:
+    """Extract the body's ``error_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):
+        error_message: JsonValue = parsed_body.get('error_message')
+        if isinstance(error_message, str):
+            return error_message
+    return body_snippet(body_text)
+
+
+class MotiveResponseClassifier(ResponseClassifier):
+    """Classifies Motive REST responses (observed shape:
+    ``{"error_message": "invalid API key"}`` on 401)."""
+
+    def classify_response(
+        self,
+        status_code: int,
+        headers: Mapping[str, str],
+        body_text: str,
+    ) -> ClassifiedResponse:
+        """Classify one Motive 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:
+                # Motive rate limiting was probed and never observed
+                # (June 2026); this branch is built to the generic HTTP
+                # contract.
+                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:
+                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)}',
+                )