:orphan: Subscription Meta Events and Procedures ======================================= A subscription is created within Crossbar.io when a first client issues a subscription request for a topic, and it is deleted when the last client unsubscribes or its session is disconnected. In between, other client sessions may be attached to the subscription or removed from it. Subscription meta-events give information about these events. Additionally, there is a set of meta-procedures which can be called to receive information about currently existing subscriptions. Meta-events are created by the router itself. This means that the events as well as the data received when calling a meta-procedure can be accorded the same trust level as the router. Use cases for subscription meta events and procedures ----------------------------------------------------- Within an application, it may be desirable for a publisher to know whether a publication to a specific topic currently makes sense, i.e. whether there are any subscribers who would receive an event based on the publication. It may also be desirable to keep a current count of subscribers to a topic to then be able to filter out any subscribers who are not supposed to receive an event. Events ------ The set of meta events covers the lifecycle of a subscription. A client can subscribe to the following subscription meta events: - ``wamp.subscription.on_create``: Is fired when a subscription is created through a subscription request for a topic which was previously without subscribers. - ``wamp.subscription.on_subscribe``: Is fired when a session is added to a subscription. - ``wamp.subscription.on_unsubscribe``: Is fired when a session is removed from a subscription. - ``wamp.subscription.on_delete``: Is fired when a subscription is deleted after the last session attached to it has been removed. Note: A ``wamp.subscription.on_subscribe`` event is always fired subsequent to a ``wamp.subscription.on_create`` event, since the first subscribe results in both the creation of the subscription and the addition of a session. Similarly, the ``wamp.subscription.on_delete`` event is always preceded by a ``wamp.subscription.on_unsubscribe`` event. The WAMP subscription meta events are dispatched by the router to the *same realm* as the WAMP session which triggered the event. **Important**: To receive and process these events, your component will need to have *subscribe* permission on the respective topic. Procedures ---------- It is possible to actively retrieve information about subscriptions via the following procedures. Retrieve Subscription IDs ~~~~~~~~~~~~~~~~~~~~~~~~~ You can retrieve subscription IDs via the following three procedures: - ``wamp.subscription.list``: Returns an object with three lists of the subscription IDs for all current subscriptions for exact matching, prefix matching and wildcard matching. - ``wamp.subscription.lookup``: Returns the subscription ID for an existing subscription to the provided topic URI, or null if no such subscription exists. The matching policy to apply is set as an option, with exact matching applied if this is omitted. - ``wamp.subscription.match``: Returns a list of IDs of subscriptions which match the URI, irrespetive of what matching policy this match is based, i.e. a list of the IDs of all subscriptions which would presently receive a publication to the URI. Example code for retrieving the **lists of current subscriptions**: .. code:: javascript session.call("wamp.subscription.list").then(session.log, session.log) Example code for **looking up a subscription**: .. code:: javascript session.call("wamp.subscription.lookup", ["com.myapp.topic1"]).then(session.log, session.log) .. code:: javascript session.call("wamp.subscription.lookup", ["com.myapp", { match: "prefix" }]).then(session.log, session.log) .. code:: javascript session.call("wamp.subscription.lookup", ["com.myapp..create", { match: "wildcard" }]).then(session.log, session.log) Example code for **matching subscriptions**: .. code:: javascript session.call("wamp.subscription.match", ["com.myapp.topic1"]).then(session.log, session.log) Retrieve information about a subscription ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Using a subscription ID, information about a specific subscription can be retrieved using: - ``wamp.subscription.get``: Returns data about the subscription itself: the subscription URI, ID, matching policy and creation date. - ``wamp.subscription.list_subscribers``: Returns a list of session IDs for sessions currently attached to the subscription. - ``wamp.subscription.count_subscribers``: Returns the number of sessions currently attached to the subscription. Example code for **getting data about a subscription**: .. code:: javascript session.call("wamp.subscription.get", [23560753]).then(session.log, session.log) Example code for **getting the subscribers to a subscription**: .. code:: javascript session.call("wamp.subscription.list_subscribers", [23560753]).then(session.log, session.log) Example code for **getting the subscriber count**: .. code:: javascript session.call("wamp.subscription.count_subscribers", [23560753]).then(session.log, session.log) Forcefully remove a subscriber ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It is possible to forcefully remove an individual subscriber from a subscription by using - ``wamp.subscription.remove_subscriber``: Removes a single subscriber from a subscription based on a provided subscription ID and subscriber ID. Example code for **removing a subscriber**: .. code:: javascript session.call("wamp.subscription.remove_subscriber", [23560753, 483984922713478]).then(session.log, session.log) .. note:: Access the to the meta-API should, of course, be limited in your configuration to avoid rogue clients wreaking havoc on your application. Note: the above examples are for Autobahn\|JS. Users of other WAMP client libraries should feel free to add code examples for these! Working Example --------------- For a full working example in JavaScript, see `Crossbar Examples `__. Event History ------------- For the possibility to retrieve past events for a topic see the :doc:`Event History doc page `.