pfmsoft-api-request 0.1.3__py3-none-any.whl

pfmsoft/api_request/request/intermediate_models.py

@@ -0,0 +1,143 @@
+"""Intermediate request and response models for request orchestration.
+
+These models are used internally by the request pipeline to represent work in
+progress and normalized intermediate outcomes before conversion into the public
+response models.
+
+They are importable across implementation modules and tests, but they are not
+part of the stable public package API and may change during internal refactors.
+"""
+
+from dataclasses import dataclass
+from typing import Any
+from uuid import UUID
+
+from pfmsoft.api_request.request.models import Request, ResponseMetadata, Source
+
+
+@dataclass(slots=True, kw_only=True)
+class IntermediateRequestBase:
+    """Base model for intermediate request pipeline objects."""
+
+    request: Request
+    """The original request that generated this intermediate object."""
+
+
+@dataclass(slots=True, kw_only=True)
+class IntermediateResponseBase(IntermediateRequestBase):
+    """Base model for intermediate responses used during request processing."""
+
+
+@dataclass(slots=True, kw_only=True)
+class FailedRequestBase(IntermediateResponseBase):
+    """Base model for failed intermediate responses."""
+
+
+@dataclass(slots=True, kw_only=True)
+class FailNoResponse(FailedRequestBase):
+    """Intermediate failure used when no response was received."""
+
+    error_message: str
+    """An error message describing the failure."""
+
+
+@dataclass(slots=True, kw_only=True)
+class FailWithResponse(FailedRequestBase):
+    """Intermediate failure used when a response indicates failure."""
+
+    metadata: ResponseMetadata
+    """The metadata of the response, including status code and headers."""
+    json: Any
+    """The parsed JSON body of the response."""
+
+
+@dataclass(slots=True, kw_only=True)
+class UnprocessedRequest(IntermediateRequestBase):
+    """Intermediate request that has not yet been sent."""
+
+
+@dataclass(slots=True, kw_only=True)
+class SuccessfulResponseBase(IntermediateResponseBase):
+    """Base model for successful intermediate responses."""
+
+    metadata: ResponseMetadata
+    """The metadata of the response, including status code and headers."""
+    json: Any
+    """The parsed JSON body of the response."""
+    source: Source
+    """The source of the response, for example cache or network."""
+
+
+@dataclass(slots=True, kw_only=True)
+class SuccessfulResponse(SuccessfulResponseBase):
+    """Successful intermediate response used during request processing."""
+
+
+@dataclass(slots=True, kw_only=True)
+class CachableRequest(UnprocessedRequest):
+    """Intermediate request that has an associated cache key."""
+
+    cache_key: UUID
+    """The cache key associated with this request."""
+
+
+@dataclass(slots=True, kw_only=True)
+class RequestFromStaleCache(CachableRequest):
+    """A stale cached request that needs revalidation."""
+
+    etag: str | None
+    """The ETag of the cached response."""
+    last_modified: str | None = None
+    """The Last-Modified header of the cached response, if available."""
+
+    @property
+    def conditional_headers(self) -> dict[str, str]:
+        """Build conditional request headers for stale-cache revalidation.
+
+        Returns:
+            A dictionary containing `If-None-Match` and/or
+            `If-Modified-Since`.
+
+        Raises:
+            ValueError: If both validators are missing.
+        """
+        headers: dict[str, str] = {}
+        if not self.etag and not self.last_modified:
+            raise ValueError(
+                "At least one of ETag or Last-Modified must be provided for a stale cache request."
+            )
+        if self.etag:
+            headers["If-None-Match"] = self.etag
+        if self.last_modified:
+            headers["If-Modified-Since"] = self.last_modified
+        return headers
+
+
+@dataclass(slots=True, kw_only=True)
+class Response304FromStaleCache(SuccessfulResponseBase):
+    """A cached-body response refreshed by an HTTP 304 revalidation."""
+
+    source: Source = Source.CACHE_304
+
+
+@dataclass(slots=True, kw_only=True)
+class Response200FromStaleCache(SuccessfulResponseBase):
+    """A refreshed cached response replaced by an HTTP 200 revalidation."""
+
+    source: Source = Source.CACHE_200
+
+
+__all__ = [
+    "CachableRequest",
+    "FailNoResponse",
+    "FailWithResponse",
+    "FailedRequestBase",
+    "IntermediateRequestBase",
+    "IntermediateResponseBase",
+    "RequestFromStaleCache",
+    "Response200FromStaleCache",
+    "Response304FromStaleCache",
+    "SuccessfulResponse",
+    "SuccessfulResponseBase",
+    "UnprocessedRequest",
+]

pfmsoft/api_request/request/models.py

@@ -0,0 +1,355 @@
+"""Public request/response models used by API orchestration.
+
+This module defines immutable dataclasses for request and response objects,
+plus convenience properties for common HTTP metadata lookups.
+"""
+
+import logging
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+from uuid import UUID, uuid4
+
+from pydantic import RootModel
+from whenever import Instant
+
+logger = logging.getLogger(__name__)
+
+type PARAMETER = str | int | float
+"""Supported query-parameter value types."""
+
+
+#######################################################################################
+# Request Models
+#######################################################################################
+
+
+@dataclass(slots=True, kw_only=True)
+class Request:
+    """Represents one outbound HTTP request definition.
+
+    The model is immutable and can be safely shared across async tasks.
+    """
+
+    request_key: UUID = field(default_factory=uuid4)
+    """The UUID key for the request."""
+    url: str
+    """The URL of the API request."""
+    method: str
+    """The HTTP method of the API request (e.g., GET, POST)."""
+    headers: dict[str, str] = field(default_factory=dict[str, str])
+    """The headers of the API request."""
+    body: Any | None = None
+    """The body of the API request, if applicable."""
+    parameters: dict[str, PARAMETER] = field(default_factory=dict[str, PARAMETER])
+    """The query parameters of the API request."""
+    cache_key: UUID | None = None
+    """The UUID key for the cached response. If None, the response is not cached."""
+    rate_key: str | None = None
+    """Optional key used by rate-limiter implementations to group requests."""
+
+    def purge_secrets(self) -> None:
+        """Purge authorization headers from the request for security purposes."""
+        # replace access tokens with REDACTED in headers
+        redacted_headers = {
+            k: "REDACTED" if k.lower() == "authorization" else v
+            for k, v in self.headers.items()
+        }
+        self.headers = redacted_headers
+
+
+#######################################################################################
+# Response Models
+#######################################################################################
+class Source(StrEnum):
+    """Enumeration of possible sources for a response."""
+
+    CACHE = "cache"
+    """The response was retrieved from the cache."""
+    CACHE_304 = "cache-304"
+    """The cached response was revalidated and remained current."""
+    CACHE_200 = "cache-200"
+    """The cached response was revalidated and replaced by fresh content."""
+    NETWORK = "network"
+    """The response was retrieved from the network."""
+
+
+@dataclass(slots=True, kw_only=True, frozen=True)
+class X_ratelimit:
+    """Parsed X-RateLimit header values."""
+
+    group: str
+    """X-RateLimit group identifier."""
+    limit: str
+    """Configured request budget for the current window."""
+    remaining: str
+    """Remaining budget in the current window."""
+    used: str
+    """Consumed budget in the current window."""
+
+
+@dataclass(slots=True, kw_only=True)
+class ResponseMetadata:
+    """Represents transport metadata for a single HTTP response.
+
+    Time unit conventions:
+        - `elapsed` is stored in microseconds.
+        - `received_timestamp` is stored in Unix nanoseconds.
+        - `expires_at` (derived) is stored in Unix seconds.
+    """
+
+    status_code: int
+    """The HTTP status code of the response."""
+    reason_phrase: str
+    """The reason phrase associated with the status code."""
+    url: str
+    """The URL that was requested to obtain this response."""
+    elapsed: int
+    """The time taken to receive the response, in microseconds, because the source is a timedelta."""
+    bytes_downloaded: int
+    """The number of bytes downloaded in the response body."""
+    headers: tuple[tuple[str, str], ...] = field(
+        default_factory=tuple[tuple[str, str], ...]
+    )
+    """The headers of the response as a tuple of key-value pairs."""
+    received_timestamp: int = -1
+    """The timestamp when the response was received, as a Unix timestamp in nanoseconds."""
+    _headers_lower: dict[str, str] = field(
+        init=False, repr=False, default_factory=dict[str, str]
+    )
+    """A lower case version of the headers for easier access to common headers like ETag and Last-Modified."""
+
+    def __post_init__(self):
+        """Build a lowercase header lookup map for convenience accessors.
+
+        If duplicate header names differ only by case, the later value wins
+        in the lowercase map and a warning is logged.
+        """
+        self._init_lowercase_headers()
+
+    def _init_lowercase_headers(self):
+        """Initialize the lowercase headers mapping."""
+        self._headers_lower = {k.lower(): v for k, v in self.headers}
+        if len(self.headers) != len(self._headers_lower):
+            logger.warning(
+                "Duplicate headers found when converting to lower case. This may lead to "
+                "unexpected behavior when accessing headers. Original headers: %s, Lower "
+                "case headers: %s",
+                self.headers,
+                self._headers_lower,
+            )
+
+    @property
+    def headers_lower(self) -> dict[str, str]:
+        """Return lowercase header mapping used by convenience properties."""
+        return self._headers_lower
+
+    @property
+    def received_at(self) -> Instant:
+        """Convert `received_timestamp` to an Instant.
+
+        Raises:
+            ValueError: If `received_timestamp` is unset (`-1`).
+        """
+        if self.received_timestamp != -1:
+            return Instant.from_timestamp_nanos(self.received_timestamp)
+        raise ValueError("Received timestamp is not set.")
+
+    @property
+    def etag(self) -> str | None:
+        """Extract the ETag from the response headers, if present."""
+        return self.headers_lower.get("etag")
+
+    @property
+    def last_modified(self) -> str | None:
+        """Extract the Last-Modified header from the response headers, if present."""
+        return self.headers_lower.get("last-modified")
+
+    @property
+    def expires(self) -> str | None:
+        """Extract the Expires header from the response headers, if present."""
+        return self.headers_lower.get("expires")
+
+    @property
+    def date(self) -> str | None:
+        """Extract the Date header from the response headers, if present."""
+        return self.headers_lower.get("date")
+
+    @property
+    def date_as_instant(self) -> Instant | None:
+        """Convert the Date header to an Instant, if possible."""
+        date_str = self.date
+        if date_str:
+            try:
+                return Instant.parse_rfc2822(date_str)
+            except ValueError:
+                pass
+        return None
+
+    @property
+    def cache_control(self) -> str | None:
+        """Extract the Cache-Control header from the response headers, if present."""
+        return self.headers_lower.get("cache-control")
+
+    @property
+    def max_age(self) -> int | None:
+        """Extract the max-age directive from the Cache-Control header, if present."""
+        cache_control = self.cache_control
+        if cache_control:
+            directives = cache_control.split(",")
+            for directive in directives:
+                if "max-age" in directive:
+                    try:
+                        return int(directive.split("=")[1].strip())
+                    except IndexError, ValueError:
+                        pass
+        return None
+
+    @property
+    def expires_at(self) -> int | None:
+        """Return cache expiration instant derived from response headers.
+
+        Precedence:
+            1. `Cache-Control: max-age` with a valid `Date` header.
+            2. `Expires` header.
+            3. `None` when neither can be parsed.
+        """
+        if self.max_age is not None and self.date is not None:
+            try:
+                response_date = Instant.parse_rfc2822(self.date)
+                return response_date.add(seconds=self.max_age).timestamp()
+            except ValueError:
+                pass
+        if self.expires:
+            try:
+                return Instant.parse_rfc2822(self.expires).timestamp()
+            except ValueError:
+                pass
+        return None
+
+    @property
+    def pages(self) -> int:
+        """Extract the number of pages from the X-Pages header, if present."""
+        pages = self.headers_lower.get("x-pages", 1)
+        return int(pages)
+
+    @property
+    def ratelimit(self) -> X_ratelimit:
+        """Extract the rate limit information from the X-RateLimit headers, if present."""
+        group = self.headers_lower.get("x-ratelimit-group", "unknown")
+        limit = self.headers_lower.get("x-ratelimit-limit", "unknown")
+        remaining = self.headers_lower.get("x-ratelimit-remaining", "unknown")
+        used = self.headers_lower.get("x-ratelimit-used", "unknown")
+        return X_ratelimit(group=group, limit=limit, remaining=remaining, used=used)
+
+    def purge_secrets(self) -> None:
+        """Purge authorization headers from the response metadata for security purposes."""
+        # replace access tokens with REDACTED in headers
+        # check the headers tuple for any authorization headers and redact them
+        redacted_headers = tuple(
+            (k, "REDACTED") if k.lower() == "authorization" else (k, v)
+            for k, v in self.headers
+        )
+        self.headers = redacted_headers
+        self._init_lowercase_headers()  # reinitialize lowercase headers after purging
+
+    def serialize(self, indent: int | None = None) -> str:
+        """Serialize the ResponseMetadata object to a JSON string."""
+        return ResponseMetadataRoot(self).model_dump_json(indent=indent)
+
+    @classmethod
+    def deserialize(cls, json_str: str) -> ResponseMetadata:
+        """Deserialize a ResponseMetadata object from a JSON string."""
+        return ResponseMetadataRoot.model_validate_json(json_str).root
+
+
+@dataclass(slots=True, kw_only=True, frozen=True)
+class Response:
+    """Represents one successful API response returned to callers."""
+
+    metadata: ResponseMetadata
+    """The metadata of the response, including status code, headers, etc."""
+    json: Any
+    """The parsed JSON body of the response."""
+    request: Request
+    """The original request that generated this response."""
+    source: Source
+    """The source of the response, for example cache or network."""
+
+    @classmethod
+    def deserialize(cls, json_str: str) -> Response:
+        """Deserialize a Response from JSON text."""
+        value = ResponseRoot.model_validate_json(json_str).root
+        return value
+
+    def purge_secrets(self) -> None:
+        """Purge authorization headers from the response metadata for security purposes."""
+        self.metadata.purge_secrets()
+        self.request.purge_secrets()
+
+    def serialize(self, indent: int | None = None) -> str:
+        """Serialize the Response object to a JSON string."""
+        return ResponseRoot(self).model_dump_json(indent=indent)
+
+
+ResponseRoot = RootModel[Response]
+
+
+@dataclass(slots=True, kw_only=True, frozen=True)
+class FailedResponse:
+    """Represents a failed ESI response, typically due to an error status code."""
+
+    metadata: ResponseMetadata | None = None
+    """The metadata of the response, including status code, headers, etc. May be None 
+    if the request failed before receiving a response."""
+    json: Any | None = None
+    """The parsed JSON body of the response. May be None if unavailable."""
+    request: Request
+    """The original request that generated this failed response."""
+    error_messages: list[str] = field(default_factory=list[str])
+    """An optional list of error messages describing the failure."""
+
+    def purge_secrets(self) -> None:
+        """Purge authorization headers from the response metadata for security purposes."""
+        if self.metadata:
+            self.metadata.purge_secrets()
+        self.request.purge_secrets()
+
+
+@dataclass(slots=True, kw_only=True, frozen=True)
+class Responses:
+    """Container for batched request outcomes."""
+
+    successful: dict[UUID, Response] = field(default_factory=dict[UUID, Response])
+    """A dictionary of successful responses, keyed by request UUID."""
+    failed: dict[UUID, FailedResponse] = field(
+        default_factory=dict[UUID, FailedResponse]
+    )
+    """A dictionary of failed responses, keyed by request UUID."""
+
+    def to_string(self, indent: int) -> str:
+        """Serialize this Responses container as JSON text.
+
+        Args:
+            indent: Indentation level passed to pydantic JSON serializer.
+        """
+        json_str = ResponsesRoot(root=self).model_dump_json(indent=indent)
+        return json_str
+
+    @classmethod
+    def from_string(cls, json_str: str) -> Responses:
+        """Deserialize a Responses container from JSON text."""
+        value = ResponsesRoot.model_validate_json(json_str).root
+        return value
+
+
+type Requests = dict[UUID, Request]
+"""Batch request mapping keyed by request UUID."""
+
+#######################################################################################
+# Root Models
+#######################################################################################
+ResponseMetadataRoot = RootModel[ResponseMetadata]
+ResponseRoot = RootModel[Response]
+RequestsRoot = RootModel[Requests]
+ResponsesRoot = RootModel[Responses]

