Explores support for concurrency tokens using PostgreSQL, continued

JsonApiDotNetCore.sln.DotSettings

@@ -660,5 +660,6 @@ $left$ = $right$;</s:String>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=subdirectory/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=unarchive/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=Workflows/@EntryIndexedValue">True</s:Boolean>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=xmin/@EntryIndexedValue">True</s:Boolean>
 	<s:Boolean x:Key="/Default/UserDictionary/Words/=xunit/@EntryIndexedValue">True</s:Boolean>
 </wpf:ResourceDictionary>

src/Examples/MultiDbContextExample/Repositories/DbContextARepository.cs

@@ -1,5 +1,6 @@
 using JetBrains.Annotations;
 using JsonApiDotNetCore.Configuration;
+using JsonApiDotNetCore.Middleware;
 using JsonApiDotNetCore.Queries;
 using JsonApiDotNetCore.Repositories;
 using JsonApiDotNetCore.Resources;
@@ -11,10 +12,10 @@ namespace MultiDbContextExample.Repositories;
 public sealed class DbContextARepository<TResource> : EntityFrameworkCoreRepository<TResource, int>
     where TResource : class, IIdentifiable<int>
 {
-    public DbContextARepository(ITargetedFields targetedFields, DbContextResolver<DbContextA> dbContextResolver, IResourceGraph resourceGraph,
-        IResourceFactory resourceFactory, IEnumerable<IQueryConstraintProvider> constraintProviders, ILoggerFactory loggerFactory,
-        IResourceDefinitionAccessor resourceDefinitionAccessor)
-        : base(targetedFields, dbContextResolver, resourceGraph, resourceFactory, constraintProviders, loggerFactory, resourceDefinitionAccessor)
+    public DbContextARepository(IJsonApiRequest request, ITargetedFields targetedFields, DbContextResolver<DbContextA> dbContextResolver,
+        IResourceGraph resourceGraph, IResourceFactory resourceFactory, IResourceDefinitionAccessor resourceDefinitionAccessor,
+        IEnumerable<IQueryConstraintProvider> constraintProviders, ILoggerFactory loggerFactory)
+        : base(request, targetedFields, dbContextResolver, resourceGraph, resourceFactory, resourceDefinitionAccessor, constraintProviders, loggerFactory)
     {
     }
 }

src/Examples/MultiDbContextExample/Repositories/DbContextBRepository.cs

@@ -1,5 +1,6 @@
 using JetBrains.Annotations;
 using JsonApiDotNetCore.Configuration;
+using JsonApiDotNetCore.Middleware;
 using JsonApiDotNetCore.Queries;
 using JsonApiDotNetCore.Repositories;
 using JsonApiDotNetCore.Resources;
@@ -11,10 +12,10 @@ namespace MultiDbContextExample.Repositories;
 public sealed class DbContextBRepository<TResource> : EntityFrameworkCoreRepository<TResource, int>
     where TResource : class, IIdentifiable<int>
 {
-    public DbContextBRepository(ITargetedFields targetedFields, DbContextResolver<DbContextB> dbContextResolver, IResourceGraph resourceGraph,
-        IResourceFactory resourceFactory, IEnumerable<IQueryConstraintProvider> constraintProviders, ILoggerFactory loggerFactory,
-        IResourceDefinitionAccessor resourceDefinitionAccessor)
-        : base(targetedFields, dbContextResolver, resourceGraph, resourceFactory, constraintProviders, loggerFactory, resourceDefinitionAccessor)
+    public DbContextBRepository(IJsonApiRequest request, ITargetedFields targetedFields, DbContextResolver<DbContextB> dbContextResolver,
+        IResourceGraph resourceGraph, IResourceFactory resourceFactory, IResourceDefinitionAccessor resourceDefinitionAccessor,
+        IEnumerable<IQueryConstraintProvider> constraintProviders, ILoggerFactory loggerFactory)
+        : base(request, targetedFields, dbContextResolver, resourceGraph, resourceFactory, resourceDefinitionAccessor, constraintProviders, loggerFactory)
     {
     }
 }

