Page last modified 10:54, 19 Aug 2010 by arnec

User:dev > Specs (Implemented) > MindTouch Event Bus

MindTouch Event Bus

1. How MindTouch uses the publish/subscribe bus
2. Hooking into the MindTouch event stream
3. Defined Events
1. 3.1. MindTouch Channel Format
2. 3.2. Event Resource Format
3. 3.3. Why is the channel in the event document?
4. 3.4. Page
  1. 3.4.1. NoOp
  2. 3.4.2. Create
  3. 3.4.3. Move
  4. 3.4.4. Update
  5. 3.4.5. Revert
  6. 3.4.6. Delete
  7. 3.4.7. Create Alias
  8. 3.4.8. View
  9. 3.4.9. Tags Update
  10. 3.4.10. Properties
    1. 3.4.10.1. Create
    2. 3.4.10.2. Update
    3. 3.4.10.3. Delete
  11. 3.4.11. Security
    1. 3.4.11.1. Create
    2. 3.4.11.2. Update
    3. 3.4.11.3. Delete
  12. 3.4.12. Dependents Changed
    1. 3.4.12.1. Comment Added
    2. 3.4.12.2. Comment Updated
    3. 3.4.12.3. Comment Deleted
    4. 3.4.12.4. Attachment Added
    5. 3.4.12.5. Attachment Update
    6. 3.4.12.6. Attachment Properties
    7. 3.4.12.7. Attachment Deleted
    8. 3.4.12.8. Attachment Restore
  13. 3.4.13. Talk Page Events
  14. 3.4.14. Custom Page Message Events (Experimental)
5. 3.5. Comment
  1. 3.5.1. NoOp
  2. 3.5.2. Create
  3. 3.5.3. Update
  4. 3.5.4. Delete
6. 3.6. File
  1. 3.6.1. No-Op
  2. 3.6.2. Create
  3. 3.6.3. Move
  4. 3.6.4. Update
  5. 3.6.5. Delete
  6. 3.6.6. Restore
  7. 3.6.7. Properties
    1. 3.6.7.1. Create
    2. 3.6.7.2. Update
    3. 3.6.7.3. Delete
7. 3.7. User
  1. 3.7.1. Create
  2. 3.7.2. Update
  3. 3.7.3. Change Password
  4. 3.7.4. Login
  5. 3.7.5. Properties
    1. 3.7.5.1. Create
    2. 3.7.5.2. Update
    3. 3.7.5.3. Delete
8. 3.8. Site
  1. 3.8.1. Start
  2. 3.8.2. Started
  3. 3.8.3. Stop
  4. 3.8.4. Rebuild Index
  5. 3.8.5. Settings Updated
  6. 3.8.6. Banning
    1. 3.8.6.1. Create
    2. 3.8.6.2. Remove

Introduced in Deki 9.02

1. How MindTouch uses the publish/subscribe bus
2. Hooking into the MindTouch event stream
3. Defined Events
1. 3.1. MindTouch Channel Format
2. 3.2. Event Resource Format
3. 3.3. Why is the channel in the event document?
4. 3.4. Page
  1. 3.4.1. NoOp
  2. 3.4.2. Create
  3. 3.4.3. Move
  4. 3.4.4. Update
  5. 3.4.5. Revert
  6. 3.4.6. Delete
  7. 3.4.7. Create Alias
  8. 3.4.8. View
  9. 3.4.9. Tags Update
  10. 3.4.10. Properties
    1. 3.4.10.1. Create
    2. 3.4.10.2. Update
    3. 3.4.10.3. Delete
  11. 3.4.11. Security
    1. 3.4.11.1. Create
    2. 3.4.11.2. Update
    3. 3.4.11.3. Delete
  12. 3.4.12. Dependents Changed
    1. 3.4.12.1. Comment Added
    2. 3.4.12.2. Comment Updated
    3. 3.4.12.3. Comment Deleted
    4. 3.4.12.4. Attachment Added
    5. 3.4.12.5. Attachment Update
    6. 3.4.12.6. Attachment Properties
    7. 3.4.12.7. Attachment Deleted
    8. 3.4.12.8. Attachment Restore
  13. 3.4.13. Talk Page Events
  14. 3.4.14. Custom Page Message Events (Experimental)
