Skip to main content

Relay Client

Purpose​

This document aims to define a set of rules that RelayClient should perform when publishing a message.

Rules​

Rules define the default behaviors that RelayClient must respect when publishing every message.

  • Publishing retrials - given that a message publish fails. RelayClient must make three retries before throwing an error to its consumer.
  • Error handling - given that a message publish fails. After making three retries, RelayClient must throw an error with a descriptive message to its consumer.
  • Offline support - given that RelayClient detects no Internet availability or web-socket connection. After making three retries, RelayClient must throw an error with a descriptive message to its consumer.

Server-Client Extended RPC ID​

When communicating with the server using publish, subscribe, or unsubscribe, Json RPC Ids should have 19 characters of entropy to avoid collisions.

The same function that is used to generate an ID for client-client communication can be used to generate an ID for client-server communication, it just needs to accept an override for the number of characters of entropy.

export function payloadId(entropy = 3): number {
  const date = Date.now() * Math.pow(10, entropy);
  const extra = Math.floor(Math.random() * Math.pow(10, entropy));
  return date + extra;
}

Instead of 3, the server should use a payloadId with an entropy set to 6.

API​

The Relay Client API defines a public interface with set of supported methods. It is consumed by an instance of SDK, where it allows to publish a message on a topic and subscribe or unsubscribe the given topic.

interface Relay {

    /*Publishes a message over the network on given topic*/
    fun publish(topic: String, message: String, policy: Policy)

    /*Subscribes on topic to receive messages*/
    fun subscribe(topic: String)

    /*Unsubscribes from a topic*/
    fun unsubscribe(topic: String, subscriptionId: String)

    /*Opens a Web-Socket connection*/
    fun connect()

    /*Closes a Web-Socket connection*/
    fun disconnect()
    
    /*Listening for new incoming messages*/
    fun on("relay_message", (topic: string, message: string, publishedAt: Int64, receivedAt: Int64) => {})
}

Policy​

The policy object defines the policy's parameters.

{
    "ttl" : seconds,
    "tag" : number, // Optional / default = 0
}

Message Id​

A Relay message is globally available and it's always a utf8 string. Therefore the message id is derived as the sha256 hash.

message_id = sha256(message)

FAQ​

  • What is a RelayClient? - an instance of Relay on the client-side used by any sdk instance.