fleetpull 0.1.0__py3-none-any.whl

fleetpull/network/limits/limiter.py

@@ -0,0 +1,153 @@
+# src/fleetpull/network/limits/limiter.py
+"""Per-quota-scope rate limiter: token bucket + in-flight semaphore.
+
+One ``QuotaScopeLimiter`` instance exists per quota scope, shared by every
+thread in the process that talks to that scope. All time reads flow through
+the injected ``Clock`` — never a direct ``time.*`` call — which is what makes
+the deterministic single-threaded tests possible.
+"""
+
+import logging
+import threading
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from fleetpull.config import RateLimitConfig
+from fleetpull.network.limits.bucket_math import refill_tokens, seconds_until_available
+from fleetpull.timing import Clock, SystemClock
+
+__all__: list[str] = ['QuotaScopeLimiter']
+
+logger = logging.getLogger(__name__)
+
+
+class QuotaScopeLimiter:
+    """Token-bucket rate limiter plus concurrency cap for one quota scope.
+
+    The bucket starts FULL at ``config.burst`` tokens (burst is the bucket
+    capacity), refills lazily at ``config.refill_rate_per_second``, and a
+    ``BoundedSemaphore`` caps requests in flight at ``config.max_concurrency``.
+    A 429 / Retry-After penalty pauses the whole scope via :meth:`penalize`.
+
+    Caller contracts (this object cannot enforce them):
+        - Every HTTP attempt consumes one slot. Retries re-acquire; every
+          page is an attempt.
+        - ``request_slot()`` wraps exactly one HTTP attempt — never a
+          pagination loop, never a retry loop.
+    """
+
+    def __init__(
+        self,
+        quota_scope: str,
+        config: RateLimitConfig,
+        clock: Clock = SystemClock(),  # noqa: B008 — SystemClock is frozen and stateless; one shared default instance is intentional
+    ) -> None:
+        """Initialize a limiter with a full bucket and no penalty.
+
+        Args:
+            quota_scope: Scope name, used for log context (a penalty WARNING
+                that cannot say which scope was penalized is useless).
+            config: Token-bucket and concurrency settings for this scope.
+            clock: Time source; injected so tests can be deterministic.
+        """
+        self._quota_scope: str = quota_scope
+        self._config: RateLimitConfig = config
+        self._clock: Clock = clock
+        self._condition: threading.Condition = threading.Condition()
+        self._tokens: float = float(config.burst)
+        self._last_refill_monotonic: float = clock.monotonic_seconds()
+        self._pause_until: float = 0.0
+        # Bounded specifically: a double-release bug must raise, not silently
+        # inflate the concurrency budget.
+        self._in_flight_semaphore: threading.BoundedSemaphore = (
+            threading.BoundedSemaphore(config.max_concurrency)
+        )
+
+    @contextmanager
+    def request_slot(self) -> Iterator[None]:
+        """Block until one HTTP attempt may start, then hold its in-flight slot.
+
+        Acquires the concurrency semaphore first, then waits out any scope
+        penalty, then consumes one bucket token. Semaphore-first ordering is
+        deliberate: taking a token and then blocking on concurrency wastes
+        start-rate budget while starting nothing, while holding an idle
+        concurrency slot costs the provider nothing.
+
+        Yields:
+            None. The caller performs its single HTTP attempt inside the
+            ``with`` block.
+
+        Side Effects:
+            Blocks the calling thread; consumes one token; holds one
+            in-flight slot for the duration of the block. The slot is
+            released even if the block raises.
+        """
+        self._in_flight_semaphore.acquire()
+        try:
+            self._consume_token()
+            yield
+        finally:
+            self._in_flight_semaphore.release()
+
+    def penalize(self, seconds: float) -> None:
+        """Pause the entire quota scope, max-merged with any existing pause.
+
+        Called on 429 / Retry-After. The new pause is
+        ``max(pause_until, now + seconds)`` — never overwritten, so concurrent
+        429s cannot shrink an existing penalty. All waiters are woken so they
+        recompute against the new penalty instead of firing the moment their
+        token math says go.
+
+        Args:
+            seconds: Pause duration (must be > 0). Clamping a zero or
+                negative Retry-After to something sane is the caller's job.
+
+        Raises:
+            ValueError: If ``seconds`` is not positive.
+
+        Side Effects:
+            Extends the scope-wide pause; wakes all waiting threads; logs a
+            WARNING naming the scope and the effective pause duration.
+        """
+        if seconds <= 0:
+            raise ValueError(f'penalty seconds must be positive, got {seconds}')
+        with self._condition:
+            now: float = self._clock.monotonic_seconds()
+            self._pause_until = max(self._pause_until, now + seconds)
+            effective_pause_seconds: float = self._pause_until - now
+            self._condition.notify_all()
+        logger.warning(
+            'Quota scope %r penalized; paused for %.2f seconds.',
+            self._quota_scope,
+            effective_pause_seconds,
+        )
+
+    def _consume_token(self) -> None:
+        """Wait out any penalty, refill the bucket, and consume one token.
+
+        The penalty check comes BEFORE the token check on every iteration:
+        no token may be consumed while the scope is paused. Every wake
+        recomputes from scratch — never assume why you woke.
+        """
+        with self._condition:
+            while True:
+                now: float = self._clock.monotonic_seconds()
+                if now < self._pause_until:
+                    self._condition.wait(timeout=self._pause_until - now)
+                    continue
+                self._tokens = refill_tokens(
+                    current_tokens=self._tokens,
+                    elapsed_seconds=now - self._last_refill_monotonic,
+                    refill_rate_per_second=self._config.refill_rate_per_second,
+                    capacity=float(self._config.burst),
+                )
+                self._last_refill_monotonic = now
+                if self._tokens >= 1.0:
+                    self._tokens -= 1.0
+                    return
+                self._condition.wait(
+                    timeout=seconds_until_available(
+                        current_tokens=self._tokens,
+                        refill_rate_per_second=self._config.refill_rate_per_second,
+                    )
+                )

