DefEssential 0.1.8__27-py3-none-any.whl

DefEssential/Adapter/Implements/Uvicorn/HTTP.py

@@ -0,0 +1,256 @@
+from asyncio import (
+	CancelledError,
+	Queue,
+	create_task,
+	get_running_loop,
+	shield,
+)
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import suppress
+from typing import Optional
+from a2wsgi.asgi_typing import (
+	Receive,
+	Scope,
+	Send,
+)
+from a2wsgi.wsgi import (
+	Body,
+	build_environ,
+)
+
+from ....Application import Application
+from ....IO.RequestReader import ClientDisconnected
+from ...WSGI import WSGIApplication
+from .Portal import Portal
+
+__all__ = (
+	'Input',
+	'Middleware',
+)
+
+
+class Input(Body):
+	"""Read ASGI request bodies without waiting for the full upload and monitor disconnects."""
+
+	def __init__(
+		self,
+		receive: Receive,
+		portal: Portal,
+		capacity: int,
+	):
+		super().__init__(
+			portal.loop,
+			receive,
+		)
+		self.portal = portal
+		self.messages: Queue[bytes] = Queue(maxsize=capacity)
+		self.finished = False
+		self.disconnected = False
+		self.failure: Optional[Exception] = None
+		return
+
+	async def pump(self) -> None:
+		try:
+			while True:
+				message = await self.receive()
+				if message['type'] == 'http.disconnect':
+					self.disconnected = True
+					await self.messages.put(b'')
+					return
+				if message['type'] != 'http.request':
+					raise RuntimeError('Expected an HTTP request body event')
+				if message['body']:
+					await self.messages.put(message['body'])
+				if not message.get('more_body', False):
+					await self.messages.put(b'')
+		except Exception as error:
+			self.failure = error
+			await self.messages.put(b'')
+			raise
+
+	async def take(
+		self,
+		size: int,
+	) -> bytes:
+		if self.failure is not None:
+			raise self.failure
+		if self.disconnected:
+			raise ClientDisconnected('Client disconnected while receiving request')
+		while not self.buffer and not self.finished:
+			data = await self.messages.get()
+			if not data:
+				if self.failure is not None:
+					raise self.failure
+				if self.disconnected:
+					raise ClientDisconnected('Client disconnected while receiving request')
+				self.finished = True
+			else:
+				self.buffer.extend(data)
+		if size < 0:
+			while not self.finished:
+				data = await self.messages.get()
+				if not data:
+					if self.failure is not None:
+						raise self.failure
+					if self.disconnected:
+						raise ClientDisconnected('Client disconnected while receiving request')
+					self.finished = True
+				else:
+					self.buffer.extend(data)
+			size = len(self.buffer)
+		data = bytes(self.buffer[:size])
+		del self.buffer[:size]
+		return data
+
+	def read(
+		self,
+		size: int = -1,
+	) -> bytes:
+		if size == 0:
+			return b''
+		return self.portal.call(self.take(size))
+
+	@property
+	def has_more(self) -> bool:
+		return bool(self.buffer) or not self.finished
+
+	def readline(
+		self,
+		limit: int = -1,
+	) -> bytes:
+		data = bytearray()
+		while limit < 0 or len(data) < limit:
+			part = self.read(1)
+			if not part:
+				break
+			data.extend(part)
+			if part == b'\n':
+				break
+		return bytes(data)
+
+	def readlines(
+		self,
+		hint: int = -1,
+	) -> list[bytes]:
+		lines = []
+		total = 0
+		while self.has_more:
+			line = self.readline()
+			if not line:
+				break
+			lines.append(line)
+			total += len(line)
+			if hint > 0 and total >= hint:
+				break
+		return lines
+
+
+class Middleware:
+	"""Use a2wsgi for environment conversion and apply backpressure during byte transmission."""
+
+	def __init__(
+		self,
+		application: Application,
+		workers: int,
+		queue_size: int,
+	):
+		self.application = WSGIApplication(application)
+		self.executor = ThreadPoolExecutor(
+			max_workers=workers,
+			thread_name_prefix='DefEssential.Uvicorn',
+		)
+		self.queue_size = queue_size
+		return
+
+	async def __call__(
+		self,
+		scope: Scope,
+		receive: Receive,
+		send: Send,
+	) -> None:
+		if scope['type'] == 'lifespan':
+			while True:
+				message = await receive()
+				if message['type'] == 'lifespan.startup':
+					await send({'type': 'lifespan.startup.complete'})
+				elif message['type'] == 'lifespan.shutdown':
+					await send({'type': 'lifespan.shutdown.complete'})
+					return
+				else:
+					raise RuntimeError('Unexpected lifespan event')
+		if scope['type'] != 'http':
+			raise RuntimeError('WebSocket connections require the native protocol')
+		portal = Portal(get_running_loop())
+		body = Input(
+			receive,
+			portal,
+			self.queue_size,
+		)
+		environ = build_environ(
+			scope,
+			body,
+		)
+		pump = create_task(body.pump())
+
+		async def transmit(message) -> None:
+			if body.failure is not None:
+				raise body.failure
+			if body.disconnected:
+				raise ClientDisconnected('Client disconnected while sending response')
+			await send(message)
+			return
+
+		def write(data: bytes) -> None:
+			portal.call(transmit({
+				'type': 'http.response.body',
+				'body': data,
+				'more_body': True,
+			}))
+			return
+
+		def start_response(
+			status: str,
+			headers: list[tuple[str, str]],
+		):
+			portal.call(transmit({
+				'type': 'http.response.start',
+				'status': int(status.split(' ', 1)[0]),
+				'headers': [
+					(
+						key.lower().encode('latin-1'),
+						value.encode('latin-1'),
+					) for key, value in headers
+				],
+			}))
+			return write
+
+		def run() -> None:
+			for data in self.application(
+				environ,
+				start_response,
+			):
+				write(data)
+			return
+
+		worker = portal.loop.run_in_executor(
+			self.executor,
+			run,
+		)
+		try:
+			await shield(worker)
+			await transmit({
+				'type': 'http.response.body',
+				'body': b'',
+				'more_body': False,
+			})
+		except CancelledError:
+			portal.close()
+			with suppress(ClientDisconnected):
+				await worker
+			raise
+		finally:
+			portal.close()
+			pump.cancel()
+			with suppress(CancelledError):
+				await pump
+		return

