DefEssential 0.1.8__23-py3-none-any.whl

DefEssential/IO/Readers/ContentReaders.py

@@ -0,0 +1,241 @@
+from json import loads
+from typing import (
+	Any,
+	Callable,
+	Optional,
+	Union,
+)
+from urllib.parse import parse_qs
+
+from ...Error import (
+	ClientError,
+	Error,
+)
+from ...Request import Request
+from ..RequestReader import RequestReader
+from ...Validator import (
+	Pattern,
+	Validator,
+)
+from .ChunkedStream import ChunkedStream
+from .ContentReader import ContentReader
+
+__all__ = (
+	'ByteStringContentReader',
+	'StreamContentReader',
+	'ChunkedStreamContentReader',
+	'TextContentReader',
+	'FormUrlEncodedContentReader',
+	'JavaScriptObjectNotationContentReader',
+)
+
+
+class ByteStringContentReader(ContentReader):
+	"""Read and validate a binary body regardless of its Content-Type."""
+
+	def __init__(
+		self,
+		va: Union[Validator, Pattern, None] = None,
+		error: Optional[Error] = None,
+	):
+		self.va = Validator(va) if isinstance(va, Pattern) else va
+		self.error = error
+		return
+
+	def validate(
+		self,
+		content: Any,
+	) -> Any:
+		return self.va(content) if self.va is not None else content
+
+	def __call__(
+		self,
+		request: Request,
+		reader: RequestReader,
+	) -> Any:
+		try:
+			return self.read_content(
+				request,
+				reader,
+			)
+		except Error as error:
+			if self.error is not None:
+				raise self.error from error
+			raise
+		except (ValueError, TypeError, LookupError) as error:
+			raise self.error if self.error is not None else ClientError(str(error)) from error
+
+	def read_content(
+		self,
+		request: Request,
+		reader: RequestReader,
+	) -> Any:
+		return self.validate(reader.read())
+
+
+class StreamContentReader(ByteStringContentReader):
+	"""Expose a Content-Length body as a binary stream without pre-reading."""
+
+	def read_content(
+		self,
+		request: Request,
+		reader: RequestReader,
+	) -> RequestReader:
+		if reader.chunked:
+			raise ClientError(
+				'Content-Length is required',
+				status=411,
+			)
+		return reader
+
+
+class ChunkedStreamContentReader(StreamContentReader):
+	"""Decode a chunked body as a binary stream that can read client chunks one at a time."""
+
+	def read_content(
+		self,
+		request: Request,
+		reader: RequestReader,
+	) -> ChunkedStream:
+		if not reader.chunked:
+			raise ClientError('Chunked transfer encoding is required')
+		return ChunkedStream(reader)
+
+
+class TextContentReader(ByteStringContentReader):
+	"""Decode text/* bodies into strings."""
+
+	def __init__(
+		self,
+		va: Union[Validator, Pattern, None] = None,
+		error: Optional[Error] = None,
+		typeerror: Optional[Error] = None,
+	):
+		super().__init__(
+			va=va,
+			error=error,
+		)
+		self.typeerror = typeerror
+		return
+
+	def accepts(
+		self,
+		format: str,
+	) -> bool:
+		return format.startswith('text/')
+
+	def __call__(
+		self,
+		request: Request,
+		reader: RequestReader,
+	) -> Any:
+		format = request.format
+		if format is None or not self.accepts(format):
+			raise self.typeerror if self.typeerror is not None else ClientError(
+				'Unsupported body format',
+				status=415,
+			)
+		return super().__call__(
+			request,
+			reader,
+		)
+
+	def decode(
+		self,
+		request: Request,
+		reader: RequestReader,
+	) -> str:
+		try:
+			return reader.read().decode(request.charset or 'utf-8')
+		except (UnicodeError, LookupError) as error:
+			raise ClientError('Invalid body character encoding') from error
+
+	def read_content(
+		self,
+		request: Request,
+		reader: RequestReader,
+	) -> Any:
+		return self.validate(self.decode(
+			request,
+			reader,
+		))
+
+
+class FormUrlEncodedContentReader(TextContentReader):
+	"""Read URL-encoded forms with single or multiple values."""
+
+	def accepts(
+		self,
+		format: str,
+	) -> bool:
+		return format == 'application/x-www-form-urlencoded'
+
+	def read_content(
+		self,
+		request: Request,
+		reader: RequestReader,
+	) -> Any:
+		values = parse_qs(
+			self.decode(
+				request,
+				reader,
+			),
+			keep_blank_values=True,
+		)
+		return self.validate({
+			key: items[0] if len(items) == 1 else items
+			for key, items in values.items()
+		})
+
+
+class JavaScriptObjectNotationContentReader(TextContentReader):
+	"""Read JSON bodies with optional value conversion and validation."""
+
+	def __init__(
+		self,
+		va: Union[Validator, Pattern, None] = None,
+		typereader: Optional[Callable[[Any], Any]] = None,
+		error: Optional[Error] = None,
+		typeerror: Optional[Error] = None,
+	):
+		super().__init__(
+			va=va,
+			error=error,
+			typeerror=typeerror,
+		)
+		self.typereader = typereader
+		return
+
+	def accepts(
+		self,
+		format: str,
+	) -> bool:
+		return format == 'application/json'
+
+	def convert(
+		self,
+		value: Any,
+	) -> Any:
+		if isinstance(value, dict):
+			return {
+				key: self.convert(item) for key, item in value.items()
+			}
+		if isinstance(value, list):
+			return [self.convert(item) for item in value]
+		return self.typereader(value) if self.typereader is not None else value
+
+	def read_content(
+		self,
+		request: Request,
+		reader: RequestReader,
+	) -> Any:
+		try:
+			value = loads(self.decode(
+				request,
+				reader,
+			))
+		except ValueError as error:
+			raise ClientError('Invalid JSON body') from error
+		if self.typereader is not None:
+			value = self.convert(value)
+		return self.validate(value)

