Add a Json schema for YARP configuration

YARP.sln

@@ -9,6 +9,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
 		global.json = global.json
 		NuGet.config = NuGet.config
 		TFMs.props = TFMs.props
+		eng\Versions.props = eng\Versions.props
 	EndProjectSection
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Yarp.ReverseProxy", "src\ReverseProxy\Yarp.ReverseProxy.csproj", "{568EF8AE-7624-490D-A19F-C25D076FF091}"

eng/Versions.props

@@ -33,6 +33,7 @@
     <SerilogSinksConsoleVersion>3.1.1</SerilogSinksConsoleVersion>
     <YamlDotNetVersion>16.2.1</YamlDotNetVersion>
     <KubernetesClientVersion>15.0.1</KubernetesClientVersion>
+    <JsonSchemaNetVersion>7.0.2</JsonSchemaNetVersion>
     <!-- Container app dependencies -->
     <YarpNugetVersion>2.2.0</YarpNugetVersion>
     <MicrosoftExtensionsServiceDiscovery>8.2.2</MicrosoftExtensionsServiceDiscovery>

samples/ReverseProxy.Config.Sample/appsettings.json

@@ -30,7 +30,7 @@
         // matches /download/* and routes to "allClusterProps"
         "ClusterId": "allClusterProps", // Name of one of the clusters
         "Order": 0, // Lower numbers have higher precidence, default is 0
-        "Authorization Policy": "Anonymous", // Name of the policy or "Default", "Anonymous"
+        "AuthorizationPolicy": "Anonymous", // Name of the policy or "Default", "Anonymous"
         "CorsPolicy": "disable", // Name of the CorsPolicy to apply to this route or "default", "disable"
         "Match": { // Rules that have to be met for the route to match the request
           "Path": "/download/{**remainder}", // The path to match using ASP.NET syntax.
@@ -53,7 +53,7 @@
             }
           ]
         },
-        "MetaData": { // List of key value pairs that can be used by custom extensions
+        "Metadata": { // List of key value pairs that can be used by custom extensions
           "MyName": "MyValue"
         },
         "Transforms": [ // List of transforms. See ReverseProxy.Transforms.Sample for more details
@@ -80,45 +80,67 @@
           },
           "another_destination": {
             "Address": "https://10.20.30.40",
-            "Health": "https://10.20.30.40:12345" // override for active health checks
+            "Health": "https://10.20.30.40:12345", // override for active health checks
+            "Host": "contoso",
+            "Metadata": {
+              "SomeKey": "SomeValue"
+            }
           }
         },
         "LoadBalancingPolicy": "PowerOfTwoChoices", // Alternatively "First", "Random", "RoundRobin", "LeastRequests"
         "SessionAffinity": { // Ensures subsequent requests from a client go to the same destination server
           "Enabled": true, // Defaults to 'false'
           "Policy": "HashCookie", // Default, alternatively "Cookie" or "CustomHeader"
           "FailurePolicy": "Redistribute", // default, alternatively "Return503Error"
-          "AffinityKeyName": "MySessionCookieName" // Required, no default
+          "AffinityKeyName": "MySessionCookieName", // Required, no default
+          "Cookie": { // Options for cookie based session affinity
+            "Path": "/",
+            "SameSite": "None",
+            "HttpOnly": true,
+            "Expiration": "00:30:00",
+            "Domain": "example.com",
+            "MaxAge": "08:00:00",
+            "SecurePolicy": "Always",
+            "IsEssential": true
+          }
         },
         "HealthCheck": { // Ways to determine which destinations should be filtered out due to unhealthy state
           "Active": { // Makes API calls to validate the health of each destination
-            "Enabled": "true",
+            "Enabled": true,
             "Interval": "00:00:10", // How often to query for health data
             "Timeout": "00:00:10", // Timeout for the health check request/response
             "Policy": "ConsecutiveFailures", // Or other custom policy that has been registered
-            "Path": "/favicon.ico" // API endpoint to query for health state. Looks for 2XX response codes to indicate healthy state
+            "Path": "/favicon.ico", // API endpoint to query for health state. Looks for 2XX response codes to indicate healthy state
             // Typically something like "/api/health" but used favicon to enable sample to run
+            "Query": "?healthCheck=true" // Query string to append to the health check request
           },
           "Passive": { // Disables destinations based on HTTP response codes for proxy requests
             "Enabled": true, // Defaults to false
             "Policy": "TransportFailureRate", // Or other custom policy that has been registered
             "ReactivationPeriod": "00:00:10" // how long before the destination is re-enabled
-          }
+          },
+          "AvailableDestinationsPolicy": "HealthyOrPanic" // Policy for which destinations can be used when sending requests
         },
         "HttpClient": { // Configuration of HttpClient instance used to contact destinations
-          "SSLProtocols": "Tls13",
+          "SslProtocols": [ "Tls13" ],
           "DangerousAcceptAnyServerCertificate": true, // Disables destination cert validation
           "MaxConnectionsPerServer": 1024, // Destination server can further limit this number
           "EnableMultipleHttp2Connections": true,
           "RequestHeaderEncoding": "Latin1", // How to interpret non ASCII characters in proxied request's header values
-          "ResponseHeaderEncoding": "Latin1" // How to interpret non ASCII characters in proxied request's response header values
+          "ResponseHeaderEncoding": "Latin1", // How to interpret non ASCII characters in proxied request's response header values
+          "WebProxy": { // Optinal proxy configuration for outgoing requests
+            "Address": "127.0.0.1",
+            "BypassOnLocal": true,
+            "UseDefaultCredentials": false
+          }
         },
         "HttpRequest": { // Options for sending request to destination
-          "Timeout": "00:02:00", // Timeout for the HttpRequest
+          "ActivityTimeout": "00:02:00", // Activity timeout for the request
           "Version": "2", // Http Version that should be tried first
-          "VersionPolicy": "RequestVersionOrLower" // Policy for which other versions can be be used
+          "VersionPolicy": "RequestVersionOrLower", // Policy for which other versions can be be used
+          "AllowResponseBuffering": false
         },
