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.
• 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.