fleetpull/network/limits/registry.py

@@ -0,0 +1,96 @@
+# src/fleetpull/network/limits/registry.py
+"""Process-wide map from quota-scope strings to their limiters, and the
+derivation of its per-scope values from provider configs."""
+
+import threading
+from collections.abc import Iterable, Mapping
+
+from fleetpull.config import ProviderConfig, RateLimitConfig
+from fleetpull.exceptions import UnknownQuotaScopeError
+from fleetpull.network.limits.limiter import QuotaScopeLimiter
+from fleetpull.timing import Clock, SystemClock
+
+__all__: list[str] = ['RateLimiterRegistry', 'rate_limits_from_configs']
+
+
+def rate_limits_from_configs(
+    provider_configs: Iterable[ProviderConfig],
+) -> dict[str, RateLimitConfig]:
+    """Derive the registry's per-scope rate limits from provider configs.
+
+    Each provider config emits every scope its budgets govern
+    (``ProviderConfig.scope_rate_limits``: the one bound ``quota_scope`` in
+    the base, plus a multi-method-class provider's extra scopes -- GeoTab's
+    feed and authenticate classes -- in its override), so composition roots
+    hand this their resolved configs and never invent rate-limit numbers,
+    and no provider is special-cased here.
+
+    Args:
+        provider_configs: The resolved provider configs for this run -- the
+            same instances handed to ``build_endpoint_registry``.
+
+    Returns:
+        The quota-scope-keyed map ``RateLimiterRegistry`` is constructed on.
+    """
+    rate_limits: dict[str, RateLimitConfig] = {}
+    for config in provider_configs:
+        rate_limits.update(config.scope_rate_limits())
+    return rate_limits
+
+
+class RateLimiterRegistry:
+    """Get-or-create registry of one ``QuotaScopeLimiter`` per quota scope.
+
+    The same scope string always returns the SAME limiter instance — two
+    limiters for one scope would silently double the request budget.
+
+    This registry is constructed by the application's composition root and
+    passed down to whatever needs it. It is NOT a module-level singleton.
+    """
+
+    def __init__(
+        self,
+        rate_limits: Mapping[str, RateLimitConfig],
+        clock: Clock = SystemClock(),  # noqa: B008 — SystemClock is frozen and stateless; one shared default instance is intentional
+    ) -> None:
+        """Initialize the registry with the configured quota scopes.
+
+        Args:
+            rate_limits: Map of quota-scope string to its rate-limit config.
+            clock: Time source passed to every limiter this registry creates.
+        """
+        self._rate_limits: dict[str, RateLimitConfig] = dict(rate_limits)
+        self._clock: Clock = clock
+        self._limiters: dict[str, QuotaScopeLimiter] = {}
+        self._lock: threading.Lock = threading.Lock()
+
+    def get(self, quota_scope: str) -> QuotaScopeLimiter:
+        """Return the limiter for a scope, creating it on first request.
+
+        The check and the create both happen under the lock — losing the
+        check-then-act race would mean two limiters for one scope.
+
+        Args:
+            quota_scope: Scope name declared by an endpoint definition.
+
+        Returns:
+            The single ``QuotaScopeLimiter`` instance for this scope.
+
+        Raises:
+            UnknownQuotaScopeError: If the scope has no configured rate
+                limits.
+        """
+        with self._lock:
+            existing_limiter: QuotaScopeLimiter | None = self._limiters.get(quota_scope)
+            if existing_limiter is not None:
+                return existing_limiter
+            scope_config: RateLimitConfig | None = self._rate_limits.get(quota_scope)
+            if scope_config is None:
+                configured_scopes: str = ', '.join(sorted(self._rate_limits)) or 'none'
+                raise UnknownQuotaScopeError(
+                    quota_scope,
+                    detail=f'configured scopes: {configured_scopes}',
+                )
+            new_limiter = QuotaScopeLimiter(quota_scope, scope_config, self._clock)
+            self._limiters[quota_scope] = new_limiter
+            return new_limiter

