Use pooled StringBuilder to reduce allocations when adding response cookies

- #561
- new `SetCookieHeaderValue.AppendToStringBuilder()` method; avoids per-call `StringBuilder` allocation
- `ResponseCookies` uses `ObjectPool<StringBuilder>` that `ResponseCookiesFeature` provides
 - `ResponseCookies` works fine if no `ObjectPoolProvider` is available
- `IHttpContextFactory` instance is a singleton instantiated from CI
 - make `HttpContextFactory` `ObjectPoolProvider` and `ResponseCookiesFeature`-aware
 - apply same pattern to sample `PooledHttpContextFactory`
- pool is not currently configurable; defaults are fine for response cookies
 - if we need (policy) configuration, would add an `IOptions<HttpContextFactorySettings>`

nit: Add some doc comments

Author: dougbu

samples/SampleApp/PooledHttpContextFactory.cs

@@ -1,24 +1,48 @@
 // 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;
 using System.Collections.Generic;
+using System.Text;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Http.Features;
+using Microsoft.AspNetCore.Http.Features.Internal;
+using Microsoft.Extensions.ObjectPool;
 
 namespace SampleApp
 {
     public class PooledHttpContextFactory : IHttpContextFactory
     {
+        private readonly ObjectPool<StringBuilder> _builderPool;
         private readonly IHttpContextAccessor _httpContextAccessor;
         private readonly Stack<PooledHttpContext> _pool = new Stack<PooledHttpContext>();
 
-        public PooledHttpContextFactory(IHttpContextAccessor httpContextAccessor)
+        public PooledHttpContextFactory(ObjectPoolProvider poolProvider)
+            : this(poolProvider, httpContextAccessor: null)
         {
+        }
+
+        public PooledHttpContextFactory(ObjectPoolProvider poolProvider, IHttpContextAccessor httpContextAccessor)
+        {
+            if (poolProvider == null)
+            {
+                throw new ArgumentNullException(nameof(poolProvider));
+            }
+
+            _builderPool = poolProvider.CreateStringBuilderPool();
             _httpContextAccessor = httpContextAccessor;
         }
 
         public HttpContext Create(IFeatureCollection featureCollection)
         {
+            if (featureCollection == null)
+            {
+                throw new ArgumentNullException(nameof(featureCollection));
+            }
+
+            var responseCookiesFeature = new ResponseCookiesFeature(featureCollection, _builderPool);
+            featureCollection.Set<IResponseCookiesFeature>(responseCookiesFeature);
+
             PooledHttpContext httpContext = null;
             lock (_pool)
             {

src/Microsoft.AspNetCore.Http.Features/IResponseCookies.cs

@@ -4,36 +4,39 @@
 namespace Microsoft.AspNetCore.Http
 {
     /// <summary>
-    /// A wrapper for the response Set-Cookie header
+    /// A wrapper for the response Set-Cookie header.
     /// </summary>
     public interface IResponseCookies
     {
         /// <summary>
-        /// Add a new cookie and value
+        /// Add a new cookie and value.
         /// </summary>
-        /// <param name="key"></param>
-        /// <param name="value"></param>
+        /// <param name="key">Name of the new cookie.</param>
+        /// <param name="value">Value of the new cookie.</param>
         void Append(string key, string value);
 
         /// <summary>
-        /// Add a new cookie
+        /// Add a new cookie.
         /// </summary>
-        /// <param name="key"></param>
-        /// <param name="value"></param>
-        /// <param name="options"></param>
+        /// <param name="key">Name of the new cookie.</param>
+        /// <param name="value">Value of the new cookie.</param>
+        /// <param name="options"><see cref="CookieOptions"/> included in the new cookie setting.</param>
         void Append(string key, string value, CookieOptions options);
 
         /// <summary>
-        /// Sets an expired cookie
+        /// Sets an expired cookie.
         /// </summary>
-        /// <param name="key"></param>
+        /// <param name="key">Name of the cookie to expire.</param>
         void Delete(string key);
 
         /// <summary>
-        /// Sets an expired cookie
+        /// Sets an expired cookie.
         /// </summary>
-        /// <param name="key"></param>
-        /// <param name="options"></param>
+        /// <param name="key">Name of the cookie to expire.</param>
+        /// <param name="options">
+        /// <see cref="CookieOptions"/> used to discriminate the particular cookie to expire. The
+        /// <see cref="CookieOptions.Domain"/> and <see cref="CookieOptions.Path"/> values are especially important.
+        /// </param>
         void Delete(string key, CookieOptions options);
     }
 }

src/Microsoft.AspNetCore.Http.Features/IResponseCookiesFeature.cs

@@ -3,8 +3,14 @@
 
 namespace Microsoft.AspNetCore.Http.Features
 {
+    /// <summary>
+    /// A helper for creating the response Set-Cookie header.
+    /// </summary>
     public interface IResponseCookiesFeature
     {
+        /// <summary>
+        /// Gets the wrapper for the response Set-Cookie header.
+        /// </summary>
         IResponseCookies Cookies { get; }
     }
 }

src/Microsoft.AspNetCore.Http/Features/ResponseCookiesFeature.cs

@@ -1,32 +1,68 @@
 // 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;
+using System.Text;
 using Microsoft.AspNetCore.Http.Internal;
+using Microsoft.Extensions.ObjectPool;
 
 namespace Microsoft.AspNetCore.Http.Features.Internal
 {
+    /// <summary>
+    /// Default implementation of <see cref="IResponseCookiesFeature"/>.
+    /// </summary>
     public class ResponseCookiesFeature : IResponseCookiesFeature
     {
+        // Object pool will be null only in test scenarios e.g. if code news up a DefaultHttpContext.
+        private readonly ObjectPool<StringBuilder> _builderPool;
+
         private FeatureReferences<IHttpResponseFeature> _features;
         private IResponseCookies _cookiesCollection;
 
+        /// <summary>
+        /// Initializes a new <see cref="ResponseCookiesFeature"/> instance.
+        /// </summary>
+        /// <param name="features">
+        /// <see cref="IFeatureCollection"/> containing all defined features, including this
+        /// <see cref="IResponseCookiesFeature"/> and the <see cref="IHttpResponseFeature"/>.
+        /// </param>
         public ResponseCookiesFeature(IFeatureCollection features)
+            : this(features, builderPool: null)
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new <see cref="ResponseCookiesFeature"/> instance.
+        /// </summary>
+        /// <param name="features">
+        /// <see cref="IFeatureCollection"/> containing all defined features, including this
+        /// <see cref="IResponseCookiesFeature"/> and the <see cref="IHttpResponseFeature"/>.
+        /// </param>
+        /// <param name="builderPool">The <see cref="ObjectPool{T}"/>, if available.</param>
+        public ResponseCookiesFeature(IFeatureCollection features, ObjectPool<StringBuilder> builderPool)
         {
+            if (features == null)
+            {
+                throw new ArgumentNullException(nameof(features));
+            }
+
             _features = new FeatureReferences<IHttpResponseFeature>(features);
+            _builderPool = builderPool;
         }
 
-        private IHttpResponseFeature HttpResponseFeature =>
-            _features.Fetch(ref _features.Cache, f => null);
+        private IHttpResponseFeature HttpResponseFeature => _features.Fetch(ref _features.Cache, f => null);
 
+        /// <inheritdoc />
         public IResponseCookies Cookies
         {
             get
             {
                 if (_cookiesCollection == null)
                 {
                     var headers = HttpResponseFeature.Headers;
-                    _cookiesCollection = new ResponseCookies(headers);
+                    _cookiesCollection = new ResponseCookies(headers, _builderPool);
                 }
+
                 return _cookiesCollection;
             }
         }

src/Microsoft.AspNetCore.Http/HttpContextFactory.cs

@@ -1,30 +1,51 @@
 // 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;
+using System.Text;
 using Microsoft.AspNetCore.Http.Features;
+using Microsoft.AspNetCore.Http.Features.Internal;
+using Microsoft.Extensions.ObjectPool;
 
 namespace Microsoft.AspNetCore.Http.Internal
 {
     public class HttpContextFactory : IHttpContextFactory
     {
-        private IHttpContextAccessor _httpContextAccessor;
+        private readonly ObjectPool<StringBuilder> _builderPool;
+        private readonly IHttpContextAccessor _httpContextAccessor;
 
-        public HttpContextFactory() : this(httpContextAccessor: null)
+        public HttpContextFactory(ObjectPoolProvider poolProvider)
+            : this(poolProvider, httpContextAccessor: null)
         {
         }
 
-        public HttpContextFactory(IHttpContextAccessor httpContextAccessor)
+        public HttpContextFactory(ObjectPoolProvider poolProvider, IHttpContextAccessor httpContextAccessor)
         {
+            if (poolProvider == null)
+            {
+                throw new ArgumentNullException(nameof(poolProvider));
+            }
+
+            _builderPool = poolProvider.CreateStringBuilderPool();
             _httpContextAccessor = httpContextAccessor;
         }
 
         public HttpContext Create(IFeatureCollection featureCollection)
         {
+            if (featureCollection == null)
+            {
+                throw new ArgumentNullException(nameof(featureCollection));
+            }
+
+            var responseCookiesFeature = new ResponseCookiesFeature(featureCollection, _builderPool);
+            featureCollection.Set<IResponseCookiesFeature>(responseCookiesFeature);
+
             var httpContext = new DefaultHttpContext(featureCollection);
             if (_httpContextAccessor != null)
             {
                 _httpContextAccessor.HttpContext = httpContext;
             }
+
             return httpContext;
         }