DefEssential/Adapter/Implements/Uvicorn/Portal.py

@@ -0,0 +1,65 @@
+from asyncio import (
+	AbstractEventLoop,
+	run_coroutine_threadsafe,
+)
+from concurrent.futures import (
+	CancelledError,
+	Future,
+)
+from threading import Lock
+from typing import (
+	Any,
+	Coroutine,
+	TypeVar,
+)
+
+from ....IO.RequestReader import ClientDisconnected
+
+__all__ = (
+	'Portal',
+)
+
+
+Result = TypeVar('Result')
+
+
+class Portal:
+	"""Bridge synchronous handler I/O to the event loop and release waits on cancellation."""
+
+	def __init__(
+		self,
+		loop: AbstractEventLoop,
+	):
+		self.loop = loop
+		self.lock = Lock()
+		self.pending: set[Future[Any]] = set()
+		self.closed = False
+		return
+
+	def call(
+		self,
+		coroutine: Coroutine[Any, Any, Result],
+	) -> Result:
+		with self.lock:
+			if self.closed:
+				coroutine.close()
+				raise ClientDisconnected('Connection is closed')
+			future = run_coroutine_threadsafe(
+				coroutine,
+				self.loop,
+			)
+			self.pending.add(future)
+		try:
+			return future.result()
+		except CancelledError as error:
+			raise ClientDisconnected('Connection was cancelled') from error
+		finally:
+			with self.lock:
+				self.pending.discard(future)
+
+	def close(self) -> None:
+		with self.lock:
+			self.closed = True
+			for future in self.pending:
+				future.cancel()
+		return

DefEssential/Adapter/Implements/Uvicorn/Server.py

