# 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](#overview) - [Fix an existing server with minimal changes](#fix-an-existing-server-with-minimal-changes) - [Enabling durable subscriptions on an existing server](#enabling-durable-subscriptions-on-an-existing-server) - [Known limitations and issues](#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](../samples/Quickstarts.Servers/DurableSubscription/DurableMonitoredItemQueueFactory.cs). - 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.