fleetpull/network/posture/__init__.py

@@ -0,0 +1,6 @@
+# src/fleetpull/network/posture/__init__.py
+"""Transport posture: the one ``HttpConfig`` -> httpx client construction."""
+
+from fleetpull.network.posture.client_options import new_http_client
+
+__all__: list[str] = ['new_http_client']

fleetpull/network/posture/client_options.py

@@ -0,0 +1,96 @@
+# src/fleetpull/network/posture/client_options.py
+"""The one construction of an httpx client from ``HttpConfig``.
+
+Every fleetpull ``httpx.Client`` — the transport's held pool and the
+GeoTab authenticator's fresh per-call client — is constructed from the
+same two-knob transport posture (DESIGN §10), so the verify/timeout
+composition is decided exactly once, here (``new_http_client``). Before
+this module existed the two construction sites hand-rolled the mapping
+independently and drifted on the pool-timeout member; a single owner is
+what keeps that class of divergence structurally impossible.
+"""
+
+import ssl
+
+import httpx
+
+from fleetpull.config import HttpConfig
+from fleetpull.network.tls import build_truststore_ssl_context
+
+__all__: list[str] = ['new_http_client']
+
+
+def _client_verify(http_config: HttpConfig) -> ssl.SSLContext | bool:
+    """Resolve the TLS verification argument for an ``httpx.Client``.
+
+    OS trust store behind a TLS-intercepting proxy; httpx's bundled CA
+    store otherwise (the proxy is the exception, not the rule).
+
+    Args:
+        http_config: The transport posture; ``use_truststore`` selects
+            the OS trust store.
+
+    Returns:
+        A truststore-backed ``SSLContext`` when ``use_truststore`` is
+        set; ``True`` (httpx's bundled CA verification) otherwise.
+
+    Raises:
+        None.
+
+    Side Effects:
+        None beyond constructing the SSL context.
+    """
+    if http_config.use_truststore:
+        return build_truststore_ssl_context()
+    return True
+
+
+def _client_timeout(http_config: HttpConfig) -> httpx.Timeout:
+    """Resolve the timeout policy for an ``httpx.Client``.
+
+    The two-knob posture maps onto httpx's four members as: read backs
+    read, write, and pool (one slow-is-broken budget for every wait on
+    an established connection), while connect — the handshake — is its
+    own knob.
+
+    Args:
+        http_config: The transport posture supplying the two knobs.
+
+    Returns:
+        The ``httpx.Timeout`` carrying the policy above.
+
+    Raises:
+        None.
+
+    Side Effects:
+        None.
+    """
+    return httpx.Timeout(
+        http_config.read_timeout_seconds,
+        connect=http_config.connect_timeout_seconds,
+    )
+
+
+def new_http_client(http_config: HttpConfig) -> httpx.Client:
+    """Construct an ``httpx.Client`` carrying the configured transport posture.
+
+    The one place the two-knob ``HttpConfig`` becomes httpx client options:
+    TLS verification (OS trust store behind a TLS-intercepting proxy, the
+    bundled CA store otherwise) and the timeout policy. Both fleetpull
+    construction sites — the transport's held pool and the GeoTab
+    authenticator's fresh per-call client — call this, so the composition
+    can never drift between them.
+
+    Args:
+        http_config: The transport posture.
+
+    Returns:
+        A new, open ``httpx.Client``; the caller owns its lifecycle.
+
+    Side Effects:
+        Constructs an httpx connection pool (opened lazily on first use).
+    """
+    return httpx.Client(
+        verify=_client_verify(http_config),
+        timeout=_client_timeout(http_config),
+    )

fleetpull/network/retry/__init__.py

