Leap & Leap Edge

Leap, internally, is the service that we’ve created to facilitate our global realtime network. Leap Edge is a service that runs on all our edge PoPs that exposes a client-facing socket service used for connecting client applications to Hop services through Channels.

​

Leap Edge Socket

The LE (Leap Edge) socket allows clients & SDKs to connect to the following Hop realtime services:

• Pipe
• Channels

​

Protocol

LE 1.0 currently only supports connections via WebSocket, which is accessible globally via wss://leap.hop.io/ws. The IP address behind the hostname is announced by the Hop anycast network, so you should be connected to the closest PoP.

Messages with LE are exchanged through a series of opcodes, documented below. All messages sent from LE are formatted with the following payload type:

type SocketMessage {
	op: number; // opcode
	d?: unknown; // message data; usually an object; does not exist on regular heartbeats
}

Clients are also expected to send messages to LE in the same format.

​

Encoding & Compression

When connecting to the websocket, LE supports 2 query parameters: encoding and compression. Refer to the below table for possible values.

Note: The json encoding type will just send plaintext minified JSON objects.

​

Opcode Map

rx = receive (from LE, to client)
tx = transmit (from client, to LE)

​

Connection flow

​

Connecting

We recommend you explicitly pass in an encoding type with the LE socket URL, e.g. wss://leap.hop.io/1.0/ws?encoding=json.

Once connected, you should receive an Op 1: Hello payload, which contains setup information about the LE session for the client to use, which includes the heartbeat interval:

Example Op 1: Hello

{
  "op": 1,
  "d": {
    "heartbeat_interval": 30000
  }
}

After receiving this, the client has 10 seconds to send an Op 2: Identify. If this is not sent, LE will disconnect the socket with a 4002: Identify timeout error.

​

Heartbeating

Once receiving Op: 1 Hello, the LE client or SDK should immediately start a repeating interval which sends Op 3: Heartbeat on the interval. Please note that Leap Edge calculates the time drift over time,so if you drift too far out of the expected heartbeat interval then you may be disconnected from the socket with error 4007: Out of sync.

Leap Edge may also send Op 3 down to the client with a tag in the data field. If the client receives this, it needs to immediately respond with Op 3: Heartbeat with the same tag in the data field.

​

Connecting to Hop Services

When generating the Leap Token (the authentication secret used when identifying with Leap Edge), Hop services are granted to the token using “service grants”. This is usually done trivially through the SDK. Service grants specify what services a Leap Token can access, however they’re not automatically subscribed when the socket connects. To susbcribe to a service that the token has a grant for, send Op 5: Create Service Subcription.

​

Errors

Clients can be disconnected from Leap for a variety of reasons. Disconnections will be sent with an error code and descriptive reason. These are not sent as normal WebSocket messages; refer to your socket library for information on how to handle these events. In JS, these events are represented as CloseEvents.

Below, you can find a map of our custom error codes and what they mean.