src/JsonApiDotNetCore.Annotations/Configuration/ResourceType.cs

@@ -1,4 +1,5 @@
 using JetBrains.Annotations;
+using JsonApiDotNetCore.Resources;
 using JsonApiDotNetCore.Resources.Annotations;
 
 namespace JsonApiDotNetCore.Configuration;
@@ -38,6 +39,11 @@ public sealed class ResourceType
     /// </summary>
     public IReadOnlySet<ResourceType> DirectlyDerivedTypes { get; internal set; } = new HashSet<ResourceType>();
 
+    /// <summary>
+    /// When <c>true</c>, this resource type uses optimistic concurrency.
+    /// </summary>
+    public bool IsVersioned => ClrType.IsOrImplementsInterface<IVersionedIdentifiable>();
+
     /// <summary>
     /// Exposed resource attributes and relationships. See https://jsonapi.org/format/#document-resource-object-fields. When using resource inheritance, this
     /// includes the attributes and relationships from base types.

src/JsonApiDotNetCore.Annotations/Resources/IVersionedIdentifiable.cs

@@ -0,0 +1,38 @@
+using JetBrains.Annotations;
+
+namespace JsonApiDotNetCore.Resources;
+
+/// <summary>
+/// Defines the basic contract for a JSON:API resource that uses optimistic concurrency. All resource classes must implement
+/// <see cref="IVersionedIdentifiable{TId, TVersion}" />.
+/// </summary>
+public interface IVersionedIdentifiable : IIdentifiable
+{
+    /// <summary>
+    /// The value for element 'version' in a JSON:API request or response.
+    /// </summary>
+    string? Version { get; set; }
+}
+
+/// <summary>
+/// When implemented by a class, indicates to JsonApiDotNetCore that the class represents a JSON:API resource that uses optimistic concurrency.
+/// </summary>
+/// <typeparam name="TId">
+/// The resource identifier type.
+/// </typeparam>
+/// <typeparam name="TVersion">
+/// The database vendor-specific type that is used to store the concurrency token.
+/// </typeparam>
+[PublicAPI]
+public interface IVersionedIdentifiable<TId, TVersion> : IIdentifiable<TId>, IVersionedIdentifiable
+{
+    /// <summary>
+    /// The concurrency token, which is used to detect if the resource was modified by another user since the moment this resource was last retrieved.
+    /// </summary>
+    TVersion ConcurrencyToken { get; set; }
+
+    /// <summary>
+    /// Represents a database column where random data is written to on updates, in order to force a concurrency check during relationship updates.
+    /// </summary>
+    Guid ConcurrencyValue { get; set; }
+}

src/JsonApiDotNetCore.Annotations/TypeExtensions.cs

@@ -13,7 +13,7 @@ public static bool IsOrImplementsInterface<TInterface>(this Type? source)
     /// <summary>
     /// Whether the specified source type implements or equals the specified interface. This overload enables to test for an open generic interface.
     /// </summary>