@@ -0,0 +1,13 @@
+"""Retry policy: the pure decision the client consults after each retryable failure."""
+
+from fleetpull.network.retry.decision import (
+    RandomFractionGenerator,
+    RetryDecision,
+    decide_retry,
+)
+
+__all__: list[str] = [
+    'RandomFractionGenerator',
+    'RetryDecision',
+    'decide_retry',
+]

fleetpull/network/retry/decision.py

@@ -0,0 +1,155 @@
+# src/fleetpull/network/retry/decision.py
+"""The retry decision: pure policy, no loop, no sleep, no state.
+
+The client asks one question after each retryable failure — "retry,
+and with what local delay?" — and this module answers it. The answer
+travels as a frozen ``RetryDecision`` rather than an overloaded
+``float | None``: the None-versus-0.0 distinction is exactly the kind
+of subtle contract retry bugs breed in.
+
+Division of labor (DESIGN §7): the limiter owns all rate-limit
+waiting. RATE_LIMITED decisions therefore never carry a local delay —
+the 429 penalized the shared quota scope, and the next
+``request_slot()`` call waits it out. Local delay exists only for
+TRANSIENT backoff, computed here, slept by the client.
+"""
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from fleetpull.config import RetryConfig
+from fleetpull.vocabulary import ResponseCategory
+
+__all__: list[str] = [
+    'RandomFractionGenerator',
+    'RetryDecision',
+    'decide_retry',
+]
+
+
+class RandomFractionGenerator(Protocol):
+    """
+    Generates random fractions for retry jitter.
+
+    The policy needs exactly one capability — a uniform fraction — so
+    the seam is one method, not a concrete randomness class (the Clock
+    precedent applied to jitter). ``random.Random`` satisfies this
+    protocol structurally; the composition root passes
+    ``random.Random()`` directly.
+    """
+
+    def random(self) -> float:
+        """Return a float in the half-open interval [0.0, 1.0)."""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class RetryDecision:
+    """
+    The answer to "retry, and with what local delay?".
+
+    Attributes:
+        should_retry: Whether the failure budget permits another
+            attempt.
+        local_delay_seconds: Seconds the client sleeps before the next
+            attempt. Meaningful only when ``should_retry`` is True;
+            0.0 otherwise (the established inert-field pattern).
+            Always 0.0 for RATE_LIMITED — the penalized limiter is
+            that category's backoff.
+    """
+
+    should_retry: bool
+    local_delay_seconds: float
+
+
+def _transient_delay_seconds(
+    failure_count: int,
+    config: RetryConfig,
+    random_source: RandomFractionGenerator,
+) -> float:
+    """
+    Full-jitter exponential backoff for one TRANSIENT failure.
+
+    Args:
+        failure_count: One-based failure count within TRANSIENT.
+        config: The retry policy.
+        random_source: Injected randomness seam; stubs make the
+            arithmetic exactly assertable in tests.
+
+    Returns:
+        A delay drawn uniformly from the half-open interval
+        ``[0, min(cap, base * 2 ** (failure_count - 1)))`` — the
+        fraction source is ``[0.0, 1.0)``, so the delay never equals
+        the envelope; the same arithmetic ``random.uniform`` performs
+        internally.
+    """
+    envelope_seconds: float = min(
+        config.transient_backoff_cap_seconds,
+        config.transient_backoff_base_seconds * 2 ** (failure_count - 1),
+    )
+    return envelope_seconds * random_source.random()
+
+
+def decide_retry(
+    category: ResponseCategory,
+    failure_count: int,
+    config: RetryConfig,
+    random_source: RandomFractionGenerator,
+) -> RetryDecision:
+    """
+    Decide whether a retryable failure gets another attempt.
+
+    ``failure_count`` is one-based within the current retryable
+    category: the first TRANSIENT failure of an attempt sequence is 1.
+    Category counters are independent — the caller keeps one per
+    category and neither resets the other. The comparison is
+    ``failure_count > max_failures``, so ``max_failures = N`` retries
+    failures 1..N and exhausts on the (N+1)th: at most N + 1 requests.
+
+    Args:
+        category: The classification of the failure. Only TRANSIENT
+            and RATE_LIMITED are retryable; anything else here is a
+            caller bug.
+        failure_count: One-based failure count within ``category``.
+        config: The retry policy.
+        random_source: Injected randomness seam for jitter. Required —
+            implementations are stateful, so the parameter earns no
+            frozen-and-stateless default; the composition root owns
+            one instance (``random.Random()`` satisfies the protocol
+            structurally).
+
+    Returns:
+        The decision. Exhausted budgets return
+        ``RetryDecision(should_retry=False, local_delay_seconds=0.0)``;
+        the caller raises ``RetriesExhaustedError`` with the terminal
+        failure count as ``attempt_count`` (equal by definition —
+        every attempt failed).
+
+    Raises:
+        ValueError: When ``category`` is not retryable or
+            ``failure_count`` is less than 1 — programming errors,
+            deliberately stdlib per the hierarchy's closure stance.
+    """
+    if failure_count < 1:
+        raise ValueError(f'failure_count is one-based; got {failure_count}')
+    match category:
+        case ResponseCategory.TRANSIENT:
+            if failure_count > config.transient_max_failures:
+                return RetryDecision(should_retry=False, local_delay_seconds=0.0)
+            return RetryDecision(
+                should_retry=True,
+                local_delay_seconds=_transient_delay_seconds(
+                    failure_count, config, random_source
+                ),
+            )
+        case ResponseCategory.RATE_LIMITED:
+            if failure_count > config.rate_limited_max_failures:
+                return RetryDecision(should_retry=False, local_delay_seconds=0.0)
+            # The limiter already absorbed this 429's penalty; the
+            # retry waits in request_slot(), never here.
+            return RetryDecision(should_retry=True, local_delay_seconds=0.0)
+        case _:
+            raise ValueError(
+                f'category {category!r} is not retryable; only TRANSIENT '
+                'and RATE_LIMITED reach retry policy'
+            )

