(#38) Basic pull operation. (#72)

Author: adrianhall

.editorconfig

@@ -386,4 +386,10 @@ dotnet_diagnostic.SA1629.severity = none
 
 dotnet_diagnostic.SA1633.severity = none
 dotnet_diagnostic.SA1634.severity = none
-dotnet_diagnostic.SA1652.severity = none
+dotnet_diagnostic.SA1652.severity = none
+
+# Regular Expression form - We have a lot of regular expressions that are not in the form of a verbatim string. 
+dotnet_diagnostic.SYSLIB1045.severity = none
+
+# Namespace requirements - it's ok to have a namespace that doesn't match the folder structure.
+dotnet_diagnostic.IDE0130.severity = none

src/CommunityToolkit.Datasync.Client/Exceptions/ConflictException.cs

@@ -2,8 +2,6 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
-using CommunityToolkit.Datasync.Client.Service;
-
 namespace CommunityToolkit.Datasync.Client;
 
 /// <summary>

src/CommunityToolkit.Datasync.Client/Exceptions/DatasyncPullException.cs

@@ -0,0 +1,36 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.Diagnostics.CodeAnalysis;
+
+namespace CommunityToolkit.Datasync.Client.Exceptions;
+
+/// <summary>
+/// An internal exception generated during the pull operation.
+/// </summary>
+internal class DatasyncPullException : DatasyncException
+{
+    /// <inheritdoc />
+    [ExcludeFromCodeCoverage]
+    public DatasyncPullException()
+    {
+    }
+
+    /// <inheritdoc />
+    [ExcludeFromCodeCoverage]
+    public DatasyncPullException(string? message) : base(message)
+    {
+    }
+
+    /// <inheritdoc />
+    [ExcludeFromCodeCoverage]
+    public DatasyncPullException(string? message, Exception? innerException) : base(message, innerException)
+    {
+    }
+
+    /// <summary>
+    /// The service response for the error.
+    /// </summary>
+    public required ServiceResponse ServiceResponse { get; init; }
+}

src/CommunityToolkit.Datasync.Client/Offline/DatasyncQueueException.cs renamed to src/CommunityToolkit.Datasync.Client/Exceptions/DatasyncQueueException.cs

@@ -2,8 +2,6 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
-using System.Net;
-
 namespace CommunityToolkit.Datasync.Client.Http;
 
 /// <summary>

src/CommunityToolkit.Datasync.Client/Http/HttpClientFactory.cs

@@ -3,7 +3,8 @@
 // See the LICENSE file in the project root for more information.
 
 using CommunityToolkit.Datasync.Client.Http;
-using CommunityToolkit.Datasync.Client.Offline.Internal;
+using CommunityToolkit.Datasync.Client.Offline.Models;
+using CommunityToolkit.Datasync.Client.Query.Linq;
 
 namespace CommunityToolkit.Datasync.Client.Offline;
 
@@ -83,8 +84,21 @@ public DatasyncOfflineOptionsBuilder UseHttpClientOptions(HttpClientOptions clie
     /// <typeparam name="TEntity">The type of the entity.</typeparam>
     /// <param name="configure">A configuration function for the entity.</param>
     /// <returns>The current builder for chaining.</returns>
-    public DatasyncOfflineOptionsBuilder Entity<TEntity>(Action<EntityOfflineOptions> configure) 
-        => Entity(typeof(TEntity), configure);
+    public DatasyncOfflineOptionsBuilder Entity<TEntity>(Action<EntityOfflineOptions<TEntity>> configure) where TEntity : class
+    {
+        ArgumentNullException.ThrowIfNull(configure, nameof(configure));
+        if (!this._entities.TryGetValue(typeof(TEntity).FullName!, out EntityOfflineOptions? options))
+        {
+            throw new DatasyncException($"Entity is not synchronizable.");
+        }
+
+        EntityOfflineOptions<TEntity> entity = new();
+        configure(entity);
+        options.ClientName = entity.ClientName;
+        options.Endpoint = entity.Endpoint;
+        options.QueryDescription = new QueryTranslator<TEntity>(entity.Query).Translate();
+        return this;
+    }
 
     /// <summary>
     /// Configures the specified entity type for offline operations.
@@ -120,9 +134,10 @@ internal OfflineOptions Build()
         {
             HttpClientFactory = this._httpClientFactory
         };
+
         foreach (EntityOfflineOptions entity in this._entities.Values)
         {
-            result.AddEntity(entity.EntityType, entity.ClientName, entity.Endpoint);
+            result.AddEntity(entity.EntityType, entity.ClientName, entity.Endpoint, entity.QueryDescription);
         }
 
         return result;
@@ -139,14 +154,46 @@ public class EntityOfflineOptions(Type entityType)
         /// </summary>
         public Type EntityType { get => entityType; }
 
+        /// <summary>
+        /// The name of the client to use when requesting a <see cref="HttpClient"/>.
+        /// </summary>
+        public string ClientName { get; set; } = string.Empty;
+
         /// <summary>
         /// The endpoint for the entity type.
         /// </summary>
         public Uri Endpoint { get; set; } = new Uri($"/tables/{entityType.Name.ToLowerInvariant()}", UriKind.Relative);
 
+        /// <summary>
+        /// The query description for the entity type - may be null (to mean "pull everything").
+        /// </summary>
+        internal QueryDescription? QueryDescription { get; set; }
+    }
+
+    /// <summary>
+    /// A typed version of the <see cref="EntityOfflineOptions"/> for setting up queries.
+    /// </summary>
+    /// <typeparam name="TEntity">The type of entity being stored.</typeparam>
+    public class EntityOfflineOptions<TEntity>() where TEntity : class
+    {
+        /// <summary>
+        /// The entity type being configured.
+        /// </summary>
+        public Type EntityType { get => typeof(TEntity); }
+
         /// <summary>
         /// The name of the client to use when requesting a <see cref="HttpClient"/>.
         /// </summary>
         public string ClientName { get; set; } = string.Empty;
+
+        /// <summary>
+        /// The endpoint for the entity type.
+        /// </summary>
+        public Uri Endpoint { get; set; } = new Uri($"/tables/{typeof(TEntity).Name.ToLowerInvariant()}", UriKind.Relative);
+
+        /// <summary>
+        /// The query used to pull the data from the service.
+        /// </summary>
+        public IDatasyncPullQuery<TEntity> Query = new DatasyncPullQuery<TEntity>();
     }
 }