DefEssential/IO/Readers/__init__.py

@@ -0,0 +1,25 @@
+from .ChunkedStream import ChunkedStream
+from .ContentReader import (
+	ContentReader,
+	TypeReader,
+)
+from .ContentReaders import (
+	ByteStringContentReader,
+	StreamContentReader,
+	ChunkedStreamContentReader,
+	TextContentReader,
+	FormUrlEncodedContentReader,
+	JavaScriptObjectNotationContentReader,
+)
+
+__all__ = (
+	'ChunkedStream',
+	'ContentReader',
+	'TypeReader',
+	'ByteStringContentReader',
+	'StreamContentReader',
+	'ChunkedStreamContentReader',
+	'TextContentReader',
+	'FormUrlEncodedContentReader',
+	'JavaScriptObjectNotationContentReader',
+)

DefEssential/IO/RequestReader.py

@@ -0,0 +1,125 @@
+from typing import (
+	Optional,
+	Protocol,
+)
+
+from ..Error import ClientError
+
+__all__ = (
+	'BinaryReader',
+	'ClientDisconnected',
+	'RequestReader',
+)
+
+
+class BinaryReader(Protocol):
+	def read(
+		self,
+		size: int = -1,
+		/,
+	) -> bytes:
+		...
+
+	def readline(
+		self,
+		size: int = -1,
+		/,
+	) -> bytes:
+		...
+
+
+class ClientDisconnected(ConnectionError):
+	"""Represent a client connection lost while receiving the request body."""
+
+
+class RequestReader:
+	"""Read length-delimited and chunked request bodies.
+
+	When decoded=True, treat the input as having already been decoded by the transport layer.
+	"""
+
+	def __init__(
+		self,
+		reader: BinaryReader,
+		size: Optional[int] = None,
+		chunked: bool = False,
+		decoded: bool = False,
+	):
+		if size is not None and size < 0:
+			raise ValueError('Body length must not be negative')
+		if chunked and size is not None:
+			raise ClientError('Content-Length and Transfer-Encoding cannot be used together')
+		self.reader = reader
+		self.remaining = size if size is not None else 0
+		self.chunked = chunked
+		self.decoded = decoded
+		self.finished = not chunked and self.remaining == 0
+		return
+
+	def line(self) -> bytes:
+		"""Read one raw CRLF-terminated line without the line ending."""
+		try:
+			line = self.reader.readline(65537)
+		except ConnectionError as error:
+			raise ClientDisconnected(*error.args) from error
+		if len(line) > 65536 or not line.endswith(b'\r\n'):
+			raise ClientError('Invalid or truncated body line')
+		return line[:-2]
+
+	def exact(
+		self,
+		size: int,
+	) -> bytes:
+		"""Read exactly size raw bytes."""
+		parts = []
+		while size:
+			try:
+				part = self.reader.read(size)
+			except ConnectionError as error:
+				raise ClientDisconnected(*error.args) from error
+			if not part:
+				raise ClientError('Connection closed while receiving the request body')
+			parts.append(part)
+			size -= len(part)
+		return b''.join(parts)
+
+	def read(
+		self,
+		size: int = -1,
+	) -> bytes:
+		if size < -1:
+			raise ValueError('Read size must be at least -1')
+		if self.chunked and not self.decoded:
+			raise ClientError(
+				'Content-Length is required',
+				status=411,
+			)
+		if size == 0 or self.finished:
+			return b''
+		if self.chunked:
+			try:
+				data = self.reader.read(size)
+			except ConnectionError as error:
+				raise ClientDisconnected(*error.args) from error
+			if not data or size == -1:
+				self.finished = True
+			return data
+		count = self.remaining if size == -1 else min(size, self.remaining)
+		data = self.exact(count)
+		self.remaining -= len(data)
+		self.finished = self.remaining == 0
+		return data
+
+	def readline(
+		self,
+		size: int = -1,
+	) -> bytes:
+		parts = []
+		while size == -1 or len(parts) < size:
+			byte = self.read(1)
+			if not byte:
+				break
+			parts.append(byte)
+			if byte == b'\n':
+				break
+		return b''.join(parts)

