fleetpull 0.1.0__py3-none-any.whl

fleetpull/network/contract/envelope_fetcher.py

@@ -0,0 +1,33 @@
+# src/fleetpull/network/contract/envelope_fetcher.py
+"""The single-request fetch surface: one spec in, one parsed envelope out.
+
+The contract-layer face of ``TransportClient.fetch_envelope`` — the
+non-paging single request that still rides the whole per-attempt pipeline
+(auth prepare, one limiter token per attempt, retry, classification).
+Declared here so declaration-layer consumers (the ``CompletenessCheck``
+protocol's implementations foremost) can type against the surface without
+importing the client package; ``TransportClient`` satisfies it structurally.
+"""
+
+from typing import Protocol
+
+from fleetpull.network.contract.request import RequestSpec
+from fleetpull.vocabulary import JsonValue
+
+__all__: list[str] = ['EnvelopeFetcher']
+
+
+class EnvelopeFetcher(Protocol):
+    """The one-method single-request surface (``TransportClient``'s shape)."""
+
+    def fetch_envelope(self, spec: RequestSpec, quota_scope: str) -> JsonValue:
+        """Execute one request outside any page loop; return its envelope.
+
+        Args:
+            spec: The credential-less request to execute.
+            quota_scope: The rate-limit scope key the attempt spends from.
+
+        Returns:
+            The parsed success envelope; interpretation is the caller's.
+        """
+        ...

fleetpull/network/contract/envelopes.py

