ansible: allow establishment of duplicate SSH connections

ansible_mitogen/connection.py

@@ -79,6 +79,9 @@ class Connection(ansible.plugins.connection.ConnectionBase):
     #: Set to 'ansible_ssh_timeout' by on_action_run().
     ansible_ssh_timeout = None
 
+    #: Set to 'mitogen_ssh_discriminator' by on_action_run()
+    mitogen_ssh_discriminator = None
+
     def __init__(self, play_context, new_stdin, original_transport):
         assert ansible_mitogen.process.MuxProcess.unix_listener_path, (
             'The "mitogen" connection plug-in may only be instantiated '
@@ -104,6 +107,10 @@ class Connection(ansible.plugins.connection.ConnectionBase):
         executing. We use the opportunity to grab relevant bits from the
         task-specific data.
         """
+        self.mitogen_ssh_discriminator = task_vars.get(
+            'mitogen_ssh_discriminator',
+            None
+        )
         self.ansible_ssh_timeout = task_vars.get(
             'ansible_ssh_timeout',
             None
@@ -142,6 +149,7 @@ class Connection(ansible.plugins.connection.ConnectionBase):
                 'method': 'ssh',
                 'check_host_keys': False,  # TODO
                 'hostname': self._play_context.remote_addr,
+                'discriminator': self.mitogen_ssh_discriminator,
                 'username': self._play_context.remote_user,
                 'password': self._play_context.password,
                 'port': self._play_context.port,

ansible_mitogen/services.py

@@ -47,8 +47,13 @@ class ContextService(mitogen.service.Service):
           having workers connect in directly.
 
     :param dict dct:
-        Parameters passed to mitogen.master.Router.[method](). One key,
+        Parameters passed to `mitogen.master.Router.[method]()`.
-        "method", is popped from the dictionary and used to look up the method.
+
+        * The `method` key is popped from the dictionary and used to look up
+          the Mitogen connection method.
+        * The `discriminator` key is mixed into the key used to select an
+          existing connection, but popped from the list of arguments passed to
+          the connection method.
 
     :returns mitogen.master.Context:
         Corresponding Context instance.
@@ -65,6 +70,8 @@ class ContextService(mitogen.service.Service):
 
     def dispatch(self, dct, msg):
         key = repr(sorted(dct.items()))
+        dct.pop('discriminator', None)
+
         if key not in self._context_by_key:
             method = getattr(self.router, dct.pop('method'))
             self._context_by_key[key] = method(**dct)

docs/ansible.rst

@@ -234,28 +234,34 @@ operation.
 SSH Variables
 -------------
 
+Matching Ansible's existing model, these variables are treated on a per-task
+basis, causing establishment of additional reuseable interpreters as necessary
+to match the configuration of each task.
+
 This list will grow as more missing pieces are discovered.
 
-* ansible_python_interpreter
+* ``ansible_ssh_timeout``
-* ansible_ssh_timeout
+* ``ansible_host``, ``ansible_ssh_host``
-* ansible_host, ansible_ssh_host
+* ``ansible_user``, ``ansible_ssh_user``
-* ansible_user, ansible_ssh_user
+* ``ansible_port``, ``ssh_port``
-* ansible_port, ssh_port
+* ``ansible_ssh_executable``, ``ssh_executable``
-* ansible_ssh_executable, ssh_executable
+* ``ansible_ssh_private_key_file``
-* ansible_ssh_private_key_file
+* ``ansible_ssh_pass``, ``ansible_password`` (default: assume passwordless)
-* ansible_ssh_pass, ansible_password (default: assume passwordless)
+* ``ssh_args``, ``ssh_common_args``, ``ssh_extra_args``
-* ssh_args, ssh_common_args, ssh_extra_args
+* ``mitogen_ssh_discriminator``: if present, a string mixed into the key used
+  to deduplicate connections. This permits intentional duplicate Mitogen
+  connections to a single host, which is probably only useful for testing.
 
 
 Sudo Variables
 --------------
 
-* ansible_python_interpreter
+* ``ansible_python_interpreter``
-* ansible_sudo_exe, ansible_become_exe
+* ``ansible_sudo_exe``, ``ansible_become_exe``
-* ansible_sudo_user, ansible_become_user (default: root)
+* ``ansible_sudo_user``, ``ansible_become_user`` (default: ``root``)
-* ansible_sudo_pass, ansible_become_pass (default: assume passwordless)
+* ``ansible_sudo_pass``, ``ansible_become_pass`` (default: assume passwordless)
-* sudo_flags, become_flags
+* ``sudo_flags``, ``become_flags``
-* ansible.cfg: timeout
+* ansible.cfg: ``timeout``
 
 
 Docker Variables