A high-performance TypeScript implementation of RSocket

Hi everyone,

I would like to share rsocket-ts, a high-performance, browser-ready implementation of RSocket 1.0 for TypeScript:

https://github.com/CKATEPTb/rsocket-ts

The project started as an alternative browser requester, but has since evolved into a modular RSocket stack covering frames, shared protocol mechanics, clients, servers, TCP, WebSocket, and browser-specific connection recovery.

It is not intended to diminish the work done in rsocket-js. The goal is to provide another implementation designed around modern TypeScript, Web Platform APIs, a small public API, and reactive programming.

Packages

The repository contains five independently published packages:

• rsocket-browser: browser-first WebSocket requester with reconnect and browser wake handling;
• rsocket-client-ts: requester for WebSocket and Node TCP;
• rsocket-server-ts: responder for WebSocket and Node TCP;
• rsocket-core-ts: shared protocol, transport, fragmentation, Resume, and backpressure mechanics;
• rsocket-frames-ts: RSocket frame, MIME type, metadata, authentication, and binary codecs.

For a browser application:

npm install rsocket-browser

For a Node.js requester supporting WebSocket and TCP:

npm install rsocket-client-ts

For a TypeScript RSocket server:

npm install rsocket-server-ts

All required lower-level packages are installed automatically.

TypeScript-first design

The implementation is written in TypeScript and publishes generated declarations.

Types are propagated through:

• SETUP data and metadata MIME codecs;
• interaction payloads;
• request and response controllers;
• per-request MIME overrides;
• routing and composite metadata;
• request context on the server.

The public API intentionally exposes only the classes and types required by application code. Internal sessions, transports, dispatchers, and protocol state remain private.

Browser-ready binary implementation

The protocol implementation uses Uint8Array, ArrayBuffer, Blob, and other standard JavaScript APIs instead of Node.js Buffer.

This means browser applications do not need Buffer polyfills, while the same binary implementation can also be used by Node.js TCP and WebSocket transports.

All packages are ESM-only, side-effect free where applicable, and licensed under MIT.

Client and server support

The requester and responder implement all four primary RSocket interaction models:

• fire-and-forget;
• request-response;
• request-stream;
• request-channel.

Request-stream and request-channel follow Reactive Streams demand and cancellation semantics.

The requester sends REQUEST_N only when the subscriber requests data. Request-channel applies backpressure independently in both directions, so outbound items are sent only after the responder grants demand.

Reactor-style API

Requester operations return Mono or Flux values from reactor-core-ts.

Operations are lazy and begin only when subscribed, awaited through block(), or consumed with for await...of.

import {RSocket} from "rsocket-browser";
import {WellKnownMimeType} from "rsocket-frames-ts";

const route = (name: string) =>
  WellKnownMimeType.MESSAGE_RSOCKET_ROUTING.toMetadata([name]);

const socket = new RSocket("wss://api.example.com/rsocket", {
  setup: {
    keepAlive: 20_000,
    lifetime: 90_000,
    fragmentSize: 16 * 1024,
    mimetype: {
      data: WellKnownMimeType.APPLICATION_JSON,
      metadata: WellKnownMimeType.MESSAGE_RSOCKET_COMPOSITE_METADATA
    }
  }
});

const connected = await socket.connect().block();
if (!connected) throw new Error("RSocket connection did not open");

const response = await socket
  .requestResponse({id: 42}, route("account.find"))
  .block();

console.log(response?.data);
connected.disconnect();

Typed metadata and authentication

Metadata is created through protocol MIME codecs instead of manually assembled strings or byte buffers.

The implementation supports:

• routing metadata;
• composite metadata;
• simple authentication;
• bearer authentication;
• persistent request metadata;
• per-request metadata overrides;
• METADATA_PUSH.

For example, persistent bearer authentication can be added and removed without affecting request routing:

import {
  WellKnownAuthType,
  WellKnownMimeType
} from "rsocket-frames-ts";

const authMime = WellKnownMimeType.MESSAGE_RSOCKET_AUTHENTICATION;

socket.metadataUpdate((metadata) => {
  metadata.set(
    authMime,
    WellKnownAuthType.BEARER.auth("access-token")
  );
});

socket.metadataUpdate((metadata) => {
  metadata.remove(authMime);
});

When composite metadata is used, persistent authentication and request-specific routing are merged by MIME type.

Declarative client controllers

Routes can be represented as typed controller classes:

import {RequestResponseController} from "rsocket-browser";

interface SignInRequest {
  login: string;
  password: string;
}

interface TokenResponse {
  token: string;
}

class SignInController extends RequestResponseController<
  SignInRequest,
  TokenResponse
> {
  protected readonly route = "account.sign-in";
}

const token = await socket
  .process(SignInController, {
    login: "user@example.com",
    password: "secret"
  })
  .map((response) => response.token)
  .block();

Equivalent controller classes are available for fire-and-forget, request-stream, and request-channel.

Declarative TypeScript server

rsocket-server-ts provides the same controller-oriented approach for responders:

import {
  RequestResponseController,
  RSocketServer
} from "rsocket-server-ts";

class FindAccountController extends RequestResponseController<
  {id: number},
  {id: number; name: string}
> {
  protected readonly route = "account.find";

  override handle(request: {id: number}) {
    return {
      id: request.id,
      name: "Ada"
    };
  }
}

const server = new RSocketServer({
  controllers: [FindAccountController],
  resume: {
    ttlMs: 5 * 60_000
  }
});

const listener = await server.listenTcp({
  host: "127.0.0.1",
  port: 7000
}).block();

For WebSocket servers, sockets accepted by an HTTP or WebSocket framework can be passed directly to server.acceptWebSocket(...).

Protocol features

The client and server include:

• RSocket 1.0 frame validation;
• TCP and WebSocket transports;
• keepalive and lifetime enforcement;
• Reactive Streams backpressure;
• request cancellation;
• configurable fragmentation and transparent reassembly;
• Resume tokens and byte-position tracking;
• replay of unacknowledged frames;
• Resume rejection and fresh SETUP fallback;
• lease support;
• metadata push;
• stream-scoped and connection-scoped errors;
• frame and lifecycle logging.

The browser package additionally reacts to online, focus, visibility, page restore, and mobile sleep/wake signals when reconnecting.

Testing

Each package has an independent test suite.

The repository tests:

• every interaction model;
• TCP and WebSocket transports separately;
• browser-to-server communication;
• backpressure in both directions;
• fragmentation and reassembly;
• Resume and replay positions;
• keepalive and lifetime behavior;
• metadata and routing;
• protocol errors and cancellation;
• resource cleanup and retained state;
• package architecture and public API boundaries.

The requester and responder are tested against each other over real transport adapters rather than relying on Java or Spring test servers.

Feedback, interoperability reports, performance results, and protocol-level review are welcome.