RSocket WebSocket Server

Common errors

• Error: Expected Metadata flag to be present for metadata. FrameType: PAYLOAD

  cause A client is sending a payload with metadata but the Metadata flag in the frame header is missing, possibly due to an older or misconfigured client library not compatible with the server's strict interpretation after `v0.0.29-alpha.0`.
  fix Update the RSocket client library to a version compatible with `rsocket-websocket-server@0.0.29-alpha.0` or later. Verify the client's payload builder correctly sets the Metadata flag when metadata is provided.

• Error: listen EADDRINUSE :::8080

  cause The specified port for the `RSocketWebSocketServer` (e.g., 8080) is already in use by another process on the system, preventing the RSocket server from binding to it.
  fix Change the port number in your server configuration (e.g., to `8081`) or terminate the process currently occupying the port using a tool like `lsof -i :8080` (macOS/Linux) or `netstat -ano | findstr :8080` (Windows).

• TypeError: RSocketWebSocketServer is not a constructor

  cause This typically happens when mixing CommonJS `require()` with an ESM-only or ESM-first library, or when using incorrect named/default imports. The `rsocket-js` monorepo targets modern JavaScript environments including ESM.
  fix Ensure you are using ES module imports: `import { RSocketWebSocketServer } from 'rsocket-websocket-server';` instead of `const RSocketWebSocketServer = require('rsocket-websocket-server');`. If in Node.js, ensure your `package.json` has `"type": "module"` or your file uses the `.mjs` extension for ESM imports.

Warnings

• breaking The `rsocket-js` monorepo, including `rsocket-websocket-server`, is currently in an alpha state (`0.0.29-alpha.0` for this package, broader `1.0.0-alpha.x` for the monorepo). This means APIs are subject to change without adhering to semantic versioning, and stability cannot be guaranteed for production environments. Users should anticipate frequent breaking changes.
  Fix: Carefully review release notes for each update. Pin exact alpha versions (e.g., `0.0.29-alpha.0` instead of `^0.0.29-alpha.0`) in `package.json` to prevent unexpected updates. Avoid production use until a stable `1.0.0` release.
• breaking In `v0.0.29-alpha.0`, a fix was introduced to correctly add the Metadata flag when sending stream payloads with metadata. This change might require client-side adjustments if clients were previously tolerant of or exploiting the incorrect flag state, potentially leading to misinterpretation of frames or connection issues.
  Fix: Ensure RSocket clients are up-to-date and correctly handle the presence of the Metadata flag as per the RSocket specification. Test client-server interactions thoroughly after updating.
• gotcha Since the `1.0.0-alpha.1` release (for the monorepo), a significant TypeScript migration occurred across `rsocket-js` packages. While `rsocket-websocket-server` itself might not have had direct API changes from this, interacting with other `rsocket-js` packages or custom `Responder` implementations might require strict adherence to TypeScript types, potentially revealing type errors that were previously overlooked in JavaScript.
  Fix: Ensure your project is configured for TypeScript (if applicable) and explicitly type your `Responder` implementations and payload handling. Leverage IDE type checking to catch potential issues early.
• gotcha The `v0.0.29-alpha.0` release added support for throwing errors with custom error codes. While a new feature, ensure your `Responder` implementations correctly handle and potentially throw `RSocketError` instances with appropriate codes, and that clients are prepared to receive and interpret these custom error codes for richer error feedback.
  Fix: When throwing errors from your `Responder` methods, use `new RSocketError(errorCode, message)` (import `RSocketError` from `rsocket-core`) for better client-side error handling. Update clients to parse custom `errorCode` values if needed.

Install

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

Imports

• RSocketWebSocketServer
  wrong:

  const RSocketWebSocketServer = require('rsocket-websocket-server');

  correct:

  import { RSocketWebSocketServer } from 'rsocket-websocket-server';

  Primarily used in ESM contexts; CommonJS `require` might lead to issues in modern Node.js setups due to its ESM-first design.
• RSocketServer
  wrong:

  import RSocketServer from 'rsocket-core';

  correct:

  import { RSocketServer, Payload, Responder } from 'rsocket-core';

  Core RSocket classes and interfaces, such as `RSocketServer`, `Payload`, and `Responder`, are imported from `rsocket-core`, which is a fundamental dependency for any RSocket.js application.
• Single, Flowable
  wrong:

  import { Observable, Subject } from 'rxjs';

  correct:

  import { Single, Flowable } from 'rsocket-flowable';

  The `Responder` interface, central to RSocket server logic, expects reactive types like `Single` and `Flowable` from the `rsocket-flowable` package. While `rxjs` can be used via adapters, these are the direct types for the API.

Quickstart

This quickstart demonstrates how to set up and run an RSocket WebSocket server, handling fire-and-forget, request-response, request-stream, and request-channel interactions using the `rsocket-flowable` reactive types.

import { RSocketServer, Payload, Responder } from 'rsocket-core';
import { RSocketWebSocketServer } from 'rsocket-websocket-server';
import { Flowable, Single } from 'rsocket-flowable';

const port = process.env.PORT ?? 8080;

class MyResponder implements Responder {
  fireAndForget(payload: Payload): void {
    console.log(`Received fire and forget: ${payload.data?.toString()}`);
  }

  requestResponse(payload: Payload): Single<Payload> {
    console.log(`Received request-response: ${payload.data?.toString()}`);
    return Single.of({
      data: Buffer.from(`Response to ${payload.data?.toString()}`),
      metadata: payload.metadata,
    });
  }

  requestStream(payload: Payload): Flowable<Payload> {
    console.log(`Received request-stream: ${payload.data?.toString()}`);
    return Flowable.just(
      { data: Buffer.from('Stream Item 1') },
      { data: Buffer.from('Stream Item 2') },
      { data: Buffer.from('Stream Item 3') }
    ).delayElements(500); // Simulate some delay
  }

  requestChannel(payloads: Flowable<Payload>): Flowable<Payload> {
    console.log(`Received request-channel setup payload:`);
    return payloads.map(p => {
      console.log(`Channel data: ${p.data?.toString()}`);
      return {
        data: Buffer.from(`Echo: ${p.data?.toString()}`),
        metadata: p.metadata,
      };
    });
  }
}

const server = new RSocketServer({
  transport: new RSocketWebSocketServer({ port }),
  responder: new MyResponder(),
});

server.start().then(() => {
  console.log(`RSocket WebSocket Server started on port ${port}`);
  console.log('Use Ctrl+C to stop');
}).catch(error => {
  console.error('Server failed to start:', error);
});

process.on('SIGINT', () => {
  server.shutdown().then(() => {
    console.log('Server gracefully shut down.');
    process.exit(0);
  }).catch(error => {
    console.error('Error during server shutdown:', error);
    process.exit(1);
  });
});