@@ -0,0 +1,189 @@
+# src/fleetpull/network/contract/envelopes.py
+"""Validate-or-raise for provider response envelopes.
+
+Relocated here from ``page_decoder.py`` at its second consumer (the
+GeoTab authenticator): the composition — ``model_validate`` and, on
+failure, raise ``ProviderResponseError`` carrying Pydantic's complaint
+— is contract-layer semantics, not page-decoding semantics, so it is
+named and homed neutrally where both consumers can reach it without a
+name lie.
+"""
+
+from typing import cast
+
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+from fleetpull.exceptions import ProviderResponseError
+from fleetpull.vocabulary import JsonObject, JsonValue
+
+__all__: list[str] = [
+    'StrictEnvelopeSlice',
+    'require_child_object',
+    'require_record_list',
+    'unwrap_record_objects',
+    'validated_envelope_slice',
+]
+
+
+class StrictEnvelopeSlice(BaseModel):
+    """The base every private envelope-slice model subclasses.
+
+    The one home of the slice-model policy, so its rationale is stated once:
+    ``strict=True`` refuses type drift on the values the consumer acts on
+    (providers elsewhere stringify numerics, and a boolean must never pass as
+    an integer); ``extra='ignore'`` tolerates the envelope fields a slice
+    does not name (a slice reads its few load-bearing keys, never the whole
+    envelope); ``frozen=True`` keeps a validated slice immutable, like every
+    internal carrier.
+    """
+
+    model_config = ConfigDict(frozen=True, extra='ignore', strict=True)
+
+
+def validated_envelope_slice[ModelT: BaseModel](
+    model_type: type[ModelT], envelope: JsonValue
+) -> ModelT:
+    """
+    Validate a response envelope against a private slice model,
+    translating failure into the contract's single-action raise.
+
+    Shared rather than reimplemented per consumer because the
+    composition — validate, and on failure raise
+    ``ProviderResponseError`` carrying Pydantic's complaint — is layer
+    semantics, not provider behavior.
+
+    Args:
+        model_type: The consumer's private envelope-slice model.
+        envelope: The parsed response body (any shape; a non-dict
+            fails validation like any other malformation).
+
+    Returns:
+        The validated slice.
+
+    Raises:
+        ProviderResponseError: When the envelope does not satisfy the
+            slice model.
+    """
+    try:
+        return model_type.model_validate(envelope)
+    except ValidationError as error:
+        raise ProviderResponseError(
+            detail=f'malformed response envelope: {error}'
+        ) from error
+
+
+def _require_json_object(value: JsonValue) -> JsonObject:
+    """Return ``value`` narrowed to a JSON object, or raise.
+
+    Args:
+        value: The parsed value under inspection.
+
+    Returns:
+        The value as a JSON object.
+
+    Raises:
+        ProviderResponseError: When the value is not a JSON object.
+    """
+    if not isinstance(value, dict):
+        raise ProviderResponseError(detail='response envelope is not a JSON object')
+    return value
+
+
+def require_child_object(envelope: JsonValue, key: str) -> JsonObject:
+    """Return the JSON object at a top-level envelope key.
+
+    The nested-container step for envelopes whose record list sits one
+    level down: validates, in order, that the envelope is a JSON object,
+    ``key`` is present, and its value is itself a JSON object.
+
+    Args:
+        envelope: The parsed response body.
+        key: The top-level key whose value is the container object.
+
+    Returns:
+        The JSON object at ``key``.
+
+    Raises:
+        ProviderResponseError: When the envelope is not an object, ``key``
+            is absent, or its value is not a JSON object — each with a
+            message naming the failure.
+    """
+    response = _require_json_object(envelope)
+    if key not in response:
+        raise ProviderResponseError(
+            detail=f'response envelope is missing the record key {key!r}'
+        )
+    child = response[key]
+    if not isinstance(child, dict):
+        raise ProviderResponseError(detail=f'record key {key!r} is not a JSON object')
+    return child
+
+
+def require_record_list(envelope: JsonValue, key: str) -> list[JsonObject]:
+    """Return the record list at a top-level envelope key.
+
+    Validates, in order: the envelope is a JSON object; ``key`` is
+    present; its value is a list; every element is a JSON object.
+
+    Args:
+        envelope: The parsed response body.
+        key: The top-level key whose value is the record list.
+
+    Returns:
+        The record list at ``key``, each element a JSON object.
+
+    Raises:
+        ProviderResponseError: When the envelope is not an object,
+            ``key`` is absent, its value is not a list, or an element is
+            not a JSON object — each with a message naming the failure.
+    """
+    response = _require_json_object(envelope)
+    if key not in response:
+        raise ProviderResponseError(
+            detail=f'response envelope is missing the record key {key!r}'
+        )
+    records = response[key]
+    if not isinstance(records, list):
+        raise ProviderResponseError(detail=f'record key {key!r} is not a list')
+    for record in records:
+        if not isinstance(record, dict):
+            raise ProviderResponseError(
+                detail=f'record under {key!r} is not a JSON object'
+            )
+    return cast(list[JsonObject], records)
+
+
+def unwrap_record_objects(
+    wrappers: list[JsonObject], item_key: str
+) -> list[JsonObject]:
+    """Lift the inner object out of each single-key record wrapper.
+
+    Motive returns each record wrapped — ``{"vehicle": {...}}`` inside
+    the ``vehicles`` list; this lifts the inner object out of every
+    wrapper. Each wrapper must carry ``item_key`` and its value must be
+    a JSON object.
+
+    Args:
+        wrappers: The wrapper objects (already validated as objects).
+        item_key: The key inside each wrapper holding the record.
+
+    Returns:
+        The unwrapped record objects.
+
+    Raises:
+        ProviderResponseError: When a wrapper lacks ``item_key`` or its
+            value is not a JSON object.
+    """
+    records: list[JsonObject] = []
+    for wrapper in wrappers:
+        if item_key not in wrapper:
+            raise ProviderResponseError(
+                detail=f'record wrapper is missing the item key {item_key!r}'
+            )
+        inner = wrapper[item_key]
+        if not isinstance(inner, dict):
+            raise ProviderResponseError(
+                detail=f'record under {item_key!r} is not a JSON object'
+            )
+        records.append(inner)
+    return records

fleetpull/network/contract/outcome.py