5. 3.5. Comment
  1. 3.5.1. NoOp
  2. 3.5.2. Create
  3. 3.5.3. Update
  4. 3.5.4. Delete
6. 3.6. File
  1. 3.6.1. No-Op
  2. 3.6.2. Create
  3. 3.6.3. Move
  4. 3.6.4. Update
  5. 3.6.5. Delete
  6. 3.6.6. Restore
  7. 3.6.7. Properties
    1. 3.6.7.1. Create
    2. 3.6.7.2. Update
    3. 3.6.7.3. Delete
7. 3.7. User
  1. 3.7.1. Create
  2. 3.7.2. Update
  3. 3.7.3. Change Password
  4. 3.7.4. Login
  5. 3.7.5. Properties
    1. 3.7.5.1. Create
    2. 3.7.5.2. Update
    3. 3.7.5.3. Delete
8. 3.8. Site
  1. 3.8.1. Start
  2. 3.8.2. Started
  3. 3.8.3. Stop
  4. 3.8.4. Rebuild Index
  5. 3.8.5. Settings Updated
  6. 3.8.6. Banning
    1. 3.8.6.1. Create
    2. 3.8.6.2. Remove

How MindTouch uses the publish/subscribe bus

MindTouch publishes a number of events via it's own pub sub services, DekiPubSubService, which is modified version of Dream's PublishSubscribeService. This services is the authentication gatekeeper for MindTouch events.

While DekiPubSubService does the authentication, generally subscriptions to MindTouch should still go through the default pubsub service provided to every feature, which will handle the chaining subscriptions and events.

Authentication for events on DekiPubSubService is currently limited to recipient authorization via apikey for all events, or for page events, by a user's access to a particular page. It is assumed that services in the pubsub chain are trusted, as userid's are checked blindly for page access without requiring authentication information providing that the subscriber has authentication credentials for the specified user.

Hooking into the MindTouch event stream

Every Dream Service is provided a Subscribe Uri that by default hooks them into the system PublishSubscribe bus. If the service is derived from DreamService, there also exists a Subscribe Plug property exposing this Uri. In order, for the service to receive Deki events, it needs to Post a subscription set against Subscribe. The format of subscription sets is described here. In order to qualify for Deki events, the subscriber must provide an auth token so that Deki can verify that the recipient is allowed to see the events. Currently, Deki uses the ApiKey as this token.

Sample Subscription Set:

<subscription-set>

  <!-- uri of the subscribing service -->   
  <uri.owner>...</uri.owner>

  <subscription>

    <!-- if the destination feature is not public, provide a cookie doc for
         publication service to be able to post the event -->
    <set-cookie version="1">
      <name>service-key</name>
      <uri>...</uri>
      <value>...</value>
    </set-cookie>
    
    <!-- one or more channel/channel wildcards -->
    <channel>...</channel>
    ...

    <!-- a feature on the service to post events to, along with the Dream ApiKey as the authtoken -->
    <recipient authtoken="...">
      <uri>...</uri>
    </recipient>

  </subscription>
</subscription-set>

Defined Events

MindTouch Channel Format

The defined channels for Deki are of the following format:

event://{wikiid}/deki/{type}/{action}[/{additional info}]

Event Resource Format

Each event affects a resource, which takes the format or the normal deki api uri to that resource with the host replaced by the wikiid. For example user with id 123 on the default wiki would have a resource uri like:

http://default/@api/deki/users/123

Why is the channel in the event document?

If you look at how the PubSubService works, you will notice that it uses a special header X-Dream-Event-Channel for routing between pub/sub services. However, the Feature that eventually receives the event document should not make any assumptions about the transport, but simply rely on the document that is posted. Conversely, PubSubService is payload neutral and should not be looking for the channel in the document. It is both conceivable that the payload sent is not an XDoc, meaning PubSubService needs the channel as a header and that the recipient feature gets an event posted to it via a transport other than the pub/sub system, meaning the channel needs to exist in the document itself.

Page

Channel: event://{wikiid}/deki/pages/{action}

Resource: http://{wikiid}/@api/deki/pages/{pageid}

