Demonstrates how to use a database function in a filter query string parameter

Author: bkoelman

src/Examples/JsonApiDotNetCoreExample/CustomFunctions/Decrypt/DecryptExpression.cs

@@ -0,0 +1,79 @@
+using System.Text;
+using JsonApiDotNetCore.Queries.Expressions;
+
+namespace JsonApiDotNetCoreExample.CustomFunctions.Decrypt;
+
+/// <summary>
+/// This expression allows to call the user-defined "decrypt_data" database function. It represents the "decrypt" function, resulting from text such as:
+/// <c>
+/// decrypt(title)
+/// </c>
+/// , or:
+/// <c>
+/// decrypt(owner.lastName)
+/// </c>
+/// .
+/// </summary>
+internal sealed class DecryptExpression(ResourceFieldChainExpression targetAttribute) : FunctionExpression
+{
+    public const string Keyword = "decrypt";
+
+    /// <summary>
+    /// The CLR type this function returns, which is always <see cref="string" />.
+    /// </summary>
+    public override Type ReturnType { get; } = typeof(string);
+
+    /// <summary>
+    /// The string attribute to decrypt. Chain format: an optional list of to-one relationships, followed by an attribute.
+    /// </summary>
+    public ResourceFieldChainExpression TargetAttribute { get; } = targetAttribute;
+
+    public override TResult Accept<TArgument, TResult>(QueryExpressionVisitor<TArgument, TResult> visitor, TArgument argument)
+    {
+        return visitor.DefaultVisit(this, argument);
+    }
+
+    public override string ToString()
+    {
+        return InnerToString(false);
+    }
+
+    public override string ToFullString()
+    {
+        return InnerToString(true);
+    }
+
+    private string InnerToString(bool toFullString)
+    {
+        var builder = new StringBuilder();
+
+        builder.Append(Keyword);
+        builder.Append('(');
+        builder.Append(toFullString ? TargetAttribute.ToFullString() : TargetAttribute);
+        builder.Append(')');
+
+        return builder.ToString();
+    }
+
+    public override bool Equals(object? obj)
+    {
+        if (ReferenceEquals(this, obj))
+        {
+            return true;
+        }
+
+        if (obj is null || GetType() != obj.GetType())
+        {
+            return false;
+        }
+
+        var other = (DecryptExpression)obj;
+
+        return TargetAttribute.Equals(other.TargetAttribute);
+    }
+
+    public override int GetHashCode()
+    {
+        return TargetAttribute.GetHashCode();
+    }
+}

src/Examples/JsonApiDotNetCoreExample/CustomFunctions/Decrypt/DecryptFilterParser.cs

@@ -0,0 +1,53 @@
+using JsonApiDotNetCore.Queries.Expressions;
+using JsonApiDotNetCore.Queries.Parsing;
+using JsonApiDotNetCore.QueryStrings.FieldChains;
+using JsonApiDotNetCore.Resources;
+using JsonApiDotNetCore.Resources.Annotations;
+
+namespace JsonApiDotNetCoreExample.CustomFunctions.Decrypt;
+
+internal sealed class DecryptFilterParser(IResourceFactory resourceFactory) : FilterParser(resourceFactory)
+{
+    protected override bool IsFunction(string name)
+    {
+        if (name == DecryptExpression.Keyword)
+        {
+            return true;
+        }
+
+        return base.IsFunction(name);
+    }
+
+    protected override FunctionExpression ParseFunction()
+    {
+        if (TokenStack.TryPeek(out Token? nextToken) && nextToken is { Kind: TokenKind.Text, Value: DecryptExpression.Keyword })
+        {
+            return ParseDecrypt();
+        }
+
+        return base.ParseFunction();
+    }
+
+    private DecryptExpression ParseDecrypt()
+    {
+        EatText(DecryptExpression.Keyword);
+        EatSingleCharacterToken(TokenKind.OpenParen);
+
+        int chainStartPosition = GetNextTokenPositionOrEnd();
+
+        ResourceFieldChainExpression targetAttributeChain =
+            ParseFieldChain(BuiltInPatterns.ToOneChainEndingInAttribute, FieldChainPatternMatchOptions.None, ResourceTypeInScope, null);
+
+        ResourceFieldAttribute attribute = targetAttributeChain.Fields[^1];
+
+        if (attribute.Property.PropertyType != typeof(string))
+        {
+            int position = chainStartPosition + GetRelativePositionOfLastFieldInChain(targetAttributeChain);
+            throw new QueryParseException("Attribute of type 'String' expected.", position);
+        }
+
+        EatSingleCharacterToken(TokenKind.CloseParen);
+
+        return new DecryptExpression(targetAttributeChain);
+    }
+}

src/Examples/JsonApiDotNetCoreExample/CustomFunctions/Decrypt/DecryptWhereClauseBuilder.cs

