Here's a treasure trove of reverse proxy

YARP 1.0 has been released and is now available for download from NuGet. YARP (Yet Another Reverse Proxy) is a highly customizable reverse proxy built using .NET. The biggest difference between YARP and other reverse proxies is how it is built and packaged - YARP is provided as a library and examples showing how to create a proxy tailored to the needs of a specific scenario.

What is a reverse proxy?

A reverse proxy is used to listen for incoming HTTP requests and forward the request to the appropriate server based on the content of the request. Unlike typical firewalls/routers that work at layer 4 (TCP/IP), reverse proxies usually work at layer 7, so they understand http and work based on http fields.

When YARP proxies a request, it handles the HTTP connection from the client and then creates its own connection to the target server, and both parties can benefit from connection pooling.

Using a reverse proxy has many advantages:

• It acts as a public endpoint for a site or set of services, making the exposed url space independent of the actual implementation
• Forward calls to backend servers to do the actual work, balancing the load between them
• Can offload work from backend servers, e.g. TLS encryption, Auth 2, compression, caching

What is YARP

YARP is a project that provides an open source reverse proxy server based on .NET. It started about two years ago when we noticed a pattern of questions from teams at Microsoft who were either building a reverse proxy for their service or had been asking about APIs and techniques for building a reverse proxy. We decided to have them work together on a common solution, which is YARP.

YARP is a reverse proxy toolkit for using ASP.NET and .NET infrastructure and building fast proxy servers in .NET. The key differentiator of YARP is that its design is easy to customize and adjust to match the specific needs of each deployment scenario.

When we talked to the teams that created the Microsoft services, each service was slightly off the beaten track, either building their own solutions or trying to customize third-party proxies. While they have a solution for HTTP/1.1, they require HTTP/2 - usually used for gRPC, and HTTP/2 uses a binary frame format, which is much more complicated to implement. YARP gives developers complete control while leveraging the proven ASP.NET Core and .NET feature set, along with the productivity of C# (or other .NET languages).

YARP plugs into ASP .NET as middleware for handling incoming requests, and YARP provides two main paths for usage and customization:

• As a full-featured proxy - YARP uses configuration to define a set of URL-pattern-based routes that map to a cluster of target servers, and each target in the cluster should be able to handle requests for the routes the cluster maps to. The list of targets is filtered based on session affinity and server health, then a load balancing algorithm is used to choose between the remaining targets. Each of these sections can be customized through configuration, and customers can add additional modules or replace stock modules as needed. The configuration system is extensible so routing and destination information can be extracted from sources such as Service Fabric.
• Alternatively, for highly customized environments, the YARP request forwarder can be invoked directly, bypassing routing, load balancing modules, etc. For example, this is how Azure App Service uses YARP to route requests to a specific instance, where the location of the instance rotates on demand.

These can even be used together in the same process, switching between them based on routing.

Getting Started with

Unlike other proxies provided as extensible executables, YARP inverts the model. You create proxies with a template called YARP, which makes it easier to add your own customizations and functionality to YARP.

The following example is based on .NET 6's new simplified template. Example applies to for .NET Core 3.1 and .NET 5.

1. Install .NET 6 if not already installed from https://dotnet.microsoft.com/download
2. Create a new web project using
   dotnet new web --name MyYarpProxy

3. Add a reference to the YARP nuget package:

   dotnet add package MyYarpProxy Yarp.ReverseProxy

4. Replace the code in program.cs with:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));

var app = builder.Build();

app.MapReverseProxy();

app.Run();

5. Replace the configuration file in appsettings.json with:

{
    "Urls": "http://localhost:5000;https://localhost:5001",
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning"
        }
    },
    "AllowedHosts": "*",
    "ReverseProxy": {
        "Routes": {
            "minimumroute": {
                "ClusterId": "minimumcluster",
                "Match": {
                    "Path": "{**catch-all}"
                }
            }
        },

        "Clusters": {
            "minimumcluster": {
                "Destinations": {
                    "httpbin.org": {
                        "Address": "https://httpbin.org/"
                    }
                }
            }
        }
    }
}