-    private static bool IsOrImplementsInterface(this Type? source, Type interfaceType)
+    public static bool IsOrImplementsInterface(this Type? source, Type interfaceType)
     {
         ArgumentGuard.NotNull(interfaceType);
 

src/JsonApiDotNetCore/AtomicOperations/IVersionTracker.cs

@@ -0,0 +1,13 @@
+using JsonApiDotNetCore.Configuration;
+using JsonApiDotNetCore.Resources;
+
+namespace JsonApiDotNetCore.AtomicOperations;
+
+public interface IVersionTracker
+{
+    bool RequiresVersionTracking();
+
+    void CaptureVersions(ResourceType resourceType, IIdentifiable resource);
+
+    string? GetVersion(ResourceType resourceType, string stringId);
+}

src/JsonApiDotNetCore/AtomicOperations/OperationsProcessor.cs

@@ -15,19 +15,21 @@ public class OperationsProcessor : IOperationsProcessor
     private readonly IOperationProcessorAccessor _operationProcessorAccessor;
     private readonly IOperationsTransactionFactory _operationsTransactionFactory;
     private readonly ILocalIdTracker _localIdTracker;
+    private readonly IVersionTracker _versionTracker;
     private readonly IResourceGraph _resourceGraph;
     private readonly IJsonApiRequest _request;
     private readonly ITargetedFields _targetedFields;
     private readonly ISparseFieldSetCache _sparseFieldSetCache;
     private readonly LocalIdValidator _localIdValidator;
 
     public OperationsProcessor(IOperationProcessorAccessor operationProcessorAccessor, IOperationsTransactionFactory operationsTransactionFactory,
-        ILocalIdTracker localIdTracker, IResourceGraph resourceGraph, IJsonApiRequest request, ITargetedFields targetedFields,
+        ILocalIdTracker localIdTracker, IVersionTracker versionTracker, IResourceGraph resourceGraph, IJsonApiRequest request, ITargetedFields targetedFields,
         ISparseFieldSetCache sparseFieldSetCache)
     {
         ArgumentGuard.NotNull(operationProcessorAccessor);
         ArgumentGuard.NotNull(operationsTransactionFactory);
         ArgumentGuard.NotNull(localIdTracker);
+        ArgumentGuard.NotNull(versionTracker);
         ArgumentGuard.NotNull(resourceGraph);
         ArgumentGuard.NotNull(request);
         ArgumentGuard.NotNull(targetedFields);
@@ -36,6 +38,7 @@ public OperationsProcessor(IOperationProcessorAccessor operationProcessorAccesso
         _operationProcessorAccessor = operationProcessorAccessor;
         _operationsTransactionFactory = operationsTransactionFactory;
         _localIdTracker = localIdTracker;
+        _versionTracker = versionTracker;
         _resourceGraph = resourceGraph;
         _request = request;
         _targetedFields = targetedFields;
@@ -104,11 +107,15 @@ public OperationsProcessor(IOperationProcessorAccessor operationProcessorAccesso
         cancellationToken.ThrowIfCancellationRequested();
 
         TrackLocalIdsForOperation(operation);
+        RefreshVersionsForOperation(operation);
 
         _targetedFields.CopyFrom(operation.TargetedFields);
         _request.CopyFrom(operation.Request);
 
         return await _operationProcessorAccessor.ProcessAsync(operation, cancellationToken);
+
+        // Ideally we'd take the versions from response here and update the version cache, but currently
+        // not all resource service methods return data. Therefore this is handled elsewhere.
     }
 
     protected void TrackLocalIdsForOperation(OperationContainer operation)
@@ -144,4 +151,36 @@ private void AssignStringId(IIdentifiable resource)
             resource.StringId = _localIdTracker.GetValue(resource.LocalId, resourceType);
         }
     }
+
+    private void RefreshVersionsForOperation(OperationContainer operation)
+    {
+        if (operation.Request.PrimaryResourceType!.IsVersioned)
+        {
+            string? requestVersion = operation.Resource.GetVersion();
+
+            if (requestVersion == null)
+            {
+                string? trackedVersion = _versionTracker.GetVersion(operation.Request.PrimaryResourceType, operation.Resource.StringId!);
+                operation.Resource.SetVersion(trackedVersion);
+
+                ((JsonApiRequest)operation.Request).PrimaryVersion = trackedVersion;
+            }
+        }
+
+        foreach (IIdentifiable rightResource in operation.GetSecondaryResources())
+        {
+            ResourceType rightResourceType = _resourceGraph.GetResourceType(rightResource.GetClrType());
+
+            if (rightResourceType.IsVersioned)
+            {
+                string? requestVersion = rightResource.GetVersion();
+
+                if (requestVersion == null)
+                {
+                    string? trackedVersion = _versionTracker.GetVersion(rightResourceType, rightResource.StringId!);
+                    rightResource.SetVersion(trackedVersion);
+                }
+            }
+        }
+    }
 }

src/JsonApiDotNetCore/AtomicOperations/VersionTracker.cs

