pulse-framework 0.1.40__tar.gz → 0.1.42__tar.gz

{pulse_framework-0.1.40 → pulse_framework-0.1.42}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pulse-framework
-Version: 0.1.40
+Version: 0.1.42
 Summary: Pulse - Full-stack framework for building real-time React applications in Python
 Requires-Dist: websockets>=12.0
 Requires-Dist: fastapi>=0.104.0

{pulse_framework-0.1.40 → pulse_framework-0.1.42}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pulse-framework"
-version = "0.1.40"
+version = "0.1.42"
 description = "Pulse - Full-stack framework for building real-time React applications in Python"
 readme = "README.md"
 requires-python = ">=3.11"

{pulse_framework-0.1.40 → pulse_framework-0.1.42}/src/pulse/__init__.py

@@ -15,6 +15,9 @@
 # (2) All imports should target the module in which a symbol is actually defined, rather than a
 # container module where it is imported.
 
+# External re-exports
+from starlette.datastructures import UploadFile as UploadFile
+
 # Core app/session
 from pulse.app import App as App
 from pulse.app import PulseMode as PulseMode
@@ -69,6 +72,7 @@ from pulse.css import (
 # Decorators
 from pulse.decorators import computed as computed
 from pulse.decorators import effect as effect
+from pulse.decorators import mutation as mutation
 from pulse.decorators import query as query
 
 # Environment
@@ -89,9 +93,6 @@ from pulse.form import (
 from pulse.form import (
 	ManualForm as ManualForm,
 )
-from pulse.form import (
-	UploadFile as UploadFile,
-)
 
 # Helpers
 from pulse.helpers import (
@@ -160,6 +161,11 @@ from pulse.hooks.core import (
 # Hooks - Effects
 from pulse.hooks.effects import EffectsHookState as EffectsHookState
 from pulse.hooks.effects import effects as effects
+
+# Hooks - Init
+from pulse.hooks.init import (
+	init as init,
+)
 from pulse.hooks.runtime import (
 	GLOBAL_STATES as GLOBAL_STATES,
 )
@@ -1300,9 +1306,10 @@ from pulse.html.tags import (
 from pulse.html.tags import (
 	wbr as wbr,
 )
+from pulse.messages import ClientMessage as ClientMessage
 from pulse.messages import Directives as Directives
+from pulse.messages import Prerender as Prerender
 from pulse.messages import PrerenderPayload as PrerenderPayload
-from pulse.messages import PrerenderResult as PrerenderResult
 from pulse.messages import SocketIODirectives as SocketIODirectives
 
 # Middleware
@@ -1312,6 +1319,9 @@ from pulse.middleware import (
 from pulse.middleware import (
 	Deny as Deny,
 )
+from pulse.middleware import (
+	LatencyMiddleware as LatencyMiddleware,
+)
 from pulse.middleware import (
 	MiddlewareStack as MiddlewareStack,
 )
@@ -1330,12 +1340,16 @@ from pulse.middleware import (
 from pulse.middleware import (
 	Redirect as Redirect,
 )
+from pulse.middleware import (
+	RoutePrerenderResponse as RoutePrerenderResponse,
+)
 from pulse.middleware import (
 	stack as stack,
 )
 
 # Plugin
 from pulse.plugin import Plugin as Plugin
+from pulse.queries.query import QueryStatus as QueryStatus
 
 # React component registry
 from pulse.react_component import (
@@ -1419,6 +1433,7 @@ from pulse.render_session import (
 from pulse.request import PulseRequest as PulseRequest
 from pulse.routing import Layout as Layout
 from pulse.routing import Route as Route
+from pulse.routing import RouteInfo as RouteInfo
 from pulse.serializer import deserialize as deserialize
 
 # Serializer

{pulse_framework-0.1.40 → pulse_framework-0.1.42}/src/pulse/app.py

@@ -11,6 +11,7 @@ import os
 from collections import defaultdict
 from collections.abc import Awaitable, Sequence
 from contextlib import asynccontextmanager
+from dataclasses import dataclass
 from enum import IntEnum
 from typing import Any, Callable, Literal, TypeVar, cast
 
@@ -57,21 +58,23 @@ from pulse.messages import (
 	ClientChannelResponseMessage,
 	ClientMessage,
 	ClientPulseMessage,
+	Prerender,
 	PrerenderPayload,
-	PrerenderResult,
 	ServerMessage,
 )
 from pulse.middleware import (
+	ConnectResponse,
 	Deny,
 	MiddlewareStack,
 	NotFound,
 	Ok,
-	PulseCoreMiddleware,
+	PrerenderResponse,
 	PulseMiddleware,
 	Redirect,
+	RoutePrerenderResponse,
 )
 from pulse.plugin import Plugin
-from pulse.proxy import ReactProxyHandler
+from pulse.proxy import ReactProxy
 from pulse.react_component import ReactComponent, registered_react_components
 from pulse.render_session import RenderSession
 from pulse.request import PulseRequest
@@ -100,6 +103,25 @@ class AppStatus(IntEnum):
 PulseMode = Literal["subdomains", "single-server"]
 
 
+@dataclass
+class ConnectionStatusConfig:
+	"""
+	Configuration for connection status message delays.
+
+	Attributes:
+	    initial_connecting_delay: Delay in seconds before showing "Connecting..." message
+	        on initial connection attempt. Default: 2.0
+	    initial_error_delay: Additional delay in seconds before showing error message
+	        on initial connection attempt (after connecting message). Default: 8.0
+	    reconnect_error_delay: Delay in seconds before showing error message when
+	        reconnecting after losing connection. Default: 8.0
+	"""
+
+	initial_connecting_delay: float = 2.0
+	initial_error_delay: float = 8.0
+	reconnect_error_delay: float = 8.0
+
+
 class App:
 	"""
 	Pulse UI Application - the main entry point for defining your app.
@@ -144,11 +166,11 @@ class App:
 	_socket_to_render: dict[str, str]
 	_render_cleanups: dict[str, asyncio.TimerHandle]
 	session_timeout: float
+	connection_status: ConnectionStatusConfig
 
 	def __init__(
 		self,
 		routes: Sequence[Route | Layout] | None = None,
-		dev_routes: Sequence[Route | Layout] | None = None,
 		codegen: CodegenConfig | None = None,
 		middleware: PulseMiddleware | Sequence[PulseMiddleware] | None = None,
 		plugins: Sequence[Plugin] | None = None,
@@ -164,14 +186,8 @@ class App:
 		cors: CORSOptions | None = None,
 		fastapi: dict[str, Any] | None = None,
 		session_timeout: float = 60.0,
+		connection_status: ConnectionStatusConfig | None = None,
 	):
-		"""
-		Initialize a new Pulse App.
-
-		Args:
-		    routes: Optional list of Route objects to register.
-		    codegen: Optional codegen configuration.
-		"""
 		# Resolve mode from environment and expose on the app instance
 		self.env = envvars.pulse_env
 		self.mode = mode
@@ -197,13 +213,12 @@ class App:
 		# Add plugin routes after user-defined routes
 		for plugin in self.plugins:
 			all_routes.extend(plugin.routes())
-			if self.env == "dev":
-				all_routes.extend(plugin.dev_routes())
 
 		# Auto-add React components to all routes
 		add_react_components(all_routes, registered_react_components())
 		add_css_modules(all_routes, registered_css_modules())
 		add_css_imports(all_routes, registered_css_imports())
+		# RouteTree filters routes based on dev flag and environment during construction
 		self.routes = RouteTree(all_routes)
 		self.not_found = not_found
 		# Default not-found path for client-side navigation on not_found()
@@ -222,6 +237,7 @@ class App:
 		# Map render_id -> cleanup timer handle for timeout-based expiry
 		self._render_cleanups = {}
 		self.session_timeout = session_timeout
+		self.connection_status = connection_status or ConnectionStatusConfig()
 
 		self.codegen = Codegen(
 			self.routes,
@@ -236,11 +252,11 @@ class App:
 		self.asgi = socketio.ASGIApp(self.sio, self.fastapi)
 
 		if middleware is None:
-			mw_stack: list[PulseMiddleware] = [PulseCoreMiddleware()]
+			mw_stack: list[PulseMiddleware] = []
 		elif isinstance(middleware, PulseMiddleware):
-			mw_stack = [PulseCoreMiddleware(), middleware]
+			mw_stack = [middleware]
 		else:
-			mw_stack = [PulseCoreMiddleware(), *middleware]
+			mw_stack = list(middleware)
 
 		# Let plugins contribute middleware (in plugin priority order)
 		for plugin in self.plugins:
@@ -266,10 +282,6 @@ class App:
 				logger.info(
 					f"Single-server mode: React Router running at {react_server_address}"
 				)
-			else:
-				logger.warning(
-					"Single-server mode: PULSE_REACT_SERVER_ADDRESS not set."
-				)
 
 		try:
 			yield
@@ -303,6 +315,7 @@ class App:
 			self.server_address,
 			self.internal_server_address or self.server_address,
 			self.api_prefix,
+			connection_status=self.connection_status,
 		)
 
 	def asgi_factory(self):
@@ -447,15 +460,7 @@ class App:
 			# Schedule cleanup timeout (will cancel/reschedule on activity)
 			self._schedule_render_cleanup(render_id)
 
-			initial_result: PrerenderResult = {
-				"views": {},
-				"directives": {
-					"headers": {"X-Pulse-Render-Id": render_id},
-					"socketio": {"auth": {"render_id": render_id}, "headers": {}},
-				},
-			}
-
-			def _prerender_one(path: str):
+			async def _prerender_one(path: str):
 				captured = render.prerender_mount_capture(path, route_info)
 				if captured["type"] == "vdom_init":
 					return Ok(captured)
@@ -469,57 +474,85 @@ class App:
 				# Fallback: shouldn't happen, return not found to be safe
 				return NotFound()
 
-			result = initial_result.copy()
+			def _normalize_prerender_response(res: Any) -> RoutePrerenderResponse:
+				if isinstance(res, (Ok, Redirect, NotFound)):
+					return res
+				# Treat any other value as a VDOM payload
+				return Ok(res)
 
 			with PulseContext.update(render=render):
-				for p in paths:
-					try:
-						res = self.middleware.prerender_route(
-							path=p,
-							route_info=route_info,
-							request=PulseRequest.from_fastapi(request),
-							session=session.data,
-							next=lambda p=p: _prerender_one(p),
-						)
-						if isinstance(res, Ok):
-							result["views"][p] = res.payload
-						elif isinstance(res, Redirect):
-							# Abort immediately with JSON redirect signal
-							location = res.path or "/"
-							resp = JSONResponse({"redirect": location})
-							session.handle_response(resp)
-							return resp
-						elif isinstance(res, NotFound):
-							# Abort immediately with JSON notFound signal
-							resp = JSONResponse({"notFound": True})
-							session.handle_response(resp)
-							return resp
-						else:
-							raise ValueError("Unexpected prerender response:", res)
-					except RedirectInterrupt as r:
-						resp = JSONResponse({"redirect": r.path})
-						session.handle_response(resp)
-						return resp
-					except NotFoundInterrupt:
-						resp = JSONResponse({"notFound": True})
-						session.handle_response(resp)
-						return resp
-
-			# Call top-level batch prerender middleware to modify final result
-			def _return_result() -> PrerenderResult:
-				return result
-
-			final_result = self.middleware.prerender(
-				payload=payload,
-				result=result,
-				request=PulseRequest.from_fastapi(request),
-				session=session.data,
-				next=_return_result,
-			)
+				# Call top-level prerender middleware, which wraps the route processing
+				async def _process_routes() -> PrerenderResponse:
+					result_data: Prerender = {
+						"views": {},
+						"directives": {
+							"headers": {"X-Pulse-Render-Id": render_id},
+							"socketio": {
+								"auth": {"render_id": render_id},
+								"headers": {},
+							},
+						},
+					}
+
+					# Fan out on routes
+					for p in paths:
+						try:
+							# Capture p in closure to avoid loop variable binding issue
+							async def _next(path: str = p) -> RoutePrerenderResponse:
+								return await _prerender_one(path)
+
+							# Call prerender_route middleware (in) -> prerender route -> (out)
+							res = await self.middleware.prerender_route(
+								path=p,
+								route_info=route_info,
+								request=PulseRequest.from_fastapi(request),
+								session=session.data,
+								next=_next,
+							)
+							res = _normalize_prerender_response(res)
+							if isinstance(res, Ok):
+								# Aggregate results
+								result_data["views"][p] = res.payload
+							elif isinstance(res, Redirect):
+								# Return redirect immediately
+								return Redirect(path=res.path or "/")
+							elif isinstance(res, NotFound):
+								# Return not found immediately
+								return NotFound()
+							else:
+								raise ValueError("Unexpected prerender response:", res)
+						except RedirectInterrupt as r:
+							return Redirect(path=r.path)
+						except NotFoundInterrupt:
+							return NotFound()
+
+					return Ok(result_data)
+
+				result = await self.middleware.prerender(
+					payload=payload,
+					request=PulseRequest.from_fastapi(request),
+					session=session.data,
+					next=_process_routes,
+				)
 
-			resp = JSONResponse(serialize(final_result))
-			session.handle_response(resp)
-			return resp
+			# Handle redirect/notFound responses
+			if isinstance(result, Redirect):
+				resp = JSONResponse({"redirect": result.path})
+				session.handle_response(resp)
+				return resp
+			if isinstance(result, NotFound):
+				resp = JSONResponse({"notFound": True})
+				session.handle_response(resp)
+				return resp
+
+			# Handle Ok result - serialize the payload (PrerenderResultData)
+			if isinstance(result, Ok):
+				resp = JSONResponse(serialize(result.payload))
+				session.handle_response(resp)
+				return resp
+
+			# Fallback (shouldn't happen)
+			raise ValueError("Unexpected prerender result type")
 
 		@self.fastapi.post(f"{prefix}/forms/{{render_id}}/{{form_id}}")
 		async def handle_form_submit(  # pyright: ignore[reportUnusedFunction]
@@ -544,7 +577,14 @@ class App:
 		# FastAPI will match specific routes before this catch-all, but we add an explicit check
 		# as a safety measure to ensure API routes are never proxied
 		if self.mode == "single-server":
-			proxy_handler = ReactProxyHandler(lambda: envvars.react_server_address)
+			react_server_address = envvars.react_server_address
+			if not react_server_address:
+				raise RuntimeError(
+					"PULSE_REACT_SERVER_ADDRESS must be set in single-server mode. "
+					+ "Use 'pulse run' CLI command or set the environment variable."
+				)
+
+			proxy_handler = ReactProxy(react_server_address)
 
 			@self.fastapi.api_route(
 				"/{path:path}",
@@ -552,8 +592,12 @@ class App:
 				include_in_schema=False,
 			)
 			async def proxy_catch_all(request: Request, path: str):  # pyright: ignore[reportUnusedFunction]
-				# Skip WebSocket upgrades (handled by Socket.IO)
-				if request.headers.get("upgrade", "").lower() == "websocket":
+				# Skip WebSocket upgrades outside the Vite dev server (handled by Socket.IO)
+				is_websocket_upgrade = (
+					request.headers.get("upgrade", "").lower() == "websocket"
+				)
+				is_vite_dev_server = self.env == "dev" and request.url.path == "/"
+				if is_websocket_upgrade and not is_vite_dev_server:
 					raise HTTPException(status_code=404, detail="Not found")
 
 				# Proxy all unmatched HTTP requests to React Router
@@ -602,20 +646,26 @@ class App:
 
 			with PulseContext.update(session=session, render=render):
 
-				def _next():
+				async def _next():
+					return Ok(None)
+
+				def _normalize_connect_response(res: Any) -> ConnectResponse:
+					if isinstance(res, (Ok, Deny)):
+						return res  # type: ignore[return-value]
+					# Treat any other value as allow
 					return Ok(None)
 
 				try:
-					res = self.middleware.connect(
+					res = await self.middleware.connect(
 						request=PulseRequest.from_socketio_environ(environ, auth),
 						session=session.data,
 						next=_next,
 					)
+					res = _normalize_connect_response(res)
 				except Exception as exc:
 					render.report_error("/", "connect", exc)
 					res = Ok(None)
 				if isinstance(res, Deny):
-					print(f"Denying connection, closing RenderSession {rid}")
 					# Tear down the created session if denied
 					self.close_render(rid)
 
@@ -623,7 +673,6 @@ class App:
 		def disconnect(sid: str):  # pyright: ignore[reportUnusedFunction]
 			rid = self._socket_to_render.pop(sid, None)
 			if rid is not None:
-				print(f"Disconnecting WebSocket for RenderSession {rid}")
 				render = self.render_sessions.get(rid)
 				if render:
 					render.connected = False
@@ -631,7 +680,7 @@ class App:
 					self._schedule_render_cleanup(rid)
 
 		@self.sio.event
-		def message(sid: str, data: Serialized):  # pyright: ignore[reportUnusedFunction]
+		async def message(sid: str, data: Serialized):  # pyright: ignore[reportUnusedFunction]
 			rid = self._socket_to_render.get(sid)
 			if not rid:
 				return
@@ -646,9 +695,9 @@ class App:
 			msg = cast(ClientMessage, deserialize(data))
 			try:
 				if msg["type"] == "channel_message":
-					self._handle_channel_message(render, session, msg)
+					await self._handle_channel_message(render, session, msg)
 				else:
-					self._handle_pulse_message(render, session, msg)
+					await self._handle_pulse_message(render, session, msg)
 			except Exception as e:
 				path = msg.get("path", "")
 				render.report_error(path, "server", e)
@@ -688,10 +737,10 @@ class App:
 		handle = later(self.session_timeout, _cleanup)
 		self._render_cleanups[rid] = handle
 
-	def _handle_pulse_message(
+	async def _handle_pulse_message(
 		self, render: RenderSession, session: UserSession, msg: ClientPulseMessage
 	) -> None:
-		def _next() -> Ok[None]:
+		async def _next() -> Ok[None]:
 			if msg["type"] == "mount":
 				render.mount(msg["path"], msg["routeInfo"])
 			elif msg["type"] == "navigate":
@@ -707,13 +756,20 @@ class App:
 				logger.warning("Unknown message type received: %s", msg)
 			return Ok()
 
+		def _normalize_message_response(res: Any) -> Ok[None] | Deny:
+			if isinstance(res, (Ok, Deny)):
+				return res  # type: ignore[return-value]
+			# Treat any other value as allow
+			return Ok(None)
+
 		with PulseContext.update(session=session, render=render):
 			try:
-				res = self.middleware.message(
+				res = await self.middleware.message(
 					data=msg,
 					session=session.data,
 					next=_next,
 				)
+				res = _normalize_message_response(res)
 			except Exception:
 				logger.exception("Error in message middleware")
 				return
@@ -727,7 +783,7 @@ class App:
 					{"kind": "deny"},
 				)
 
-	def _handle_channel_message(
+	async def _handle_channel_message(
 		self, render: RenderSession, session: UserSession, msg: ClientChannelMessage
 	) -> None:
 		if msg.get("responseTo"):
@@ -737,15 +793,20 @@ class App:
 			channel_id = str(msg.get("channel", ""))
 			msg = cast(ClientChannelRequestMessage, msg)
 
-			def _next() -> Ok[Any]:
-				return Ok(
-					render.channels.handle_client_event(
-						render=render, session=session, message=msg
-					)
+			async def _next() -> Ok[None]:
+				render.channels.handle_client_event(
+					render=render, session=session, message=msg
 				)
+				return Ok(None)
+
+			def _normalize_message_response(res: Any) -> Ok[None] | Deny:
+				if isinstance(res, (Ok, Deny)):
+					return res  # type: ignore[return-value]
+				# Treat any other value as allow
+				return Ok(None)
 
 			with PulseContext.update(session=session, render=render):
-				res = self.middleware.channel(
+				res = await self.middleware.channel(
 					channel_id=channel_id,
 					event=msg.get("event", ""),
 					payload=msg.get("payload"),
@@ -753,6 +814,7 @@ class App:
 					session=session.data,
 					next=_next,
 				)
+				res = _normalize_message_response(res)
 
 			if isinstance(res, Deny):
 				if req_id := msg.get("requestId"):
@@ -844,7 +906,6 @@ class App:
 	):
 		if rid in self.render_sessions:
 			raise ValueError(f"RenderSession {rid} already exists")
-		print(f"Creating RenderSession {rid}")
 		render = RenderSession(
 			rid,
 			self.routes,
@@ -863,7 +924,6 @@ class App:
 		render = self.render_sessions.pop(rid, None)
 		if not render:
 			return
-		print(f"Closing RenderSession {rid}")
 		sid = self._render_to_user.pop(rid)
 		session = self.user_sessions[sid]
 		render.close()

{pulse_framework-0.1.40 → pulse_framework-0.1.42}/src/pulse/channel.py

@@ -15,7 +15,6 @@ from pulse.messages import (
 	ServerChannelRequestMessage,
 	ServerChannelResponseMessage,
 )
-from pulse.routing import normalize_path
 
 if TYPE_CHECKING:
 	from pulse.render_session import RenderSession
@@ -69,7 +68,8 @@ class ChannelsManager:
 
 		route_path: str | None = None
 		if ctx.route is not None:
-			route_path = normalize_path(ctx.route.pulse_route.unique_path())
+			# unique_path() returns absolute path, use as-is for keys
+			route_path = ctx.route.pulse_route.unique_path()
 
 		channel = Channel(
 			self,
@@ -84,18 +84,18 @@ class ChannelsManager:
 		return channel
 
 	# ------------------------------------------------------------------
-	def remove_route(self, route_path: str) -> None:
-		key = normalize_path(route_path)
-		route_channels = list(self._channels_by_route.get(key, set()))
+	def remove_route(self, path: str) -> None:
+		# route_path is already an absolute path
+		route_channels = list(self._channels_by_route.get(path, set()))
 		# if route_channels:
-		# 	print(f"Disposing {len(route_channels)} channel(s) for route {key}")
+		# 	print(f"Disposing {len(route_channels)} channel(s) for route {route_path}")
 		for channel_id in route_channels:
 			channel = self._channels.get(channel_id)
 			if channel is None:
 				continue
 			channel.closed = True
 			self.dispose_channel(channel, reason="route.unmount")
-		self._channels_by_route.pop(key, None)
+		self._channels_by_route.pop(path, None)
 
 	# ------------------------------------------------------------------
 	def handle_client_response(self, message: ClientChannelResponseMessage) -> None: