Merge branch 'main' into mapichov/154_utf8_headers

.gitignore

@@ -232,7 +232,6 @@ ClientBin/
 *.dbmdl
 *.dbproj.schemaview
 *.jfm
-*.pfx
 *.publishsettings
 orleans.codegen.cs
 

NuGet.config

@@ -5,7 +5,7 @@
     <!-- Feed to use to restore the Arcade SDK from -->
     <add key="dotnet-eng" value="https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-eng/nuget/v3/index.json" />
     <!-- Feeds to use to restore dependent packages from -->
-    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
+    <add key="dotnet-public" value="https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-public/nuget/v3/index.json" />
     <add key="dotnet-tools" value="https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-tools/nuget/v3/index.json" />
     <!-- Feed for benchmark infrastructure to restore Microsoft.NETCore.App.Runtime for self-contained builds -->
     <add key="dotnet6" value="https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet6/nuget/v3/index.json" />

README.md

@@ -6,9 +6,9 @@ YARP is a reverse proxy toolkit for building fast proxy servers in .NET using th
 
 We expect YARP to ship as a library and project template that together provide a robust, performant proxy server. Its pipeline and modules are designed so that you can then customize the functionality for your needs. For example, while YARP supports configuration files, we expect that many users will want to manage the configuration programmatically based on their own backend configuration management system, YARP will provide a configuration API to enable that customization in-proc.  YARP is designed with customizability as a primary scenario, rather than requiring you to break out to script or having to rebuild from source.
 
-# Current Status
+# Updates
 
-For the latest status updates, see our [Status Report thread](https://github.com/microsoft/reverse-proxy/issues/97). Subscribe to notifications on that issue and we'll comment regularly with status updates.
+For regular updates, see our [releases page](https://github.com/microsoft/reverse-proxy/releases). Subscribe to release notifications on this repository to be notified of future updates (Watch -> Custom -> Releases).
 
 # Build
 

docs/docfx/articles/getting_started.md

@@ -7,7 +7,7 @@ title: Getting Started with YARP
 
 YARP is designed as a library that provides the core proxy functionality which you can then customize by adding or replacing modules. YARP is currently provided as a NuGet package and code snippets. We plan on providing a project template and pre-built exe in the future. 
 
-YARP 1.0.0 Preview 8 supports ASP.NET Core 3.1 and 5.0. You can download the .NET 5 SDK from https://dotnet.microsoft.com/download/dotnet/5.0. ASP.NET Core 5.0 on Windows requires Visual Studio 2019 v16.8 or newer.
+YARP 1.0.0 Preview 9 supports ASP.NET Core 3.1 and 5.0. You can download the .NET 5 SDK from https://dotnet.microsoft.com/download/dotnet/5.0. ASP.NET Core 5.0 on Windows requires Visual Studio 2019 v16.8 or newer.
 
 ### Create a new project
 
@@ -35,7 +35,7 @@ And then add:
 
  ```XML
 <ItemGroup> 
-  <PackageReference Include="Microsoft.ReverseProxy" Version="1.0.0-preview.8.*" />
+  <PackageReference Include="Microsoft.ReverseProxy" Version="1.0.0-preview.9.*" />
 </ItemGroup> 
 ```
 

docs/docfx/articles/session-affinity.md

@@ -7,15 +7,14 @@ Session affinity is a mechanism to bind (affinitize) a causally related request
 
 ## Configuration
 ### Services and middleware registration
-Session affinity services are registered in the DI container via `AddSessionAffinityProvider()` method which is automatically called by `AddReverseProxy()`. The middleware `UseAffinitizedDestinationLookup()` and `UseRequestAffinitizer()` are included by default in the parameterless MapReverseProxy method. If you are customizing the proxy pipeline, place the first middleware **before** adding `LoadBalancingMiddleware` and the second **after** load balancing.
+Session affinity services are registered in the DI container via `AddSessionAffinityProvider()` method which is automatically called by `AddReverseProxy()`. The middleware `UseAffinitizedDestinationLookup()` is included by default in the parameterless MapReverseProxy method. If you are customizing the proxy pipeline, place the first middleware **before** adding `LoadBalancingMiddleware` load balancing.
 
 Example:
 ```C#
 endpoints.MapReverseProxy(proxyPipeline =>
 {
     proxyPipeline.UseAffinitizedDestinationLookup();
     proxyPipeline.UseProxyLoadBalancing();
-    proxyPipeline.UseRequestAffinitizer();
 });
 ```
 
@@ -77,4 +76,4 @@ There are two built-in failure policies.  The default is `Redistribute`.
 The session affinity mechanisms are implemented by the services (mentioned above) and the two following middleware:
 1. `AffinitizedDestinationLookupMiddleware` - coordinates the request's affinity resolution process. First, it calls a provider implementing the mode specified for the given cluster on `ClusterConfig.SessionAffinity.Mode` property. Then, it checks the affinity resolution status returned by the provider, and calls a failure handling policy set on `ClusterConfig.SessionAffinity.FailurePolicy` in case of failures. It must be added to the pipeline **before** the load balancer.
 
-2. `AffinitizeRequestMiddleware` - sets the key on the response if a new affinity has been established for the request. Otherwise, if the request follows an existing affinity, it does nothing. It must be added to the pipeline **after** the load balancer.
+2. `AffinitizeTransform` - sets the key on the response if a new affinity has been established for the request. Otherwise, if the request follows an existing affinity, it does nothing. This is automatically added as a response transform.

docs/docfx/articles/transforms.md

@@ -497,8 +497,8 @@ The {Prefix}PathBase header value is taken from `HttpContext.Request.PathBase`.
 | Key | Value | Default | Required |
 |-----|-------|---------|----------|
 | Forwarded | A comma separated list containing any of these values: for,by,proto,host | (none) | yes |
-| ForFormat | Random/RandomAndPort/Unknown/UnknownAndPort/Ip/IpAndPort | Random | no |
-| ByFormat | Random/RandomAndPort/Unknown/UnknownAndPort/Ip/IpAndPort | Random | no |
+| ForFormat | Random/RandomAndPort/RandomAndRandomPort/Unknown/UnknownAndPort/UnknownAndRandomPort/Ip/IpAndPort/IpAndRandomPort | Random | no |
+| ByFormat | Random/RandomAndPort/RandomAndRandomPort/Unknown/UnknownAndPort/UnknownAndRandomPort/Ip/IpAndPort/IpAndRandomPort | Random | no |
 | Append | true/false | true | no |
 
 Config:
@@ -543,10 +543,13 @@ The RFC allows a [variety of formats](https://tools.ietf.org/html/rfc7239#sectio
 |--------|-------------|---------|
 | Random | An obfuscated identifier that is generated randomly per request. This allows for diagnostic tracing scenarios while limiting the flow of uniquely identifying information for privacy reasons. | `by=_YQuN68tm6` |
 | RandomAndPort | The Random identifier plus the port. | `by="_YQuN68tm6:80"` |
+| RandomAndRandomPort | The Random identifier plus another random identifier for the port. | `by="_YQuN68tm6:_jDw5Cf3tQ"` |
 | Unknown | This can be used when the identity of the preceding entity is not known, but the proxy server still wants to signal that the request was forwarded. | `by=unknown` |
 | UnknownAndPort | The Unknown identifier plus the port if available. | `by="unknown:80"` |
+| UnknownAndRandomPort | The Unknown identifier plus random identifier for the port. | `by="unknown:_jDw5Cf3tQ"` |
 | Ip | An IPv4 address or an IPv6 address including brackets. | `by="[::1]"` |
 | IpAndPort | The IP address plus the port. | `by="[::1]:80"` |
+| IpAndRandomPort | The IP address plus random identifier for the port. | `by="[::1]:_jDw5Cf3tQ"` |
 
 ### ClientCert
 
@@ -686,15 +689,15 @@ ResponseTrailer follows the same structure and guidance as ResponseHeader.
 
 ### AddRequestTransform
 
-[AddRequestTransform](xref:Microsoft.ReverseProxy.Abstractions.Config.TransformBuilderContextFuncExtensions) is a `TransformBuilderContext` extension method that defines a request transform as a `Func<RequestTransformContext, Task>`. This allows creating a custom request transform without implementing a `RequestTransform` derived class.
+[AddRequestTransform](xref:Microsoft.ReverseProxy.Abstractions.Config.TransformBuilderContextFuncExtensions) is a `TransformBuilderContext` extension method that defines a request transform as a `Func<RequestTransformContext, ValueTask>`. This allows creating a custom request transform without implementing a `RequestTransform` derived class.
 
 ### AddResponseTransform
 
-[AddResponseTransform](xref:Microsoft.ReverseProxy.Abstractions.Config.TransformBuilderContextFuncExtensions) is a `TransformBuilderContext` extension method that defines a response transform as a `Func<ResponseTransformContext, Task>`. This allows creating a custom response transform without implementing a `ResponseTransform` derived class.
+[AddResponseTransform](xref:Microsoft.ReverseProxy.Abstractions.Config.TransformBuilderContextFuncExtensions) is a `TransformBuilderContext` extension method that defines a response transform as a `Func<ResponseTransformContext, ValueTask>`. This allows creating a custom response transform without implementing a `ResponseTransform` derived class.
 
 ### AddResponseTrailersTransform
 
-[AddResponseTrailersTransform](xref:Microsoft.ReverseProxy.Abstractions.Config.TransformBuilderContextFuncExtensions) is a `TransformBuilderContext` extension method that defines a response trailers transform as a `Func<ResponseTrailersTransformContext, Task>`. This allows creating a custom response trailers transform without implementing a `ResponseTrailersTransform` derived class.
+[AddResponseTrailersTransform](xref:Microsoft.ReverseProxy.Abstractions.Config.TransformBuilderContextFuncExtensions) is a `TransformBuilderContext` extension method that defines a response trailers transform as a `Func<ResponseTrailersTransformContext, ValueTask>`. This allows creating a custom response trailers transform without implementing a `ResponseTrailersTransform` derived class.
 
 ### RequestTransform
 
@@ -755,7 +758,7 @@ services.AddReverseProxy()
                 transformBuildContext.AddRequestTransform(transformContext =>
                 {
                     transformContext.ProxyRequest.Headers.Add("CustomHeader", value);
-                    return Task.CompletedTask;
+                    return default;
                 });
             }
         }
@@ -810,7 +813,7 @@ services.AddReverseProxy()
                 context.AddRequestTransform(transformContext =>
                 {
                     transformContext.ProxyRequest.Headers.Add("CustomHeader", value);
-                    return Task.CompletedTask;
+                    return default;
                 });
 
                 return true; // Matched

docs/docfx/readme.md

@@ -14,6 +14,6 @@ The build will produce a series of HTML files in the `_site` directory. Many of
 
 The docs are automatically built and published by a [GitHub Action](https://github.com/microsoft/reverse-proxy/blob/main/.github/workflows/docfx_build.yml) on every push to `release/docs`. The built `_site` directory is pushed to the `gh-pages` branch and served by [https://microsoft.github.io/reverse-proxy/](https://microsoft.github.io/reverse-proxy/). Maintaining a seperate branch for the released docs allows us to choose when to publish them and with what content, and without modifying the build scripts each release.
 
-Doc edits for the current public release should go into that release's branch (e.g. `release/1.0.0-preview3`) and merged forward into `main`. Then `release/docs` should be reset to that release branch's position.
+Doc edits for the current public release should go into that release's branch (e.g. `release/1.0.0-preview3`) and merged forward into `main` and `release/docs`.
 
 When publishing a new product version (e.g. `release/1.0.0-preview4`) `release/docs` should be reset to that position after the docs have been updated.

docs/operations/BackportingToPreview.md

@@ -0,0 +1,21 @@
+# Backporting changes to a preview branch
+
+Backporting changes is very similar to a regular release. Changes are made on the preview branch, the builds are validated and ultimately released.
+
+- Checkout the preview branch
+
+  `git checkout release/1.0.0-previewX`
+- Make and commit any changes
+- Push the changes **to your own fork** and submit a PR against the preview branch
+- Once the PR is merged, wait for the internal [`microsoft-reverse-proxy-official`](https://dev.azure.com/dnceng/internal/_build?definitionId=809&_a=summary&view=branches) pipeline to produce a build
+- Validate the build the same way you would for a regular release [docs](https://github.com/microsoft/reverse-proxy/blob/main/docs/operations/Release.md#validate-the-final-build)
+- Package Artifacts from this build can be shared to validate the patch. Optionally, the artifacts from the [public pipeline](https://dev.azure.com/dnceng/public/_build?definitionId=807&view=branches) can be used
+- Continue iterating on the preview branch until satisfied with the validation of the change
+- [Release the build](https://github.com/microsoft/reverse-proxy/blob/main/docs/operations/Release.md#release-the-build) from the preview branch
+- Update the preview tag to the released commit
+
+  **While still on the preview branch:**
+  - `git tag -d v1.0.0-previewX` (delete the current tag)
+  - `git tag v1.0.0-previewX` (re-create the tag on the current commit)
+  - `git push upstream --tags --force` (force push the tag change to the upstream repo (**not your fork**))
+- Update the description of the [release](https://github.com/microsoft/reverse-proxy/releases) if necessary. The associated tag/commit will be automatically updated by the previous step.