Push notifications support

Overview

A dhtnode can forward values to a device via push notifications. The gateway send wake up notifications to device vendor push provider which sends a push notifications.

         +---------------------------------------------+  +-------------------+
         |                                             |  |                   |
         |                    Distant Node             |  |   Device Vendor   |
         |                                             |  |                   |
         |+-------------------+     +----------------+ |  | +---------------+ |
         ||                   |     |   Push Gateway | |  | |               | |
         ||    OpenDHT Node   +----->  (GoRush /     +------> Push Provider | |
         ||    (with proxy)   |     |   UnifiedPush) | |  | |    (FCM/APN)  | |
         |+-^-----------------+     +----------------+ |  | +----+----------+ |
         +--|------------------------------------------+  +-------------------+
 OpenDHT    |                                                    |
 Proxy API  |                                                    |
            |                                                    |
            |   +--+-+                                           |
            |   |    <-------------------------------------------+
            +---+    |
                |    |                  
                +----+
           Android or iOS device

How it works

Applications certificates and tokens.

To add the ability to handle push notifications both for iOS or Android, an application should have two things:

1. A private certificate for the application, provided by the Push Provider, to have the ability to push notifications for this app. This certificate is stored with the Push Gateway.
2. A client token for each device, stored by the client device, typically provided by the Push Provider library integrated in the app.

Push notifications Step by step

Ask a distant node to listen a hash

The first thing to do is to ask a distant node to listen the DHT for a device. For this, the DhtProxyServer have the SUBSCRIBE endpoint:

Method: SUBSCRIBE  "/{InfoHash: .*}"
Body: {"key": "device_key", (optional)"callback_id":y,
"platform":"android"}"
Return: {"token": x}" where x if a token to save

Supported values for "platform": android (using gorush), ios (using gorush), unifiedpush (using the UnifiedPush API)

where the client pass the device_key (the token previously generated for the device), if the device is an android device and a callback_id used to have the ability to have multiple listen for the same hash. The distant node will listen for this hash during six hours, after this the listen will stop (timeout) and the client should refresh this listen operations. To stop listening before the timeout, the client can call the UNSUBSCRIBE endpoint.

Method: UNSUBSCRIBE "/{InfoHash: .*}"
Body: {"key": "device_key", "token": x, (optional)"callback_id":y"
where x if the token to cancel
Return: nothing

and the distant node will send a push notifications to inform the device the listen is finished.

DhtProxyServer side

The proxy server will listen on the DHT during six hours. Two types of push notifications can be generated:

1. The timeout push notifications to inform a device that the listen has finished:

{
    "token":"the token",
    "callback_id":"optionnal",
    "timeout":"the hash"
}

2. A wake up notification, to inform the device that it can retrieves new values (via a GET on the DHT):

{
    "token":"the token",
    "callback_id":"optionnal"
}

The notification doesn't contains any value for two reasons. First, the notification must pass through Google or Apple (FCM/APN) and the size of a notification is limited to 2kb versus 64kb for values in OpenDHT.

The proxy server send notifications to a push gateway. Here, we are currently using GoRush. Then the client will receives the push notification. If it's a wake up notification, it will do a get on the proxy to retrieves values and decrypt it. If it's a timeout value it will redo a subscribe if needed, else the notification will be ignored.

Push gateway

The DhtProxyServer uses a GoRush or UnifiedPush push gateway which stores certificates for linked applications.

Because the push gateway is strongly related to an application (because of the certificate), you only can send push notifications to an application with the related gateway. If you want to use your own gateway with an application, you should recompile the application with your own certificate. You can use any proxy node with any gateway but not any gateway with any application. And all applications will use FCM or APN.

Client side when receiving

When a push notification is received, the application must reinject the notification in OpenDHT. The method provided by the library is:

/**
 * Insert a push notification to process for OpenDHT
 */
void pushNotificationReceived(const std::string& notification) const;
void pushNotificationReceived(const Json::Value& notification) const; // with jsoncpp

This will inject the notification in DhtProxyClient. For a wake up notification, the proxy client will perform a get on the hash to retrieves values from the DHT and if it's a timeout notification, it will check if the listener should be restarted or not.

Summary