DefEssential/IO/ResponseWriter.py

@@ -0,0 +1,242 @@
+from typing import (
+	Callable,
+	Optional,
+	Protocol,
+)
+
+from ..Response import (
+	Response,
+	close_bodies,
+)
+from ..Error import ClientError
+
+__all__ = (
+	'BinaryWriter',
+	'ResponseWriter',
+)
+
+
+class BinaryWriter(Protocol):
+	def write(
+		self,
+		data: bytes,
+		/,
+	) -> int:
+		...
+
+	def flush(self) -> None:
+		...
+
+
+class ResponseWriter:
+	"""Share response state to prevent duplicate direct and returned responses."""
+
+	def __init__(
+		self,
+		sender: Callable[[Response, bool], None],
+		writer: BinaryWriter,
+		method: str = 'GET',
+		version: str = 'HTTP/1.1',
+	):
+		self.sender = sender
+		self.writer = writer
+		self.method = method
+		self.version = version
+		self.started = False
+		self.status = 500
+		self.ended = False
+		self.failed = False
+		self.chunked = False
+		self.suppress_body = False
+		self.on_request_response: Optional[Callable[[Response], Response]] = None
+		return
+
+	def start(
+		self,
+		response: Response,
+		chunked: bool,
+	) -> None:
+		if self.started:
+			raise RuntimeError('Cannot start a response that has already started')
+		if not 200 <= response.status <= 599:
+			raise ValueError('Final response status code must be between 200 and 599')
+		self.chunked = chunked
+		self.suppress_body = self.method == 'HEAD' or response.status in (
+			204,
+			205,
+			304,
+		)
+		if chunked and not self.suppress_body and self.version != 'HTTP/1.1':
+			raise ClientError('Chunked output requires an HTTP/1.1 request')
+		self.started = True
+		self.status = response.status
+		try:
+			self.sender(
+				response,
+				chunked,
+			)
+		except Exception:
+			self.failed = True
+			raise
+		return
+
+	def filter(
+		self,
+		response: Response,
+	) -> Response:
+		"""Call the injected response hook and validate a response for direct output."""
+		if self.on_request_response is not None:
+			response = self.on_request_response(response)
+		if not isinstance(response, Response):
+			raise TypeError('Response hooks must return a Response')
+		try:
+			if not isinstance(response.body, bytes) or response.body:
+				raise ValueError('Response hooks must not set a body for direct output')
+			if response.header('Content-Length') is not None:
+				raise ValueError('Content-Length must not be set for direct output')
+		except Exception:
+			close_bodies(
+				response.body,
+				preserve_error=True,
+			)
+			raise
+		return response
+
+	def begin(
+		self,
+		response: Response,
+		chunked: bool = False,
+	) -> None:
+		"""Send direct-output response headers once, after running response hooks and validation."""
+		if self.started:
+			raise RuntimeError('Cannot start a response that has already started')
+		self.start(
+			self.filter(response),
+			chunked,
+		)
+		return
+
+	def upgrade(
+		self,
+		response: Response,
+	) -> None:
+		"""Send 101 Switching Protocols headers once through the response hook.
+
+		Subsequent write() calls send bytes without HTTP framing; the caller is
+		responsible for framing the upgraded protocol.
+		"""
+		if self.started:
+			raise RuntimeError('Cannot start a response that has already started')
+		if response.status != 101:
+			raise ValueError('Protocol upgrades require status 101')
+		response = self.filter(response)
+		if response.status != 101:
+			raise ValueError('Response hooks must keep status 101 for protocol upgrades')
+		self.chunked = False
+		self.suppress_body = False
+		self.started = True
+		self.status = response.status
+		try:
+			self.sender(
+				response,
+				False,
+			)
+		except Exception:
+			self.failed = True
+			raise
+		return
+
+	def require_open(self) -> None:
+		if not self.started:
+			raise RuntimeError('Response must be started first')
+		if self.ended or self.failed:
+			raise RuntimeError('Cannot write to a completed or failed response')
+		return
+
+	def write(
+		self,
+		data: bytes,
+	) -> None:
+		"""Write bytes immediately using the current response framing."""
+		self.require_open()
+		if not isinstance(data, bytes):
+			raise TypeError('Response streams require bytes')
+		if not data or self.suppress_body:
+			return
+		if self.chunked:
+			data = format(len(data), 'x').encode('ascii') + b'\r\n' + data + b'\r\n'
+		self.write_bytes(data)
+		return
+
+	def write_bytes(
+		self,
+		data: bytes,
+	) -> None:
+		try:
+			while data:
+				count = self.writer.write(data)
+				if count <= 0 or count > len(data):
+					raise OSError('Response write made no valid progress')
+				data = data[count:]
+		except Exception:
+			self.failed = True
+			raise
+		return
+
+	def flush(self) -> None:
+		self.require_open()
+		try:
+			self.writer.flush()
+		except Exception:
+			self.failed = True
+			raise
+		return
+
+	def end(self) -> None:
+		"""Send the terminating chunk exactly once on successful completion."""
+		if self.ended:
+			return
+		self.require_open()
+		if self.chunked and not self.suppress_body:
+			self.write_bytes(b'0\r\n\r\n')
+		self.flush()
+		self.ended = True
+		return
+
+	def response(
+		self,
+		response: Response,
+		*,
+		filtered: bool = False,
+	) -> None:
+		"""Send returned bytes or iterable responses through the same transport boundary."""
+		if self.started:
+			raise RuntimeError('Cannot send a response that has already started')
+		if not filtered and self.on_request_response is not None:
+			response = self.on_request_response(response)
+		if not isinstance(response, Response):
+			raise TypeError('Response hooks must return a Response')
+		if isinstance(response.body, bytes) and response.status not in (
+			204,
+			205,
+			304,
+		):
+			response.header(
+				'Content-Length',
+				str(len(response.body)),
+			)
+		else:
+			del response.props['Content-Length']
+		self.start(
+			response,
+			False,
+		)
+		if not self.suppress_body:
+			if isinstance(response.body, bytes):
+				self.write(response.body)
+			else:
+				for data in response.body:
+					self.write(data)
+					self.flush()
+		self.end()
+		return