@@ -0,0 +1,43 @@
+# src/fleetpull/network/contract/outcome.py
+"""The carrier for a classifier's verdict on one response.
+
+Produced exclusively by ``ResponseClassifier`` implementations;
+consumed by the client, which dispatches on ``category`` (the
+``ResponseCategory`` vocabulary lives in ``fleetpull.vocabulary``).
+"""
+
+from dataclasses import dataclass, field
+
+from fleetpull.vocabulary import JsonValue, ResponseCategory
+
+__all__: list[str] = ['ClassifiedResponse']
+
+
+@dataclass(frozen=True, slots=True)
+class ClassifiedResponse:
+    """
+    A classifier's verdict on one response or transport failure.
+
+    Fields are inert outside their category (the established
+    required-with-default-inert pattern).
+
+    Attributes:
+        category: What the client does next.
+        retry_after_seconds: Meaningful only for RATE_LIMITED; None
+            means the provider sent no usable hint and the client
+            applies its fallback penalty.
+        detail: Human-readable context for failure paths. Decisions
+            never read it.
+        parsed_body: The parsed equivalent of the response's body text
+            — the whole document, not extracted records. Populated only
+            when classification itself required parsing the body; None
+            on SUCCESS means the classifier did not parse and the
+            client must. Inert outside SUCCESS. Excluded from ``repr``
+            because it can hold a multi-megabyte structure that no log
+            line may embed.
+    """
+
+    category: ResponseCategory
+    retry_after_seconds: float | None = None
+    detail: str | None = None
+    parsed_body: JsonValue | None = field(default=None, repr=False)

fleetpull/network/contract/page_decoder.py

@@ -0,0 +1,101 @@
+# src/fleetpull/network/contract/page_decoder.py
+"""The page-decoder contract: interpret a response envelope once,
+yielding its records and its pagination verdict together.
+
+Supersedes the split ``PaginationStrategy`` + ``RecordExtractor``: a
+provider's envelope is parsed in exactly one place, so the records and
+the continuation cursor are read from a single validated view rather
+than re-interpreted downstream. Implementations live in the sibling
+``network/decoders/`` package and reach this surface through the
+contract face; they deliberately share no concrete behavior
+(blast-radius over DRY).
+"""
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from fleetpull.network.contract.request import RequestSpec
+from fleetpull.vocabulary import JsonObject, JsonValue
+
+__all__: list[str] = ['DecodedPage', 'PageAdvance', 'PageDecoder']
+
+
+@dataclass(frozen=True, slots=True)
+class PageAdvance:
+    """
+    A decoder's verdict on one completed page.
+
+    Attributes:
+        next_spec: The request for the next page, or None when
+            pagination is complete.
+        durable_progress: Cursor progress that must outlive the fetch
+            (GeoTab's ``toVersion``; the state layer's FeedToken commit
+            value). None for providers whose cursors are fetch-private
+            (the established inert pattern). Carried on EVERY page
+            including the terminal one — the terminal page's value is
+            the resume point.
+    """
+
+    next_spec: RequestSpec | None
+    durable_progress: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class DecodedPage:
+    """One decoded page: its records and its pagination verdict.
+
+    Composes ``PageAdvance`` rather than re-declaring ``next_spec`` /
+    ``durable_progress`` — the meaning of "next transient request plus
+    durable cursor progress" stays defined in exactly one place.
+
+    Attributes:
+        records: The page's records, each a JSON object.
+        advance: The pagination verdict (continue/complete plus durable
+            progress) for the page just decoded.
+    """
+
+    records: list[JsonObject]
+    advance: PageAdvance
+
+
+class PageDecoder(Protocol):
+    """Per-provider envelope interpreter: records and pagination in one pass.
+
+    A plain Protocol (no ``@runtime_checkable``) — conformance is a
+    static obligation checked by mypy at the binding site, not an
+    isinstance gate.
+    """
+
+    def first_request(self, spec: RequestSpec) -> RequestSpec:
+        """Decorate the base spec for page one.
+
+        Absorbs the former ``PaginationStrategy.first_request`` so that
+        pagination configuration (page size, the first-page cursor
+        rule) stays inside the decoder and the spec builder stays
+        pagination-blind.
+
+        Args:
+            spec: The endpoint's base request spec.
+
+        Returns:
+            The spec to send for the first page.
+        """
+        ...
+
+    def decode_page(self, sent: RequestSpec, envelope: JsonValue) -> DecodedPage:
+        """Interpret one response envelope into records and a verdict.
+
+        Args:
+            sent: The spec that produced this page; supplies whatever
+                the continuation request is derived from.
+            envelope: The parsed response body.
+
+        Returns:
+            The page's records and its pagination verdict.
+
+        Raises:
+            ProviderResponseError: When the envelope's record-bearing or
+                pagination shape is structurally violating (the §8
+                stance).
+        """
+        ...

