Skip to main content

Presence Subscriptions Management

Context: Subscription Lifecycle​

The subscription lifecycle semantics used by XMPP and SIP differ between the protocols, and these differences need to be reconciled by the Gateway. This has an impact on behavior and configuration, so it is useful to consider the two systems:

  • SIP models subscriptions as a semi-automated process where subscriptions are expressed using short-lived "sessions". These sessions are expected to be terminated regularly, without changing the underlying contact relationship between users, or their desire to be subscribed.
  • XMPP models subscriptions as a manual process, requiring explicit user participation and approval of subscription requests. Subscriptions are thought of as long-lived relationships between users, termination of which expresses the desire of a user for presence updates to stop.

Subscription Persistence​

The Gateway maintains an internal view of presence subscription state in order to ensure reliable forwarding of presence information. This state can be broken down into:

  1. A view of the current status of a subscription, tracking its progress through negotiation, acceptance, etc.
  2. A handle to any active SIP subscription "sessions" (as described above). These sessions are needed to send/receive presence updates, negotiate subscriptions, etc.

All of this information is stored in-memory and is lost (or is terminated in the case of the subscription sessions) when the Gateway service stops. Crucially, the external systems and users do not lose this information and, in many cases, will believe that their subscriptions are still active. This state must therefore be persisted and recovered when needed so that the Gateway's internal state remains consistent with that of external services and presence updates continue to propagate.

Subscription Recovery​

To facilitate subscription recovery after Gateway service downtime, various options are exposed in configuration to enable subscription persistence features. These are described in detail in Installation and Configuration with the relevant settings being PresenceSubscriptionPersistenceEnabled, DatabaseConnectionString, SubscriptionRecoveryBatchSize, SubscriptionRecoveryBatchIntervalSeconds.

caution

Subscription persistence and recovery are not hard deployment requirements for the Gateway and require Microsoft SQL Server for persistent storage.

However, a deployment without these features enabled will be prone to state inconsistencies across restarts which will require manual user action to rectify. Such a deployment would likely only be useful for initial testing.

Configuration of subscription persistence will cause database entries to be written to track all active subscriptions, as well as the time at which each subscription was activated. On Gateway startup, the following process will then take place automatically:

  1. Recovery of a batch of subscriptions will be scheduled to occur after an elapsed time interval configured by SubscriptionRecoveryBatchIntervalSeconds.
  2. Batch recovery begins by fetching a batch of stale-timestamped subscription records from the database. The number of subscription records in the batch is configured by SubscriptionRecoveryBatchSize.
  3. Any necessary subscription "sessions" are re-established in order to recover these subscriptions (SIP subscriptions only).*
  4. In-memory subscription state is recovered for the batch. When processing subscription operations for one of these subscriptions, the Gateway will now consider the subscription to be active.
  5. Repeat from step 1.

Note that records and state are tracked by both the XMPP and SIP adapters, and each subscription record represents a unidirectional subscription.

Additionally, this process is guaranteed to take place when handling a request for a subscription. If the subscription has not yet been recovered in the above batched manner, it will be automatically recovered when needed.

Database Resiliency​

Note that transient infrastructural issues may cause issues when database operations are performed by the Gateway. A couple of automated safeguards are in-place to limit the effect of such issues.

  1. Database operations are subject to internal resiliency policies. Namely:
    1. Failed operations will be automatically retried a small number of times.
    2. Consistent failure of database operations will active a "circuit breaker" mechanism. This prevents operations for a time and will re-activate if failures persist.
  2. All subscription state is maintained in-memory. Recovery of a faulty persistence layer (detected by the above circuit breaker mechanism) will result in the database being updated will all up-to-date records which are stored in-memory.

Note that the application of these resiliency policies will be visible in service logs and Metrics.

Limitations​

Re-establishment of "inbound" SIP subscriptions​

The subscription recovery process described above states that the necessary subscription sessions are re-established when the corresponding subscriptions are processed during recovery. This is only strictly true for "outbound" subscription sessions, which can be initialized and negotiated by the Gateway with no external action required. These "outbound" sessions are used for subscriptions from XMPP users to SfB users, so these subscriptions can be fully recovered during the recovery process and XMPP users will continue to receive presence updates.

However, "inbound" subscription sessions require action from the external SfB deployment in order for negotiation to begin. This process cannot be started automatically by the Gateway.

Impact: Subscriptions from SfB users to XMPP users will not be recovered until the underlying session is re-established by SfB. This will likely happen automatically after a short time, or when the SfB user logs out and back in to their SfB client. Until this happens, SfB users will not receive presence updates.

SIP subscription lifecycle​

Internal modelling of subscriptions and subscription events within the Gateway largely follows the XMPP model of subscription lifecycle (see the top of this page), meaning that the Gateway takes certain automatic actions to attempt to align SIP traffic with this model. These are the main effects that users may notice:

  1. Subscription requests received by the Gateway from SfB are automatically accepted. This allows the Gateway to fulfil certain time-based requirements when communicating with SfB, as the destination XMPP user is not required to send a timely approval or rejection of the request.
    Impact: SfB users will likely see their subscription as "Updating…" until such a response is received.
  2. Subscription requests received by the Gateway from SfB may be automatically rejected. If a subscription is cancelled or rejected by an XMPP user, further subscription requests from SfB will be automatically rejected during a resulting "cooldown period". This allows the Gateway to honor the cancellation, since SfB automatically attempts to resubscribe shortly afterwards. Forwarding these resubscriptions to the XMPP user is clearly undesirable. Note that this cooldown period is configurable via the SipAdapter.CancelledSubscriptionCooldownSeconds setting described in Installation and Configuration and can be disabled by setting a value of 0.
    Impact: SfB users may see their subscriptions fail for this reason.
  3. Subscription termination received by the Gateway from SfB will not be forwarded. As discussed, frequent termination of SIP subscriptions is expected and does not represent a user’s desire to stop presence updates, so is inappropriate to forward to the XMPP user.
    Impact: XMPP users may believe that SfB users are still receiving their presence updates, even after the SfB user has unsubscribed.