httpdex-core 0.1.0__tar.gz

httpdex_core-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.coverage
+__pycache__/
+*.pyc
+dist/
+target/
+.venv/

httpdex_core-0.1.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: httpdex-core
+Version: 0.1.0
+Summary: Async/sync HTTP connection pool. Replaces httpcore.
+Author: Marcelo Trylesinski
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4.0
+Requires-Dist: certifi
+Requires-Dist: httpdex-h2>=0.1.0
+Requires-Dist: httpdex-h3>=0.1.0
+Requires-Dist: httpdex-parse>=0.1.0
+Description-Content-Type: text/markdown
+
+# httpdex-core
+
+Core transport primitives for `httpdex`.
+
+`httpdex-core` provides the async and sync connection pools, per-protocol connection implementations, request/response models, and backend abstractions used by the top-level client.
+
+## Highlights
+
+- Async and sync connection pools
+- HTTP/1.1, HTTP/2, and HTTP/3 connection implementations
+- Shared request and response models
+- Small public surface for building custom transports or experiments
+
+## Public API
+
+- `AsyncConnectionPool`
+- `SyncConnectionPool`
+- `AsyncHTTP11Connection`, `AsyncHTTP2Connection`, `AsyncHTTP3Connection`
+- `SyncHTTP11Connection`, `SyncHTTP2Connection`, `SyncHTTP3Connection`
+- `Request`, `Response`, `URL`, `Origin`
+
+## Role In The Workspace
+
+This package is the transport layer that sits below `httpdex` and above the protocol-specific parser and framing packages.

httpdex_core-0.1.0/README.md

@@ -0,0 +1,24 @@
+# httpdex-core
+
+Core transport primitives for `httpdex`.
+
+`httpdex-core` provides the async and sync connection pools, per-protocol connection implementations, request/response models, and backend abstractions used by the top-level client.
+
+## Highlights
+
+- Async and sync connection pools
+- HTTP/1.1, HTTP/2, and HTTP/3 connection implementations
+- Shared request and response models
+- Small public surface for building custom transports or experiments
+
+## Public API
+
+- `AsyncConnectionPool`
+- `SyncConnectionPool`
+- `AsyncHTTP11Connection`, `AsyncHTTP2Connection`, `AsyncHTTP3Connection`
+- `SyncHTTP11Connection`, `SyncHTTP2Connection`, `SyncHTTP3Connection`
+- `Request`, `Response`, `URL`, `Origin`
+
+## Role In The Workspace
+
+This package is the transport layer that sits below `httpdex` and above the protocol-specific parser and framing packages.

httpdex_core-0.1.0/httpdex_core/__init__.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from httpdex_core._connection import AsyncHTTP11Connection, SyncHTTP11Connection
+from httpdex_core._exceptions import (
+    ConnectError,
+    ConnectionError,
+    ConnectTimeout,
+    PoolTimeout,
+    ReadError,
+    ReadTimeout,
+    UnsupportedProtocol,
+    WriteError,
+    WriteTimeout,
+)
+from httpdex_core._h2_connection import AsyncHTTP2Connection, SyncHTTP2Connection
+from httpdex_core._h3_connection import AsyncHTTP3Connection, SyncHTTP3Connection
+from httpdex_core._mock import MockAsyncBackend, MockSyncBackend
+from httpdex_core._models import URL, AsyncResponseStream, Origin, Request, Response, SyncResponseStream
+from httpdex_core._pool import AsyncConnectionPool, SyncConnectionPool
+
+__all__ = [
+    "AsyncConnectionPool",
+    "AsyncHTTP11Connection",
+    "AsyncHTTP2Connection",
+    "AsyncHTTP3Connection",
+    "AsyncResponseStream",
+    "ConnectError",
+    "ConnectTimeout",
+    "ConnectionError",
+    "MockAsyncBackend",
+    "MockSyncBackend",
+    "Origin",
+    "PoolTimeout",
+    "ReadError",
+    "ReadTimeout",
+    "Request",
+    "Response",
+    "SyncConnectionPool",
+    "SyncHTTP11Connection",
+    "SyncResponseStream",
+    "SyncHTTP2Connection",
+    "SyncHTTP3Connection",
+    "URL",
+    "UnsupportedProtocol",
+    "WriteError",
+    "WriteTimeout",
+]

