feat(plugin-bridge): add RPC bridge

.nx/version-plans/version-plan-1766951301102.md

@@ -0,0 +1,5 @@
+---
+"@rozenite/plugin-bridge": minor
+---
+
+Introduced `createRozeniteRPCBridge` for symmetrical bi-directional RPC communication between App and DevTools. This enables type-safe, contract-first method calls across the bridge.

packages/plugin-bridge/README.md

@@ -101,3 +101,99 @@ Like the project? ⚛️ [Join the team](https://callstack.com/careers/?utm_camp
 [prs-welcome]: https://github.com/callstackincubator/rozenite/blob/main/CONTRIBUTING.md
 [chat-badge]: https://img.shields.io/discord/426714625279524876.svg?style=for-the-badge
 [chat]: https://discord.gg/xgGt7KAjxv
+
+## RPC Bridge
+
+The `createRozeniteRPCBridge` function allows you to set up a symmetrical bi-directional RPC bridge between the App and the DevTools.
+
+### Usage
+
+1. **Define Protocols**
+
+```typescript
+// Shared types
+export type AppProtocol = {
+  getAppVersion(): Promise<string>;
+  logMessage(msg: string): Promise<void>;
+};
+
+export type DevToolsProtocol = {
+  refresh(): Promise<void>;
+  showNotification(text: string): Promise<boolean>;
+};
+```
+
+2. **Initialize in App**
+
+```typescript
+import { createRozeniteRPCBridge, getRozeniteDevToolsClient } from '@rozenite/plugin-bridge';
+import { AppProtocol, DevToolsProtocol } from './protocols';
+
+async function setupAppBridge() {
+  const client = await getRozeniteDevToolsClient('my-plugin');
+
+  // Implement local handlers
+  const localHandlers: AppProtocol = {
+    async getAppVersion() {
+      return '1.0.0';
+    },
+    async logMessage(msg) {
+      console.log('App Log:', msg);
+    }
+  };
+
+  // Create Bridge
+  const devTools = createRozeniteRPCBridge<AppProtocol, DevToolsProtocol>(
+    {
+      send: (msg) => client.send('rpc', msg),
+      onMessage: (listener) => client.onMessage('rpc', listener),
+    },
+    localHandlers,
+    { timeout: 30000 } // Optional: Timeout in ms (default: 60000)
+  );
+
+  // Call remote method
+  await devTools.showNotification('App connected!');
+}
+```
+
+3. **Initialize in DevTools**
+
+```typescript
+import { useEffect } from 'react';
+import { createRozeniteRPCBridge, useRozeniteDevToolsClient } from '@rozenite/plugin-bridge';
+import { AppProtocol, DevToolsProtocol } from './protocols';
+
+function MyPlugin() {
+  const client = useRozeniteDevToolsClient({ pluginId: 'my-plugin' });
+
+  useEffect(() => {
+    if (!client) return;
+
+    const localHandlers: DevToolsProtocol = {
+      async refresh() {
+        console.log('Refreshing...');
+      },
+      async showNotification(text) {
+        alert(text);
+        return true;
+      }
+    };
+
+    const app = createRozeniteRPCBridge<DevToolsProtocol, AppProtocol>(
+      {
+        send: (msg) => client.send('rpc', msg),
+        onMessage: (listener) => client.onMessage('rpc', listener),
+      },
+      localHandlers
+    );
+
+    // Call remote method
+    app.getAppVersion().then(version => console.log('App Version:', version));
+
+  }, [client]);
+
+  return <div>My Plugin</div>;
+}
+```
+

packages/plugin-bridge/src/index.ts

@@ -4,3 +4,6 @@ export type { Subscription } from './types';
 export type { UseRozeniteDevToolsClientOptions } from './useRozeniteDevToolsClient';
 export { getRozeniteDevToolsClient } from './client';
 export { UnsupportedPlatformError } from './errors';
+export { createRozeniteRPCBridge } from './rpc';
+export type { Transport as RozeniteRPCTransport } from './rpc';
+export type { RPCBridgeOptions } from './rpc';

packages/plugin-bridge/src/rpc.test.ts

@@ -0,0 +1,187 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createRozeniteRPCBridge } from './rpc';
+import type { RozeniteRPCTransport } from './index';
+
+describe('createRozeniteRPCBridge', () => {
+  const createMockTransport = () => {
+    let listener: (message: unknown) => void = () => {
+      // Empty listener to avoid warnings
+    };
+
+    return {
+      send: vi.fn(),
+      onMessage: vi.fn((l) => {
+        listener = l;
+      }),
+      // Helper to simulate receiving a message
+      emit: (message: unknown) => listener(message),
+    };
+  };
+
+  type Local = {
+    add(a: number, b: number): Promise<number>;
+    getError(): Promise<void>;
+  };
+
+  type Remote = {
+    multiply(a: number, b: number): Promise<number>;
+  };
+
+  it('should call remote methods via proxy and receive results', async () => {
+    const transport = createMockTransport();
+    const localHandlers: Local = {
+      add: async (a, b) => a + b,
+      getError: async () => {
+        throw new Error('Local error');
+      },
+    };
+
+    const bridge = createRozeniteRPCBridge<Local, Remote>(
+      transport as unknown as RozeniteRPCTransport,
+      localHandlers
+    );
+
+    // Call remote method
+    const promise = bridge.multiply(2, 3);
+
+    // Verify request was sent
+    expect(transport.send).toHaveBeenCalledWith(
+      expect.objectContaining({
+        jsonrpc: '2.0',
+        method: 'multiply',
+        params: [2, 3],
+        id: expect.any(String),
+      })
+    );
+
+    // Simulate response
+    const lastCall = transport.send.mock.calls[0][0] as any;
+    transport.emit({
+      jsonrpc: '2.0',
+      id: lastCall.id,
+      result: 6,
+    });
+
+    const result = await promise;
+    expect(result).toBe(6);
+  });
+
+  it('should handle incoming requests and send responses', async () => {
+    const transport = createMockTransport();
+    const localHandlers: Local = {
+      add: async (a, b) => a + b,
+      getError: async () => {
+        throw new Error('Local error');
+      },
+    };
+
+    createRozeniteRPCBridge<Local, Remote>(
+      transport as unknown as RozeniteRPCTransport,
+      localHandlers
+    );
+
+    // Simulate incoming request
+    transport.emit({
+      jsonrpc: '2.0',
+      id: '123',
+      method: 'add',
+      params: [10, 20],
+    });
+
+    // Wait for promise resolution in handler
+    await vi.waitFor(() => {
+      expect(transport.send).toHaveBeenCalledWith({
+        jsonrpc: '2.0',
+        id: '123',
+        result: 30,
+      });
+    });
+  });
+
+  it('should handle errors across the bridge', async () => {
+    const transport = createMockTransport();
+    const localHandlers: Local = {
+      add: async (a, b) => a + b,
+      getError: async () => {
+        throw new Error('Remote crash');
+      },
+    };
+
+    const bridge = createRozeniteRPCBridge<Local, Remote>(
+      transport as unknown as RozeniteRPCTransport,
+      localHandlers
+    );
+
+    // Test remote error (received from other side)
+    const promise = bridge.multiply(5, 5);
+    const lastCall = transport.send.mock.calls[0][0] as any;
+
+    transport.emit({
+      jsonrpc: '2.0',
+      id: lastCall.id,
+      error: { message: 'Method failed' },
+    });
+
+    await expect(promise).rejects.toThrow('Method failed');
+
+    // Test local error (sent to other side)
+    transport.emit({
+      jsonrpc: '2.0',
+      id: '456',
+      method: 'getError',
+      params: [],
+    });
+
+    await vi.waitFor(() => {
+      expect(transport.send).toHaveBeenCalledWith(
+        expect.objectContaining({
+          jsonrpc: '2.0',
+          id: '456',
+          error: expect.objectContaining({
+            message: 'Remote crash',
+          }),
+        })
+      );
+    });
+  });
+
+  it('should ignore non-RPC messages', async () => {
+    const transport = createMockTransport();
+    const localHandlers = {
+      ping: vi.fn(),
+    };
+
+    createRozeniteRPCBridge(
+      transport as unknown as RozeniteRPCTransport,
+      localHandlers
+    );
+
+    // Send invalid message
+    transport.emit({ type: 'not-rpc', data: {} });
+
+    expect(localHandlers.ping).not.toHaveBeenCalled();
+    expect(transport.send).not.toHaveBeenCalled();
+  });
+
+  it('should timeout if no response is received', async () => {
+    const transport = createMockTransport();
+    const localHandlers = {};
+
+    vi.useFakeTimers();
+
+    const bridge = createRozeniteRPCBridge<typeof localHandlers, Remote>(
+      transport as unknown as RozeniteRPCTransport,
+      localHandlers,
+      { timeout: 1000 }
+    );
+
+    const promise = bridge.multiply(1, 2);
+
+    // Fast-forward time
+    vi.advanceTimersByTime(1001);
+
+    await expect(promise).rejects.toThrow('RPC Timeout: Request multiply timed out after 1000ms');
+
+    vi.useRealTimers();
+  });
+});