@@ -0,0 +1,137 @@
+from logging import getLogger
+from socket import socket
+from typing import (
+	Any,
+	Optional,
+)
+
+from ....Application import Application
+from ....Startup import startup
+from ...Server import Server as ServerAdapter
+
+__all__ = (
+	'Server',
+)
+
+
+class Server(ServerAdapter):
+	"""Run a synchronous application on Uvicorn through a2wsgi."""
+
+	logger = getLogger('DefEssential.Server')
+
+	def __init__(
+		self,
+		host: str,
+		port: int,
+		application: Application,
+		*,
+		wsgi_workers: int = 10,
+		send_queue_size: int = 10,
+		**options: Any,
+	):
+		super().__init__(
+			host,
+			port,
+			application,
+		)
+		if wsgi_workers < 1 or send_queue_size < 1:
+			raise ValueError('wsgi_workers and send_queue_size must be at least 1')
+		if options.get('workers') not in (
+			None,
+			1,
+		) or options.get('reload', False):
+			raise ValueError('Application instances require workers=1 and reload=False')
+		if options.get('interface', 'asgi3') != 'asgi3':
+			raise ValueError('a2wsgi requires interface=asgi3')
+		if any(key == 'ws' or key.startswith('ws_') for key in options):
+			raise ValueError('The adapter manages WebSocket framing; configure limits and ping in WebSocket handlers')
+		self.wsgi_workers = wsgi_workers
+		self.send_queue_size = send_queue_size
+		self.options = options
+		return
+
+	def run(self) -> None:
+		# Do not import optional dependencies when using the built-in server.
+		from .HTTP import Middleware
+		from .WebSocket import WebSocketProtocol
+		from uvicorn import (
+			Config,
+			Server as UvicornServer,
+		)
+
+		middleware = Middleware(
+			self.application,
+			workers=self.wsgi_workers,
+			queue_size=self.send_queue_size,
+		)
+		try:
+			application = self.application
+
+			class NativeWebSocketProtocol(WebSocketProtocol):
+				def __init__(
+					self,
+					config,
+					server_state,
+					app_state,
+				):
+					super().__init__(
+						config,
+						server_state,
+						app_state,
+						application,
+						middleware.executor,
+					)
+					return
+
+			options = dict(self.options)
+			options['workers'] = 1
+			options['interface'] = 'asgi3'
+			logger = self.logger
+
+			class NativeServer(UvicornServer):
+				async def startup(
+					self,
+					sockets: Optional[list[socket]] = None,
+				) -> None:
+					try:
+						await super().startup(sockets=sockets)
+					except SystemExit:
+						logger.error('Server startup aborted: adapter=Uvicorn', exc_info=True)
+						raise
+					if self.started:
+						for listener in self.servers:
+							for bound_socket in listener.sockets or ():
+								logger.info(
+									'Server ready: adapter=Uvicorn address=%s',
+									bound_socket.getsockname(),
+								)
+					return
+
+			server = NativeServer(Config(
+				middleware,
+				host=self.host,
+				port=self.port,
+				ws=NativeWebSocketProtocol,
+				**options,
+			))
+			startup(
+				self.application,
+				'Uvicorn',
+				self.host,
+				self.port,
+			)
+			self.application.start()
+			try:
+				self.logger.info('Server starting: adapter=Uvicorn host=%s port=%s', self.host, self.port)
+				try:
+					server.run()
+				except Exception:
+					self.logger.exception('Server execution failed: adapter=Uvicorn')
+					raise
+			finally:
+				self.logger.info('Server stopping: adapter=Uvicorn')
+				self.application.stop()
+			self.logger.info('Server stopped: adapter=Uvicorn')
+		finally:
+			middleware.executor.shutdown(wait=True)
+		return

DefEssential/Adapter/Implements/Uvicorn/WebSocket.py

