DefEssential 0.1.8__25-py3-none-any.whl

DefEssential/Extensions/Status.py

@@ -0,0 +1,110 @@
+from logging import getLogger
+from typing import (
+	Optional,
+	Sequence,
+	Union,
+)
+
+from ..Application import Application
+from ..Extension import (
+	Extension,
+	ExtensionCleanup,
+	ExtensionRequest,
+	ExtensionRequestError,
+	ExtensionRequestResponse,
+	ExtensionStartup,
+)
+from ..Request import Request
+from ..Response import Response
+from .Utils import page
+from .Utils.Routes import (
+	http_routes,
+	validate_path,
+)
+
+__all__ = (
+	'Status',
+)
+
+
+class Status(Extension):
+	"""Provide a status page using an explicitly configured same-origin metrics path."""
+
+	logger = getLogger('DefEssential.Extensions.Status')
+
+	def __init__(
+		self,
+		path: str,
+		*,
+		metrics_uri: str,
+		title: str = 'DefEssential',
+		description: str = '',
+		on_startup: Optional[Union[
+			ExtensionStartup,
+			Sequence[ExtensionStartup],
+		]] = None,
+		on_cleanup: Optional[Union[
+			ExtensionCleanup,
+			Sequence[ExtensionCleanup],
+		]] = None,
+		on_request: Optional[Union[
+			ExtensionRequest,
+			Sequence[ExtensionRequest],
+		]] = None,
+		on_request_response: Optional[Union[
+			ExtensionRequestResponse,
+			Sequence[ExtensionRequestResponse],
+		]] = None,
+		on_request_error: Optional[Union[
+			ExtensionRequestError,
+			Sequence[ExtensionRequestError],
+		]] = None,
+	):
+		super().__init__(
+			on_startup=on_startup,
+			on_cleanup=on_cleanup,
+			on_request=on_request,
+			on_request_response=on_request_response,
+			on_request_error=on_request_error,
+		)
+		validate_path(path)
+		self.path = path
+		if (
+			not isinstance(metrics_uri, str)
+			or not metrics_uri.startswith('/')
+			or metrics_uri.startswith('//')
+			or any(character.isspace() or ord(character) < 32 or character == '\\' for character in metrics_uri)
+		):
+			raise ValueError('Status metrics_uri must be a same-origin absolute path')
+		if not isinstance(title, str) or not title or not isinstance(description, str):
+			raise ValueError('Status title must be a non-empty string and description must be a string')
+		self.title = title
+		self.description = description
+		self.metrics_uri = metrics_uri
+		return
+
+	def __str__(self) -> str:
+		return '{}(uri={}, metrics={})'.format(type(self).__name__, self.path, self.metrics_uri)
+
+	def startup(
+		self,
+		application: Application,
+	) -> None:
+		for route in http_routes(self, self.path):
+			application.add_extension_route(self, route)
+		super().startup(application)
+		return
+
+	def __call__(
+		self,
+		request: Request,
+	) -> Response:
+		self.logger.debug('Status page preparing: request_id=%s', request.id)
+		response = page(
+			'Status',
+			self.title,
+			self.description,
+			parameters={'metrics_uri': self.metrics_uri},
+		)
+		self.logger.debug('Status page prepared: request_id=%s', request.id)
+		return response

DefEssential/Extensions/Swagger.html

