DefEssential 0.1.8__23-py3-none-any.whl

DefEssential/Responses/__init__.py

@@ -0,0 +1,63 @@
+from dataclasses import (
+	asdict,
+	is_dataclass,
+)
+from json import dumps
+
+from ..Response import Response
+from .ResponseFile import ResponseFile
+
+__all__ = (
+	'ResponseFile',
+	'ResponseJSON',
+	'ResponseText',
+)
+
+
+class ResponseJSON(Response):
+	"""Serialize JSON or dataclass values as UTF-8 responses."""
+
+	def __init__(
+		self,
+		value,
+		status=200,
+		headers=None,
+	):
+		def encode(value):
+			if is_dataclass(value) and not isinstance(value, type):
+				return asdict(value)
+			raise TypeError('Value is not JSON serializable: ' + type(value).__name__)
+
+		super().__init__(
+			status=status,
+			headers=headers,
+			body=dumps(
+				value,
+				default=encode,
+				ensure_ascii=False,
+				allow_nan=False,
+			).encode('utf-8'),
+			format='application/json',
+			charset='utf-8',
+		)
+		return
+
+
+class ResponseText(Response):
+	"""Encode a string using an explicit charset."""
+
+	def __init__(
+		self,
+		text,
+		status=200,
+		headers=None,
+		charset='utf-8',
+	):
+		super().__init__(
+			status=status,
+			headers=headers,
+			body=text.encode(charset),
+			format='text/plain',
+			charset=charset,
+		)
+		return

DefEssential/Route.py

@@ -0,0 +1,55 @@
+from re import (
+	compile,
+	escape,
+)
+from typing import (
+	Optional,
+	Type,
+)
+
+from .RequestRunner import RequestRunner
+
+__all__ = (
+	'Route',
+)
+
+
+class Route:
+	"""Represent a route using the existing :name path parameter syntax."""
+
+	variable = compile(r':([A-Za-z_][A-Za-z_0-9]*)')
+
+	def __init__(
+		self,
+		method: str,
+		url: str,
+		obj: Type[RequestRunner],
+	):
+		self.method = method
+		self.url = url
+		self.object = obj
+		parts = []
+		position = 0
+		for match in self.variable.finditer(url):
+			parts.append(escape(url[position:match.start()]))
+			parts.append('(?P<{}>[^/]+)'.format(match.group(1)))
+			position = match.end()
+		parts.append(escape(url[position:]))
+		self.pattern = compile(''.join(parts))
+		self.parameter_count = self.pattern.groups
+		return
+
+	@property
+	def priority(self) -> tuple[int, int, int]:
+		return (
+			0,
+			self.parameter_count,
+			0,
+		)
+
+	def match(
+		self,
+		url: str,
+	) -> Optional[dict[str, str]]:
+		match = self.pattern.fullmatch(url)
+		return match.groupdict() if match is not None else None

DefEssential/Router.py

@@ -0,0 +1,48 @@
+from typing import (
+	Dict,
+	Tuple,
+)
+
+from .Route import Route
+
+__all__ = (
+	'Router',
+)
+
+
+class Router:
+	"""Maintain per-Application registrations and prioritize static routes."""
+
+	def __init__(self):
+		self.routes: list[Route] = []
+		return
+
+	def add(
+		self,
+		route: Route,
+	) -> None:
+		for registered in self.routes:
+			if registered.method == route.method and registered.url == route.url:
+				if registered.object is route.object:
+					return
+				raise ValueError('Route already registered: {} {}'.format(
+					route.method,
+					route.url,
+				))
+		self.routes.append(route)
+		self.routes.sort(key=lambda entry: entry.priority)
+		return
+
+	def matches(
+		self,
+		url: str,
+	) -> Dict[str, Tuple[Route, dict[str, str]]]:
+		matches = {}
+		for route in self.routes:
+			parameters = route.match(url)
+			if parameters is not None and route.method not in matches:
+				matches[route.method] = (
+					route,
+					parameters,
+				)
+		return matches

DefEssential/Runners/RunExtension.py

@@ -0,0 +1,116 @@
+from logging import getLogger
+from typing import (
+	Optional,
+	Type,
+)
+
+from ..Extension import Extension
+from ..Request import Request
+from ..RequestRunner import RequestRunner
+from ..Response import Response
+from .RunFactory import RunFactory
+
+__all__ = (
+	'RunExtensionFactory',
+)
+
+logger = getLogger('DefEssential.Extension')
+
+
+def run_extension(
+	extension: Extension,
+	request: Request,
+) -> Optional[Response]:
+	"""Wrap only the extension-processing boundary after internal RequestRunner validation."""
+	try:
+		for index, hook in enumerate(extension.request_hooks):
+			logger.debug('Extension request hook starting: request_id=%s index=%s hook=%s', request.id, index, type(hook).__qualname__)
+			result = hook(request)
+			if not isinstance(result, Request):
+				raise TypeError('ExtensionRequest hooks must return a Request')
+			logger.debug('Extension request hook completed: request_id=%s index=%s', request.id, index)
+			if request.id != result.id:
+				logger.debug('Request replaced: previous_request_id=%s request_id=%s', request.id, result.id)
+			request = result
+		logger.debug('Extension running: request_id=%s extension=%s', request.id, type(extension).__qualname__)
+		response = extension(request)
+		if response is not None and not isinstance(response, Response):
+			raise TypeError('Extension must return a Response or None')
+		writer = request.response_writer
+		if response is None and (writer is None or not writer.started):
+			raise TypeError('Extension must return a Response or start direct output')
+		if response is not None and writer is not None and writer.started:
+			response.close()
+			raise RuntimeError('Cannot return a Response after starting direct output')
+		logger.debug('Extension response provided: request_id=%s extension=%s', request.id, type(extension).__qualname__)
+		for index, hook in enumerate(extension.request_response_hooks):
+			previous = response
+			previous_body = previous.body if previous is not None else None
+			try:
+				logger.debug('Extension response hook starting: request_id=%s index=%s hook=%s', request.id, index, type(hook).__qualname__)
+				response = hook(request, response)
+				if response is not None and not isinstance(response, Response):
+					raise TypeError('ExtensionRequestResponse hooks must return a Response or None')
+				if previous is None and response is not None:
+					response.close()
+					raise TypeError('ExtensionRequestResponse hooks cannot replace direct output')
+				writer = request.response_writer
+				if response is None and (writer is None or not writer.started):
+					raise TypeError('ExtensionRequestResponse hooks cannot discard a response without direct output')
+				logger.debug('Extension response hook completed: request_id=%s index=%s', request.id, index)
+			except Exception:
+				if previous is not None:
+					previous.close()
+				raise
+			finally:
+				if previous is not None and previous.body is not previous_body:
+					close = getattr(previous_body, 'close', None)
+					if close is not None:
+						close()
+			if previous is not None and response is not previous:
+				if response is None or response.body is not previous_body:
+					previous.close()
+		return response
+	except Exception as error:
+		logger.debug('Extension failed: request_id=%s extension=%s error_type=%s', request.id, type(extension).__qualname__, type(error).__qualname__)
+		for index, hook in enumerate(extension.request_error_hooks):
+			logger.debug('Extension error hook starting: request_id=%s index=%s hook=%s', request.id, index, type(hook).__qualname__)
+			if hook(request, error) is not None:
+				raise TypeError('ExtensionRequestError hooks must return None')
+			logger.debug('Extension error hook completed: request_id=%s index=%s', request.id, index)
+		raise
+
+
+class RunExtensionFactory(RunFactory[Type[RequestRunner]]):
+	"""Create a request handler class that delegates calls to an extension."""
+
+	def __init__(
+		self,
+		extension: Extension,
+		method: str,
+		path: str,
+	):
+		self.extension = extension
+		self.method = method
+		self.path = path
+		return
+
+	def __call__(self) -> Type[RequestRunner]:
+		extension = self.extension
+
+		class RunExtension(
+			RequestRunner,
+			method=self.method,
+			url=self.path,
+			name=type(extension).__name__,
+		):
+			def run(
+				self,
+				request: Request,
+			) -> Optional[Response]:
+				return run_extension(
+					extension,
+					request,
+				)
+
+		return RunExtension

DefEssential/Runners/RunFactory.py

@@ -0,0 +1,26 @@
+from abc import (
+	ABC,
+	abstractmethod,
+)
+from typing import (
+	Generic,
+	TypeVar,
+)
+
+__all__ = (
+	'RunFactory',
+)
+
+
+T = TypeVar('T')
+
+
+class RunFactory(
+	ABC,
+	Generic[T],
+):
+	"""Store configuration and create a request handler to register when called."""
+
+	@abstractmethod
+	def __call__(self) -> T:
+		raise NotImplementedError

