pulse-framework 0.1.39__py3-none-any.whl → 0.1.41__py3-none-any.whl

pulse/proxy.py

@@ -1,46 +1,38 @@
 """
-Proxy ASGI app for forwarding requests to React Router server in single-server mode.
+Proxy handler for forwarding requests to React Router server in single-server mode.
 """
 
+import asyncio
 import logging
-from collections.abc import Iterable
-from typing import Callable, cast
+from typing import cast
 
 import httpx
-from starlette.datastructures import Headers
-from starlette.types import ASGIApp, Receive, Scope, Send
+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
+from websockets.typing import Subprotocol
 
 logger = logging.getLogger(__name__)
 
 
-class PulseProxy:
+class ReactProxy:
 	"""
-	ASGI app that proxies non-API requests to React Router server.
-
-	In single-server mode, Python FastAPI handles /_pulse/* routes and
-	proxies everything else to the React Router server running on an internal port.
+	Handles proxying HTTP requests and WebSocket connections to React Router server.
 	"""
 
-	def __init__(
-		self,
-		app: ASGIApp,
-		get_react_server_address: Callable[[], str | None],
-		api_prefix: str = "/_pulse",
-	):
-		"""
-		Initialize proxy ASGI app.
+	react_server_address: str
+	_client: httpx.AsyncClient | None
 
+	def __init__(self, react_server_address: str):
+		"""
 		Args:
-		    app: The ASGI application to wrap (socketio.ASGIApp)
-		    get_react_server_address: Callable that returns the React Router server full URL (or None if not started)
-		    api_prefix: Prefix for API routes that should NOT be proxied (default: "/_pulse")
+		    react_server_address: React Router server full URL (required in single-server mode)
 		"""
-		self.app: ASGIApp = app
-		self.get_react_server_address: Callable[[], str | None] = (
-			get_react_server_address
-		)
-		self.api_prefix: str = api_prefix
-		self._client: httpx.AsyncClient | None = None
+		self.react_server_address = react_server_address
+		self._client = None
 
 	@property
 	def client(self) -> httpx.AsyncClient:
@@ -52,141 +44,170 @@ class PulseProxy:
 			)
 		return self._client
 
-	async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+	def _is_websocket_upgrade(self, request: Request) -> bool:
+		"""Check if request is a WebSocket upgrade."""
+		upgrade = request.headers.get("upgrade", "").lower()
+		connection = request.headers.get("connection", "").lower()
+		return upgrade == "websocket" and "upgrade" in connection
+
+	def _http_to_ws_url(self, http_url: str) -> str:
+		"""Convert HTTP URL to WebSocket URL."""
+		if http_url.startswith("https://"):
+			return http_url.replace("https://", "wss://", 1)
+		elif http_url.startswith("http://"):
+			return http_url.replace("http://", "ws://", 1)
+		return http_url
+
+	async def proxy_websocket(self, websocket: WebSocket) -> None:
 		"""
-		ASGI application handler.
-
-		Routes starting with api_prefix or WebSocket connections go to FastAPI.
-		Everything else is proxied to React Router.
-		"""
-		if scope["type"] != "http":
-			# Pass through non-HTTP requests (WebSocket, lifespan, etc.)
-			await self.app(scope, receive, send)
-			return
-
-		path = scope["path"]
-
-		# Check if path starts with API prefix or is a WebSocket upgrade
-		if path.startswith(self.api_prefix):
-			# This is an API route, pass through to FastAPI
-			await self.app(scope, receive, send)
-			return
-
-		# Check if this is a WebSocket upgrade request (even if not prefixed)
-		headers = Headers(scope=scope)
-		if headers.get("upgrade", "").lower() == "websocket":
-			# WebSocket request, pass through to FastAPI
-			await self.app(scope, receive, send)
-			return
-
-		# Proxy to React Router server
-		await self._proxy_request(scope, receive, send)
-
-	async def _proxy_request(self, scope: Scope, receive: Receive, send: Send) -> None:
+		Proxy WebSocket connection to React Router server.
+		Only allowed in dev mode and on root path "/".
 		"""
