DefEssential 0.1.8__25-py3-none-any.whl

DefEssential/Adapter/RequestHandler.py

@@ -0,0 +1,109 @@
+from logging import getLogger
+from time import monotonic
+from typing import Callable
+
+from ..Application import Application
+from ..Error import Error
+from ..IO.RequestReader import ClientDisconnected
+from ..IO.ResponseWriter import ResponseWriter
+from ..Request import Request
+from ..Response import Response
+
+__all__ = (
+	'handle_request',
+)
+
+LOGGER = getLogger('DefEssential.Server')
+
+
+def handle_request(
+	application: Application,
+	create_request: Callable[[], Request],
+	writer: ResponseWriter,
+) -> None:
+	"""Handle error responses and resource cleanup independently of the transport layer."""
+	logger = LOGGER
+	started = monotonic()
+	request = None
+	response = None
+	outcome = 'failed'
+	try:
+		try:
+			request = create_request()
+			logger.debug(
+				'HTTP request received: request_id=%s method=%s',
+				request.id,
+				ascii(request.method[:32]),
+			)
+			response = application(request)
+		except ClientDisconnected:
+			raise
+		except Error as error:
+			if writer.started:
+				raise
+			logger.debug(
+				'HTTP error response selected: request_id=%s status=%s',
+				request.id if request is not None else None,
+				error.status,
+			)
+			response = Response(
+				status=error.status,
+				headers=error.headers,
+				body=error.reason.encode('utf-8'),
+				format='text/plain',
+				charset='utf-8',
+			)
+		except Exception:
+			if writer.started:
+				raise
+			logger.exception(
+				'Unexpected error while handling request: request_id=%s',
+				request.id if request is not None else None,
+			)
+			response = Response(
+				status=500,
+				body=b'Internal Server Error',
+			)
+		if response is not None:
+			logger.debug('Response transmission starting: request_id=%s status=%s', request.id if request is not None else None, response.status)
+			writer.response(
+				response,
+				filtered=True,
+			)
+		elif not writer.ended:
+			raise RuntimeError('Response was neither returned nor completed successfully')
+		outcome = 'completed'
+	except ConnectionError:
+		outcome = 'disconnected'
+		logger.warning(
+			'Client disconnected: request_id=%s',
+			request.id if request is not None else None,
+		)
+		raise
+	except Exception:
+		logger.exception(
+			'Response transmission failed: closing connection without another error response request_id=%s',
+			request.id if request is not None else None,
+		)
+		raise
+	finally:
+		duration = monotonic() - started
+		logger.info(
+			'HTTP transmission result: request_id=%s method=%s status=%s outcome=%s duration=%.6f',
+			request.id if request is not None else None,
+			ascii(request.method[:32]) if request is not None else None,
+			writer.status if writer.started else None,
+			outcome,
+			duration,
+		)
+		if response is not None:
+			try:
+				logger.debug('Response body cleaning up: request_id=%s', request.id if request is not None else None)
+				response.close()
+				logger.debug('Response body cleaned up: request_id=%s', request.id if request is not None else None)
+			except Exception:
+				logger.exception(
+					'Response body cleanup failed: request_id=%s',
+					request.id if request is not None else None,
+				)
+	return

DefEssential/Adapter/Server.py

@@ -0,0 +1,54 @@
+from abc import (
+	ABC,
+	abstractmethod,
+)
+from types import TracebackType
+from typing import (
+	Optional,
+	TypeVar,
+)
+
+from ..Application import Application
+
+__all__ = (
+	'Server',
+)
+
+
+ServerType = TypeVar(
+	'ServerType',
+	bound='Server',
+)
+
+
+class Server(ABC):
+	"""Define the server adapter contract for running an application at an address."""
+
+	def __init__(
+		self,
+		host: str,
+		port: int,
+		application: Application,
+	):
+		self.host = host
+		self.port = port
+		self.application = application
+		return
+
+	def __enter__(self: ServerType) -> ServerType:
+		"""Return this instance without starting the server."""
+		return self
+
+	def __exit__(
+		self,
+		exception_type: Optional[type[BaseException]],
+		exception: Optional[BaseException],
+		traceback: Optional[TracebackType],
+	) -> None:
+		"""Propagate exceptions; run() is responsible for cleaning up active resources."""
+		return
+
+	@abstractmethod
+	def run(self) -> None:
+		"""Serve until shutdown and manage the application lifecycle."""
+		raise NotImplementedError

DefEssential/Adapter/WSGI.py

@@ -0,0 +1,219 @@
+from typing import (
+	Any,
+	Callable,
+	Iterable,
+	Mapping,
+	Optional,
+	Protocol,
+)
+from urllib.parse import quote_from_bytes
+from wsgiref.util import is_hop_by_hop
+
+from ..Application import Application
+from ..Error import Error
+from ..IO.RequestReader import RequestReader
+from ..IO.ResponseWriter import ResponseWriter
+from ..Request import Request
+from ..Response import Response
+from .RequestHandler import handle_request
+
+__all__ = (
+	'StartResponse',
+	'WSGITransport',
+	'WSGIResponseWriter',
+	'WSGIApplication',
+)
+
+
+class StartResponse(Protocol):
+	def __call__(
+		self,
+		status: str,
+		headers: list[tuple[str, str]],
+		/,
+	) -> Callable[[bytes], object]:
+		...
+
+
+class WSGITransport:
+	"""Delegate HTTP framing to the WSGI server and forward bytes immediately."""
+
+	def __init__(
+		self,
+		start_response: StartResponse,
+	):
+		self.start_response = start_response
+		self.output: Optional[Callable[[bytes], object]] = None
+		return
+
+	def begin(
+		self,
+		response: Response,
+		chunked: bool,
+	) -> None:
+		headers = [
+			(
+				key,
+				value,
+			) for key, value in response.headers()
+			if not is_hop_by_hop(key)
+			and not (key.lower() == 'content-length' and response.status in (
+				204,
+				205,
+				304,
+			))
+		]
+		if response.status == 205:
+			headers.append((
+				'Content-Length',
+				'0',
+			))
+		self.output = self.start_response(
+			f'{response.status} {response.message}',
+			headers,
+		)
+		return
+
+	def write(
+		self,
+		data: bytes,
+		/,
+	) -> int:
+		if self.output is None:
+			raise RuntimeError('WSGI response must be started before writing')
+		self.output(data)
+		return len(data)
+
+	def flush(self) -> None:
+		# Calling WSGI write() forwards the bytes to the server.
+		return
+
+
+class WSGIResponseWriter(ResponseWriter):
+	"""Preserve the direct-output API without applying chunk framing twice."""
+
+	def start(
+		self,
+		response: Response,
+		chunked: bool,
+	) -> None:
+		super().start(
+			response,
+			False,
+		)
+		return
+
+	def upgrade(
+		self,
+		response: Response,
+	) -> None:
+		raise Error(
+			501,
+			'WSGI adapters do not support protocol upgrades',
+		)
+
+
+class WSGIApplication:
+	"""Adapt DefEssential requests to the WSGI calls used by Gunicorn and a2wsgi."""
+
+	def __init__(
+		self,
+		application: Application,
+	):
+		self.application = application
+		return
+
+	def request_reader(
+		self,
+		environ: Mapping[str, Any],
+	) -> RequestReader:
+		length = environ.get('CONTENT_LENGTH', '')
+		transfer = environ.get('HTTP_TRANSFER_ENCODING', '')
+		if length and (not length.isascii() or not length.isdigit()):
+			raise Error(
+				400,
+				'Invalid Content-Length',
+			)
+		if transfer and (transfer.lower() != 'chunked' or length):
+			raise Error(
+				400,
+				'Ambiguous or unsupported request body framing',
+			)
+		return RequestReader(
+			environ['wsgi.input'],
+			size=int(length) if length else None,
+			chunked=transfer.lower() == 'chunked',
+			decoded=True,
+		)
+
+	def response_writer(
+		self,
+		environ: Mapping[str, Any],
+		start_response: StartResponse,
+	) -> ResponseWriter:
+		transport = WSGITransport(start_response)
+		return WSGIResponseWriter(
+			transport.begin,
+			transport,
+			method=environ['REQUEST_METHOD'],
+			version=environ['SERVER_PROTOCOL'],
+		)
+
+	def __call__(
+		self,
+		environ: Mapping[str, Any],
+		start_response: StartResponse,
+	) -> Iterable[bytes]:
+		writer = self.response_writer(
+			environ,
+			start_response,
+		)
+
+		def create_request() -> Request:
+			reader = self.request_reader(environ)
+			headers = {
+				key[5:].replace('_', '-'): value
+				for key, value in environ.items()
+				if key.startswith('HTTP_')
+			}
+			for source, target in (
+				(
+					'CONTENT_LENGTH',
+					'Content-Length',
+				),
+				(
+					'CONTENT_TYPE',
+					'Content-Type',
+				),
+			):
+				if environ.get(source):
+					headers[target] = environ[source]
+			uri = environ.get('RAW_URI') or environ.get('REQUEST_URI')
+			if uri is None:
+				raw_path = environ.get('asgi.scope', {}).get('raw_path')
+				if raw_path is not None:
+					uri = raw_path.decode('latin-1')
+				else:
+					path = environ.get('SCRIPT_NAME', '') + environ['PATH_INFO']
+					uri = quote_from_bytes(
+						path.encode('latin-1'),
+						safe="/:@!$&'()*+,;=-._~",
+					)
+				if environ.get('QUERY_STRING'):
+					uri += '?' + environ['QUERY_STRING']
+			return Request(
+				address=environ.get('REMOTE_ADDR', ''),
+				port=int(environ.get('REMOTE_PORT', 0)),
+				method=environ['REQUEST_METHOD'],
+				uri=uri,
+				headers=headers,
+				reader=reader,
+				writer=writer,
+			)
+
+		handle_request(
+			self.application,
+			create_request,
+			writer,
+		)
+		return ()

DefEssential/Adapter/__init__.py

@@ -0,0 +1,5 @@
+from .Server import Server
+
+__all__ = (
+	'Server',
+)