Data Models

This document describes the data models used throughout the WebSocket Manager.

WebSocketConnection

Namespace: Virtufin.WebSocketManager.Models

Purpose: Represents a managed external WebSocket connection. Contains both connection metadata and runtime state.

Properties

Property	Type	Default	Description
`Id`	`string`	`Guid.NewGuid().ToString()`	Unique identifier for this connection
`Url`	`string`	`string.Empty`	WebSocket server URL
`Status`	`ConnectionStatus`	`Disconnected`	Current connection status
`Topic`	`string?`	`null`	Dapr pub/sub topic for publishing messages
`AutoReconnect`	`bool`	`false`	Whether to automatically reconnect on failure
`CreatedAt`	`DateTime`	`DateTime.UtcNow`	When this connection was created
`InstanceId`	`string?`	`null`	ID of the service instance that owns this connection
`WebSocket`	`ClientWebSocket?`	`null`	The underlying WebSocket instance (runtime only)
`CancellationTokenSource`	`CancellationTokenSource?`	`null`	Token source for the receive loop (runtime only)
`ReceiveTask`	`Task?`	`null`	Background task running the receive loop (runtime only)

Runtime vs. Persisted Properties

The following properties are persisted to Dapr state store: - Id, Url, Status, Topic, AutoReconnect, CreatedAt, InstanceId

These properties are runtime-only and not persisted: - WebSocket, CancellationTokenSource, ReceiveTask

Usage Example

var connection = new WebSocketConnection
{
    Id = Guid.NewGuid().ToString(),
    Url = "wss://example.com/socket",
    Status = ConnectionStatus.Connected,
    AutoReconnect = true,
    InstanceId = instanceIdProvider.GetInstanceId()
};

ConnectionStatus

Namespace: Virtufin.WebSocketManager.Models

Purpose: Enumeration representing the current state of a WebSocket connection.

Values

Value	Description
`Disconnected`	The WebSocket is not connected
`Connecting`	The WebSocket connection is being established
`Connected`	The WebSocket is connected and ready for communication
`Reconnecting`	The WebSocket is attempting to reconnect after a connection loss

State Transitions

Disconnected ──▶ Connecting ──▶ Connected
                    │               │
                    │               │
                    ▼               ▼
               Reconnecting ◀──────┘
                    │
                    ▼
               Disconnected

DaprStateStoreEntry

Namespace: Virtufin.WebSocketManager.Services

Purpose: Represents a WebSocket connection entry stored in Dapr state store. This is the serialization format used for persistence.

Properties

Property	Type	Default	Description
`Id`	`string`	`string.Empty`	Unique identifier for this connection
`Url`	`string`	`string.Empty`	WebSocket server URL
`Status`	`ConnectionStatus`	`Disconnected`	Current connection status
`Topic`	`string?`	`null`	Dapr pub/sub topic for publishing messages
`AutoReconnect`	`bool`	`false`	Whether to automatically reconnect on failure
`CreatedAt`	`DateTime`	`DateTime.UtcNow`	When this connection was created
`InstanceId`	`string?`	`null`	ID of the service instance that owns this connection

Conversion Methods

FromConnection

Creates a DaprStateStoreEntry from a WebSocketConnection.

public static DaprStateStoreEntry FromConnection(WebSocketConnection connection)

Parameters: | Parameter | Type | Description | |-----------|------|-------------| | connection | WebSocketConnection | The connection to convert |

Returns: A new DaprStateStoreEntry with all persistable properties copied.

ToConnection

Creates a WebSocketConnection from a DaprStateStoreEntry.

public WebSocketConnection ToConnection()

Returns: A new WebSocketConnection with properties copied from this entry.

Note: The returned connection will have null for runtime properties (WebSocket, CancellationTokenSource, ReceiveTask).

MessageEnvelope

Internal Record - Not for external use

Namespace: Virtufin.WebSocketManager.Services

Purpose: Internal record used by DaprPublisher to wrap messages before publishing to Dapr pub/sub.

Structure

private record MessageEnvelope(
    string WebsocketId,
    string WebsocketUrl,
    DateTime Timestamp,
    string Payload
);

Properties

Property	Type	Description
`WebsocketId`	`string`	ID of the WebSocket connection that received the message
`WebsocketUrl`	`string`	URL of the WebSocket connection
`Timestamp`	`DateTime`	When the message was received (UTC)
`Payload`	`string`	The raw message payload

Usage

var envelope = new MessageEnvelope(connection.Id, connection.Url, DateTime.UtcNow, message);
await daprClient.PublishEventAsync(pubsubComponent, topic, envelope);

Subscribers

Subscribers to the pub/sub topic will receive messages in this envelope format, allowing them to: - Identify which WebSocket connection received the message - Track when the message was received - Access the original payload

WebSocketOptions

Namespace: Virtufin.WebSocketManager.Services.Options

Purpose: Configuration options for WebSocket client behavior. See Configuration Documentation for full details.

Key Prefixes and Constants

For reference, the key patterns used in Dapr state store:

Constant	Value	Usage
`DaprConstants.KeyPrefix`	`"websocket-"`	Prefix for connection entry keys
`DaprConstants.IndexKey`	`"websocket-index"`	Key for the connection ID index

Key Examples

Connection entry: websocket-abc123 (where abc123 is the connection ID)
Index: websocket-index (contains HashSet<string> of all connection IDs)