Enhance error handling and validation in RSC-related modules

Author: AbanoubGhadban

node_package/src/PostSSRHookTracker.ts

@@ -5,33 +5,59 @@ type PostSSRHook = () => void;
  *
  * This class provides a local alternative to the global hook management,
  * allowing each request to have its own isolated hook tracker without sharing state.
+ *
+ * The tracker ensures that:
+ * - Hooks are executed exactly once when SSR ends
+ * - No hooks can be added after SSR has completed
+ * - Proper cleanup occurs to prevent memory leaks
  */
 class PostSSRHookTracker {
   private hooks: PostSSRHook[] = [];
 
+  private hasSSREnded = false;
+
   /**
    * Adds a hook to be executed when SSR ends for this request.
    *
    * @param hook - Function to call when SSR ends
+   * @throws Error if called after SSR has already ended
    */
   addPostSSRHook(hook: PostSSRHook): void {
+    if (this.hasSSREnded) {
+      console.error(
+        'Cannot add post-SSR hook: SSR has already ended for this request. ' +
+          'Hooks must be registered before or during the SSR process.',
+      );
+      return;
+    }
+
     this.hooks.push(hook);
   }
 
   /**
    * Notifies all registered hooks that SSR has ended and clears the hook list.
-   * This should be called when server-side rendering is complete.
+   * This should be called exactly once when server-side rendering is complete.
+   *
+   * @throws Error if called multiple times
    */
   notifySSREnd(): void {
-    this.hooks.forEach((hook) => hook());
-    this.hooks = [];
-  }
+    if (this.hasSSREnded) {
+      console.warn('notifySSREnd() called multiple times. This may indicate a bug in the SSR lifecycle.');
+      return;
+    }
 
-  /**
-   * Clears all hooks without executing them.
-   * Should be called if the request is aborted or cleanup is needed.
-   */
-  clear(): void {
+    this.hasSSREnded = true;
+
+    // Execute all hooks and handle any errors gracefully
+    this.hooks.forEach((hook, index) => {
+      try {
+        hook();
+      } catch (error) {
+        console.error(`Error executing post-SSR hook ${index}:`, error);
+      }
+    });
+
+    // Clear hooks to free memory
     this.hooks = [];
   }
 }

node_package/src/RSCRequestTracker.ts