pfmsoft/api_request/request/protocols.py

@@ -0,0 +1,54 @@
+"""Request orchestration protocol contracts.
+
+This module defines the public behavioral surface expected from requester
+implementations.
+
+Typical usage:
+
+```python
+from uuid import uuid4
+
+from api_request import ApiRequester, Request
+from api_request.cache import InMemoryCache
+from api_request.rate_limit import AiolimiterRateLimiterFactory
+
+request = Request(
+    request_key=uuid4(),
+    method="GET",
+    url="https://esi.evetech.net/status/",
+)
+
+async with ApiRequester(
+    cache_factory=InMemoryCache,
+    rate_limiter_factory=AiolimiterRateLimiterFactory(max_rate=100.0),
+) as requester:
+    responses = await requester.process_requests({request.request_key: request})
+```
+"""
+
+from typing import Protocol
+
+from pfmsoft.api_request.request.models import (
+    Requests,
+    Responses,
+)
+
+
+class ApiRequesterProtocol(Protocol):
+    """Protocol for batched request orchestration.
+
+    Contract:
+        - Input keys in `requests` are preserved in output mappings.
+        - Successful request outcomes are returned in `Responses.successful`.
+        - Request-scoped failures are returned in `Responses.failed`.
+        - Implementations are typically used as async context managers to
+            provision HTTP/cache/rate-limit dependencies.
+        - Implementations may raise for fatal infrastructure/configuration errors.
+    """
+
+    async def process_requests(
+        self,
+        requests: Requests,
+    ) -> Responses:
+        """Process a batch of requests and return normalized success/failure maps."""
+        ...

