Permalink
Browse files

Updated docs

  • Loading branch information...
1 parent 5d39515 commit 6bbf4f30151486331274307057cdbf59a1440f5c @kriszyp kriszyp committed Dec 28, 2011
Showing with 37 additions and 33 deletions.
  1. +37 −33 README.md
View
@@ -1,27 +1,22 @@
[Tunguska](http://en.wikipedia.org/wiki/Tunguska_event) is a comet-based
-distributed publish/subscribe hub for server side JavaScript (Node, Rhino/Narwhal).
+distributed publish/subscribe hub for server side JavaScript (NodeJS, Rhino/RingoJS).
Tunguska is publish subscribe framework for building applications around a
publish-subscribe system with real-time message delivery
to browsers. An introduction to Tunguska can be [found here](http://www.sitepen.com/blog/2010/07/19/real-time-comet-applications-on-node-with-tunguska/).
+Tunguska can be installed as NPM package using:
+
+ npm install tunguska
+
Tunguska consists of several modules:
-lib/hub.js
-========
+## hub
This is the actual publish-subscribe hub. The hub is a simple, easy to use set of channels
for publishing and listening for events, but includes some powerful features. To use the
-hub, simply require the hub.js module to get the hub object. If you installed Tunguska
-such that lib/hub.js is available through the tunguska path:
+hub, simply require the hub.js module to get the hub object. If you installed Tunguska, you can do:
var hub = require("tunguska/hub");
-If you are using [Nodules](http://github.com/kriszyp/nodules) you can map to tunguska
-by adding this line to your package.json (And Tunguska will automatically be downloaded for you):
-
- "mappings": {
- "tunguska": "jar:http://github.com/kriszyp/tunguska/zipball/master!/lib/"
- }
-
Now to subscribe to a channel:
hub.subscribe("name/of/channel", function listenerFunction(message){
@@ -36,17 +31,15 @@ And to unsubscribe:
hub.unsubscribe("name/of/channel", listenerFunction);
-Return Values
--------------
+### Return Values
Calls to publish, subscribe, and unsubscribe will return an array of promises that
represent the eventual return value from each subscriber. One can therefore determine
when all the messages have been delivered, and if there was failures. In a distributed
environment, the return value from subscription requests can be monitored to determine when the subscription
has been distributed to all hubs.
-Globbing/Wildcards
------------------
+### Globbing/Wildcards
Tunguska supports wildcarding/globbing for subscriptions. We can subscribe to a set
of channels like:
@@ -74,8 +67,7 @@ we could choose to only listen to the "system" messages on a channel:
hub.subscribe("name/of/channel", "system", systemListener);
-Named Events
--------------
+### Named Events
And we can define name of the type of events with the "type" property in our published
messages. For example:
@@ -96,8 +88,7 @@ whenever a channel becomes free of any subscribers. For example:
(This is used by the connectors)
-Client Identity/Echo Suppression
------------------------------
+### Client Identity/Echo Suppression
Tunguska provides echo suppression by defining client identities. This is an important
feature for distributed pubsub because it allows you to define efficient message routing
@@ -120,12 +111,15 @@ client. For example:
hub.fromClient("client-1").publish("name/of/channel", {name:"msg-1"}); // will not fire the listenerFunction above
hub.fromClient("client-2").publish("name/of/channel", {name:"msg-2"}); // will fire the listenerFunction
-lib/jsgi/comet.js
-============
+### jsgi/comet
This module consists of several JSGI appliances.
-* require("tunguska/jsgi/comet").Connections(nextApp) - This a middleware appliance for creating and
+#### Connections
+
+ require("tunguska/jsgi/comet").Connections(nextApp)
+
+This a middleware appliance for creating and
using a pool of client connection entities that can be shared across requests. This can
be useful to use directly if non-comet requests may add or alter subscriptions for
another comet connection that shares the same virtual connection entity. Connections
@@ -135,32 +129,42 @@ handling.
Connections are available within downstream JSGI applications from
request.clientConnection. The connection queue object has the following properties/methods:
-** send(message) - This can be called to send a message to any connected client
-** onclose() - This event is called/triggered when a connection is closed
+* send(message) - This can be called to send a message to any connected client
+* onclose() - This event is called/triggered when a connection is closed
+
+#### Broadcaster
-* require("tunguska/jsgi/comet").Broadcaster(path, subscriptionApp, nextApp) - This
-provides a comet end-point. A request that matches the path will be handled by the
+ require("tunguska/jsgi/comet").Broadcaster(path, subscriptionApp, nextApp)
+
+This provides a comet end-point. A request that matches the path will be handled by the
Broadcaster and any messages in the client connection queue will be sent to the client,
or if the connection queue is empty, it will wait until a message is sent to the connection
and the broadcaster will deliver the message to the client. When the path is matched,
the subscriptionApp will be called next and can handle defining any subscriptions that
should be made (to the hub) and routing received messages to the connection queue.
If the path is not matched, the nextApp is called.
-* require("tunguska/jsgi/comet").Subscriber(subscriptions, nextApp) - This is a
-subscription handling appliance that will either use list of subscriptions provided in the
+#### Subscriber
+
+ require("tunguska/jsgi/comet").Subscriber(subscriptions, nextApp)
+
+This is a subscription handling appliance that will either use list of subscriptions provided in the
setup argument, or if the subscriptions argument is omitted, any subscriptions
provided in the request, and subscribes to given channels on the hub, and forwards any received messages
to the connection queue object.
-* require("tunguska/jsgi/comet").Notifications(path, subscriptions, nextApp) - This combines
-all three middleware appliance above into a single middleware appliance. The path defines
+#### Notifications
+
+ require("tunguska/jsgi/comet").Notifications(path, subscriptions, nextApp)
+
+This combines all three middleware appliance above into a single middleware appliance. The path defines
the comet end-point. The subscriptions parameter is optional and can specify the set
of channels to subscribe to. The nextApp is called for requests that don't match the path.
-Connectors
-=========
+### connector
+ require("tunguska/connector").Connector(connectionId, stream);
+
Connectors provide a means for connecting hubs in different processes and on
different machines, thus allowing for distributed publish/subscribe systems. Connectors
are provided for worker-based communication, WebSocket communication

0 comments on commit 6bbf4f3

Please sign in to comment.