Added support for bulk/batch requests (atomic:operations) (#930)

Author: Bart Koelman

benchmarks/Serialization/JsonApiDeserializerBenchmarks.cs

@@ -39,7 +39,7 @@ public JsonApiDeserializerBenchmarks()
             IResourceGraph resourceGraph = DependencyFactory.CreateResourceGraph(options);
             var targetedFields = new TargetedFields();
             var request = new JsonApiRequest();
-            _jsonApiDeserializer = new RequestDeserializer(resourceGraph, new ResourceFactory(new ServiceContainer()), targetedFields, new HttpContextAccessor(), request);
+            _jsonApiDeserializer = new RequestDeserializer(resourceGraph, new ResourceFactory(new ServiceContainer()), targetedFields, new HttpContextAccessor(), request, options);
         }
 
         [Benchmark]

docs/usage/toc.md

@@ -14,6 +14,7 @@
 ## [Creating](writing/creating.md)
 ## [Updating](writing/updating.md)
 ## [Deleting](writing/deleting.md)
+## [Bulk/batch](writing/bulk-batch-operations.md)
 
 # [Resource Graph](resource-graph.md)
 # [Options](options.md)

docs/usage/writing/bulk-batch-operations.md

@@ -0,0 +1,116 @@
+# Bulk/batch
+
+_since v4.1_
+
+The [Atomic Operations](https://jsonapi.org/ext/atomic/) JSON:API extension defines
+how to perform multiple write operations in a linear and atomic manner.
+
+Clients can send an array of operations in a single request. JsonApiDotNetCore guarantees that those
+operations will be processed in order and will either completely succeed or fail together.
+
+On failure, the zero-based index of the failing operation is returned in the `error.source.pointer` field of the error response.
+
+## Usage
+
+To enable operations, add a controller to your project that inherits from `JsonApiOperationsController` or `BaseJsonApiOperationsController`:
+```c#
+public sealed class OperationsController : JsonApiOperationsController
+{
+    public OperationsController(IJsonApiOptions options, ILoggerFactory loggerFactory,
+        IOperationsProcessor processor, IJsonApiRequest request,
+        ITargetedFields targetedFields)
+        : base(options, loggerFactory, processor, request, targetedFields)
+    {
+    }
+}
+```
+
+You'll need to send the next Content-Type in a POST request for operations:
+```
+application/vnd.api+json; ext="https://jsonapi.org/ext/atomic"
+```
+
+### Local IDs
+
+Local IDs (lid) can be used to associate resources that have not yet been assigned an ID.
+The next example creates two resources and sets a relationship between them:
+
+```json
+POST http://localhost/api/operations HTTP/1.1
+Content-Type: application/vnd.api+json;ext="https://jsonapi.org/ext/atomic"
+
+{
+  "atomic:operations": [
+    {
+      "op": "add",
+      "data": {
+        "type": "musicTracks",
+        "lid": "id-for-i-will-survive",
+        "attributes": {
+          "title": "I will survive"
+        }
+      }
+    },
+    {
+      "op": "add",
+      "data": {
+        "type": "performers",
+        "lid": "id-for-gloria-gaynor",
+        "attributes": {
+          "artistName": "Gloria Gaynor"
+        }
+      }
+    },
+    {
+      "op": "update",
+      "ref": {
+        "type": "musicTracks",
+        "lid": "id-for-i-will-survive",
+        "relationship": "performers"
+      },
+      "data": [
+        {
+          "type": "performers",
+          "lid": "id-for-gloria-gaynor"
+        }
+      ]
+    }
+  ]
+}
+```
+
+For example requests, see our suite of tests in JsonApiDotNetCoreExampleTests.IntegrationTests.AtomicOperations.
+
+## Configuration
+
+The maximum number of operations per request defaults to 10, which you can change from Startup.cs:
+```c#
+services.AddJsonApi(options => options.MaximumOperationsPerRequest = 250);
+```
+Or, if you want to allow unconstrained, set it to `null` instead.
+
+### Multiple controllers
+
+You can register multiple operations controllers using custom routes, for example:
+```c#
+[DisableRoutingConvention, Route("/operations/musicTracks/create")]
+public sealed class CreateMusicTrackOperationsController : JsonApiOperationsController
+{
+    public override async Task<IActionResult> PostOperationsAsync(
+        IList<OperationContainer> operations, CancellationToken cancellationToken)
+    {
+        AssertOnlyCreatingMusicTracks(operations);
+
+        return await base.PostOperationsAsync(operations, cancellationToken);
+    }
+}
+```
+
+## Limitations
+
+For our atomic:operations implementation, the next limitations apply:
+
+- The `ref.href` field cannot be used. Use type/id or type/lid instead.
+- You cannot both assign and reference the same local ID in a single operation.
+- All repositories used in an operations request must implement `IRepositorySupportsTransaction` and participate in the same transaction.
+- If you're not using Entity Framework Core, you'll need to implement and register `IOperationsTransactionFactory` yourself.

src/Examples/JsonApiDotNetCoreExample/Controllers/OperationsController.cs

@@ -0,0 +1,18 @@
+using JsonApiDotNetCore.AtomicOperations;
+using JsonApiDotNetCore.Configuration;
+using JsonApiDotNetCore.Controllers;
+using JsonApiDotNetCore.Middleware;
+using JsonApiDotNetCore.Resources;
+using Microsoft.Extensions.Logging;
+
+namespace JsonApiDotNetCoreExample.Controllers
+{
+    public sealed class OperationsController : JsonApiOperationsController
+    {
+        public OperationsController(IJsonApiOptions options, ILoggerFactory loggerFactory,
+            IOperationsProcessor processor, IJsonApiRequest request, ITargetedFields targetedFields)
+            : base(options, loggerFactory, processor, request, targetedFields)
+        {
+        }
+    }
+}

src/JsonApiDotNetCore/AtomicOperations/EntityFrameworkCoreTransaction.cs

@@ -0,0 +1,56 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using JsonApiDotNetCore.Repositories;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Storage;
+
+namespace JsonApiDotNetCore.AtomicOperations
+{
+    /// <summary>
+    /// Represents an Entity Framework Core transaction in an atomic:operations request.
+    /// </summary>
+    public sealed class EntityFrameworkCoreTransaction : IOperationsTransaction
+    {
+        private readonly IDbContextTransaction _transaction;
+        private readonly DbContext _dbContext;
+
+        /// <inheritdoc />
+        public Guid TransactionId => _transaction.TransactionId;
+
+        public EntityFrameworkCoreTransaction(IDbContextTransaction transaction, DbContext dbContext)
+        {
+            _transaction = transaction ?? throw new ArgumentNullException(nameof(transaction));
+            _dbContext = dbContext ?? throw new ArgumentNullException(nameof(dbContext));
+        }
+
+        /// <summary>
+        /// Detaches all entities from the Entity Framework Core change tracker.
+        /// </summary>
+        public Task BeforeProcessOperationAsync(CancellationToken cancellationToken)
+        {
+            _dbContext.ResetChangeTracker();
+            return Task.CompletedTask;
+        }
+
+        /// <summary>
+        /// Does nothing.
+        /// </summary>
+        public Task AfterProcessOperationAsync(CancellationToken cancellationToken)
+        {
+            return Task.CompletedTask;
+        }
+
+        /// <inheritdoc />
+        public Task CommitAsync(CancellationToken cancellationToken)
+        {
+            return _transaction.CommitAsync(cancellationToken);
+        }
+
+        /// <inheritdoc />
+        public ValueTask DisposeAsync()
+        {
+            return _transaction.DisposeAsync();
+        }
+    }
+}

src/JsonApiDotNetCore/AtomicOperations/EntityFrameworkCoreTransactionFactory.cs

@@ -0,0 +1,37 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using JsonApiDotNetCore.Configuration;
+using JsonApiDotNetCore.Repositories;
+using Microsoft.EntityFrameworkCore;
+
+namespace JsonApiDotNetCore.AtomicOperations
+{
+    /// <summary>
+    /// Provides transaction support for atomic:operation requests using Entity Framework Core.
+    /// </summary>
+    public sealed class EntityFrameworkCoreTransactionFactory : IOperationsTransactionFactory
+    {
+        private readonly IDbContextResolver _dbContextResolver;
+        private readonly IJsonApiOptions _options;
+
+        public EntityFrameworkCoreTransactionFactory(IDbContextResolver dbContextResolver, IJsonApiOptions options)
+        {
+            _dbContextResolver = dbContextResolver ?? throw new ArgumentNullException(nameof(dbContextResolver));
+            _options = options ?? throw new ArgumentNullException(nameof(options));
+        }
+
+        /// <inheritdoc />
+        public async Task<IOperationsTransaction> BeginTransactionAsync(CancellationToken cancellationToken)
+        {
+            var dbContext = _dbContextResolver.GetContext();
+
+            var transaction = _options.TransactionIsolationLevel != null
+                ? await dbContext.Database.BeginTransactionAsync(_options.TransactionIsolationLevel.Value,
+                    cancellationToken)
+                : await dbContext.Database.BeginTransactionAsync(cancellationToken);
+
+            return new EntityFrameworkCoreTransaction(transaction, dbContext);
+        }
+    }
+}

src/JsonApiDotNetCore/AtomicOperations/ILocalIdTracker.cs

@@ -0,0 +1,28 @@
+namespace JsonApiDotNetCore.AtomicOperations
+{
+    /// <summary>
+    /// Used to track declarations, assignments and references to local IDs an in atomic:operations request.
+    /// </summary>
+    public interface ILocalIdTracker
+    {
+        /// <summary>
+        /// Removes all declared and assigned values.
+        /// </summary>
+        void Reset();
+
+        /// <summary>
+        /// Declares a local ID without assigning a server-generated value.
+        /// </summary>
+        void Declare(string localId, string resourceType);
+
+        /// <summary>
+        /// Assigns a server-generated ID value to a previously declared local ID.
+        /// </summary>
+        void Assign(string localId, string resourceType, string stringId);
+
+        /// <summary>
+        /// Gets the server-assigned ID for the specified local ID.
+        /// </summary>
+        string GetValue(string localId, string resourceType);
+    }
+}

src/JsonApiDotNetCore/AtomicOperations/IOperationProcessorAccessor.cs

@@ -0,0 +1,18 @@
+using System.Threading;
+using System.Threading.Tasks;
+using JsonApiDotNetCore.AtomicOperations.Processors;
+using JsonApiDotNetCore.Resources;
+
+namespace JsonApiDotNetCore.AtomicOperations
+{
+    /// <summary>
+    /// Retrieves a <see cref="IOperationProcessor"/> instance from the D/I container and invokes a method on it.
+    /// </summary>
+    public interface IOperationProcessorAccessor
+    {
+        /// <summary>
+        /// Invokes <see cref="IOperationProcessor.ProcessAsync"/> on a processor compatible with the operation kind.
+        /// </summary>
+        Task<OperationContainer> ProcessAsync(OperationContainer operation, CancellationToken cancellationToken);
+    }
+}

src/JsonApiDotNetCore/AtomicOperations/IOperationsProcessor.cs

@@ -0,0 +1,18 @@
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using JsonApiDotNetCore.Resources;
+
+namespace JsonApiDotNetCore.AtomicOperations
+{
+    /// <summary>
+    /// Atomically processes a request that contains a list of operations.
+    /// </summary>
+    public interface IOperationsProcessor
+    {
+        /// <summary>
+        /// Processes the list of specified operations.
+        /// </summary>
+        Task<IList<OperationContainer>> ProcessAsync(IList<OperationContainer> operations, CancellationToken cancellationToken);
+    }
+}

src/JsonApiDotNetCore/AtomicOperations/IOperationsTransaction.cs

@@ -0,0 +1,32 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace JsonApiDotNetCore.AtomicOperations
+{
+    /// <summary>
+    /// Represents the overarching transaction in an atomic:operations request.
+    /// </summary>
+    public interface IOperationsTransaction : IAsyncDisposable
+    {
+        /// <summary>
+        /// Identifies the active transaction.
+        /// </summary>
+        Guid TransactionId { get; }
+
+        /// <summary>
+        /// Enables to execute custom logic before processing of an operation starts.
+        /// </summary>
+        Task BeforeProcessOperationAsync(CancellationToken cancellationToken);
+
+        /// <summary>
+        /// Enables to execute custom logic after processing of an operation succeeds.
+        /// </summary>
+        Task AfterProcessOperationAsync(CancellationToken cancellationToken);
+
+        /// <summary>
+        /// Commits all changes made to the underlying data store.
+        /// </summary>
+        Task CommitAsync(CancellationToken cancellationToken);
+    }
+}

src/JsonApiDotNetCore/AtomicOperations/IOperationsTransactionFactory.cs

@@ -0,0 +1,16 @@
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace JsonApiDotNetCore.AtomicOperations
+{
+    /// <summary>
+    /// Provides a method to start the overarching transaction for an atomic:operations request.
+    /// </summary>
+    public interface IOperationsTransactionFactory
+    {
+        /// <summary>
+        /// Starts a new transaction.
+        /// </summary>
+        Task<IOperationsTransaction> BeginTransactionAsync(CancellationToken cancellationToken);
+    }
+}