Event Xml:

<deki-event wikiid="..." event-time="...">
  <channel>...</channel>
  <uri>...</uri>
  <pageid>...</pageid>
  <user id="..." anonymous="true|false">
    <uri>...</uri>
  </user>
  <content.uri type="..">...</content.uri>
  <revision.uri>...</revision.uri>
  <tags.uri>...</tags.uri>
  <comments.uri>...</comments.uri>
  <path>...</path>
</deki-event>

NoOp

Channel: event://{wikiid}/deki/pages/noop

Event Xml Addtion:

<deki-event wikiid="..." event-time="...">
  ...
  <previous-path>...</previous-path>
</deki-event>

A NoOp is used to tell listening parties to look at a page again although nothing has changed. It's current use is simply to allow the index service to re-index a page without sending a fake update event.

Create

Channel: event://{wikiid}/deki/pages/create

A new page was created

Move

Channel: event://{wikiid}/deki/pages/move

A page was moved. The id remains the same, but path and previous-path in the change doc describe hierarchical change.

Update

Channel: event://{wikiid}/deki/pages/update

The content of a page was changed

Revert

Channel: event://{wikiid}/deki/pages/revert

Event Xml Addition:

<deki-event wikiid="..." event-time="...">
  ...
  <reverted-to>{revision}</reverted-to>
  ...
</deki-event>

The content of a page was reverted to a previous revision. Reverting a page will send both an update and a revert event.

Delete

Channel: event://{wikiid}/deki/pages/delete

A page was deleted

Create Alias

Channel: event://{wikiid}/deki/pages/createalias

An alias to another page was created (generally this happens in tandem with a move event)

View

Channel: event://{wikiid}/deki/pages/view

A page was viewed.

Note: This event is disabled by default because it can be an expensive operation for busy sites. In order to enable it, you must create or set the configuration key 'events/enable-page-view-events' to true.

Tags Update

Channel: event://{wikiid}/deki/pages/tags/update

The tags collection for the page was updated

Properties

Channel: event://{wikiid}/deki/pages/properties/{action}

Resource: http://{wikiid}/@api/deki/pages/{pageid}/properties/{propname}

Event Xml:

<deki-event wikiid="..." event-time="...">
  <channel>...</channel>
  <uri>...</uri>
  <name>...</name>
  <pageid>...</pageid>
  <content mime-type="..." href="...">...</content>
</deki-event>

Pages use properties to store meta-data that don't fall under page updates, which should be reserved for content changes.

Create

Channel: event://{wikiid}/deki/pages/properties/create

Update

Channel: event://{wikiid}/deki/pages/properties/update

Delete

Channel: event://{wikiid}/deki/pages/properties/delete

Security

Channel: event://{wikiid}/deki/pages/security/{action}

Resource: http://{wikiid}/@api/deki/pages/{pageid}

Event Xml:

<deki-event wikiid="..." event-time="...">
  <channel>...</channel>
  <uri>...</uri>
  <pageid>...</pageid>
  <security cascade="..."/>
</deki-event>

Security settings are properties of a page, but since they are meta data they don't fall under page updates, which should be reserved for content changes.

Create

Channel: event://{wikiid}/deki/pages/security/create

Create in terms of security settings is unique in that it really means set, which could be overwriting existing settings

Update

Channel: event://{wikiid}/deki/pages/security/update

Delete

Channel: event://{wikiid}/deki/pages/security/delete

Dependents Changed

Dependent change events are triggered when a resource attached to a page is modified.

Comment Added

Channel: event://{wikiid}/deki/pages/dependentschanged/comments/create

Comment Updated

Channel: event://{wikiid}/deki/pages/dependentschanged/comments/update

Comment Deleted

Channel: event://{wikiid}/deki/pages/dependentschanged/comments/delete

Attachment Added

Channel: event://{wikiid}/deki/pages/dependentschanged/files/create

Attachment Update

Channel: event://{wikiid}/deki/pages/dependentschanged/files/update

Attachment Properties

Channel: event://{wikiid}/deki/pages/dependentschanged/files/properties/{action}

Attachment Deleted

Channel: event://{wikiid}/deki/pages/dependentschanged/files/delete

