Refactored include chains into a tree, so it can be used from ResourceDefinitions

Author: Bart Koelman

docs/usage/resources/resource-definitions.md

@@ -144,6 +144,26 @@ public class AccountDefinition : ResourceDefinition<Account>
 }
 ```
 
+## Block including related resources
+
+```c#
+public class EmployeeDefinition : ResourceDefinition<Employee>
+{
+    public override IReadOnlyCollection<IncludeElementExpression> OnApplyIncludes(IReadOnlyCollection<IncludeElementExpression> existingIncludes)
+    {
+        if (existingIncludes.Any(include => include.Relationship.Property.Name == nameof(Employee.Manager)))
+        {
+            throw new JsonApiException(new Error(HttpStatusCode.BadRequest)
+            {
+                Title = "Including the manager of employees is not permitted."
+            });
+        }
+
+        return existingIncludes;
+    }
+}
+```
+
 ## Custom query string parameters
 
 _since v3.0.0_

src/JsonApiDotNetCore/Hooks/Execution/HookExecutorHelper.cs

@@ -147,7 +147,7 @@ private IEnumerable<TResource> GetWhereAndInclude<TResource, TId>(IEnumerable<TI
             var chains = relationshipsToNextLayer.Select(relationship => new ResourceFieldChainExpression(relationship)).ToList();
             if (chains.Any())
             {
-                queryLayer.Include = new IncludeExpression(chains);
+                queryLayer.Include = IncludeChainConverter.FromRelationshipChains(chains);
             }
 
             var repository = GetRepository<TResource, TId>();

src/JsonApiDotNetCore/Hooks/ResourceHookExecutor.cs

@@ -55,7 +55,7 @@ public void BeforeRead<TResource>(ResourcePipeline pipeline, string stringId = n
                 .OfType<IncludeExpression>()
                 .ToArray();
 
-            foreach (var chain in includes.SelectMany(include => include.Chains))
+            foreach (var chain in includes.SelectMany(IncludeChainConverter.GetRelationshipChains))
             {
                 RecursiveBeforeRead(chain.Fields.Cast<RelationshipAttribute>().ToList(), pipeline, calledContainers);
             }

src/JsonApiDotNetCore/Internal/Queries/Expressions/IncludeChainConverter.cs

@@ -0,0 +1,156 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using JsonApiDotNetCore.Models.Annotation;
+
+namespace JsonApiDotNetCore.Internal.Queries.Expressions
+{
+    public static class IncludeChainConverter
+    {
+        /// <summary>
+        /// Converts a tree of inclusions into a set of relationship chains.
+        /// </summary>
+        /// <example>
+        /// Input tree:
+        /// Article
+        /// {
+        ///   Blog,
+        ///   Revisions
+        ///   {
+        ///     Author
+        ///   }
+        /// }
+        ///
+        /// Output chains:
+        /// Article -> Blog,
+        /// Article -> Revisions -> Author
+        /// </example>
+        public static IReadOnlyCollection<ResourceFieldChainExpression> GetRelationshipChains(IncludeExpression include)
+        {
+            if (include == null)
+            {
+                throw new ArgumentNullException(nameof(include));
+            }
+
+            IncludeToChainsConverter converter = new IncludeToChainsConverter();
+            converter.Visit(include, null);
+
+            return converter.Chains.AsReadOnly();
+        }
+
+        /// <summary>
+        /// Converts a set of relationship chains into a tree of inclusions.
+        /// </summary>
+        /// <example>
+        /// Input chains:
+        /// Article -> Blog,
+        /// Article -> Revisions -> Author
+        ///
+        /// Output tree:
+        /// Article
+        /// {
+        ///   Blog,
+        ///   Revisions
+        ///   {
+        ///     Author
+        ///   }
+        /// }
+        /// </example>
+        public static IncludeExpression FromRelationshipChains(IEnumerable<ResourceFieldChainExpression> chains)
+        {
+            if (chains == null)
+            {
+                throw new ArgumentNullException(nameof(chains));
+            }
+
+            var elements = ConvertChainsToElements(chains);
+            return elements.Any() ? new IncludeExpression(elements) : IncludeExpression.Empty;
+        }
+
+        private static IReadOnlyCollection<IncludeElementExpression> ConvertChainsToElements(IEnumerable<ResourceFieldChainExpression> chains)
+        {
+            var rootNode = new MutableIncludeNode(null);
+
+            foreach (ResourceFieldChainExpression chain in chains)
+            {
+                MutableIncludeNode currentNode = rootNode;
+
+                foreach (var relationship in chain.Fields.OfType<RelationshipAttribute>())
+                {
+                    if (!currentNode.Children.ContainsKey(relationship))
+                    {
+                        currentNode.Children[relationship] = new MutableIncludeNode(relationship);
+                    }
+
+                    currentNode = currentNode.Children[relationship];
+                }
+            }
+
+            return rootNode.Children.Values.Select(child => child.ToExpression()).ToList();
+        }
+
+        private sealed class IncludeToChainsConverter : QueryExpressionVisitor<object, object>
+        {
+            private readonly Stack<RelationshipAttribute> _parentRelationshipStack = new Stack<RelationshipAttribute>();
+
+            public List<ResourceFieldChainExpression> Chains { get; } = new List<ResourceFieldChainExpression>();
+
+            public override object VisitInclude(IncludeExpression expression, object argument)
+            {
+                foreach (IncludeElementExpression element in expression.Elements)
+                {
+                    Visit(element, null);
+                }
+
+                return null;
+            }
+
+            public override object VisitIncludeElement(IncludeElementExpression expression, object argument)
+            {
+                if (!expression.Children.Any())
+                {
+                    FlushChain(expression);
+                }
+                else
+                {
+                    _parentRelationshipStack.Push(expression.Relationship);
+
+                    foreach (IncludeElementExpression child in expression.Children)
+                    {
+                        Visit(child, null);
+                    }
+
+                    _parentRelationshipStack.Pop();
+                }
+
+                return null;
+            }
+
+            private void FlushChain(IncludeElementExpression expression)
+            {
+                List<RelationshipAttribute> fieldsInChain = _parentRelationshipStack.Reverse().ToList();
+                fieldsInChain.Add(expression.Relationship);
+
+                Chains.Add(new ResourceFieldChainExpression(fieldsInChain));
+            }
+        }
+
+        private sealed class MutableIncludeNode
+        {
+            private readonly RelationshipAttribute _relationship;
+
+            public IDictionary<RelationshipAttribute, MutableIncludeNode> Children { get; } = new Dictionary<RelationshipAttribute, MutableIncludeNode>();
+
+            public MutableIncludeNode(RelationshipAttribute relationship)
+            {
+                _relationship = relationship;
+            }
+
+            public IncludeElementExpression ToExpression()
+            {
+                var elementChildren = Children.Values.Select(child => child.ToExpression()).ToList();
+                return new IncludeElementExpression(_relationship, elementChildren);
+            }
+        }
+    }
+}

src/JsonApiDotNetCore/Internal/Queries/Expressions/IncludeElementExpression.cs

@@ -0,0 +1,45 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using JsonApiDotNetCore.Models.Annotation;
+
+namespace JsonApiDotNetCore.Internal.Queries.Expressions
+{
+    public class IncludeElementExpression : QueryExpression
+    {
+        public RelationshipAttribute Relationship { get; }
+        public IReadOnlyCollection<IncludeElementExpression> Children { get; }
+
+        public IncludeElementExpression(RelationshipAttribute relationship)
+            : this(relationship, Array.Empty<IncludeElementExpression>())
+        {
+        }
+
+        public IncludeElementExpression(RelationshipAttribute relationship, IReadOnlyCollection<IncludeElementExpression> children)
+        {
+            Relationship = relationship ?? throw new ArgumentNullException(nameof(relationship));
+            Children = children ?? throw new ArgumentNullException(nameof(children));
+        }
+
+        public override TResult Accept<TArgument, TResult>(QueryExpressionVisitor<TArgument, TResult> visitor, TArgument argument)
+        {
+            return visitor.VisitIncludeElement(this, argument);
+        }
+
+        public override string ToString()
+        {
+            var builder = new StringBuilder();
+            builder.Append(Relationship);
+
+            if (Children.Any())
+            {
+                builder.Append('{');
+                builder.Append(string.Join(",", Children.Select(child => child.ToString())));
+                builder.Append('}');
+            }
+            
+            return builder.ToString();
+        }
+    }
+}

src/JsonApiDotNetCore/Internal/Queries/Expressions/IncludeExpression.cs

@@ -6,24 +6,22 @@ namespace JsonApiDotNetCore.Internal.Queries.Expressions
 {
     public class IncludeExpression : QueryExpression
     {
-        // TODO: Unfold into a tree of child relationships, so it can be used from ResourceDefinitions.
-
-        public IReadOnlyCollection<ResourceFieldChainExpression> Chains { get; }
+        public IReadOnlyCollection<IncludeElementExpression> Elements { get; }
 
         public static readonly IncludeExpression Empty = new IncludeExpression();
 
         private IncludeExpression()
         {
-            Chains = Array.Empty<ResourceFieldChainExpression>();
+            Elements = Array.Empty<IncludeElementExpression>();
         }
 
-        public IncludeExpression(IReadOnlyCollection<ResourceFieldChainExpression> chains)
+        public IncludeExpression(IReadOnlyCollection<IncludeElementExpression> elements)
         {
-            Chains = chains ?? throw new ArgumentNullException(nameof(chains));
+            Elements = elements ?? throw new ArgumentNullException(nameof(elements));
 
-            if (!chains.Any())
+            if (!elements.Any())
             {
-                throw new ArgumentException("Must have one or more chains.", nameof(chains));
+                throw new ArgumentException("Must have one or more elements.", nameof(elements));
             }
         }
 
@@ -34,7 +32,8 @@ public override TResult Accept<TArgument, TResult>(QueryExpressionVisitor<TArgum
 
         public override string ToString()
         {
-            return string.Join(",", Chains.Select(child => child.ToString()));
+            var chains = IncludeChainConverter.GetRelationshipChains(this);
+            return string.Join(",", chains.Select(child => child.ToString()));
         }
     }
 }

src/JsonApiDotNetCore/Internal/Queries/Expressions/QueryExpressionVisitor.cs

@@ -102,6 +102,11 @@ public virtual TResult VisitInclude(IncludeExpression expression, TArgument argu
             return DefaultVisit(expression, argument);
         }
 
+        public virtual TResult VisitIncludeElement(IncludeElementExpression expression, TArgument argument)
+        {
+            return DefaultVisit(expression, argument);
+        }
+
         public virtual TResult VisitQueryableHandler(QueryableHandlerExpression expression, TArgument argument)
         {
             return DefaultVisit(expression, argument);

src/JsonApiDotNetCore/Internal/Queries/Parsing/IncludeParser.cs

@@ -38,7 +38,7 @@ protected IncludeExpression ParseInclude()
                 chains.Add(nextChain);
             }
 
-            return new IncludeExpression(chains);
+            return IncludeChainConverter.FromRelationshipChains(chains);
         }
     }
 }