{"id":11964,"library":"rsocket-websocket-server","title":"RSocket WebSocket Server","description":"rsocket-websocket-server provides a robust implementation of an RSocket server that operates over the WebSocket protocol, enabling reactive, multiplexed, and message-driven communication between applications. As part of the rsocket-js monorepo, it integrates seamlessly with other RSocket.js components like rsocket-core for protocol handling and various adapters. Currently, the package is in an alpha state, with 0.0.29-alpha.0 being its latest version, indicating ongoing development and pre-production readiness. The release cadence is tied to the broader rsocket-js monorepo development, which saw a significant TypeScript migration in 1.0.0-alpha.1 across its packages. Its key differentiator is offering a full RSocket server implementation specifically for WebSocket connections, adhering to the RSocket specification for high-performance, resilient, and responsive microservices and real-time applications.","status":"active","version":"0.0.29-alpha.0","language":"javascript","source_language":"en","source_url":"https://github.com/rsocket/rsocket-js","tags":["javascript"],"install":[{"cmd":"npm install rsocket-websocket-server","lang":"bash","label":"npm"},{"cmd":"yarn add rsocket-websocket-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add rsocket-websocket-server","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primarily used in ESM contexts; CommonJS `require` might lead to issues in modern Node.js setups due to its ESM-first design.","wrong":"const RSocketWebSocketServer = require('rsocket-websocket-server');","symbol":"RSocketWebSocketServer","correct":"import { RSocketWebSocketServer } from 'rsocket-websocket-server';"},{"note":"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.","wrong":"import RSocketServer from 'rsocket-core';","symbol":"RSocketServer","correct":"import { RSocketServer, Payload, Responder } from 'rsocket-core';"},{"note":"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.","wrong":"import { Observable, Subject } from 'rxjs';","symbol":"Single, Flowable","correct":"import { Single, Flowable } from 'rsocket-flowable';"}],"quickstart":{"code":"import { RSocketServer, Payload, Responder } from 'rsocket-core';\nimport { RSocketWebSocketServer } from 'rsocket-websocket-server';\nimport { Flowable, Single } from 'rsocket-flowable';\n\nconst port = process.env.PORT ?? 8080;\n\nclass MyResponder implements Responder {\n  fireAndForget(payload: Payload): void {\n    console.log(`Received fire and forget: ${payload.data?.toString()}`);\n  }\n\n  requestResponse(payload: Payload): Single<Payload> {\n    console.log(`Received request-response: ${payload.data?.toString()}`);\n    return Single.of({\n      data: Buffer.from(`Response to ${payload.data?.toString()}`),\n      metadata: payload.metadata,\n    });\n  }\n\n  requestStream(payload: Payload): Flowable<Payload> {\n    console.log(`Received request-stream: ${payload.data?.toString()}`);\n    return Flowable.just(\n      { data: Buffer.from('Stream Item 1') },\n      { data: Buffer.from('Stream Item 2') },\n      { data: Buffer.from('Stream Item 3') }\n    ).delayElements(500); // Simulate some delay\n  }\n\n  requestChannel(payloads: Flowable<Payload>): Flowable<Payload> {\n    console.log(`Received request-channel setup payload:`);\n    return payloads.map(p => {\n      console.log(`Channel data: ${p.data?.toString()}`);\n      return {\n        data: Buffer.from(`Echo: ${p.data?.toString()}`),\n        metadata: p.metadata,\n      };\n    });\n  }\n}\n\nconst server = new RSocketServer({\n  transport: new RSocketWebSocketServer({ port }),\n  responder: new MyResponder(),\n});\n\nserver.start().then(() => {\n  console.log(`RSocket WebSocket Server started on port ${port}`);\n  console.log('Use Ctrl+C to stop');\n}).catch(error => {\n  console.error('Server failed to start:', error);\n});\n\nprocess.on('SIGINT', () => {\n  server.shutdown().then(() => {\n    console.log('Server gracefully shut down.');\n    process.exit(0);\n  }).catch(error => {\n    console.error('Error during server shutdown:', error);\n    process.exit(1);\n  });\n});","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.0.1-alpha.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.0.29-alpha.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0-alpha.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.29-alpha.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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`.","error":"Error: Expected Metadata flag to be present for metadata. FrameType: PAYLOAD"},{"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).","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.","error":"Error: listen EADDRINUSE :::8080"},{"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.","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.","error":"TypeError: RSocketWebSocketServer is not a constructor"}],"ecosystem":"npm"}