pfmsoft/api_request/settings.py

@@ -0,0 +1,65 @@
+"""Settings for the api-request module."""
+
+import logging
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from uuid import NAMESPACE_DNS, uuid5
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from typer import get_app_dir
+
+from pfmsoft.api_request import (
+    __app_name__,
+    __project_namespace__,
+    __url__,
+    __version__,
+)
+
+logger = logging.getLogger(__name__)
+
+USER_AGENT = f"{__app_name__} ({__version__}) (+{__url__})"
+APP_DOMAIN = f"{__project_namespace__}.{__app_name__}"
+APP_NAMESPACE = uuid5(NAMESPACE_DNS, APP_DOMAIN)
+ENV_PREFIX = APP_DOMAIN.replace(".", "_").replace("-", "_").upper() + "_"
+SETTINGS_KEY = ENV_PREFIX + "SETTINGS"
+
+
+@dataclass(slots=True, kw_only=True)
+class ApiRequestSettings:
+    """Settings for the api-request module."""
+
+    application_directory: Path
+    logging_directory: Path
+    web_cache_path: Path
+
+
+class ApiRequestSettingsPydantic(BaseSettings):
+    """Pydantic settings for the api-request module."""
+
+    application_directory: Path = Path(get_app_dir(__app_name__))
+
+    model_config = SettingsConfigDict(
+        env_prefix=ENV_PREFIX,
+        env_file=(".env", ".env.dev"),
+        env_file_encoding="utf-8",
+    )
+
+
+def get_settings() -> ApiRequestSettings:
+    """Get the settings for the api-request module."""
+    logger.info("Loading settings from environment variables...")
+    logger.info(f"Environment variable prefix: {ENV_PREFIX}")
+    pydantic_settings = ApiRequestSettingsPydantic()
+    logger.info(
+        f"Loaded settings from environment variables: {pydantic_settings.model_dump()}"
+    )
+    application_directory = pydantic_settings.application_directory.resolve()
+    if not application_directory.exists():
+        application_directory.mkdir(parents=True, exist_ok=True)
+    settings = ApiRequestSettings(
+        application_directory=application_directory,
+        logging_directory=application_directory / "logs",
+        web_cache_path=application_directory / "api_requests_web_cache.sqlite",
+    )
+    logger.info(f"Resolved application settings: {asdict(settings)}")
+    return settings