@@ -0,0 +1,91 @@
+using JsonApiDotNetCore.Configuration;
+using JsonApiDotNetCore.Middleware;
+using JsonApiDotNetCore.Resources;
+using JsonApiDotNetCore.Resources.Annotations;
+
+namespace JsonApiDotNetCore.AtomicOperations;
+
+public sealed class VersionTracker : IVersionTracker
+{
+    private static readonly CollectionConverter CollectionConverter = new();
+
+    private readonly ITargetedFields _targetedFields;
+    private readonly IJsonApiRequest _request;
+    private readonly Dictionary<string, string> _versionPerResource = new();
+
+    public VersionTracker(ITargetedFields targetedFields, IJsonApiRequest request)
+    {
+        ArgumentGuard.NotNull(targetedFields, nameof(targetedFields));
+        ArgumentGuard.NotNull(request, nameof(request));
+
+        _targetedFields = targetedFields;
+        _request = request;
+    }
+
+    public bool RequiresVersionTracking()
+    {
+        if (_request.Kind != EndpointKind.AtomicOperations)
+        {
+            return false;
+        }
+
+        return _request.PrimaryResourceType!.IsVersioned || _targetedFields.Relationships.Any(relationship => relationship.RightType.IsVersioned);
+    }
+
+    public void CaptureVersions(ResourceType resourceType, IIdentifiable resource)
+    {
+        if (_request.Kind == EndpointKind.AtomicOperations)
+        {
+            if (resourceType.IsVersioned)
+            {
+                string? leftVersion = resource.GetVersion();
+                SetVersion(resourceType, resource.StringId!, leftVersion);
+            }
+
+            foreach (RelationshipAttribute relationship in _targetedFields.Relationships)
+            {
+                if (relationship.RightType.IsVersioned)
+                {
+                    CaptureVersionsInRelationship(resource, relationship);
+                }
+            }
+        }
+    }
+
+    private void CaptureVersionsInRelationship(IIdentifiable resource, RelationshipAttribute relationship)
+    {
+        object? afterRightValue = relationship.GetValue(resource);
+        IReadOnlyCollection<IIdentifiable> afterRightResources = CollectionConverter.ExtractResources(afterRightValue);
+
+        foreach (IIdentifiable rightResource in afterRightResources)
+        {
+            string? rightVersion = rightResource.GetVersion();
+            SetVersion(relationship.RightType, rightResource.StringId!, rightVersion);
+        }
+    }
+
+    private void SetVersion(ResourceType resourceType, string stringId, string? version)
+    {
+        string key = GetKey(resourceType, stringId);
+
+        if (version == null)
+        {
+            _versionPerResource.Remove(key);
+        }
+        else
+        {
+            _versionPerResource[key] = version;
+        }
+    }
+
+    public string? GetVersion(ResourceType resourceType, string stringId)
+    {
+        string key = GetKey(resourceType, stringId);
+        return _versionPerResource.TryGetValue(key, out string? version) ? version : null;
+    }
+
+    private string GetKey(ResourceType resourceType, string stringId)
+    {
+        return $"{resourceType.PublicName}::{stringId}";
+    }
+}

src/JsonApiDotNetCore/Configuration/JsonApiApplicationBuilder.cs

@@ -275,6 +275,7 @@ private void AddOperationsLayer()
         _services.AddScoped<IOperationsProcessor, OperationsProcessor>();
         _services.AddScoped<IOperationProcessorAccessor, OperationProcessorAccessor>();
         _services.AddScoped<ILocalIdTracker, LocalIdTracker>();
+        _services.AddScoped<IVersionTracker, VersionTracker>();
     }
 
     public void Dispose()

src/JsonApiDotNetCore/Configuration/ResourceGraphBuilder.cs

@@ -207,6 +207,12 @@ public ResourceGraphBuilder Add(Type resourceClrType, Type? idClrType = null, st
             return this;
         }
 
