konnect.http 0.1.0__tar.gz

konnect_http-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.1
+Name: konnect.http
+Version: 0.1.0
+Summary: Pythonic, asynchronous HTTP client
+Author-email: Dom Sekotill <dom.sekotill@kodo.org.uk>
+Requires-Python: ~=3.11
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
+Classifier: Topic :: Internet
+Requires-Dist: anyio ~=4.0
+Requires-Dist: konnect.curl ~=0.1.0

konnect_http-0.1.0/konnect/http/__init__.py

@@ -0,0 +1,6 @@
+# Copyright 2023-2024  Dom Sekotill <dom.sekotill@kodo.org.uk>
+
+from .request import Method as Method
+from .request import Request as Request
+from .response import Response as Response
+from .session import Session as Session

konnect_http-0.1.0/konnect/http/authenticators.py

@@ -0,0 +1,39 @@
+# Copyright 2023  Dom Sekotill <dom.sekotill@kodo.org.uk>
+
+"""
+Authentication handlers for adding auth data to requests and implementing auth flows
+
+The two entrypoints for all concrete authentication handler classes are
+`AuthHandler.prepare_request()` for up-front modifications to requests and pre-request
+authentication flows, and `AuthHandler.process_response()` for post-request authentication
+flows.
+"""
+
+from typing import Protocol
+
+from .request import CurlRequest
+from .response import Response
+
+
+class AuthHandler(Protocol):
+	"""
+	Abstract definition of authentication handlers' entrypoints
+	"""
+
+	async def prepare_request(self, request: CurlRequest) -> None:
+		"""
+		Process a request instance before the request is enacted
+
+		This method can be used by handlers to modify requests (such as adding headers or
+		adding session cookies); it is a coroutine to allow handlers to inject an auth-flow
+		before the request.  Any such flow SHOULD use the request's session.
+		"""
+
+	async def process_response(self, request: CurlRequest, response: Response) -> Response:
+		"""
+		Examine a response to a request and perform any follow-up actions
+
+		This method may return the passed response if the request was authenticated and no
+		further actions need to be taken; or further requests can be made if necessary,
+		after which a new successful response to an identical request must be returned.
+		"""

konnect_http-0.1.0/konnect/http/cookies/__init__.py

@@ -0,0 +1,4 @@
+# Copyright 2023  Dom Sekotill <dom.sekotill@kodo.org.uk>
+
+from .cookie import Cookie as Cookie
+from .cookie import check_cookie as check_cookie

konnect_http-0.1.0/konnect/http/cookies/cookie.py

@@ -0,0 +1,137 @@
+# Copyright 2023  Dom Sekotill <dom.sekotill@kodo.org.uk>
+
+"""
+Module containing the core Cookie class and checking functions
+"""
+
+from datetime import datetime as DateTime
+from datetime import timedelta as TimeDelta
+from ipaddress import IPv4Address
+from ipaddress import IPv6Address
+from ipaddress import ip_address
+from typing import Self
+from urllib.parse import urlparse
+
+from .set_cookie_parser import TokenType
+from .set_cookie_parser import tokenise
+
+
+class Cookie:
+	"""
+	Client-side cookie data class
+	"""
+
+	def __init__(
+		self,
+		name: str, value: bytes,
+		expires: DateTime|TimeDelta|None,
+		domain: str, path: str, *,
+		secure: bool = False, httponly: bool = False, exactdomain: bool = True,
+	):
+		self.name = name
+		self.value = value
+		self.expires = (
+			None if expires is None else
+			expires if isinstance(expires, DateTime) else
+			(DateTime.now() + expires)
+		)
+		self.domain = domain
+		self.path = path
+		self.secure = secure
+		self.httponly = httponly
+		self.exactdomain = exactdomain
+
+	def __bytes__(self) -> bytes:
+		return b"=".join((self.name.encode("ascii"), self.value))
+
+	@classmethod
+	def from_header(cls, header: bytes, domain: str, path: str) -> Self:
+		"""
+		Return a `Cookie` from an HTTP "Set-Cookie:" header string
+		"""
+		self = cls("", b"", None, domain, path)
+		for token in tokenise(header):
+			if token[0] is TokenType.NAME:
+				self.name = token[1]
+			elif token[0] is TokenType.VALUE:
+				self.value = token[1]
+			elif token[0] is TokenType.DOMAIN:
+				# TODO: check cookie domain allowed
+				self.domain = token[1]
+				self.exactdomain = False
+			elif token[0] is TokenType.PATH:
+				# TODO: check cookie path allowed
+				self.path = token[1]
+			elif token[0] is TokenType.EXPIRES:
+				self.expires = token[1]
+			elif token[0] is TokenType.MAX_AGE:
+				self.expires = DateTime.now() + token[1]
+			elif token[0] is TokenType.SECURE:
+				self.secure = token[1]
+			elif token[0] is TokenType.HTTP_ONLY:
+				self.httponly = token[1]
+		assert self.name != ""
+		return self
+
+	def as_header(self, header_name: str = "Cookie") -> bytes:
+		"""
+		Return the cookie formatted as an HTTP header
+		"""
+		raise NotImplementedError
+
+
+def check_cookie(cookie: Cookie, url: str) -> bool:
+	"""
+	Return whether the cookie should be sent with the request
+	"""
+	if cookie.expires and cookie.expires <= DateTime.now():
+		return False
+
+	parts = urlparse(url)
+	if not parts.hostname:
+		raise ValueError("URLs must be absolute")
+
+	cookie_host = normalencode_host(cookie.domain)
+	url_host = normalencode_host(parts.hostname)
+	if cookie_host != url_host:
+		if not isinstance(cookie_host, bytes) or not isinstance(url_host, bytes):
+			return False
+		if cookie.domain[-1] == ".":  # Treat trailing `.` as marker for exact match
+			return False
+		if not url_host.endswith(b"." + cookie_host):
+			return False
+
+	cookie_path = normalise_path(cookie.path)
+	url_path = normalise_path(parts.path)
+	if cookie_path != url_path:
+		prefix, _, suffix = url_path.partition(cookie_path)
+		if prefix:
+			return False
+		if suffix and suffix[0] != "/":
+			return False
+
+	return True
+
+
+def normalencode_host(host: str) -> bytes|IPv4Address|IPv6Address:
+	"""
+	Turn a host name or address string into a normalised host name or IP address object
+
+	Host name normalisation includes case lowering, and encoding unicode labels according to
+	IDNA standards.
+	"""
+	try:
+		return ip_address(host)
+	except ValueError:
+		return host.strip(".").lower().encode("idna")
+
+
+def normalise_path(path: str) -> str:
+	"""
+	Normalise a cookie path by stripping leaf components and replacing invalid paths with /
+
+	Note that the output path *always* ends with a "/".
+	"""
+	if not path or path[0] != "/":
+		return "/"
+	return path.rsplit("/", 1)[0] + "/"