Attachment Restore

Channel: event://{wikiid}/deki/pages/dependentschanged/files/restore

Talk Page Events

Channel: event://{wikiid}/deki/pages/dependentschanged/talk/{talk event path}

Talk pages trigger events like any regular page, but they will also cascade events onto the page they talk about. I.e. the event event://{wikiid}/deki/pages/update on a talk page would also trigger event://{wikiid}/deki/pages/dependentschanged/talk/update. This extends to dependents on the talk page, i.e. there could be an event such as event://{wikiid}/deki/pages/dependentschanged/talk/dependentschanged/files/create

Custom Page Message Events (Experimental)

Channel: event://{wikiid}/deki/pages/message/{custom/path}

As part of the experimental Javascript Events & Messages (JEM) feature, it is possible for javascript on a page to send custom events back into the Deki bus. Currently there is no facility in JEM to receive these injected messages, but that feature will come soon. However, in the meantime it is still possible to build a DekiScript extension that can be used to receive and expose these custom messages back to the front end.

Comment

Channel: event://{wikiid}/deki/comments/{action}

Resource: http://{wikiid}/@api/deki/pages/{pageid}/comments/{commentnumber}

Event Xml:

<deki-event wikiid="..." event-time="...">
  <channel>...</channel>
  <uri>...</uri>
  <pageid>...</pageid>
  <uri.page>...</uri.page>
  <user id="..." anonymous="...">
    <uri>...</uri>
  </user>
  <path>...</path>
  <!-- content/@type and value are only included if smaller than 255 chars -->
  <content uri="..." type="...">...</content>
</deki-event>

All comment events (except noop) also trigger an event://{wikiid}/deki/pages/dependentschanged/{sub-action} for the parent page.

NoOp

Channel: event://{wikiid}/deki/comments/noop

A NoOp is used to tell listening parties to look at a comment again although nothing has changed. It's current use is simply to allow the index service to re-index a comment without sending a fake update event.

Create

Channel: event://{wikiid}/deki/comments/create

A comment was added to a page

Update

Channel: event://{wikiid}/deki/comments/update

An existing comment was updated

Delete

Channel: event://{wikiid}/deki/comments/delete

A comment was deleted

File

Channel: event://{wikiid}/deki/files/{action}

Resource: http://{wikiid}/@api/deki/files/{fileid}

Event Xml:

<deki-event wikiid="..." event-time="...">
  <channel>...</channel>
  <fileid>...</fileid>
  <uri>...</uri>
  <content.uri type="...">...</content.uri>   <revision.uri>...</revision.uri> 
  <path>...</path>
</deki-event>

All file events (except noop) also trigger an event://{wikiid}/deki/pages/dependentschanged/{sub-action} for the parent page.

No-Op

Channel: event://{wikiid}/deki/files/noop

A No-Op is used to tell listening parties to look at a file again although nothing has changed. It's current use is simply to allow the index service to re-index a file without sending a fake update event.

Create

Channel: event://{wikiid}/deki/files/create

A new file was attached to a page

Move

Channel: event://{wikiid}/deki/files/move

A file was moved from one page to another

Update

Channel: event://{wikiid}/deki/files/update

A new version of a file was uploaded

Delete

Channel: event://{wikiid}/deki/files/delete

A file was deleted

Restore

Channel: event://{wikiid}/deki/files/restore

A previously deleted file was restored

Properties

Channel: event://{wikiid}/deki/files/properties/{action}

Resource: http://{wikiid}/@api/deki/files/{pageid}/properties/{propname}

Event Xml:

<deki-event wikiid="..." event-time="...">
  <channel>...</channel>
  <uri>...</uri>
  <name>...</name>
  <fileid>...</fileid>
  <content mime-type="..." href="...">...</content>
</deki-event>

Files use properties to store meta-data that don't fall under file updates, which should be reserved for content changes.

Create

Channel: event://{wikiid}/deki/files/properties/create

Update

Channel: event://{wikiid}/deki/files/properties/update

Delete

Channel: event://{wikiid}/deki/files/properties/delete

User

Channel: event://{wikiid}/deki/users/{action}

Resource: http://{wikiid}/@api/deki/users/{userid}

