scadalink-design/lmxproxy/docs/requirements/Component-SubscriptionManager.md

Component: SubscriptionManager

Purpose

Manages the lifecycle of tag value subscriptions, multiplexing multiple client subscriptions onto shared MXAccess tag subscriptions and delivering updates via per-client bounded channels with configurable backpressure.

Location

src/ZB.MOM.WW.LmxProxy.Host/Subscriptions/SubscriptionManager.cs

Responsibilities

• Create per-client subscription channels with bounded capacity.
• Share underlying MXAccess tag subscriptions across multiple clients subscribing to the same tags.
• Deliver tag value updates from MXAccess callbacks to all subscribed clients.
• Handle backpressure when client channels are full (DropOldest, DropNewest, or Wait).
• Clean up subscriptions on client disconnect.
• Notify all subscribed clients with bad quality when MXAccess disconnects.

1. Architecture

1.1 Per-Client Channels

Each subscribing client gets a bounded System.Threading.Channel<(string address, Vtq vtq)>:

• Capacity: configurable (default 1000 messages).
• Full mode: configurable (default DropOldest).
• SingleReader = true, SingleWriter = false.

1.2 Shared Tag Subscriptions

Tag subscriptions to MXAccess are shared across clients:

• When the first client subscribes to a tag, a new MXAccess subscription is created.
• When additional clients subscribe to the same tag, they are added to the existing tag subscription's client set.
• When the last client unsubscribes from a tag, the MXAccess subscription is disposed.

1.3 Thread Safety

• ReaderWriterLockSlim protects tag subscription updates.
• ConcurrentDictionary for client subscription tracking.

2. Subscription Flow

2.1 Subscribe

SubscribeAsync(clientId, addresses, ct):

1. Creates a bounded channel with configured capacity and full mode.
2. Creates a ClientSubscription record (clientId, channel, address set, CancellationTokenSource, counters).
3. For each tag address:
   • If the tag already has a subscription, adds the client to the existing TagSubscription.clientIds set.
   • Otherwise, creates a new TagSubscription and calls _scadaClient.SubscribeAsync() to register with MXAccess (outside the lock to avoid blocking).
4. Registers a cancellation token callback to automatically call UnsubscribeClient on disconnect.
5. Returns the channel reader for the GrpcServer to stream from.

2.2 Value Updates

OnTagValueChanged(address, Vtq) — called from MxAccessClient's COM event handler:

1. Looks up the tag subscription to find all subscribed clients.
2. For each client, calls channel.Writer.TryWrite((address, vtq)).
3. If the channel is full:
   • DropOldest: Logs a warning, increments DroppedMessageCount. The oldest message is automatically discarded by the channel.
   • DropNewest: Drops the incoming message.
   • Wait: Blocks the writer until space is available (not recommended for gRPC streaming).
4. On channel closed (client disconnected), schedules UnsubscribeClient cleanup.

2.3 Unsubscribe

UnsubscribeClient(clientId):

1. Removes the client from the client dictionary.
2. For each tag the client was subscribed to, removes the client from the tag's subscriber set.
3. If a tag has no remaining subscribers, disposes the MXAccess subscription handle.
4. Completes the client's channel writer (signals end of stream).

3. Backpressure

Mode	Behavior	Use Case
DropOldest	Silently discards oldest message when channel is full	Default. Fire-and-forget semantics. No client blocking.
DropNewest	Drops the incoming message when channel is full	Preserves history, drops latest updates.
Wait	Blocks the writer until space is available	Not recommended for gRPC streaming (blocks callback thread).

Per-client statistics track DeliveredMessageCount and DroppedMessageCount for monitoring via the status dashboard.

4. Disconnection Handling

4.1 Client Disconnect

When a client's gRPC stream ends (cancellation or error), the cancellation token callback triggers UnsubscribeClient, which cleans up all tag subscriptions for that client.

4.2 MxAccess Disconnect

OnConnectionStateChanged — when the MxAccess connection drops:

• Sends a bad-quality Vtq to all subscribed clients via their channels.
• Each client receives an async notification of the connection loss.
• Tag subscriptions are retained in memory for reconnection (via MxAccessClient's _storedSubscriptions).

5. Statistics

GetSubscriptionStats() returns:

• TotalClients — number of active client subscriptions.
• TotalTags — number of unique tags with active MXAccess subscriptions.
• ActiveSubscriptions — total client-tag subscription count.

Dependencies

• MxAccessClient (IScadaClient) — creates and disposes MXAccess tag subscriptions.
• Configuration — SubscriptionConfiguration for channel capacity and full mode.

Interactions

• GrpcServer calls SubscribeAsync on Subscribe RPC and reads from the returned channel.
• MxAccessClient delivers value updates via the OnTagValueChanged callback.
• HealthAndMetrics reads subscription statistics for health checks and status reports.
• ServiceHost disposes the SubscriptionManager at shutdown.