+        if (resourceClrType.IsOrImplementsInterface<IVersionedIdentifiable>() && !resourceClrType.IsOrImplementsInterface(typeof(IVersionedIdentifiable<,>)))
+        {
+            throw new InvalidConfigurationException(
+                $"Resource type '{resourceClrType}' implements 'IVersionedIdentifiable', but not 'IVersionedIdentifiable<TId, TVersion>'.");
+        }
+
         if (resourceClrType.IsOrImplementsInterface<IIdentifiable>())
         {
             string effectivePublicName = publicName ?? FormatResourceName(resourceClrType);

src/JsonApiDotNetCore/Controllers/BaseJsonApiController.cs

@@ -206,8 +206,9 @@ public virtual async Task<IActionResult> PostAsync([FromBody] TResource resource
 
         TResource? newResource = await _create.CreateAsync(resource, cancellationToken);
 
-        string resourceId = (newResource ?? resource).StringId!;
-        string locationUrl = $"{HttpContext.Request.Path}/{resourceId}";
+        TResource resultResource = newResource ?? resource;
+        string? resourceVersion = resultResource.GetVersion();
+        string locationUrl = $"{HttpContext.Request.Path}/{resultResource.StringId}{(resourceVersion != null ? $";v~{resourceVersion}" : null)}";
 
         if (newResource == null)
         {
@@ -221,6 +222,9 @@ public virtual async Task<IActionResult> PostAsync([FromBody] TResource resource
     /// <summary>
     /// Adds resources to a to-many relationship. Example: <code><![CDATA[
     /// POST /articles/1/revisions HTTP/1.1
+    /// ]]></code> Example:
+    /// <code><![CDATA[
+    /// POST /articles/1;v~8/revisions HTTP/1.1
     /// ]]></code>
     /// </summary>
     /// <param name="id">
@@ -262,6 +266,9 @@ public virtual async Task<IActionResult> PostRelationshipAsync(TId id, string re
     /// Updates the attributes and/or relationships of an existing resource. Only the values of sent attributes are replaced. And only the values of sent
     /// relationships are replaced. Example: <code><![CDATA[
     /// PATCH /articles/1 HTTP/1.1
+    /// ]]></code> Example:
+    /// <code><![CDATA[
+    /// PATCH /articles/1;v~8 HTTP/1.1
     /// ]]></code>
     /// </summary>
     public virtual async Task<IActionResult> PatchAsync(TId id, [FromBody] TResource resource, CancellationToken cancellationToken)
@@ -295,7 +302,13 @@ public virtual async Task<IActionResult> PatchAsync(TId id, [FromBody] TResource
     /// PATCH /articles/1/relationships/author HTTP/1.1
     /// ]]></code> Example:
     /// <code><![CDATA[
+    /// PATCH /articles/1;v~8/relationships/author HTTP/1.1
+    /// ]]></code> Example:
+    /// <code><![CDATA[
     /// PATCH /articles/1/relationships/revisions HTTP/1.1
+    /// ]]></code> Example:
+    /// <code><![CDATA[
+    /// PATCH /articles/1;v~8/relationships/revisions HTTP/1.1
     /// ]]></code>
     /// </summary>
     /// <param name="id">
@@ -335,6 +348,9 @@ public virtual async Task<IActionResult> PatchRelationshipAsync(TId id, string r
     /// <summary>
     /// Deletes an existing resource. Example: <code><![CDATA[
     /// DELETE /articles/1 HTTP/1.1
+    /// ]]></code> Example:
+    /// <code><![CDATA[
+    /// DELETE /articles/1;v~8 HTTP/1.1
     /// ]]></code>
     /// </summary>
     public virtual async Task<IActionResult> DeleteAsync(TId id, CancellationToken cancellationToken)
@@ -357,6 +373,9 @@ public virtual async Task<IActionResult> DeleteAsync(TId id, CancellationToken c
     /// <summary>
     /// Removes resources from a to-many relationship. Example: <code><![CDATA[
     /// DELETE /articles/1/relationships/revisions HTTP/1.1
+    /// ]]></code> Example:
+    /// <code><![CDATA[
+    /// DELETE /articles/1;v~8/relationships/revisions HTTP/1.1
     /// ]]></code>
     /// </summary>
     /// <param name="id">