Shellfish

Class: RpcSession

server.RpcSession

Class representing a session for handling remote procedure calls (RPC) to use with core.RpcProxy as the client-side counter part.

The RPC session runs on a server.HTTPServer and uses the server's SSL encryption, if available. The server.HTTPRoute may assign an authentication method to the RPC session as well.

Use the route's generateSessionId property to make sure that a client that opened a RPC connection will get the same connection on all its RPC calls.

RPC requests have the HTTP header x-shellfish-rpc-session set with the session ID, except for the initial connection. This header may be used to open a session per client.

Parameters of type Uint8Array are transfered in binary form.

Details of the RPC Protocol

This section describes the underlying RPC protocol. Understanding the protocol is not required for using the core.RpcProxy or server.RpcSession.

Communication

The communication between client and server (endpoint) runs over HTTP or HTTPS with a reverse channel for receiving asynchronous messages from the server.

Initially, the client sends a GET request to the endpoint in order to retrieve the reverse channel. From then on, the client sends messages to the endpoint via POST messages, while the server sends messages to the client via the reverse channel.

Message Data

Messages consist of a JSON document describing the type of message along with type-specific properties, and an optional chunk of binary data.

The binary chunk is used when transfering parameters in binary form.

A message looks like this:

  • JSON_SIZE - 32 bits: The size of the JSON document in bytes.
  • BINARY_SIZE - 32 bits: The size of the binary chunk in bytes.
  • JSON: The JSON document. This is the message body.
  • BINARIES: The chunk of binary data. This is a concatenation of the binary parameters in the message.

For messages without binary parts, the BINARIES chunk is of size 0.

Initiating the Connection

In order to initiate a connection and retrieve the reverse channel, the client sends a GET request to the endpoint. The server's response will be an unlimited data stream with ContentType: application/x-shellfish-rpc, over which incoming messages will arrive. This is the reverse channel.

Upon successful connection, the server sends a ready message to the client along with a unique clientId and sessionId, e.g.

{ type: "ready", clientId: "7b12a3-a2ce36-598a73", sessionId: "2683a9-453d46-58df44" }

All RPC POST messages sent from the client to the endpoint are expected to have the x-shellfish-rpc-session HTTP header set with the session ID received above. This allows the server to route the message to the corresponding RPCSession instance.

Message Types

heartbeat

At intervals (every 30 seconds) the server will send a heartbeat message to clients that haven't recently sent any messages

{ type: "heartbeat" }

and expects to receive a response heartbeat message.

{ type: "heartbeat", clientId: "7b12a3-a2ce36-598a73" }

If a client does not respond to the heartbeat request in time, the server will close the connection and destroy any context it may have associated with it.

exit

The client may send an exit message to the server in order to close a connection immediately.

{ type: "exit", clientId: "7b12a3-a2ce36-598a73" }

call

The client sends a call message to the server in order to invoke a remote procedure by name.

{ type: "call", clientId: "7b12a3-a2ce36-598a73", name: "foo", callId: 42, parameters }

The property callId is an ID by which the client associates result and error messages with this particular remote call.

The property name is the name of the remote procedure to invoke.

The property parameters is a list of parameter items (see below) passed to the remote procedure.

result

When a remote procedure is finished, the server sends a result message with the result value to the client.

{ type: "result", callId: 42, value: "This is the result" }

The value property contains a single parameter item with the return value.

error

If a remote procedure fails, the server sends an error message to the client.

{ type: "error", callId: 42, value: "Some error occured." }

The value property contains the error message string.

callback

Callbacks invoked by the server asynchronously are sent by the callback message.

{ type: "callback", callbackId: 11, parameters }

The callbackId property contains the ID of the callback which is recognized by the client.

The parameters property contains a list of parameter items.

Parameter Items

There are four types of parameters: callbacks, proxy objects, binary data, and JSON-serializable data.

JSON-serializable data is passed as is.

Binary data is passed as binary items:

{ type: "binary", size: 32768 }

The property size is the size of this particular parameter value in bytes within the BINARIES chunk of the message.

Callbacks are passed as callback items:

{ type: "callback", clientId: "7b12a3-a2ce36-598a73", callbackId: 11 }

The property callback is an ID recognized by the client and is associated with a function stored on the client side.

Proxy objects may only be passed from the server to the client. A proxy object item looks like

{ type: "proxy", instanceId: 99, methods: ["foo", "bar"] }

The property instanceId is an ID recognized by the server and is associated with the instance of the actual object.

The property methods is a list of available method names that may be called via the call message by appending to the instanceId ID, e.g.

{ type: "call", clientId: "7b12a3-a2ce36-598a73", name: "99.foo", callId: 43, parameters: ["data"] }

new server.RpcSession ()

rpcsession.js:328

Extends

Methods

proxyObject (obj, exposedMethods)object

rpcsession.js:638

Creates a RPC proxy object of the given object, which can then be passed to the RPC client.

The proxy object is destroyed when the connection to the client closes. In order to destroy it earlier, it exposes the special method destroy() to the client.

Example

class MyClass
{
    constructor(initial)
    {
        this.value = initial;
    }

    add(n) { this.value += n; }

    value() { return this.value; }
}

registerMethod("getMyClass", (initial) =>
{
    return proxyObject(new MyClass(initial));
});
Name Type Description
obj object

The object for which to create the proxy.
exposedMethods Array.<string>

An optional list of the methods to expose. If this parameter is not used, all methods will be exposed.
Returns:
Type Description
object The RPC proxy object.

registerMethod (name, f)

rpcsession.js:601

Registers a function as RPC method.

Example

registerMethod("sum", (a, b) => a + b);

registerMethod("countDown", cb =>
{
    for (let i = 10; i > 0; --i)
    {
        cb(i);
    }
});
Name Type Description
name string

The name of the method.
f function

The method's implementation.