pulse-framework 0.1.64__py3-none-any.whl → 0.1.66a1__py3-none-any.whl

pulse/__init__.py

@@ -1134,16 +1134,16 @@ from pulse.env import env as env
 from pulse.env import mode as mode
 
 # Forms
-from pulse.form import (
+from pulse.forms import (
 	Form as Form,
 )
-from pulse.form import (
+from pulse.forms import (
 	FormData as FormData,
 )
-from pulse.form import (
+from pulse.forms import (
 	FormValue as FormValue,
 )
-from pulse.form import (
+from pulse.forms import (
 	ManualForm as ManualForm,
 )
 
@@ -1151,12 +1151,6 @@ from pulse.form import (
 from pulse.helpers import (
 	CSSProperties as CSSProperties,
 )
-from pulse.helpers import (
-	later as later,
-)
-from pulse.helpers import (
-	repeat as repeat,
-)
 
 # Hooks - Core
 from pulse.hooks.core import (
@@ -1414,6 +1408,18 @@ from pulse.requirements import require as require
 from pulse.routing import Layout as Layout
 from pulse.routing import Route as Route
 from pulse.routing import RouteInfo as RouteInfo
+from pulse.scheduling import (
+	TaskRegistry as TaskRegistry,
+)
+from pulse.scheduling import (
+	TimerRegistry as TimerRegistry,
+)
+from pulse.scheduling import (
+	later as later,
+)
+from pulse.scheduling import (
+	repeat as repeat,
+)
 from pulse.serializer import deserialize as deserialize
 
 # Serializer

pulse/app.py

@@ -5,7 +5,6 @@ This module provides the main App class that users instantiate in their main.py
 to define routes and configure their Pulse application.
 """
 
-import asyncio
 import logging
 import os
 from collections import defaultdict
@@ -40,11 +39,9 @@ from pulse.env import (
 )
 from pulse.env import env as envvars
 from pulse.helpers import (
-	create_task,
 	find_available_port,
 	get_client_address,
 	get_client_address_socketio,
-	later,
 )
 from pulse.hooks.core import hooks
 from pulse.messages import (
@@ -74,6 +71,7 @@ from pulse.proxy import ReactProxy
 from pulse.render_session import RenderSession
 from pulse.request import PulseRequest
 from pulse.routing import Layout, Route, RouteTree, ensure_absolute_path
+from pulse.scheduling import TaskRegistry, TimerHandleLike, TimerRegistry
 from pulse.serializer import Serialized, deserialize, serialize
 from pulse.user_session import (
 	CookieSessionStore,
@@ -109,8 +107,8 @@ PulseMode = Literal["subdomains", "single-server"]
 """Deployment mode for the application.
 
 Values:
-    "single-server": Python and React served from the same origin (default).
-    "subdomains": Python API on a subdomain (e.g., api.example.com).
+		"single-server": Python and React served from the same origin (default).
+		"subdomains": Python API on a subdomain (e.g., api.example.com).
 """
 
 
@@ -120,12 +118,12 @@ 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: 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
@@ -173,15 +171,15 @@ class App:
 		import pulse as ps
 
 		app = ps.App(
-		    routes=[
-		        ps.Route("/", render=home),
-		        ps.Route("/users/:id", render=user_detail),
-		    ],
-		    session_timeout=120.0,
+				routes=[
+						ps.Route("/", render=home),
+						ps.Route("/users/:id", render=user_detail),
+				],
+				session_timeout=120.0,
 		)
 
 		if __name__ == "__main__":
-		    app.run(port=8000)
+				app.run(port=8000)
 		```
 	"""
 
@@ -209,7 +207,10 @@ class App:
 	_render_to_user: dict[str, str]
 	_sessions_in_request: dict[str, int]
 	_socket_to_render: dict[str, str]
-	_render_cleanups: dict[str, asyncio.TimerHandle]
+	_render_cleanups: dict[str, TimerHandleLike]
+	_tasks: TaskRegistry
+	_timers: TimerRegistry
+	_proxy: ReactProxy | None
 	session_timeout: float
 	connection_status: ConnectionStatusConfig
 	render_loop_limit: int
@@ -283,6 +284,9 @@ class App:
 		self._socket_to_render = {}
 		# Map render_id -> cleanup timer handle for timeout-based expiry
 		self._render_cleanups = {}
+		self._tasks = TaskRegistry(name="app")
+		self._timers = TimerRegistry(tasks=self._tasks, name="app")
+		self._proxy = None
 		self.session_timeout = session_timeout
 		self.detach_queue_timeout = detach_queue_timeout
 		self.disconnect_queue_timeout = disconnect_queue_timeout
@@ -540,10 +544,21 @@ class App:
 			paths = [ensure_absolute_path(path) for path in paths]
 			payload["paths"] = paths
 			route_info = payload.get("routeInfo")
+			debug = os.environ.get("PULSE_DEBUG_RENDER")
+			if debug:
+				logger.info(
+					"[PulseDebug][prerender] session=%s header_render_id=%s payload_render_id=%s paths=%s route_info=%s",
+					session.sid,
+					request.headers.get("x-pulse-render-id"),
+					payload.get("renderId"),
+					paths,
+					route_info,
+				)
 
 			client_addr: str | None = get_client_address(request)
 			# Reuse render session from header (set by middleware) or create new one
 			render = PulseContext.get().render
+			reused = render is not None
 			if render is not None:
 				render_id = render.id
 			else:
@@ -552,9 +567,19 @@ class App:
 				render = self.create_render(
 					render_id, session, client_address=client_addr
 				)
+			if debug:
+				logger.info(
+					"[PulseDebug][prerender] session=%s render=%s reused=%s connected=%s",
+					session.sid,
+					render_id,
+					reused,
+					render.connected,
+				)
+			print(f"Prerendering for RenderSession {render_id}")
 
 			# Schedule cleanup timeout (will cancel/reschedule on activity)
-			self._schedule_render_cleanup(render_id)
+			if not render.connected:
+				self._schedule_render_cleanup(render_id)
 
 			def _normalize_prerender_result(
 				captured: ServerInitMessage | ServerNavigateToMessage,
@@ -659,10 +684,11 @@ class App:
 					+ "Use 'pulse run' CLI command or set the environment variable."
 				)
 
-			proxy_handler = ReactProxy(
+			self._proxy = ReactProxy(
 				react_server_address=react_server_address,
 				server_address=server_address,
 			)
+			proxy_handler = self._proxy
 
 			# In dev mode, proxy WebSocket connections to React Router (e.g. Vite HMR)
 			# Socket.IO handles /socket.io/ at ASGI level before reaching FastAPI
@@ -693,6 +719,13 @@ class App:
 			if cookie is None:
 				raise ConnectionRefusedError("Socket connect missing cookie")
 			session = await self.get_or_create_session(cookie)
+			debug = os.environ.get("PULSE_DEBUG_RENDER")
+			if debug:
+				logger.info(
+					"[PulseDebug][connect] session=%s render_id=%s",
+					session.sid,
+					rid,
+				)
 
 			if not rid:
 				# Still refuse connections without a renderId
@@ -703,6 +736,13 @@ class App:
 			# Allow reconnects where the provided renderId no longer exists by creating a new RenderSession
 			render = self.render_sessions.get(rid)
 			if render is None:
+				# The client will try to attach to a non-existing RouteMount, which will cause a reload down the line
+				if debug:
+					logger.info(
+						"[PulseDebug][connect] render_missing session=%s render_id=%s creating=true",
+						session.sid,
+						rid,
+					)
 				render = self.create_render(
 					rid, session, client_address=get_client_address_socketio(environ)
 				)
@@ -713,12 +753,21 @@ class App:
 						f"Socket connect session mismatch render={render.id} "
 						+ f"owner={owner} session={session.sid}"
 					)
+				if debug:
+					logger.info(
+						"[PulseDebug][connect] render_found session=%s render_id=%s owner=%s connected=%s",
+						session.sid,
+						render.id,
+						owner,
+						render.connected,
+					)
+			print(f"Connected to RenderSession {render.id}")
 
 			def on_message(message: ServerMessage):
 				payload = serialize(message)
 				# `serialize` returns a tuple, which socket.io will mistake for multiple arguments
 				payload = list(payload)
-				create_task(self.sio.emit("message", list(payload), to=sid))
+				self._tasks.create_task(self.sio.emit("message", list(payload), to=sid))
 
 			render.connect(on_message)
 			# Map socket sid to renderId for message routing
@@ -790,8 +839,10 @@ class App:
 	def _cancel_render_cleanup(self, rid: str):
 		"""Cancel any pending cleanup task for a render session."""
 		cleanup_handle = self._render_cleanups.pop(rid, None)
-		if cleanup_handle and not cleanup_handle.cancelled():
-			cleanup_handle.cancel()
+		if cleanup_handle:
+			if not cleanup_handle.cancelled():
+				cleanup_handle.cancel()
+			self._timers.discard(cleanup_handle)
 
 	def _schedule_render_cleanup(self, rid: str):
 		"""Schedule cleanup of a RenderSession after the configured timeout."""
@@ -817,12 +868,26 @@ class App:
 				)
 				self.close_render(rid)
 
-		handle = later(self.session_timeout, _cleanup)
+		handle = self._timers.later(self.session_timeout, _cleanup)
 		self._render_cleanups[rid] = handle
 
 	async def _handle_pulse_message(
 		self, render: RenderSession, session: UserSession, msg: ClientPulseMessage
 	) -> None:
+		if os.environ.get("PULSE_DEBUG_RENDER") and msg["type"] in (
+			"attach",
+			"update",
+			"detach",
+		):
+			logger.info(
+				"[PulseDebug][client-message] session=%s render=%s type=%s path=%s route_info=%s",
+				session.sid,
+				render.id,
+				msg["type"],
+				msg.get("path"),
+				msg.get("routeInfo"),
+			)
+
 		async def _next() -> Ok[None]:
 			if msg["type"] == "attach":
 				render.attach(msg["path"], msg["routeInfo"])
@@ -1023,7 +1088,7 @@ class App:
 		self._user_to_render[session.sid].remove(rid)
 
 		if len(self._user_to_render[session.sid]) == 0:
-			later(60, self.close_session_if_inactive, sid)
+			self._timers.later(60, self.close_session_if_inactive, sid)
 
 	def close_session(self, sid: str):
 		session = self.user_sessions.pop(sid, None)
@@ -1053,6 +1118,15 @@ class App:
 		for sid in list(self.user_sessions.keys()):
 			self.close_session(sid)
 
+		# Cancel any remaining app-level tasks/timers
+		self._tasks.cancel_all()
+		self._timers.cancel_all()
+		if self._proxy is not None:
+			try:
+				await self._proxy.close()
+			except Exception:
+				logger.exception("Error during ReactProxy.close()")
+
 		# Update status
 		self.status = AppStatus.stopped
 		# Call plugin on_shutdown hooks before closing
@@ -1082,5 +1156,8 @@ class App:
 			return  # no active render for this user session
 
 		# We don't want to wait for this to resolve
-		create_task(render.call_api(f"{self.api_prefix}/set-cookies", method="GET"))
+		render.create_task(
+			render.call_api(f"{self.api_prefix}/set-cookies", method="GET"),
+			name="cookies.refresh",
+		)
 		sess.scheduled_cookie_refresh = True

pulse/channel.py

@@ -7,7 +7,6 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, cast
 
 from pulse.context import PulseContext
-from pulse.helpers import create_future_on_loop
 from pulse.messages import (
 	ClientChannelRequestMessage,
 	ClientChannelResponseMessage,
@@ -15,6 +14,7 @@ from pulse.messages import (
 	ServerChannelRequestMessage,
 	ServerChannelResponseMessage,
 )
+from pulse.scheduling import create_future
 
 if TYPE_CHECKING:
 	from pulse.render_session import RenderSession
@@ -203,7 +203,7 @@ class ChannelsManager:
 					msg=msg,
 				)
 
-		asyncio.create_task(_invoke())
+		render.create_task(_invoke(), name=f"channel:{channel_id}:{event}")
 
 	# ------------------------------------------------------------------
 	def register_pending(
@@ -494,7 +494,7 @@ class Channel:
 
 		self._ensure_open()
 		request_id = uuid.uuid4().hex
-		fut = create_future_on_loop()
+		fut = create_future()
 		self._manager.register_pending(request_id, fut, self.id)
 		msg = ServerChannelRequestMessage(
 			type="channel_message",

pulse/codegen/templates/layout.py

@@ -53,15 +53,11 @@ export async function loader(args: LoaderFunctionArgs) {
   return data(prerenderData, { headers });
 }
 
-// Client loader: re-prerender on navigation while reusing renderId
+// Client loader: re-prerender on navigation while reusing directives
 export async function clientLoader(args: ClientLoaderFunctionArgs) {
   const url = new URL(args.request.url);
   const matches = matchRoutes(rrPulseRouteTree, url.pathname) ?? [];
   const paths = matches.map(m => m.route.uniquePath);
-  const renderId = 
-    typeof window !== "undefined" && typeof sessionStorage !== "undefined"
-      ? (sessionStorage.getItem("__PULSE_RENDER_ID") ?? undefined) 
-      : undefined;
   const directives = 
     typeof window !== "undefined" && typeof sessionStorage !== "undefined"
       ? (JSON.parse(sessionStorage.getItem("__PULSE_DIRECTIVES") ?? "{}"))
@@ -76,7 +72,7 @@ export async function clientLoader(args: ClientLoaderFunctionArgs) {
     method: "POST",
     headers,
     credentials: "include",
-    body: JSON.stringify({ paths, routeInfo: extractServerRouteInfo(args), renderId }),
+    body: JSON.stringify({ paths, routeInfo: extractServerRouteInfo(args) }),
   });
   if (!res.ok) throw new Error("Failed to prerender batch:" + res.status);
   const body = await res.json();
@@ -92,7 +88,6 @@ export async function clientLoader(args: ClientLoaderFunctionArgs) {
 export default function PulseLayout() {
   const data = useLoaderData<typeof loader>();
   if (typeof window !== "undefined" && typeof sessionStorage !== "undefined") {
-    sessionStorage.setItem("__PULSE_RENDER_ID", data.renderId);
     sessionStorage.setItem("__PULSE_DIRECTIVES", JSON.stringify(data.directives));
   }
   return (
@@ -101,6 +96,6 @@ export default function PulseLayout() {
     </PulseProvider>
   );
 }
-// Persist renderId and directives in sessionStorage for reuse in clientLoader is handled within the component
+// Persist directives in sessionStorage for reuse in clientLoader is handled within the component
 """
 )

pulse/{form.py → forms.py}

@@ -244,7 +244,7 @@ def Form(
 	key: str,
 	onSubmit: EventHandler1[FormData] | None = None,
 	**props: Unpack[PulseFormProps],  # pyright: ignore[reportGeneralTypeIssues]
-) -> Node:
+):
 	"""Server-registered HTML form component.
 
 	Automatically wires up form submission to a Python handler. Uses
@@ -435,7 +435,7 @@ class ManualForm(Disposable):
 		*children: Node,
 		key: str | None = None,
 		**props: Unpack[PulseFormProps],
-	) -> Node:
+	):
 		"""Render as a form element with children.
 
 		Args:

pulse/helpers.py

@@ -1,4 +1,3 @@
-import asyncio
 import inspect
 import linecache
 import os
@@ -17,7 +16,6 @@ from typing import (
 )
 from urllib.parse import urlsplit
 
-from anyio import from_thread
 from fastapi import Request
 
 from pulse.env import env
@@ -89,7 +87,15 @@ P = ParamSpec("P")
 CSSProperties = dict[str, Any]
 
 
-MISSING = object()
+class Missing:
+	__slots__: tuple[str, ...] = ()
+
+	@override
+	def __repr__(self) -> str:
+		return "MISSING"
+
+
+MISSING = Missing()
 
 
 class File(TypedDict):
@@ -130,7 +136,6 @@ def data(**attrs: Any):
 	return {f"data-{k}": v for k, v in attrs.items()}
 
 
-# --- Async scheduling helpers (work from loop or sync threads) ---
 class Disposable(ABC):
 	__disposed__: bool = False
 
@@ -158,214 +163,6 @@ class Disposable(ABC):
 			cls.dispose = wrapped_dispose
 
 
-def is_pytest() -> bool:
-	"""Detect if running inside pytest using environment variables."""
-	return bool(os.environ.get("PYTEST_CURRENT_TEST")) or (
-		"PYTEST_XDIST_TESTRUNUID" in os.environ
-	)
-
-
-def schedule_on_loop(callback: Callable[[], None]) -> None:
-	"""Schedule a callback to run ASAP on the main event loop from any thread."""
-	try:
-		loop = asyncio.get_running_loop()
-		loop.call_soon_threadsafe(callback)
-	except RuntimeError:
-
-		async def _runner():
-			loop = asyncio.get_running_loop()
-			loop.call_soon(callback)
-
-		try:
-			from_thread.run(_runner)
-		except RuntimeError:
-			if not is_pytest():
-				raise
-
-
-def create_task(
-	coroutine: Awaitable[T],
-	*,
-	name: str | None = None,
-	on_done: Callable[[asyncio.Task[T]], None] | None = None,
-) -> asyncio.Task[T]:
-	"""Create and schedule a coroutine task on the main loop from any thread.
-
-	- factory should create a fresh coroutine each call
-	- optional on_done is attached on the created task within the loop
-	"""
-
-	try:
-		asyncio.get_running_loop()
-		# ensure_future accepts Awaitable and returns a Task when given a coroutine
-		task = asyncio.ensure_future(coroutine)
-		if name is not None:
-			task.set_name(name)
-		if on_done:
-			task.add_done_callback(on_done)
-		return task
-	except RuntimeError:
-
-		async def _runner():
-			asyncio.get_running_loop()
-			# ensure_future accepts Awaitable and returns a Task when given a coroutine
-			task = asyncio.ensure_future(coroutine)
-			if name is not None:
-				task.set_name(name)
-			if on_done:
-				task.add_done_callback(on_done)
-			return task
-
-		try:
-			return from_thread.run(_runner)
-		except RuntimeError:
-			if is_pytest():
-				return None  # pyright: ignore[reportReturnType]
-			raise
-
-
-def create_future_on_loop() -> asyncio.Future[Any]:
-	"""Create an asyncio Future on the main event loop from any thread."""
-	try:
-		return asyncio.get_running_loop().create_future()
-	except RuntimeError:
-		from anyio import from_thread
-
-		async def _create():
-			loop = asyncio.get_running_loop()
-			return loop.create_future()
-
-		return from_thread.run(_create)
-
-
-def later(
-	delay: float, fn: Callable[P, Any], *args: P.args, **kwargs: P.kwargs
-) -> asyncio.TimerHandle:
-	"""
-	Schedule `fn(*args, **kwargs)` to run after `delay` seconds.
-	Works with sync or async functions. Returns a TimerHandle; call .cancel() to cancel.
-
-	The callback runs with no reactive scope to avoid accidentally capturing
-	reactive dependencies from the calling context. Other context vars (like
-	PulseContext) are preserved normally.
-	"""
-
-	from pulse.reactive import Untrack
-
-	try:
-		loop = asyncio.get_running_loop()
-	except RuntimeError:
-		try:
-			loop = asyncio.get_event_loop()
-		except RuntimeError as exc:
-			raise RuntimeError("later() requires an event loop") from exc
-
-	def _run():
-		try:
-			with Untrack():
-				res = fn(*args, **kwargs)
-				if asyncio.iscoroutine(res):
-					task = loop.create_task(res)
-
-					def _log_task_exception(t: asyncio.Task[Any]):
-						try:
-							t.result()
-						except asyncio.CancelledError:
-							# Normal cancellation path
-							pass
-						except Exception as exc:
-							loop.call_exception_handler(
-								{
-									"message": "Unhandled exception in later() task",
-									"exception": exc,
-									"context": {"callback": fn},
-								}
-							)
-
-					task.add_done_callback(_log_task_exception)
-		except Exception as exc:
-			# Surface exceptions via the loop's exception handler and continue
-			loop.call_exception_handler(
-				{
-					"message": "Unhandled exception in later() callback",
-					"exception": exc,
-					"context": {"callback": fn},
-				}
-			)
-
-	return loop.call_later(delay, _run)
-
-
-class RepeatHandle:
-	task: asyncio.Task[None] | None
-	cancelled: bool
-
-	def __init__(self) -> None:
-		self.task = None
-		self.cancelled = False
-
-	def cancel(self):
-		if self.cancelled:
-			return
-		self.cancelled = True
-		if self.task is not None and not self.task.done():
-			self.task.cancel()
-
-
-def repeat(interval: float, fn: Callable[P, Any], *args: P.args, **kwargs: P.kwargs):
-	"""
-	Repeatedly run `fn(*args, **kwargs)` every `interval` seconds.
-	Works with sync or async functions.
-	For async functions, waits for completion before starting the next delay.
-	Returns a handle with .cancel() to stop future runs.
-
-	The callback runs with no reactive scope to avoid accidentally capturing
-	reactive dependencies from the calling context. Other context vars (like
-	PulseContext) are preserved normally.
-
-	Optional kwargs:
-	- immediate: bool = False  # run once immediately before the first interval
-	"""
-
-	from pulse.reactive import Untrack
-
-	loop = asyncio.get_running_loop()
-	handle = RepeatHandle()
-
-	async def _runner():
-		nonlocal handle
-		try:
-			while not handle.cancelled:
-				# Start counting the next interval AFTER the previous execution completes
-				await asyncio.sleep(interval)
-				if handle.cancelled:
-					break
-				try:
-					with Untrack():
-						result = fn(*args, **kwargs)
-						if asyncio.iscoroutine(result):
-							await result
-				except asyncio.CancelledError:
-					# Propagate to outer handler to finish cleanly
-					raise
-				except Exception as exc:
-					# Surface exceptions via the loop's exception handler and continue
-					loop.call_exception_handler(
-						{
-							"message": "Unhandled exception in repeat() callback",
-							"exception": exc,
-							"context": {"callback": fn},
-						}
-					)
-		except asyncio.CancelledError:
-			# Swallow task cancellation to avoid noisy "exception was never retrieved"
-			pass
-
-	handle.task = loop.create_task(_runner())
-
-	return handle
-
-
 def get_client_address(request: Request) -> str | None:
 	"""Best-effort client origin/address from an HTTP request.
 

pulse/proxy.py

@@ -9,7 +9,6 @@ from typing import cast
 import httpx
 import websockets
 from fastapi.responses import StreamingResponse
-from starlette.background import BackgroundTask
 from starlette.requests import Request
 from starlette.responses import PlainTextResponse, Response
 from starlette.websockets import WebSocket, WebSocketDisconnect
@@ -223,9 +222,17 @@ class ReactProxy:
 					v = self.rewrite_url(v)
 				response_headers[k] = v
 
+			async def _iter():
+				try:
+					async for chunk in r.aiter_raw():
+						if await request.is_disconnected():
+							break
+						yield chunk
+				finally:
+					await r.aclose()
+
 			return StreamingResponse(
-				r.aiter_raw(),
-				background=BackgroundTask(r.aclose),
+				_iter(),
 				status_code=r.status_code,
 				headers=response_headers,
 			)