@@ -0,0 +1,77 @@
+<!doctype html>
+<html lang="ko">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{{title}} Swagger UI</title>
+  <meta name="description" content="{{description}}">
+  <style>
+    :root {
+      --ui-font: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", "Malgun Gothic", "Apple SD Gothic Neo", sans-serif;
+      --code-font: Consolas, "SFMono-Regular", Menlo, "Malgun Gothic", "Apple SD Gothic Neo", monospace;
+    }
+    body { margin: 0; background: #fafafa; font-family: var(--ui-font); }
+    .swagger-ui, .swagger-ui * { font-family: var(--ui-font) !important; }
+    .swagger-ui code, .swagger-ui code *, .swagger-ui pre, .swagger-ui pre *,
+    .swagger-ui textarea, .swagger-ui .opblock-summary-path, .swagger-ui .opblock-summary-path *,
+    .swagger-ui .opblock-summary-path__deprecated, .swagger-ui .opblock-summary-path__deprecated * {
+      font-family: var(--code-font) !important;
+    }
+    #loading, #error, noscript { display: block; margin: 16px 20px; font-size: 14px; line-height: 1.6; }
+    #error { color: #b00020; white-space: pre-wrap; }
+    #error a { margin-left: 8px; }
+    [hidden] { display: none !important; }
+  </style>
+</head>
+<body>
+  <p id="loading" role="status">Swagger UI를 불러오는 중입니다.</p>
+  <div id="error" role="alert" hidden><span id="error-message"></span><a href="{{spec_url}}">OpenAPI 문서</a></div>
+  <noscript>Swagger UI를 사용하려면 JavaScript를 활성화하세요. <a href="{{spec_url}}">OpenAPI 문서</a></noscript>
+  <div id="swagger-ui" data-spec-url="{{spec_url}}"></div>
+  <script>
+    'use strict';
+    const error = document.getElementById('error');
+    function fail(message) {
+      document.getElementById('loading').hidden = true;
+      error.hidden = false;
+      document.getElementById('error-message').textContent = message;
+    }
+    const stylesheet = document.createElement('link');
+    stylesheet.rel = 'stylesheet';
+    stylesheet.crossOrigin = 'anonymous';
+    stylesheet.href = 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.32.0/swagger-ui.css';
+    stylesheet.addEventListener('error', () => fail('Failed to load Swagger UI styles. Check your CDN connection.'));
+    document.head.append(stylesheet);
+  </script>
+  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.32.0/swagger-ui-bundle.js" crossorigin="anonymous"></script>
+  <script>
+    if (typeof SwaggerUIBundle !== 'function') {
+      fail('Failed to load Swagger UI. Check your CDN connection.');
+    } else {
+      try {
+        window.ui = SwaggerUIBundle({
+          url: document.getElementById('swagger-ui').dataset.specUrl,
+          dom_id: '#swagger-ui',
+          deepLinking: true,
+          validatorUrl: null,
+          persistAuthorization: false,
+          queryConfigEnabled: false,
+          withCredentials: false,
+          requestInterceptor(request) {
+            const url = new URL(request.url, location.origin);
+            if (url.origin !== location.origin || url.username || url.password) {
+              throw new Error('Only same-origin API and document requests are allowed.');
+            }
+            request.credentials = 'same-origin';
+            request.redirect = 'error';
+            return request;
+          },
+          onComplete() { document.getElementById('loading').hidden = true; }
+        });
+      } catch (failure) {
+        fail('Failed to initialize Swagger UI: ' + failure.message);
+      }
+    }
+  </script>
+</body>
+</html>

DefEssential/Extensions/Swagger.py

@@ -0,0 +1,117 @@
+from logging import getLogger
+from typing import (
+	Optional,
+	Sequence,
+	Union,
+)
+
+from ..Application import Application
+from ..Extension import (
+	Extension,
+	ExtensionCleanup,
+	ExtensionRequest,
+	ExtensionRequestError,
+	ExtensionRequestResponse,
+	ExtensionStartup,
+)
+from ..Request import Request
+from ..Response import Response
+from .Utils import page
+from .Utils.Routes import (
+	http_routes,
+	validate_path,
+)
+
+__all__ = (
+	'Swagger',
+)
+
+
+class Swagger(Extension):
+	"""Connect Swagger UI to an explicitly configured same-origin specification path."""
+
+	logger = getLogger('DefEssential.Extensions.Swagger')
+
+	def __init__(
+		self,
+		path: str,
+		*,
+		spec_uri: str,
+		title: str = 'DefEssential',
+		description: str = '',
+		on_startup: Optional[Union[
+			ExtensionStartup,
+			Sequence[ExtensionStartup],
+		]] = None,
+		on_cleanup: Optional[Union[
+			ExtensionCleanup,
+			Sequence[ExtensionCleanup],
+		]] = None,
+		on_request: Optional[Union[
+			ExtensionRequest,
+			Sequence[ExtensionRequest],
+		]] = None,
+		on_request_response: Optional[Union[
+			ExtensionRequestResponse,
+			Sequence[ExtensionRequestResponse],
+		]] = None,
+		on_request_error: Optional[Union[
+			ExtensionRequestError,
+			Sequence[ExtensionRequestError],
+		]] = None,
+	):
+		super().__init__(
+			on_startup=on_startup,
+			on_cleanup=on_cleanup,
+			on_request=on_request,
+			on_request_response=on_request_response,
+			on_request_error=on_request_error,
+		)
+		validate_path(path)
+		self.path = path
+		if (
+			not isinstance(spec_uri, str)
+			or not spec_uri.startswith('/')
+			or spec_uri.startswith('//')
+			or any(character.isspace() or ord(character) < 32 or character == '\\' for character in spec_uri)
+		):
+			raise ValueError('Swagger spec_uri must be a same-origin absolute path')
+		if not isinstance(title, str) or not title or not isinstance(description, str):
+			raise ValueError('Swagger title must be a non-empty string and description must be a string')
+		self.title = title
+		self.description = description
+		self.spec_uri = spec_uri
+		return
+
+	def __str__(self) -> str:
+		return '{}(uri={}, spec={})'.format(type(self).__name__, self.path, self.spec_uri)
+
+	def startup(
+		self,
+		application: Application,
+	) -> None:
+		for route in http_routes(self, self.path):
+			application.add_extension_route(self, route)
+		super().startup(application)
+		return
+
+	def __call__(
+		self,
+		request: Request,
+	) -> Response:
+		self.logger.debug('Swagger page preparing: request_id=%s', request.id)
+		response = page(
+			'Swagger',
+			self.title,
+			self.description,
+			parameters={'spec_url': self.spec_uri},
+			policy=(
+				"default-src 'none'; "
+				"script-src 'unsafe-inline' https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.32.0/; "
+				"style-src 'unsafe-inline' https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.32.0/; "
+				"img-src 'self' data: blob:; font-src 'self' data:; "
+				"connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'"
+			),
+		)
+		self.logger.debug('Swagger page prepared: request_id=%s', request.id)
+		return response

DefEssential/Extensions/Utils/Routes.py

@@ -0,0 +1,42 @@
+from ...Extension import Extension
+from ...Route import Route
+from ...Runners.RunExtension import RunExtensionFactory
+
+__all__ = (
+	'validate_path',
+	'http_routes',
+)
+
+
+def validate_path(path: str) -> None:
+	if not isinstance(path, str) or not path.startswith('/') or any(
+		character in path for character in (
+			'?',
+			'#',
+			':',
+		)
+	):
+		raise ValueError('Extensions require an absolute HTTP path without parameters')
+	return
+
+
+def http_routes(
+	extension: Extension,
+	path: str,
+) -> tuple[Route, ...]:
+	"""Create GET and HEAD request handlers for an extension."""
+	return tuple(
+		Route(
+			method,
+			path,
+			RunExtensionFactory(
+				extension,
+				method,
+				path,
+			)(),
+		)
+		for method in (
+			'GET',
+			'HEAD',
+		)
+	)

DefEssential/Extensions/Utils/__init__.py

@@ -0,0 +1,43 @@
+from html import escape
+from importlib.resources import files
+from re import sub
+from typing import Optional
+
+from ...Response import Response
+
+__all__ = (
+	'page',
+)
+
+
+def page(
+	name: str,
+	title: str,
+	description: str,
+	*,
+	parameters: Optional[dict[str, str]] = None,
+	policy: Optional[str] = None,
+) -> Response:
+	values = {
+		'title': escape(title),
+		'description': escape(description),
+	}
+	if parameters is not None:
+		values.update({key: escape(value) for key, value in parameters.items()})
+	text = files(__name__.rpartition('.')[0]).joinpath(name + '.html').read_text(encoding='utf-8')
+	text = sub(
+		r'\{\{(' + '|'.join(values) + r')\}\}',
+		lambda match: values[match[1]],
+		text,
+	)
+	return Response(
+		body=text.encode('utf-8'),
+		format='text/html',
+		charset='utf-8',
+		headers={
+			'Content-Security-Policy': policy if policy is not None else "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'",
+			'X-Content-Type-Options': 'nosniff',
+			'Referrer-Policy': 'no-referrer',
+			'Cache-Control': 'no-store',
+		},
+	)

DefEssential/Extensions/__init__.py

@@ -0,0 +1,21 @@
+from .Status import Status
+from .Ping import Ping
+from .Metrics import (
+	Metrics,
+	MetricsCollector,
+)
+from .Specifications import Specifications
+from .Swagger import Swagger
+from .File import File
+from .FileSystem import FileSystem
+
+__all__ = (
+	'Status',
+	'Ping',
+	'Metrics',
+	'Specifications',
+	'Swagger',
+	'File',
+	'FileSystem',
+	'MetricsCollector',
+)

DefEssential/IO/Readers/ChunkedStream.py

@@ -0,0 +1,106 @@
+from ...Error import ClientError
+from ..RequestReader import RequestReader
+
+__all__ = (
+	'ChunkedStream',
+)
+
+
+class ChunkedStream:
+	"""Decode HTTP/1.1 chunked transfer coding from raw request input."""
+
+	def __init__(
+		self,
+		reader: RequestReader,
+	):
+		if not reader.chunked:
+			raise ValueError('ChunkedStream requires a chunked request body')
+		self.reader = reader
+		self.remaining = 0
+		self.finished = reader.finished
+		return
+
+	def next_chunk(self) -> None:
+		line = self.reader.line()
+		size = line.split(b';', 1)[0]
+		if not size or any(byte not in b'0123456789abcdefABCDEF' for byte in size):
+			raise ClientError('Invalid chunk size')
+		self.remaining = int(size, 16)
+		if self.remaining == 0:
+			while True:
+				trailer = self.reader.line()
+				if not trailer:
+					break
+				name, separator, _ = trailer.partition(b':')
+				if not separator or name.lower() in (
+					b'content-length',
+					b'transfer-encoding',
+					b'host',
+				):
+					raise ClientError('Invalid chunked trailer')
+			self.finished = True
+			self.reader.finished = True
+		return
+
+	def take(
+		self,
+		size: int,
+	) -> bytes:
+		data = self.reader.exact(size)
+		self.remaining -= size
+		if self.remaining == 0 and self.reader.exact(2) != b'\r\n':
+			raise ClientError('Invalid chunk delimiter')
+		return data
+
+	def read(
+		self,
+		size: int = -1,
+	) -> bytes:
+		if size < -1:
+			raise ValueError('Read size must be at least -1')
+		if self.reader.decoded:
+			data = self.reader.read(size)
+			self.finished = self.reader.finished
+			return data
+		parts = []
+		while not self.finished and (size == -1 or size > 0):
+			if self.remaining == 0:
+				self.next_chunk()
+				if self.finished:
+					break
+			part = self.take(self.remaining if size == -1 else min(size, self.remaining))
+			parts.append(part)
+			if size != -1:
+				size -= len(part)
+		return b''.join(parts)
+
+	def chunk(
+		self,
+		size: int = -1,
+	) -> bytes:
+		"""Read up to size bytes without crossing the current chunk boundary."""
+		if size < -1:
+			raise ValueError('Read size must be at least -1')
+		if self.reader.decoded:
+			return self.read(size)
+		if size == 0 or self.finished:
+			return b''
+		if self.remaining == 0:
+			self.next_chunk()
+			if self.finished:
+				return b''
+		return self.take(self.remaining if size == -1 else min(size, self.remaining))
+
+	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/Readers/ContentReader.py

@@ -0,0 +1,36 @@
+from abc import (
+	ABC,
+	abstractmethod,
+)
+from typing import Any
+
+from ...Request import Request
+from ..RequestReader import RequestReader
+
+__all__ = (
+	'ContentReader',
+	'TypeReader',
+)
+
+
+class ContentReader(ABC):
+	"""Define body parsing and streaming input selection."""
+
+	@abstractmethod
+	def __call__(
+		self,
+		request: Request,
+		reader: RequestReader,
+	) -> Any:
+		raise NotImplementedError
+
+
+class TypeReader(ABC):
+	"""Define conversion of individual JSON leaf values."""
+
+	@abstractmethod
+	def __call__(
+		self,
+		value: Any,
+	) -> Any:
+		raise NotImplementedError