base/SOURCES/key-connection-pools-off-cu...

From 99274b9e7524be7e8f041e327be1dd7ba3fdc8a4 Mon Sep 17 00:00:00 2001
From: Jeremy Cline <jcline@redhat.com>
Date: Thu, 21 Apr 2016 10:56:28 -0700
Subject: [PATCH] Key connection pools off custom keys

---
 CONTRIBUTORS.txt         |   3 +
 docs/managers.rst        |  44 +++++++++
 test/test_poolmanager.py | 230 ++++++++++++++++++++++++++++++++++++++++++++++-
 urllib3/poolmanager.py   | 104 +++++++++++++++++++--
 4 files changed, 371 insertions(+), 10 deletions(-)

diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt
index 5141a50..f32faaa 100644
--- a/CONTRIBUTORS.txt
+++ b/CONTRIBUTORS.txt
@@ -142,5 +142,8 @@ In chronological order:
 * Alex Gaynor <alex.gaynor@gmail.com>
   * Updates to the default SSL configuration

+* Jeremy Cline <jeremy@jcline.org>
+  * Added connection pool keys by scheme
+
 * [Your name or handle] <[email or website]>
   * [Brief summary of your changes]
diff --git a/docs/managers.rst b/docs/managers.rst
index 6c841b7..ef91ca4 100644
--- a/docs/managers.rst
+++ b/docs/managers.rst
@@ -28,6 +28,44 @@ so you don't have to.
     >>> conn.num_requests
     3

+A :class:`.PoolManager` will create a new :doc:`ConnectionPool <pools>`
+when no :doc:`ConnectionPools <pools>` exist with a matching pool key.
+The pool key is derived using the requested URL and the current values
+of the ``connection_pool_kw`` instance variable on :class:`.PoolManager`.
+
+The keys in ``connection_pool_kw`` used when deriving the key are
+configurable. For example, by default the ``my_field`` key is not
+considered.
+
+.. doctest ::
+
+    >>> from urllib3.poolmanager import PoolManager
+    >>> manager = PoolManager(10, my_field='wheat')
+    >>> manager.connection_from_url('http://example.com')
+    >>> manager.connection_pool_kw['my_field'] = 'barley'
+    >>> manager.connection_from_url('http://example.com')
+    >>> len(manager.pools)
+    1
+
+To make the pool manager create new pools when the value of
+``my_field`` changes, you can define a custom pool key and alter
+the ``key_fn_by_scheme`` instance variable on :class:`.PoolManager`.
+
+.. doctest ::
+
+    >>> import functools
+    >>> from collections import namedtuple
+    >>> from urllib3.poolmanager import PoolManager, HTTPPoolKey
+    >>> from urllib3.poolmanager import default_key_normalizer as normalizer
+    >>> CustomKey = namedtuple('CustomKey', HTTPPoolKey._fields + ('my_field',))
+    >>> manager = PoolManager(10, my_field='wheat')
+    >>> manager.key_fn_by_scheme['http'] = functools.partial(normalizer, CustomKey)
+    >>> manager.connection_from_url('http://example.com')
+    >>> manager.connection_pool_kw['my_field'] = 'barley'
+    >>> manager.connection_from_url('http://example.com')
+    >>> len(manager.pools)
+    2
+
 The API of a :class:`.PoolManager` object is similar to that of a
 :doc:`ConnectionPool <pools>`, so they can be passed around interchangeably.

@@ -59,6 +97,12 @@ API

     .. autoclass:: PoolManager
        :inherited-members:
+    .. autoclass:: BasePoolKey
+       :inherited-members:
+    .. autoclass:: HTTPPoolKey
+       :inherited-members:
+    .. autoclass:: HTTPSPoolKey
+       :inherited-members:

 ProxyManager
 ============
diff --git a/test/test_poolmanager.py b/test/test_poolmanager.py
index 6195d51..fb134fb 100644
--- a/test/test_poolmanager.py
+++ b/test/test_poolmanager.py
@@ -1,11 +1,21 @@
+import functools
 import unittest