DefEssential/Runners/RunOptions.py

@@ -0,0 +1,77 @@
+from ..Error import ClientError
+from ..Request import Request
+from ..Response import Response
+from ..Router import Router
+from ..CrossOriginResourceSharing import CrossOriginResourceSharing
+
+__all__ = (
+	'RunOptions',
+)
+
+
+class RunOptions:
+	"""Compute Allow and CORS preflight responses from Application-owned routes."""
+
+	def run(
+		self,
+		request: Request,
+		router: Router,
+	) -> Response:
+		if request.uri == '*':
+			methods = {route.method for route in router.routes}
+			methods.add('OPTIONS')
+			return Response(
+				status=204,
+				headers={'Allow': ', '.join(sorted(methods))},
+			)
+		matches = router.matches(request.path)
+		if not matches:
+			raise ClientError(
+				'No matching route',
+				status=404,
+			)
+		methods = sorted(set(matches) | {'OPTIONS'})
+		response = Response(
+			status=204,
+			headers={'Allow': ', '.join(methods)},
+		)
+		method = request.header('Access-Control-Request-Method')
+		if method is None:
+			return response
+		if method not in matches:
+			raise ClientError(
+				'Preflight method not allowed',
+				status=405,
+			)
+		properties = matches[method][0].object.properties
+		cross_origin_resource_sharing = CrossOriginResourceSharing(properties)
+		if request.header('Origin') is None or not cross_origin_resource_sharing.has_origin_policy():
+			raise ClientError(
+				'No CORS policy is configured for this preflight request',
+				status=403,
+			)
+		cross_origin_resource_sharing.validate_origin(request)
+		headers = cross_origin_resource_sharing.allowed_request_headers()
+		requested = request.header('Access-Control-Request-Headers')
+		if requested is not None:
+			allowed = {name.lower() for name in headers}
+			if any(name.strip().lower() not in allowed for name in requested.split(',')):
+				raise ClientError('Preflight header not allowed')
+		response.header(
+			'Access-Control-Allow-Methods',
+			method,
+		)
+		if headers:
+			response.header(
+				'Access-Control-Allow-Headers',
+				', '.join(headers),
+			)
+		response.header(
+			'Vary',
+			'Access-Control-Request-Method, Access-Control-Request-Headers',
+		)
+		return cross_origin_resource_sharing.apply_to_response(
+			request,
+			response,
+			preflight=True,
+		)

DefEssential/Runners/RunRequest.py

