[Alpha] Add new route functions (...WithExtensions)

[64J0]

Description

With this PR, I'm adding some new endpoint routing functions based on what was presented at PR #619. The new routing functions are:

• routeWithExtensions
• routefWithExtensions
• subRouteWithExtensions

There is a new sample showing how to use it with ASP.NET's Rate limiting middleware, a new docs section was added to explain this new feature and more unit tests were added.

From the DOCUMENTATION (added with this PR):

ASP.NET Core provides several "extension" functions which can be used to fine-tune the HTTP handler behaviour. For example, there's the Rate limiting and Output caching middlewares.

By using the Endpoint Routing module we can leverage this along with the ...WithExtensions routing functions: routeWithExtensions, routefWithExtensions and subRouteWithExtensions.

Basically, whenever you decide to use a routing function variant with ...WithExtensions you're required to provide as the first parameter a function that obbeys the ConfigureEndpoint type definition:

// Note: IEndpointConventionBuilder is a shorter version of Microsoft.AspNetCore.Builder.IEndpointConventionBuilder
type ConfigureEndpoint = IEndpointConventionBuilder -> IEndpointConventionBuilder

And you can use it like this:

let MY_RATE_LIMITER = "fixed"

let endpoints: list<Endpoint> =
    [
        GET [
            routeWithExtensions (fun eb -> eb.RequireRateLimiting MY_RATE_LIMITER) "/rate-limit" (text "Hello World")
            route "/no-rate-limit" (text "Hello World: No Rate Limit!")
        ]
    ]

In this example, we're using the ASP.NET Rate limiting middleware for the path /rate-limit, and not using it for /no-rate-limit. If you'd like to test it, check the sample at the official repository under the path samples/RateLimiting/. There's a README.md file with instructions on how to run it locally.

Note that for those extensions to work properly, you'll probably need to make additional changes to the server. Please check the official extension documentation page to know more about this.

How to test

• Check the CI;
• Check the new sample.

Related issues

• Related to Asp.NET Rate Limiter middleware support #618

[TheAngryByrd]

I'm not a fan the DU. This means if someone wants to extend this functionality they have to edit giraffe source code. And if they're doing something custom it's not something we'd want to accept.

It would be better to have a list of IEndpointConventionBuilder -> IEndpointConventionBuilder/unit functions and maybe provide helpers for known ones we'd want to support.

[64J0]

I changed the code to expose the type ConfigureEndpoint = IEndpointConventionBuilder -> IEndpointConventionBuilder to the client. Is this aligned to what you had in mind?

[64J0]

@nojaf and @mrtz-j I'd like to know your opinion too

[nojaf]

From afar this looks good, I agree with Jimmy his comment.

[nojaf]

Again, fine by me but I would try to get a hold of the folks who actually want this. Give them the alpha and take it from there.

[nojaf]

-alpha-001 or however it is done here.

[64J0]

Good catch, done!

[nojaf]

alpha

[64J0]

Done!

[nojaf]

Is it used anywhere?

[64J0]

I don't think so, but since I'm not sure why it was added in the first place, I'll leave it there and remove the comment.

[64J0]

Removed this comment

[TheAngryByrd]

Looks great. Agree with @nojaf. Time to let people try it and get feedback.