UA-.NETStandard/docs/DurableSubscription.md

Durable Subscription

Overview

Durable subscriptions let servers retain subscriptions for longer periods and use large notification queues. If a client disconnects, the server continues sampling values. After reconnecting, the client can use the TransferSubscriptions service to retrieve missed notifications.

Contents

• Overview
• Fix an existing server with minimal changes
• Enabling durable subscriptions on an existing server
• Known limitations and issues

Fix an existing server with minimal changes

• If you implement a custom INodeManager or override CreateMonitoredItems, add the createDurable parameter. You can ignore it while durable subscriptions are disabled in the server configuration.
• Implement INodeManager.RestoreMonitoredItems. The server calls this method only when durable subscriptions are enabled.
• If you implement a custom IMonitoredItem, set IsDurable to false and implement Dispose.

Enabling durable subscriptions on an existing server

Typically the following porting steps are necessary:

• Implement IMonitoredItemQueueFactory and set SupportsDurableQueues to true. Return an IMonitoredItemQueue that persists values and supports large queue sizes. See the sample DurableMonitoredItemQueueFactory.
• Register the queue factory by overriding StandardServer.CreateMonitoredItemQueueFactory.
• Implement ISubscriptionStore to persist and restore subscriptions across server restarts. After restoring a subscription, the store must also provide persistent queues to its monitored items. Register the store by overriding StandardServer.CreateSubscriptionStore.
• Report a store that cannot read its subscriptions from RestoreSubscriptionsAsync, either by throwing or by returning RestoreSubscriptionResult.Success = false; return Success = true with no subscriptions when nothing was stored. Keep the stored subscriptions and the queue snapshots of their monitored items until OnSubscriptionRestoreCompleteAsync is called: the server calls it only after it has recreated every stored subscription, so a store that deletes its data while reading it loses the subscriptions when the restore fails.
• A failed restore fails SubscriptionManager.RestoreSubscriptionsAsync and with it the server startup: a store failure surfaces as a ServiceResultException (BadInternalError), stored subscriptions that cannot be recreated as an AggregateException. To start anyway, set SubscriptionManager.ContinueOnRestoreFailure to true in an override of StandardServer.CreateSubscriptionManager; failures are then logged as errors and warnings, and the subscriptions concerned are lost. A restore that fails or is cancelled deletes the subscriptions it already recreated without storing them; it keeps the stored contents of their monitored item queues and resets what it set on the stored subscriptions and monitored items the store returned, so the store may return the same objects to a retry. A server startup that fails releases its session and subscription managers, so the restore can be retried by starting again.
• A queue whose contents are kept in storage while the server runs, and which disposing removes from that storage, should implement IRestorableMonitoredItemQueue. While SubscriptionManager.RestoreSubscriptionsAsync restores the subscriptions it calls BeginRestore before it changes such a queue of a restored monitored item; the queue must then not write to its storage. When every stored subscription was restored and the store was told so, the server calls CommitRestore, and the queue writes its current contents once and resumes writing. The restore can no longer be rolled back then, so CommitRestore must not throw: a queue that cannot write handles the failure itself, e.g. logs it and writes on its next change; the server logs an exception it throws and commits the other queues. When the restore fails or is cancelled the server calls AbortRestore and disposes the queue; the queue must drop every write it has not started, never start a write again, and not remove its stored contents on dispose, because the retry reads them again. A write already in progress when AbortRestore is called cannot be recalled and may complete; a queue staged by BeginRestore starts no write before CommitRestore, so its stored contents stay exactly as they were. A queue disposed after BeginRestore but before CommitRestore, e.g. because a node manager failed to create its monitored item, must keep its stored contents as well. The mirrored queues of SharedKeyValueMonitoredItemQueueFactory implement it. Only the base SubscriptionManager.RestoreSubscriptionsAsync stages queues: a monitored item restored outside of it, e.g. by calling Subscription.RestoreAsync or the restoring MonitoredItem constructor directly, writes its queue to storage at once, as before.
• If you implement a custom INodeManager or override CreateMonitoredItems, add the createDurable parameter and pass it to the MonitoredItem constructor. When you check queue length for a durable subscription, compare it with the durable queue limit in ServerConfiguration.
• If you implement a custom IMonitoredItem, add the createDurable constructor parameter, implement IsDurable, and implement Dispose.
• In a custom MonitoredItem, use IServerInternal.MonitoredItemQueueFactory to get the registered durable queues for events and value changes instead of using internal queues.
• To test custom queues, adapt the monitored-item tests in the server test project. Provide your IMonitoredItemQueueFactory in the test constructor.

Configure durable subscriptions in ServerConfiguration:

• Set DurableSubscriptionsEnabled to true
• Set MaxDurableNotificationQueueSize to the desired value
• Set MaxDurableEventQueueSize to the desired value
• Set MaxDurableSubscriptionLifetime to the desired value

Known limitations and issues

• The Quickstarts queues return false from Dequeue while a batch is being persisted or cannot be restored within the bounded wait. The queue retains the item count for a later attempt. A failed restore does not mean the batch data is resident. The store deletes restored batch files after their readers close.
• The server persists subscriptions only during a graceful shutdown. A crash or forced shutdown loses all subscriptions and monitored items.
• The Quickstarts durable-subscription store writes format version 3. It can read version 1 records, which enable publishing but do not persist the owning application URI. The store rejects retired version 2 records. Current records persist publishing state and the owning client ApplicationUri, allowing anonymous durable subscriptions to transfer after restart. The store removes user-name passwords before persistence. It does not persist issued-token subscriptions because their bearer token is their identity.
• Breaking change: The INodeManager and IMonitoredItem interfaces were extended to support durable subscriptions.