-        "MetaData": { // Custom Key/value pairs for extensibility
+        "Metadata": { // Custom Key/value pairs for extensibility
           "TransportFailureRateHealthPolicy.RateLimit": "0.5", // Used by Passive health policy
           "MyKey": "MyValue"
         }

samples/ReverseProxy.Transforms.Sample/appsettings.json

@@ -26,8 +26,8 @@
         },
         "Transforms": [
           { "PathPrefix": "/prefix" },
-          { "RequestHeadersCopy": "true" },
-          { "RequestHeaderOriginalHost": "false" },
+          { "RequestHeadersCopy": true },
+          { "RequestHeaderOriginalHost": false },
           {
             "RequestHeader": "foo0",
             "Append": "bar"

src/Common/Package.targets

@@ -0,0 +1,6 @@
+<Project>
+  <ItemGroup>
+    <JsonSchemaSegment Include="$(MSBuildThisFileDirectory)..\..\ConfigurationSchema.json"
+                       FilePathPattern="appsettings\..*json" />
+  </ItemGroup>
+</Project>

src/Directory.Build.props

@@ -3,6 +3,29 @@
   <!-- Recurse up. -->
   <Import Project="$(MSBuildThisFileDirectory)..\Directory.Build.props" />
 
+  <!-- Include ConfigurationSchema.json in the package if it exists. -->
+  <PropertyGroup>
+    <ConfigurationSchemaPath>$(MSBuildProjectDirectory)\ConfigurationSchema.json</ConfigurationSchemaPath>
+    <ConfigurationSchemaExists Condition="Exists('$(ConfigurationSchemaPath)')">true</ConfigurationSchemaExists>
+  </PropertyGroup>
+
+  <ItemGroup Condition="'$(ConfigurationSchemaExists)' == 'true'">
+    <None Include="$(ConfigurationSchemaPath)"
+          Pack="True"
+          PackagePath="ConfigurationSchema.json" />
+  </ItemGroup>
+
+  <PropertyGroup Condition="'$(ConfigurationSchemaExists)' == 'true'">
+    <TargetsForTfmSpecificContentInPackage>$(TargetsForTfmSpecificContentInPackage);AddPackageTargetsInPackage</TargetsForTfmSpecificContentInPackage>
+  </PropertyGroup>
+
+  <Target Name="AddPackageTargetsInPackage">
+    <ItemGroup>
+      <TfmSpecificPackageFile Include="$(MSBuildThisFileDirectory)Common\Package.targets"
+                              PackagePath="buildTransitive\$(TargetFramework)\$(PackageId).targets" />
+    </ItemGroup>
+  </Target>
+
   <PropertyGroup>
     <IsShipping>true</IsShipping>
     <IsPackable>true</IsPackable>

src/ReverseProxy/Configuration/PassiveHealthCheckConfig.cs

@@ -2,6 +2,7 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System;
+using Yarp.ReverseProxy.Model;
 
 namespace Yarp.ReverseProxy.Configuration;
 
@@ -21,7 +22,7 @@ public sealed record PassiveHealthCheckConfig
     public string? Policy { get; init; }
 
     /// <summary>
-    /// Destination reactivation period after which an unhealthy destination is considered healthy again.
+    /// Destination reactivation period after which an unhealthy destination reverts back to <see cref="DestinationHealth.Unknown"/>.
     /// </summary>
     public TimeSpan? ReactivationPeriod { get; init; }
 

src/ReverseProxy/Configuration/RouteHeader.cs

@@ -20,7 +20,7 @@ public sealed record RouteHeader
 
     /// <summary>
     /// A collection of acceptable header values used during routing. Only one value must match.
-    /// The list must not be empty unless using <see cref="HeaderMatchMode.Exists"/> or <see cref="HeaderMatchMode.NotExists"/>.
+    /// The list must not be empty unless when using <see cref="HeaderMatchMode.Exists"/> or <see cref="HeaderMatchMode.NotExists"/>.
     /// </summary>
     public IReadOnlyList<string>? Values { get; init; }
 

src/ReverseProxy/Configuration/SessionAffinityConfig.cs

@@ -30,7 +30,6 @@ public sealed record SessionAffinityConfig
     /// Identifies the name of the field where the affinity value is stored.
     /// For the cookie affinity policy this will be the cookie name.
     /// For the header affinity policy this will be the header name.
-    /// The policy will give its own default if no value is set.
     /// This value should be unique across clusters to avoid affinity conflicts.
     /// https://github.com/dotnet/yarp/issues/976
     /// This field is required.