fleetpull/network/tls/__init__.py

@@ -0,0 +1,5 @@
+"""TLS plumbing: SSL-context construction for the OS trust store."""
+
+from fleetpull.network.tls.truststore_context import build_truststore_ssl_context
+
+__all__: list[str] = ['build_truststore_ssl_context']

fleetpull/network/tls/truststore_context.py

@@ -0,0 +1,35 @@
+# src/fleetpull/network/tls/truststore_context.py
+"""SSL context factory using the operating system trust store.
+
+Builds SSL contexts that verify certificates against the OS-native
+trust store rather than Python's bundled certifi certificates. The
+primary use case is corporate environments using aggressive proxies
+(like Zscaler) that act as man-in-the-middle inspectors: these proxies
+re-encrypt traffic with a private root CA that is installed in the
+Windows/macOS system store but is unknown to standard Python
+libraries. Without this module, requests fail with
+``SSLCertVerificationError``; with it, Python trusts the proxy's root
+CA, enabling secure connectivity without disabling SSL verification.
+"""
+
+import ssl
+from ssl import SSLContext
+
+import truststore
+
+__all__: list[str] = ['build_truststore_ssl_context']
+
+
+def build_truststore_ssl_context() -> SSLContext:
+    """
+    Create an SSLContext using truststore for system certificate validation.
+
+    Explicitly uses ``PROTOCOL_TLS_CLIENT`` — secure defaults for
+    client-side TLS with automatic protocol negotiation and certificate
+    verification. Safe for library code: no global monkey-patching.
+
+    Returns:
+        A new context that validates certificates against the OS trust
+        store.
+    """
+    return truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)

fleetpull/orchestrator/__init__.py

@@ -0,0 +1,30 @@
+# src/fleetpull/orchestrator/__init__.py
+"""The orchestration layer's face: what the composition roots consume (DESIGN §14).
+
+``run_endpoint`` is the caller boundary: it resolves the endpoint's declared
+request driver through the shared shape seam (``resolve_request_driver`` --
+the one match over the ``RequestShape`` union, called by both composition
+roots) and runs. ``EndpointRunner`` owns one endpoint's run and dispatches on
+its sync mode, constructed on the ``RunStateAccess`` state bundle;
+``RosterMachinery`` bundles the roster collaborators a run consults and
+``RosterRefreshCoordinator`` owns the roster staleness policy whole;
+``FetchPoolRegistry`` owns one fan-out worker pool per provider (DESIGN §7).
+Everything else in the package -- the drives, the drivers, the outcome union,
+the unit loop -- is internal machinery its modules export directly."""
+
+from fleetpull.orchestrator.entry import RosterMachinery, run_endpoint
+from fleetpull.orchestrator.executors import FetchPoolRegistry
+from fleetpull.orchestrator.roster_refresh import RosterRefreshCoordinator
+from fleetpull.orchestrator.runner import EndpointRunner
+from fleetpull.orchestrator.shape_resolution import resolve_request_driver
+from fleetpull.orchestrator.spine import RunStateAccess
+
+__all__: list[str] = [
+    'EndpointRunner',
+    'FetchPoolRegistry',
+    'RosterMachinery',
+    'RosterRefreshCoordinator',
+    'RunStateAccess',
+    'resolve_request_driver',
+    'run_endpoint',
+]