pubs

Kopano API pubs plugin

The pubs plugin provides a simple pub/sub system with HTTP webhooks and websocket stream subscription.

Configuration

For security, the pubs plugin needs a secret key so it can HMAC its tokens. By default a random 512 bit secret key is generated on startup. For production use the key should not change and can be provided as hex encoded value by the KOPANO_PUBS_SECRET_KEY environment variable. A suitable key value can be created with with openssl rand -hex 64.

KOPANO_PUBS_ALLOW_CORS is an environment variable which if set to 1 enables CORS (Cross Origin Resource Sharing) HTTP requests and headers so that the REST endpoints provided by this plugin can be used from a browser cross origin.

KOPANO_PUBS_REQUIRED_SCOPES is an environment variable which defines the required access token scopes to grant access to the API endpoints provided by this plugin. By default the scopes are kopano/pubs.

HTTP API v1

The base URL to this API is /api/pubs/v1. All example URLs are sub paths of this base URL.

Authentication

All endpoints of the Pubs API require OAuth2 Bearer authentication with an access token (if not stated otherwise).

Register webhook pub URL

Registers a new webhook URL to publish data to a certain topic.

POST /webhook?topic=optional-client-provided-topic
201

{
	"id": "${id}",
	"pubUrl": "/api/pubs/v1/webhook/${topic-and-webhook-token-id}",
	"topic": "${topic-as-passed-to-post-or-random}"
}

The id is auto generated by the server and is unique and can be used to reference this webhook. If no topic is provided via the topic request parameter, a unique secure random topic is generated and returned.

Webhook pub

Publish data to a previously registered webhook URL. Authorization and topic are encoded inside the token and cannot be changed. Thus the webhook pub endpoints do not require additional Bearer authentication.

POST /webhook/${id}/${topic-and-webhook-token}
POST /webhook/${id}/${topic-and-webhook-token}/${envelope}
204

Optionally the data is enclosed into a JSON structure with a type matching the value of the subpath envelope.

Websocket bi-directional event stream

Websocket stream can be used to interact with pubs pub/sub. To retrieve the address for Websocket streaming, issue an authenticated request to the /stream/connect endpoint.

GET /stream/connect
200

{
  "streamUrl": "/api/pubs/v1/stream/websocket/ap1L3rNzuC9uWc07FT3QJCDZ1Q8PjLoV"
}

The streamUrl is a one URL to use for Websocket streaming. It can be used exactly one time. Further connects will result in 404. If the connection is lost, call connect again. The Websocket stream URL does not require Bearer authentication.

GET /stream/${key} (Websocket)
101

The key is part of the URL received from a previous call to /stream/connect.

Websocket payload data

< {
  "type": "hello",
  "info": {
    "ref": "gnP4kvAKhHAd4ZalVDsRVmkvi9nHHYF71vsCz0UcX2k="
  }
}

> {
	"type": "sub"
	"state": "optional-client-controlled-state",
	"data": {
		"topics": ["topic1", "topic2"]
	}
}
< {
  "type": "ack",
  "state": "optional-client-controlled-state"
}

< {
  "type": "event",
  "data": {
    "type": "trigger-controlled-envelope",
    "data": 1
  },
  "info": {
    "ref": "HINSF2ZYw4MIJCVW4EdorffqTAW4tGJEMifd4lsIcy8=",
    "topics": [
      "topic1"
    ]
  }
}

Possible types are hello, ack, sub, unsub, closeTopic, pub and event.

If the payload data contains a state value, then the server replies with an ack type once the action has been exectued. The ack payload includes the state unmodified.

All received event messages, contain an info object, with the ref to the sending entity (if any) and the topics array which tells what topics this message was meant for.

The data value of the event type is entirely controlled by the trigger, and thus is application specific. For simplicity in client implementations it is recommended to always use a JSON object for data together with a type key so applications can easily handle incoming messages.

Usage examples

This assumes you have wscat and curl in your path.

Websocket example:

$ export PUBS_HOST=https://localhost:8428"
$ wscat -n --connect $PUBS_HOST/api/pubs/v1/stream/websocket
connected (press CTRL+C to quit)
< {
  "type": "hello",
  "info": {
    "ref": "qIclxqTjWWh3KkPYwrZaO1uDIjxbSsIGdHscLpWkLg4="
  }
}
> {"type": "sub", "state": "123", "info": {"topics": ["lala"]}}
< {
  "type": "ack",
  "state": "123"
}

Webhook example:

$ export TOKEN_VALUE=<access_token>
$ curl -s -XPOST -H "Authorization: Bearer $TOKEN_VALUE" "$PUBS_HOST/api/pubs/v1/webhook?topic=lala"
{
  "id": "VNEH1P5s6v1mTKGcG4pwKp9GNxp-bqx2r2oB52uCkfM=",
  "topic": "lala",
  "pubUrl": "/api/pubs/v1/webhook/VNEH1P5s6v1mTKGcG4pwKp9GNxp-bqx2r2oB52uCkfM=/MTUxODUyMjc5NnxNdi1CQXdFQkUzZGxZbWh2YjJ0UWRXSlViMnRsYmtSaGRHRUJfNElBQVFJQkFrbEVBUXdBQVFWVWIzQnBZd0VNQUFBQU5fLUNBU3hXVGtWSU1WQTFjeloyTVcxVVMwZGpSelJ3ZDB0d09VZE9lSEF0WW5GNE1uSXliMEkxTW5WRGEyWk5QUUVFYkdGc1lRQT18U84T7M7v3wD5xuO7P4O5WzICbLAUwuxvPDX2Rjpz_Ic="
}
$ curl -s -XPOST -H "Content-Type: application/json" -d '{"some":"data"}' "$PUBS_HOST/api/pubs/v1/webhook/VNEH1P5s6v1mTKGcG4pwKp9GNxp-bqx2r2oB52uCkfM=/MTUxODUyMjc5NnxNdi1CQXdFQkUzZGxZbWh2YjJ0UWRXSlViMnRsYmtSaGRHRUJfNElBQVFJQkFrbEVBUXdBQVFWVWIzQnBZd0VNQUFBQU5fLUNBU3hXVGtWSU1WQTFjeloyTVcxVVMwZGpSelJ3ZDB0d09VZE9lSEF0WW5GNE1uSXliMEkxTW5WRGEyWk5QUUVFYkdGc1lRQT18U84T7M7v3wD5xuO7P4O5WzICbLAUwuxvPDX2Rjpz_Ic="