konnect_http-0.1.0/konnect/http/cookies/dates.py

@@ -0,0 +1,89 @@
+# Copyright 2023  Dom Sekotill <dom.sekotill@kodo.org.uk>
+
+"""
+Parsing of timestamps used for the "expires" attribute of "Set-Cookie:" headers
+
+For historical reasons, although the current standards prefer RFC822#section-5 dates
+(updated by RFC1123#section-5.2.14) as stated in RFC2616#section-3.3.1, user-agents must be
+able to parse a wide variety of formats.  This is module provides an implementation of the
+algorithm described in RFC6265#section-5.1.1
+"""
+
+import re
+from datetime import datetime as DateTime
+from typing import TypedDict
+
+__all__ = ["dateparse"]
+
+MONTHS = [
+	"jan", "feb", "mar", "apr", "may", "jun",
+	"jul", "aug", "sep", "oct", "nov", "dec",
+]
+
+DATETIME_RE = re.compile(
+	r"""(?ix)
+	(?:^|[\t\x20-\x2f\x3b-\x40\x5b-\x60\x7b-\x7e]+)  # Start or leading delimiter chars
+	(?P<match>
+		(?P<month>jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec) |
+		(?P<hour>[0-9]{1,2}):(?P<min>[0-9]{1,2}):(?P<sec>[0-9]{1,2}) (?=[^0-9]*) |
+		(?P<number>[0-9]{1,4}) (?=[^0-9]*)
+	)
+	""",
+)
+
+
+class DateTimeArgs(TypedDict):
+	"""
+	A dictionary of keyword arguments to pass to `DateTime`
+	"""
+
+	year: int
+	month: int
+	day: int
+	hour: int
+	minute: int
+	second: int
+
+
+def dateparse(date: str) -> DateTime:
+	"""
+	Parse a "Set-Cookie:" expiration date string
+	"""
+	vals = DateTimeArgs(year=0, month=0, day=0, hour=0, minute=0, second=0)
+	found_time = found_day = found_month = found_year = False
+	for match in DATETIME_RE.finditer(date):
+		match match.groupdict():
+			case {"hour": str(sh), "min": str(sm), "sec": str(ss)} if not found_time:
+				if not (
+					(0 <= (hour := int(sh)) < 24) and
+					(0 <= (minute := int(sm)) < 60) and
+					(0 <= (second := int(ss)) < 60)
+				):
+					raise ValueError(f"Invalid time: {sh}:{sm}:{ss}")
+				found_time = True
+				vals["hour"] = hour
+				vals["minute"] = minute
+				vals["second"] = second
+			case {"number": str(sd)} if not found_day and 1 <= len(sd) <= 2:
+				if not (0 < (day := int(sd)) <= 31):
+					raise ValueError(f"Invalid day of month: {sd}")
+				found_day = True
+				vals["day"] = day
+			case {"month": str(month)} if not found_month:
+				found_month = True
+				vals["month"] = 1 + MONTHS.index(month.lower())
+			case {"number": str(sy)} if not found_year and 2 <= len(sy) <= 4:
+				found_year = True
+				year = int(sy)
+				if 0 <= year < 70:
+					year += 2000
+				elif 70 <= year < 100:
+					year += 1900
+				elif year < 1601:
+					raise ValueError("Dates before year 1601 are invalid")
+				vals["year"] = year
+			case _:
+				raise ValueError(f"Unexpected value: {match.group('match')}")
+	if not (found_time and found_day and found_month and found_year):
+		raise ValueError(f"Incomplete date-time: {date} ({vals})")
+	return DateTime(**vals)

konnect_http-0.1.0/konnect/http/cookies/set_cookie_parser.py