+from collections import namedtuple

-from urllib3.poolmanager import PoolManager
+from urllib3.poolmanager import (
+    _default_key_normalizer,
+    HTTPPoolKey,
+    HTTPSPoolKey,
+    key_fn_by_scheme,
+    PoolManager,
+    SSL_KEYWORDS,
+)
 from urllib3 import connection_from_url
 from urllib3.exceptions import (
     ClosedPoolError,
     LocationValueError,
 )
+from urllib3.util import retry, timeout


 class TestPoolManager(unittest.TestCase):
@@ -87,6 +97,224 @@ class TestPoolManager(unittest.TestCase):

         self.assertEqual(len(p.pools), 0)

+    def test_http_pool_key_fields(self):
+        """Assert the HTTPPoolKey fields are honored when selecting a pool."""
+        connection_pool_kw = {
+            'timeout': timeout.Timeout(3.14),
+            'retries': retry.Retry(total=6, connect=2),
+            'block': True,
+            'strict': True,
+            'source_address': '127.0.0.1',
+        }
+        p = PoolManager()
+        conn_pools = [
+            p.connection_from_url('http://example.com/'),
+            p.connection_from_url('http://example.com:8000/'),
+            p.connection_from_url('http://other.example.com/'),
+        ]
+
+        for key, value in connection_pool_kw.items():
+            p.connection_pool_kw[key] = value
+            conn_pools.append(p.connection_from_url('http://example.com/'))
+
+        self.assertTrue(
+            all(
+                x is not y
+                for i, x in enumerate(conn_pools)
+                for j, y in enumerate(conn_pools)
+                if i != j
+            )
+        )
+        self.assertTrue(
+            all(
+                isinstance(key, HTTPPoolKey)
+                for key in p.pools.keys())
+        )
+
+    def test_http_pool_key_extra_kwargs(self):
+        """Assert non-HTTPPoolKey fields are ignored when selecting a pool."""
+        p = PoolManager()
+        conn_pool = p.connection_from_url('http://example.com/')
+        p.connection_pool_kw['some_kwarg'] = 'that should be ignored'
+        other_conn_pool = p.connection_from_url('http://example.com/')
+
+        self.assertTrue(conn_pool is other_conn_pool)
+
+    def test_http_pool_key_https_kwargs(self):
+        """Assert HTTPSPoolKey fields are ignored when selecting a HTTP pool."""
+        p = PoolManager()
+        conn_pool = p.connection_from_url('http://example.com/')
+        for key in SSL_KEYWORDS:
+            p.connection_pool_kw[key] = 'this should be ignored'
+        other_conn_pool = p.connection_from_url('http://example.com/')
+
+        self.assertTrue(conn_pool is other_conn_pool)
+
+    def test_https_pool_key_fields(self):
+        """Assert the HTTPSPoolKey fields are honored when selecting a pool."""
+        connection_pool_kw = {
+            'timeout': timeout.Timeout(3.14),
+            'retries': retry.Retry(total=6, connect=2),
+            'block': True,
+            'strict': True,
+            'source_address': '127.0.0.1',
+            'key_file': '/root/totally_legit.key',
+            'cert_file': '/root/totally_legit.crt',
+            'cert_reqs': 'CERT_REQUIRED',
+            'ca_certs': '/root/path_to_pem',
+            'ssl_version': 'SSLv23_METHOD',
+        }
+        p = PoolManager()
+        conn_pools = [
+            p.connection_from_url('https://example.com/'),
+            p.connection_from_url('https://example.com:4333/'),
+            p.connection_from_url('https://other.example.com/'),
+        ]
+        # Asking for a connection pool with the same key should give us an
+        # existing pool.
+        dup_pools = []
+
+        for key, value in connection_pool_kw.items():
+            p.connection_pool_kw[key] = value
+            conn_pools.append(p.connection_from_url('https://example.com/'))
+            dup_pools.append(p.connection_from_url('https://example.com/'))
+
+        self.assertTrue(
+            all(
+                x is not y
+                for i, x in enumerate(conn_pools)
+                for j, y in enumerate(conn_pools)
+                if i != j
+            )
+        )
+        self.assertTrue(all(pool in conn_pools for pool in dup_pools))
+        self.assertTrue(
+            all(
+                isinstance(key, HTTPSPoolKey)
+                for key in p.pools.keys())
+        )
+
+    def test_https_pool_key_extra_kwargs(self):
+        """Assert non-HTTPSPoolKey fields are ignored when selecting a pool."""
+        p = PoolManager()
+        conn_pool = p.connection_from_url('https://example.com/')
+        p.connection_pool_kw['some_kwarg'] = 'that should be ignored'
+        other_conn_pool = p.connection_from_url('https://example.com/')
+
+        self.assertTrue(conn_pool is other_conn_pool)
+
+    def test_default_pool_key_funcs_copy(self):
+        """Assert each PoolManager gets a copy of ``pool_keys_by_scheme``."""
+        p = PoolManager()
+        self.assertEqual(p.key_fn_by_scheme, p.key_fn_by_scheme)
+        self.assertFalse(p.key_fn_by_scheme is key_fn_by_scheme)
+
+    def test_pools_keyed_with_from_host(self):
+        """Assert pools are still keyed correctly with connection_from_host."""
+        ssl_kw = {
+            'key_file': '/root/totally_legit.key',
+            'cert_file': '/root/totally_legit.crt',
+            'cert_reqs': 'CERT_REQUIRED',
+            'ca_certs': '/root/path_to_pem',
+            'ssl_version': 'SSLv23_METHOD',
+        }
+        p = PoolManager(5, **ssl_kw)
+        conns = []
+        conns.append(
+            p.connection_from_host('example.com', 443, scheme='https')
+        )
+
+        for k in ssl_kw:
+            p.connection_pool_kw[k] = 'newval'
+            conns.append(
+                p.connection_from_host('example.com', 443, scheme='https')
+            )
+
+        self.assertTrue(
+            all(
+                x is not y
+                for i, x in enumerate(conns)
+                for j, y in enumerate(conns)
+                if i != j
+            )
+        )
+
+    def test_https_connection_from_url_case_insensitive(self):
+        """Assert scheme case is ignored when pooling HTTPS connections."""
+        p = PoolManager()
+        pool = p.connection_from_url('https://example.com/')
+        other_pool = p.connection_from_url('HTTPS://EXAMPLE.COM/')
+
+        self.assertEqual(1, len(p.pools))
+        self.assertTrue(pool is other_pool)
+        self.assertTrue(all(isinstance(key, HTTPSPoolKey) for key in p.pools.keys()))
+
+    def test_https_connection_from_host_case_insensitive(self):
+        """Assert scheme case is ignored when getting the https key class."""
+        p = PoolManager()
+        pool = p.connection_from_host('example.com', scheme='https')
+        other_pool = p.connection_from_host('EXAMPLE.COM', scheme='HTTPS')
+
+        self.assertEqual(1, len(p.pools))
+        self.assertTrue(pool is other_pool)
+        self.assertTrue(all(isinstance(key, HTTPSPoolKey) for key in p.pools.keys()))
+
+    def test_https_connection_from_context_case_insensitive(self):
+        """Assert scheme case is ignored when getting the https key class."""
+        p = PoolManager()
+        context = {'scheme': 'https', 'host': 'example.com', 'port': '443'}
+        other_context = {'scheme': 'HTTPS', 'host': 'EXAMPLE.COM', 'port': '443'}
+        pool = p.connection_from_context(context)
+        other_pool = p.connection_from_context(other_context)
+
+        self.assertEqual(1, len(p.pools))
+        self.assertTrue(pool is other_pool)
+        self.assertTrue(all(isinstance(key, HTTPSPoolKey) for key in p.pools.keys()))
+
+    def test_http_connection_from_url_case_insensitive(self):
+        """Assert scheme case is ignored when pooling HTTP connections."""
+        p = PoolManager()
+        pool = p.connection_from_url('http://example.com/')
+        other_pool = p.connection_from_url('HTTP://EXAMPLE.COM/')
+
+        self.assertEqual(1, len(p.pools))
+        self.assertTrue(pool is other_pool)
+        self.assertTrue(all(isinstance(key, HTTPPoolKey) for key in p.pools.keys()))
+
+    def test_http_connection_from_host_case_insensitive(self):
+        """Assert scheme case is ignored when getting the https key class."""
+        p = PoolManager()
+        pool = p.connection_from_host('example.com', scheme='http')
+        other_pool = p.connection_from_host('EXAMPLE.COM', scheme='HTTP')
+
+        self.assertEqual(1, len(p.pools))
+        self.assertTrue(pool is other_pool)
+        self.assertTrue(all(isinstance(key, HTTPPoolKey) for key in p.pools.keys()))
+
+    def test_http_connection_from_context_case_insensitive(self):
+        """Assert scheme case is ignored when getting the https key class."""
+        p = PoolManager()
+        context = {'scheme': 'http', 'host': 'example.com', 'port': '8080'}
+        other_context = {'scheme': 'HTTP', 'host': 'EXAMPLE.COM', 'port': '8080'}
+        pool = p.connection_from_context(context)
+        other_pool = p.connection_from_context(other_context)
+
+        self.assertEqual(1, len(p.pools))
+        self.assertTrue(pool is other_pool)
+        self.assertTrue(all(isinstance(key, HTTPPoolKey) for key in p.pools.keys()))
+
+    def test_custom_pool_key(self):
+        """Assert it is possible to define addition pool key fields."""
+        custom_key = namedtuple('CustomKey', HTTPPoolKey._fields + ('my_field',))
+        p = PoolManager(10, my_field='barley')
+
+        p.key_fn_by_scheme['http'] = functools.partial(_default_key_normalizer, custom_key)
+        p.connection_from_url('http://example.com')
+        p.connection_pool_kw['my_field'] = 'wheat'
+        p.connection_from_url('http://example.com')
+
+        self.assertEqual(2, len(p.pools))
+

 if __name__ == '__main__':
     unittest.main()
