diff --git a/src/Middleware/HttpOverrides/src/ForwardedHeaders.cs b/src/Middleware/HttpOverrides/src/ForwardedHeaders.cs index f161c3aee7..0da2b10622 100644 --- a/src/Middleware/HttpOverrides/src/ForwardedHeaders.cs +++ b/src/Middleware/HttpOverrides/src/ForwardedHeaders.cs @@ -5,13 +5,31 @@ using System; namespace Microsoft.AspNetCore.HttpOverrides { + /// + /// Flags for controlling which forwarders are processed. + /// [Flags] public enum ForwardedHeaders { + /// + /// Do not process any forwarders + /// None = 0, + /// + /// Process X-Forwarded-For, which identifies the originating IP address of the client. + /// XForwardedFor = 1 << 0, + /// + /// Process X-Forwarded-Host, which identifies the original host requested by the client. + /// XForwardedHost = 1 << 1, + /// + /// Process X-Forwarded-Proto, which identifies the protocol (HTTP or HTTPS) the client used to connect. + /// XForwardedProto = 1 << 2, + /// + /// Process X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Proto. + /// All = XForwardedFor | XForwardedHost | XForwardedProto } } diff --git a/src/Middleware/HttpOverrides/src/ForwardedHeadersExtensions.cs b/src/Middleware/HttpOverrides/src/ForwardedHeadersExtensions.cs index 3572c3d72a..eb50f3a41f 100644 --- a/src/Middleware/HttpOverrides/src/ForwardedHeadersExtensions.cs +++ b/src/Middleware/HttpOverrides/src/ForwardedHeadersExtensions.cs @@ -7,15 +7,22 @@ using Microsoft.Extensions.Options; namespace Microsoft.AspNetCore.Builder { + /// + /// Extension methods for enabling . + /// public static class ForwardedHeadersExtensions { private const string ForwardedHeadersAdded = "ForwardedHeadersAdded"; /// - /// Forwards proxied headers onto current request + /// Applies forwarded headers to their matching fields on the current request. + /// + /// By convention, HTTP proxies forward information from the client in well-known HTTP headers. + /// The reads these headers and fills in the associated fields on HttpContext. + /// /// - /// - /// + /// The . + /// A reference to after the operation has completed. public static IApplicationBuilder UseForwardedHeaders(this IApplicationBuilder builder) { if (builder == null) @@ -35,11 +42,15 @@ namespace Microsoft.AspNetCore.Builder } /// - /// Forwards proxied headers onto current request + /// Applies forwarded headers to their matching fields on the current request. + /// + /// By convention, HTTP proxies forward information from the client in well-known HTTP headers. + /// The reads these headers and fills in the associated fields on HttpContext. + /// /// - /// + /// The . /// Enables the different forwarding options. - /// + /// A reference to after the operation has completed. public static IApplicationBuilder UseForwardedHeaders(this IApplicationBuilder builder, ForwardedHeadersOptions options) { if (builder == null) diff --git a/src/Middleware/HttpOverrides/src/ForwardedHeadersMiddleware.cs b/src/Middleware/HttpOverrides/src/ForwardedHeadersMiddleware.cs index c9e756d513..60170c0ce2 100644 --- a/src/Middleware/HttpOverrides/src/ForwardedHeadersMiddleware.cs +++ b/src/Middleware/HttpOverrides/src/ForwardedHeadersMiddleware.cs @@ -15,6 +15,9 @@ using Microsoft.Extensions.Primitives; namespace Microsoft.AspNetCore.HttpOverrides { + /// + /// A middleware for forwarding proxied headers onto the current request. + /// public class ForwardedHeadersMiddleware { private static readonly bool[] HostCharValidity = new bool[127]; @@ -62,6 +65,12 @@ namespace Microsoft.AspNetCore.HttpOverrides } } + /// + /// Create a new . + /// + /// The representing the next middleware in the pipeline. + /// The used for logging. + /// The for configuring the middleware. public ForwardedHeadersMiddleware(RequestDelegate next, ILoggerFactory loggerFactory, IOptions options) { if (next == null) @@ -137,12 +146,20 @@ namespace Microsoft.AspNetCore.HttpOverrides || string.Equals("0.0.0.0", host, StringComparison.Ordinal)); // IPv4 Any } + /// + /// Executes the middleware. + /// + /// The for the current request. public Task Invoke(HttpContext context) { ApplyForwarders(context); return _next(context); } + /// + /// Forward the proxied headers to the given . + /// + /// The . public void ApplyForwarders(HttpContext context) { // Gather expected headers. diff --git a/src/Middleware/HttpOverrides/src/ForwardedHeadersOptions.cs b/src/Middleware/HttpOverrides/src/ForwardedHeadersOptions.cs index 3507d9bea5..dcfe650f3d 100644 --- a/src/Middleware/HttpOverrides/src/ForwardedHeadersOptions.cs +++ b/src/Middleware/HttpOverrides/src/ForwardedHeadersOptions.cs @@ -1,4 +1,4 @@ -// Copyright (c) .NET Foundation. All rights reserved. +// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. using System.Collections.Generic; @@ -7,40 +7,46 @@ using Microsoft.AspNetCore.HttpOverrides; namespace Microsoft.AspNetCore.Builder { + /// + /// Options for + /// public class ForwardedHeadersOptions { /// - /// Use this header instead of + /// Gets or sets the header used to retrieve the originating client IP. Defaults to the value specified by + /// . /// - /// public string ForwardedForHeaderName { get; set; } = ForwardedHeadersDefaults.XForwardedForHeaderName; /// - /// Use this header instead of + /// Gets or sets the header used to retrieve the original value of the Host header field. + /// Defaults to the value specified by /// - /// public string ForwardedHostHeaderName { get; set; } = ForwardedHeadersDefaults.XForwardedHostHeaderName; /// - /// Use this header instead of + /// Gets or sets the header used to retrieve the value for the originating scheme (HTTP/HTTPS). + /// Defaults to the value specified by /// - /// public string ForwardedProtoHeaderName { get; set; } = ForwardedHeadersDefaults.XForwardedProtoHeaderName; /// - /// Use this header instead of + /// Gets or sets the header used to store the original value of client IP before applying forwarded headers. + /// Defaults to the value specified by /// /// public string OriginalForHeaderName { get; set; } = ForwardedHeadersDefaults.XOriginalForHeaderName; /// - /// Use this header instead of + /// Gets or sets the header used to store the original value of the Host header field before applying forwarded headers. + /// Defaults to the value specified by /// /// public string OriginalHostHeaderName { get; set; } = ForwardedHeadersDefaults.XOriginalHostHeaderName; /// - /// Use this header instead of + /// Gets or sets the header used to store the original scheme (HTTP/HTTPS) before applying forwarded headers. + /// Defaults to the value specified by /// /// public string OriginalProtoHeaderName { get; set; } = ForwardedHeadersDefaults.XOriginalProtoHeaderName; diff --git a/src/Middleware/HttpOverrides/src/HttpMethodOverrideExtensions.cs b/src/Middleware/HttpOverrides/src/HttpMethodOverrideExtensions.cs index 425a27adc2..07e3d06517 100644 --- a/src/Middleware/HttpOverrides/src/HttpMethodOverrideExtensions.cs +++ b/src/Middleware/HttpOverrides/src/HttpMethodOverrideExtensions.cs @@ -7,10 +7,15 @@ using Microsoft.Extensions.Options; namespace Microsoft.AspNetCore.Builder { + /// + /// Extension methods for enabling . + /// public static class HttpMethodOverrideExtensions { /// - /// Allows incoming POST request to override method type with type specified in header. + /// Allows incoming POST request to override method type with type specified in header. This middleware + /// is used when a client is limited to sending GET or POST methods but wants to invoke other HTTP methods. + /// By default, the X-HTTP-Method-Override request header is used to specify the HTTP method being tunneled. /// /// The instance this method extends. public static IApplicationBuilder UseHttpMethodOverride(this IApplicationBuilder builder) @@ -24,10 +29,13 @@ namespace Microsoft.AspNetCore.Builder } /// - /// Allows incoming POST request to override method type with type specified in form. + /// Allows incoming POST request to override method type with type specified in form. This middleware + /// is used when a client is limited to sending GET or POST methods but wants to invoke other HTTP methods. /// /// The instance this method extends. - /// The . + /// + /// The which indicates which form type specifies the override method. + /// public static IApplicationBuilder UseHttpMethodOverride(this IApplicationBuilder builder, HttpMethodOverrideOptions options) { if (builder == null) diff --git a/src/Middleware/HttpOverrides/src/HttpMethodOverrideMiddleware.cs b/src/Middleware/HttpOverrides/src/HttpMethodOverrideMiddleware.cs index 6fc75b7a36..9d44412cc7 100644 --- a/src/Middleware/HttpOverrides/src/HttpMethodOverrideMiddleware.cs +++ b/src/Middleware/HttpOverrides/src/HttpMethodOverrideMiddleware.cs @@ -9,12 +9,20 @@ using Microsoft.Extensions.Options; namespace Microsoft.AspNetCore.HttpOverrides { + /// + /// A middleware for overriding the HTTP method of an incoming POST request. + /// public class HttpMethodOverrideMiddleware { private const string xHttpMethodOverride = "X-Http-Method-Override"; private readonly RequestDelegate _next; private readonly HttpMethodOverrideOptions _options; + /// + /// Create a new . + /// + /// The representing the next middleware in the pipeline. + /// The for configuring the middleware. public HttpMethodOverrideMiddleware(RequestDelegate next, IOptions options) { if (next == null) @@ -29,6 +37,10 @@ namespace Microsoft.AspNetCore.HttpOverrides _options = options.Value; } + /// + /// Executes the middleware. + /// + /// The for the current request. public async Task Invoke(HttpContext context) { if (HttpMethods.IsPost(context.Request.Method)) diff --git a/src/Middleware/HttpOverrides/src/HttpMethodOverrideOptions.cs b/src/Middleware/HttpOverrides/src/HttpMethodOverrideOptions.cs index 8bfb82790f..df84883e3f 100644 --- a/src/Middleware/HttpOverrides/src/HttpMethodOverrideOptions.cs +++ b/src/Middleware/HttpOverrides/src/HttpMethodOverrideOptions.cs @@ -1,8 +1,13 @@ // Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. +using Microsoft.AspNetCore.HttpOverrides; + namespace Microsoft.AspNetCore.Builder { + /// + /// Options for configuring + /// public class HttpMethodOverrideOptions { /// diff --git a/src/Middleware/HttpOverrides/src/IPNetwork.cs b/src/Middleware/HttpOverrides/src/IPNetwork.cs index 034e5754b6..9c5ff7591e 100644 --- a/src/Middleware/HttpOverrides/src/IPNetwork.cs +++ b/src/Middleware/HttpOverrides/src/IPNetwork.cs @@ -1,12 +1,20 @@ -// Copyright (c) .NET Foundation. All rights reserved. +// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. using System.Net; namespace Microsoft.AspNetCore.HttpOverrides { + /// + /// A representation of an IP network based on CIDR notation. + /// public class IPNetwork { + /// + /// Create a new with the specified and prefix length. + /// + /// The . + /// The prefix length. public IPNetwork(IPAddress prefix, int prefixLength) { Prefix = prefix; @@ -15,6 +23,9 @@ namespace Microsoft.AspNetCore.HttpOverrides Mask = CreateMask(); } + /// + /// Get the that represents the prefix for the network. + /// public IPAddress Prefix { get; } private byte[] PrefixBytes { get; } @@ -26,6 +37,11 @@ namespace Microsoft.AspNetCore.HttpOverrides private byte[] Mask { get; } + /// + /// Determine whether a given The is part of the IP network. + /// + /// The . + /// if the is part of the IP network. Otherwise, . public bool Contains(IPAddress address) { if (Prefix.AddressFamily != address.AddressFamily) diff --git a/src/Middleware/HttpOverrides/src/Microsoft.AspNetCore.HttpOverrides.csproj b/src/Middleware/HttpOverrides/src/Microsoft.AspNetCore.HttpOverrides.csproj index aa225718c4..befba1fcb2 100644 --- a/src/Middleware/HttpOverrides/src/Microsoft.AspNetCore.HttpOverrides.csproj +++ b/src/Middleware/HttpOverrides/src/Microsoft.AspNetCore.HttpOverrides.csproj @@ -6,7 +6,7 @@ * HTTP method override header. $(DefaultNetCoreTargetFramework) true - $(NoWarn);CS1591 + $(NoWarn.Replace('1591', '')) true aspnetcore;proxy;headers;xforwarded false diff --git a/src/Middleware/HttpOverrides/test/IPNetworkTest.cs b/src/Middleware/HttpOverrides/test/IPNetworkTest.cs index fa9a099057..cd5c37b906 100644 --- a/src/Middleware/HttpOverrides/test/IPNetworkTest.cs +++ b/src/Middleware/HttpOverrides/test/IPNetworkTest.cs @@ -1,4 +1,4 @@ -// Copyright (c) .NET Foundation. All rights reserved. +// Copyright (c) .NET Foundation. All rights reserved. // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. using System.Net; using Xunit;