RSocket WebSocket Client for Browsers

Common errors

• TypeError: Buffer is not defined

  cause Attempting to use `Buffer.from` or other `Buffer` methods in a browser environment without a polyfill.
  fix If using Webpack 5, add `resolve: { fallback: { 'buffer': require.resolve('buffer/') } }` to your `webpack.config.js`. Alternatively, explicitly use `new TextEncoder().encode(JSON.stringify(data))` for outgoing data and `new TextDecoder().decode(payload.data)` for incoming `Uint8Array`.

• Failed to connect or interact with RSocket server: Error: RSocket: Connection error.

  cause Generic RSocket connection failure, often due to server not running, incorrect URL, firewall, or protocol mismatch during handshake.
  fix Verify the RSocket server is running and accessible at the specified URL (`ws://localhost:7000/rsocket`). Check server logs for handshake errors and ensure `dataMimeType` and `metadataMimeType` are correctly configured on both client and server.

• TypeError: client.connect is not a function

  cause The `client` variable was not properly initialized as an instance of `RSocketClient` or was imported incorrectly.
  fix Ensure `client` is instantiated with `const client = new RSocketClient({...});` and `RSocketClient` is correctly imported as a named export from `rsocket-core`.

• TypeError: rsocket.requestResponse(...).toPromise is not a function

  cause `toPromise()` is a method of `Flowable` (from `rsocket-flowable`), and `requestResponse` returns a `Flowable` which might need explicit conversion or `rsocket-flowable` might not be imported.
  fix Ensure `import { Flowable } from 'rsocket-flowable';` is present and wrap the `requestResponse` call: `await Flowable.from(rsocket.requestResponse(payload)).first().toPromise();`

Warnings

• breaking This package is currently in an alpha development phase (v0.0.29-alpha.0). The API is subject to frequent, significant, and breaking changes without prior notice. It is not recommended for production environments where API stability is critical.
  Fix: Monitor the `rsocket-js` monorepo's releases and changelogs for updates. Pin exact versions in `package.json` to prevent unexpected breaking changes.
• gotcha In browser environments, the `Buffer` global is not natively available. While `rsocket-js` often uses `Buffer` internally, payload data handling might require polyfills or explicit usage of `Uint8Array` with `TextEncoder`/`TextDecoder` for maximum compatibility.
  Fix: Ensure your build setup includes a `Buffer` polyfill (e.g., in Webpack 5 config) or explicitly convert your payload data to `Uint8Array` before passing it to RSocket methods and convert `Uint8Array` responses back to string/object.
• gotcha Mismatched `dataMimeType` or `metadataMimeType` between client and server can lead to communication failures or malformed payloads, as RSocket relies on these for proper serialization/deserialization.
  Fix: Carefully configure `dataMimeType` and `metadataMimeType` in the `RSocketClient` setup options to match the server's expectations. Common values include 'application/json', 'text/plain', 'message/x.rsocket.routing.v0', or 'message/x.rsocket.composite-metadata.v0'.
• gotcha The `RSocketWebSocketClient` requires a `wsCreator` function when used in a browser environment to provide the correct `WebSocket` constructor, as Node.js's global `WebSocket` is not available.
  Fix: When initializing `RSocketWebSocketClient`, pass an object `{ url: 'ws://your-server', wsCreator: (url) => new WebSocket(url) }` to ensure the client can instantiate the browser's native WebSocket.
• gotcha RSocket interactions like `requestResponse` and `requestStream` return `Flowable` instances from `rsocket-flowable`. Incorrectly handling these reactive streams (e.g., forgetting to `subscribe` or `toPromise()`) will result in no data being exchanged.
  Fix: Always call `.subscribe()` on `Flowable` instances for stream interactions, or use `.first().toPromise()` (if expecting a single result) for request-response patterns, ensuring you handle `onNext`, `onError`, and `onComplete` callbacks.

Install

• npm install rsocket-websocket-client npm
• yarn add rsocket-websocket-client yarn
• pnpm add rsocket-websocket-client pnpm