-		Forward HTTP request to React Router server and stream response back.
-		"""
-		# Get the React server address
-		react_server_address = self.get_react_server_address()
-		if react_server_address is None:
-			# React server not started yet, return error
-			await send(
-				{
-					"type": "http.response.start",
-					"status": 503,
-					"headers": [(b"content-type", b"text/plain")],
-				}
+
+		# Build target WebSocket URL
+		ws_url = self._http_to_ws_url(self.react_server_address)
+		target_url = ws_url.rstrip("/") + websocket.url.path
+		if websocket.url.query:
+			target_url += "?" + websocket.url.query
+
+		# Extract subprotocols from client request
+		subprotocol_header = websocket.headers.get("sec-websocket-protocol")
+		subprotocols: list[Subprotocol] | None = None
+		if subprotocol_header:
+			# Parse comma-separated list of subprotocols
+			# Subprotocol is a NewType (just a type annotation), so cast strings to it
+			subprotocols = cast(
+				list[Subprotocol], [p.strip() for p in subprotocol_header.split(",")]
 			)
-			await send(
-				{
-					"type": "http.response.body",
-					"body": b"Service Unavailable: React server not ready",
-				}
+
+		# Extract headers for WebSocket connection (excluding WebSocket-specific headers)
+		headers = {
+			k: v
+			for k, v in websocket.headers.items()
+			if k.lower()
+			not in (
+				"host",
+				"upgrade",
+				"connection",
+				"sec-websocket-key",
+				"sec-websocket-version",
+				"sec-websocket-protocol",
 			)
-			return
+		}
 
-		# Build target URL
-		path = scope["path"]
-		query_string = scope.get("query_string", b"").decode("utf-8")
-		# Ensure react_server_address doesn't end with /
-		base_url = react_server_address.rstrip("/")
-		target_path = f"{base_url}{path}"
-		if query_string:
-			target_path += f"?{query_string}"
-
-		# Extract headers
-		headers: dict[str, str] = {}
-		for name, value in cast(Iterable[tuple[bytes, bytes]], scope["headers"]):
-			name = name.decode("latin1")
-			value = value.decode("latin1")
-
-			# Skip host header (will be set by httpx)
-			if name.lower() == "host":
-				continue
-
-			# Collect headers (handle multiple values)
-			existing = headers.get(name)
-			if existing:
-				headers[name] = f"{existing},{value}"
-			else:
-				headers[name] = value
-
-		# Read request body
-		body_parts: list[bytes] = []
-		while True:
-			message = await receive()
-			if message["type"] == "http.request":
-				body_parts.append(message.get("body", b""))
-				if not message.get("more_body", False):
-					break
-		body = b"".join(body_parts)
+		# Accept the client WebSocket connection first
+		# We'll accept without subprotocol initially, then update if target accepts one
+		await websocket.accept()
 
+		# Connect to target WebSocket server
 		try:
-			# Forward request to React Router
-			method = scope["method"]
-			response = await self.client.request(
-				method=method,
-				url=target_path,
-				headers=headers,
-				content=body,
+			async with websockets.connect(
+				target_url,
+				additional_headers=headers,
+				subprotocols=subprotocols,
+				ping_interval=None,  # Let the target server handle ping/pong
+			) as target_ws:
+				# Forward messages bidirectionally
+				async def forward_client_to_target():
+					try:
+						async for message in websocket.iter_text():
+							await target_ws.send(message)
+					except (WebSocketDisconnect, websockets.ConnectionClosed):
+						# Client disconnected, close target connection
+						logger.debug("Client disconnected, closing target connection")
+						try:
+							await target_ws.close()
+						except Exception:
+							pass
+					except Exception as e:
+						logger.error(f"Error forwarding client message: {e}")
+						raise
+
+				async def forward_target_to_client():
+					try:
+						async for message in target_ws:
+							if isinstance(message, str):
+								await websocket.send_text(message)
+							else:
+								await websocket.send_bytes(message)
+					except (WebSocketDisconnect, websockets.ConnectionClosed) as e:
+						# Client or target disconnected, stop forwarding
+						logger.debug(
+							"Connection closed, stopping forward_target_to_client"
+						)
+						# If target disconnected, close client connection
+						if isinstance(e, websockets.ConnectionClosed):
+							try:
+								await websocket.close()
+							except Exception:
+								pass
+					except Exception as e:
+						logger.error(f"Error forwarding target message: {e}")
+						raise
+
+				# Run both forwarding tasks concurrently
+				# If one side closes, the other will detect it and stop gracefully
+				await asyncio.gather(
+					forward_client_to_target(),
+					forward_target_to_client(),
+					return_exceptions=True,
+				)
+
+		except (websockets.WebSocketException, websockets.ConnectionClosedError) as e:
+			logger.error(f"WebSocket proxy connection failed: {e}")
+			await websocket.close(
+				code=1014,  # Bad Gateway
+				reason="Bad Gateway: Could not connect to React Router server",
 			)
+		except Exception as e:
+			logger.error(f"WebSocket proxy error: {e}")
+			await websocket.close(
+				code=1011,  # Internal Server Error
+				reason="Bad Gateway: Proxy error",
+			)
+
+	async def __call__(self, request: Request) -> Response:
+		"""
+		Forward HTTP request to React Router server and stream response back.
+		"""
+		# Build target URL
+		url = self.react_server_address.rstrip("/") + request.url.path
+		if request.url.query:
+			url += "?" + request.url.query
 
-			# Send response status
-			await send(
-				{
-					"type": "http.response.start",
-					"status": response.status_code,
-					"headers": [
-						(name.encode("latin1"), value.encode("latin1"))
-						for name, value in response.headers.items()
-					],
-				}
+		# Extract headers, skip host header (will be set by httpx)
+		headers = {k: v for k, v in request.headers.items() if k.lower() != "host"}
+
+		try:
+			# Build request
+			req = self.client.build_request(
+				method=request.method,
+				url=url,
+				headers=headers,
+				content=request.stream(),
 			)
 
-			# Stream response body
-			await send(
-				{
-					"type": "http.response.body",
-					"body": response.content,
-				}
+			# Send request with streaming
+			r = await self.client.send(req, stream=True)
+
+			# Filter out headers that shouldn't be present in streaming responses
+			response_headers = {
+				k: v
+				for k, v in r.headers.items()
+				# if k.lower() not in ("content-length", "transfer-encoding")
+			}
+
+			return StreamingResponse(
+				r.aiter_raw(),
+				background=BackgroundTask(r.aclose),
+				status_code=r.status_code,
+				headers=response_headers,
 			)
 
 		except httpx.RequestError as e:
 			logger.error(f"Proxy request failed: {e}")
-
-			# Send error response
-			await send(
-				{
-					"type": "http.response.start",
-					"status": 502,
-					"headers": [(b"content-type", b"text/plain")],
-				}
-			)
-			await send(
-				{
-					"type": "http.response.body",
-					"body": b"Bad Gateway: Could not reach React Router server",
-				}
+			return PlainTextResponse(
+				"Bad Gateway: Could not reach React Router server", status_code=502
 			)
 
 	async def close(self):

pulse/queries/common.py

@@ -0,0 +1,24 @@
+from collections.abc import Callable
+from typing import (
+	Any,
+	Concatenate,
+	ParamSpec,
+	TypeVar,
+)
+
+from pulse.state import State
+
+T = TypeVar("T")
+TState = TypeVar("TState", bound="State")
+P = ParamSpec("P")
+R = TypeVar("R")
+
+OnSuccessFn = Callable[[TState], Any] | Callable[[TState, T], Any]
+OnErrorFn = Callable[[TState], Any] | Callable[[TState, Exception], Any]
+
+
+def bind_state(
+	state: TState, fn: Callable[Concatenate[TState, P], R]
+) -> Callable[P, R]:
+	"Type-safe helper to bind a method to a state"
+	return fn.__get__(state, state.__class__)

pulse/queries/mutation.py

@@ -0,0 +1,142 @@
+from collections.abc import Awaitable, Callable
+from typing import (
+	Any,
+	Concatenate,
+	Generic,
+	ParamSpec,
+	TypeVar,
+	override,
+)
+
+from pulse.helpers import call_flexible, maybe_await
+from pulse.queries.common import OnErrorFn, OnSuccessFn, bind_state
+from pulse.reactive import Signal
+from pulse.state import InitializableProperty, State
+
+T = TypeVar("T")
+TState = TypeVar("TState", bound=State)
+R = TypeVar("R")
+P = ParamSpec("P")
+
+
+class MutationResult(Generic[T, P]):
+	"""
+	Result object for mutations that provides reactive access to mutation state
+	and is callable to execute the mutation.
+	"""
+
+	_data: Signal[T | None]
+	_is_running: Signal[bool]
+	_error: Signal[Exception | None]
+	_fn: Callable[P, Awaitable[T]]
+	_on_success: Callable[[T], Any] | None
+	_on_error: Callable[[Exception], Any] | None
+
+	def __init__(
+		self,
+		fn: Callable[P, Awaitable[T]],
+		on_success: Callable[[T], Any] | None = None,
+		on_error: Callable[[Exception], Any] | None = None,
+	):
+		self._data = Signal(None, name="mutation.data")
+		self._is_running = Signal(False, name="mutation.is_running")
+		self._error = Signal(None, name="mutation.error")
+		self._fn = fn
+		self._on_success = on_success
+		self._on_error = on_error
+
+	@property
+	def data(self) -> T | None:
+		return self._data()
+
+	@property
+	def is_running(self) -> bool:
+		return self._is_running()
+
+	@property
+	def error(self) -> Exception | None:
+		return self._error()
+
+	async def __call__(self, *args: P.args, **kwargs: P.kwargs) -> T:
+		self._is_running.write(True)
+		self._error.write(None)
+		try:
+			mutation_result = await self._fn(*args, **kwargs)
+			self._data.write(mutation_result)
+			if self._on_success:
+				await maybe_await(call_flexible(self._on_success, mutation_result))
+			return mutation_result
+		except Exception as e:
+			self._error.write(e)
+			if self._on_error:
+				await maybe_await(call_flexible(self._on_error, e))
+			raise e
+		finally:
+			self._is_running.write(False)
+
+
+class MutationProperty(Generic[T, TState, P], InitializableProperty):
+	_on_success_fn: Callable[[TState, T], Any] | None
+	_on_error_fn: Callable[[TState, Exception], Any] | None
+	name: str
+	fn: Callable[Concatenate[TState, P], Awaitable[T]]
+
+	def __init__(
+		self,
+		name: str,
+		fn: Callable[Concatenate[TState, P], Awaitable[T]],
+		on_success: OnSuccessFn[TState, T] | None = None,
+		on_error: OnErrorFn[TState] | None = None,
+	):
+		self.name = name
+		self.fn = fn
+		self._on_success_fn = on_success  # pyright: ignore[reportAttributeAccessIssue]
+		self._on_error_fn = on_error  # pyright: ignore[reportAttributeAccessIssue]
+
+	# Decorator to attach an on-success handler (sync or async)
+	def on_success(self, fn: OnSuccessFn[TState, T]):
+		if self._on_success_fn is not None:
+			raise RuntimeError(
+				f"Duplicate on_success() decorator for mutation '{self.name}'. Only one is allowed."
+			)
+		self._on_success_fn = fn  # pyright: ignore[reportAttributeAccessIssue]
+		return fn
+
+	# Decorator to attach an on-error handler (sync or async)
+	def on_error(self, fn: OnErrorFn[TState]):
+		if self._on_error_fn is not None:
+			raise RuntimeError(
+				f"Duplicate on_error() decorator for mutation '{self.name}'. Only one is allowed."
+			)
+		self._on_error_fn = fn  # pyright: ignore[reportAttributeAccessIssue]
+		return fn
+
+	def __get__(self, obj: Any, objtype: Any = None) -> MutationResult[T, P]:
+		if obj is None:
+			return self  # pyright: ignore[reportReturnType]
+
+		# Cache the result on the instance
+		cache_key = f"__mutation_{self.name}"
+		if not hasattr(obj, cache_key):
+			# Bind methods to state
+			bound_fn = bind_state(obj, self.fn)
+			bound_on_success = (
+				bind_state(obj, self._on_success_fn) if self._on_success_fn else None
+			)
+			bound_on_error = (
+				bind_state(obj, self._on_error_fn) if self._on_error_fn else None
+			)
+
+			result = MutationResult[T, P](
+				fn=bound_fn,
+				on_success=bound_on_success,
+				on_error=bound_on_error,
+			)
+			setattr(obj, cache_key, result)
+
+		return getattr(obj, cache_key)
+
+	@override
+	def initialize(self, state: State, name: str) -> MutationResult[T, P]:
+		# For compatibility with InitializableProperty, but mutations don't need special initialization
+		return self.__get__(state, state.__class__)