This will create a proxy to listen http://localhost:5000 and https://localhost:5001 and route any requests to https://httpbin.org (a useful site for http debugging ), config.

What's in YARP 1.0

This YARP 1.0 release includes the following features:

config

• YARP configuration defines routes and destinations. It can be provided by:

1. Static configuration file with dynamically updated file change detection
2. Programmatic configuration scalability to interface with other sources

• For hyperscale hosting, routing can be fully dynamic, determined by application code and handled by YARP on a per-request basis

Routing and Inbound Connections

• YARP can multiple sites and routes based on SNI/Host
• Routing can be based on request URL and header value
• Active and passive health checks to confirm destination availability and filter out bad requests
• Session Affinity will route subsequent requests to the same destination request-based URL
• Multiple algorithms for load balancing across destinations
• Route-specific authentication, authorization and CORS

Proxy and outbound connections

• The incoming request URL can be converted before being passed to the destination
• Can convert request and response header
• Can convert Http method (eg POST to PUT)
• Outbound http connection to destination is configurable
• Proxy adds standard header related to request forwarding
• gRPC and web socket traffic, including streaming

Diagnostics

• metrics for monitoring performance
• Logging to track each request in detail

general

• Brokers with cloud-scale performance
• Documentation
• Easily extensible - customers can add middleware to customize proxy functionality such as routing, header manipulation
• Supports .NET Core 3.1, .NET 5 and .NET 6

performance

The performance of the proxy will depend on many factors:

• The http version used by the client for the proxy
• The http version used by the target proxy
• Whether to use TLS encryption
• Size of request/response headers and content payload

We have a set of benchmarks that we run daily against YARP and other proxy servers. This was measured in the lab using the " Citrine " hardware definition created to measure the TechEmpower benchmark. The results are presented using a PowerBI dashboard and can be used for comparison with other agents. For example, compare YARP and Envoy's (incoming and outgoing protocols) http-http1.1 and https-https1.1 with the 10/21 results as follows:
The dashboard can be found at https://aka.ms/aspnet/benchmarks . There, at the bottom of the page is a widget for selecting pages. Proxy results on page 16.

prompts : Clicking the text "1 of 21" will pop up a page menu, in which "Proxy" can be directly selected.

open source

YARP is being developed and delivered as an open source project. It is hosted on github at https://github.com/microsoft/reverse-proxy . We appreciate everyone's contributions, questions, and discussions.

supports

YARP support is provided by the product team (engineers working on YARP) consisting of members of the ASP.NET and core library networking teams. We don't offer 24/7 support or "pagers", but we generally have good time zone coverage as our team members are located in Prague and Redmond. Bugs should be reported in github using the issue template and a reply is usually given within 24 hours. If you find a security issue, we ask you to report it through the Microsoft Security Response Center ( MSRC ).

We will provide 1.0 services for security or other major issues. New features will be considered in future releases. We expect to start releasing preview builds of the next version in the next few months.

what's next

The work of the reverse proxy will continue. Items on our list that we are working on for the next release include:

• HTTP/3 support - preliminary tests show it mostly works, but we hope there is a solid implementation in ARP # 1208
• More performance optimizations - we're pushing performance again and using YARP to bring additional performance features into .NET
• Use LLHTTP provides more control over outbound connections and more efficient header handling. LLHTTP is an experiment aimed at developing a lower-level HTTP API than HttpClient to give more control over how HTTP requests are made and processed.
• Support for Service Fabric – Early preview releases of YARP include a module for Service Fabric integration. This is insufficient for typical large-scale site deployments for sites using Service Fabric. We are working with SF team members to implement a more robust and scalable solution for dynamically provisioning agents based on SF data # 257
• @jkotalik wrote a prototype implementation for Kubernetes integration. The Microsoft team members working on YARP are not experts in k8s deployment, so we are working with community members to further develop this integration. # 200