pulse-framework 0.1.37__py3-none-any.whl → 0.1.38a2__py3-none-any.whl

pulse/__init__.py

@@ -17,7 +17,7 @@
 
 # Core app/session
 from pulse.app import App as App
-from pulse.app import DeploymentMode as DeploymentMode
+from pulse.app import PulseMode as PulseMode
 from pulse.channel import (
 	Channel as Channel,
 )
@@ -72,7 +72,7 @@ from pulse.decorators import effect as effect
 from pulse.decorators import query as query
 
 # Environment
-from pulse.env import PulseMode as PulseMode
+from pulse.env import PulseEnv as PulseEnv
 from pulse.env import env as env
 from pulse.env import mode as mode
 

pulse/app.py

@@ -5,17 +5,23 @@ 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
+import subprocess
 from collections import defaultdict
 from collections.abc import Awaitable, Sequence
 from contextlib import asynccontextmanager
 from enum import IntEnum
+from pathlib import Path
 from typing import Any, Callable, Literal, NotRequired, TypedDict, TypeVar, cast
 
 import socketio
+import uvicorn
 from fastapi import FastAPI, HTTPException, Request, Response
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse
+from starlette.types import ASGIApp
 
 from pulse.codegen.codegen import Codegen, CodegenConfig
 from pulse.context import PULSE_CONTEXT, PulseContext
@@ -32,15 +38,14 @@ from pulse.css import (
 	registered_css_imports,
 	registered_css_modules,
 )
-from pulse.env import PulseMode, env
+from pulse.env import ENV_PULSE_HOST, ENV_PULSE_PORT, PulseEnv
+from pulse.env import env as envvars
 from pulse.helpers import (
 	create_task,
-	ensure_web_lock,
+	find_available_port,
 	get_client_address,
 	get_client_address_socketio,
 	later,
-	lock_path_for_web_root,
-	remove_web_lock,
 )
 from pulse.hooks.core import hooks
 from pulse.hooks.runtime import NotFoundInterrupt, RedirectInterrupt
@@ -63,6 +68,7 @@ from pulse.middleware import (
 	Redirect,
 )
 from pulse.plugin import Plugin
+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
@@ -87,7 +93,7 @@ class AppStatus(IntEnum):
 	stopped = 3
 
 
-DeploymentMode = Literal["dev", "same_host", "subdomains"]
+PulseMode = Literal["subdomains", "single-server"]
 
 
 class PrerenderPayload(TypedDict):