httpdex_core-0.1.0/httpdex_core/_backends.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+import socket
+import ssl
+
+import anyio
+import anyio.abc
+from anyio.streams.tls import TLSStream
+
+from httpdex_core._exceptions import ConnectError, ConnectTimeout, ReadError, ReadTimeout, WriteError, WriteTimeout
+
+
+class AsyncBackend:
+    async def connect(
+        self,
+        host: str,
+        port: int,
+        *,
+        timeout: float | None = None,
+        ssl_context: ssl.SSLContext | None = None,
+        local_address: str | None = None,
+    ) -> AsyncStream:
+        try:
+            with anyio.fail_after(timeout):
+                stream = await anyio.connect_tcp(
+                    remote_host=host,
+                    remote_port=port,
+                    local_host=local_address,
+                )
+                if ssl_context is not None:
+                    tls_hostname = host.rstrip(".")
+                    tls_stream = await TLSStream.wrap(
+                        stream, ssl_context=ssl_context, hostname=tls_hostname, standard_compatible=False
+                    )
+                    return AsyncStream(tls_stream)
+                return AsyncStream(stream)
+        except TimeoutError as exc:
+            raise ConnectTimeout(str(exc)) from None
+        except OSError as exc:
+            raise ConnectError(str(exc)) from None
+
+
+class AsyncStream:
+    def __init__(self, stream: anyio.abc.ByteStream) -> None:
+        self._stream = stream
+
+    @property
+    def alpn_protocol(self) -> str | None:
+        if isinstance(self._stream, TLSStream):
+            ssl_object = self._stream.extra(anyio.abc.TLSAttribute.ssl_object)
+            if ssl_object is not None:
+                return ssl_object.selected_alpn_protocol()  # type: ignore[union-attr]
+        return None
+
+    async def read(self, max_bytes: int, *, timeout: float | None = None) -> bytes:
+        try:
+            with anyio.fail_after(timeout):
+                data = await self._stream.receive(max_bytes)
+                return data
+        except anyio.EndOfStream:
+            return b""
+        except TimeoutError as exc:
+            raise ReadTimeout(str(exc)) from None
+        except anyio.ClosedResourceError as exc:
+            raise ReadError(str(exc)) from None
+
+    async def write(self, data: bytes, *, timeout: float | None = None) -> None:
+        try:
+            with anyio.fail_after(timeout):
+                view = memoryview(data)
+                await self._stream.send(bytes(view))
+        except TimeoutError as exc:
+            raise WriteTimeout(str(exc)) from None
+        except anyio.ClosedResourceError as exc:
+            raise WriteError(str(exc)) from None
+
+    async def aclose(self) -> None:
+        await self._stream.aclose()
+
+    def is_readable(self) -> bool:
+        # Intentionally no socket poll here - checked only on use.
+        return True
+
+
+class SyncBackend:
+    def connect(
+        self,
+        host: str,
+        port: int,
+        *,
+        timeout: float | None = None,
+        ssl_context: ssl.SSLContext | None = None,
+        local_address: str | None = None,
+    ) -> SyncStream:
+        try:
+            sock = socket.create_connection(
+                (host, port),
+                timeout=timeout,
+                source_address=(local_address, 0) if local_address else None,
+            )
+            sock.settimeout(None)
+            if ssl_context is not None:
+                tls_hostname = host.rstrip(".")
+                sock = ssl_context.wrap_socket(sock, server_hostname=tls_hostname)
+            return SyncStream(sock)
+        except TimeoutError as exc:
+            raise ConnectTimeout(str(exc)) from None
+        except OSError as exc:
+            raise ConnectError(str(exc)) from None
+
+
+class SyncStream:
+    def __init__(self, sock: socket.socket | ssl.SSLSocket) -> None:
+        self._sock = sock
+
+    @property
+    def alpn_protocol(self) -> str | None:
+        if isinstance(self._sock, ssl.SSLSocket):
+            return self._sock.selected_alpn_protocol()
+        return None
+
+    def read(self, max_bytes: int, *, timeout: float | None = None) -> bytes:
+        self._sock.settimeout(timeout)
+        try:
+            data = self._sock.recv(max_bytes)
+            return data
+        except TimeoutError as exc:
+            raise ReadTimeout(str(exc)) from None
+        except OSError as exc:
+            raise ReadError(str(exc)) from None
+
+    def write(self, data: bytes, *, timeout: float | None = None) -> None:
+        self._sock.settimeout(timeout)
+        view = memoryview(data)
+        try:
+            while view:
+                sent = self._sock.send(view)
+                view = view[sent:]
+        except TimeoutError as exc:
+            raise WriteTimeout(str(exc)) from None
+        except OSError as exc:
+            raise WriteError(str(exc)) from None
+
+    def close(self) -> None:
+        self._sock.close()
+
+    def is_readable(self) -> bool:
+        return True
+
+
+class AsyncUDPBackend:
+    async def connect(self, host: str, port: int, *, timeout: float | None = None) -> AsyncUDPSocket:
+        try:
+            with anyio.fail_after(timeout):
+                udp_socket = await anyio.create_connected_udp_socket(remote_host=host, remote_port=port)
+                return AsyncUDPSocket(udp_socket)
+        except TimeoutError as exc:
+            raise ConnectTimeout(str(exc)) from None
+        except OSError as exc:
+            raise ConnectError(str(exc)) from None
+
+
+class AsyncUDPSocket:
+    def __init__(self, socket: anyio.abc.ConnectedUDPSocket) -> None:
+        self._socket = socket
+
+    async def send(self, data: bytes) -> None:
+        try:
+            await self._socket.send(item=data)
+        except OSError as exc:
+            raise WriteError(str(exc)) from None
+
+    async def receive(self, *, timeout: float | None = None) -> bytes:
+        try:
+            with anyio.fail_after(timeout):
+                return await self._socket.receive()
+        except TimeoutError as exc:
+            raise ReadTimeout(str(exc)) from None
+        except anyio.ClosedResourceError as exc:
+            raise ReadError(str(exc)) from None
+
+    async def aclose(self) -> None:
+        await self._socket.aclose()
+
+
+class SyncUDPBackend:
+    def connect(self, host: str, port: int, *, timeout: float | None = None) -> SyncUDPSocket:
+        try:
+            sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+            sock.settimeout(timeout)
+            sock.connect((host, port))
+            sock.settimeout(None)
+            return SyncUDPSocket(sock)
+        except TimeoutError as exc:
+            raise ConnectTimeout(str(exc)) from None
+        except OSError as exc:
+            raise ConnectError(str(exc)) from None
+
+
+class SyncUDPSocket:
+    def __init__(self, sock: socket.socket) -> None:
+        self._sock = sock
+
+    def send(self, data: bytes) -> None:
+        try:
+            self._sock.send(data)
+        except OSError as exc:
+            raise WriteError(str(exc)) from None
+
+    def receive(self, *, timeout: float | None = None) -> bytes:
+        self._sock.settimeout(timeout)
+        try:
+            data = self._sock.recv(65536)
+            return data
+        except TimeoutError as exc:
+            raise ReadTimeout(str(exc)) from None
+        except OSError as exc:
+            raise ReadError(str(exc)) from None
+
+    def close(self) -> None:
+        self._sock.close()

httpdex_core-0.1.0/httpdex_core/_connection.py

@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+import enum
+import time
+
+import httpdex_parse
+
+from httpdex_core._backends import AsyncStream, SyncStream
+from httpdex_core._models import AsyncResponseStream, Origin, Request, Response, SyncResponseStream
+
+
+class ConnectionStatus(enum.Enum):
+    NEW = enum.auto()
+    ACTIVE = enum.auto()
+    IDLE = enum.auto()
+    CLOSED = enum.auto()
+
+
+class AsyncHTTP11Connection:
+    def __init__(self, origin: Origin, stream: AsyncStream, *, keepalive_expiry: float | None = 5.0) -> None:
+        self._origin = origin
+        self._stream = stream
+        self._h11 = httpdex_parse.Connection(httpdex_parse.CLIENT)
+        self._status = ConnectionStatus.IDLE
+        self._expire_at: float | None = None
+        self._keepalive_expiry = keepalive_expiry
+        self._timeout: float | None = None
+
+    @property
+    def origin(self) -> Origin:
+        return self._origin
+
+    @property
+    def status(self) -> ConnectionStatus:
+        return self._status
+
+    def is_idle(self) -> bool:
+        return self._status is ConnectionStatus.IDLE
+
+    def is_closed(self) -> bool:
+        return self._status is ConnectionStatus.CLOSED
+
+    def is_available(self) -> bool:
+        return self._status is ConnectionStatus.IDLE
+
+    def has_expired(self) -> bool:
+        if self._expire_at is None:
+            return False
+        now = time.monotonic()
+        return now > self._expire_at
+
+    async def handle_async_request(
+        self,
+        request: Request,
+        *,
+        timeout: float | None = None,
+    ) -> tuple[Response, AsyncResponseStream]:
+        self._status = ConnectionStatus.ACTIVE
+        self._timeout = timeout
+        try:
+            return await self._send_request_and_read_response(request)
+        except BaseException:
+            self._status = ConnectionStatus.CLOSED
+            await self._stream.aclose()
+            raise
+
+    async def _send_request_and_read_response(self, request: Request) -> tuple[Response, AsyncResponseStream]:
+        # Send request.
+        h11_request = httpdex_parse.Request(
+            method=request.method,
+            target=request.url.target,
+            headers=request.headers,
+        )
+        await self._stream.write(self._h11.send(h11_request), timeout=self._timeout)
+
+        if request.stream is not None:
+            async for chunk in request.stream:  # type: ignore[union-attr]  # pragma: no branch
+                body_data = self._h11.send(httpdex_parse.Data(data=chunk))
+                if body_data:
+                    await self._stream.write(body_data, timeout=self._timeout)
+
+        eom_data = self._h11.send(httpdex_parse.EndOfMessage())
+        if eom_data:
+            await self._stream.write(eom_data, timeout=self._timeout)
+
+        # Read response.
+        response_event = await self._read_until_event(
+            (httpdex_parse.Response, httpdex_parse.InformationalResponse),
+        )
+        while isinstance(response_event, httpdex_parse.InformationalResponse):
+            response_event = await self._read_until_event(
+                (httpdex_parse.Response, httpdex_parse.InformationalResponse),
+            )
+        assert isinstance(response_event, httpdex_parse.Response)
+
+        # Build a lazy stream that reads body chunks on demand.
+        async def read_next_chunk() -> bytes | None:
+            event = await self._read_until_event((httpdex_parse.Data, httpdex_parse.EndOfMessage))
+            if isinstance(event, httpdex_parse.Data):
+                return event.data
+            return None  # EndOfMessage
+
+        body_stream = AsyncResponseStream(read_next_chunk, self._mark_idle)
+
+        response_headers: list[tuple[bytes, bytes]] = [(rn, v) for rn, _, v in response_event.headers]
+        return Response(
+            status=response_event.status_code,
+            headers=response_headers,
+            stream=None,
+        ), body_stream
+
+    async def _read_until_event(
+        self,
+        event_types: tuple[type, ...],
+    ) -> httpdex_parse.Request | httpdex_parse.Response | httpdex_parse.InformationalResponse | httpdex_parse.Data | httpdex_parse.EndOfMessage:
+        while True:
+            event = self._h11.next_event()
+            if isinstance(event, event_types):
+                return event
+            if event is httpdex_parse.NEED_DATA:
+                data = await self._stream.read(65536, timeout=self._timeout)
+                self._h11.receive_data(data if data else b"")
+                continue
+            if event is httpdex_parse.PAUSED:  # pragma: no cover
+                break
+        raise RuntimeError("unexpected parser state")  # pragma: no cover
+
+    def _mark_idle(self) -> None:
+        try:
+            self._h11.start_next_cycle()
+            self._status = ConnectionStatus.IDLE
+            if self._keepalive_expiry is not None:
+                self._expire_at = time.monotonic() + self._keepalive_expiry
+        except httpdex_parse.LocalProtocolError:
+            self._status = ConnectionStatus.CLOSED
+
+    async def aclose(self) -> None:
+        self._status = ConnectionStatus.CLOSED
+        await self._stream.aclose()
+
+
+class SyncHTTP11Connection:
+    def __init__(self, origin: Origin, stream: SyncStream, *, keepalive_expiry: float | None = 5.0) -> None:
+        self._origin = origin
+        self._stream = stream
+        self._h11 = httpdex_parse.Connection(httpdex_parse.CLIENT)
+        self._status = ConnectionStatus.IDLE
+        self._expire_at: float | None = None
+        self._keepalive_expiry = keepalive_expiry
+        self._timeout: float | None = None
+
+    @property
+    def origin(self) -> Origin:
+        return self._origin
+
+    @property
+    def status(self) -> ConnectionStatus:
+        return self._status
+
+    def is_idle(self) -> bool:
+        return self._status is ConnectionStatus.IDLE
+
+    def is_closed(self) -> bool:
+        return self._status is ConnectionStatus.CLOSED
+
+    def is_available(self) -> bool:
+        return self._status is ConnectionStatus.IDLE
+
+    def has_expired(self) -> bool:
+        if self._expire_at is None:
+            return False
+        now = time.monotonic()
+        return now > self._expire_at
+
+    def handle_request(
+        self,
+        request: Request,
+        *,
+        timeout: float | None = None,
+    ) -> tuple[Response, SyncResponseStream]:
+        self._status = ConnectionStatus.ACTIVE
+        self._timeout = timeout
+        try:
+            return self._send_request_and_read_response(request)
+        except BaseException:
+            self._status = ConnectionStatus.CLOSED
+            self._stream.close()
+            raise
+
+    def _send_request_and_read_response(self, request: Request) -> tuple[Response, SyncResponseStream]:
+        h11_request = httpdex_parse.Request(
+            method=request.method,
+            target=request.url.target,
+            headers=request.headers,
+        )
+        self._stream.write(self._h11.send(h11_request), timeout=self._timeout)
+
+        if request.stream is not None:
+            for chunk in request.stream:  # type: ignore[union-attr]
+                body_data = self._h11.send(httpdex_parse.Data(data=chunk))
+                if body_data:
+                    self._stream.write(body_data, timeout=self._timeout)
+
+        eom_data = self._h11.send(httpdex_parse.EndOfMessage())
+        if eom_data:
+            self._stream.write(eom_data, timeout=self._timeout)
+
+        response_event = self._read_until_event(
+            (httpdex_parse.Response, httpdex_parse.InformationalResponse),
+        )
+        while isinstance(response_event, httpdex_parse.InformationalResponse):
+            response_event = self._read_until_event(
+                (httpdex_parse.Response, httpdex_parse.InformationalResponse),
+            )
+        assert isinstance(response_event, httpdex_parse.Response)
+
+        # Build a lazy stream that reads body chunks on demand.
+        def read_next_chunk() -> bytes | None:
+            event = self._read_until_event((httpdex_parse.Data, httpdex_parse.EndOfMessage))
+            if isinstance(event, httpdex_parse.Data):
+                return event.data
+            return None  # EndOfMessage
+
+        body_stream = SyncResponseStream(read_next_chunk, self._mark_idle)
+
+        response_headers: list[tuple[bytes, bytes]] = [(rn, v) for rn, _, v in response_event.headers]
+        return Response(
+            status=response_event.status_code,
+            headers=response_headers,
+        ), body_stream
+
+    def _read_until_event(
+        self,
+        event_types: tuple[type, ...],
+    ) -> httpdex_parse.Request | httpdex_parse.Response | httpdex_parse.InformationalResponse | httpdex_parse.Data | httpdex_parse.EndOfMessage:
+        while True:
+            event = self._h11.next_event()
+            if isinstance(event, event_types):
+                return event
+            if event is httpdex_parse.NEED_DATA:
+                data = self._stream.read(65536, timeout=self._timeout)
+                self._h11.receive_data(data if data else b"")
+                continue
+            if event is httpdex_parse.PAUSED:  # pragma: no cover
+                break
+        raise RuntimeError("unexpected parser state")  # pragma: no cover
+
+    def _mark_idle(self) -> None:
+        try:
+            self._h11.start_next_cycle()
+            self._status = ConnectionStatus.IDLE
+            if self._keepalive_expiry is not None:
+                self._expire_at = time.monotonic() + self._keepalive_expiry
+        except httpdex_parse.LocalProtocolError:
+            self._status = ConnectionStatus.CLOSED
+
+    def close(self) -> None:
+        self._status = ConnectionStatus.CLOSED
+        self._stream.close()