@@ -0,0 +1,198 @@
+from logging import getLogger
+from typing import (
+	Optional,
+	Type,
+)
+
+from ..RequestRunner import RequestRunner
+from ..Request import Request
+from ..Response import (
+	Response,
+	close_bodies,
+)
+from ..CrossOriginResourceSharing import CrossOriginResourceSharing
+
+__all__ = (
+	'RunRequest',
+)
+
+
+class RunRequest:
+	"""Manage validation, handler execution, response processing, and error observation."""
+
+	logger = getLogger('DefEssential.RequestRunner')
+
+	def __init__(
+		self,
+		obj: Type[RequestRunner],
+	):
+		self.object = obj
+		self.cross_origin_resource_sharing = CrossOriginResourceSharing(obj.properties)
+		return
+
+	def run(
+		self,
+		request: Request,
+	) -> Optional[Response]:
+		properties = self.object.properties
+		request_id = request.id
+		phase = 'runner.cors_origin'
+
+		def apply_response_hooks(response: Response) -> Response:
+			for index, hook in enumerate(properties.on_request_response):
+				previous = response
+				previous_body = previous.body
+				phase = 'runner.response_hook.' + str(index)
+				self.logger.debug(
+					'Response hook starting: request_id=%s phase=%s hook=%s',
+					request.id,
+					phase,
+					type(hook).__qualname__,
+				)
+				try:
+					result = hook(request, previous)
+					if not isinstance(result, Response):
+						raise TypeError('RequestRunnerRequestResponse hooks must return a Response')
+				except Exception:
+					close_bodies(
+						previous_body,
+						previous.body,
+						preserve_error=True,
+					)
+					raise
+				response = result
+				self.logger.debug('Response hook completed: request_id=%s phase=%s', request.id, phase)
+				try:
+					close_bodies(*(
+						body for body in (
+							previous_body,
+							previous.body,
+						)
+						if body is not response.body
+					))
+				except Exception:
+					close_bodies(
+						response.body,
+						preserve_error=True,
+					)
+					raise
+			try:
+				self.logger.debug('CORS response starting: request_id=%s', request.id)
+				response = self.cross_origin_resource_sharing.apply_to_response(
+					request,
+					response,
+				)
+				self.logger.debug('CORS response completed: request_id=%s', request.id)
+				return response
+			except Exception:
+				close_bodies(
+					response.body,
+					preserve_error=True,
+				)
+				raise
+
+		writer = None
+		try:
+			self.logger.debug('CORS origin check starting: request_id=%s', request.id)
+			self.cross_origin_resource_sharing.validate_origin(request)
+			self.logger.debug('CORS origin check completed: request_id=%s', request.id)
+			for name, check in (
+				(
+					'auth',
+					properties.auth,
+				),
+				(
+					'parameters',
+					properties.parameters,
+				),
+				(
+					'query',
+					properties.qs,
+				),
+				(
+					'headers',
+					properties.headers,
+				),
+			):
+				if check is not None:
+					phase = 'runner.validation.' + name
+					self.logger.debug(
+						'Validation starting: request_id=%s phase=%s validator=%s',
+						request.id,
+						phase,
+						type(check).__qualname__,
+					)
+					check(request)
+					self.logger.debug('Validation completed: request_id=%s phase=%s', request.id, phase)
+			if properties.body is not None:
+				phase = 'runner.body'
+				self.logger.debug('Request body processing: request_id=%s processor=%s', request.id, type(properties.body).__qualname__)
+				request.body = properties.body(request)
+				self.logger.debug('Request body processed: request_id=%s', request.id)
+			phase = 'runner.create'
+			self.logger.debug('Handler creating: request_id=%s handler=%s.%s', request.id, self.object.__module__, self.object.__qualname__)
+			runner = self.object()
+			self.logger.debug('Handler created: request_id=%s', request.id)
+			for index, hook in enumerate(properties.on_request):
+				phase = 'runner.request_hook.' + str(index)
+				self.logger.debug('Request hook starting: request_id=%s phase=%s hook=%s', request.id, phase, type(hook).__qualname__)
+				result = hook(request)
+				if not isinstance(result, Request):
+					raise TypeError('RequestRunnerRequest hooks must return a Request')
+				self.logger.debug('Request hook completed: request_id=%s phase=%s', request.id, phase)
+				if request.id != result.id:
+					self.logger.debug('Request replaced: previous_request_id=%s request_id=%s', request.id, result.id)
+				request = result
+			writer = request.response_writer
+			if writer is not None:
+				writer.on_request_response = apply_response_hooks
+			phase = 'runner.run'
+			self.logger.debug('Handler running: request_id=%s handler=%s.%s', request.id, self.object.__module__, self.object.__qualname__)
+			response = runner.run(request)
+			self.logger.debug('Handler returned: request_id=%s', request.id)
+			phase = 'runner.response_validation'
+			if writer is not None and writer.started:
+				if response is not None:
+					if isinstance(response, Response):
+						close_bodies(
+							response.body,
+							preserve_error=True,
+						)
+					raise RuntimeError('Cannot return a Response after starting direct output')
+				phase = 'runner.direct_end'
+				self.logger.debug('Direct response ending: request_id=%s', request.id)
+				writer.end()
+				self.logger.debug('Runner response provided: request_id=%s mode=direct', request.id)
+				return None
+			if not isinstance(response, Response):
+				raise TypeError('run must return a Response or start a response through the writer')
+			phase = 'runner.response_hooks'
+			response = apply_response_hooks(response)
+			self.logger.debug(
+				'Runner response provided: request_id=%s mode=returned status=%s',
+				request.id,
+				response.status,
+			)
+			return response
+		except Exception as error:
+			self.logger.debug(
+				'Runner failed: request_id=%s phase=%s handler=%s error_type=%s',
+				request_id,
+				phase,
+				self.object.__module__ + '.' + self.object.__qualname__,
+				type(error).__qualname__,
+			)
+			for index, hook in enumerate(properties.on_request_error):
+				self.logger.debug(
+					'Error hook starting: request_id=%s phase=runner.error_hook.%s hook=%s',
+					request.id,
+					index,
+					type(hook).__qualname__,
+				)
+				if hook(request, error) is not None:
+					raise TypeError('RequestRunnerRequestError hooks must return None')
+				self.logger.debug('Error hook completed: request_id=%s index=%s', request.id, index)
+			raise
+		finally:
+			if writer is not None:
+				writer.on_request_response = None