Imports

• RSocketWebSocketClient
  wrong:

  const RSocketWebSocketClient = require('rsocket-websocket-client');

  correct:

  import { RSocketWebSocketClient } from 'rsocket-websocket-client';

  This package primarily uses ESM. CommonJS `require` may lead to issues or require specific build configurations, especially for browser consumption.
• RSocketClient
  wrong:

  import RSocketClient from 'rsocket-core';

  correct:

  import { RSocketClient } from 'rsocket-core';

  RSocketClient is a named export from `rsocket-core`, not a default export.
• BufferEncoders
  wrong:

  const { BufferEncoders } = require('rsocket-core');

  correct:

  import { BufferEncoders } from 'rsocket-core';

  Used for serialization within the RSocketClient. Correct import is a named export from `rsocket-core`.
• Flowable
  wrong:

  import { Flowable } from 'rsocket-core';

  correct:

  import { Flowable } from 'rsocket-flowable';

  The reactive streams `Flowable` class is provided by `rsocket-flowable`, not directly by `rsocket-core`.

Quickstart

Demonstrates connecting an RSocket client via WebSocket, performing a Request-Response interaction, and subscribing to a Request-Stream, including proper connection setup and teardown for a browser environment.

import { RSocketClient, BufferEncoders, RSocketConnection, Payload } from 'rsocket-core';
import { RSocketWebSocketClient } from 'rsocket-websocket-client';
import { Flowable } from 'rsocket-flowable';

// For browser environments, Buffer might not be globally available.
// Use TextEncoder/TextDecoder for explicit Uint8Array handling, or rely on build tool polyfills.
// This example uses Buffer.from for simplicity, which works well in Node.js or with polyfills.

async function connectAndInteract() {
  const client = new RSocketClient({
    serializers: BufferEncoders,
    setup: {
      keepAlive: 60000, // Milliseconds
      lifetime: 180000, // Milliseconds
      dataMimeType: 'application/json',
      metadataMimeType: 'message/x.rsocket.routing.v0', // Or 'message/x.rsocket.composite-metadata.v0'
    },
    transport: new RSocketWebSocketClient({
      url: 'ws://localhost:7000/rsocket', // Replace with your RSocket server's WebSocket URL
      // For browser environments, explicitly provide a WebSocket constructor:
      wsCreator: (url) => new WebSocket(url),
    }),
  });

  let rsocket: RSocketConnection | null = null;
  try {
    rsocket = await client.connect();
    console.log('RSocket client connected successfully.');

    // --- Request-Response interaction ---
    console.log('\nSending Request-Response...');
    const rrPayload: Payload = {
      data: Buffer.from(JSON.stringify({ request: 'greeting' })),
      metadata: Buffer.from('hello.world'), // Simple routing key
    };
    const rrResult = await Flowable.from<Payload>(rsocket.requestResponse(rrPayload)).first().toPromise();
    console.log('Request-Response received:', rrResult.data?.toString());

    // --- Request-Stream interaction ---
    console.log('\nSending Request-Stream...');
    const rsPayload: Payload = {
      data: Buffer.from(JSON.stringify({ count: 3 })),
      metadata: Buffer.from('stream.data'), // Simple routing key
    };
    rsocket.requestStream(rsPayload).subscribe({
      onComplete: () => console.log('Request-Stream completed.'),
      onError: (error) => console.error('Request-Stream error:', error),
      onNext: (payload) => console.log('Request-Stream data:', payload.data?.toString()),
      onSubscribe: (subscription) => subscription.request(Infinity), // Request all available items
    });

    // Keep the connection open for a few seconds to receive stream data
    await new Promise(resolve => setTimeout(resolve, 5000));

  } catch (error) {
    console.error('Failed to connect or interact with RSocket server:', error);
  } finally {
    if (rsocket) {
      client.close();
      console.log('RSocket client disconnected.');
    }
  }
}

connectAndInteract();