Connection (Subscription) Management

Beebotte subscription management or connection management provides the following operations:

  • Get User Connections to get the list of active subscriptions (or live connections) by users.
  • Drop User Connections to drop an active subscription (or live connection) of a user.

An active subscription or live connection is any MQTT or Websockets (socketio protocol) connection made by a client to Beebotte.

Each user subscription is identified by:

  • A user id: optionally provided when establishing the MQTT ot Websockets (socketio protocol) connection. On MQTT, if the user id is not provided, one will automatically get generated.
  • A session id: randomly created unique session id when using Websockets (socketio). The user id when using MQTT.

Connection Management operations require authentication either:

  • using the account API and Secret Keys, or,
  • using IAM Token with admin:connection:read and admin:connection:write access rights.

Get User Connections

You can ask Beebotte to return the list of all live connections as follows:

// get all connections
bclient.getUserConnections(function(err, res) {
    if(err) console.log(err);
    // On success, res is an array of connection descriptions
});

// get connection of a given user id. A user might have multiple sessions
bclient.getUserConnections({
userid: "uid-12345"}, function(err, res) {
    if(err) console.log(err);
    // On success, res is an array of connection description
});

// get connection of a given user id and session id. This will give one connection max
bclient.getUserConnections({
userid: "uid-12345", sid: "sid-09876"}, function(err, res) {
    if(err) console.log(err);
    // On success, res is an array of connection description
});

# get all connections
connections = bclient.getUserConnections()

# get connection of a given user id. A user might have multiple sessions
connections = bclient.getUserConnections(userid="uid-12345")

# get connection of a given user id and session id. This will give one connection max
connections = bclient.getUserConnections(userid="uid-12345", sid="sid-098765")
/// get all connections
var connections = bclient.GetUserConnections();

/// get connection of a given user id. A user might have multiple sessions
var connections = bclient.GetUserConnections("uid-12345");

/// get connection of a given user id and session id. This will give one connection max
var connections = bclient.GetUserConnections("uid-12345", sessionId: "sid-098765");

## cURL requires IAM Token authentication

# get all connections
curl -H "Content-Type: application/json" \
     -H "X-Auth-Token: YOUR_IAM_TOKEN" \
     -X GET \
     http://api.beebotte.com/v1/connections

# get connection of a given user id. A user might have multiple sessions
curl -H "Content-Type: application/json" \
     -H "X-Auth-Token: YOUR_IAM_TOKEN" \
     -X GET \
     http://api.beebotte.com/v1/connections/uid-12345

# get connection of a given user id and session id. This will give one connection max
curl -H "Content-Type: application/json" \
     -H "X-Auth-Token: YOUR_IAM_TOKEN" \
     -X GET \
     http://api.beebotte.com/v1/connections/uid-12345?sid=sid-098765

Connection information has the following structure:

[{
  clientid: "uid-bCY0jGcM17MPKkd8",
  clientip: "::ffff:10.0.0.123",
  owner: "beebotte",
  protocol: "socketio",
  sid: "G-bQyzSxjW9PLYbZAxo3",
  userid: "uid-bCY0jGcM17MPKkd8",
  subscriptions: [{channel: "my_channel", resource: "my_resource", read: true, write: true}],
  userinfo: {userid: "uid-bCY0jGcM17MPKkd8", username: "optional_username"}
},
{
  clientid: "bbt_test-mqttjs_115e84d1",
  clientip: "::ffff:10.0.0.123",
  owner: "beebotte",
  protocol: "mqtt",
  sid: "bbt_test-mqttjs_115e84d1",
  userid: "bbt_test-mqttjs_115e84d1"
}]

The content of the connection description differs slightly based on the protocol. With Socketio protocol, the connection description includes the list of subscriptions and the userinfo details.

Drop User Connections

You can drop user connections as follows:

Dropping connections will close any user connection matching the given parameters without returning any details about closed connections. This API call will not fail if it founds no connections to drop.

// drop all connections of a userid
// on socketio multiple can exist
// on mqtt only one can exist
// a userid can have connections both using mqtt and socketio
bclient.dropUserConnection({
    userid: 'uid-12345'
}, function(err, res) {
    if(err) console.log(err);
    // On success empty response is returned
});

// drop all connections of a userid on a given protocol
bclient.dropUserConnection({
    userid: 'uid-12345',
    protocol: 'socketio' // or mqtt
}, function(err, res) {
    if(err) console.log(err);
    // On success empty response is returned
});

// drop connection identified by session id (only one can exist)
bclient.dropUserConnection({
    userid: 'uid-12345',
    protocol: 'socketio', // or mqtt
    sid: 'sid-098765'
}, function(err, res) {
    if(err) console.log(err);
    // On success empty response is returned
});

# drop all connections of a userid
# on socketio multiple can exist
# on mqtt only one can exist
# a userid can have connections both using mqtt and socketio
bclient.dropUserConnection(userid="uid-12345")

# using Python, dropping connection by protocol is not supported yet

# drop connection identified by session id (only one can exist)
bclient.dropUserConnection(userid="uid-12345", sid="sid-098765")

/// drop all connections of a userid
/// on socketio multiple can exist
/// on mqtt only one can exist
/// a userid can have connections both using mqtt and socketio
bclient.DeleteConnection("uid-12345");

/// using .Net, dropping connection by protocol is not supported yet

// drop connection identified by session id (only one can exist)
bclient.DeleteConnection("uid-12345", sessionId: "sid-098765");

## cURL requires IAM Token authentication

# drop all connections of a userid
# on socketio multiple can exist
# on mqtt only one can exist
# a userid can have connections both using mqtt and socketio
curl -H "Content-Type: application/json" \
     -H "X-Auth-Token: YOUR_IAM_TOKEN" \
     -X DELETE \
     http://api.beebotte.com/v1/connections/drop/uid-12345

# drop all connections of a userid on a given protocol
curl -H "Content-Type: application/json" \
     -H "X-Auth-Token: YOUR_IAM_TOKEN" \
     -X DELETE \
     http://api.beebotte.com/v1/connections/drop/uid-12345?protocol=mqtt

# drop connection identified by session id (only one can exist)
curl -H "Content-Type: application/json" \
     -H "X-Auth-Token: YOUR_IAM_TOKEN" \
     -X DELETE \
     http://api.beebotte.com/v1/connections/drop/uid-12345?sid=sid-098765

Beebotte Documentation