src/CommunityToolkit.Datasync.Client/Offline/DatasyncOfflineOptionsBuilder.cs

@@ -0,0 +1,25 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.ComponentModel.DataAnnotations;
+
+namespace CommunityToolkit.Datasync.Client.Offline;
+
+/// <summary>
+///  A mapping for the delta-token store, which records the last sequence number of
+///  the entity that was synchronized (normally a time stamp).
+/// </summary>
+public class DatasyncDeltaToken
+{
+    /// <summary>
+    /// The ID of the entity type.
+    /// </summary>
+    [Key]
+    public required string Id { get; set; }
+
+    /// <summary>
+    /// The value of the sequence number.
+    /// </summary>
+    public required long Value { get; set; }
+}

src/CommunityToolkit.Datasync.Client/Offline/DbSetExtensions.cs

@@ -0,0 +1,80 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using CommunityToolkit.Datasync.Client.Serialization;
+
+namespace CommunityToolkit.Datasync.Client.Offline.DeltaTokenStore;
+
+/// <summary>
+/// A default implementation of the <see cref="DeltaTokenStore"/> that will
+/// store the delta tokens for each query in an Entity Framework table.
+/// </summary>
+internal class DefaultDeltaTokenStore(OfflineDbContext context) : IDeltaTokenStore
+{
+    /// <summary>
+    /// Obtains the current delta token for a table/queryId from persistent store.
+    /// </summary>
+    /// <param name="queryId">The query ID of the table.</param>
+    /// <param name="cancellationToken">A <see cref="CancellationToken"/> to observe.</param>
+    /// <returns>A task that returns the delta token when complete.</returns>
+    public async Task<DateTimeOffset> GetDeltaTokenAsync(string queryId, CancellationToken cancellationToken = default)
+    {
+        ValidateQueryId(queryId);
+        DatasyncDeltaToken? deltaToken = await context.DatasyncDeltaTokens.FindAsync([queryId], cancellationToken).ConfigureAwait(false);
+        long unixms = deltaToken?.Value ?? 0L;
+        return DateTimeOffset.FromUnixTimeMilliseconds(unixms);
+    }
+
+    /// <summary>
+    /// Resets the delta token for a table/queryId from persistent store.
+    /// </summary>
+    /// <param name="queryId">The query ID of the table.</param>
+    /// <param name="cancellationToken">A <see cref="CancellationToken"/> to observe.</param>
+    /// <returns>A task that completes when the delta token has been reset.</returns>
+    public async Task ResetDeltaTokenAsync(string queryId, CancellationToken cancellationToken = default)
+    {
+        ValidateQueryId(queryId);
+        DatasyncDeltaToken? deltaToken = await context.DatasyncDeltaTokens.FindAsync([queryId], cancellationToken).ConfigureAwait(false);
+        if (deltaToken is not null)
+        {
+            _ = context.DatasyncDeltaTokens.Remove(deltaToken);
+        }
+    }
+
+    /// <summary>
+    /// Sets the delta token for a table/queryId from persistent store.
+    /// </summary>
+    /// <param name="queryId">The query ID of the table.</param>
+    /// <param name="value">The value of the delta token.</param>
+    /// <param name="cancellationToken">A <see cref="CancellationToken"/> to observe.</param>
+    /// <returns>A task that completes when the delta token has been set in the persistent store.</returns>
+    public async Task SetDeltaTokenAsync(string queryId, DateTimeOffset value, CancellationToken cancellationToken = default)
+    {
+        ValidateQueryId(queryId);
+        long unixms = value.ToUnixTimeMilliseconds();
+        DatasyncDeltaToken? deltaToken = await context.DatasyncDeltaTokens.FindAsync([queryId], cancellationToken).ConfigureAwait(false);
+        if (deltaToken is null)
+        {
+            _ = context.DatasyncDeltaTokens.Add(new DatasyncDeltaToken() { Id = queryId, Value = unixms });
+        }
+        else if (deltaToken.Value != unixms)
+        {
+            deltaToken.Value = unixms;
+            _ = context.DatasyncDeltaTokens.Update(deltaToken);
+        }
+    }
+
+    /// <summary>
+    /// Checks to see if the provided queryId is valid.
+    /// </summary>
+    /// <param name="queryId">The queryId to check.</param>
+    /// <exception cref="ArgumentException">Thrown if the queryId is not valid.</exception>
+    private static void ValidateQueryId(string queryId)
+    {
+        if (!EntityResolver.EntityIdIsValid(queryId))
+        {
+            throw new ArgumentException("Provided QueryId is not valid", nameof(queryId));
+        }
+    }
+}