DefEssential/Runners/__init__.py

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

DefEssential/Startup.py

@@ -0,0 +1,104 @@
+from os import environ
+import sys
+from .Application import Application
+
+__all__ = (
+	'LOGO',
+	'supports_color',
+	'colorize_logo',
+	'startup',
+)
+
+
+LOGO = r"""
+▄▄▄▄▄▄           ▄▄ ▄▄▄▄▄▄▄                              ▄▄       ▄▄
+███▀▀██▄        ██  ███▀▀▀▀                          ██  ▀▀       ██
+███  ███ ▄█▀█▄ ▀██▀ █████   ▄██▀▀ ▄██▀▀ ▄█▀█▄ ████▄ ▀██▀ ██  ▀▀█▄ ██
+███  ███ ██▄█▀  ██  ███     ▀▀██▄ ▀▀██▄ ██▄█▀ ██ ██  ██  ██ ▄█▀██ ██
+██████▀  ▀█▄▄▄  ██  ███████ ▀███▀ ▀███▀ ▀█▄▄▄ ██ ██  ██  ██ ▀█▄██ ██
+
+Just def. Let web apps do the work. You don't need to await this.
+"""
+
+
+def supports_color() -> bool:
+	"""Use colors only for terminal output and honor NO_COLOR."""
+	return (
+		getattr(sys.stdout, 'isatty', lambda: False)()
+		and 'NO_COLOR' not in environ
+	)
+
+
+def colorize_logo(logo: str) -> str:
+	"""Apply the existing startup color gradient to the five banner lines."""
+	colors = (
+		'\033[38;5;39m',
+		'\033[38;5;45m',
+		'\033[38;5;51m',
+		'\033[38;5;45m',
+		'\033[38;5;39m',
+	)
+	lines = []
+	art_line = 0
+	for line in logo.splitlines(keepends=True):
+		if line.strip() and art_line < len(colors):
+			newline = '\n' if line.endswith('\n') else ''
+			lines.append(
+				f'{colors[art_line]}{line[:-1] if newline else line}'
+				f'\033[0m{newline}',
+			)
+			art_line += 1
+		else:
+			lines.append(line)
+	return ''.join(lines)
+
+
+def startup(
+	application: Application,
+	server: str,
+	host: str,
+	port: int,
+) -> None:
+	"""Log the application's registration details, adapter name, and listening address."""
+	if not isinstance(host, str):
+		raise TypeError('HTTP listen address must be a string')
+	address = f'[{host}]' if ':' in host else host
+	logo = LOGO.rstrip()
+	starting = 'Starting'
+	if supports_color():
+		logo = colorize_logo(logo)
+		starting = f'\033[1;38;5;51m{starting}\033[0m'
+	routes = [
+		route for route in application.router.routes
+		if route not in application.extension_routes
+	]
+	lines = [
+		logo,
+		'',
+		starting,
+		f'  Server: {server}',
+		f'  Listen: http://{address}:{port}',
+		f'  Applications: {len(routes)} applications',
+	]
+	for route in routes:
+		lines.extend((
+			f'    - {route.object.properties.name if route.object.properties.name is not None else route.object.__qualname__}',
+			f'      {route.method} {route.url}',
+		))
+	if application.exts:
+		lines.append(f'  Extensions: {len(application.exts)} extensions')
+		for extension in application.exts:
+			lines.append(
+				f'    - {extension}',
+			)
+	lines.append('\n')
+	text = '\n'.join(lines)
+	encoding = getattr(sys.stdout, 'encoding', None)
+	if encoding is not None:
+		# Escape only unprintable characters to preserve the startup details.
+		text = text.encode(encoding, errors='backslashreplace').decode(encoding)
+	print(
+		text,
+		flush=True,
+	)
+	return