We met last week to review a design for this last week. The text of the design is below. There's some open questions that we need to follow-up on but for now we are moving forward with implementation primarily in two phases:

• Update code generation in RequestDelegateFactory to support invoking filters
• Add new APIs for registering endpoints onto a filter

Endpoint Filters Design

Date: January 27, 2022

Summary

Filters are MVC construct that allow developers to. Unlike middlewares, filters run after the routing middleware and have access to additional data that middlewares don’t. While middlewares operate on the HttpContext, filters have access MVC-specific constructs (such as HttpContext, RotueData, ActionDescriptor, and ModelState) that they can operate on.

Filters, and particularly ActionFilters , are heavily tied to action and controllers concepts in MVC and there are no parallels that exist for endpoints. This design doc outlines an approach for adding support for filters on endpoints that are registered as route handlers. Some general notes about the approach outlined here:

• It more closely aligns with the filter implementation in SignalR than the one in MVC for simplicity’s sake.
• It attempts to outline the “minimum viable product for most valuable feedback” or the simplest implementation we can ship that will allow us to gather feedback and review the implementation.
• The document outlines new APIs that need to be added. The API shape is there for illustrative purposes and not meant to be taken at face value.

Goals

• Provide support for filters that give access to request and response data
• Providing an “flexible” design that allows us to go in different directions in response to user feedback
• Endpoints without filters registered should not encounter any negative side effects related to perf/etc

Non-goals

• Implementing a default set of filters in the framework as part of this work
• Providing first-class support for handler-specific filters

Risks/Unknowns

• How will this API intersect with features like route groups?
• What are the performance ramifications for this implementation?

Proposed Design Walkthrough

1. The user implements UnsupportedContentTypeFilter by extending the IEndpointFilter interface.

public class UnsupportedContentTypeFilter : IEndpointFilter
{
	public override ValueTask<object> RunAsync(IEndpointFilterContext context, Func<IEndpointFilterContext, ValueTask<object?>> next)
	{
			// Assume last argument is some Boolean flag
			if (context.Parameters.Last())
			{
				var result = await next(context);
				if (result.ContentType != "application/json")
				{
					return new UnsupportedMediaTypeResult();
				}
				return result;
			}
	} 
}

• Framework Code

  To support this feature, we’ll be adding two new interfaces for implementing a filter and accessing it’s context.

  public class EndpointFilterContext
  {
  	public HttpContext HttpContext { get; }
  	public IList<object?> Parameters { get; } // Not read-only to premit modifying of parameters by filters
  }
  
  public interface IEndpointFilter
  {
  	public abstract ValueTask<object?> RunAsync(IEndpointFilterContext context, Func<IEndpointFilterContext, ValueTask<object?>> next)
  
  	public ValueTask OnBeforeAsync()
  
  	public ValueTask OnAfterAsync()
  }

1. A user register a filter on an endpoint by invoking their preferred AddFilter method on the RouteHandlerBuilder for the endpoint they want to target.

// Option 1
app.MapGet("/todos/{id}", (int id) => new Todo(id, $"Task {id}"))
	.AddFilter<UnsupportedContentTypeFilter>();

// Option 2
app
	.AddFilter<UnsupportedContentTypeFilter>()
	.MapGet("/todos/{id}", (int id) => new Todo(id, $"Task {id}"));

// Option 2.5
app.MapGet("/root", () => "Hello from root").AddFilter<UnsupportedContentTypeFilter>()
var rootGroup1 = app.RouteGroup().AddFilter<UnsupportedContentTypeFilter>;

// Option 3
app
	.MapGet(new UnsupportedContentTypeFilter(), "/todos/{id}", (int id) => new Todo(id, $"Task {id}"));