fleetpull/network/contract/request.py

@@ -0,0 +1,97 @@
+# src/fleetpull/network/contract/request.py
+"""Request description: the spec endpoint definitions build, auth
+strategies transform, and the client executes.
+
+A ``RequestSpec`` is a pure description of one HTTP request — no
+transport, no credentials until an ``AuthStrategy`` injects them.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+from enum import StrEnum
+from typing import Self
+
+from fleetpull.vocabulary import JsonValue
+
+__all__: list[str] = [
+    'HttpMethod',
+    'RequestSpec',
+]
+
+
+class HttpMethod(StrEnum):
+    """HTTP methods fleetpull uses.
+
+    GET and POST only — fleetpull never writes to providers. Add
+    members only when a real endpoint needs them.
+    """
+
+    GET = 'GET'
+    POST = 'POST'
+
+
+@dataclass(frozen=True, slots=True)
+class RequestSpec:
+    """
+    Pure description of one HTTP request.
+
+    Built by endpoint definitions, transformed by auth strategies,
+    executed by the client. Frozen prevents rebinding, not mutation of
+    the contained mappings — they are treated as immutable by
+    convention.
+
+    Attributes:
+        method: The HTTP method.
+        url: Fully qualified request URL.
+        headers: Request headers (empty by default).
+        params: Query parameters, or None.
+        json_body: JSON request body (the GeoTab JSON-RPC envelope
+            lives here), or None.
+    """
+
+    method: HttpMethod
+    url: str
+    headers: Mapping[str, str] = field(default_factory=dict)
+    params: Mapping[str, str] | None = None
+    json_body: Mapping[str, JsonValue] | None = None
+
+    def with_extra_headers(self, extra: Mapping[str, str]) -> Self:
+        """
+        Return a NEW spec whose headers merge existing and ``extra``.
+
+        ``extra`` wins on key collisions. The original spec is
+        unchanged.
+
+        Args:
+            extra: Headers to add or override.
+
+        Returns:
+            A new ``RequestSpec`` with the merged headers; every other
+            field is preserved.
+        """
+        return replace(self, headers={**self.headers, **extra})
+
+    def with_merged_params(self, overrides: Mapping[str, str]) -> Self:
+        """
+        Copy of this spec with ``overrides`` merged into ``params``
+        (add-or-replace per key; existing keys not named are kept).
+
+        Args:
+            overrides: Query parameters to add or replace.
+
+        Returns:
+            The new spec; ``self`` is unchanged.
+        """
+        return replace(self, params={**(self.params or {}), **overrides})
+
+    def with_json_body(self, json_body: Mapping[str, JsonValue]) -> Self:
+        """
+        Copy of this spec with ``json_body`` replaced wholesale.
+
+        Args:
+            json_body: The replacement body.
+
+        Returns:
+            The new spec; ``self`` is unchanged.
+        """
+        return replace(self, json_body=json_body)

fleetpull/network/decoders/__init__.py

@@ -0,0 +1,40 @@
+# src/fleetpull/network/decoders/__init__.py
+"""Per-provider page decoders: envelope interpreters that yield records
+and a pagination verdict in one pass.
+
+Implementations of the ``PageDecoder`` protocol (in
+``network/contract/page_decoder.py``); peers of the contract surface,
+imported by bindings through this face. Each decoder is independent --
+provider envelopes evolve separately (blast-radius over DRY). The one
+shared package-internal piece is the window stamp (``_window_stamp.py``):
+the synthesized window-identity keys are our own provider-uniform
+vocabulary, not envelope logic.
+"""
+
+from fleetpull.network.decoders.geotab import (
+    GeotabFeedPageDecoder,
+    GeotabGetPageDecoder,
+)
+from fleetpull.network.decoders.motive import (
+    MotiveWrappedListPageDecoder,
+    MotiveWrappedSinglePageDecoder,
+)
+from fleetpull.network.decoders.motive_reports import MotiveWindowReportPageDecoder
+from fleetpull.network.decoders.samsara import (
+    SamsaraCursorPageDecoder,
+    SamsaraVehicleSeriesPageDecoder,
+)
+from fleetpull.network.decoders.samsara_reports import SamsaraWindowReportPageDecoder
+from fleetpull.network.decoders.single_page import SinglePageDecoder
+
+__all__: list[str] = [
+    'GeotabFeedPageDecoder',
+    'GeotabGetPageDecoder',
+    'MotiveWindowReportPageDecoder',
+    'MotiveWrappedListPageDecoder',
+    'MotiveWrappedSinglePageDecoder',
+    'SamsaraCursorPageDecoder',
+    'SamsaraVehicleSeriesPageDecoder',
+    'SamsaraWindowReportPageDecoder',
+    'SinglePageDecoder',
+]

fleetpull/network/decoders/_window_stamp.py

@@ -0,0 +1,78 @@
+# src/fleetpull/network/decoders/_window_stamp.py
+"""The shared window stamp for window-grain report decoders.
+
+Window-grain rollup surfaces return rows carrying NO event time of any
+kind -- each row is the provider's aggregate over exactly the requested
+window, so the row's time identity is the window the SENT spec asked
+for. The decoders for those surfaces stamp every record with the
+synthesized ``windowStartDate``/``windowEndDate`` keys, copied VERBATIM
+from the sent spec's own window params.
+
+The stamp keys are OUR vocabulary, deliberately PROVIDER-UNIFORM: they
+are synthesized, not mirrored, so uniformity costs no wire fidelity and
+buys one recognizable window-identity shape across providers (the
+Samsara fuel-energy pair and the Motive utilization pair both land
+``window_start``/``window_end`` on their models). That is why this
+helper is shared across provider decoder modules -- a deliberate,
+narrow exception to the decoders' blast-radius-over-DRY rule, which
+covers provider ENVELOPE logic: only the param NAMES vary per provider,
+and each caller passes its own.
+"""
+
+from typing import Final
+
+from fleetpull.exceptions import ProviderResponseError
+from fleetpull.network.contract import RequestSpec
+from fleetpull.vocabulary import JsonObject
+
+__all__: list[str] = [
+    'WINDOW_END_KEY',
+    'WINDOW_START_KEY',
+    'window_stamp_from_sent_spec',
+]
+
+# The synthesized window-identity keys merged onto each report record.
+# Chosen collision-free against every walked report census (no
+# time-shaped key on any window-grain surface's wire rows), and named
+# after what they carry: the window that was asked of the provider.
+WINDOW_START_KEY: Final[str] = 'windowStartDate'
+WINDOW_END_KEY: Final[str] = 'windowEndDate'
+
+
+def window_stamp_from_sent_spec(
+    sent: RequestSpec, *, start_param: str, end_param: str
+) -> JsonObject:
+    """The window-identity keys the sent spec contributes to its records.
+
+    Copied VERBATIM from the sent spec's own window params --
+    wire-truthful: the stamp is exactly what was asked of the provider,
+    whose answer each rollup row is. A sent spec lacking either param is
+    a wiring bug (every window-grain builder renders both), and silently
+    unstamped rows would strip the rows' time identity -- so it fails
+    loudly instead.
+
+    Args:
+        sent: The spec that produced the page being decoded.
+        start_param: The provider's window-start param name (e.g.
+            Samsara's ``startDate``, Motive's ``start_date``).
+        end_param: The provider's window-end param name.
+
+    Returns:
+        ``{'windowStartDate': ..., 'windowEndDate': ...}``, values
+        verbatim from the sent params.
+
+    Raises:
+        ProviderResponseError: The sent spec lacks either window param.
+    """
+    params = sent.params or {}
+    if start_param not in params or end_param not in params:
+        raise ProviderResponseError(
+            detail=(
+                f'sent spec lacks the {start_param!r}/{end_param!r} window '
+                'params to stamp report rows with'
+            )
+        )
+    return {
+        WINDOW_START_KEY: params[start_param],
+        WINDOW_END_KEY: params[end_param],
+    }