Skip to content

Latest commit

 

History

History
145 lines (101 loc) · 9.29 KB

api.md

File metadata and controls

145 lines (101 loc) · 9.29 KB
Raw

API

BlueRPC.listen(options)

  • options <Object>
    • server <http.Server> an HTTP or HTTPS server instance to attach to.
    • methods <Object> A map of RPC-style methods to serve.
    • maxPayload <number> The maximum accepted size of incoming WebSocket messages (in bytes). Default: 1048576 (1 MiB). Note that byte streams are not affected by this, as they automatically break large payloads into many smaller messages.
    • perMessageDeflate <Object> | <boolean> Passed to the underlying WebSocketServer to configure automatic compression. Default: Compresses messages at least 8192 bytes (8 KiB) in size.
    • verifyClient <Function> Passed to the underlying WebSocketServer to reject incoming connections. Default: null.
    • logger <Function> If provided, auto-generated server logs will be passed to this function, for convenience. Default: null.
    • Any option allowed in server.listen().
  • Returns: <Promise<WebSocketServer>>

Creates and starts a WebSocketServer that uses BlueRPC to serve the given methods. By default, port 80 is used for http.Servers and port 443 is used for https.Servers, but you can pass any custom port you like.

The returned promise will not resolve until the server is ready to accept connections.

All method handlers will receive a MethodContext as their second parameter, which exposes metadata about the invocation. Also, if the client sends a stream, but the method handler returns without using it, the stream will automatically be cleaned up, so you don't have to worry about resource management.

Configuring perMessageDeflate

Although compression can greatly reduce bandwidth usage, it also has real CPU and memory costs. Usually these costs don't become a bottleneck unless you are processing thousands of messages per second (on a typical workstation in 2023). Usually, if you are processing that many messages per second, each message is so small that bandwidth is not even an issue. This is the rationale that led to the current default setting, which only compresses messages at least 8 KiB in size. It is a compromise that tries to minimize CPU and memory costs while still using compression in cases where you are likely to benefit from it.

However, if you are sending a large number of small messages (below 8 KiB) and you want to hyper-optimize for low bandwidth usage (at the cost of higher CPU and memory consumpton), you can use the following perMessageDeflate settings:

const perMessageDeflate = {
	serverNoContextTakeover: false,
	clientNoContextTakeover: false,
	concurrencyLimit: 10,
};

BlueRPC.createClient(url[, options])

  • url <string> The URL of the BlueRPC server to connect to.
  • options <Object>
    • maxPayload <number> The maximum accepted size of incoming WebSocket messages (in bytes). Default: 1048576 (1 MiB). Note that byte streams are not affected by this, as they automatically break large payloads into many smaller messages.
    • perMessageDeflate <Object> | <boolean> Passed to the underlying WebSocket to configure automatic message compression. Default: Compresses messages at least 8192 bytes (8 KiB) in size.
    • Any option allowed in http.request() or https.request().
  • Returns: <BlueClient>

Creates a BlueRPC client that connects to the specified server.

In the browser, all options are ignored.

class BlueClient

This class represents a BlueRPC client. It allows you to invoke methods on a remote BlueRPC server.

client.invoke(methodName, param[, abortSignal])

  • methodName <string> The name of the remote method to invoke.
  • param <any> The value to send to the remote method.
  • abortSignal <AbortSignal> A signal that can be used to cancel the RPC call. Default: null.
  • Returns: <Promise<any>>

Invokes a method on the remote server and returns a Promise that will resolve with the method's result. If the method throws an exception, the promise will be rejected with the error.

If you pass an AbortSignal, you'll be able to cancel the RPC call. If you cancel an RPC call, the streams you sent will automatically be destroyed, and the promise will be rejected with an AbortError.

client.notify(methodName, param)

This is the same as client.invoke() except that it returns nothing and it cannot be aborted. In BlueRPC, notifications are a way of invoking remote methods without needing a response. The returned promise resolves as soon as the notification is successfully sent.

client.cancel()

Closes all open WebSocket connections, cancelling any RPC calls or streams that were in progress. You may continue using the client normally after calling this.

class MethodContext

context.signal

Read-only property communicating whether this RPC method was aborted by the client. Note that the client can abort calls explicitly but they will also be aborted automatically if the WebSocket connection closes.

context.isAborted

Alias for context.signal.aborted.

context.isNotification

Read-only property indicating whether this RPC method was invoked as a notification.

context.connection

  • <Object>
    • tls <boolean> Whether this RPC method was invoked over a TLS connection.
    • headers <Object> The headers that were sent by the client in the WebSocket opening handshake.

An object containing info about the underlying connection. This object is shared among all RPC calls on the same connection, so you can use it as a place to store your own "session data".

class KnownError

This class represents a known/expected failure condition. KnownError can be used to attach custom properties to an error thrown by a BlueRPC method handler. On other types of errors, all properties except message are normally stripped for security reasons.