diff --git a/urllib3/poolmanager.py b/urllib3/poolmanager.py
index b8d1e74..4fdae8d 100644
--- a/urllib3/poolmanager.py
+++ b/urllib3/poolmanager.py
@@ -1,3 +1,5 @@
+import collections
+import functools
 import logging

 try:  # Python 3
@@ -17,16 +19,69 @@ from .util.retry import Retry
 __all__ = ['PoolManager', 'ProxyManager', 'proxy_from_url']


+log = logging.getLogger(__name__)
+
+SSL_KEYWORDS = ('key_file', 'cert_file', 'cert_reqs', 'ca_certs',
+                'ssl_version', 'ca_cert_dir')
+
+# The base fields to use when determining what pool to get a connection from;
+# these do not rely on the ``connection_pool_kw`` and can be determined by the
+# URL and potentially the ``urllib3.connection.port_by_scheme`` dictionary.
+#
+# All custom key schemes should include the fields in this key at a minimum.
+BasePoolKey = collections.namedtuple('BasePoolKey', ('scheme', 'host', 'port'))
+
+# The fields to use when determining what pool to get a HTTP and HTTPS
+# connection from. All additional fields must be present in the PoolManager's
+# ``connection_pool_kw`` instance variable.
+HTTPPoolKey = collections.namedtuple(
+    'HTTPPoolKey', BasePoolKey._fields + ('timeout', 'retries', 'strict',
+                                          'block', 'source_address')
+)
+HTTPSPoolKey = collections.namedtuple(
+    'HTTPSPoolKey', HTTPPoolKey._fields + SSL_KEYWORDS
+)
+
+
+def _default_key_normalizer(key_class, request_context):
+    """
+    Create a pool key of type ``key_class`` for a request.
+
+    According to RFC 3986, both the scheme and host are case-insensitive.
+    Therefore, this function normalizes both before constructing the pool
+    key for an HTTPS request. If you wish to change this behaviour, provide
+    alternate callables to ``key_fn_by_scheme``.
+
+    :param key_class:
+        The class to use when constructing the key. This should be a namedtuple
+        with the ``scheme`` and ``host`` keys at a minimum.
+
+    :param request_context:
+        A dictionary-like object that contain the context for a request.
+        It should contain a key for each field in the :class:`HTTPPoolKey`
+    """
+    context = {}
+    for key in key_class._fields:
+        context[key] = request_context.get(key)
+    context['scheme'] = context['scheme'].lower()
+    context['host'] = context['host'].lower()
+    return key_class(**context)
+
+
+# A dictionary that maps a scheme to a callable that creates a pool key.
+# This can be used to alter the way pool keys are constructed, if desired.
+# Each PoolManager makes a copy of this dictionary so they can be configured
+# globally here, or individually on the instance.
+key_fn_by_scheme = {
+    'http': functools.partial(_default_key_normalizer, HTTPPoolKey),
+    'https': functools.partial(_default_key_normalizer, HTTPSPoolKey),
+}
+
 pool_classes_by_scheme = {
     'http': HTTPConnectionPool,
     'https': HTTPSConnectionPool,
 }

