[asterisk-app-dev] Blinky Lights Proposal

[Matthew Jordan]

Hey everyone -

At AstriDevCon, we mentioned that two features ARI would need were the
ability to raise MWI and the ability to publish state (device state, but
theoretically, any event package for some subscribable resource).
Initially, we discussed needing two resources in ARI - one that represents
the state of mailboxes, and one that represents the state of a "device".

The more we've thought about it, the more it feels like - from ARI's
perspective - these are the same concepts. From the perspective of an ARI
client, you want the ability to define a resource that someone can
subscribe to. You want to be notified when something subscribes to it; when
they unsubscribe to it; and when a resource's state changes. In turn, you
want to publish state about that resource to the subscribers. The fact that
the resource is a mailbox, or a device, or who knows what else - is
immaterial. The application itself should determine this.

(Plus, we forgot that in addition to device state and MWI, there's also
presence state in Asterisk. So we were already up to 3 things anyway)

We need a more generic concept - a 'blinky light' resource, if you will.

The trick, unfortunately, is that in the guts of Asterisk, these are not
the same concepts. MWI and device state (or presence state, for that
matter) are all handled very differently. As much as it'd be fun to say
"let's unify all the implementations!" - that's unrealistic and potentially
harmful. So whatever we choose, there has to be a way to map the generic
concept back to the actual implementation inside Asterisk.

The following is a proposal on how I think this might work:

Add a new resource to ARI to represent a generic resource that can be
subscribed to/published about, 'topics'. A topic is something that
something can subscribe to, that has state, and that the ARI client can
publish state about. (Note that I chose the name 'topic' as it's what the
XMPP folks used for their publish/subscribe XEP (XEP-0060), and 'resource'
isn't a good name as it's a generic term in REST. Hopefully it doesn't get
too confusing with Stasis message bus topics.)

Objects:

Topic:
    type: string - Valid types initially would be 'mailbox', 'device',
'presence'
    uri: string - The URI subscribers use to subscribe to the topic
    subscribers: List[Subscriber] - A list of active subscriptions
    id: string - A unique ID for the topic

Subscriber
    id: string - A unique ID for the subscriber
    topic_id: string - The topic ID this subscription refers to
    endpoint: Endpoint - If available, the endpoint that subscribed to this
Topic

TopicSubscriptionCreated : Event - Event raised when a new subscription is
created for a topic
    subscriber : Subscriber
    topic: Topic

TopicSubscriptionDestroyed : Event - Event raised when a subscription is
destroyed for a topic
    subscriber : Subscriber
    topic : Topic

TopicEvent : Event - Event raised in relation to a topic
    topic : Topic
    body : JSON

TopicCreated : Event - Event raised when a new topic is created
    topic : Topic

TopicDestroyed : Event - Event raised when a topic is destroyed
    topic : Topic

Operations:

GET /topics List[Topic] - list all topics, with optional filter for type
GET /topic Topic - get information about a specific topic
DELETE /topic - destroy a topic. This should implicitly unsubscribe all
subscribers.
POST /topics Topic - create a new topic. When you create a topic, you are
implicitly subscribed to that topic.
    type: The type of topic to create. Valid types initially would be
'mailbox', 'device', 'presence'
    uri: The URI subscribers will use to subscribe to the topic
POST /topics/publish - publish an event to a topic. Events are passed as
JSON, and are opaque from the perspective of ARI. It would be up to the
specific topic types to understand the  event packages.

/applications/{applicationName}/subscription will be updated to allow for
an ARI client to subscribe to any topic in Asterisk.

Note that a topic doesn't have to be something created by ARI - Asterisk
will create a *lot* of topics by itself. There would be a topic for all
mailboxes created by voicemail providers; a topic for all producers of
extension state (at a minimum; devices as well); a topic for all producers
of presence state. Much like the Endpoints resource, the Topics resource
lets an ARI client subscribe to other things in the system other than what
is directly in their application, so that the client can choose to have
knowledge of the whole system, even if it only affects a part.

This is quite a big project, but a very necessary one. There's only one
thing that has to be fixed in ARI before we can do this - namely the
ability to POST JSON (thanks Paul!)  But other than that, I don't think
there are any technical barriers to this approach.

Thoughts? Comments?

-- 
Matthew Jordan
Digium, Inc. | Engineering Manager
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at: http://digium.com & http://asterisk.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-app-dev/attachments/20131031/5412eb78/attachment.html>