pulse-framework 0.1.62__py3-none-any.whl

pulse/middleware.py

@@ -0,0 +1,471 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Any, Generic, TypeVar, overload, override
+
+from pulse.env import env
+from pulse.messages import (
+	ClientMessage,
+	Prerender,
+	PrerenderPayload,
+)
+from pulse.request import PulseRequest
+
+T = TypeVar("T")
+
+
+class Redirect:
+	"""Redirect response. Causes navigation to the specified path.
+
+	Attributes:
+		path: The path to redirect to.
+
+	Example:
+
+	```python
+	return ps.Redirect("/login")
+	```
+	"""
+
+	path: str
+
+	def __init__(self, path: str) -> None:
+		"""Initialize a redirect response.
+
+		Args:
+			path: The path to redirect to.
+		"""
+		self.path = path
+
+
+class NotFound:
+	"""Not found response. Returns 404."""
+
+
+class Ok(Generic[T]):
+	"""Success response wrapper.
+
+	Use ``Ok(None)`` for void success, or ``Ok(payload)`` to wrap a value.
+
+	Attributes:
+		payload: The wrapped success value.
+
+	Example:
+
+	```python
+	return ps.Ok(None)  # Allow request
+	return ps.Ok(prerender_result)  # Return with payload
+	```
+	"""
+
+	payload: T
+
+	@overload
+	def __init__(self, payload: T) -> None: ...
+	@overload
+	def __init__(self, payload: None = None) -> None: ...
+	def __init__(self, payload: T | None = None) -> None:
+		"""Initialize a success response.
+
+		Args:
+			payload: The success value (optional, defaults to None).
+		"""
+		self.payload = payload  # pyright: ignore[reportAttributeAccessIssue]
+
+
+class Deny:
+	"""Denial response. Blocks the request."""
+
+
+PrerenderResponse = Ok[Prerender] | Redirect | NotFound
+"""Response type for batch prerender: ``Ok[Prerender] | Redirect | NotFound``."""
+
+ConnectResponse = Ok[None] | Deny
+"""Response type for WebSocket connection: ``Ok[None] | Deny``."""
+
+
+class PulseMiddleware:
+	"""Base middleware class with pass-through defaults.
+
+	Subclass and override hooks to implement custom behavior. Each hook receives
+	a ``next`` callable to continue the middleware chain.
+
+	Attributes:
+		dev: If True, middleware is only active in dev environments.
+
+	Example:
+
+	```python
+	class AuthMiddleware(ps.PulseMiddleware):
+	    async def prerender_route(
+	        self,
+	        *,
+	        path: str,
+	        request: ps.PulseRequest,
+	        route_info: ps.RouteInfo,
+	        session: dict[str, Any],
+	        next,
+	    ):
+	        if path.startswith("/admin") and not session.get("is_admin"):
+	            return ps.Redirect("/login")
+	        return await next()
+
+	    async def connect(self, *, request, session, next):
+	        if not session.get("user_id"):
+	            return ps.Deny()
+	        return await next()
+	```
+	"""
+
+	dev: bool
+
+	def __init__(self, dev: bool = False) -> None:
+		"""Initialize middleware.
+
+		Args:
+			dev: If True, this middleware is only active in dev environments.
+		"""
+		self.dev = dev
+
+	async def prerender(
+		self,
+		*,
+		payload: "PrerenderPayload",
+		request: PulseRequest,
+		session: dict[str, Any],
+		next: Callable[[], Awaitable[PrerenderResponse]],
+	) -> PrerenderResponse:
+		"""Handle batch prerender for the full request.
+
+		Receives the full PrerenderPayload (all paths). Call next() to get the
+		Prerender result and can modify it (views and directives) before returning.
+		"""
+		return await next()
+
+	async def connect(
+		self,
+		*,
+		request: PulseRequest,
+		session: dict[str, Any],
+		next: Callable[[], Awaitable[ConnectResponse]],
+	) -> ConnectResponse:
+		"""Handle WebSocket connection establishment.
+
+		Args:
+			request: Normalized request object.
+			session: Session data dictionary.
+			next: Callable to continue the middleware chain.
+
+		Returns:
+			``Ok[None]`` to allow, ``Deny`` to reject.
+		"""
+		return await next()
+
+	async def message(
+		self,
+		*,
+		data: ClientMessage,
+		session: dict[str, Any],
+		next: Callable[[], Awaitable[Ok[None]]],
+	) -> Ok[None] | Deny:
+		"""Handle per-message authorization.
+
+		Args:
+			data: Client message data.
+			session: Session data dictionary.
+			next: Callable to continue the middleware chain.
+
+		Returns:
+			``Ok[None]`` to allow, ``Deny`` to block.
+		"""
+		return await next()
+
+	async def channel(
+		self,
+		*,
+		channel_id: str,
+		event: str,
+		payload: Any,
+		request_id: str | None,
+		session: dict[str, Any],
+		next: Callable[[], Awaitable[Ok[None]]],
+	) -> Ok[None] | Deny:
+		"""Handle channel message authorization.
+
+		Args:
+			channel_id: Channel identifier.
+			event: Event name.
+			payload: Event payload.
+			request_id: Request ID if awaiting response.
+			session: Session data dictionary.
+			next: Callable to continue the middleware chain.
+
+		Returns:
+			``Ok[None]`` to allow, ``Deny`` to block.
+		"""
+		return await next()
+
+
+class MiddlewareStack(PulseMiddleware):
+	"""Composable stack of ``PulseMiddleware`` executed in order.
+
+	Each middleware receives a ``next`` callable that advances the chain. If a
+	middleware returns without calling ``next``, the chain short-circuits.
+
+	Args:
+		middlewares: Sequence of middleware instances.
+
+	Example:
+
+	```python
+	app = ps.App(
+	    middleware=ps.stack(
+	        AuthMiddleware(),
+	        LoggingMiddleware(),
+	    )
+	)
+	```
+	"""
+
+	def __init__(self, middlewares: Sequence[PulseMiddleware]) -> None:
+		"""Initialize middleware stack.
+
+		Args:
+			middlewares: Sequence of middleware instances.
+		"""
+		super().__init__(dev=False)
+		# Filter out dev middlewares when not in dev environment
+		if env.pulse_env != "dev":
+			middlewares = [mw for mw in middlewares if not mw.dev]
+		self._middlewares: list[PulseMiddleware] = list(middlewares)
+
+	@override
+	async def prerender(
+		self,
+		*,
+		payload: "PrerenderPayload",
+		request: PulseRequest,
+		session: dict[str, Any],
+		next: Callable[[], Awaitable[PrerenderResponse]],
+	) -> PrerenderResponse:
+		async def dispatch(index: int) -> PrerenderResponse:
+			if index >= len(self._middlewares):
+				return await next()
+			mw = self._middlewares[index]
+
+			async def _next() -> PrerenderResponse:
+				return await dispatch(index + 1)
+
+			return await mw.prerender(
+				payload=payload,
+				request=request,
+				session=session,
+				next=_next,
+			)
+
+		return await dispatch(0)
+
+	@override
+	async def connect(
+		self,
+		*,
+		request: PulseRequest,
+		session: dict[str, Any],
+		next: Callable[[], Awaitable[ConnectResponse]],
+	) -> ConnectResponse:
+		async def dispatch(index: int) -> ConnectResponse:
+			if index >= len(self._middlewares):
+				return await next()
+			mw = self._middlewares[index]
+
+			async def _next() -> ConnectResponse:
+				return await dispatch(index + 1)
+
+			return await mw.connect(request=request, session=session, next=_next)
+
+		return await dispatch(0)
+
+	@override
+	async def message(
+		self,
+		*,
+		data: ClientMessage,
+		session: dict[str, Any],
+		next: Callable[[], Awaitable[Ok[None]]],
+	) -> Ok[None] | Deny:
+		async def dispatch(index: int) -> Ok[None] | Deny:
+			if index >= len(self._middlewares):
+				return await next()
+			mw = self._middlewares[index]
+
+			async def _next() -> Ok[None]:
+				result = await dispatch(index + 1)
+				# If dispatch returns Deny, the middleware should have short-circuited
+				# This should only be called when continuing the chain
+				if isinstance(result, Deny):
+					# This shouldn't happen, but handle it gracefully
+					return Ok(None)
+				return result
+
+			return await mw.message(session=session, data=data, next=_next)
+
+		return await dispatch(0)
+
+	@override
+	async def channel(
+		self,
+		*,
+		channel_id: str,
+		event: str,
+		payload: Any,
+		request_id: str | None,
+		session: dict[str, Any],
+		next: Callable[[], Awaitable[Ok[None]]],
+	) -> Ok[None] | Deny:
+		async def dispatch(index: int) -> Ok[None] | Deny:
+			if index >= len(self._middlewares):
+				return await next()
+			mw = self._middlewares[index]
+
+			async def _next() -> Ok[None]:
+				result = await dispatch(index + 1)
+				# If dispatch returns Deny, the middleware should have short-circuited
+				# This should only be called when continuing the chain
+				if isinstance(result, Deny):
+					# This shouldn't happen, but handle it gracefully
+					return Ok(None)
+				return result
+
+			return await mw.channel(
+				channel_id=channel_id,
+				event=event,
+				payload=payload,
+				request_id=request_id,
+				session=session,
+				next=_next,
+			)
+
+		return await dispatch(0)
+
+
+def stack(*middlewares: PulseMiddleware) -> PulseMiddleware:
+	"""Compose multiple middlewares into a single middleware stack.
+
+	Args:
+		*middlewares: Middleware instances to compose.
+
+	Returns:
+		``MiddlewareStack`` instance.
+
+	Example:
+
+	```python
+	import pulse as ps
+
+	app = ps.App(
+	    middleware=ps.stack(
+	        AuthMiddleware(),
+	        LoggingMiddleware(),
+	    )
+	)
+	```
+	"""
+	return MiddlewareStack(list(middlewares))
+
+
+class LatencyMiddleware(PulseMiddleware):
+	"""Middleware that adds artificial latency to simulate network conditions.
+
+	Useful for testing and development to simulate real-world network delays.
+	Defaults are realistic for typical web applications.
+
+	Example:
+	    ```python
+	    app = ps.App(
+	        middleware=ps.LatencyMiddleware(
+	            prerender_ms=100,
+	            connect_ms=50,
+	        )
+	    )
+	    ```
+	"""
+
+	prerender_ms: float
+	connect_ms: float
+	message_ms: float
+	channel_ms: float
+
+	def __init__(
+		self,
+		*,
+		prerender_ms: float = 80.0,
+		connect_ms: float = 40.0,
+		message_ms: float = 25.0,
+		channel_ms: float = 20.0,
+	) -> None:
+		"""Initialize latency middleware.
+
+		Args:
+			prerender_ms: Latency for batch prerender requests (HTTP). Default: 80ms
+			connect_ms: Latency for WebSocket connections. Default: 40ms
+			message_ms: Latency for WebSocket messages (including API calls). Default: 25ms
+			channel_ms: Latency for channel messages. Default: 20ms
+		"""
+		super().__init__(dev=True)
+		self.prerender_ms = prerender_ms
+		self.connect_ms = connect_ms
+		self.message_ms = message_ms
+		self.channel_ms = channel_ms
+
+	@override
+	async def prerender(
+		self,
+		*,
+		payload: "PrerenderPayload",
+		request: PulseRequest,
+		session: dict[str, Any],
+		next: Callable[[], Awaitable[PrerenderResponse]],
+	) -> PrerenderResponse:
+		if self.prerender_ms > 0:
+			await asyncio.sleep(self.prerender_ms / 1000.0)
+		return await next()
+
+	@override
+	async def connect(
+		self,
+		*,
+		request: PulseRequest,
+		session: dict[str, Any],
+		next: Callable[[], Awaitable[ConnectResponse]],
+	) -> ConnectResponse:
+		if self.connect_ms > 0:
+			await asyncio.sleep(self.connect_ms / 1000.0)
+		return await next()
+
+	@override
+	async def message(
+		self,
+		*,
+		data: ClientMessage,
+		session: dict[str, Any],
+		next: Callable[[], Awaitable[Ok[None]]],
+	) -> Ok[None] | Deny:
+		if self.message_ms > 0:
+			await asyncio.sleep(self.message_ms / 1000.0)
+		return await next()
+
+	@override
+	async def channel(
+		self,
+		*,
+		channel_id: str,
+		event: str,
+		payload: Any,
+		request_id: str | None,
+		session: dict[str, Any],
+		next: Callable[[], Awaitable[Ok[None]]],
+	) -> Ok[None] | Deny:
+		if self.channel_ms > 0:
+			await asyncio.sleep(self.channel_ms / 1000.0)
+		return await next()

pulse/plugin.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pulse.middleware import PulseMiddleware
+from pulse.routing import Layout, Route
+
+if TYPE_CHECKING:
+	from pulse.app import App
+
+
+class Plugin:
+	"""Base class for application plugins.
+
+	Plugins extend application functionality by contributing routes,
+	middleware, and lifecycle hooks. Create a subclass and override
+	the methods you need.
+
+	Attributes:
+		priority: Plugin execution order. Higher values run first.
+			Defaults to 0. Use positive values for plugins that should
+			initialize early (e.g., auth), negative for late initialization.
+
+	Example:
+		```python
+		class AuthPlugin(ps.Plugin):
+		    priority = 10  # Higher priority runs first
+
+		    def routes(self):
+		        return [ps.Route("/login", render=login_page)]
+
+		    def middleware(self):
+		        return [AuthMiddleware()]
+
+		    def on_startup(self, app):
+		        print("Auth plugin started")
+		```
+	"""
+
+	priority: int = 0
+
+	def routes(self) -> list[Route | Layout]:
+		"""Return routes to add to the application.
+
+		Override to contribute routes from this plugin. Routes are added
+		after user-defined routes in the App constructor.
+
+		Returns:
+			List of Route or Layout objects to register.
+		"""
+		return []
+
+	def middleware(self) -> list[PulseMiddleware]:
+		"""Return middleware to add to the application.
+
+		Override to contribute middleware from this plugin. Middleware
+		is added after user-defined middleware.
+
+		Returns:
+			List of PulseMiddleware instances to register.
+		"""
+		return []
+
+	def on_setup(self, app: App) -> None:
+		"""Called after FastAPI routes are configured.
+
+		Override to perform setup that requires FastAPI routes to exist,
+		such as adding custom endpoints or middleware.
+
+		Args:
+			app: The Pulse application instance.
+		"""
+		...
+
+	def on_startup(self, app: App) -> None:
+		"""Called when the application starts.
+
+		Override to perform initialization when the server begins
+		accepting connections, such as connecting to databases or
+		initializing caches.
+
+		Args:
+			app: The Pulse application instance.
+		"""
+		...
+
+	def on_shutdown(self, app: App) -> None:
+		"""Called when the application shuts down.
+
+		Override to perform cleanup when the server is stopping,
+		such as closing database connections or flushing caches.
+
+		Args:
+			app: The Pulse application instance.
+		"""
+		...