pulse-framework 0.1.38a5__tar.gz → 0.1.38a7__tar.gz

{pulse_framework-0.1.38a5 → pulse_framework-0.1.38a7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pulse-framework
-Version: 0.1.38a5
+Version: 0.1.38a7
 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.38a5 → pulse_framework-0.1.38a7}/pyproject.toml

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

{pulse_framework-0.1.38a5 → pulse_framework-0.1.38a7}/src/pulse/__init__.py

@@ -1300,6 +1300,10 @@ from pulse.html.tags import (
 from pulse.html.tags import (
 	wbr as wbr,
 )
+from pulse.messages import Directives as Directives
+from pulse.messages import PrerenderPayload as PrerenderPayload
+from pulse.messages import PrerenderResult as PrerenderResult
+from pulse.messages import SocketIODirectives as SocketIODirectives
 
 # Middleware
 from pulse.middleware import (

{pulse_framework-0.1.38a5 → pulse_framework-0.1.38a7}/src/pulse/app.py

@@ -5,13 +5,14 @@ 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
 from collections.abc import Awaitable, Sequence
 from contextlib import asynccontextmanager
 from enum import IntEnum
-from typing import Any, Callable, Literal, NotRequired, TypedDict, TypeVar, cast
+from typing import Any, Callable, Literal, TypeVar, cast
 
 import socketio
 import uvicorn
@@ -56,7 +57,8 @@ from pulse.messages import (
 	ClientChannelResponseMessage,
 	ClientMessage,
 	ClientPulseMessage,
-	ServerInitMessage,
+	PrerenderPayload,
+	PrerenderResult,
 	ServerMessage,
 )
 from pulse.middleware import (
@@ -73,7 +75,7 @@ from pulse.proxy import PulseProxy
 from pulse.react_component import ReactComponent, registered_react_components
 from pulse.render_session import RenderSession
 from pulse.request import PulseRequest
-from pulse.routing import Layout, Route, RouteInfo, RouteTree
+from pulse.routing import Layout, Route, RouteTree
 from pulse.serializer import Serialized, deserialize, serialize
 from pulse.user_session import (
 	CookieSessionStore,
@@ -91,24 +93,13 @@ class AppStatus(IntEnum):
 	created = 0
 	initialized = 1
 	running = 2
-	stopped = 3
+	draining = 3
+	stopped = 4
 
 
 PulseMode = Literal["subdomains", "single-server"]
 
 
-class PrerenderPayload(TypedDict):
-	paths: list[str]
-	routeInfo: RouteInfo
-	ttlSeconds: NotRequired[float | int]
-	renderId: NotRequired[str]
-
-
-class PrerenderResult(TypedDict):
-	renderId: str
-	views: dict[str, ServerInitMessage | None]
-
-
 class App:
 	"""
 	Pulse UI Application - the main entry point for defining your app.
@@ -151,6 +142,8 @@ 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]
+	session_timeout: float
 
 	def __init__(
 		self,
@@ -170,6 +163,7 @@ class App:
 		api_prefix: str = "/_pulse",
 		cors: CORSOptions | None = None,
 		fastapi: dict[str, Any] | None = None,
+		session_timeout: float = 60.0,
 	):
 		"""
 		Initialize a new Pulse App.
@@ -225,6 +219,9 @@ class App:
 		self._sessions_in_request = {}
 		# Map websocket sid -> renderId for message routing
 		self._socket_to_render = {}
+		# Map render_id -> cleanup timer handle for timeout-based expiry
+		self._render_cleanups = {}
+		self.session_timeout = session_timeout
 
 		self.codegen = Codegen(
 			self.routes,
@@ -277,6 +274,11 @@ class App:
 		try:
 			yield
 		finally:
+			try:
+				await self.close()
+			except Exception:
+				logger.exception("Error during App.close()")
+
 			try:
 				if isinstance(self.session_store, SessionStore):
 					await self.session_store.close()
@@ -372,7 +374,6 @@ class App:
 		else:
 			# Use deployment-specific CORS settings
 			cors_config = cors_options(self.mode, self.server_address)
-			print(f"CORS config: {cors_config}")
 			self.fastapi.add_middleware(
 				CORSMiddleware,
 				**cors_config,
@@ -380,7 +381,7 @@ class App:
 
 		# Debug middleware to log CORS-related request details
 		# @self.fastapi.middleware("http")
-		# async def cors_debug_middleware(  # pyright: ignore[reportUnusedFunction]
+		# async def cors_debug_middleware(
 		# 	request: Request, call_next: Callable[[Request], Awaitable[Response]]
 		# ):
 		# 	origin = request.headers.get("origin")
@@ -417,10 +418,9 @@ class App:
 				self._sessions_in_request.get(session.sid, 0) + 1
 			)
 			render_id = request.headers.get("x-pulse-render-id")
-			if render_id:
-				render = self.render_sessions.get(render_id)
-			else:
-				render = None
+			render = self._get_render_for_session(render_id, session)
+			if render:
+				print(f"Reusing render session {render_id}")
 			with PulseContext.update(session=session, render=render):
 				res: Response = await call_next(request)
 			session.handle_response(res)
@@ -447,7 +447,8 @@ class App:
 		async def prerender(payload: PrerenderPayload, request: Request):  # pyright: ignore[reportUnusedFunction]
 			"""
 			POST /prerender
-			Body: { paths: string[], routeInfo: RouteInfo, ttlSeconds?: number, renderId?: string }
+			Body: { paths: string[], routeInfo: RouteInfo, ttlSeconds?: number }
+			Headers: X-Pulse-Render-Id (optional, for render session reuse)
 			Returns: { renderId: string, <path>: VDOM, ... }
 			"""
 			session = PulseContext.get().session
@@ -459,31 +460,29 @@ class App:
 					status_code=400, detail="'paths' must be a non-empty list"
 				)
 			route_info = payload.get("routeInfo")
-			ttl = payload.get("ttlSeconds")
-			if not isinstance(ttl, (int, float)):
-				ttl = 15
 
 			client_addr: str | None = get_client_address(request)
-			# Optional reuse of existing RenderSession
-			render_id = payload.get("renderId")
-			if isinstance(render_id, str):
-				# Validate render exists and belongs to this user session
-				existing = self.render_sessions.get(render_id)
-				if existing is None:
-					raise HTTPException(status_code=400, detail="Unknown renderId")
-				owner = self._render_to_user.get(render_id)
-				if owner != session.sid:
-					raise HTTPException(status_code=403, detail="Forbidden renderId")
-				render = existing
-				cleanup = False
+			# Reuse render session from header (set by middleware) or create new one
+			render = PulseContext.get().render
+			if render is not None:
+				render_id = render.id
 			else:
+				# Create new render session
 				render_id = new_sid()
 				render = self.create_render(
 					render_id, session, client_address=client_addr
 				)
-				cleanup = True
 
-			result: PrerenderResult = {"renderId": render_id, "views": {}}
+			# 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):
 				captured = render.prerender_mount_capture(path, route_info)
@@ -499,10 +498,12 @@ class App:
 				# Fallback: shouldn't happen, return not found to be safe
 				return NotFound()
 
+			result = initial_result.copy()
+
 			with PulseContext.update(render=render):
 				for p in paths:
 					try:
-						res = self.middleware.prerender(
+						res = self.middleware.prerender_route(
 							path=p,
 							route_info=route_info,
 							request=PulseRequest.from_fastapi(request),
@@ -533,19 +534,19 @@ class App:
 						session.handle_response(resp)
 						return resp
 
-				# schedule TTL cleanup if never connected
-				def _gc_if_unadopted(rid: str):
-					r = self.render_sessions.get(rid)
-					if r is None:
-						return
-					if r.connected:
-						return
-					self.close_render(rid)
+			# Call top-level batch prerender middleware to modify final result
+			def _return_result() -> PrerenderResult:
+				return result
 
-				if cleanup:
-					later(float(ttl), _gc_if_unadopted, render_id)
+			final_result = self.middleware.prerender(
+				payload=payload,
+				result=result,
+				request=PulseRequest.from_fastapi(request),
+				session=session.data,
+				next=_return_result,
+			)
 
-			resp = JSONResponse(serialize(result))
+			resp = JSONResponse(serialize(final_result))
 			session.handle_response(resp)
 			return resp
 
@@ -572,7 +573,7 @@ class App:
 			sid: str, environ: dict[str, Any], auth: dict[str, str] | None
 		):
 			# Expect renderId during websocket auth and require a valid user session
-			rid = auth.get("renderId") if auth else None
+			rid = auth.get("render_id") if auth else None
 
 			# Parse cookies from environ and ensure a session exists
 			cookie = self.cookie.get_from_socketio(environ)
@@ -605,6 +606,9 @@ class App:
 			# Map socket sid to renderId for message routing
 			self._socket_to_render[sid] = rid
 
+			# Cancel any pending cleanup since session is now connected
+			self._cancel_render_cleanup(rid)
+
 			with PulseContext.update(session=session, render=render):
 
 				def _next():
@@ -620,6 +624,7 @@ class App:
 					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)
 
@@ -627,8 +632,12 @@ class App:
 		def disconnect(sid: str):  # pyright: ignore[reportUnusedFunction]
 			rid = self._socket_to_render.pop(sid, None)
 			if rid is not None:
-				# Close the RenderSession entirely to avoid lingering effects/tasks
-				self.close_render(rid)
+				print(f"Disconnecting WebSocket for RenderSession {rid}")
+				render = self.render_sessions.get(rid)
+				if render:
+					render.connected = False
+					# Schedule cleanup after timeout (will keep session alive for reuse)
+					self._schedule_render_cleanup(rid)
 
 		@self.sio.event
 		def message(sid: str, data: Serialized):  # pyright: ignore[reportUnusedFunction]
@@ -638,6 +647,8 @@ class App:
 			render = self.render_sessions.get(rid)
 			if render is None:
 				return
+			# Cancel any pending cleanup for active sessions (connected sessions stay alive)
+			self._cancel_render_cleanup(rid)
 			# Use renderId mapping to user session
 			session = self.user_sessions[self._render_to_user[rid]]
 			# Make sure to properly deserialize the message contents
@@ -653,6 +664,39 @@ class App:
 
 		self.status = AppStatus.initialized
 
+	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()
+
+	def _schedule_render_cleanup(self, rid: str):
+		"""Schedule cleanup of a RenderSession after the configured timeout."""
+		render = self.render_sessions.get(rid)
+		if render is None:
+			return
+		# Don't schedule cleanup for connected sessions (they stay alive)
+		if render.connected:
+			return
+
+		# Cancel any existing cleanup task for this render session
+		self._cancel_render_cleanup(rid)
+
+		# Schedule new cleanup task
+		def _cleanup():
+			render = self.render_sessions.get(rid)
+			if render is None:
+				return
+			# Only cleanup if not connected (if connected, keep it alive)
+			if not render.connected:
+				logger.info(
+					f"RenderSession {rid} expired after {self.session_timeout}s timeout"
+				)
+				self.close_render(rid)
+
+		handle = later(self.session_timeout, _cleanup)
+		self._render_cleanups[rid] = handle
+
 	def _handle_pulse_message(
 		self, render: RenderSession, session: UserSession, msg: ClientPulseMessage
 	) -> None:
@@ -787,11 +831,29 @@ class App:
 		self.user_sessions[sid] = session
 		return session
 
+	def _get_render_for_session(
+		self, render_id: str | None, session: UserSession
+	) -> RenderSession | None:
+		"""
+		Get an existing render session for the given session, validating ownership.
+		Returns None if render_id is None, render doesn't exist, or doesn't belong to session.
+		"""
+		if not render_id:
+			return None
+		render = self.render_sessions.get(render_id)
+		if render is None:
+			return None
+		owner = self._render_to_user.get(render_id)
+		if owner != session.sid:
+			return None
+		return render
+
 	def create_render(
 		self, rid: str, session: UserSession, *, client_address: str | None = None
 	):
 		if rid in self.render_sessions:
 			raise ValueError(f"RenderSession {rid} already exists")
+		print(f"Creating RenderSession {rid}")
 		render = RenderSession(
 			rid,
 			self.routes,
@@ -804,9 +866,13 @@ class App:
 		return render
 
 	def close_render(self, rid: str):
+		# Cancel any pending cleanup task
+		self._cancel_render_cleanup(rid)
+
 		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()
@@ -825,6 +891,34 @@ class App:
 		if len(self._user_to_render[sid]) == 0:
 			self.close_session(sid)
 
+	async def close(self):
+		"""
+		Close the app and clean up all sessions.
+		This method is called automatically during shutdown.
+		"""
+
+		# Cancel all pending cleanup tasks
+		for rid in list(self._render_cleanups.keys()):
+			self._cancel_render_cleanup(rid)
+
+		# Close all render sessions
+		print("Closing app")
+		for rid in list(self.render_sessions.keys()):
+			self.close_render(rid)
+
+		# Close all user sessions
+		for sid in list(self.user_sessions.keys()):
+			self.close_session(sid)
+
+		# Update status
+		self.status = AppStatus.stopped
+		# Call plugin on_shutdown hooks before closing
+		for plugin in self.plugins:
+			try:
+				plugin.on_shutdown(self)
+			except Exception:
+				logger.exception("Error during plugin.on_shutdown()")
+
 	def refresh_cookies(self, sid: str):
 		# If the session is currently inside an HTTP request, we don't need to schedule
 		# set-cookies via WS; cookies will be attached on the HTTP response.
@@ -845,7 +939,7 @@ 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("/set-cookies", method="GET"))
+		create_task(render.call_api(f"/{self.api_prefix}/set-cookies", method="GET"))
 		sess.scheduled_cookie_refresh = True
 
 

{pulse_framework-0.1.38a5 → pulse_framework-0.1.38a7}/src/pulse/codegen/templates/layout.py

@@ -54,9 +54,19 @@ export async function clientLoader(args: ClientLoaderFunctionArgs) {
     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") ?? "{}"))
+      : {};
+  const headers: HeadersInit = { "content-type": "application/json" };
+  if (directives?.headers) {
+    for (const [key, value] of Object.entries(directives.headers)) {
+      headers[key] = value as string;
+    }
+  }
   const res = await fetch(`$${"{"}config.serverAddress}$${"{"}config.apiPrefix}/prerender`, {
     method: "POST",
-    headers: { "content-type": "application/json" },
+    headers,
     credentials: "include",
     body: JSON.stringify({ paths, routeInfo: extractServerRouteInfo(args), renderId }),
   });
@@ -64,13 +74,18 @@ export async function clientLoader(args: ClientLoaderFunctionArgs) {
   const body = await res.json();
   if (body.redirect) return new Response(null, { status: 302, headers: { Location: body.redirect } });
   if (body.notFound) return new Response(null, { status: 404 });
-  return deserialize(body) as PulsePrerender;
+  const prerenderData = deserialize(body) as PulsePrerender;
+  if (typeof window !== "undefined" && typeof sessionStorage !== "undefined" && prerenderData.directives) {
+    sessionStorage.setItem("__PULSE_DIRECTIVES", JSON.stringify(prerenderData.directives));
+  }
+  return prerenderData as PulsePrerender;
 }
 
 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 (
     <PulseProvider config={config} prerender={data}>
@@ -78,6 +93,6 @@ export default function PulseLayout() {
     </PulseProvider>
   );
 }
-// Persist renderId in sessionStorage for reuse in clientLoader is handled within the component
+// Persist renderId and directives in sessionStorage for reuse in clientLoader is handled within the component
 """
 )

{pulse_framework-0.1.38a5 → pulse_framework-0.1.38a7}/src/pulse/messages.py

@@ -156,3 +156,25 @@ ClientPulseMessage = (
 )
 ClientChannelMessage = ClientChannelRequestMessage | ClientChannelResponseMessage
 ClientMessage = ClientPulseMessage | ClientChannelMessage
+
+
+class PrerenderPayload(TypedDict):
+	paths: list[str]
+	routeInfo: RouteInfo
+	ttlSeconds: NotRequired[float | int]
+	renderId: NotRequired[str]
+
+
+class SocketIODirectives(TypedDict):
+	headers: dict[str, str]
+	auth: dict[str, str]
+
+
+class Directives(TypedDict):
+	headers: dict[str, str]
+	socketio: SocketIODirectives
+
+
+class PrerenderResult(TypedDict):
+	views: dict[str, ServerInitMessage | None]
+	directives: Directives

{pulse_framework-0.1.38a5 → pulse_framework-0.1.38a7}/src/pulse/middleware.py

@@ -1,12 +1,15 @@
 from __future__ import annotations
 
 from collections.abc import Callable, Sequence
-from typing import Any, Generic, TypeVar, overload, override
+from typing import TYPE_CHECKING, Any, Generic, TypeVar, overload, override
 
 from pulse.messages import ClientMessage, ServerInitMessage
 from pulse.request import PulseRequest
 from pulse.routing import RouteInfo
 
+if TYPE_CHECKING:
+	from pulse.app import PrerenderPayload, PrerenderResult
+
 T = TypeVar("T")
 
 
@@ -46,6 +49,22 @@ class PulseMiddleware:
 	"""
 
 	def prerender(
+		self,
+		*,
+		payload: "PrerenderPayload",
+		result: "PrerenderResult",
+		request: PulseRequest,
+		session: dict[str, Any],
+		next: Callable[[], "PrerenderResult"],
+	) -> "PrerenderResult":
+		"""Handle batch prerender at the top level.
+
+		Receives the full PrerenderPayload and can modify the PrerenderResult
+		(views and directives) before it's returned to the client.
+		"""
+		return next()
+
+	def prerender_route(
 		self,
 		*,
 		path: str,
@@ -103,6 +122,34 @@ class MiddlewareStack(PulseMiddleware):
 
 	@override
 	def prerender(
+		self,
+		*,
+		payload: "PrerenderPayload",
+		result: "PrerenderResult",
+		request: PulseRequest,
+		session: dict[str, Any],
+		next: Callable[[], "PrerenderResult"],
+	) -> "PrerenderResult":
+		def dispatch(index: int) -> "PrerenderResult":
+			if index >= len(self._middlewares):
+				return next()
+			mw = self._middlewares[index]
+
+			def _next() -> "PrerenderResult":
+				return dispatch(index + 1)
+
+			return mw.prerender(
+				payload=payload,
+				result=result,
+				request=request,
+				session=session,
+				next=_next,
+			)
+
+		return dispatch(0)
+
+	@override
+	def prerender_route(
 		self,
 		*,
 		path: str,
@@ -119,7 +166,7 @@ class MiddlewareStack(PulseMiddleware):
 			def _next() -> PrerenderResponse:
 				return dispatch(index + 1)
 
-			return mw.prerender(
+			return mw.prerender_route(
 				path=path,
 				route_info=route_info,
 				request=request,
@@ -216,6 +263,20 @@ class PulseCoreMiddleware(PulseMiddleware):
 	run, and finally returns their response unchanged.
 	"""
 
+	@override
+	def prerender(
+		self,
+		*,
+		payload: "PrerenderPayload",
+		result: "PrerenderResult",
+		request: PulseRequest,
+		session: dict[str, Any],
+		next: Callable[[], "PrerenderResult"],
+	) -> "PrerenderResult":
+		res = next()
+		# Return the result as-is (no normalization needed)
+		return res
+
 	# --- Normalization helpers -------------------------------------------------
 	def _normalize_prerender_response(self, res: Any) -> PrerenderResponse:
 		if isinstance(res, (Ok, Redirect, NotFound)):
@@ -236,7 +297,7 @@ class PulseCoreMiddleware(PulseMiddleware):
 		return Ok(None)
 
 	@override
-	def prerender(
+	def prerender_route(
 		self,
 		*,
 		path: str,

{pulse_framework-0.1.38a5 → pulse_framework-0.1.38a7}/src/pulse/plugin.py

@@ -25,3 +25,4 @@ class Plugin:
 	# Optional lifecycle
 	def on_setup(self, app: App) -> None: ...
 	def on_startup(self, app: App) -> None: ...
+	def on_shutdown(self, app: App) -> None: ...