(#34) CRUD for remote dataset (#50)

* (#34) Remote dataset, exceptions, and tests

Author: adrianhall

Datasync.Toolkit.sln

@@ -5,12 +5,13 @@ VisualStudioVersion = 17.0.31903.59
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{84AD662A-4B9E-4E64-834D-72529FB7FCE5}"
 	ProjectSection(SolutionItems) = preProject
-		src\Shared.Build.props = src\Shared.Build.props
+		src\Directory.Build.props = src\Directory.Build.props
 	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{D59F1489-5D74-4F52-B78B-88037EAB2838}"
 	ProjectSection(SolutionItems) = preProject
-		tests\Shared.Build.props = tests\Shared.Build.props
+		tests\Directory.Build.props = tests\Directory.Build.props
+		tests\EFCore.Packages.props = tests\EFCore.Packages.props
 	EndProjectSection
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CommunityToolkit.Datasync.Server.Abstractions", "src\CommunityToolkit.Datasync.Server.Abstractions\CommunityToolkit.Datasync.Server.Abstractions.csproj", "{852F8266-603E-4FC6-A5CB-E492E747924F}"
@@ -59,9 +60,9 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CommunityToolkit.Datasync.S
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CommunityToolkit.Datasync.Server.Swashbuckle", "src\CommunityToolkit.Datasync.Server.Swashbuckle\CommunityToolkit.Datasync.Server.Swashbuckle.csproj", "{45D47A4E-AD58-40C8-B4CC-95BC888C47A7}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CommunityToolkit.Datasync.Client", "src\CommunityToolkit.Datasync.Client\CommunityToolkit.Datasync.Client.csproj", "{D3B72031-D4BD-44D3-973C-2752AB1570F6}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CommunityToolkit.Datasync.Client", "src\CommunityToolkit.Datasync.Client\CommunityToolkit.Datasync.Client.csproj", "{D3B72031-D4BD-44D3-973C-2752AB1570F6}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CommunityToolkit.Datasync.Client.Test", "tests\CommunityToolkit.Datasync.Client.Test\CommunityToolkit.Datasync.Client.Test.csproj", "{2889E6B2-9CD1-437C-A43C-98CFAFF68B99}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CommunityToolkit.Datasync.Client.Test", "tests\CommunityToolkit.Datasync.Client.Test\CommunityToolkit.Datasync.Client.Test.csproj", "{2889E6B2-9CD1-437C-A43C-98CFAFF68B99}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution

src/CommunityToolkit.Datasync.Client/CommunityToolkit.Datasync.Client.csproj

@@ -3,10 +3,8 @@
     <Description>The client capabilities for developing applications using the Datasync Toolkit.</Description>
   </PropertyGroup>
 
-  <Import Project="..\Shared.Build.props" />
-
   <ItemGroup>
-    <InternalsVisibleTo Include="CommunityToolkit.Datasync.Client.Test"/>
+    <InternalsVisibleTo Include="CommunityToolkit.Datasync.Client.Test" />
   </ItemGroup>
 
   <ItemGroup>

src/CommunityToolkit.Datasync.Client/DatasyncClient.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.
 
-#pragma warning disable IDE0058 // Expression value is never used
-
 using CommunityToolkit.Datasync.Client.Http;
 using CommunityToolkit.Datasync.Common;
 using System.Diagnostics.CodeAnalysis;
@@ -22,6 +20,7 @@ public class DatasyncClient : IDisposable
     protected DatasyncClient()
     {
         ClientOptions = new DatasyncClientOptions();
+        ServiceOptions = new DatasyncServiceOptions();
         Endpoint = new Uri("http://localhost/");
         HttpClientFactory = new DefaultHttpClientFactory(Endpoint, new HttpClientOptions());
     }
@@ -62,13 +61,10 @@ public DatasyncClient(string endpoint, DatasyncClientOptions options) : this(new
     /// <exception cref="UriFormatException">if the endpoint is not a valid datasync Uri.</exception>
     public DatasyncClient(Uri endpoint, DatasyncClientOptions options)
     {
-        Ensure.That(endpoint, nameof(endpoint)).IsNotNull().And.IsDatasyncEndpoint();
-        Ensure.That(options, nameof(options)).IsNotNull();
-
-        ClientOptions = options;
+        Endpoint = NormalizeEndpoint(Ensure.That(endpoint, nameof(endpoint)).IsNotNull().And.IsDatasyncEndpoint().Value);
+        ClientOptions = Ensure.That(options, nameof(options)).IsNotNull().Value;
         ServiceOptions = options.DatasyncServiceOptions;
-        Endpoint = NormalizeEndpoint(endpoint);
-        HttpClientFactory = options.HttpClientFactory ?? new DefaultHttpClientFactory(endpoint, new HttpClientOptions());
+        HttpClientFactory = options.HttpClientFactory ?? new DefaultHttpClientFactory(Endpoint, new HttpClientOptions());
     }
 
     /// <summary>

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

@@ -0,0 +1,58 @@
+// 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;
+using System.Text.Json;
+
+namespace CommunityToolkit.Datasync.Client;
+
+/// <summary>
+/// An exception used by the Datasync client library to report server conflict errors.
+/// </summary>
+/// <typeparam name="T">The type of entity in conflict</typeparam>
+public class ConflictException<T> : DatasyncHttpException where T : notnull
+{
+    /// <inheritdoc />
+    public ConflictException(string? message) : base(message)
+    {
+    }
+
+    /// <inheritdoc />
+    [ExcludeFromCodeCoverage(Justification = "Standard exception constructor")]
+    public ConflictException(string? message, Exception? innerException) : base(message, innerException)
+    {
+    }
+
+    /// <summary>
+    /// The parsed server-side entity (or null).
+    /// </summary>
+    public T? ServerEntity { get; set; } = default;
+
+    /// <summary>
+    /// Creates a new <see cref="ConflictException{T}"/> for the response.
+    /// </summary>
+    /// <param name="responseMessage">The <see cref="HttpResponseMessage"/> that is creating the exception.</param>
+    /// <param name="serializerOptions">The JSON serializer options to use for deserializing content.</param>
+    /// <param name="cancellationToken">A <see cref="CancellationToken"/> to observe.</param>
+    /// <returns></returns>
+    public static async Task<ConflictException<T>> CreateAsync(HttpResponseMessage responseMessage, JsonSerializerOptions serializerOptions, CancellationToken cancellationToken = default)
+    {
+        try
+        {
+            string mediaType = responseMessage.Content.Headers.ContentType?.MediaType ?? string.Empty;
+            string content = await responseMessage.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+            return new ConflictException<T>(responseMessage.ReasonPhrase)
+            {
+                StatusCode = responseMessage.StatusCode,
+                ContentType = mediaType,
+                Payload = content,
+                ServerEntity = JsonSerializer.Deserialize<T>(content, serializerOptions)
+            };
+        }
+        catch (JsonException ex)
+        {
+            throw new DatasyncException("Invalid JSON content received from server", ex);
+        }
+    }
+}

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

@@ -0,0 +1,30 @@
+// 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;
+using System.Text.Json;
+
+namespace CommunityToolkit.Datasync.Client;
+
+/// <summary>
+/// A base exception for the Datasync client library.
+/// </summary>
+[ExcludeFromCodeCoverage(Justification = "Standard exception")]
+public class DatasyncException : Exception
+{
+    /// <inheritdoc />
+    public DatasyncException()
+    {
+    }
+
+    /// <inheritdoc />
+    public DatasyncException(string? message) : base(message)
+    {
+    }
+
+    /// <inheritdoc />
+    public DatasyncException(string? message, Exception? innerException) : base(message, innerException)
+    {
+    }
+}

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

@@ -0,0 +1,63 @@
+// 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;
+using System.Net;
+
+namespace CommunityToolkit.Datasync.Client;
+
+/// <summary>
+/// An exception used by the Datasync client library to report HTTP errors.
+/// </summary>
+public class DatasyncHttpException : DatasyncException
+{
+    /// <inheritdoc />
+    public DatasyncHttpException(string? message) : base(message)
+    {
+    }
+
+    /// <inheritdoc />
+    [ExcludeFromCodeCoverage(Justification = "Standard exception constructor")]
+    public DatasyncHttpException(string? message, Exception? innerException) : base(message, innerException)
+    {
+    }
+
+    /// <summary>
+    /// The HTTP Status Code that was returned.
+    /// </summary>
+    public HttpStatusCode StatusCode { get; set; } = HttpStatusCode.Ambiguous;
+
+    /// <summary>
+    /// The MIME content type for the payload, or the empty string if none was found.
+    /// </summary>
+    public string ContentType { get; set; } = string.Empty;
+
+    /// <summary>
+    /// The payload within the response, or the empty string if none was found.
+    /// </summary>
+    public string Payload { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Creates a new <see cref="DatasyncHttpException"/> for the response.
+    /// </summary>
+    /// <param name="responseMessage">The <see cref="HttpResponseMessage"/> that is creating the exception.</param>
+    /// <param name="cancellationToken">A <see cref="CancellationToken"/> to observe.</param>
+    /// <returns></returns>
+    public static async Task<DatasyncHttpException> CreateAsync(HttpResponseMessage responseMessage, CancellationToken cancellationToken = default)
+    {
+        if (responseMessage.StatusCode == HttpStatusCode.NotFound)
+        {
+            throw new EntityNotFoundException();
+        }
+
+        string mediaType = responseMessage.Content.Headers.ContentType?.MediaType ?? string.Empty;
+        string content = await responseMessage.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+        return new DatasyncHttpException(responseMessage.ReasonPhrase)
+        {
+            StatusCode = responseMessage.StatusCode,
+            ContentType = mediaType,
+            Payload = content
+        };
+    }
+}

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

@@ -0,0 +1,29 @@
+// 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;
+
+/// <summary>
+/// An exception that indicates the requested entity does not exist.
+/// </summary>
+[ExcludeFromCodeCoverage(Justification = "Standard exception")]
+public class EntityNotFoundException : DatasyncException
+{
+    /// <inheritdoc />
+    public EntityNotFoundException()
+    {
+    }
+
+    /// <inheritdoc />
+    public EntityNotFoundException(string? message) : base(message)
+    {
+    }
+
+    /// <inheritdoc />
+    public EntityNotFoundException(string? message, Exception? innerException) : base(message, innerException)
+    {
+    }
+}

src/CommunityToolkit.Datasync.Client/Models/AsyncPageable.cs

@@ -0,0 +1,83 @@
+// 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.Models;
+
+/// <summary>
+/// A collection of values that may take multiple service requests to iterate over.
+/// </summary>
+/// <typeparam name="T">The type of the entity being iterated over.</typeparam>
+/// <example>
+/// Example of enumerating an <see cref="AsyncPageable{T}"/> using the <c>async foreach</c> loop:
+/// <code snippet="Snippet:AsyncPageable">
+/// AsyncPageable&lt;Movie&gt; allMovies = dataset.QueryAsync();
+/// await foreach (Movie movie in allMovies)
+/// {
+///   ProcessMovie(movie);
+/// }
+/// </code>
+/// </example>
+public abstract class AsyncPageable<T> : IAsyncEnumerable<T> where T : notnull
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AsyncPageable{T}"/> class.
+    /// </summary>
+    /// <remarks>
+    /// Used for unit test mocking.
+    /// </remarks>
+    protected AsyncPageable()
+    {
+    }
+
+    /// <summary>
+    /// Enumerate the values a page of items at a time.  This may take multiple service requests.
+    /// </summary>
+    /// <param name="continuationToken">A continuation token indicating where to resume paging, or <c>null</c> to begin paging from the beginning.</param>
+    /// <returns>An async sequence of <see cref="Page{T}"/> entities</returns>
+    public abstract IAsyncEnumerable<Page<T>> AsPages(string? continuationToken = default);
+
+    /// <summary>
+    /// Enumerate the values in the collection asynchronously.  This may make multiple service requests.
+    /// </summary>
+    /// <param name="token">A <see cref="CancellationToken"/> used for requests made while enumerating asynchronously.</param>
+    /// <returns>An async sequence of values.</returns>
+    public virtual async IAsyncEnumerator<T> GetAsyncEnumerator(CancellationToken token = default)
+    {
+        await foreach (Page<T> page in AsPages().ConfigureAwait(false).WithCancellation(token))
+        {
+            Count = page.Count;
+            if (page.Items != null)
+            {
+                foreach (T value in page.Items)
+                {
+                    yield return value;
+                }
+            }
+        }
+    }
+
+    /// <summary>
+    /// The total number of items that would be returned by the query, if not for paging.
+    /// This is populated only if the total count ($count=true) is requested on the query.
+    /// </summary>
+    public long? Count { get; private set; }
+}
+
+/// <summary>
+/// Creates a new <see cref="AsyncPageable{T}"/> with a function iterator.
+/// </summary>
+/// <param name="pageFunc">The function that gets the next page</param>
+internal class FuncAsyncPageable<T>(Func<string?, Task<Page<T>>> pageFunc) : AsyncPageable<T> where T : notnull
+{
+    /// <inheritdoc />
+    public override async IAsyncEnumerable<Page<T>> AsPages(string? requestUri = default)
+    {
+        do
+        {
+            Page<T> pageResponse = await pageFunc(requestUri).ConfigureAwait(false);
+            requestUri = pageResponse.NextLink?.ToString();
+            yield return pageResponse ?? new Page<T>();
+        } while (requestUri != null);
+    }
+}

src/CommunityToolkit.Datasync.Client/Models/Page.cs

@@ -0,0 +1,27 @@
+// 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.Models;
+
+/// <summary>
+/// The model for the response from a query operation.
+/// </summary>
+public class Page<T> where T : notnull
+{
+    /// <summary>
+    /// The items in a page.
+    /// </summary>
+    public IEnumerable<T> Items { get; set; } = [];
+
+    /// <summary>
+    /// The number of items that would be returned by the query,
+    /// if not for paging.
+    /// </summary>
+    public long? Count { get; set; }
+
+    /// <summary>
+    /// The Uri to the nexty page in the result set.
+    /// </summary>
+    public string NextLink { get; set; } = string.Empty;
+}