diff --git a/aspnetcore/fundamentals/middleware/index.md b/aspnetcore/fundamentals/middleware/index.md index c857774abcdb..e9eac056cc53 100644 --- a/aspnetcore/fundamentals/middleware/index.md +++ b/aspnetcore/fundamentals/middleware/index.md @@ -260,6 +260,7 @@ ASP.NET Core ships with the following middleware components. The *Order* column | [HTTP Strict Transport Security (HSTS)](xref:security/enforcing-ssl#http-strict-transport-security-protocol-hsts) | Security enhancement middleware that adds a special response header. | Before responses are sent and after components that modify requests. Examples: Forwarded Headers, URL Rewriting. | | [MVC](xref:mvc/overview) | Processes requests with MVC/Razor Pages. | Terminal if a request matches a route. | | [OWIN](xref:fundamentals/owin) | Interop with OWIN-based apps, servers, and middleware. | Terminal if the OWIN Middleware fully processes the request. | +| [Request Decompression](xref:fundamentals/middleware/request-decompression) | Provides support for decompressing requests. | Before components that read the request body. | | [Response Caching](xref:performance/caching/middleware) | Provides support for caching responses. | Before components that require caching. `UseCORS` must come before `UseResponseCaching`.| | [Response Compression](xref:performance/response-compression) | Provides support for compressing responses. | Before components that require compression. | | [Request Localization](xref:fundamentals/localization) | Provides localization support. | Before localization sensitive components. Must appear after Routing Middleware when using . | diff --git a/aspnetcore/fundamentals/middleware/request-decompression.md b/aspnetcore/fundamentals/middleware/request-decompression.md new file mode 100644 index 000000000000..e2f3755aa290 --- /dev/null +++ b/aspnetcore/fundamentals/middleware/request-decompression.md @@ -0,0 +1,67 @@ +--- +title: Request Decompression in ASP.NET Core +author: david-acker +description: Learn how to use the request decompression middleware in ASP.NET Core +monikerRange: '>= aspnetcore-7.0' +ms.author: david-acker +ms.date: 8/17/2022 +uid: fundamentals/middleware/request-decompression +--- +# Request Decompression in ASP.NET Core + +By [David Acker](https://github.com/david-acker) + +The request decompression middleware enables API endpoints to start accepting requests with compressed content, without requiring developers to manually handle compressed requests, by using the `Content-Encoding` HTTP header to automatically identify and decompress requests which contain compressed content. + +When the `Content-Encoding` header value on a request matches one of the available decompression providers, the middleware will use the matching provider to wrap the in an appropriate decompression stream and remove the `Content-Encoding` header (indicating that the request body is no longer compressed). For requests with uncompressed content, which specify no `Content-Encoding` header, the middleware will simply pass the requests on unchanged. + +> [!NOTE] +> * Decompression occurs when the body of the request is being read (e.g. at the endpoint, during model binding). The request body is not decompressed eagerly. +> * If the compressed data is invalid for the specified `Content-Encoding`, an exception will be thrown when attempting to read the decompressed request body. + +In the event that the middleware encounters a request with compressed content but will not be able to decompress the request, such as the request having an unsupported `Content-Encoding` header value or multiple `Content-Encoding` header values, the middleware will pass the request on changed. + +## Configuration + +The following code shows how to enable request decompression for the default `Content-Encoding` types: + +[!code-csharp[](samples/request-decompression/7.x/Program.cs?name=snippet_WithDefaultProviders&highlight=3,7)] + +## Decompression Providers + +### Default Providers + +The `Content-Encoding` header values that the request decompression middleware supports by default are listed in the following table: + +| [`Content-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding) header values | Description | +| --------- | --------- | +| `br` | [Brotli compressed data format](https://tools.ietf.org/html/rfc7932) | +| `deflate` | [DEFLATE compressed data format](https://tools.ietf.org/html/rfc1951) | +| `gzip` | [Gzip file format](https://tools.ietf.org/html/rfc1952) | + +### Custom Providers + +Support for custom or niche encodings can be added by creating custom decompression provider classes which implement : + +[!code-csharp[](samples/request-decompression/7.x/CustomDecompressionProvider.cs?name=snippet_CustomDecompressionProvider)] + +These custom decompression providers can then be registered with along with their corresponding `Content-Encoding` header values: + +[!code-csharp[](samples/request-decompression/7.x/Program.cs?name=snippet_WithCustomProvider&highlight=3-6,10)] + +## Request Size Limits + +In order to guard against [zip bombs/decompression bombs](https://en.wikipedia.org/wiki/Zip_bomb), the maximum size of the decompressed request body is limited to the request body size limit enforced by the endpoint or server. If the number of bytes read from the decompressed request body stream exceeds this limit, an [InvalidOperationException](xref:System.InvalidOperationException) will be thrown to prevent additional bytes from being read from the stream. + +If available, the size limit specified for the endpoint by , such as or for MVC endpoints, will be used. Otherwise, the global server size limit specified by will be used. + +> [!WARNING] +> Disabling the request body size limit poses a security risk in regards to uncontrolled resource consumption, particularly if the request body is being buffered. Ensure that safeguards are in place to mitigate the risk of denial of service attacks. + +## Additional Resources + +* +* [Mozilla Developer Network: Content-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding) +* [Brotli Compressed Data Format](https://www.rfc-editor.org/rfc/rfc7932) +* [DEFLATE Compressed Data Format Specification version 1.3](https://www.rfc-editor.org/rfc/rfc1951) +* [GZIP file format specification version 4.3](https://www.rfc-editor.org/rfc/rfc1952) \ No newline at end of file diff --git a/aspnetcore/fundamentals/middleware/samples/readme.txt b/aspnetcore/fundamentals/middleware/samples/readme.txt deleted file mode 100644 index ee57ae4b26b5..000000000000 --- a/aspnetcore/fundamentals/middleware/samples/readme.txt +++ /dev/null @@ -1 +0,0 @@ -Delete this file after writing sample for [#26541](https://github.com/dotnet/AspNetCore.Docs/issues/26541) diff --git a/aspnetcore/fundamentals/middleware/samples/request-decompression/7.x/CustomDecompressionProvider.cs b/aspnetcore/fundamentals/middleware/samples/request-decompression/7.x/CustomDecompressionProvider.cs new file mode 100644 index 000000000000..58dedc929e12 --- /dev/null +++ b/aspnetcore/fundamentals/middleware/samples/request-decompression/7.x/CustomDecompressionProvider.cs @@ -0,0 +1,14 @@ +using Microsoft.AspNetCore.RequestDecompression; + +namespace RequestDecompressionSample; + +#region snippet_CustomDecompressionProvider +public class CustomDecompressionProvider : IDecompressionProvider +{ + public Stream GetDecompressionStream(Stream stream) + { + // Perform custom decompression logic here + return stream; + } +} +#endregion diff --git a/aspnetcore/fundamentals/middleware/samples/request-decompression/7.x/Program.cs b/aspnetcore/fundamentals/middleware/samples/request-decompression/7.x/Program.cs new file mode 100644 index 000000000000..ee7775fe32a8 --- /dev/null +++ b/aspnetcore/fundamentals/middleware/samples/request-decompression/7.x/Program.cs @@ -0,0 +1,37 @@ +#define WithDefaultProviders // WithDefaultProviders WithCustomProvider + +using Microsoft.AspNetCore.Http.HttpResults; +using RequestDecompressionSample; + +#if WithDefaultProviders +#region snippet_WithDefaultProviders +var builder = WebApplication.CreateBuilder(args); + +builder.Services.AddRequestDecompression(); + +var app = builder.Build(); + +app.UseRequestDecompression(); + +app.MapPost("/", (HttpRequest request) => Results.Stream(request.Body)); + +app.Run(); +#endregion +#elif WithCustomProvider +#region snippet_WithCustomProvider +var builder = WebApplication.CreateBuilder(args); + +builder.Services.AddRequestDecompression(options => +{ + options.DecompressionProviders.Add("custom", new CustomDecompressionProvider()); +}); + +var app = builder.Build(); + +app.UseRequestDecompression(); + +app.MapPost("/", (HttpRequest request) => Results.Stream(request.Body)); + +app.Run(); +#endregion +#endif diff --git a/aspnetcore/fundamentals/middleware/samples/request-decompression/7.x/RequestDecompressionSample.csproj b/aspnetcore/fundamentals/middleware/samples/request-decompression/7.x/RequestDecompressionSample.csproj new file mode 100644 index 000000000000..f1fe53268f8d --- /dev/null +++ b/aspnetcore/fundamentals/middleware/samples/request-decompression/7.x/RequestDecompressionSample.csproj @@ -0,0 +1,9 @@ + + + + net7.0 + enable + enable + + + \ No newline at end of file