Event Xml:

<deki-event wikiid="..." event-time="...">
  <channel>...</channel>
  <userid>...</userid>
  <uri>...</uri>
</deki-event>

Create

Channel: event://{wikiid}/deki/users/create

Update

Channel: event://{wikiid}/deki/users/update

Change Password

Channel: event://{wikiid}/deki/users/update/password

Login

Channel: event://{wikiid}/deki/users/login

Properties

Channel: event://{wikiid}/deki/users/properties/{action}

Resource: http://{wikiid}/@api/deki/users/{pageid}/properties/{propname}

Event Xml:

<deki-event wikiid="..." event-time="...">
  <channel>...</channel>
  <uri>...</uri>
  <name>...</name>
  <userid>...</userid>
  <content mime-type="..." href="...">...</content>
</deki-event>

Users use properties to store meta-data that don't fall under other user updates

Create

Channel: event://{wikiid}/deki/users/properties/create

Update

Channel: event://{wikiid}/deki/users/properties/update

Delete

Channel: event://{wikiid}/deki/users/properties/delete

Site

Site collects events that don't fall under a resource grouping, and therefore each may have different channel and Xml formats

Start

The start event is triggered when an API instance starts up. At this time it is not fully ready for interaction.

Channel: event://{wikiid}/deki/site/start

Event Xml:

<deki-event wikiid="..." event-time="...">
    <channel>...</channel
    <uri>...</uri>
</deki-event>

Started

The start event is triggered when an API instance has completed startup and is ready for interaction.

Channel: event://{wikiid}/deki/site/started

Event Xml:

<deki-event wikiid="..." event-time="...">
    <channel>...</channel
    <uri>...</uri>
</deki-event>

Stop

Channel: event://{wikiid}/deki/site/stop

Event Xml:

<deki-event wikiid="..." event-time="...">
    <channel>...</channel>
    <uri>...</uri>
</deki-event>

Rebuild Index

Channel: event://{wikiid}/deki/site/reindex

Event Xml:

<deki-event wikiid="..." event-time="...">
    <channel>...</channel>
</deki-event>

Settings Updated

This event is triggered when an API's instance settings have been updated.

Channel: event://{wikiid}/deki/site/settings/update

Event Xml:

<deki-event wikiid="..." event-time="...">
    <channel>...</channel>
</deki-event>

Banning

Channel: event://{wikiid}/deki/users/{action}

Event Xml:

<deki-event wikiid="..." event-time="...">
    <channel>...</channel>
    <banid>...</banid>

    <!-- userid of the user creating the ban -->
    <by>...</by>

    <!-- list of IPs, if the ban affected addresses -->
    <addresses>
        <addresss>...</address>
        ...
    </addresses>

    <!-- list of userids, if the ban affected users -->
    <users>
        <user id="..."/>
        ...
    </users>
</deki-event>

Bans do not have a resource attached to them and contain all relevant data in the event doc

Create

Channel: event://{wikiid}/deki/ban/create

Remove

Channel: event://{wikiid}/deki/ban/delete

Tag page
What links here

Files 0

Attach file or image

Images 0
No images to display in the gallery.

You must login to post a comment.

MindTouch Social Knowledge Base

Login or Join Community

MindTouch Event Bus

Table of contents

How MindTouch uses the publish/subscribe bus

Hooking into the MindTouch event stream

Defined Events

MindTouch Channel Format

Event Resource Format

Why is the channel in the event document?

Page

NoOp

Create

Move

Update

Revert

Delete

Create Alias

View

Tags Update

Properties

Create

Update

Delete

Security

Create

Update

Delete

Dependents Changed

Comment Added

Comment Updated

Comment Deleted

Attachment Added

Attachment Update

Attachment Properties

Attachment Deleted

Attachment Restore

Talk Page Events

Custom Page Message Events (Experimental)

Comment

NoOp

Create

Update

Delete

File

No-Op

Create

Move

Update

Delete

Restore

Properties

Create

Update

Delete

User

Create

Update

Change Password

Login

Properties

Create

Update

Delete

Site

Start

Started

Stop

Rebuild Index

Settings Updated

Banning

Create

Remove

Files 0

Table of contents