Publish Subscribe messaging

In the EW-DOS implementation of Pub/Sub messages the following requirements shall be implemented:

  • Messages are pushed exactly once to each subscriber
  • Only authorised participants can publish and subscribe
  • The authentication is performed through a signature verification of a DID
  • The authorisation is configured using Switchboard roles

Channel Namespaces

The messaging application exists in Switchboard just like any other app. Its namespace is messaging.apps.energyweb.iam.ewc.

Each channel is part of an application defined in Switchboard. An example namespace for a channel is mynews.channels.myapp.apps.myorg.iam.ewc. This namespace is refered to as fully qualified channel name or fqcn for short.

Authorisations

Users of the messaging app must have the role user.roles.messaging.apps.energyweb.iam.ewc at the very least. Getting this role means that the user has paid their subscription and entitles them to sending and receiving direct messages only.

A heightened permission in the messaging app is required to create channels. This privilege is only granted to members of the channel-creation.roles.messaging.apps.energyweb.iam.ewc role.

Additionally to the overall channel-creation role, a user must have the correct role in the relevant application too. The role is channel-creation.roles.myapp.apps.myorg.iam.ewc by convention.

It should not be possible to remove a channel on which a message has been published as this would delete the entire history for it. It is better to remove access to the channel.

Channel creation

Provided a user has the correct roles to do so, they can create as many channels as they like for a specific application. The channel's creator must have the correct channel-creation roles (in the messaging app and the app to which the channel belongs) for the fqcn.

The input required for the creation is:

class ChannelInput {
  // fqcn = fully qualified channel name
  fqcn: string;
  description?: string;
  publisherRole: string
  subscriberRole: string
  maxTimeout: ChannelTimeoutInput
  defaultTimeout: ChannelTimeoutInput
}
fqcn

The fully qualified channel name e.g. mynews.channels.myapp.apps.myorg.iam.ewc.

description

A text description of the channel's usage. This will be useful for users of this message

publisherRole

An arbitrary Switchboard role which is required in order to publish messages to this channel. The role must exist at channel creation time.

subscriberRole

An arbitrary Switchboard role which is required in order to subscribe to messages from this channel. The role must exist at channel creation time.

maxTimeout

How long can a message live on this channel before being deleted. When a message is sent, the defaultTimeout can be overwritten, but it cannot be higher than this.

defaultTimeout

if nothing is specified, messages on this channel will expire after this timeout and not be available for query anymore.

process
sequenceDiagram participant alice as Alice participant msg as Message Broker participant adb as Address Book alice ->> msg: create channelC msg ->> adb: create channel adb ->> adb: check fqcn existence alt channel exists adb -->> msg: error channel exists msg -->> alice: error channel exists else adb -->> msg: creation success msg -->> alice: creation success end

Publication of message on a channel

Any user with the role defined in publisherRole of a channel can publish messages on it. The messages will be delivered to any subscriber as long as the timeout has not been reached.

sequenceDiagram participant alice as Alice participant msg as Message Broker A participant adb as Address Book participant mtr as Mesage transport participant msgb as Message Broker B participant arc as Message Archive alice ->> msg: publish message to channel msg ->> adb: get channel's roles adb -->> msg: channel roles msg ->> msg: check Alice's roles alt Alice has the publisher role for the channel msg ->> mtr: publish message to fqcn mtr ->> msgb: push message mtr ->> arc: push message mtr -->> msg: message sent msg -->> alice: message sent else msg -->> alice: permission denied end

Subscribing to messages from a channel

Any user with the role defined in subscriberRole of a channel can subscribe to get the messages of a websocket subcription on the graphql server. This subscription will push all the messages sent to the channel while the connection is active. If the connection is interrupted, it is the client's responsibility to query for the missing messages.

Querying for messages on a channel

Any user with the role defined in subscriberRole of a channel can query the message history on this channel up to maxTimeout into the past.

By calling the getMessagesFromChannel function, a user can request the messages between two timestamps. This function is used in two scenarios:

  1. When the user does not want to subscribe for push notifications and regularly polls for new messages
  2. When the connection has been interrupted and the user wants to check for missed messages