@@ -0,0 +1,24 @@
+using System.Linq.Expressions;
+using JsonApiDotNetCore.Queries.Expressions;
+using JsonApiDotNetCore.Queries.QueryableBuilding;
+
+namespace JsonApiDotNetCoreExample.CustomFunctions.Decrypt;
+
+internal sealed class DecryptWhereClauseBuilder : WhereClauseBuilder
+{
+    public override Expression DefaultVisit(QueryExpression expression, QueryClauseBuilderContext context)
+    {
+        if (expression is DecryptExpression decryptExpression)
+        {
+            return VisitDecrypt(decryptExpression, context);
+        }
+
+        return base.DefaultVisit(expression, context);
+    }
+
+    private Expression VisitDecrypt(DecryptExpression expression, QueryClauseBuilderContext context)
+    {
+        Expression propertyAccess = Visit(expression.TargetAttribute, context);
+        return Expression.Call(null, FunctionStub.DecryptMethod, propertyAccess);
+    }
+}

src/Examples/JsonApiDotNetCoreExample/CustomFunctions/Decrypt/FunctionStub.cs

@@ -0,0 +1,16 @@
+using System.Reflection;
+
+#pragma warning disable AV1008 // Class should not be static
+
+namespace JsonApiDotNetCoreExample.CustomFunctions.Decrypt;
+
+internal static class FunctionStub
+{
+    public static readonly MethodInfo DecryptMethod = typeof(FunctionStub).GetMethod(nameof(Decrypt), [typeof(string)])!;
+
+    // ReSharper disable once UnusedParameter.Global
+    public static string Decrypt(string text)
+    {
+        throw new InvalidOperationException($"The '{nameof(Decrypt)}' function cannot be called client-side.");
+    }
+}

src/Examples/JsonApiDotNetCoreExample/Data/AppDbContext.cs

@@ -1,4 +1,5 @@
 using JetBrains.Annotations;
+using JsonApiDotNetCoreExample.CustomFunctions.Decrypt;
 using JsonApiDotNetCoreExample.Models;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Metadata;
@@ -26,6 +27,9 @@ protected override void OnModelCreating(ModelBuilder builder)
             .WithOne(todoItem => todoItem.Owner);
 
         AdjustDeleteBehaviorForJsonApi(builder);
+
+        builder.HasDbFunction(FunctionStub.DecryptMethod)
+            .HasName("decrypt_data");
     }
 
     private static void AdjustDeleteBehaviorForJsonApi(ModelBuilder builder)

src/Examples/JsonApiDotNetCoreExample/Data/Seeder.cs

@@ -1,5 +1,6 @@
 using JetBrains.Annotations;
 using JsonApiDotNetCoreExample.Models;
+using Microsoft.EntityFrameworkCore;
 
 namespace JsonApiDotNetCoreExample.Data;
 
@@ -52,5 +53,22 @@ public static async Task CreateSampleDataAsync(AppDbContext dbContext)
 
         dbContext.TodoItems.AddRange(todoItems.Elements);
         await dbContext.SaveChangesAsync();
+
+        // Just for demo purposes, decryption is defined as: prefix and suffix the incoming value with an underscore.
+        await dbContext.Database.ExecuteSqlRawAsync("""
+            CREATE OR REPLACE FUNCTION decrypt_data(value text)
+              RETURNS text
+            RETURN '_' || value || '_';
+            """);
+
+        dbContext.TodoItems.Add(new TodoItem
+        {
+            Description = "secret",
+            Priority = priorities.GetNext(),
+            CreatedAt = DateTimeOffset.UtcNow,
+            Owner = people.GetNext()
+        });
+
+        await dbContext.SaveChangesAsync();
     }
 }

src/Examples/JsonApiDotNetCoreExample/Program.cs

@@ -4,6 +4,9 @@
 using JsonApiDotNetCore.Configuration;
 using JsonApiDotNetCore.Diagnostics;
 using JsonApiDotNetCoreExample;
+using JsonApiDotNetCore.Queries.Parsing;
+using JsonApiDotNetCore.Queries.QueryableBuilding;
+using JsonApiDotNetCoreExample.CustomFunctions.Decrypt;
 using JsonApiDotNetCoreExample.Data;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Diagnostics;
@@ -27,6 +30,9 @@ static WebApplication CreateWebApplication(string[] args)
 
     WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
 
+    builder.Services.AddTransient<IFilterParser, DecryptFilterParser>();
+    builder.Services.AddTransient<IWhereClauseBuilder, DecryptWhereClauseBuilder>();
+
     // Add services to the container.
     ConfigureServices(builder);
 

src/Examples/JsonApiDotNetCoreExample/Properties/launchSettings.json

@@ -12,15 +12,15 @@
     "IIS Express": {
       "commandName": "IISExpress",
       "launchBrowser": true,
-      "launchUrl": "api/todoItems?include=owner,assignee,tags&filter=equals(priority,'High')",
+      "launchUrl": "api/todoItems?include=owner,assignee,tags&filter=equals(decrypt(description),'_secret_')",
       "environmentVariables": {
         "ASPNETCORE_ENVIRONMENT": "Development"
       }
     },
     "Kestrel": {
       "commandName": "Project",
       "launchBrowser": true,
-      "launchUrl": "api/todoItems?include=owner,assignee,tags&filter=equals(priority,'High')",
+      "launchUrl": "api/todoItems?include=owner,assignee,tags&filter=equals(decrypt(description),'_secret_')",
       "applicationUrl": "https://localhost:44340;http://localhost:14140",
       "environmentVariables": {
         "ASPNETCORE_ENVIRONMENT": "Development"