@@ -120,11 +126,13 @@ class App:
 	    ```
 	"""
 
+	env: PulseEnv
 	mode: PulseMode
-	deployment: DeploymentMode
 	status: AppStatus
 	server_address: str | None
+	dev_server_address: str
 	internal_server_address: str | None
+	api_prefix: str
 	plugins: list[Plugin]
 	routes: RouteTree
 	not_found: str
@@ -135,8 +143,8 @@ class App:
 	cors: CORSOptions | None
 	codegen: Codegen
 	fastapi: FastAPI
-	sio: socketio.AsyncServer  # type: ignore
-	asgi: socketio.ASGIApp  # type: ignore
+	sio: socketio.AsyncServer
+	asgi: ASGIApp
 	middleware: MiddlewareStack
 	_user_to_render: dict[str, list[str]]
 	_render_to_user: dict[str, str]
@@ -153,11 +161,12 @@ class App:
 		cookie: Cookie | None = None,
 		session_store: SessionStore | None = None,
 		server_address: str | None = None,
+		dev_server_address: str = "http://localhost:8000",
 		internal_server_address: str | None = None,
 		not_found: str = "/not-found",
 		# Deployment and integration options
-		mode: PulseMode | None = None,
-		deployment: DeploymentMode = "subdomains",
+		mode: PulseMode = "single-server",
+		api_prefix: str = "/_pulse",
 		cors: CORSOptions | None = None,
 		fastapi: dict[str, Any] | None = None,
 	):
@@ -169,14 +178,18 @@ class App:
 		    codegen: Optional codegen configuration.
 		"""
 		# Resolve mode from environment and expose on the app instance
-		self.mode = mode or env.pulse_mode
-		self.deployment = "dev" if self.mode == "dev" else deployment
+		self.env = envvars.pulse_env
+		self.mode = mode
 		self.status = AppStatus.created
 		# Persist the server address for use by sessions (API calls, etc.)
 		self.server_address = server_address
+		# Development server address (used in dev mode)
+		self.dev_server_address = dev_server_address
 		# Optional internal address used by server-side loader fetches
 		self.internal_server_address = internal_server_address
 
+		self.api_prefix = api_prefix
+
 		# Resolve and store plugins (sorted by priority, highest first)
 		self.plugins = []
 		if plugins:
@@ -189,7 +202,7 @@ class App:
 		# Add plugin routes after user-defined routes
 		for plugin in self.plugins:
 			all_routes.extend(plugin.routes())
-			if self.mode == "dev":
+			if self.env == "dev":
 				all_routes.extend(plugin.dev_routes())
 
 		# Auto-add React components to all routes
@@ -203,7 +216,7 @@ class App:
 		self.user_sessions = {}
 		self.render_sessions = {}
 		self.session_store = session_store or CookieSessionStore()
-		self.cookie = cookie or session_cookie(mode=self.deployment)
+		self.cookie = cookie or session_cookie(mode=self.mode)
 		self.cors = cors
 
 		self._user_to_render = defaultdict(list)
@@ -212,56 +225,22 @@ class App:
 		# Map websocket sid -> renderId for message routing
 		self._socket_to_render = {}
 
+		# Subprocess management for single-server mode
+		self.web_server_proc: subprocess.Popen[str] | None = None
+		self.web_server_port: int | None = None
+
 		self.codegen = Codegen(
 			self.routes,
 			config=codegen or CodegenConfig(),
 		)
 
-		@asynccontextmanager
-		async def lifespan(_: FastAPI):
-			try:
-				if isinstance(self.session_store, SessionStore):
-					await self.session_store.init()
-			except Exception:
-				logger.exception("Error during SessionStore.init()")
-			# Create a lock file in the web project (unless the CLI manages it)
-			lock_path = None
-			try:
-				if not env.lock_managed_by_cli:
-					try:
-						lock_path = lock_path_for_web_root(self.codegen.cfg.web_root)
-						__ = ensure_web_lock(lock_path, owner="server")
-					except RuntimeError as e:
-						logger.error(str(e))
-						raise
-			except Exception:
-				logger.exception("Failed to create Pulse dev lock file")
-				raise
-			# Call plugin on_startup hooks before serving
-			for plugin in self.plugins:
-				plugin.on_startup(self)
-			try:
-				yield
-			finally:
-				try:
-					if isinstance(self.session_store, SessionStore):
-						await self.session_store.close()
-				except Exception:
-					logger.exception("Error during SessionStore.close()")
-				# Remove lock if we created it
-				try:
-					if not env.lock_managed_by_cli and lock_path:
-						remove_web_lock(lock_path)
-				except Exception:
-					# Best-effort
-					pass
-
 		self.fastapi = FastAPI(
 			title="Pulse UI Server",
-			lifespan=lifespan,
+			lifespan=self.fastapi_lifespan,
 		)
 		self.sio = socketio.AsyncServer(async_mode="asgi", cors_allowed_origins="*")
 		self.asgi = socketio.ASGIApp(self.sio, self.fastapi)
+
 		if middleware is None:
 			mw_stack: list[PulseMiddleware] = [PulseCoreMiddleware()]
 		elif isinstance(middleware, PulseMiddleware):
@@ -275,11 +254,133 @@ class App:
 
 		self.middleware = MiddlewareStack(mw_stack)
 
+	@asynccontextmanager
+	async def fastapi_lifespan(self, _: FastAPI):
+		try:
+			if isinstance(self.session_store, SessionStore):
+				await self.session_store.init()
+		except Exception:
+			logger.exception("Error during SessionStore.init()")
+
+		# Call plugin on_startup hooks before serving
+		for plugin in self.plugins:
+			plugin.on_startup(self)
+
+		# Start React Router server in single-server mode
+		logger.info(f"Deployment mode: {self.mode}")
+		if self.mode == "single-server":
+			logger.info("Starting React Router server in single-server mode...")
+			try:
+				web_root = self.codegen.cfg.web_root
+				logger.info(f"Web root: {web_root}")
+				port = await self.start_web_server(web_root, self.env)
+				logger.info(
+					f"Single-server mode: React Router running on internal port {port}"
+				)
+			except Exception:
+				logger.exception("Failed to start React Router server")
+				raise
+
+		try:
+			yield
+		finally:
+			# Stop React Router server in single-server mode
+			if self.mode == "single-server":
+				try:
+					self.stop_web_server()
+				except Exception:
+					logger.exception("Error stopping React Router server")
+
+			try:
+				if isinstance(self.session_store, SessionStore):
+					await self.session_store.close()
+			except Exception:
+				logger.exception("Error during SessionStore.close()")
+
+	async def start_web_server(self, web_root: Path, mode: str) -> int:
+		"""Start React Router server as subprocess and return its port."""
+
+		# Find available port
+		port = find_available_port(5173)
+
+		# Build command based on mode
+		if mode == "prod":
+			# Check if build exists
+			build_server = web_root / "build" / "server" / "index.js"
+			if not build_server.exists():
+				raise RuntimeError(
+					f"Production build not found at {build_server}. Run 'bun run build' in the web directory first."
+				)
+			cli_path = (
+				web_root
+				/ "node_modules"
+				/ "@react-router"
+				/ "serve"
+				/ "dist"
+				/ "cli.js"
+			)
+			if not cli_path.exists():
+				raise RuntimeError(
+					f"React Router CLI not found at {cli_path}. Did you install web dependencies?"
+				)
+			# Production: use Node to serve the built bundle (Bun lacks renderToPipeableStream)
+			cmd = [
+				"bun",
+				"run",
+				"start",
+				"--port",
+				str(port),
+			]
+		else:
+			# Development: use dev server
+			cmd = ["bun", "run", "dev", "--port", str(port)]
+
+		logger.info(f"Starting React Router server: {' '.join(cmd)}")
+
+		proc = subprocess.Popen(
+			cmd,
+			cwd=web_root,
+			stdout=subprocess.PIPE,
+			stderr=subprocess.STDOUT,
+			env=os.environ.copy(),
+			text=True,
+		)
+
+		# Wait for server to be ready
+		await asyncio.sleep(2.0 if mode == "prod" else 1.0)
+
+		# Check if process is still running
+		if proc.poll() is not None:
+			output = proc.stdout.read() if proc.stdout else ""
+			raise RuntimeError(f"React Router server failed to start: {output}")
+
+		self.web_server_proc = proc
+		self.web_server_port = port
+
+		logger.info(f"React Router server started on port {port}")
+		return port
+
+	def stop_web_server(self):
+		"""Stop the React Router subprocess."""
+		if self.web_server_proc:
+			logger.info("Stopping React Router server...")
+			self.web_server_proc.terminate()
+			try:
+				self.web_server_proc.wait(timeout=5)
+			except subprocess.TimeoutExpired:
+				logger.warning(
+					"React Router server did not stop gracefully, killing..."
+				)
+				self.web_server_proc.kill()
+				self.web_server_proc.wait()
+			self.web_server_proc = None
+			self.web_server_port = None
+
 	def run_codegen(
 		self, address: str | None = None, internal_address: str | None = None
 	):
 		# Allow the CLI to disable codegen in specific scenarios (e.g., prod server-only)
-		if env.codegen_disabled:
+		if envvars.codegen_disabled:
 			return
 		if address:
 			self.server_address = address
@@ -292,6 +393,7 @@ class App:
 		self.codegen.generate_all(
 			self.server_address,
 			self.internal_server_address or self.server_address,
+			self.api_prefix,
 		)
 
 	def asgi_factory(self):
@@ -299,28 +401,49 @@ class App:
 		ASGI factory for uvicorn. This is called on every reload.
 		"""
 
-		# In prod, prefer the public server address passed to App(...).
-		# In dev/ci, derive from environment variables which the CLI populates
-		# based on the actual bind host/port.
-		if self.mode == "prod":
+		# In prod/ci, use the server_address provided to App(...).
+		if self.env in ("prod", "ci"):
 			if not self.server_address:
 				raise RuntimeError(
-					"In prod, please provide an explicit server_address to App(...)."
+					f"In {self.env}, please provide an explicit server_address to App(...)."
 				)
 			server_address = self.server_address
+		# In dev, prefer env vars set by CLI (--address/--port), otherwise use dev_server_address.
 		else:
-			host = env.pulse_host  # defaults to "localhost"
-			port = env.pulse_port  # defaults to 8000
-			protocol = "http" if host in ("127.0.0.1", "localhost") else "https"
-			server_address = f"{protocol}://{host}:{port}"
+			# In dev mode, check if CLI set PULSE_HOST/PULSE_PORT env vars
+			# If env vars were explicitly set (not just defaults), use them
+			host = os.environ.get(ENV_PULSE_HOST)
+			port = os.environ.get(ENV_PULSE_PORT)
+			if host is not None and port is not None:
+				protocol = "http" if host in ("127.0.0.1", "localhost") else "https"
+				server_address = f"{protocol}://{host}:{port}"
+			else:
+				server_address = self.dev_server_address
 
 		# Use internal server address for server-side loader if provided; fallback to public
 		internal_address = self.internal_server_address or server_address
 		self.run_codegen(server_address, internal_address)
 		self.setup(server_address)
 		self.status = AppStatus.running
+
+		# Wrap with proxy in single-server mode. Do it here instead of within
+		# __init__ to allow the CLI to override the mode.
+		if self.mode == "single-server":
+			return PulseProxy(self.asgi, lambda: self.web_server_port, self.api_prefix)
 		return self.asgi
 
+	def run(
+		self,
+		address: str = "localhost",
+		port: int = 8000,
+		find_port: bool = True,
+		reload: bool = True,
+	):
+		if find_port:
+			port = find_available_port(port)
+
+		uvicorn.run(self.asgi_factory, reload=reload)
+
 	def setup(self, server_address: str):
 		if self.status >= AppStatus.initialized:
 			logger.warning("Called App.setup() on an already initialized application")
@@ -333,19 +456,42 @@ class App:
 
 		# Compute cookie domain from deployment/server address if not explicitly provided
 		if self.cookie.domain is None:
-			self.cookie.domain = compute_cookie_domain(
-				self.deployment, self.server_address
-			)
+			self.cookie.domain = compute_cookie_domain(self.mode, self.server_address)
 
 		# Add CORS middleware (configurable/overridable)
 		if self.cors is not None:
 			self.fastapi.add_middleware(CORSMiddleware, **self.cors)
 		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_options(self.deployment, self.server_address),
+				**cors_config,
 			)
 
+		# Debug middleware to log CORS-related request details
+		@self.fastapi.middleware("http")
+		async def cors_debug_middleware(  # pyright: ignore[reportUnusedFunction]
+			request: Request, call_next: Callable[[Request], Awaitable[Response]]
+		):
+			origin = request.headers.get("origin")
+			method = request.method
+			path = request.url.path
+			print(
+				f"[CORS Debug] {method} {path} | Origin: {origin} | "
+				+ f"Mode: {self.mode} | Server: {self.server_address}"
+			)
+			response = await call_next(request)
+			allow_origin = response.headers.get("access-control-allow-origin")
+			if allow_origin:
+				print(f"[CORS Debug] Response allows origin: {allow_origin}")
+			elif origin:
+				logger.warning(
+					f"[CORS Debug] Origin {origin} present but no Access-Control-Allow-Origin header set"
+				)
+			return response
+
 		# Mount PulseContext for all FastAPI routes (no route info). Other API
 		# routes / middleware should be added at the module-level, which means
 		# this middleware will wrap all of them.
@@ -362,9 +508,9 @@ class App:
 			self._sessions_in_request[session.sid] = (
 				self._sessions_in_request.get(session.sid, 0) + 1
 			)
-			header_sid = request.headers.get("x-pulse-render-id")
-			if header_sid:
-				render = self.render_sessions.get(header_sid)
+			render_id = request.headers.get("x-pulse-render-id")
+			if render_id:
+				render = self.render_sessions.get(render_id)
 			else:
 				render = None
 			with PulseContext.update(session=session, render=render):
@@ -377,16 +523,19 @@ class App:
 
 			return res
 
-		@self.fastapi.get("/health")
+		# Apply prefix to all routes
+		prefix = self.api_prefix
+
+		@self.fastapi.get(f"{prefix}/health")
 		def healthcheck():  # pyright: ignore[reportUnusedFunction]
 			return {"health": "ok", "message": "Pulse server is running"}
 
-		@self.fastapi.get("/set-cookies")
+		@self.fastapi.get(f"{prefix}/set-cookies")
 		def set_cookies():  # pyright: ignore[reportUnusedFunction]
 			return {"health": "ok", "message": "Cookies updated"}
 
 		# RouteInfo is the request body
-		@self.fastapi.post("/prerender")
+		@self.fastapi.post(f"{prefix}/prerender")
 		async def prerender(payload: PrerenderPayload, request: Request):  # pyright: ignore[reportUnusedFunction]
 			"""
 			POST /prerender
@@ -492,7 +641,7 @@ class App:
 			session.handle_response(resp)
 			return resp
 
-		@self.fastapi.post("/pulse/forms/{render_id}/{form_id}")
+		@self.fastapi.post(f"{prefix}/forms/{{render_id}}/{{form_id}}")
 		async def handle_form_submit(  # pyright: ignore[reportUnusedFunction]
 			render_id: str, form_id: str, request: Request
 		) -> Response: