pulse-framework 0.1.38a4__tar.gz → 0.1.38a6__tar.gz

{pulse_framework-0.1.38a4 → pulse_framework-0.1.38a6}/PKG-INFO

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

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

{pulse_framework-0.1.38a4 → pulse_framework-0.1.38a6}/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.38a4 → pulse_framework-0.1.38a6}/src/pulse/app.py

@@ -11,7 +11,7 @@ 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 +56,8 @@ from pulse.messages import (
 	ClientChannelResponseMessage,
 	ClientMessage,
 	ClientPulseMessage,
-	ServerInitMessage,
+	PrerenderPayload,
+	PrerenderResult,
 	ServerMessage,
 )
 from pulse.middleware import (
@@ -73,7 +74,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 +92,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.
@@ -277,6 +267,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()
@@ -380,7 +375,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")
@@ -483,7 +478,13 @@ class App:
 				)
 				cleanup = True
 
-			result: PrerenderResult = {"renderId": render_id, "views": {}}
+			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 +500,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),
@@ -545,7 +548,19 @@ class App:
 				if cleanup:
 					later(float(ttl), _gc_if_unadopted, render_id)
 
-			resp = JSONResponse(serialize(result))
+			# 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,
+			)
+
+			resp = JSONResponse(serialize(final_result))
 			session.handle_response(resp)
 			return resp
 
@@ -572,7 +587,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)
@@ -825,6 +840,29 @@ 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.
+		"""
+
+		# Close all render sessions
+		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.

{pulse_framework-0.1.38a4 → pulse_framework-0.1.38a6}/src/pulse/cli/cmd.py

@@ -416,18 +416,25 @@ def build_web_command(
 	port: int | None = None,
 	mode: PulseEnv = "dev",
 ) -> CommandSpec:
+	command_env = os.environ.copy()
 	if mode == "prod":
 		# Production: use built server
 		args = ["bun", "run", "start"]
 	else:
 		# Development: use dev server
 		args = ["bun", "run", "dev"]
+
 	if port is not None:
-		args.extend(["--port", str(port)])
+		if mode == "prod":
+			# react-router-serve uses PORT environment variable
+			# Don't add --port flag for production
+			command_env["PORT"] = str(port)
+		else:
+			# react-router dev accepts --port flag
+			args.extend(["--port", str(port)])
 	if extra_args:
 		args.extend(extra_args)
 
-	command_env = os.environ.copy()
 	command_env.update(
 		{
 			"FORCE_COLOR": "1",

{pulse_framework-0.1.38a4 → pulse_framework-0.1.38a6}/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,20 @@ 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);
+    if (data.directives) {
+      sessionStorage.setItem("__PULSE_DIRECTIVES", JSON.stringify(data.directives));
+    }
   }
   return (
     <PulseProvider config={config} prerender={data}>
@@ -78,6 +95,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.38a4 → pulse_framework-0.1.38a6}/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.38a4 → pulse_framework-0.1.38a6}/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.38a4 → pulse_framework-0.1.38a6}/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: ...