@@ -0,0 +1,134 @@
+# Copyright 2023  Dom Sekotill <dom.sekotill@kodo.org.uk>
+
+"""
+Tokenising of cookies and attributes from "Set-Cookie:" HTTP headers
+"""
+
+import re
+from collections.abc import Iterator
+from datetime import datetime as DateTime
+from datetime import timedelta as TimeDelta
+from enum import Enum
+from enum import auto
+from typing import Literal
+from typing import TypeAlias
+from typing import Union
+from urllib.parse import unquote as urldecode
+
+from .dates import dateparse
+
+__all__ = ["tokenise"]
+
+DOT = ord(".")
+SLASH = ord("/")
+
+HEADER_RE = re.compile(
+	rb"""(?ix)
+	^Set-Cookie:
+		\s* (?P<name>[^][()<>@,;:\\"/?={} \t]*)
+		\s* (?P<value>[=][^;]*)?  # value includes "="
+	| [;] \s*
+		(?P<attr_name> expires | max-age | domain | path | secure | httpOnly ) \s*
+		(?:[=] (?P<attr_value>[^;]*))?
+	\s*
+	""",
+)
+
+
+class TokenType(Enum):
+
+	NAME = auto()
+	VALUE = auto()
+	DOMAIN = auto()
+	PATH = auto()
+	EXPIRES = auto()
+	MAX_AGE = auto()
+	SECURE = auto()
+	HTTP_ONLY = auto()
+
+
+Token: TypeAlias = Union[
+	tuple[Literal[TokenType.NAME, TokenType.DOMAIN, TokenType.PATH], str],
+	tuple[Literal[TokenType.VALUE], bytes],
+	tuple[Literal[TokenType.EXPIRES], DateTime],
+	tuple[Literal[TokenType.MAX_AGE], TimeDelta],
+	tuple[Literal[TokenType.SECURE, TokenType.HTTP_ONLY], bool],
+]
+
+
+def tokenise(header: bytes) -> Iterator[Token]:
+	"""
+	Yield tokenised parts of a "Set-Cookie:" header
+
+	Yields token (name, value) tuples; the type of a token value is token dependant.
+	The algorithm used is the more permissive one for user agents in RFC6265#section-5.1
+
+	This parser is guaranteed to yield the following tokens or raise `ValueError`:
+
+	- name: a non-empty raw byte string
+	- value: a raw byte string that may be empty
+	- secure: boolean
+	- http-only: boolean
+
+	The parser may optionally yield the following tokens:
+
+	- domain: a normalised, decoded domain name (str)
+	- path: a decoded, absolute path value (str)
+	- expires: a `datetime.datetime` instance
+	- max-age: a `datetime.timedelta` instance
+	"""
+	if not header.startswith(b"Set-Cookie:"):
+		raise ValueError(f"Not a Set-Cookie header: {header!r}")
+
+	secure = http_only = False
+
+	for match in HEADER_RE.finditer(header):
+		name, value = match.group("name", "value")
+		if name is None:
+			name, value = match.group("attr_name", "attr_value")
+			assert name is not None
+		elif name == b"":
+			raise ValueError("Cookies require a name")
+		elif value is None:
+			raise ValueError("Cookies require a value")
+		else:
+			yield TokenType.NAME, name.strip().decode("ascii")
+			yield TokenType.VALUE, value.strip()[1:]  # strip leading "="
+			continue
+
+		match (name.strip().lower(), value):
+			case [b"expires", bytes(expires)]:
+				yield TokenType.EXPIRES, dateparse(expires.decode("ascii"))
+			case [b"max-age", bytes(max_age)]:
+				yield TokenType.MAX_AGE, TimeDelta(seconds=int(max_age, 10))
+			case [b"domain", bytes(domain)]:
+				domain = domain.strip()
+				if domain[-1] == DOT:
+					continue  # domains ending with "." MUST be ignored
+				if domain[0] == DOT:
+					domain = domain.lstrip(b".")
+				# TODO: Additional check for disallowed chars?
+				yield TokenType.DOMAIN, domain.decode("idna").lower()
+			case [b"path", bytes(path)]:
+				path = path.strip()
+				if path[0] != SLASH:
+					continue  # relative paths MUST be ignored
+				yield TokenType.PATH, urldecode(path)
+			case [b"secure", _]:
+				secure = True
+				yield TokenType.SECURE, True
+			case [b"httponly", _]:
+				http_only = True
+				yield TokenType.HTTP_ONLY, True
+			case [b"expires" | b"max-age" | b"domain" | b"path", None]:
+				raise ValueError(f"Cookie attribute {name.decode()!r} requires a value")
+			case _:  # pragma: no-cover
+				raise RuntimeError(
+					f"Unhandled attribute or missing value"
+					f" ({match.group(0)!r} -> {match.groupdict()})",
+				)
+
+	if not secure:
+		yield TokenType.SECURE, False
+	if not http_only:
+		yield TokenType.HTTP_ONLY, False

konnect_http-0.1.0/konnect/http/exceptions.py

@@ -0,0 +1,11 @@
+# Copyright 2023  Dom Sekotill <dom.sekotill@kodo.org.uk>
+
+"""
+Publicly exposed exception classes used in the package
+"""
+
+
+class UnsupportedSchemeError(ValueError):
+	"""
+	An exception for non-HTTP URL schemes
+	"""

