sincpro-framework 3.24.2__tar.gz → 3.26.0__tar.gz

{sincpro_framework-3.24.2 → sincpro_framework-3.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sincpro-framework
-Version: 3.24.2
+Version: 3.26.0
 Summary: Sincpro framework to use DDD, Clean architecture, Hexagonal architecture
 License: MIT
 License-File: LICENSE.md
@@ -34,7 +34,7 @@ Requires-Dist: boto3 (>=1.35) ; extra == "aws"
 Requires-Dist: dependency-injector (>=4.49.1,<5.0.0)
 Requires-Dist: duckdb-engine (>=0.17.0,<0.18.0) ; extra == "duckdb"
 Requires-Dist: fastapi (>=0.115) ; extra == "fastapi"
-Requires-Dist: fastmcp (>=3.4.10,<4) ; extra == "mcp"
+Requires-Dist: fastmcp (>=3.4.10,<5) ; extra == "mcp"
 Requires-Dist: faststream (>=0.7,<0.8) ; extra == "faststream"
 Requires-Dist: grpcio (>=1.60) ; extra == "grpc"
 Requires-Dist: grpcio-health-checking (>=1.60) ; extra == "grpc"

{sincpro_framework-3.24.2 → sincpro_framework-3.26.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "sincpro-framework"
-version = "3.24.2"
+version = "3.26.0"
 description = "Sincpro framework to use DDD, Clean architecture, Hexagonal architecture"
 authors = ["Gutierrez Andres <andru1236@gmail.com>"]
 readme = "README.md"
@@ -23,7 +23,7 @@ opentelemetry-sdk = {version = ">=1.45.1", optional = true}
 opentelemetry-exporter-otlp-proto-grpc = {version = ">=1.45.1", optional = true}
 opentelemetry-exporter-otlp-proto-http = {version = ">=1.45.1", optional = true}
 sentry-sdk = {version = ">=2.0", optional = true}
-fastmcp = {version = ">=3.4.10,<4", optional = true}
+fastmcp = {version = ">=3.4.10,<5", optional = true}
 starlette = {version = ">=1.0", optional = true}
 fastapi = {version = ">=0.115", optional = true}
 grpcio = {version = ">=1.60", optional = true}

{sincpro_framework-3.24.2 → sincpro_framework-3.26.0}/sincpro_framework/__init__.py

@@ -13,12 +13,16 @@ around it: context, persistence, events, caching, observability and transports.
 
     @cache.ttl(timedelta(minutes=5))           the service's cache, beside every bus's own
 
+    problem_of(error)                          a failure as every wire tells it — kind, reason,
+                                               status, what to do next — for a route of one's own
+
 The top level holds what nearly every project imports; each component has its own package
 (`sincpro_framework.context` — where `store_context_in` lives —, `.ddd`, `.pipelines`,
 `.data_layer.store`, `.data_layer.caching`, …).
 """
 
 from .bus_pipeline.interceptors import CallNext, Interceptor
+from .common.failures import NextStep, Problem, problem_of
 from .data_layer.caching.entrypoint.facades import cache, idempotency
 from .exceptions import (
     ClientError,
@@ -51,8 +55,10 @@ __all__ = [
     "FailureKind",
     "FrameworkError",
     "Interceptor",
+    "NextStep",
     "OutcomeUnknownError",
     "Preview",
+    "Problem",
     "ProgrammingError",
     "ServiceUnavailableError",
     "Feature",
@@ -60,6 +66,7 @@ __all__ = [
     "cache",
     "idempotency",
     "logger",
+    "problem_of",
     "TypeDTO",
     "TypeDTOResponse",
 ]

{sincpro_framework-3.24.2 → sincpro_framework-3.26.0}/sincpro_framework/auth/domain/exceptions.py

@@ -10,6 +10,7 @@ each — authenticate again. `PermissionDenied`, not `PermissionError`: Python's
 
 from typing import Any
 
+from sincpro_framework.common.failures.problem import Problem
 from sincpro_framework.exceptions import ClientError, FailureKind, ProgrammingError
 
 
@@ -39,6 +40,18 @@ class AuthError(ClientError):
         """
         return {"kind": self.failure_kind.value, "reason": self.reason}
 
+    def refine_problem(self, problem: Problem) -> Problem:
+        """The problem of a refusal: its reason as what the caller reads, its own HTTP status, and
+        what else the refusal says — a `step_up`, a missing `requirement` — as extensions."""
+        said = {
+            name: value
+            for name, value in self.refusal_body().items()
+            if name not in ("kind", "reason")
+        }
+        return problem.model_copy(
+            update={"detail": self.reason, "status": self.http_status, "extensions": said}
+        )
+
 
 class Unauthenticated(AuthError):
     """Who is calling is not known well enough. `step_up` names what the caller has to come back

{sincpro_framework-3.24.2 → sincpro_framework-3.26.0}/sincpro_framework/common/failures/__init__.py

@@ -1,5 +1,6 @@
 """How every wire tells its caller what kind of failure an error is (`FailureKind`, in the core
-`exceptions`): the classification, and how long to wait before a retry."""
+`exceptions`): the classification, how long to wait before a retry, and the `Problem` every wire
+draws — what happened and what to do next."""
 
 from sincpro_framework.common.failures.classification import (
     DEFAULT_RETRY_AFTER,
@@ -12,10 +13,28 @@ from sincpro_framework.common.failures.classification import (
     retry_after,
     said_to_the_caller,
 )
+from sincpro_framework.common.failures.problem import (
+    HTTP_STATUS_OF,
+    NEXT_STEP_OF,
+    TITLE_OF,
+    FieldError,
+    NextStep,
+    Problem,
+    pointer,
+    problem_of,
+)
 from sincpro_framework.exceptions import FailureKind
 
 __all__ = [
     "DEFAULT_RETRY_AFTER",
+    "FieldError",
+    "HTTP_STATUS_OF",
+    "NEXT_STEP_OF",
+    "NextStep",
+    "Problem",
+    "TITLE_OF",
+    "pointer",
+    "problem_of",
     "PERMANENT",
     "RETRYABLE",
     "failure_reason",

sincpro_framework-3.26.0/sincpro_framework/common/failures/problem.py

@@ -0,0 +1,288 @@
+"""`Problem`: one failure as every wire tells it — its kind, a stable reason, what the caller reads,
+and **what to do next** — built once (`problem_of`) and drawn by each wire in its own encoding:
+RFC 9457 on REST, an error's `data` on JSON-RPC, `google.rpc.Status` on gRPC, a tool error on MCP.
+
+    problem_of(InvoiceNotFound("invoice F-9 does not exist"))
+    ->  Problem(kind=not_found, reason="INVOICE_NOT_FOUND", title="Not found", status=404,
+                detail="invoice F-9 does not exist", next_step=do_not_retry,
+                guidance="What the request names does not exist: …", retryable=False)
+
+Context: the defaults are the kind's — its title, its HTTP status, its next step and guidance
+(`NEXT_STEP_OF`). An error changes what it means without any table to edit:
+
+    class InvoiceNotFound(ClientError):
+        failure_kind = FailureKind.NOT_FOUND                     what kind it is
+        next_step = NextStep.FIX_REQUEST                         what the caller does
+        guidance = "Check the invoice number on the printed copy."
+
+        def refine_problem(self, problem: Problem) -> Problem:   anything else
+            return problem.model_copy(update={"extensions": {"number": self.number}})
+
+An error a project does not own (a library's) is translated into one of its own by an error
+handler of the bus — the one place a project maps a failure. Nothing of a failure that is not
+written for the caller (`said_to_the_caller`) is told: no detail, its kind as its reason.
+"""
+
+from collections.abc import Iterable, Mapping, Sequence
+from datetime import timedelta
+from enum import StrEnum
+from typing import Any
+
+from pydantic import ConfigDict, ValidationError
+
+from sincpro_framework import exceptions
+from sincpro_framework.common.failures.classification import (
+    failure_reason,
+    refined_failure_kind,
+    retry_after,
+    said_to_the_caller,
+)
+from sincpro_framework.sincpro_abstractions import DataTransferObject
+
+
+class NextStep(StrEnum):
+    """What a caller — a person, a client, an agent — does after a failure."""
+
+    FIX_REQUEST = "fix_request"
+    """Correct what was sent, then send it again."""
+    AUTHENTICATE = "authenticate"
+    """Get a credential, or a fresh one, then send it again."""
+    ASK_FOR_ACCESS = "ask_for_access"
+    """Do not retry: whoever calls may not do this until someone grants it."""
+    DO_NOT_RETRY = "do_not_retry"
+    """The same request fails the same way: show the answer and stop."""
+    REFRESH_AND_RETRY = "refresh_and_retry"
+    """Read what changed, then send the request again on what was read."""
+    RETRY_LATER = "retry_later"
+    """Send the same request again after `retry_after`."""
+    VERIFY_THEN_RETRY = "verify_then_retry"
+    """It may have run: check whether it did before sending it again — or send it again with the
+    same idempotency key."""
+
+
+NEXT_STEP_OF: Mapping[exceptions.FailureKind, tuple[NextStep, str]] = {
+    exceptions.FailureKind.INVALID: (
+        NextStep.FIX_REQUEST,
+        "The request does not fit what the use case takes: correct the fields named and send "
+        "it again.",
+    ),
+    exceptions.FailureKind.UNAUTHENTICATED: (
+        NextStep.AUTHENTICATE,
+        "Who is calling is not known: authenticate, or renew the credential, and send it again.",
+    ),
+    exceptions.FailureKind.PERMISSION_DENIED: (
+        NextStep.ASK_FOR_ACCESS,
+        "The caller may not do this: retrying will not help until the access is granted.",
+    ),
+    exceptions.FailureKind.NOT_FOUND: (
+        NextStep.DO_NOT_RETRY,
+        "What the request names does not exist: check the identifier; the same request "
+        "fails the same way.",
+    ),
+    exceptions.FailureKind.CONFLICT: (
+        NextStep.REFRESH_AND_RETRY,
+        "Someone else wrote first: read the current state, then send the request again on it.",
+    ),
+    exceptions.FailureKind.IN_PROGRESS: (
+        NextStep.RETRY_LATER,
+        "The same request is still running: wait `retry_after`, then ask again for its answer.",
+    ),
+    exceptions.FailureKind.KEY_REUSED: (
+        NextStep.FIX_REQUEST,
+        "The idempotency key was used for another request: a new request needs a new key.",
+    ),
+    exceptions.FailureKind.DOMAIN: (
+        NextStep.DO_NOT_RETRY,
+        "A business rule refused the request: show the answer; the same request is refused "
+        "the same way.",
+    ),
+    exceptions.FailureKind.EXHAUSTED: (
+        NextStep.RETRY_LATER,
+        "A limit was reached: wait `retry_after`, then send the same request again.",
+    ),
+    exceptions.FailureKind.UNAVAILABLE: (
+        NextStep.RETRY_LATER,
+        "Something the call needs is down for now: wait `retry_after`, then send the same "
+        "request again.",
+    ),
+    exceptions.FailureKind.UNKNOWN_OUTCOME: (
+        NextStep.VERIFY_THEN_RETRY,
+        "The request was sent and no answer came back — it may have run: check before sending "
+        "it again, or send it with the same idempotency key.",
+    ),
+    exceptions.FailureKind.INTERNAL: (
+        NextStep.RETRY_LATER,
+        "The service failed on its side: try again later, and report it with the trace if it "
+        "keeps failing.",
+    ),
+}
+"""What a caller does after each kind of failure, and why — the default an error may change."""
+
+TITLE_OF: Mapping[exceptions.FailureKind, str] = {
+    exceptions.FailureKind.INVALID: "The request does not validate",
+    exceptions.FailureKind.UNAUTHENTICATED: "Who is calling is not known",
+    exceptions.FailureKind.PERMISSION_DENIED: "Not allowed",
+    exceptions.FailureKind.NOT_FOUND: "Not found",
+    exceptions.FailureKind.CONFLICT: "The write collided",
+    exceptions.FailureKind.IN_PROGRESS: "The same request is still running",
+    exceptions.FailureKind.KEY_REUSED: "The idempotency key was used for another request",
+    exceptions.FailureKind.DOMAIN: "The domain refused the request",
+    exceptions.FailureKind.EXHAUSTED: "Too many requests",
+    exceptions.FailureKind.UNAVAILABLE: "Unavailable for now",
+    exceptions.FailureKind.UNKNOWN_OUTCOME: "It may have run — verify before retrying",
+    exceptions.FailureKind.INTERNAL: "Internal error",
+}
+
+HTTP_STATUS_OF: Mapping[exceptions.FailureKind, int] = {
+    exceptions.FailureKind.INVALID: 422,
+    exceptions.FailureKind.UNAUTHENTICATED: 401,
+    exceptions.FailureKind.PERMISSION_DENIED: 403,
+    exceptions.FailureKind.NOT_FOUND: 404,
+    exceptions.FailureKind.CONFLICT: 409,
+    exceptions.FailureKind.IN_PROGRESS: 409,
+    exceptions.FailureKind.KEY_REUSED: 422,
+    exceptions.FailureKind.DOMAIN: 422,
+    exceptions.FailureKind.EXHAUSTED: 429,
+    exceptions.FailureKind.UNAVAILABLE: 503,
+    exceptions.FailureKind.UNKNOWN_OUTCOME: 504,
+    exceptions.FailureKind.INTERNAL: 500,
+}
+"""The HTTP status of each kind — the one REST answers, and any route of a project's own."""
+
+RETRYABLE_STEPS = frozenset({NextStep.RETRY_LATER, NextStep.REFRESH_AND_RETRY})
+"""The next steps that send the request again without changing it by hand."""
+
+
+def pointer(location: Sequence[Any]) -> str:
+    """A validation error's location as a JSON pointer into the DTO (RFC 6901) — where the value
+    came from (`body`, `query`, …) dropped, `~` and `/` escaped.
+
+        pointer(("body", "lines", 0, "amount"))  ->  "#/lines/0/amount"
+    """
+    parts = list(location)
+    if parts and parts[0] in ("body", "query", "path", "header", "cookie"):
+        parts = parts[1:]
+    return "#/" + "/".join(str(one).replace("~", "~0").replace("/", "~1") for one in parts)
+
+
+class FieldError(DataTransferObject):
+    """One field the request got wrong — `pointer` addresses it in the DTO (`#/total`)."""
+
+    pointer: str
+    detail: str
+
+
+class Problem(DataTransferObject):
+    """One failure, as every wire tells it — as JSON, `retry_after` is a number of seconds, as
+    the `Retry-After` header says it."""
+
+    model_config = ConfigDict(ser_json_timedelta="float")
+
+    kind: exceptions.FailureKind
+    """What kind of failure — the same word on every wire."""
+    reason: str
+    """UPPER_SNAKE, stable: what a client switches on — never the text."""
+    title: str
+    status: int
+    """Its HTTP status — what REST answers, and what a route of a project's own answers."""
+    detail: str | None = None
+    """What the caller reads of this failure — `None` when nothing of it is the caller's."""
+    next_step: NextStep
+    guidance: str
+    """What to do next, in words — for a person or an agent reading it."""
+    retryable: bool
+    """Whether sending the request again, as it is or on a fresh read, may succeed."""
+    retry_after: timedelta | None = None
+    """How long to wait first — `None` when waiting does not help."""
+    errors: list[FieldError] = []
+    """The fields of the request that did not validate."""
+    extensions: dict[str, Any] = {}
+    """What the error chose to disclose besides — a missing permission, a step-up, a limit."""
+
+    @classmethod
+    def for_kind(
+        cls,
+        kind: exceptions.FailureKind,
+        reason: str | None = None,
+        detail: str | None = None,
+        errors: Iterable[FieldError] = (),
+        **extensions: Any,
+    ) -> "Problem":
+        """A problem of `kind` with its defaults — title, status, next step, guidance — and what
+        is given; what an entrypoint answers for a failure no error raised (a body that does not
+        parse, a route that does not exist).
+
+            Problem.for_kind(FailureKind.INVALID, "UNREADABLE", "the body is not JSON")
+        """
+        step, guidance = NEXT_STEP_OF[kind]
+        return cls(
+            kind=kind,
+            reason=reason or kind.value.upper(),
+            title=TITLE_OF[kind],
+            status=HTTP_STATUS_OF[kind],
+            detail=detail,
+            next_step=step,
+            guidance=guidance,
+            retryable=step in RETRYABLE_STEPS,
+            errors=list(errors),
+            extensions=extensions,
+        )
+
+    def body(self) -> dict[str, Any]:
+        """The problem as JSON, as RFC 9457 lays it out: its members and, beside them, what its
+        error disclosed (`extensions`) — a member with nothing to say left out.
+
+            Problem.for_kind(FailureKind.INVALID, "UNREADABLE", "not JSON").body()
+            ->  {"kind": "invalid", "reason": "UNREADABLE", "title": "…", "status": 422,
+                 "detail": "not JSON", "next_step": "fix_request", "guidance": "…",
+                 "retryable": False}
+        """
+        told = {**self.model_dump(mode="json", exclude={"extensions"}), **self.extensions}
+        return {
+            name: value for name, value in told.items() if value not in (None, [], {}, "")
+        }
+
+
+def problem_of(error: Exception) -> Problem:
+    """The problem every wire answers `error` with.
+
+        problem_of(InvoiceNotFound("invoice F-9 does not exist"))
+        ->  Problem(kind=not_found, reason="INVOICE_NOT_FOUND", status=404,
+                    detail="invoice F-9 does not exist", next_step=do_not_retry, …)
+        problem_of(RuntimeError("postgres://admin:pw@db"))
+        ->  Problem(kind=internal, reason="INTERNAL", status=500, detail=None, …)
+
+    1. The kind (`refined_failure_kind`) gives the defaults (`Problem.for_kind`); the reason is
+       the error's class when the caller may read the error, its kind otherwise.
+    2. What the caller reads is the error's message only when it was written for the caller.
+    3. A request that did not validate names each field; a retryable kind says how long to wait.
+    4. The error's `next_step` and `guidance`, when it declares them, take the kind's place.
+    Final: the error's `refine_problem(problem)`, when it has one, changes anything else — what
+    it answers is the problem when it is one.
+    """
+    kind = refined_failure_kind(error)
+    errors = (
+        [
+            FieldError(pointer=pointer(one.get("loc", ())), detail=str(one.get("msg", "")))
+            for one in error.errors(include_url=False)
+        ]
+        if isinstance(error, ValidationError)
+        else []
+    )
+    problem = Problem.for_kind(
+        kind, failure_reason(error, kind), said_to_the_caller(error), errors
+    )
+    step = getattr(error, "next_step", None)
+    step = step if isinstance(step, NextStep) else problem.next_step
+    guidance = getattr(error, "guidance", None)
+    problem = problem.model_copy(
+        update={
+            "retry_after": retry_after(error, kind),
+            "next_step": step,
+            "retryable": step in RETRYABLE_STEPS,
+            "guidance": guidance if isinstance(guidance, str) else problem.guidance,
+        }
+    )
+    refine = getattr(error, "refine_problem", None)
+    refined = refine(problem) if callable(refine) else problem
+    return refined if isinstance(refined, Problem) else problem

{sincpro_framework-3.24.2 → sincpro_framework-3.26.0}/sincpro_framework/context/domain/keys.py

@@ -30,6 +30,9 @@ class ContextKey(StrEnum):
     EXECUTION_ID = "execution_id"
     CAUSATION_ID = "causation_id"
     CORRELATION_ID = "correlation_id"
+    LANG = "lang"
+    """The language of the call, a BCP 47 tag (`es-BO`) — what a `MultiLanguage` and a message
+    are read in."""
     PIPELINE_CONTEXT = "SINCPRO_PIPELINE_CONTEXT"
     """The run a pipeline's steps belong to — `{"pipeline": …, "run_id": …}` on the node of its
     execution, so a run at the same time is another branch; in the store, the namespace of every

{sincpro_framework-3.24.2 → sincpro_framework-3.26.0}/sincpro_framework/data_layer/object_storage/__init__.py

@@ -7,11 +7,15 @@ entrypoint's, and `ObjectStorage` is injected as any adapter.
     billing.add_dependency("storage", ObjectStorage(S3CompatibleObjectStore("documents", boto3_client), secret))
 
     self.storage.put("exports/invoices.csv", data, "text/csv")
+    self.storage.get("exports/invoices.csv")           whole, to process it
+    self.storage.stream("exports/invoices.csv")        by parts, to pass it on
+    self.storage.fetch(url, "inbox/scan.pdf", max_bytes=50 * MB)   a URL's bytes into the store
     published = self.storage.publish("exports/invoices.csv", Access.READ, timedelta(hours=1), max_uses=1)
     self.storage.redeem(published.id, Access.READ)     the entrypoint, when the id comes back
 
-    domain/      ObjectStore (the port), ObjectRef, StoredObject, Access, Publication, Grant, Refusal;
-                 ObjectNotFound, ObjectAlreadyExists, PublicationRefused
+    domain/      ObjectStore (the port), ObjectRef, StoredObject, ObjectStream, Access, Publication, Grant, Refusal;
+                 ObjectNotFound, ObjectAlreadyExists, PublicationRefused, FetchRefused, FetchFailed,
+                 FetchRefusal
     adapters/    InMemoryObjectStore, LocalObjectStore, S3CompatibleObjectStore
     entrypoint/  ObjectStorage, the facade a project injects
 """
@@ -22,14 +26,18 @@ from sincpro_framework.data_layer.object_storage.adapters.s3_compatible import (
     S3CompatibleObjectStore,
 )
 from sincpro_framework.data_layer.object_storage.domain.exceptions import (
+    FetchFailed,
+    FetchRefused,
     ObjectAlreadyExists,
     ObjectNotFound,
     PublicationRefused,
 )
+from sincpro_framework.data_layer.object_storage.domain.fetch import FetchRefusal
 from sincpro_framework.data_layer.object_storage.domain.object_store import (
     Access,
     ObjectRef,
     ObjectStore,
+    ObjectStream,
     StoredObject,
 )
 from sincpro_framework.data_layer.object_storage.domain.publication import (
@@ -43,6 +51,9 @@ from sincpro_framework.data_layer.object_storage.entrypoint.object_storage impor
 
 __all__ = [
     "Access",
+    "FetchFailed",
+    "FetchRefusal",
+    "FetchRefused",
     "Grant",
     "InMemoryObjectStore",
     "LocalObjectStore",
@@ -51,6 +62,7 @@ __all__ = [
     "ObjectRef",
     "ObjectStorage",
     "ObjectStore",
+    "ObjectStream",
     "Publication",
     "PublicationRefused",
     "Refusal",

sincpro_framework-3.26.0/sincpro_framework/data_layer/object_storage/adapters/http_source.py

@@ -0,0 +1,172 @@
+"""`HttpSource`: the bytes of a URL as its server sends them, read by a store — the standard library's
+`urllib`, a redirect followed only when told and each hop judged, the bytes counted against a size
+and a time as they come.
+
+    body = HttpSource().open("https://cdn.acme.bo/scan.pdf", timedelta(seconds=30), {}, False,
+                             judged, max_bytes=50 * MB)
+    body.content_type            ->  "application/pdf"
+    store.put(key, io.BufferedReader(body), …)     read to its end, or refused on the way
+
+Context: what `urllib` raises is said in object storage's words — a redirect not followed or a
+client error (4xx) is `FetchRefused`, a server error (5xx), a host that cannot be reached or a time
+run out is `FetchFailed` — so the service judges a fetch without knowing HTTP. A refusal raised
+while a store reads is also kept on the body (`refusal`): a store that wraps what its reader raised
+(a bucket's `ExternalServiceError`) is seen through.
+"""
+
+import io
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Callable, Mapping
+from datetime import timedelta
+from typing import Any
+
+from sincpro_framework.data_layer.object_storage.domain.exceptions import (
+    FetchFailed,
+    FetchRefused,
+)
+from sincpro_framework.data_layer.object_storage.domain.fetch import FetchRefusal
+
+
+class Redirects(urllib.request.HTTPRedirectHandler):
+    """A redirect followed only when told, each new URL judged first."""
+
+    def __init__(self, follow: bool, judged: Callable[[str], None]) -> None:
+        """`follow` the redirects or not; `judged` raises for a URL the fetch does not take."""
+        super().__init__()
+        self.follow = follow
+        self.judged = judged
+
+    def redirect_request(
+        self,
+        req: urllib.request.Request,
+        fp: Any,
+        code: int,
+        msg: str,
+        headers: Any,
+        newurl: str,
+    ) -> urllib.request.Request | None:
+        """The request to the new URL once it is judged — none when redirects are not followed,
+        which `urllib` answers as the redirect's own `HTTPError`."""
+        if not self.follow:
+            return None
+        self.judged(newurl)
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+class HttpBody(io.RawIOBase):
+    """A URL's bytes as they come, refused past `max_bytes` or once its time ran out."""
+
+    def __init__(
+        self, response: Any, url: str, max_bytes: int | None, deadline: float
+    ) -> None:
+        """`response` the server's, of `url`; `deadline` on `time.monotonic()`."""
+        super().__init__()
+        self.response = response
+        self.url = url
+        self.max_bytes = max_bytes
+        self.deadline = deadline
+        self.received = 0
+        self.refusal: FetchRefused | FetchFailed | None = None
+        self.content_type: str | None = response.headers.get("Content-Type")
+
+    def readable(self) -> bool:
+        return True
+
+    def readinto(self, buffer: Any) -> int:
+        """The next bytes into `buffer` — `0` at the end.
+
+        1. Past its deadline: `FetchFailed`.
+        2. What has arrived, up to the buffer's size — never waiting for it to fill, so the
+           deadline is judged between every part a slow server sends; a connection that fails
+           or times out while reading: `FetchFailed`.
+        3. Past `max_bytes`: `FetchRefused` (`TOO_LARGE`).
+        Final: what was read; a refusal is kept in `refusal` before it is raised.
+        """
+        if time.monotonic() > self.deadline:
+            self.refusal = FetchFailed(self.url, f"{self.url} did not send its bytes in time")
+            raise self.refusal
+        view = memoryview(buffer).cast("B")
+        try:
+            part = self.response.read1(len(view))
+        except OSError as error:
+            self.refusal = FetchFailed(self.url, f"{self.url} could not be read: {error}")
+            raise self.refusal from error
+        read = len(part)
+        view[:read] = part
+        self.received += read
+        if self.max_bytes is not None and self.received > self.max_bytes:
+            self.refusal = FetchRefused(
+                FetchRefusal.TOO_LARGE,
+                self.url,
+                f"{self.url} sends more than {self.max_bytes} bytes",
+            )
+            raise self.refusal
+        return read
+
+    def close(self) -> None:
+        """Close the server's response with it."""
+        if not self.closed:
+            self.response.close()
+        super().close()
+
+
+class HttpSource:
+    """URLs opened with the standard library."""
+
+    def open(
+        self,
+        url: str,
+        timeout: timedelta,
+        headers: Mapping[str, str],
+        follow_redirects: bool,
+        judged: Callable[[str], None],
+        max_bytes: int | None = None,
+    ) -> HttpBody:
+        """The body of `url`, asked with `headers`, for a store to read — within `timeout` in
+        all, each read of the connection too.
+
+        1. Opened with `follow_redirects`, each redirect's URL `judged` first.
+        2. A redirect not followed or a client error (4xx): `FetchRefused`; a server error
+           (5xx), a host not reached, a time run out: `FetchFailed`.
+        3. A `Content-Length` past `max_bytes`: `FetchRefused` before a byte is read.
+        Final: the body, counted against `max_bytes` and the time left as it is read.
+        """
+        deadline = time.monotonic() + timeout.total_seconds()
+        opener = urllib.request.build_opener(Redirects(follow_redirects, judged))
+        try:
+            response = opener.open(
+                urllib.request.Request(url, headers=dict(headers)),
+                timeout=timeout.total_seconds(),
+            )
+        except urllib.error.HTTPError as error:
+            error.close()
+            if 300 <= error.code < 400:
+                raise FetchRefused(
+                    FetchRefusal.REDIRECTED,
+                    url,
+                    f"{url} answered a redirect ({error.code}) to {error.headers.get('Location')}",
+                    error.code,
+                ) from error
+            if error.code < 500:
+                raise FetchRefused(
+                    FetchRefusal.ANSWERED, url, f"{url} answered {error.code}", error.code
+                ) from error
+            raise FetchFailed(url, f"{url} answered {error.code}", error.code) from error
+        except (urllib.error.URLError, OSError) as error:
+            raise FetchFailed(url, f"{url} could not be reached: {error}") from error
+        declared = response.headers.get("Content-Length")
+        if (
+            max_bytes is not None
+            and declared
+            and declared.isdigit()
+            and int(declared) > max_bytes
+        ):
+            response.close()
+            raise FetchRefused(
+                FetchRefusal.TOO_LARGE,
+                url,
+                f"{url} sends {declared} bytes, more than {max_bytes}",
+            )
+        return HttpBody(response, url, max_bytes, deadline)