Live query server error management

Author: theSlyest

Parse/Abstractions/Platform/LiveQueries/IParseLiveQueryController.cs

@@ -1,5 +1,7 @@
+using System;
 using System.Threading;
 using System.Threading.Tasks;
+using Parse.Platform.LiveQueries;
 
 namespace Parse.Abstractions.Platform.LiveQueries;
 
@@ -9,13 +11,105 @@ namespace Parse.Abstractions.Platform.LiveQueries;
 /// </summary>
 public interface IParseLiveQueryController
 {
+    /// <summary>
+    /// Event triggered when an error occurs during the operation of the ParseLiveQueryController.
+    /// </summary>
+    /// <remarks>
+    /// This event provides details about a live query operation failure, such as specific error messages,
+    /// error codes, and whether automatic reconnection is recommended.
+    /// It is raised in scenarios like:
+    /// - Receiving an error response from the LiveQuery server.
+    /// - Issues with subscriptions, unsubscriptions, or query updates.
+    /// Subscribers to this event can use the provided <see cref="ParseLiveQueryErrorEventArgs"/> to
+    /// understand the error and implement appropriate handling mechanisms.
+    /// </remarks>
+    public event EventHandler<ParseLiveQueryErrorEventArgs> Error;
+
+    /// <summary>
+    /// Establishes a connection to the live query server asynchronously.
+    /// </summary>
+    /// <param name="cancellationToken">
+    /// A cancellation token that can be used to cancel the connection process. If the token is triggered,
+    /// the connection process will be terminated.
+    /// </param>
+    /// <returns>
+    /// A task that represents the asynchronous connection operation.
+    /// </returns>
+    /// <exception cref="TimeoutException">
+    /// Thrown when the connection request times out before receiving confirmation from the server.
+    /// </exception>
     Task ConnectAsync(CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// Subscribes to a live query, enabling real-time updates for the specified query object.
+    /// </summary>
+    /// <typeparam name="T">
+    /// The type of the ParseObject associated with the live query.
+    /// </typeparam>
+    /// <param name="liveQuery">
+    /// The live query instance to subscribe to. It contains details about the query and its parameters.
+    /// </param>
+    /// <param name="cancellationToken">
+    /// A token to monitor for cancellation requests. It allows the operation to be canceled if requested.
+    /// </param>
+    /// <returns>
+    /// An object representing the active subscription for the specified query, enabling interaction with the subscribed events and updates.
+    /// </returns>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when attempting to subscribe while the live query connection is in a closed state.
+    /// </exception>
+    /// <exception cref="TimeoutException">
+    /// Thrown when the subscription request times out before receiving confirmation from the server.
+    /// </exception>
     Task<IParseLiveQuerySubscription> SubscribeAsync<T>(ParseLiveQuery<T> liveQuery, CancellationToken cancellationToken = default) where T : ParseObject;
 
+    /// <summary>
+    /// Updates an active subscription. This method modifies the parameters of an existing subscription for a specific query.
+    /// </summary>
+    /// <param name="liveQuery">
+    /// The live query object that holds the query parameters to be updated.
+    /// </param>
+    /// <param name="requestId">
+    /// The unique identifier of the subscription to update.
+    /// </param>
+    /// <param name="cancellationToken">
+    /// A token to monitor for cancellation requests, allowing the operation to be cancelled before completion.
+    /// </param>
+    /// <typeparam name="T">
+    /// The type of the ParseObject that the query targets.
+    /// </typeparam>
+    /// <returns>
+    /// A task that represents the asynchronous operation of updating the subscription.
+    /// </returns>
     Task UpdateSubscriptionAsync<T>(ParseLiveQuery<T> liveQuery, int requestId, CancellationToken cancellationToken = default) where T : ParseObject;
 
+    /// <summary>
+    /// Unsubscribes from a live query subscription associated with the given request identifier.
+    /// </summary>
+    /// <param name="requestId">
+    /// The unique identifier of the subscription to unsubscribe from.
+    /// </param>
+    /// <param name="cancellationToken">
+    /// A cancellation token that can be used to cancel the unsubscription operation before completion.
+    /// </param>
+    /// <returns>
+    /// A task that represents the asynchronous unsubscription operation.
+    /// </returns>
+    /// <exception cref="TimeoutException">
+    /// Thrown if the unsubscription process does not complete within the specified timeout period.
+    /// </exception>
     Task UnsubscribeAsync(int requestId, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// Closes the live query connection asynchronously.
+    /// </summary>
+    /// <param name="cancellationToken">
+    /// A token to monitor for cancellation requests while closing the live query connection.
+    /// If the operation is canceled, the task will terminate early.
+    /// </param>
+    /// <returns>
+    /// A task that represents the asynchronous operation of closing the live query connection.
+    /// The task completes when the connection is fully closed and resources are cleaned up.
+    /// </returns>
     Task CloseAsync(CancellationToken cancellationToken = default);
 }

Parse/Platform/LiveQueries/ParseLiveQueryController.cs

@@ -267,18 +267,17 @@ private void WebSocketClientOnMessageReceived(object sender, string e)
         => ProcessMessage(JsonUtilities.Parse(e) as IDictionary<string, object>);
 
     /// <summary>
-    /// Establishes a connection to the live query server asynchronously. This method initiates the connection process,
-    /// manages connection states, and handles any timeout scenarios if the connection cannot be established within the specified duration.
+    /// Initiates a connection to the live query server asynchronously.
     /// </summary>
     /// <param name="cancellationToken">
-    /// A cancellation token that can be used to cancel the connection process. If the token is triggered,
-    /// the connection process will be terminated.
+    /// A cancellation token to monitor for cancellation requests.
     /// </param>
     /// <returns>
-    /// A task that represents the asynchronous connection operation. If the connection is successful,
-    /// the task will complete when the connection is established. In the event of a timeout or error,
-    /// it will throw the appropriate exception.
+    /// A task representing the asynchronous operation.
     /// </returns>
+    /// <exception cref="TimeoutException">
+    /// Thrown if the connection attempt exceeds the specified timeout period.
+    /// </exception>
     public async Task ConnectAsync(CancellationToken cancellationToken = default)
     {
         if (State == ParseLiveQueryState.Closed)

Parse/Utilities/ObjectServiceExtensions.cs

@@ -10,6 +10,7 @@
 using Parse.Infrastructure.Utilities;
 using Parse.Infrastructure.Data;
 using System.Diagnostics;
+using Parse.Platform.LiveQueries;
 
 namespace Parse;
 
@@ -293,9 +294,13 @@ public static ParseQuery<ParseObject> GetQuery(this IServiceHub serviceHub, stri
     /// </summary>
     /// <param name="serviceHub">The service hub instance containing the Live Query controller to manage the connection.</param>
     /// <returns>A task that represents the asynchronous operation of connecting to the Live Query server.</returns>
-    public static async Task ConnectLiveQueryServerAsync(this IServiceHub serviceHub)
+    public static async Task ConnectLiveQueryServerAsync(this IServiceHub serviceHub, EventHandler<ParseLiveQueryErrorEventArgs> onError = null)
     {
         await serviceHub.LiveQueryController.ConnectAsync();
+        if (onError is not null)
+        {
+            serviceHub.LiveQueryController.Error += onError;
+        }
     }
 
     /// <summary>