-log = logging.getLogger(__name__)
-
-SSL_KEYWORDS = ('key_file', 'cert_file', 'cert_reqs', 'ca_certs',
-                'ssl_version')
-

 class PoolManager(RequestMethods):
     """
@@ -64,6 +119,11 @@ class PoolManager(RequestMethods):
         self.pools = RecentlyUsedContainer(num_pools,
                                            dispose_func=lambda p: p.close())

+        # Locally set the pool classes and keys so other PoolManagers can
+        # override them.
+        self.pool_classes_by_scheme = pool_classes_by_scheme
+        self.key_fn_by_scheme = key_fn_by_scheme.copy()
+
     def __enter__(self):
         return self

@@ -109,10 +169,36 @@ class PoolManager(RequestMethods):
         if not host:
             raise LocationValueError("No host specified.")

-        scheme = scheme or 'http'
-        port = port or port_by_scheme.get(scheme, 80)
-        pool_key = (scheme, host, port)
+        request_context = self.connection_pool_kw.copy()
+        request_context['scheme'] = scheme or 'http'
+        if not port:
+            port = port_by_scheme.get(request_context['scheme'].lower(), 80)
+        request_context['port'] = port
+        request_context['host'] = host
+
+        return self.connection_from_context(request_context)
+
+    def connection_from_context(self, request_context):
+        """
+        Get a :class:`ConnectionPool` based on the request context.
+
+        ``request_context`` must at least contain the ``scheme`` key and its
+        value must be a key in ``key_fn_by_scheme`` instance variable.
+        """
+        scheme = request_context['scheme'].lower()
+        pool_key_constructor = self.key_fn_by_scheme[scheme]
+        pool_key = pool_key_constructor(request_context)
+
+        return self.connection_from_pool_key(pool_key)

+    def connection_from_pool_key(self, pool_key):
+        """
+        Get a :class:`ConnectionPool` based on the provided pool key.
+
+        ``pool_key`` should be a namedtuple that only contains immutable
+        objects. At a minimum it must have the ``scheme``, ``host``, and
+        ``port`` fields.
+        """
         with self.pools.lock:
             # If the scheme, host, or port doesn't match existing open
             # connections, open a new ConnectionPool.
@@ -121,7 +207,7 @@ class PoolManager(RequestMethods):
                 return pool

             # Make a fresh ConnectionPool of the desired type
-            pool = self._new_pool(scheme, host, port)
+            pool = self._new_pool(pool_key.scheme, pool_key.host, pool_key.port)
             self.pools[pool_key] = pool

         return pool
--
2.5.5