RSocketClient - rsocket-js

note

This guide pertains to rsocket-js 0.x versions. Ensure that your version of rsocket- packages are not 1.0.0-alpha before following this guide.

An rsocket-js client can be used to communicate with any RSocket Server implemented against the same protocol version as the client, and which implements the same transport as the client.

Available transports for rsocket-js include:

• rsocket-tcp-client
• rsocket-websocket-client

The RSocketClient class is exported from the rsocket-core NPM package, and should be passed an instance of one of the available transports.

To get started creating an RSocket client, you will first need to install the rsocket-core NPM package, and atleast one transport protocol implementation. See the WebSocket client example below.

WebSocket Client Quick Start Example

npm install rsocket-core rsocket-websocket-client

import { RSocketClient } from 'rsocket-core';
import RSocketWebsocketClient from 'rsocket-websocket-client';

async function createClient(options) {
  const client = new RSocketClient({
    setup: {
      dataMimeType: 'text/plain',
      keepAlive: 1000000, // avoid sending during test
      lifetime: 100000,
      metadataMimeType: 'text/plain',
    },
    transport: new RSocketWebsocketClient({
      host: options.host,
      port: options.port,
    }),
  });

  return client.connect();
}

async function run() {
  const rsocket = await createClient({
    host: '127.0.0.1',
    port: 9898,
  });

  ...
}

await run();

Client API

The rsocket-core package exposes the the following types:

RSocketClient (class)

RSocketClient is used to create an instance of a client. The clients connection does not initialize until the connect method is invoked.

constructor (function)

// @flow

class RSocketClient {
  constructor(options: Options)
}

type Options = {
  serializers?: {
    data: Serializer
    metadata: Serializer,
  },
  setup: {
    keepAlive: number,
    lifetime: number,
    dataMimeType: string,
    metadataMimeType: string,
  },
  transport: TransportClient,
};

type Serializer<T> = {
  deserialize: (data: ?Encodable) => ?T,
  serialize: (data: ?T) => ?Encodable,
}

type Encodable = string | Buffer | UInt8Array;

type TransportClient = {
  connect: Single<DuplexConnection>,
}

serializers (property)

By default the data and metadata of each payload are passed through to the transport layer as-is. This is appropriate for sending/receiving strings/binary. To send/receive JSON instead, pass serializers: JsonSerializers (imported from rsocket-core).

transport (property)

This will typically be an instance of rsocket-tcp-client or rsocket-websocket-client, though any value conforming to the TransportClient protocol is allowed.

connect() (method)

This method opens the connection to the peer. Internally this calls connect() on the transport client. See below for the RSocket interface.

class RSocketClient {
  ⋮
  connect(): Single<RSocket>
}

RSocket (interface)

This interface represents an instance of a rsocket peer-to-peer connection, providing the five core interactions (fire/forget, request/reponse, etc.):

fireAndForget() (method)

This method sends data/metadata to the server without waiting for a response. The data is sent immediately.

fireAndForget(payload: Payload): void

requestResponse() (method)

This method sends data/metadata to the server, which returns a single response. The data is sent lazily when the returned Single is subscribed to.

requestResponse(payload: Payload): Single<Payload>

requestStream() (method)

This method sends data/metadata to the server, which returns a stream of responses. The semantics of the stream are application-specific. For example, the stream may represent updates to a single conceptual value over time, items in an incrementally loaded list, events, etc. The data is sent to the peer lazily when the returned Flowable is subscribed to and request(n) is called to signal demand.

requestStream(payload: Payload): Flowable<Payload>

requestChannel() (method)

This method establishes an understanding between a client and a server where each intends to send and receive streams of data from the other. Each actor in this relationship is responsible for signaling to the other that they are ready to receive data by invoking request(n), where n is the max number of payloads the actor is comfortable handling. Conceptually, requestChannel can be thought of as two entities 'polling' from each other by signaling to the others that they are ready to accept n number of messages. Inversely, requestChannel can be leveraged to facilitate a consistent stream of data transfer payloads between client and server by each (or either) invoking request(0x7fffffff), where 0x7fffffff is the max integer value for int32.

requestChannel(payload: Flowable<Payload>): Flowable<Payload>

metadataPush() (method)

This method sends metadata only to the server without waiting for a response. The payload is sent immediately. This method is not for the direct application usage and should be used to exchange some service level information

metadataPush(payload: Payload): Single<Payload>