src/CommunityToolkit.Datasync.Client/Offline/DeltaTokenStore/DatasyncDeltaToken.cs

@@ -0,0 +1,36 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+namespace CommunityToolkit.Datasync.Client.Offline;
+
+/// <summary>
+/// The delta token store holds the last sync times for a specific query.
+/// </summary>
+internal interface IDeltaTokenStore
+{
+    /// <summary>
+    /// Obtains the current delta token for a queryId from persistent store.
+    /// </summary>
+    /// <param name="queryId">The query ID of the table.</param>
+    /// <param name="cancellationToken">A <see cref="CancellationToken"/> to observe.</param>
+    /// <returns>A task that returns the delta token when complete.</returns>
+    Task<DateTimeOffset> GetDeltaTokenAsync(string queryId, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Resets the delta token for a queryId from persistent store.
+    /// </summary>
+    /// <param name="queryId">The query ID of the table.</param>
+    /// <param name="cancellationToken">A <see cref="CancellationToken"/> to observe.</param>
+    /// <returns>A task that completes when the delta token has been reset.</returns>
+    Task ResetDeltaTokenAsync(string queryId, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Sets the delta token for a queryId from persistent store.
+    /// </summary>
+    /// <param name="queryId">The query ID of the table.</param>
+    /// <param name="value">The value of the delta token.</param>
+    /// <param name="cancellationToken">A <see cref="CancellationToken"/> to observe.</param>
+    /// <returns>A task that completes when the delta token has been set in the persistent store.</returns>
+    Task SetDeltaTokenAsync(string queryId, DateTimeOffset value, CancellationToken cancellationToken = default);
+}