@@ -36,12 +36,22 @@ class RSCRequestTracker {
    * Clears all streams and callbacks for this request.
    * Should be called when the request is complete to ensure proper cleanup,
    * though garbage collection will handle cleanup automatically when the tracker goes out of scope.
+   *
+   * This method is safe to call multiple times and will handle any errors during cleanup gracefully.
    */
   clear(): void {
     // Close any active streams before clearing
-    this.streams.forEach(({ stream }) => {
-      if (typeof (stream as Readable).destroy === 'function') {
-        (stream as Readable).destroy();
+    this.streams.forEach(({ stream, componentName }, index) => {
+      try {
+        if (stream && typeof (stream as Readable).destroy === 'function') {
+          (stream as Readable).destroy();
+        }
+      } catch (error) {
+        // Log the error but don't throw to avoid disrupting cleanup of other streams
+        console.warn(
+          `Warning: Error while destroying RSC stream for component "${componentName}" at index ${index}:`,
+          error,
+        );
       }
     });
 
@@ -83,31 +93,50 @@ class RSCRequestTracker {
    * @param componentName - Name of the server component
    * @param props - Props for the server component
    * @returns A stream of the RSC payload
+   * @throws Error if generateRSCPayload is not available or fails
    */
   async getRSCPayloadStream(componentName: string, props: unknown): Promise<NodeJS.ReadableStream> {
-    const stream = await generateRSCPayload(componentName, props, this.railsContext);
-
-    // Tee stream to allow for multiple consumers:
-    //   1. stream1 - Used by React's runtime to perform server-side rendering
-    //   2. stream2 - Used by react-on-rails to embed the RSC payloads
-    //      into the HTML stream for client-side hydration
-    const stream1 = new PassThrough();
-    stream.pipe(stream1);
-    const stream2 = new PassThrough();
-    stream.pipe(stream2);
-
-    const streamInfo: RSCPayloadStreamInfo = {
-      componentName,
-      props,
-      stream: stream2,
-    };
-
-    this.streams.push(streamInfo);
-
-    // Notify callbacks about the new stream in a sync manner to maintain proper hydration timing
-    this.callbacks.forEach((callback) => callback(streamInfo));
-
-    return stream1;
+    // Validate that the global generateRSCPayload function is available
+    if (typeof generateRSCPayload !== 'function') {
+      throw new Error(
+        'generateRSCPayload is not defined. Please ensure that you are using at least version 4.0.0 of ' +
+          'React on Rails Pro and the Node renderer, and that ReactOnRailsPro.configuration.enable_rsc_support ' +
+          'is set to true.',
+      );
+    }
+
+    try {
+      const stream = await generateRSCPayload(componentName, props, this.railsContext);
+
+      // Tee stream to allow for multiple consumers:
+      //   1. stream1 - Used by React's runtime to perform server-side rendering
+      //   2. stream2 - Used by react-on-rails to embed the RSC payloads
+      //      into the HTML stream for client-side hydration
+      const stream1 = new PassThrough();
+      stream.pipe(stream1);
+      const stream2 = new PassThrough();
+      stream.pipe(stream2);
+
+      const streamInfo: RSCPayloadStreamInfo = {
+        componentName,
+        props,
+        stream: stream2,
+      };
+
+      this.streams.push(streamInfo);
+
+      // Notify callbacks about the new stream in a sync manner to maintain proper hydration timing
+      this.callbacks.forEach((callback) => callback(streamInfo));
+
+      return stream1;
+    } catch (error) {
+      // Provide a more helpful error message that includes context
+      throw new Error(
+        `Failed to generate RSC payload for component "${componentName}": ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
   }
 
   /**

node_package/src/getReactServerComponent.client.ts

@@ -42,13 +42,39 @@ const createFromFetch = async (fetchPromise: Promise<Response>) => {
  *
  * @param props - Object containing component name, props, and railsContext
  * @returns A Promise resolving to the rendered React element
+ * @throws Error if RSC payload generation URL path is not configured or network request fails
  */
 const fetchRSC = ({ componentName, componentProps, railsContext }: ClientGetReactServerComponentProps) => {
-  const propsString = JSON.stringify(componentProps);
   const { rscPayloadGenerationUrlPath } = railsContext;
-  const strippedUrlPath = rscPayloadGenerationUrlPath?.replace(/^\/|\/$/g, '');
-  const encodedParams = new URLSearchParams({ props: propsString }).toString();
-  return createFromFetch(fetch(`/${strippedUrlPath}/${componentName}?${encodedParams}`));
+
+  if (!rscPayloadGenerationUrlPath) {
+    throw new Error(
+      `Cannot fetch RSC payload for component "${componentName}": rscPayloadGenerationUrlPath is not configured. ` +
+        'Please ensure React Server Components support is properly enabled and configured.',
+    );
+  }
+
+  try {
+    const propsString = JSON.stringify(componentProps);
+    const strippedUrlPath = rscPayloadGenerationUrlPath.replace(/^\/|\/$/g, '');
+    const encodedParams = new URLSearchParams({ props: propsString }).toString();
+    const fetchUrl = `/${strippedUrlPath}/${componentName}?${encodedParams}`;
+
+    return createFromFetch(fetch(fetchUrl)).catch((error: unknown) => {
+      throw new Error(
+        `Failed to fetch RSC payload for component "${componentName}" from "${fetchUrl}": ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    });
+  } catch (error: unknown) {
+    // Handle JSON.stringify errors or other synchronous errors
+    throw new Error(
+      `Failed to prepare RSC request for component "${componentName}": ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
 };
 
 const createRSCStreamFromArray = (payloads: string[]) => {

node_package/src/streamServerRenderedReactComponent.ts

@@ -220,6 +220,22 @@ type StreamRenderer<T, P extends RenderParams> = (
   streamingTrackers: StreamingTrackers,
 ) => T;
 
+/**
+ * This module implements request-scoped tracking for React Server Components (RSC)
+ * and post-SSR hooks using local tracker instances per request.
+ *
+ * DESIGN PRINCIPLES:
+ * - Each request gets its own PostSSRHookTracker and RSCRequestTracker instances
+ * - State is automatically garbage collected when request completes
+ * - No shared state between concurrent requests
+ * - Simple, predictable cleanup lifecycle
+ *
+ * TRACKER RESPONSIBILITIES:
+ * - PostSSRHookTracker: Manages hooks that run after SSR completes
+ * - RSCRequestTracker: Handles RSC payload generation and stream tracking
+ * - Both inject their capabilities into the Rails context for component access
+ */
+
 export const streamServerRenderedComponent = <T, P extends RenderParams>(
   options: P,
   renderStrategy: StreamRenderer<T, P>,

node_package/src/utils.ts

@@ -10,15 +10,36 @@ const customFetch = (...args: Parameters<typeof fetch>) => {
 
 export { customFetch as fetch };
 
+/**
+ * Creates a unique cache key for RSC payloads to prevent collisions between component instances.
+ *
+ * This function generates cache keys that ensure:
+ * 1. Different components have different keys
+ * 2. Same components with different props have different keys
+ * 3. Multiple instances of the same component on the same rails view have different keys
+ *
+ * @param componentName - Name of the React Server Component
+ * @param componentProps - Props passed to the component (serialized to JSON)
+ * @param domNodeId - DOM node ID of the parent react component rendered at the rails view (prevents instance collisions)
+ * @returns A unique cache key string
+ * @throws Error if domNodeId is missing, which could lead to cache collisions
+ */
 export const createRSCPayloadKey = (
   componentName: string,
   componentProps: unknown,
   domNodeId: string | undefined,
 ) => {
   if (!domNodeId) {
-    console.warn(
-      'Warning: domNodeId is required when using React Server Components to ensure unique RSC payload caching and prevent conflicts between multiple instances of the same component.',
-    );
+    const errorMessage =
+      'domNodeId is required when using React Server Components to ensure unique RSC payload caching ' +
+      'and prevent conflicts between multiple instances of the same component at the same rails view. ' +
+      'This could lead to incorrect hydration and component state issues.';
+
+    if (process.env.NODE_ENV === 'development') {
+      throw new Error(`RSC Cache Key Error: ${errorMessage}`);
+    } else {
+      console.warn(`Warning: ${errorMessage}`);
+    }
   }
 
   return `${componentName}-${JSON.stringify(componentProps)}-${domNodeId}`;