@@ -0,0 +1,222 @@
+from asyncio import (
+	CancelledError,
+	Event,
+	Protocol,
+	StreamReader,
+	Transport,
+	get_running_loop,
+	shield,
+)
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import suppress
+from logging import getLogger
+from socket import socket
+from socketserver import BaseServer
+from typing import (
+	Any,
+	cast,
+)
+
+from ....Application import Application
+from ....IO.RequestReader import ClientDisconnected
+from ....IO.WebSocket.WebSocketFrame import WebSocketFrame
+from ..Python.Server import ServerRequestHandler
+from .Portal import Portal
+
+__all__ = (
+	'ServerContext',
+	'Connection',
+	'WebSocketProtocol',
+)
+
+
+class ServerContext(BaseServer):
+	app: Application
+
+
+class Connection:
+	"""Expose an asyncio connection as a socket to the existing HTTP/WebSocket handler."""
+
+	def __init__(
+		self,
+		protocol: 'WebSocketProtocol',
+	):
+		self.protocol = protocol
+		return
+
+	def makefile(
+		self,
+		mode: str,
+		buffering: int = -1,
+	) -> 'Connection':
+		if mode != 'rb' or buffering not in (
+			-1,
+			0,
+		):
+			raise ValueError('Only a binary input file is supported')
+		return self
+
+	def read(
+		self,
+		size: int = -1,
+		/,
+	) -> bytes:
+		return self.protocol.portal.call(self.protocol.reader.read(size))
+
+	def readline(
+		self,
+		size: int = -1,
+		/,
+	) -> bytes:
+		return self.protocol.portal.call(self.protocol.readline(size))
+
+	def sendall(
+		self,
+		data: bytes,
+	) -> None:
+		self.protocol.portal.call(self.protocol.write(data))
+		return
+
+	def close(self) -> None:
+		return
+
+
+class WebSocketProtocol(Protocol):
+	"""Run the existing RFC 6455 handler on Uvicorn's upgraded connection."""
+
+	logger = getLogger('DefEssential.Server')
+
+	def __init__(
+		self,
+		config: Any,
+		server_state: Any,
+		app_state: dict[str, Any],
+		application: Application,
+		executor: ThreadPoolExecutor,
+	):
+		self.application = application
+		self.executor = executor
+		self.state = server_state
+		self.portal = Portal(get_running_loop())
+		self.reader = StreamReader(limit=65536)
+		self.writable = Event()
+		self.writable.set()
+		self.transport: Transport
+		self.task = None
+		self.upgraded = False
+		return
+
+	def connection_made(
+		self,
+		transport,
+	) -> None:
+		if not isinstance(transport, Transport):
+			raise TypeError('A stream transport is required')
+		self.transport = transport
+		self.reader.set_transport(transport)
+		self.state.connections.add(self)
+		self.task = self.portal.loop.create_task(self.run())
+		self.state.tasks.add(self.task)
+		self.task.add_done_callback(self.state.tasks.discard)
+		return
+
+	def data_received(
+		self,
+		data: bytes,
+	) -> None:
+		self.reader.feed_data(data)
+		return
+
+	def eof_received(self) -> None:
+		self.reader.feed_eof()
+		return
+
+	def connection_lost(
+		self,
+		error,
+	) -> None:
+		self.state.connections.discard(self)
+		if error is None:
+			self.reader.feed_eof()
+		else:
+			self.reader.set_exception(error)
+		self.writable.set()
+		return
+
+	async def readline(
+		self,
+		size: int,
+	) -> bytes:
+		data = bytearray()
+		while size < 0 or len(data) < size:
+			part = await self.reader.read(1)
+			if not part:
+				break
+			data.extend(part)
+			if part == b'\n':
+				break
+		return bytes(data)
+
+	def pause_writing(self) -> None:
+		self.writable.clear()
+		return
+
+	def resume_writing(self) -> None:
+		self.writable.set()
+		return
+
+	async def write(
+		self,
+		data: bytes,
+	) -> None:
+		await self.writable.wait()
+		if self.transport.is_closing():
+			raise ClientDisconnected('WebSocket connection is closed')
+		self.transport.write(data)
+		if data.startswith(b'HTTP/1.1 101 '):
+			self.upgraded = True
+		return
+
+	def shutdown(self) -> None:
+		if self.upgraded and not self.transport.is_closing():
+			self.transport.write(WebSocketFrame(
+				WebSocketFrame.CLOSE,
+				b'\x03\xe9',
+			).encode())
+		self.transport.close()
+		self.reader.feed_eof()
+		return
+
+	async def run(self) -> None:
+		def handle() -> None:
+			server = ServerContext(
+				self.transport.get_extra_info('sockname'),
+				ServerRequestHandler,
+			)
+			# The standard handler requires the nominal socket type but uses only the file and send contracts below.
+			connection = Connection(self)
+			server.app = self.application
+			ServerRequestHandler(
+				cast(socket, connection),
+				self.transport.get_extra_info('peername'),
+				server,
+			)
+			return
+
+		worker = self.portal.loop.run_in_executor(
+			self.executor,
+			handle,
+		)
+		try:
+			await shield(worker)
+		except CancelledError:
+			self.portal.close()
+			with suppress(ClientDisconnected):
+				await worker
+			raise
+		except Exception:
+			self.logger.exception('WebSocket connection handling failed: adapter=Uvicorn')
+		finally:
+			self.portal.close()
+			self.transport.close()
+		return

DefEssential/Adapter/Implements/Uvicorn/__init__.py

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

DefEssential/Adapter/Implements/__init__.py

@@ -0,0 +1,3 @@
+"""Import the required server implementations from their respective subpackages."""
+
+__all__ = ()