How Subscriptions Work¶
With the Publish & Subscribe (PubSub) messaging pattern in WAMP, a WAMP client issues a subscription request to a router, in which it expresses interest in a topic. The router registers this. Whenever a publication to this topic comes in, an event is dispatched to all WAMP clients which are currently registered for the topic.
Note: WAMP uses URIs to identify topics. There are some specific rules regarding URI formatting.
For example, any WAMP client which has registered a subscription for the
topic com.myapp.topic1
receives an event whenever any other client
publishes to the topic com.myapp.topic1
. (The “any other” is
because as a default, no event is dispatched to the publisher itself if
it is subscribed to the topic. This behavior can be overriden by setting
exclude_me=False
in PublishOptions
when calling publish()
).
The ‘subscription’, as the term is used here, exists within the router. A subscription is created when a client sends a subscription request for a topic where there are currently no other subscribers. It is deleted when the last subscriber cancels its subscriptions, or its session is disconnected.
A subscriber receives a subscription ID as the result of a successful
subscription request. E.g. say a client issues a subscription request
for a topic com.myapp.topic1
, it could receive the subscription ID
748038973
on success. This subscription ID is used as part of the
unsubscribe request, i.e. an unsubscribe does not contain a topic URI,
but a subscription ID.
When an second subscriber issues a subscription request for the same
topic, then it receives the same subscription ID. For
com.myapp.topic1
, it would also receive 748038973
.
When the subscription is deleted, e.g. because the above two clients both issue an unsubscribe for the topic, and then a client issues a subscription request for the same topic, a new subscription is created, and the client receives a new subscription ID.
The act of subscribing and unsubscribing may create or delete a subscription. It necessarily adds or removes a session from a subscription.
The creation and deletion of subscriptions, as well as the addition or removal of sessions to a subscription lead to subscription meta-events, to which you can subscribe. It is also possible to retrieve information about currently existing subscriptions. For more information see Subscription Meta-Events and Procedures .
The above explanation used a topic string which was fully matched. WAMP additionally allows for pattern-based subscriptions in two flavors: prefix registration and wildcard registration. These are explained in Pattern-Based Subscriptions .
There is also the possibility to exclude certain sessions from receiving an event, or to restrict publication to a certain set of sessions - see Subscriber Black- and Whitelisting .
There is normally no need for subscribers to know the identity of a publisher, but if required it is possible to disclose this information - see Publisher Identification .
As a default, Publishers do not receive an event if they are also a Subsciber, but this can be overriden - see Publisher Exclusion .