konnect_http-0.1.0/konnect/http/request.py

@@ -0,0 +1,375 @@
+# Copyright 2023-2024  Dom Sekotill <dom.sekotill@kodo.org.uk>
+
+"""
+Module providing a `konnect.curl.Request` implementation for HTTP requests
+
+Using the `Request` class directly allows for finer-grained control of a request, including
+asynchronously sending chunked data.
+
+For many uses, there is a simple interface supplied by the `Session` class which does not
+require users to interact directly with the classes supplied in this module.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from enum import Flag
+from enum import auto
+from ipaddress import IPv4Address
+from ipaddress import IPv6Address
+from pathlib import Path
+from typing import TYPE_CHECKING
+from typing import Literal
+from typing import Mapping
+from typing import TypeAlias
+from typing import Union
+from urllib.parse import urlparse
+
+from konnect.curl import MILLISECONDS
+from pycurl import *
+
+from .cookies import check_cookie
+from .exceptions import UnsupportedSchemeError
+from .response import ReadStream
+from .response import Response
+
+if TYPE_CHECKING:
+	from .authenticators import AuthHandler
+	from .session import Session
+
+ServiceIdentifier: TypeAlias = tuple[Literal["http", "https"], str]
+TransportInfo: TypeAlias = Union[
+	tuple[IPv4Address | IPv6Address | str, int],
+	Path,
+]
+
+
+__all__ = [
+	"Method",
+	"Transport",
+	"Request",
+]
+
+
+class Method(Enum):
+	"""
+	HTTP methods supported by konnect.http
+	"""
+
+	GET = auto()
+	HEAD = auto()
+	PUT = auto()
+	POST = auto()
+	PATCH = auto()
+	DELETE = auto()
+
+
+class Transport(Flag):
+	"""
+	Transport layer types
+	"""
+
+	TCP = auto()
+	UNIX = auto()
+	TLS = auto()
+
+
+class Phase(Enum):
+
+	INITIAL = auto()
+	HEADERS = auto()
+	BODY_START = auto()
+	BODY_CHUNKS = auto()
+	TRAILERS = auto()
+
+
+class Request:
+	"""
+	This class provides the user-callable API for requests
+	"""
+
+	def __init__(self, session: Session, method: Method, url: str):
+		self._request = CurlRequest(session, method, url)
+
+	def __repr__(self) -> str:
+		return f"<Request {self._request.method.name} {self._request.url}>"
+
+	@property
+	def session(self) -> Session:
+		"""
+		Wrap the underlying request's session attribute
+		"""
+		return self._request.session
+
+	@property
+	def method(self) -> Method:
+		"""
+		Wrap the underlying request's method attribute
+		"""
+		return self._request.method
+
+	@property
+	def url(self) -> str:
+		"""
+		Wrap the underlying request's url attribute
+		"""
+		return self._request.url
+
+	async def write(self, data: bytes, /) -> None:
+		"""
+		Write data to an upload request
+
+		Signal an EOF by writing b""
+		"""
+		await self._request.write(data)
+
+	async def get_response(self) -> Response:
+		"""
+		Progress the request far enough to create a `Response` object and return it
+		"""
+		return await self._request.get_response()
+
+
+class CurlRequest:
+	"""
+	This class provides the `konnect.curl.Request` interface, callbacks and internal API
+
+	It is not intended to be used directly by users.
+	"""
+
+	def __init__(self, session: Session, method: Method, url: str):
+		self.session = session
+		self.method = method
+		self.url = url
+		self._handle: Curl|None = None
+		self._response: Response|None = None
+		self._phase = Phase.INITIAL
+		self._upcomplete = False
+		self._data = b""
+
+	def configure_handle(self, handle: Curl) -> None:
+		"""
+		Configure a konnect.curl.Curl handle for this request
+
+		This is part of the `konnect.curl.Request` interface.
+		"""
+		self._handle = handle
+
+		handle.setopt(URL, self.url)
+
+		match self.method:
+			case Method.HEAD:
+				handle.setopt(NOBODY, True)
+			case Method.PUT:
+				handle.setopt(UPLOAD, True)
+				handle.setopt(INFILESIZE, -1)
+				handle.setopt(READFUNCTION, self._process_input)
+			case Method.POST:
+				handle.setopt(POST, True)
+				handle.setopt(READFUNCTION, self._process_input)
+			case Method.PATCH:
+				handle.setopt(CUSTOMREQUEST, "PATCH")
+				handle.setopt(UPLOAD, True)
+				handle.setopt(INFILESIZE, -1)
+				handle.setopt(READFUNCTION, self._process_input)
+			case Method.DELETE:
+				handle.setopt(CUSTOMREQUEST, "DELETE")
+
+		match get_transport(self.session.transports, self.url):
+			case Path() as path:
+				handle.setopt(UNIX_SOCKET_PATH, path.as_posix())
+			case [(IPv4Address() | IPv6Address() | str()) as host, int(port)]:
+				handle.setopt(CONNECT_TO, [f"::{host}:{port}"])
+			case transport:
+				raise TypeError(f"Unknown transport: {transport!r}")
+
+		handle.setopt(COOKIE, self.get_cookies())
+
+		handle.setopt(VERBOSE, 0)
+		handle.setopt(NOPROGRESS, 1)
+
+		handle.setopt(TIMEOUT_MS, self.session.timeout // MILLISECONDS)
+		handle.setopt(CONNECTTIMEOUT_MS, self.session.connect_timeout // MILLISECONDS)
+
+		handle.setopt(PIPEWAIT, 1)
+		handle.setopt(DEFAULT_PROTOCOL, "https")
+		# handle.setopt(PROTOCOLS_STR, "http,https")
+		# handle.setopt(REDIR_PROTOCOLS_STR, "http,https")
+		handle.setopt(PROTOCOLS, PROTO_HTTP|PROTO_HTTPS)
+		handle.setopt(REDIR_PROTOCOLS, PROTO_HTTP|PROTO_HTTPS)
+		handle.setopt(HEADERFUNCTION, self._process_header)
+		handle.setopt(WRITEFUNCTION, self._process_body)
+
+	def has_response(self) -> bool:
+		"""
+		Return whether calling `response()` will return a value or raise `LookupError`
+
+		This is part of the `konnect.curl.Request` interface.
+		"""
+		match self._phase:
+			case Phase.BODY_START:
+				assert self._response is not None
+				return self._response.code >= 200
+			case Phase.BODY_CHUNKS:
+				return self._data != b""
+		return False
+
+	def response(self) -> Response|bytes:
+		"""
+		Return a waiting response or raise `LookupError` if there is none
+
+		See `has_response()` for checking for waiting responses.
+
+		This is part of the `konnect.curl.Request` interface.
+		"""
+		if self._phase == Phase.BODY_START:
+			self._phase = Phase.BODY_CHUNKS
+			assert self._response is not None
+			if self._response.code < 200:
+				raise LookupError
+			return self._response
+		if self._phase != Phase.BODY_CHUNKS or not self._data:
+			raise LookupError
+		data, self._data = self._data, b""
+		return data
+
+	def completed(self) -> bytes:
+		"""
+		Complete the transfer by returning the final stream bytes
+
+		This is part of the `konnect.curl.Request` interface.
+		"""
+		assert self._phase == Phase.BODY_CHUNKS
+		data, self._data = self._data, b""
+		return data
+
+	async def write(self, data: bytes, /) -> None:
+		"""
+		Write data to an upload request
+
+		Signal an EOF by writing b""
+		"""
+		# TODO: apply back-pressure when self._data reaches a certain length
+		# TODO: use a nicer buffer implementation than just appending
+		if data == b"":
+			self._upcomplete = True
+		elif self._data:
+			self._data += data
+		else:
+			self._data = data
+		if self._handle:
+			self._handle.pause(PAUSE_CONT)
+
+	def _process_input(self, size: int) -> bytes|int:
+		if self._data:
+			data, self._data = self._data[:size], self._data[size:]
+			return data
+		if self._upcomplete:
+			return b""
+		return READFUNC_PAUSE
+
+	def _process_header(self, data: bytes) -> None:
+		if data.startswith(b"HTTP/"):
+			self._phase = Phase.HEADERS
+			stream = ReadStream(self)
+			self._response = Response(data.decode("ascii"), stream)
+			return
+		assert self._response is not None
+		if data == b"\r\n":
+			self._phase = Phase.BODY_START
+			return
+		if self._phase not in (Phase.HEADERS, Phase.TRAILERS):
+			self._phase = Phase.TRAILERS
+		self._response.headers.append(self._split_field(data))
+
+	def _split_field(self, field: bytes) -> tuple[str, bytes]:
+		assert self._response is not None
+		name, has_sep, value = field.partition(b":")
+		if has_sep:
+			# TODO: test performance of str.lower() vs. bytes.lower()
+			return name.lower().decode("ascii"), value.strip()
+		try:
+			lname = self._response.headers[-1][0]
+		except IndexError:
+			raise ValueError("Non-field value when reading HTTP message fields")
+		else:
+			raise ValueError(f"Non-compliant multi-line field: {lname}")
+
+	def _process_body(self, data: bytes) -> None:
+		self._data += data
+
+	async def get_response(self) -> Response:
+		"""
+		Progress the request far enough to create a `Response` object and return it
+		"""
+		if self._phase != Phase.INITIAL:
+			raise RuntimeError("get_response() can only be called on an unstarted request")
+		auth = get_authenticator(self.session.auth, self.url)
+		if auth is not None:
+			await auth.prepare_request(self)
+		resp = await self.session.multi.process(self)
+		assert isinstance(resp, Response)
+		if auth is not None:
+			resp = await auth.process_response(self, resp)
+		return resp
+
+	async def get_data(self) -> bytes:
+		"""
+		Return chunks of received data from the body of the response to the request
+		"""
+		if self._phase != Phase.BODY_CHUNKS:
+			raise RuntimeError("get_data() can only be called after get_response()")
+		data = await self.session.multi.process(self)
+		assert isinstance(data, bytes), repr(data)
+		return data
+
+	def get_cookies(self) -> bytes:
+		"""
+		Return the encoded cookie values to be sent with the request
+		"""
+		return b"; ".join(
+			bytes(cookie)
+			for cookie in self.session.cookies
+			if check_cookie(cookie, self.url)
+		)
+
+
+def get_transport(
+	transports: Mapping[ServiceIdentifier, TransportInfo],
+	url: str,
+) -> TransportInfo:
+	"""
+	For a given http:// or https:// URL, return suitable transport layer information
+	"""
+	parts = urlparse(url)
+	if parts.hostname is None:
+		raise ValueError("An absolute URL is required")
+	match parts.scheme:
+		case "https" as scheme:
+			default_port = 443
+		case "http" as scheme:
+			default_port = 80
+		case _:
+			raise UnsupportedSchemeError(url)
+	try:
+		return transports[scheme, parts.netloc]
+	except KeyError:
+		return parts.hostname, parts.port or default_port
+
+
+def get_authenticator(
+	authenticators: Mapping[ServiceIdentifier, AuthHandler],
+	url: str,
+) -> AuthHandler|None:
+	"""
+	For a given http:// or https:// URL, return any `AuthHandler` associated with it
+	"""
+	parts = urlparse(url)
+	if parts.hostname is None:
+		raise ValueError("An absolute URL is required")
+	if parts.scheme not in ("http", "https"):
+		raise UnsupportedSchemeError(url)
+	try:
+		return authenticators[parts.scheme, parts.netloc]  # type: ignore[index]
+	except KeyError:
+		return None

konnect_http-0.1.0/konnect/http/response.py

@@ -0,0 +1,191 @@
+# Copyright 2023-2024  Dom Sekotill <dom.sekotill@kodo.org.uk>
+
+"""
+Response classes for HTTP requests
+
+Instances of the classes contained in this module are not created directly by users, instead
+they are returned from `konnect.http.Session` methods.  If needed for typing, they are
+exported from `konnect.http`.
+"""
+
+from __future__ import annotations
+
+from asyncio import IncompleteReadError
+from asyncio import LimitOverrunError
+from collections.abc import AsyncIterator
+from http import HTTPStatus
+from typing import TYPE_CHECKING
+
+from anyio import EndOfStream
+
+if TYPE_CHECKING:
+	from .request import CurlRequest
+
+
+class ReadStream:
+	"""
+	A readable stream for response bodies
+
+	This class implements the methods for `asyncio.StreamReader` and
+	`anyio.abc.ByteReceiveStream`, allowing it to be passed to library functions that may
+	require either of those interfaces.
+	"""
+
+	def __init__(self, request: CurlRequest) -> None:
+		self.request: CurlRequest|None = request
+		self._buffer = b""
+
+	async def __aiter__(self) -> AsyncIterator[bytes]:
+		try:
+			while (chunk := await self.receive()):
+				yield chunk
+		except EndOfStream:
+			return
+
+	async def aclose(self) -> None:
+		"""
+		Close the stream
+
+		Implements `anyio.abc.AsyncResource.aclose()`
+		"""
+		self.request = None
+
+	async def _receive(self) -> bytes:
+		# Wait until a chunk is available, and return it. Raise EndOfStream if indicated
+		# with an empty byte chunk.
+		if self._buffer:
+			data, self._buffer = self._buffer, b""
+			return data
+		if self.request is None:
+			raise EndOfStream
+		if (data := await self.request.get_data()) == b"":
+			self.request = None
+			raise EndOfStream
+		return data
+
+	async def receive(self, max_bytes: int = 65536, /) -> bytes:
+		"""
+		Read and return up to `max_bytes` bytes from the stream
+
+		Implements `anyio.abc.ByteReceiveStream.receive()`
+		"""
+		data = await self._receive()
+		if max_bytes >= 0:
+			data, self._buffer = data[:max_bytes], data[max_bytes:]
+		return data
+
+	async def readuntil(self, separator: bytes = b'\n') -> bytes:
+		"""
+		Read and return up-to and including the first instance of `separator` in the stream
+
+		If an EOF occurs before encountering the separator `IncompleteReadError` is raised.
+		If the separator is not encountered within the configured buffer size limit for the
+		stream, `LimitOverrunError` is raised and the buffer left intact.
+
+		Implements `asyncio.StreamReader.readuntil()`
+		"""
+		chunks = list[bytes]()
+		length = 0
+		split = -1
+		while split < 0:
+			try:
+				data = await self._receive()
+			except EndOfStream:
+				raise IncompleteReadError(b''.join(chunks), None)
+			if (split := data.find(separator)) >= 0:
+				split += len(separator)
+				assert len(data) >= split
+				data, self._buffer = data[:split], data[split:]
+			chunks.append(data)
+			length += len(data)
+		return b''.join(chunks)
+
+	async def read(self, max_size: int = -1, /) -> bytes:
+		"""
+		Read and return up to `max_size` bytes from the stream
+
+		Be cautious about calling this with a non-positive `max_size` as the entire stream
+		will be stored in memory.
+
+		Implements `asyncio.StreamReader.read()`
+		"""
+		if max_size >= 0:
+			try:
+				return await self.receive(max_size)
+			except EndOfStream:
+				return b""
+		# Collect ALL THE DATA and return it
+		chunks = list[bytes]()
+		try:
+			while (chunk := await self.receive()):
+				chunks.append(chunk)
+		except EndOfStream:
+			pass
+		return b''.join(chunks)
+
+	async def readline(self) -> bytes:
+		r"""
+		Read and return one '\n' terminated line from the stream
+
+		Unlike `readuntil()` an incomplete line will be returned of an EOF occurs, and
+		`ValueError` is raised instead of `LimitOverrunError`.  In the event of
+		a `LimitOverrunError` the buffer is also cleared.
+
+		This implementation differs very slightly from Asyncio's, as the behaviour described
+		there is a hot mess.  It is *highly* recommended you use `readuntil` instead.
+
+		Implements `asyncio.StreamReader.readline()`
+		"""
+		try:
+			return await self.readuntil(b'\n')
+		except IncompleteReadError as exc:
+			return exc.partial
+		except LimitOverrunError as exc:
+			self._buffer = b""
+			raise ValueError(exc.args[0])
+
+	async def readexactly(self, size: int, /) -> bytes:
+		"""
+		Read and return exactly `size` bytes from the stream
+
+		Implements `asyncio.StreamReader.readexactly()`
+		"""
+		chunks = list[bytes]()
+		try:
+			while size > 0:
+				chunks.append(chunk := await self.receive(size))
+				size -= len(chunk)
+			assert size == 0, "ReadStream.receive() returned too many bytes"
+		except EndOfStream:
+			IncompleteReadError(b''.join(chunks), size)
+		return b''.join(chunks)
+
+	def at_eof(self) -> bool:
+		"""
+		Return `True` if the buffer is empty and an end-of-file has been indicated
+		"""
+		return not self._buffer and self.request is None
+
+
+class Response:
+	"""
+	A class for response details, and header and body accessors
+	"""
+
+	def __init__(self, response: str, stream: ReadStream):
+		match response.split(maxsplit=2):
+			case [version, response, status]:
+				self.version = version
+				self.code = HTTPStatus(int(response))
+				self.status = status.strip()
+			case [version, response]:
+				self.version = version
+				self.code = HTTPStatus(int(response))
+				self.status = self.code.phrase
+			case _:
+				raise ValueError
+		self.stream = stream
+		self.headers = list[tuple[str, bytes]]()
+
+	def __repr__(self) -> str:
+		return f"<Response {self.code} {self.status}>"

konnect_http-0.1.0/konnect/http/session.py

@@ -0,0 +1,180 @@
+# Copyright 2023  Dom Sekotill <dom.sekotill@kodo.org.uk>
+
+"""
+Sessions are the primary entrypoint for users
+
+Sessions handle global, prepared, shared state for requests.  They are also the primary
+entrypoint for users, abstracting away request generation and scheduling, and yielding
+responses for users to consume.
+
+> **Note:**
+> Unlike the `requests` package, there are no top-level functions for generating requests
+> and producing responses, as they would have to be synchronous.
+
+The `Session` class has several request methods which return `Response` objects.  These are
+conveniences for creating `Request` objects, writing data to them (if appropriate for the
+HTTP method), and awaiting a response from them.
+"""
+
+from typing import Self
+from urllib.parse import urlparse
+
+from konnect.curl import SECONDS
+from konnect.curl import Multi
+from konnect.curl import Time
+from konnect.curl.scalars import Quantity
+
+from .authenticators import AuthHandler
+from .cookies import Cookie
+from .exceptions import UnsupportedSchemeError
+from .request import Method
+from .request import Request
+from .request import ServiceIdentifier
+from .request import TransportInfo
+from .response import Response
+
+
+class Session:
+	"""
+	A shared request state class
+
+	Users *should* use a `Session` instance as an asynchronous context manager.
+
+	Users can provide a shared `Multi` object to allow connections to be shared between
+	sessions (or even different protocol clients), otherwise a new `Multi` object is
+	created; either option is safe in a single threaded environment but `Multi` objects
+	must not be shared between threads.
+
+	Users may also inject a subclass of `Request` to be used by the various methods that
+	return `Response` objects; the return object is the result of calling
+	`Request.get_response()`.
+	"""
+
+	# TODO: cookiejars
+	# TODO: proxies
+
+	def __init__(
+		self, *,
+		multi: Multi|None = None,
+		request_class: type[Request] = Request,
+	) -> None:
+		self.multi = multi or Multi()
+		self.request_class = request_class
+		self.timeout: Quantity[Time] = 0 @ SECONDS
+		self.connect_timeout: Quantity[Time] = 300 @ SECONDS
+		self.transports = dict[ServiceIdentifier, TransportInfo]()
+		self.auth = dict[ServiceIdentifier, AuthHandler]()
+		self.cookies = set[Cookie]()
+
+	async def __aenter__(self) -> Self:
+		# For future use; likely downloading PAC files if used for proxies
+		return self
+
+	async def __aexit__(self, *exc_info: object) -> None:
+		return
+
+	async def head(self, url: str) -> Response:
+		"""
+		Perform an HTTP HEAD request
+		"""
+		req = self.request_class(self, Method.HEAD, url)
+		return await req.get_response()
+
+	async def get(self, url: str) -> Response:
+		"""
+		Perform an HTTP GET request
+		"""
+		req = self.request_class(self, Method.GET, url)
+		return await req.get_response()
+
+	async def put(self, url: str, data: bytes) -> Response:
+		"""
+		Perform a simple HTTP PUT request with in-memory data
+		"""
+		req = self.request_class(self, Method.PUT, url)
+		await req.write(data)
+		await req.write(b"")
+		return await req.get_response()
+
+	async def post(self, url: str, data: bytes) -> Response:
+		"""
+		Perform a simple HTTP POST request with in-memory data
+		"""
+		req = self.request_class(self, Method.POST, url)
+		await req.write(data)
+		await req.write(b"")
+		return await req.get_response()
+
+	async def patch(self, url: str, data: bytes) -> Response:
+		"""
+		Perform a simple HTTP PATCH request with in-memory data
+		"""
+		req = self.request_class(self, Method.PATCH, url)
+		await req.write(data)
+		await req.write(b"")
+		return await req.get_response()
+
+	async def delete(self, url: str) -> Response:
+		"""
+		Perform an HTTP DELETE request
+		"""
+		req = self.request_class(self, Method.DELETE, url)
+		return await req.get_response()
+
+	def add_redirect(self, url: str, target: TransportInfo) -> None:
+		"""
+		Add a redirect for a URL base to a target address/port
+
+		The URL base should be a schema and 'hostname[:port]' only,
+		e.g. `"http://example.com"`; anything else will be ignored but may have an effect in
+		future releases.
+		"""
+		parts = urlparse(url)
+		if parts.scheme not in ("http", "https"):
+			raise UnsupportedSchemeError(url)
+		self.transports[parts.scheme, parts.netloc] = target  # type: ignore[index]
+
+	def remove_redirect(self, url: str) -> None:
+		"""
+		Remove a redirect for a URL base
+
+		See `add_redirect()` for the format of the URL base.
+		"""
+		parts = urlparse(url)
+		if parts.scheme not in ("http", "https"):
+			raise UnsupportedSchemeError(url)
+		del self.transports[parts.scheme, parts.netloc]  # type: ignore[arg-type]
+
+	def add_authentication(self, url: str, authenticator: AuthHandler) -> None:
+		"""
+		Add an authentication handler to use when accessing URLs under the given URL base
+
+		The URL base should be a schema and 'hostname[:port]' only,
+		e.g. `"http://example.com"`; anything else will be ignored but may have an effect in
+		future releases.
+		"""
+		parts = urlparse(url)
+		if parts.scheme not in ("http", "https"):
+			raise UnsupportedSchemeError(url)
+		self.auth[parts.scheme, parts.netloc] = authenticator  # type: ignore[index]
+
+	def remove_authentication(self, url: str) -> None:
+		"""
+		Remove an authentication handler for a URL base
+
+		See `add_authentication()` for the format of the URL base
+		"""
+		parts = urlparse(url)
+		if parts.scheme not in ("http", "https"):
+			raise UnsupportedSchemeError(url)
+		del self.auth[parts.scheme, parts.netloc]  # type: ignore[arg-type]
+
+	def add_cookie(self, url: str, name: str, value: bytes) -> None:
+		"""
+		Add a cookie for the given URL base
+		"""
+		parts = urlparse(url)
+		if parts.hostname is None:
+			raise ValueError(f"a hostname is required in URL: {url}")
+		cookie = Cookie(name, value, None, parts.hostname, parts.path, secure=(parts.scheme == "https"))
+		self.cookies.add(cookie)

konnect_http-0.1.0/pyproject.toml

@@ -0,0 +1,88 @@
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[[project.authors]]
+name = "Dom Sekotill"
+email = "dom.sekotill@kodo.org.uk"
+
+[project]
+name = "konnect.http"
+version = "0.1.0"
+description = "Pythonic, asynchronous HTTP client"
+
+classifiers = [
+	"Development Status :: 3 - Alpha",
+	"Intended Audience :: Developers",
+	"License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)",
+	"Topic :: Internet",
+]
+
+requires-python = "~=3.11"
+dependencies = [
+	"anyio ~=4.0",
+	"konnect.curl ~=0.1.0",
+]
+
+[tool.isort]
+force_single_line = true
+line_length = 92
+
+[tool.unimport]
+ignore-init = true
+
+
+[tool.flakeheaven]
+base = "https://code.kodo.org.uk/dom/project-templates/-/raw/main/.flakerules.toml"
+colored = true
+max_line_length = 92
+max_doc_length = 92
+
+[tool.flakeheaven.plugins]
+flake8-return = ["-R504"]
+
+[tool.flakeheaven.exceptions."examples/"]
+flake8-print = ["-*"]
+
+
+[tool.mypy]
+strict = true
+namespace_packages = true
+explicit_package_bases = true
+allow_redefinition = true
+warn_unused_configs = true
+warn_unreachable = true
+
+
+[tool.coverage.run]
+data_file = "results/coverage.db"
+branch = true
+source = ["konnect"]
+
+[tool.coverage.report]
+precision = 2
+skip_empty = true
+exclude_lines = [
+	"pragma: no-cover",
+	"if .*\\b__name__\\b",
+	"if .*\\bTYPE_CHECKING\\b",
+	"class .*(.*\\bProtocol\\b.*):",
+	"def __repr__",
+	"@overload",
+	"@(abc\\.)abstractmethod",
+]
+partial_branches = [
+	"pragma: no-branch",
+	"if .*\\b__debug__\\b",
+]
+
+[tool.coverage.json]
+output = "results/coverage.json"
+show_contexts = true
+
+[tool.coverage.xml]
+output = "results/coverage.xml"
+
+[tool.coverage.html]
+directory = "results/coverage"
+show_contexts = true