• Framework Code

  We expose a collection of extension methods for registering an filter on a particular endpoint.

  public static class EndpointFilterExtensions
  {
  	public static RouteHandlerBuilder AddFilter<TFilterType>();
  	public static RouteHandlerBuilder AddFilter(Type filterType);
  	public static RouteHandlerBuilder AddFilter(IEndpointFilter filter);
  	public static RouteHandlerBuilder AddFilter(Func<IEndpointFilterContext, Func<IEndpointFilterContext, Task<object>>> filter);
  }

  Under the hood, the AddFilter methods will populate a new Filters property on the RouteHandlerBuilder.

  public sealed class RouteHandlerBuilder
  {
  	internal IEnumerable<IEndpointFilter> Filters { get; set; }
  }

  The RouteHandlerBuilder.Filters property is passed to the RequestDelegateFactory.Create call in the [RouteHandlerBuilder.Map](http://RouteHandlerBuilder.Map) method. To support adding the filter invocations before/after the handler invocation, we need to restructure the RequestDelegateFactory in the following ways:

  • Add a new RequestDelegateFactory.Create overload that takes a reference to a list of filters and returns an Expression.

  public static class RequestDelegateFactory
  {
  	internal static Expression Create(
  		Delegate handler,
  		RequestDelegateFactoryOptions options = null,
  		IEnumerable<IEndpointFilter> filters = new List<IEndpointFilter>());
  }

  • Add a new RequestDelegateFactory.Compile overload that has the same method signature but produces a compiled delegate.

  public static class RequestDelegateFactory
  {
  	internal static Func<object?, HttpContext, Task> Compile(Expression requestDelegateExpression);
  }

  • Add a new RequestDelegateExpression property to the RouteEndpointBuilder class which will be used to delay the compilation of the request delegate until Build is called.

  public sealed class RouteEndpointBuilder
  {
  	public Expression RequestDelegateExpression { get; set; }
  
  	public RouteEndpointBuilder(Expression requestDelegateExpression, RoutePattern routePattern, int order);
  }

  With these overloads in place, we will “delay” the compilation of the request delegate until the Endpoint is being constructed so that we have access to the filters added after the invocation of the MapAction methods.

  public static class EndpointRouteBuilderExtensions
  {
  	public static RouteHanlderBuilder Map(this IEndpointRouteBuilder endpoints)
  	{
  		var requestDelegateExpression = RequestDelegateFactory.Create(handler, options, endpoints.Filters);
  		var requestDelegate = RequestDelegateFactory.Create(handler, options, endpoints.Filters);
  	
  	  var builder = new RouteEndpointBuilder(
  	      requestDelegateExpression,
  	      pattern,
  	      defaultOrder)
  	  {
  	      DisplayName = pattern.RawText ?? pattern.DebuggerToString(),
  	  };
  
  		endpoints.Filters.Clear();
  	}
  }

  public sealed class RouteEndpointBuilder : EndpointBuilder
  {
  	public override Endpoint Build()
    {
        if (RequestDelegate is null && RequestExpression is null)
        {
            throw new InvalidOperationException($"{nameof(RequestDelegate)} or {nameof(RequestExpression)} must be specified to construct a {nameof(RouteEndpoint)}.");
        }
  
  			if (RequestExpression is not null && RequestDelegate is null)
  			{
  				var compiledDelegate = RequestDelegateFactory.Compile(RequestExpression);
  				RequestDelegate = compiledDelegate.RequestDelegate;
  			}
  
        var routeEndpoint = new RouteEndpoint(
            RequestDelegate,
            RoutePattern,
            Order,
            new EndpointMetadataCollection(Metadata),
            DisplayName);
  
        return routeEndpoint;
    }
  }

1. The user sends a request to the endpoint with a filter registered.

$ http POST http://localhost:5000/todos/1

• Framework Code

  When the user starts up the application, the RequestDelegate associated with their endpoint is not compiled. Instead, this happens lazily when they visit the route and the routing logic invokes the [EndpointBuilder.Build](http://EndpointBuilder.Build) logic which compiles the request delegate and produces an endpoint from it.

  The request delegate that is invoked consists of a “wrapped” delegate that invokes the registered filters in FILO order before processing the user’s handler.

RequestDelegateFactory Changes

The most consequential changes in this design will happen in the RequestDelegateFactory which will need to be modified to support:

• Delaying the compilation of the complete expression until RequestDelegateFactory.Compile is invoked in [RouteEndpointBuilder.Build](http://RouteEndpointBuilder.Build) is invoked
• Supporting generating an expression tree for invoking the filters in the appropriate order
• Support for processing the arguments passed to the endpoint to both the filters and the core handler

Comments from the Call

• Is it possible to add the Result to the HttpContext so that filters can function more like middleware?
• Should the IEndpointFilterContext provide access to endpoint info like metadata, name, route template, etc?
  • As an alternative users can call GetEndpoint()
• Should it be called IEndpointFilter.RunAsync or something else?
• Should IEndpointFilter just be a delegate?
• EndpointDecorators
• How do we make sure that Validate scenarios work?