Vendor API connection code from Docker SDK for Python (#398)

* Vendor parts of the Docker SDK for Python

This is a combination of the latest git version
(https://github.com/docker/docker-py/tree/a48a5a9647761406d66e8271f19fab7fa0c5f582)
and the version before Python 2.7 support was removed
(https://github.com/docker/docker-py/tree/650aad3a5fb84059b392ad450f760ed08143ae3f),
including some modifications to work with Ansible module_utils's
system (i.e. third-party imports are guarded, and errors are
reported during runtime through a new exception
MissingRequirementException).

* Create module_utils and plugin_utils for working with the vendored code.

The delete call cannot be called delete() since that method already exists from requests.

* Vendor more code from Docker SDK for Python.

* Adjust code from common module_utils.

* Add unit tests from Docker SDK for Python.

* Make test compile with Python 2.6, but skip them on Python 2.6.

* Skip test that requires a network server.

* Add changelog.

* Update changelogs/fragments/398-docker-api.yml

Co-authored-by: Brian Scholer <1260690+briantist@users.noreply.github.com>

* Minimum API version is 1.25.

Co-authored-by: Brian Scholer <1260690+briantist@users.noreply.github.com>

plugins/module_utils/_api/_import_helper.py

@@ -0,0 +1,96 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import traceback
+
+from ansible.module_utils.six import PY2
+
+
+REQUESTS_IMPORT_ERROR = None
+URLLIB3_IMPORT_ERROR = None
+BACKPORTS_SSL_MATCH_HOSTNAME_IMPORT_ERROR = None
+
+
+try:
+    from requests import Session
+    from requests.adapters import HTTPAdapter
+    from requests.exceptions import HTTPError, InvalidSchema
+except ImportError:
+    REQUESTS_IMPORT_ERROR = traceback.format_exc()
+
+    class Session(object):
+        __attrs__ = []
+
+    class HTTPAdapter(object):
+        __attrs__ = []
+
+    class HTTPError(Exception):
+        pass
+
+    class InvalidSchema(Exception):
+        pass
+
+
+try:
+    from requests.packages import urllib3
+except ImportError:
+    try:
+        import urllib3
+    except ImportError:
+        URLLIB3_IMPORT_ERROR = traceback.format_exc()
+
+        class _HTTPConnectionPool(object):
+            pass
+
+        class FakeURLLIB3(object):
+            def __init__(self):
+                self._collections = self
+                self.poolmanager = self
+                self.connection = self
+                self.connectionpool = self
+
+                self.RecentlyUsedContainer = object()
+                self.PoolManager = object()
+                self.match_hostname = object()
+                self.HTTPConnectionPool = _HTTPConnectionPool
+
+        urllib3 = FakeURLLIB3()
+
+
+# Monkey-patching match_hostname with a version that supports
+# IP-address checking. Not necessary for Python 3.5 and above
+if PY2:
+    try:
+        from backports.ssl_match_hostname import match_hostname
+        urllib3.connection.match_hostname = match_hostname
+    except ImportError:
+        BACKPORTS_SSL_MATCH_HOSTNAME_IMPORT_ERROR = traceback.format_exc()
+
+
+def fail_on_missing_imports():
+    if REQUESTS_IMPORT_ERROR is not None:
+        from .errors import MissingRequirementException
+
+        raise MissingRequirementException(
+            'You have to install requests',
+            'requests', REQUESTS_IMPORT_ERROR)
+    if URLLIB3_IMPORT_ERROR is not None:
+        from .errors import MissingRequirementException
+
+        raise MissingRequirementException(
+            'You have to install urllib3',
+            'urllib3', URLLIB3_IMPORT_ERROR)
+    if BACKPORTS_SSL_MATCH_HOSTNAME_IMPORT_ERROR is not None:
+        from .errors import MissingRequirementException
+
+        raise MissingRequirementException(
+            'You have to install backports.ssl-match-hostname',
+            'backports.ssl-match-hostname', BACKPORTS_SSL_MATCH_HOSTNAME_IMPORT_ERROR)

plugins/module_utils/_api/api/client.py

@@ -0,0 +1,591 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import json
+import logging
+import struct
+from functools import partial
+
+from ansible.module_utils.six import PY3, binary_type, iteritems, string_types
+from ansible.module_utils.six.moves.urllib.parse import quote
+
+from .. import auth
+from .._import_helper import fail_on_missing_imports
+from .._import_helper import HTTPError as _HTTPError
+from .._import_helper import InvalidSchema as _InvalidSchema
+from .._import_helper import Session as _Session
+from ..constants import (DEFAULT_NUM_POOLS, DEFAULT_NUM_POOLS_SSH,
+                         DEFAULT_MAX_POOL_SIZE, DEFAULT_TIMEOUT_SECONDS,
+                         DEFAULT_USER_AGENT, IS_WINDOWS_PLATFORM,
+                         MINIMUM_DOCKER_API_VERSION, STREAM_HEADER_SIZE_BYTES,
+                         DEFAULT_DATA_CHUNK_SIZE)
+from ..errors import (DockerException, InvalidVersion, TLSParameterError, MissingRequirementException,
+                      create_api_error_from_http_exception)
+from ..tls import TLSConfig
+from ..transport.npipeconn import NpipeHTTPAdapter
+from ..transport.npipesocket import PYWIN32_IMPORT_ERROR
+from ..transport.unixconn import UnixHTTPAdapter
+from ..transport.sshconn import SSHHTTPAdapter, PARAMIKO_IMPORT_ERROR
+from ..transport.ssladapter import SSLHTTPAdapter
+from ..utils import config, utils, json_stream
+from ..utils.decorators import check_resource, update_headers
+from ..utils.proxy import ProxyConfig
+from ..utils.socket import consume_socket_output, demux_adaptor, frames_iter
+
+from .daemon import DaemonApiMixin
+
+
+log = logging.getLogger(__name__)
+
+
+class APIClient(
+        _Session,
+        DaemonApiMixin):
+    """
+    A low-level client for the Docker Engine API.
+
+    Example:
+
+        >>> import docker
+        >>> client = docker.APIClient(base_url='unix://var/run/docker.sock')
+        >>> client.version()
+        {u'ApiVersion': u'1.33',
+         u'Arch': u'amd64',
+         u'BuildTime': u'2017-11-19T18:46:37.000000000+00:00',
+         u'GitCommit': u'f4ffd2511c',
+         u'GoVersion': u'go1.9.2',
+         u'KernelVersion': u'4.14.3-1-ARCH',
+         u'MinAPIVersion': u'1.12',
+         u'Os': u'linux',
+         u'Version': u'17.10.0-ce'}
+
+    Args:
+        base_url (str): URL to the Docker server. For example,
+            ``unix:///var/run/docker.sock`` or ``tcp://127.0.0.1:1234``.
+        version (str): The version of the API to use. Set to ``auto`` to
+            automatically detect the server's version. Default: ``1.35``
+        timeout (int): Default timeout for API calls, in seconds.
+        tls (bool or :py:class:`~docker.tls.TLSConfig`): Enable TLS. Pass
+            ``True`` to enable it with default options, or pass a
+            :py:class:`~docker.tls.TLSConfig` object to use custom
+            configuration.
+        user_agent (str): Set a custom user agent for requests to the server.
+        credstore_env (dict): Override environment variables when calling the
+            credential store process.
+        use_ssh_client (bool): If set to `True`, an ssh connection is made
+            via shelling out to the ssh client. Ensure the ssh client is
+            installed and configured on the host.
+        max_pool_size (int): The maximum number of connections
+            to save in the pool.
+    """
+
+    __attrs__ = _Session.__attrs__ + ['_auth_configs',
+                                      '_general_configs',
+                                      '_version',
+                                      'base_url',
+                                      'timeout']
+
+    def __init__(self, base_url=None, version=None,
+                 timeout=DEFAULT_TIMEOUT_SECONDS, tls=False,
+                 user_agent=DEFAULT_USER_AGENT, num_pools=None,
+                 credstore_env=None, use_ssh_client=False,
+                 max_pool_size=DEFAULT_MAX_POOL_SIZE):
+        super(APIClient, self).__init__()
+
+        fail_on_missing_imports()
+
+        if tls and not base_url:
+            raise TLSParameterError(
+                'If using TLS, the base_url argument must be provided.'
+            )
+
+        self.base_url = base_url
+        self.timeout = timeout
+        self.headers['User-Agent'] = user_agent
+
+        self._general_configs = config.load_general_config()
+
+        proxy_config = self._general_configs.get('proxies', {})
+        try:
+            proxies = proxy_config[base_url]
+        except KeyError:
+            proxies = proxy_config.get('default', {})
+
+        self._proxy_configs = ProxyConfig.from_dict(proxies)
+
+        self._auth_configs = auth.load_config(
+            config_dict=self._general_configs, credstore_env=credstore_env,
+        )
+        self.credstore_env = credstore_env
+
+        base_url = utils.parse_host(
+            base_url, IS_WINDOWS_PLATFORM, tls=bool(tls)
+        )
+        # SSH has a different default for num_pools to all other adapters
+        num_pools = num_pools or DEFAULT_NUM_POOLS_SSH if \
+            base_url.startswith('ssh://') else DEFAULT_NUM_POOLS
+
+        if base_url.startswith('http+unix://'):
+            self._custom_adapter = UnixHTTPAdapter(
+                base_url, timeout, pool_connections=num_pools,
+                max_pool_size=max_pool_size
+            )
+            self.mount('http+docker://', self._custom_adapter)
+            self._unmount('http://', 'https://')
+            # host part of URL should be unused, but is resolved by requests
+            # module in proxy_bypass_macosx_sysconf()
+            self.base_url = 'http+docker://localhost'
+        elif base_url.startswith('npipe://'):
+            if not IS_WINDOWS_PLATFORM:
+                raise DockerException(
+                    'The npipe:// protocol is only supported on Windows'
+                )
+            if PYWIN32_IMPORT_ERROR is not None:
+                raise MissingRequirementException(
+                    'Install pypiwin32 package to enable npipe:// support',
+                    'pywin32',
+                    PYWIN32_IMPORT_ERROR)
+            self._custom_adapter = NpipeHTTPAdapter(
+                base_url, timeout, pool_connections=num_pools,
+                max_pool_size=max_pool_size
+            )
+            self.mount('http+docker://', self._custom_adapter)
+            self.base_url = 'http+docker://localnpipe'
+        elif base_url.startswith('ssh://'):
+            if PARAMIKO_IMPORT_ERROR is not None and not use_ssh_client:
+                raise MissingRequirementException(
+                    'Install paramiko package to enable ssh:// support',
+                    'paramiko',
+                    PARAMIKO_IMPORT_ERROR)
+            self._custom_adapter = SSHHTTPAdapter(
+                base_url, timeout, pool_connections=num_pools,
+                max_pool_size=max_pool_size, shell_out=use_ssh_client
+            )
+            self.mount('http+docker://ssh', self._custom_adapter)
+            self._unmount('http://', 'https://')
+            self.base_url = 'http+docker://ssh'
+        else:
+            # Use SSLAdapter for the ability to specify SSL version
+            if isinstance(tls, TLSConfig):
+                tls.configure_client(self)
+            elif tls:
+                self._custom_adapter = SSLHTTPAdapter(
+                    pool_connections=num_pools)
+                self.mount('https://', self._custom_adapter)
+            self.base_url = base_url
+
+        # version detection needs to be after unix adapter mounting
+        if version is None or (isinstance(version, string_types) and version.lower() == 'auto'):
+            self._version = self._retrieve_server_version()
+        else:
+            self._version = version
+        if not isinstance(self._version, string_types):
+            raise DockerException(
+                'Version parameter must be a string or None. Found {0}'.format(
+                    type(version).__name__
+                )
+            )
+        if utils.version_lt(self._version, MINIMUM_DOCKER_API_VERSION):
+            raise InvalidVersion(
+                'API versions below {0} are no longer supported by this '
+                'library.'.format(MINIMUM_DOCKER_API_VERSION)
+            )
+
+    def _retrieve_server_version(self):
+        try:
+            return self.version(api_version=False)["ApiVersion"]
+        except KeyError:
+            raise DockerException(
+                'Invalid response from docker daemon: key "ApiVersion"'
+                ' is missing.'
+            )
+        except Exception as e:
+            raise DockerException(
+                'Error while fetching server API version: {0}'.format(e)
+            )
+
+    def _set_request_timeout(self, kwargs):
+        """Prepare the kwargs for an HTTP request by inserting the timeout
+        parameter, if not already present."""
+        kwargs.setdefault('timeout', self.timeout)
+        return kwargs
+
+    @update_headers
+    def _post(self, url, **kwargs):
+        return self.post(url, **self._set_request_timeout(kwargs))
+
+    @update_headers
+    def _get(self, url, **kwargs):
+        return self.get(url, **self._set_request_timeout(kwargs))
+
+    @update_headers
+    def _put(self, url, **kwargs):
+        return self.put(url, **self._set_request_timeout(kwargs))
+
+    @update_headers
+    def _delete(self, url, **kwargs):
+        return self.delete(url, **self._set_request_timeout(kwargs))
+
+    def _url(self, pathfmt, *args, **kwargs):
+        for arg in args:
+            if not isinstance(arg, string_types):
+                raise ValueError(
+                    'Expected a string but found {0} ({1}) '
+                    'instead'.format(arg, type(arg))
+                )
+
+        quote_f = partial(quote, safe="/:")
+        args = map(quote_f, args)
+
+        if kwargs.get('versioned_api', True):
+            return '{0}/v{1}{2}'.format(
+                self.base_url, self._version, pathfmt.format(*args)
+            )
+        else:
+            return '{0}{1}'.format(self.base_url, pathfmt.format(*args))
+
+    def _raise_for_status(self, response):
+        """Raises stored :class:`APIError`, if one occurred."""
+        try:
+            response.raise_for_status()
+        except _HTTPError as e:
+            raise create_api_error_from_http_exception(e)
+
+    def _result(self, response, json=False, binary=False):
+        if json and binary:
+            raise AssertionError('json and binary must not be both True')
+        self._raise_for_status(response)
+
+        if json:
+            return response.json()
+        if binary:
+            return response.content
+        return response.text
+
+    def _post_json(self, url, data, **kwargs):
+        # Go <1.1 can't unserialize null to a string
+        # so we do this disgusting thing here.
+        data2 = {}
+        if data is not None and isinstance(data, dict):
+            for k, v in iteritems(data):
+                if v is not None:
+                    data2[k] = v
+        elif data is not None:
+            data2 = data
+
+        if 'headers' not in kwargs:
+            kwargs['headers'] = {}
+        kwargs['headers']['Content-Type'] = 'application/json'
+        return self._post(url, data=json.dumps(data2), **kwargs)
+
+    def _attach_params(self, override=None):
+        return override or {
+            'stdout': 1,
+            'stderr': 1,
+            'stream': 1
+        }
+
+    def _get_raw_response_socket(self, response):
+        self._raise_for_status(response)
+        if self.base_url == "http+docker://localnpipe":
+            sock = response.raw._fp.fp.raw.sock
+        elif self.base_url.startswith('http+docker://ssh'):
+            sock = response.raw._fp.fp.channel
+        elif PY3:
+            sock = response.raw._fp.fp.raw
+            if self.base_url.startswith("https://"):
+                sock = sock._sock
+        else:
+            sock = response.raw._fp.fp._sock
+        try:
+            # Keep a reference to the response to stop it being garbage
+            # collected. If the response is garbage collected, it will
+            # close TLS sockets.
+            sock._response = response
+        except AttributeError:
+            # UNIX sockets can't have attributes set on them, but that's
+            # fine because we won't be doing TLS over them
+            pass
+
+        return sock
+
+    def _stream_helper(self, response, decode=False):
+        """Generator for data coming from a chunked-encoded HTTP response."""
+
+        if response.raw._fp.chunked:
+            if decode:
+                for chunk in json_stream.json_stream(self._stream_helper(response, False)):
+                    yield chunk
+            else:
+                reader = response.raw
+                while not reader.closed:
+                    # this read call will block until we get a chunk
+                    data = reader.read(1)
+                    if not data:
+                        break
+                    if reader._fp.chunk_left:
+                        data += reader.read(reader._fp.chunk_left)
+                    yield data
+        else:
+            # Response isn't chunked, meaning we probably
+            # encountered an error immediately
+            yield self._result(response, json=decode)
+
+    def _multiplexed_buffer_helper(self, response):
+        """A generator of multiplexed data blocks read from a buffered
+        response."""
+        buf = self._result(response, binary=True)
+        buf_length = len(buf)
+        walker = 0
+        while True:
+            if buf_length - walker < STREAM_HEADER_SIZE_BYTES:
+                break
+            header = buf[walker:walker + STREAM_HEADER_SIZE_BYTES]
+            dummy, length = struct.unpack_from('>BxxxL', header)
+            start = walker + STREAM_HEADER_SIZE_BYTES
+            end = start + length
+            walker = end
+            yield buf[start:end]
+
+    def _multiplexed_response_stream_helper(self, response):
+        """A generator of multiplexed data blocks coming from a response
+        stream."""
+
+        # Disable timeout on the underlying socket to prevent
+        # Read timed out(s) for long running processes
+        socket = self._get_raw_response_socket(response)
+        self._disable_socket_timeout(socket)
+
+        while True:
+            header = response.raw.read(STREAM_HEADER_SIZE_BYTES)
+            if not header:
+                break
+            dummy, length = struct.unpack('>BxxxL', header)
+            if not length:
+                continue
+            data = response.raw.read(length)
+            if not data:
+                break
+            yield data
+
+    def _stream_raw_result(self, response, chunk_size=1, decode=True):
+        ''' Stream result for TTY-enabled container and raw binary data'''
+        self._raise_for_status(response)
+
+        # Disable timeout on the underlying socket to prevent
+        # Read timed out(s) for long running processes
+        socket = self._get_raw_response_socket(response)
+        self._disable_socket_timeout(socket)
+
+        for out in response.iter_content(chunk_size, decode):
+            yield out
+
+    def _read_from_socket(self, response, stream, tty=True, demux=False):
+        socket = self._get_raw_response_socket(response)
+
+        gen = frames_iter(socket, tty)
+
+        if demux:
+            # The generator will output tuples (stdout, stderr)
+            gen = (demux_adaptor(*frame) for frame in gen)
+        else:
+            # The generator will output strings
+            gen = (data for (dummy, data) in gen)
+
+        if stream:
+            return gen
+        else:
+            # Wait for all the frames, concatenate them, and return the result
+            return consume_socket_output(gen, demux=demux)
+
+    def _disable_socket_timeout(self, socket):
+        """ Depending on the combination of python version and whether we're
+        connecting over http or https, we might need to access _sock, which
+        may or may not exist; or we may need to just settimeout on socket
+        itself, which also may or may not have settimeout on it. To avoid
+        missing the correct one, we try both.
+
+        We also do not want to set the timeout if it is already disabled, as
+        you run the risk of changing a socket that was non-blocking to
+        blocking, for example when using gevent.
+        """
+        sockets = [socket, getattr(socket, '_sock', None)]
+
+        for s in sockets:
+            if not hasattr(s, 'settimeout'):
+                continue
+
+            timeout = -1
+
+            if hasattr(s, 'gettimeout'):
+                timeout = s.gettimeout()
+
+            # Don't change the timeout if it is already disabled.
+            if timeout is None or timeout == 0.0:
+                continue
+
+            s.settimeout(None)
+
+    @check_resource('container')
+    def _check_is_tty(self, container):
+        cont = self.inspect_container(container)
+        return cont['Config']['Tty']
+
+    def _get_result(self, container, stream, res):
+        return self._get_result_tty(stream, res, self._check_is_tty(container))
+
+    def _get_result_tty(self, stream, res, is_tty):
+        # We should also use raw streaming (without keep-alives)
+        # if we're dealing with a tty-enabled container.
+        if is_tty:
+            return self._stream_raw_result(res) if stream else \
+                self._result(res, binary=True)
+
+        self._raise_for_status(res)
+        sep = binary_type()
+        if stream:
+            return self._multiplexed_response_stream_helper(res)
+        else:
+            return sep.join(
+                list(self._multiplexed_buffer_helper(res))
+            )
+
+    def _unmount(self, *args):
+        for proto in args:
+            self.adapters.pop(proto)
+
+    def get_adapter(self, url):
+        try:
+            return super(APIClient, self).get_adapter(url)
+        except _InvalidSchema as e:
+            if self._custom_adapter:
+                return self._custom_adapter
+            else:
+                raise e
+
+    @property
+    def api_version(self):
+        return self._version
+
+    def reload_config(self, dockercfg_path=None):
+        """
+        Force a reload of the auth configuration
+
+        Args:
+            dockercfg_path (str): Use a custom path for the Docker config file
+                (default ``$HOME/.docker/config.json`` if present,
+                otherwise ``$HOME/.dockercfg``)
+
+        Returns:
+            None
+        """
+        self._auth_configs = auth.load_config(
+            dockercfg_path, credstore_env=self.credstore_env
+        )
+
+    def _set_auth_headers(self, headers):
+        log.debug('Looking for auth config')
+
+        # If we don't have any auth data so far, try reloading the config
+        # file one more time in case anything showed up in there.
+        if not self._auth_configs or self._auth_configs.is_empty:
+            log.debug("No auth config in memory - loading from filesystem")
+            self._auth_configs = auth.load_config(
+                credstore_env=self.credstore_env
+            )
+
+        # Send the full auth configuration (if any exists), since the build
+        # could use any (or all) of the registries.
+        if self._auth_configs:
+            auth_data = self._auth_configs.get_all_credentials()
+
+            # See https://github.com/docker/docker-py/issues/1683
+            if (auth.INDEX_URL not in auth_data and
+                    auth.INDEX_NAME in auth_data):
+                auth_data[auth.INDEX_URL] = auth_data.get(auth.INDEX_NAME, {})
+
+            log.debug(
+                'Sending auth config (%s)',
+                ', '.join(repr(k) for k in auth_data.keys())
+            )
+
+            if auth_data:
+                headers['X-Registry-Config'] = auth.encode_header(
+                    auth_data
+                )
+        else:
+            log.debug('No auth config found')
+
+    def get_binary(self, pathfmt, *args, **kwargs):
+        return self._result(self._get(self._url(pathfmt, *args, versioned_api=True), **kwargs), binary=True)
+
+    def get_json(self, pathfmt, *args, **kwargs):
+        return self._result(self._get(self._url(pathfmt, *args, versioned_api=True), **kwargs), json=True)
+
+    def get_text(self, pathfmt, *args, **kwargs):
+        return self._result(self._get(self._url(pathfmt, *args, versioned_api=True), **kwargs))
+
+    def get_raw_stream(self, pathfmt, *args, **kwargs):
+        chunk_size = kwargs.pop('chunk_size', DEFAULT_DATA_CHUNK_SIZE)
+        res = self._get(self._url(pathfmt, *args, versioned_api=True), stream=True, **kwargs)
+        self._raise_for_status(res)
+        return self._stream_raw_result(res, chunk_size, False)
+
+    def delete_call(self, pathfmt, *args, **kwargs):
+        self._raise_for_status(self._delete(self._url(pathfmt, *args, versioned_api=True), **kwargs))
+
+    def delete_json(self, pathfmt, *args, **kwargs):
+        return self._result(self._delete(self._url(pathfmt, *args, versioned_api=True), **kwargs), json=True)
+
+    def post_json(self, pathfmt, *args, **kwargs):
+        data = kwargs.pop('data', None)
+        self._raise_for_status(self._post_json(self._url(pathfmt, *args, versioned_api=True), data, **kwargs))
+
+    def post_json_to_binary(self, pathfmt, *args, **kwargs):
+        data = kwargs.pop('data', None)
+        return self._result(self._post_json(self._url(pathfmt, *args, versioned_api=True), data, **kwargs), binary=True)
+
+    def post_json_to_json(self, pathfmt, *args, **kwargs):
+        data = kwargs.pop('data', None)
+        return self._result(self._post_json(self._url(pathfmt, *args, versioned_api=True), data, **kwargs), json=True)
+
+    def post_json_to_text(self, pathfmt, *args, **kwargs):
+        data = kwargs.pop('data', None)
+
+    def post_json_to_stream_socket(self, pathfmt, *args, **kwargs):
+        data = kwargs.pop('data', None)
+        headers = (kwargs.pop('headers', None) or {}).copy()
+        headers.update({
+            'Connection': 'Upgrade',
+            'Upgrade': 'tcp',
+        })
+        return self._get_raw_response_socket(
+            self._post_json(self._url(pathfmt, *args, versioned_api=True), data, headers=headers, stream=True, **kwargs))
+
+    def post_json_to_stream(self, pathfmt, *args, **kwargs):
+        data = kwargs.pop('data', None)
+        headers = (kwargs.pop('headers', None) or {}).copy()
+        headers.update({
+            'Connection': 'Upgrade',
+            'Upgrade': 'tcp',
+        })
+        stream = kwargs.pop('stream', False)
+        demux = kwargs.pop('demux', False)
+        tty = kwargs.pop('tty', False)
+        return self._read_from_socket(
+            self._post_json(self._url(pathfmt, *args, versioned_api=True), data, headers=headers, stream=True, **kwargs),
+            stream,
+            tty=tty,
+            demux=demux
+        )
+
+    def post_to_json(self, pathfmt, *args, **kwargs):
+        return self._result(self._post(self._url(pathfmt, *args, versioned_api=True), **kwargs), json=True)

plugins/module_utils/_api/api/daemon.py

@@ -0,0 +1,195 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import os
+from datetime import datetime
+
+from .. import auth
+from ..utils.utils import datetime_to_timestamp, convert_filters
+from ..utils.decorators import minimum_version
+from ..types.daemon import CancellableStream
+
+
+class DaemonApiMixin(object):
+    @minimum_version('1.25')
+    def df(self):
+        """
+        Get data usage information.
+
+        Returns:
+            (dict): A dictionary representing different resource categories
+            and their respective data usage.
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
+        url = self._url('/system/df')
+        return self._result(self._get(url), True)
+
+    def events(self, since=None, until=None, filters=None, decode=None):
+        """
+        Get real-time events from the server. Similar to the ``docker events``
+        command.
+
+        Args:
+            since (UTC datetime or int): Get events from this point
+            until (UTC datetime or int): Get events until this point
+            filters (dict): Filter the events by event time, container or image
+            decode (bool): If set to true, stream will be decoded into dicts on
+                the fly. False by default.
+
+        Returns:
+            A :py:class:`docker.types.daemon.CancellableStream` generator
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+
+        Example:
+
+            >>> for event in client.events(decode=True)
+            ...   print(event)
+            {u'from': u'image/with:tag',
+             u'id': u'container-id',
+             u'status': u'start',
+             u'time': 1423339459}
+            ...
+
+            or
+
+            >>> events = client.events()
+            >>> for event in events:
+            ...   print(event)
+            >>> # and cancel from another thread
+            >>> events.close()
+        """
+
+        if isinstance(since, datetime):
+            since = datetime_to_timestamp(since)
+
+        if isinstance(until, datetime):
+            until = datetime_to_timestamp(until)
+
+        if filters:
+            filters = convert_filters(filters)
+
+        params = {
+            'since': since,
+            'until': until,
+            'filters': filters
+        }
+        url = self._url('/events')
+
+        response = self._get(url, params=params, stream=True, timeout=None)
+        stream = self._stream_helper(response, decode=decode)
+
+        return CancellableStream(stream, response)
+
+    def info(self):
+        """
+        Display system-wide information. Identical to the ``docker info``
+        command.
+
+        Returns:
+            (dict): The info as a dict
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
+        return self._result(self._get(self._url("/info")), True)
+
+    def login(self, username, password=None, email=None, registry=None,
+              reauth=False, dockercfg_path=None):
+        """
+        Authenticate with a registry. Similar to the ``docker login`` command.
+
+        Args:
+            username (str): The registry username
+            password (str): The plaintext password
+            email (str): The email for the registry account
+            registry (str): URL to the registry.  E.g.
+                ``https://index.docker.io/v1/``
+            reauth (bool): Whether or not to refresh existing authentication on
+                the Docker server.
+            dockercfg_path (str): Use a custom path for the Docker config file
+                (default ``$HOME/.docker/config.json`` if present,
+                otherwise ``$HOME/.dockercfg``)
+
+        Returns:
+            (dict): The response from the login request
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
+
+        # If we don't have any auth data so far, try reloading the config file
+        # one more time in case anything showed up in there.
+        # If dockercfg_path is passed check to see if the config file exists,
+        # if so load that config.
+        if dockercfg_path and os.path.exists(dockercfg_path):
+            self._auth_configs = auth.load_config(
+                dockercfg_path, credstore_env=self.credstore_env
+            )
+        elif not self._auth_configs or self._auth_configs.is_empty:
+            self._auth_configs = auth.load_config(
+                credstore_env=self.credstore_env
+            )
+
+        authcfg = self._auth_configs.resolve_authconfig(registry)
+        # If we found an existing auth config for this registry and username
+        # combination, we can return it immediately unless reauth is requested.
+        if authcfg and authcfg.get('username', None) == username \
+                and not reauth:
+            return authcfg
+
+        req_data = {
+            'username': username,
+            'password': password,
+            'email': email,
+            'serveraddress': registry,
+        }
+
+        response = self._post_json(self._url('/auth'), data=req_data)
+        if response.status_code == 200:
+            self._auth_configs.add_auth(registry or auth.INDEX_NAME, req_data)
+        return self._result(response, json=True)
+
+    def ping(self):
+        """
+        Checks the server is responsive. An exception will be raised if it
+        isn't responding.
+
+        Returns:
+            (bool) The response from the server.
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
+        return self._result(self._get(self._url('/_ping'))) == 'OK'
+
+    def version(self, api_version=True):
+        """
+        Returns version information from the server. Similar to the ``docker
+        version`` command.
+
+        Returns:
+            (dict): The server version information
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
+        url = self._url("/version", versioned_api=api_version)
+        return self._result(self._get(url), json=True)

plugins/module_utils/_api/auth.py

@@ -0,0 +1,387 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import base64
+import json
+import logging
+
+from ansible.module_utils.six import iteritems, string_types
+
+from . import errors
+from .credentials.store import Store
+from .credentials.errors import StoreError, CredentialsNotFound
+from .utils import config
+
+INDEX_NAME = 'docker.io'
+INDEX_URL = 'https://index.{0}/v1/'.format(INDEX_NAME)
+TOKEN_USERNAME = '<token>'
+
+log = logging.getLogger(__name__)
+
+
+def resolve_repository_name(repo_name):
+    if '://' in repo_name:
+        raise errors.InvalidRepository(
+            'Repository name cannot contain a scheme ({0})'.format(repo_name)
+        )
+
+    index_name, remote_name = split_repo_name(repo_name)
+    if index_name[0] == '-' or index_name[-1] == '-':
+        raise errors.InvalidRepository(
+            'Invalid index name ({0}). Cannot begin or end with a'
+            ' hyphen.'.format(index_name)
+        )
+    return resolve_index_name(index_name), remote_name
+
+
+def resolve_index_name(index_name):
+    index_name = convert_to_hostname(index_name)
+    if index_name == 'index.' + INDEX_NAME:
+        index_name = INDEX_NAME
+    return index_name
+
+
+def get_config_header(client, registry):
+    log.debug('Looking for auth config')
+    if not client._auth_configs or client._auth_configs.is_empty:
+        log.debug(
+            "No auth config in memory - loading from filesystem"
+        )
+        client._auth_configs = load_config(credstore_env=client.credstore_env)
+    authcfg = resolve_authconfig(
+        client._auth_configs, registry, credstore_env=client.credstore_env
+    )
+    # Do not fail here if no authentication exists for this
+    # specific registry as we can have a readonly pull. Just
+    # put the header if we can.
+    if authcfg:
+        log.debug('Found auth config')
+        # auth_config needs to be a dict in the format used by
+        # auth.py username , password, serveraddress, email
+        return encode_header(authcfg)
+    log.debug('No auth config found')
+    return None
+
+
+def split_repo_name(repo_name):
+    parts = repo_name.split('/', 1)
+    if len(parts) == 1 or (
+        '.' not in parts[0] and ':' not in parts[0] and parts[0] != 'localhost'
+    ):
+        # This is a docker index repo (ex: username/foobar or ubuntu)
+        return INDEX_NAME, repo_name
+    return tuple(parts)
+
+
+def get_credential_store(authconfig, registry):
+    if not isinstance(authconfig, AuthConfig):
+        authconfig = AuthConfig(authconfig)
+    return authconfig.get_credential_store(registry)
+
+
+class AuthConfig(dict):
+    def __init__(self, dct, credstore_env=None):
+        if 'auths' not in dct:
+            dct['auths'] = {}
+        self.update(dct)
+        self._credstore_env = credstore_env
+        self._stores = {}
+
+    @classmethod
+    def parse_auth(cls, entries, raise_on_error=False):
+        """
+        Parses authentication entries
+
+        Args:
+          entries:        Dict of authentication entries.
+          raise_on_error: If set to true, an invalid format will raise
+                          InvalidConfigFile
+
+        Returns:
+          Authentication registry.
+        """
+
+        conf = {}
+        for registry, entry in iteritems(entries):
+            if not isinstance(entry, dict):
+                log.debug('Config entry for key %s is not auth config', registry)
+                # We sometimes fall back to parsing the whole config as if it
+                # was the auth config by itself, for legacy purposes. In that
+                # case, we fail silently and return an empty conf if any of the
+                # keys is not formatted properly.
+                if raise_on_error:
+                    raise errors.InvalidConfigFile(
+                        'Invalid configuration for registry {0}'.format(
+                            registry
+                        )
+                    )
+                return {}
+            if 'identitytoken' in entry:
+                log.debug('Found an IdentityToken entry for registry %s', registry)
+                conf[registry] = {
+                    'IdentityToken': entry['identitytoken']
+                }
+                continue  # Other values are irrelevant if we have a token
+
+            if 'auth' not in entry:
+                # Starting with engine v1.11 (API 1.23), an empty dictionary is
+                # a valid value in the auths config.
+                # https://github.com/docker/compose/issues/3265
+                log.debug('Auth data for %s is absent. Client might be using a credentials store instead.', registry)
+                conf[registry] = {}
+                continue
+
+            username, password = decode_auth(entry['auth'])
+            log.debug('Found entry (registry=%s, username=%s)', repr(registry), repr(username))
+
+            conf[registry] = {
+                'username': username,
+                'password': password,
+                'email': entry.get('email'),
+                'serveraddress': registry,
+            }
+        return conf
+
+    @classmethod
+    def load_config(cls, config_path, config_dict, credstore_env=None):
+        """
+        Loads authentication data from a Docker configuration file in the given
+        root directory or if config_path is passed use given path.
+        Lookup priority:
+            explicit config_path parameter > DOCKER_CONFIG environment
+            variable > ~/.docker/config.json > ~/.dockercfg
+        """
+
+        if not config_dict:
+            config_file = config.find_config_file(config_path)
+
+            if not config_file:
+                return cls({}, credstore_env)
+            try:
+                with open(config_file) as f:
+                    config_dict = json.load(f)
+            except (IOError, KeyError, ValueError) as e:
+                # Likely missing new Docker config file or it's in an
+                # unknown format, continue to attempt to read old location
+                # and format.
+                log.debug(e)
+                return cls(_load_legacy_config(config_file), credstore_env)
+
+        res = {}
+        if config_dict.get('auths'):
+            log.debug("Found 'auths' section")
+            res.update({
+                'auths': cls.parse_auth(
+                    config_dict.pop('auths'), raise_on_error=True
+                )
+            })
+        if config_dict.get('credsStore'):
+            log.debug("Found 'credsStore' section")
+            res.update({'credsStore': config_dict.pop('credsStore')})
+        if config_dict.get('credHelpers'):
+            log.debug("Found 'credHelpers' section")
+            res.update({'credHelpers': config_dict.pop('credHelpers')})
+        if res:
+            return cls(res, credstore_env)
+
+        log.debug(
+            "Couldn't find auth-related section ; attempting to interpret "
+            "as auth-only file"
+        )
+        return cls({'auths': cls.parse_auth(config_dict)}, credstore_env)
+
+    @property
+    def auths(self):
+        return self.get('auths', {})
+
+    @property
+    def creds_store(self):
+        return self.get('credsStore', None)
+
+    @property
+    def cred_helpers(self):
+        return self.get('credHelpers', {})
+
+    @property
+    def is_empty(self):
+        return (
+            not self.auths and not self.creds_store and not self.cred_helpers
+        )
+
+    def resolve_authconfig(self, registry=None):
+        """
+        Returns the authentication data from the given auth configuration for a
+        specific registry. As with the Docker client, legacy entries in the
+        config with full URLs are stripped down to hostnames before checking
+        for a match. Returns None if no match was found.
+        """
+
+        if self.creds_store or self.cred_helpers:
+            store_name = self.get_credential_store(registry)
+            if store_name is not None:
+                log.debug('Using credentials store "%s"', store_name)
+                cfg = self._resolve_authconfig_credstore(registry, store_name)
+                if cfg is not None:
+                    return cfg
+                log.debug('No entry in credstore - fetching from auth dict')
+
+        # Default to the public index server
+        registry = resolve_index_name(registry) if registry else INDEX_NAME
+        log.debug("Looking for auth entry for %s", repr(registry))
+
+        if registry in self.auths:
+            log.debug("Found %s", repr(registry))
+            return self.auths[registry]
+
+        for key, conf in iteritems(self.auths):
+            if resolve_index_name(key) == registry:
+                log.debug("Found %s", repr(key))
+                return conf
+
+        log.debug("No entry found")
+        return None
+
+    def _resolve_authconfig_credstore(self, registry, credstore_name):
+        if not registry or registry == INDEX_NAME:
+            # The ecosystem is a little schizophrenic with index.docker.io VS
+            # docker.io - in that case, it seems the full URL is necessary.
+            registry = INDEX_URL
+        log.debug("Looking for auth entry for %s", repr(registry))
+        store = self._get_store_instance(credstore_name)
+        try:
+            data = store.get(registry)
+            res = {
+                'ServerAddress': registry,
+            }
+            if data['Username'] == TOKEN_USERNAME:
+                res['IdentityToken'] = data['Secret']
+            else:
+                res.update({
+                    'Username': data['Username'],
+                    'Password': data['Secret'],
+                })
+            return res
+        except CredentialsNotFound:
+            log.debug('No entry found')
+            return None
+        except StoreError as e:
+            raise errors.DockerException(
+                'Credentials store error: {0}'.format(repr(e))
+            )
+
+    def _get_store_instance(self, name):
+        if name not in self._stores:
+            self._stores[name] = Store(
+                name, environment=self._credstore_env
+            )
+        return self._stores[name]
+
+    def get_credential_store(self, registry):
+        if not registry or registry == INDEX_NAME:
+            registry = INDEX_URL
+
+        return self.cred_helpers.get(registry) or self.creds_store
+
+    def get_all_credentials(self):
+        auth_data = self.auths.copy()
+        if self.creds_store:
+            # Retrieve all credentials from the default store
+            store = self._get_store_instance(self.creds_store)
+            for k in store.list().keys():
+                auth_data[k] = self._resolve_authconfig_credstore(
+                    k, self.creds_store
+                )
+                auth_data[convert_to_hostname(k)] = auth_data[k]
+
+        # credHelpers entries take priority over all others
+        for reg, store_name in self.cred_helpers.items():
+            auth_data[reg] = self._resolve_authconfig_credstore(
+                reg, store_name
+            )
+            auth_data[convert_to_hostname(reg)] = auth_data[reg]
+
+        return auth_data
+
+    def add_auth(self, reg, data):
+        self['auths'][reg] = data
+
+
+def resolve_authconfig(authconfig, registry=None, credstore_env=None):
+    if not isinstance(authconfig, AuthConfig):
+        authconfig = AuthConfig(authconfig, credstore_env)
+    return authconfig.resolve_authconfig(registry)
+
+
+def convert_to_hostname(url):
+    return url.replace('http://', '').replace('https://', '').split('/', 1)[0]
+
+
+def decode_auth(auth):
+    if isinstance(auth, string_types):
+        auth = auth.encode('ascii')
+    s = base64.b64decode(auth)
+    login, pwd = s.split(b':', 1)
+    return login.decode('utf8'), pwd.decode('utf8')
+
+
+def encode_header(auth):
+    auth_json = json.dumps(auth).encode('ascii')
+    return base64.urlsafe_b64encode(auth_json)
+
+
+def parse_auth(entries, raise_on_error=False):
+    """
+    Parses authentication entries
+
+    Args:
+      entries:        Dict of authentication entries.
+      raise_on_error: If set to true, an invalid format will raise
+                      InvalidConfigFile
+
+    Returns:
+      Authentication registry.
+    """
+
+    return AuthConfig.parse_auth(entries, raise_on_error)
+
+
+def load_config(config_path=None, config_dict=None, credstore_env=None):
+    return AuthConfig.load_config(config_path, config_dict, credstore_env)
+
+
+def _load_legacy_config(config_file):
+    log.debug("Attempting to parse legacy auth file format")
+    try:
+        data = []
+        with open(config_file) as f:
+            for line in f.readlines():
+                data.append(line.strip().split(' = ')[1])
+            if len(data) < 2:
+                # Not enough data
+                raise errors.InvalidConfigFile(
+                    'Invalid or empty configuration file!'
+                )
+
+        username, password = decode_auth(data[0])
+        return {'auths': {
+            INDEX_NAME: {
+                'username': username,
+                'password': password,
+                'email': data[1],
+                'serveraddress': INDEX_URL,
+            }
+        }}
+    except Exception as e:
+        log.debug(e)
+        pass
+
+    log.debug("All parsing attempts failed - returning empty config")
+    return {}

plugins/module_utils/_api/constants.py

@@ -0,0 +1,49 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import sys
+
+DEFAULT_DOCKER_API_VERSION = '1.41'
+MINIMUM_DOCKER_API_VERSION = '1.21'
+DEFAULT_TIMEOUT_SECONDS = 60
+STREAM_HEADER_SIZE_BYTES = 8
+CONTAINER_LIMITS_KEYS = [
+    'memory', 'memswap', 'cpushares', 'cpusetcpus'
+]
+
+DEFAULT_HTTP_HOST = "127.0.0.1"
+DEFAULT_UNIX_SOCKET = "http+unix:///var/run/docker.sock"
+DEFAULT_NPIPE = 'npipe:////./pipe/docker_engine'
+
+BYTE_UNITS = {
+    'b': 1,
+    'k': 1024,
+    'm': 1024 * 1024,
+    'g': 1024 * 1024 * 1024
+}
+
+IS_WINDOWS_PLATFORM = (sys.platform == 'win32')
+WINDOWS_LONGPATH_PREFIX = '\\\\?\\'
+
+DEFAULT_USER_AGENT = "ansible-community.docker"
+DEFAULT_NUM_POOLS = 25
+
+# The OpenSSH server default value for MaxSessions is 10 which means we can
+# use up to 9, leaving the final session for the underlying SSH connection.
+# For more details see: https://github.com/docker/docker-py/issues/2246
+DEFAULT_NUM_POOLS_SSH = 9
+
+DEFAULT_MAX_POOL_SIZE = 10
+
+DEFAULT_DATA_CHUNK_SIZE = 1024 * 2048
+
+DEFAULT_SWARM_ADDR_POOL = ['10.0.0.0/8']
+DEFAULT_SWARM_SUBNET_SIZE = 24

plugins/module_utils/_api/credentials/constants.py

@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+PROGRAM_PREFIX = 'docker-credential-'
+DEFAULT_LINUX_STORE = 'secretservice'
+DEFAULT_OSX_STORE = 'osxkeychain'
+DEFAULT_WIN32_STORE = 'wincred'

plugins/module_utils/_api/credentials/errors.py

@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+class StoreError(RuntimeError):
+    pass
+
+
+class CredentialsNotFound(StoreError):
+    pass
+
+
+class InitializationError(StoreError):
+    pass
+
+
+def process_store_error(cpe, program):
+    message = cpe.output.decode('utf-8')
+    if 'credentials not found in native keychain' in message:
+        return CredentialsNotFound(
+            'No matching credentials in {0}'.format(
+                program
+            )
+        )
+    return StoreError(
+        'Credentials store {0} exited with "{1}".'.format(
+            program, cpe.output.decode('utf-8').strip()
+        )
+    )

plugins/module_utils/_api/credentials/store.py

@@ -0,0 +1,118 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import errno
+import json
+import subprocess
+
+from ansible.module_utils.six import PY3, binary_type
+
+from . import constants
+from . import errors
+from .utils import create_environment_dict
+from .utils import find_executable
+
+
+class Store(object):
+    def __init__(self, program, environment=None):
+        """ Create a store object that acts as an interface to
+            perform the basic operations for storing, retrieving
+            and erasing credentials using `program`.
+        """
+        self.program = constants.PROGRAM_PREFIX + program
+        self.exe = find_executable(self.program)
+        self.environment = environment
+        if self.exe is None:
+            raise errors.InitializationError(
+                '{0} not installed or not available in PATH'.format(
+                    self.program
+                )
+            )
+
+    def get(self, server):
+        """ Retrieve credentials for `server`. If no credentials are found,
+            a `StoreError` will be raised.
+        """
+        if not isinstance(server, binary_type):
+            server = server.encode('utf-8')
+        data = self._execute('get', server)
+        result = json.loads(data.decode('utf-8'))
+
+        # docker-credential-pass will return an object for inexistent servers
+        # whereas other helpers will exit with returncode != 0. For
+        # consistency, if no significant data is returned,
+        # raise CredentialsNotFound
+        if result['Username'] == '' and result['Secret'] == '':
+            raise errors.CredentialsNotFound(
+                'No matching credentials in {0}'.format(self.program)
+            )
+
+        return result
+
+    def store(self, server, username, secret):
+        """ Store credentials for `server`. Raises a `StoreError` if an error
+            occurs.
+        """
+        data_input = json.dumps({
+            'ServerURL': server,
+            'Username': username,
+            'Secret': secret
+        }).encode('utf-8')
+        return self._execute('store', data_input)
+
+    def erase(self, server):
+        """ Erase credentials for `server`. Raises a `StoreError` if an error
+            occurs.
+        """
+        if not isinstance(server, binary_type):
+            server = server.encode('utf-8')
+        self._execute('erase', server)
+
+    def list(self):
+        """ List stored credentials. Requires v0.4.0+ of the helper.
+        """
+        data = self._execute('list', None)
+        return json.loads(data.decode('utf-8'))
+
+    def _execute(self, subcmd, data_input):
+        output = None
+        env = create_environment_dict(self.environment)
+        try:
+            if PY3:
+                output = subprocess.check_output(
+                    [self.exe, subcmd], input=data_input, env=env,
+                )
+            else:
+                process = subprocess.Popen(
+                    [self.exe, subcmd], stdin=subprocess.PIPE,
+                    stdout=subprocess.PIPE, env=env,
+                )
+                output, dummy = process.communicate(data_input)
+                if process.returncode != 0:
+                    raise subprocess.CalledProcessError(
+                        returncode=process.returncode, cmd='', output=output
+                    )
+        except subprocess.CalledProcessError as e:
+            raise errors.process_store_error(e, self.program)
+        except OSError as e:
+            if e.errno == errno.ENOENT:
+                raise errors.StoreError(
+                    '{0} not installed or not available in PATH'.format(
+                        self.program
+                    )
+                )
+            else:
+                raise errors.StoreError(
+                    'Unexpected OS error "{0}", errno={1}'.format(
+                        e.strerror, e.errno
+                    )
+                )
+        return output

plugins/module_utils/_api/credentials/utils.py

@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import os
+import sys
+
+from ansible.module_utils.six import PY2
+
+if PY2:
+    from distutils.spawn import find_executable as which
+else:
+    from shutil import which
+
+
+def find_executable(executable, path=None):
+    """
+    As distutils.spawn.find_executable, but on Windows, look up
+    every extension declared in PATHEXT instead of just `.exe`
+    """
+    if sys.platform != 'win32':
+        if PY2:
+            return which(executable, path)
+        else:
+            return which(executable, path=path)
+
+    if path is None:
+        path = os.environ['PATH']
+
+    paths = path.split(os.pathsep)
+    extensions = os.environ.get('PATHEXT', '.exe').split(os.pathsep)
+    base, ext = os.path.splitext(executable)
+
+    if not os.path.isfile(executable):
+        for p in paths:
+            for ext in extensions:
+                f = os.path.join(p, base + ext)
+                if os.path.isfile(f):
+                    return f
+        return None
+    else:
+        return executable
+
+
+def create_environment_dict(overrides):
+    """
+    Create and return a copy of os.environ with the specified overrides
+    """
+    result = os.environ.copy()
+    result.update(overrides or {})
+    return result

plugins/module_utils/_api/errors.py

@@ -0,0 +1,220 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+from ._import_helper import HTTPError as _HTTPError
+
+
+class DockerException(Exception):
+    """
+    A base class from which all other exceptions inherit.
+
+    If you want to catch all errors that the Docker SDK might raise,
+    catch this base exception.
+    """
+
+
+def create_api_error_from_http_exception(e):
+    """
+    Create a suitable APIError from requests.exceptions.HTTPError.
+    """
+    response = e.response
+    try:
+        explanation = response.json()['message']
+    except ValueError:
+        explanation = (response.content or '').strip()
+    cls = APIError
+    if response.status_code == 404:
+        if explanation and ('No such image' in str(explanation) or
+                            'not found: does not exist or no pull access'
+                            in str(explanation) or
+                            'repository does not exist' in str(explanation)):
+            cls = ImageNotFound
+        else:
+            cls = NotFound
+    raise cls(e, response=response, explanation=explanation)
+
+
+class APIError(_HTTPError, DockerException):
+    """
+    An HTTP error from the API.
+    """
+    def __init__(self, message, response=None, explanation=None):
+        # requests 1.2 supports response as a keyword argument, but
+        # requests 1.1 doesn't
+        super(APIError, self).__init__(message)
+        self.response = response
+        self.explanation = explanation
+
+    def __str__(self):
+        message = super(APIError, self).__str__()
+
+        if self.is_client_error():
+            message = '{0} Client Error for {1}: {2}'.format(
+                self.response.status_code, self.response.url,
+                self.response.reason)
+
+        elif self.is_server_error():
+            message = '{0} Server Error for {1}: {2}'.format(
+                self.response.status_code, self.response.url,
+                self.response.reason)
+
+        if self.explanation:
+            message = '{0} ("{1}")'.format(message, self.explanation)
+
+        return message
+
+    @property
+    def status_code(self):
+        if self.response is not None:
+            return self.response.status_code
+
+    def is_error(self):
+        return self.is_client_error() or self.is_server_error()
+
+    def is_client_error(self):
+        if self.status_code is None:
+            return False
+        return 400 <= self.status_code < 500
+
+    def is_server_error(self):
+        if self.status_code is None:
+            return False
+        return 500 <= self.status_code < 600
+
+
+class NotFound(APIError):
+    pass
+
+
+class ImageNotFound(NotFound):
+    pass
+
+
+class InvalidVersion(DockerException):
+    pass
+
+
+class InvalidRepository(DockerException):
+    pass
+
+
+class InvalidConfigFile(DockerException):
+    pass
+
+
+class InvalidArgument(DockerException):
+    pass
+
+
+class DeprecatedMethod(DockerException):
+    pass
+
+
+class TLSParameterError(DockerException):
+    def __init__(self, msg):
+        self.msg = msg
+
+    def __str__(self):
+        return self.msg + (". TLS configurations should map the Docker CLI "
+                           "client configurations. See "
+                           "https://docs.docker.com/engine/articles/https/ "
+                           "for API details.")
+
+
+class NullResource(DockerException, ValueError):
+    pass
+
+
+class ContainerError(DockerException):
+    """
+    Represents a container that has exited with a non-zero exit code.
+    """
+    def __init__(self, container, exit_status, command, image, stderr):
+        self.container = container
+        self.exit_status = exit_status
+        self.command = command
+        self.image = image
+        self.stderr = stderr
+
+        err = ": {0}".format(stderr) if stderr is not None else ""
+        msg = ("Command '{0}' in image '{1}' returned non-zero exit "
+               "status {2}{3}").format(command, image, exit_status, err)
+
+        super(ContainerError, self).__init__(msg)
+
+
+class StreamParseError(RuntimeError):
+    def __init__(self, reason):
+        self.msg = reason
+
+
+class BuildError(DockerException):
+    def __init__(self, reason, build_log):
+        super(BuildError, self).__init__(reason)
+        self.msg = reason
+        self.build_log = build_log
+
+
+class ImageLoadError(DockerException):
+    pass
+
+
+def create_unexpected_kwargs_error(name, kwargs):
+    quoted_kwargs = ["'{0}'".format(k) for k in sorted(kwargs)]
+    text = ["{0}() ".format(name)]
+    if len(quoted_kwargs) == 1:
+        text.append("got an unexpected keyword argument ")
+    else:
+        text.append("got unexpected keyword arguments ")
+    text.append(', '.join(quoted_kwargs))
+    return TypeError(''.join(text))
+
+
+class MissingContextParameter(DockerException):
+    def __init__(self, param):
+        self.param = param
+
+    def __str__(self):
+        return ("missing parameter: {0}".format(self.param))
+
+
+class ContextAlreadyExists(DockerException):
+    def __init__(self, name):
+        self.name = name
+
+    def __str__(self):
+        return ("context {0} already exists".format(self.name))
+
+
+class ContextException(DockerException):
+    def __init__(self, msg):
+        self.msg = msg
+
+    def __str__(self):
+        return (self.msg)
+
+
+class ContextNotFound(DockerException):
+    def __init__(self, name):
+        self.name = name
+
+    def __str__(self):
+        return ("context '{0}' not found".format(self.name))
+
+
+class MissingRequirementException(DockerException):
+    def __init__(self, msg, requirement, import_exception):
+        self.msg = msg
+        self.requirement = requirement
+        self.import_exception = import_exception
+
+    def __str__(self):
+        return (self.msg)

plugins/module_utils/_api/tls.py

@@ -0,0 +1,123 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import os
+import ssl
+
+from . import errors
+from .transport.ssladapter import SSLHTTPAdapter
+
+
+class TLSConfig(object):
+    """
+    TLS configuration.
+
+    Args:
+        client_cert (tuple of str): Path to client cert, path to client key.
+        ca_cert (str): Path to CA cert file.
+        verify (bool or str): This can be ``False`` or a path to a CA cert
+            file.
+        ssl_version (int): A valid `SSL version`_.
+        assert_hostname (bool): Verify the hostname of the server.
+
+    .. _`SSL version`:
+        https://docs.python.org/3.5/library/ssl.html#ssl.PROTOCOL_TLSv1
+    """
+    cert = None
+    ca_cert = None
+    verify = None
+    ssl_version = None
+
+    def __init__(self, client_cert=None, ca_cert=None, verify=None,
+                 ssl_version=None, assert_hostname=None,
+                 assert_fingerprint=None):
+        # Argument compatibility/mapping with
+        # https://docs.docker.com/engine/articles/https/
+        # This diverges from the Docker CLI in that users can specify 'tls'
+        # here, but also disable any public/default CA pool verification by
+        # leaving verify=False
+
+        self.assert_hostname = assert_hostname
+        self.assert_fingerprint = assert_fingerprint
+
+        # TODO(dperny): according to the python docs, PROTOCOL_TLSvWhatever is
+        # depcreated, and it's recommended to use OPT_NO_TLSvWhatever instead
+        # to exclude versions. But I think that might require a bigger
+        # architectural change, so I've opted not to pursue it at this time
+
+        # If the user provides an SSL version, we should use their preference
+        if ssl_version:
+            self.ssl_version = ssl_version
+        else:
+            # If the user provides no ssl version, we should default to
+            # TLSv1_2.  This option is the most secure, and will work for the
+            # majority of users with reasonably up-to-date software. However,
+            # before doing so, detect openssl version to ensure we can support
+            # it.
+            if ssl.OPENSSL_VERSION_INFO[:3] >= (1, 0, 1) and hasattr(
+                    ssl, 'PROTOCOL_TLSv1_2'):
+                # If the OpenSSL version is high enough to support TLSv1_2,
+                # then we should use it.
+                self.ssl_version = getattr(ssl, 'PROTOCOL_TLSv1_2')
+            else:
+                # Otherwise, TLS v1.0 seems to be the safest default;
+                # SSLv23 fails in mysterious ways:
+                # https://github.com/docker/docker-py/issues/963
+                self.ssl_version = ssl.PROTOCOL_TLSv1
+
+        # "client_cert" must have both or neither cert/key files. In
+        # either case, Alert the user when both are expected, but any are
+        # missing.
+
+        if client_cert:
+            try:
+                tls_cert, tls_key = client_cert
+            except ValueError:
+                raise errors.TLSParameterError(
+                    'client_cert must be a tuple of'
+                    ' (client certificate, key file)'
+                )
+
+            if not (tls_cert and tls_key) or (not os.path.isfile(tls_cert) or
+                                              not os.path.isfile(tls_key)):
+                raise errors.TLSParameterError(
+                    'Path to a certificate and key files must be provided'
+                    ' through the client_cert param'
+                )
+            self.cert = (tls_cert, tls_key)
+
+        # If verify is set, make sure the cert exists
+        self.verify = verify
+        self.ca_cert = ca_cert
+        if self.verify and self.ca_cert and not os.path.isfile(self.ca_cert):
+            raise errors.TLSParameterError(
+                'Invalid CA certificate provided for `ca_cert`.'
+            )
+
+    def configure_client(self, client):
+        """
+        Configure a client with these TLS options.
+        """
+        client.ssl_version = self.ssl_version
+
+        if self.verify and self.ca_cert:
+            client.verify = self.ca_cert
+        else:
+            client.verify = self.verify
+
+        if self.cert:
+            client.cert = self.cert
+
+        client.mount('https://', SSLHTTPAdapter(
+            ssl_version=self.ssl_version,
+            assert_hostname=self.assert_hostname,
+            assert_fingerprint=self.assert_fingerprint,
+        ))

plugins/module_utils/_api/transport/basehttpadapter.py

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+from .._import_helper import HTTPAdapter as _HTTPAdapter
+
+
+class BaseHTTPAdapter(_HTTPAdapter):
+    def close(self):
+        super(BaseHTTPAdapter, self).close()
+        if hasattr(self, 'pools'):
+            self.pools.clear()

plugins/module_utils/_api/transport/npipeconn.py

@@ -0,0 +1,118 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+from ansible.module_utils.six import PY3
+from ansible.module_utils.six.moves.queue import Empty
+
+from .. import constants
+from .._import_helper import HTTPAdapter, urllib3
+
+from .basehttpadapter import BaseHTTPAdapter
+from .npipesocket import NpipeSocket
+
+if PY3:
+    import http.client as httplib
+else:
+    import httplib
+
+RecentlyUsedContainer = urllib3._collections.RecentlyUsedContainer
+
+
+class NpipeHTTPConnection(httplib.HTTPConnection, object):
+    def __init__(self, npipe_path, timeout=60):
+        super(NpipeHTTPConnection, self).__init__(
+            'localhost', timeout=timeout
+        )
+        self.npipe_path = npipe_path
+        self.timeout = timeout
+
+    def connect(self):
+        sock = NpipeSocket()
+        sock.settimeout(self.timeout)
+        sock.connect(self.npipe_path)
+        self.sock = sock
+
+
+class NpipeHTTPConnectionPool(urllib3.connectionpool.HTTPConnectionPool):
+    def __init__(self, npipe_path, timeout=60, maxsize=10):
+        super(NpipeHTTPConnectionPool, self).__init__(
+            'localhost', timeout=timeout, maxsize=maxsize
+        )
+        self.npipe_path = npipe_path
+        self.timeout = timeout
+
+    def _new_conn(self):
+        return NpipeHTTPConnection(
+            self.npipe_path, self.timeout
+        )
+
+    # When re-using connections, urllib3 tries to call select() on our
+    # NpipeSocket instance, causing a crash. To circumvent this, we override
+    # _get_conn, where that check happens.
+    def _get_conn(self, timeout):
+        conn = None
+        try:
+            conn = self.pool.get(block=self.block, timeout=timeout)
+
+        except AttributeError:  # self.pool is None
+            raise urllib3.exceptions.ClosedPoolError(self, "Pool is closed.")
+
+        except Empty:
+            if self.block:
+                raise urllib3.exceptions.EmptyPoolError(
+                    self,
+                    "Pool reached maximum size and no more "
+                    "connections are allowed."
+                )
+            pass  # Oh well, we'll create a new connection then
+
+        return conn or self._new_conn()
+
+
+class NpipeHTTPAdapter(BaseHTTPAdapter):
+
+    __attrs__ = HTTPAdapter.__attrs__ + ['npipe_path',
+                                         'pools',
+                                         'timeout',
+                                         'max_pool_size']
+
+    def __init__(self, base_url, timeout=60,
+                 pool_connections=constants.DEFAULT_NUM_POOLS,
+                 max_pool_size=constants.DEFAULT_MAX_POOL_SIZE):
+        self.npipe_path = base_url.replace('npipe://', '')
+        self.timeout = timeout
+        self.max_pool_size = max_pool_size
+        self.pools = RecentlyUsedContainer(
+            pool_connections, dispose_func=lambda p: p.close()
+        )
+        super(NpipeHTTPAdapter, self).__init__()
+
+    def get_connection(self, url, proxies=None):
+        with self.pools.lock:
+            pool = self.pools.get(url)
+            if pool:
+                return pool
+
+            pool = NpipeHTTPConnectionPool(
+                self.npipe_path, self.timeout,
+                maxsize=self.max_pool_size
+            )
+            self.pools[url] = pool
+
+        return pool
+
+    def request_url(self, request, proxies):
+        # The select_proxy utility in requests errors out when the provided URL
+        # doesn't have a hostname, like is the case when using a UNIX socket.
+        # Since proxies are an irrelevant notion in the case of UNIX sockets
+        # anyway, we simply return the path URL directly.
+        # See also: https://github.com/docker/docker-sdk-python/issues/811
+        return request.path_url

plugins/module_utils/_api/transport/npipesocket.py

@@ -0,0 +1,235 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import functools
+import io
+import time
+import traceback
+
+from ansible.module_utils.six import PY2
+
+PYWIN32_IMPORT_ERROR = None
+try:
+    import win32file
+    import win32pipe
+except ImportError:
+    PYWIN32_IMPORT_ERROR = traceback.format_exc()
+
+
+cERROR_PIPE_BUSY = 0xe7
+cSECURITY_SQOS_PRESENT = 0x100000
+cSECURITY_ANONYMOUS = 0
+
+MAXIMUM_RETRY_COUNT = 10
+
+
+def check_closed(f):
+    @functools.wraps(f)
+    def wrapped(self, *args, **kwargs):
+        if self._closed:
+            raise RuntimeError(
+                'Can not reuse socket after connection was closed.'
+            )
+        return f(self, *args, **kwargs)
+    return wrapped
+
+
+class NpipeSocket(object):
+    """ Partial implementation of the socket API over windows named pipes.
+        This implementation is only designed to be used as a client socket,
+        and server-specific methods (bind, listen, accept...) are not
+        implemented.
+    """
+
+    def __init__(self, handle=None):
+        self._timeout = win32pipe.NMPWAIT_USE_DEFAULT_WAIT
+        self._handle = handle
+        self._closed = False
+
+    def accept(self):
+        raise NotImplementedError()
+
+    def bind(self, address):
+        raise NotImplementedError()
+
+    def close(self):
+        self._handle.Close()
+        self._closed = True
+
+    @check_closed
+    def connect(self, address, retry_count=0):
+        try:
+            handle = win32file.CreateFile(
+                address,
+                win32file.GENERIC_READ | win32file.GENERIC_WRITE,
+                0,
+                None,
+                win32file.OPEN_EXISTING,
+                cSECURITY_ANONYMOUS | cSECURITY_SQOS_PRESENT,
+                0
+            )
+        except win32pipe.error as e:
+            # See Remarks:
+            # https://msdn.microsoft.com/en-us/library/aa365800.aspx
+            if e.winerror == cERROR_PIPE_BUSY:
+                # Another program or thread has grabbed our pipe instance
+                # before we got to it. Wait for availability and attempt to
+                # connect again.
+                retry_count = retry_count + 1
+                if (retry_count < MAXIMUM_RETRY_COUNT):
+                    time.sleep(1)
+                    return self.connect(address, retry_count)
+            raise e
+
+        self.flags = win32pipe.GetNamedPipeInfo(handle)[0]
+
+        self._handle = handle
+        self._address = address
+
+    @check_closed
+    def connect_ex(self, address):
+        return self.connect(address)
+
+    @check_closed
+    def detach(self):
+        self._closed = True
+        return self._handle
+
+    @check_closed
+    def dup(self):
+        return NpipeSocket(self._handle)
+
+    def getpeername(self):
+        return self._address
+
+    def getsockname(self):
+        return self._address
+
+    def getsockopt(self, level, optname, buflen=None):
+        raise NotImplementedError()
+
+    def ioctl(self, control, option):
+        raise NotImplementedError()
+
+    def listen(self, backlog):
+        raise NotImplementedError()
+
+    def makefile(self, mode=None, bufsize=None):
+        if mode.strip('b') != 'r':
+            raise NotImplementedError()
+        rawio = NpipeFileIOBase(self)
+        if bufsize is None or bufsize <= 0:
+            bufsize = io.DEFAULT_BUFFER_SIZE
+        return io.BufferedReader(rawio, buffer_size=bufsize)
+
+    @check_closed
+    def recv(self, bufsize, flags=0):
+        err, data = win32file.ReadFile(self._handle, bufsize)
+        return data
+
+    @check_closed
+    def recvfrom(self, bufsize, flags=0):
+        data = self.recv(bufsize, flags)
+        return (data, self._address)
+
+    @check_closed
+    def recvfrom_into(self, buf, nbytes=0, flags=0):
+        return self.recv_into(buf, nbytes, flags), self._address
+
+    @check_closed
+    def recv_into(self, buf, nbytes=0):
+        if PY2:
+            return self._recv_into_py2(buf, nbytes)
+
+        readbuf = buf
+        if not isinstance(buf, memoryview):
+            readbuf = memoryview(buf)
+
+        err, data = win32file.ReadFile(
+            self._handle,
+            readbuf[:nbytes] if nbytes else readbuf
+        )
+        return len(data)
+
+    def _recv_into_py2(self, buf, nbytes):
+        err, data = win32file.ReadFile(self._handle, nbytes or len(buf))
+        n = len(data)
+        buf[:n] = data
+        return n
+
+    @check_closed
+    def send(self, string, flags=0):
+        err, nbytes = win32file.WriteFile(self._handle, string)
+        return nbytes
+
+    @check_closed
+    def sendall(self, string, flags=0):
+        return self.send(string, flags)
+
+    @check_closed
+    def sendto(self, string, address):
+        self.connect(address)
+        return self.send(string)
+
+    def setblocking(self, flag):
+        if flag:
+            return self.settimeout(None)
+        return self.settimeout(0)
+
+    def settimeout(self, value):
+        if value is None:
+            # Blocking mode
+            self._timeout = win32pipe.NMPWAIT_WAIT_FOREVER
+        elif not isinstance(value, (float, int)) or value < 0:
+            raise ValueError('Timeout value out of range')
+        elif value == 0:
+            # Non-blocking mode
+            self._timeout = win32pipe.NMPWAIT_NO_WAIT
+        else:
+            # Timeout mode - Value converted to milliseconds
+            self._timeout = value * 1000
+
+    def gettimeout(self):
+        return self._timeout
+
+    def setsockopt(self, level, optname, value):
+        raise NotImplementedError()
+
+    @check_closed
+    def shutdown(self, how):
+        return self.close()
+
+
+class NpipeFileIOBase(io.RawIOBase):
+    def __init__(self, npipe_socket):
+        self.sock = npipe_socket
+
+    def close(self):
+        super(NpipeFileIOBase, self).close()
+        self.sock = None
+
+    def fileno(self):
+        return self.sock.fileno()
+
+    def isatty(self):
+        return False
+
+    def readable(self):
+        return True
+
+    def readinto(self, buf):
+        return self.sock.recv_into(buf)
+
+    def seekable(self):
+        return False
+
+    def writable(self):
+        return False

plugins/module_utils/_api/transport/sshconn.py

@@ -0,0 +1,275 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import logging
+import os
+import signal
+import socket
+import subprocess
+import traceback
+
+from ansible.module_utils.six import PY3
+from ansible.module_utils.six.moves.queue import Empty
+from ansible.module_utils.six.moves.urllib_parse import urlparse
+
+from .basehttpadapter import BaseHTTPAdapter
+from .. import constants
+
+if PY3:
+    import http.client as httplib
+else:
+    import httplib
+
+from .._import_helper import HTTPAdapter, urllib3
+
+PARAMIKO_IMPORT_ERROR = None
+try:
+    import paramiko
+except ImportError:
+    PARAMIKO_IMPORT_ERROR = traceback.format_exc()
+
+
+RecentlyUsedContainer = urllib3._collections.RecentlyUsedContainer
+
+
+class SSHSocket(socket.socket):
+    def __init__(self, host):
+        super(SSHSocket, self).__init__(
+            socket.AF_INET, socket.SOCK_STREAM)
+        self.host = host
+        self.port = None
+        self.user = None
+        if ':' in self.host:
+            self.host, self.port = self.host.split(':')
+        if '@' in self.host:
+            self.user, self.host = self.host.split('@')
+
+        self.proc = None
+
+    def connect(self, **kwargs):
+        args = ['ssh']
+        if self.user:
+            args = args + ['-l', self.user]
+
+        if self.port:
+            args = args + ['-p', self.port]
+
+        args = args + ['--', self.host, 'docker system dial-stdio']
+
+        preexec_func = None
+        if not constants.IS_WINDOWS_PLATFORM:
+            def f():
+                signal.signal(signal.SIGINT, signal.SIG_IGN)
+            preexec_func = f
+
+        env = dict(os.environ)
+
+        # drop LD_LIBRARY_PATH and SSL_CERT_FILE
+        env.pop('LD_LIBRARY_PATH', None)
+        env.pop('SSL_CERT_FILE', None)
+
+        self.proc = subprocess.Popen(
+            ' '.join(args),
+            env=env,
+            shell=True,
+            stdout=subprocess.PIPE,
+            stdin=subprocess.PIPE,
+            preexec_fn=preexec_func)
+
+    def _write(self, data):
+        if not self.proc or self.proc.stdin.closed:
+            raise Exception('SSH subprocess not initiated.'
+                            'connect() must be called first.')
+        written = self.proc.stdin.write(data)
+        self.proc.stdin.flush()
+        return written
+
+    def sendall(self, data):
+        self._write(data)
+
+    def send(self, data):
+        return self._write(data)
+
+    def recv(self, n):
+        if not self.proc:
+            raise Exception('SSH subprocess not initiated.'
+                            'connect() must be called first.')
+        return self.proc.stdout.read(n)
+
+    def makefile(self, mode):
+        if not self.proc:
+            self.connect()
+        if PY3:
+            self.proc.stdout.channel = self
+
+        return self.proc.stdout
+
+    def close(self):
+        if not self.proc or self.proc.stdin.closed:
+            return
+        self.proc.stdin.write(b'\n\n')
+        self.proc.stdin.flush()
+        self.proc.terminate()
+
+
+class SSHConnection(httplib.HTTPConnection, object):
+    def __init__(self, ssh_transport=None, timeout=60, host=None):
+        super(SSHConnection, self).__init__(
+            'localhost', timeout=timeout
+        )
+        self.ssh_transport = ssh_transport
+        self.timeout = timeout
+        self.ssh_host = host
+
+    def connect(self):
+        if self.ssh_transport:
+            sock = self.ssh_transport.open_session()
+            sock.settimeout(self.timeout)
+            sock.exec_command('docker system dial-stdio')
+        else:
+            sock = SSHSocket(self.ssh_host)
+            sock.settimeout(self.timeout)
+            sock.connect()
+
+        self.sock = sock
+
+
+class SSHConnectionPool(urllib3.connectionpool.HTTPConnectionPool):
+    scheme = 'ssh'
+
+    def __init__(self, ssh_client=None, timeout=60, maxsize=10, host=None):
+        super(SSHConnectionPool, self).__init__(
+            'localhost', timeout=timeout, maxsize=maxsize
+        )
+        self.ssh_transport = None
+        self.timeout = timeout
+        if ssh_client:
+            self.ssh_transport = ssh_client.get_transport()
+        self.ssh_host = host
+
+    def _new_conn(self):
+        return SSHConnection(self.ssh_transport, self.timeout, self.ssh_host)
+
+    # When re-using connections, urllib3 calls fileno() on our
+    # SSH channel instance, quickly overloading our fd limit. To avoid this,
+    # we override _get_conn
+    def _get_conn(self, timeout):
+        conn = None
+        try:
+            conn = self.pool.get(block=self.block, timeout=timeout)
+
+        except AttributeError:  # self.pool is None
+            raise urllib3.exceptions.ClosedPoolError(self, "Pool is closed.")
+
+        except Empty:
+            if self.block:
+                raise urllib3.exceptions.EmptyPoolError(
+                    self,
+                    "Pool reached maximum size and no more "
+                    "connections are allowed."
+                )
+            pass  # Oh well, we'll create a new connection then
+
+        return conn or self._new_conn()
+
+
+class SSHHTTPAdapter(BaseHTTPAdapter):
+
+    __attrs__ = HTTPAdapter.__attrs__ + [
+        'pools', 'timeout', 'ssh_client', 'ssh_params', 'max_pool_size'
+    ]
+
+    def __init__(self, base_url, timeout=60,
+                 pool_connections=constants.DEFAULT_NUM_POOLS,
+                 max_pool_size=constants.DEFAULT_MAX_POOL_SIZE,
+                 shell_out=False):
+        self.ssh_client = None
+        if not shell_out:
+            self._create_paramiko_client(base_url)
+            self._connect()
+
+        self.ssh_host = base_url
+        if base_url.startswith('ssh://'):
+            self.ssh_host = base_url[len('ssh://'):]
+
+        self.timeout = timeout
+        self.max_pool_size = max_pool_size
+        self.pools = RecentlyUsedContainer(
+            pool_connections, dispose_func=lambda p: p.close()
+        )
+        super(SSHHTTPAdapter, self).__init__()
+
+    def _create_paramiko_client(self, base_url):
+        logging.getLogger("paramiko").setLevel(logging.WARNING)
+        self.ssh_client = paramiko.SSHClient()
+        base_url = urlparse(base_url)
+        self.ssh_params = {
+            "hostname": base_url.hostname,
+            "port": base_url.port,
+            "username": base_url.username,
+        }
+        ssh_config_file = os.path.expanduser("~/.ssh/config")
+        if os.path.exists(ssh_config_file):
+            conf = paramiko.SSHConfig()
+            with open(ssh_config_file) as f:
+                conf.parse(f)
+            host_config = conf.lookup(base_url.hostname)
+            if 'proxycommand' in host_config:
+                self.ssh_params["sock"] = paramiko.ProxyCommand(
+                    self.ssh_conf['proxycommand']
+                )
+            if 'hostname' in host_config:
+                self.ssh_params['hostname'] = host_config['hostname']
+            if base_url.port is None and 'port' in host_config:
+                self.ssh_params['port'] = host_config['port']
+            if base_url.username is None and 'user' in host_config:
+                self.ssh_params['username'] = host_config['user']
+            if 'identityfile' in host_config:
+                self.ssh_params['key_filename'] = host_config['identityfile']
+
+        self.ssh_client.load_system_host_keys()
+        self.ssh_client.set_missing_host_key_policy(paramiko.WarningPolicy())
+
+    def _connect(self):
+        if self.ssh_client:
+            self.ssh_client.connect(**self.ssh_params)
+
+    def get_connection(self, url, proxies=None):
+        if not self.ssh_client:
+            return SSHConnectionPool(
+                ssh_client=self.ssh_client,
+                timeout=self.timeout,
+                maxsize=self.max_pool_size,
+                host=self.ssh_host
+            )
+        with self.pools.lock:
+            pool = self.pools.get(url)
+            if pool:
+                return pool
+
+            # Connection is closed try a reconnect
+            if self.ssh_client and not self.ssh_client.get_transport():
+                self._connect()
+
+            pool = SSHConnectionPool(
+                ssh_client=self.ssh_client,
+                timeout=self.timeout,
+                maxsize=self.max_pool_size,
+                host=self.ssh_host
+            )
+            self.pools[url] = pool
+
+        return pool
+
+    def close(self):
+        super(SSHHTTPAdapter, self).close()
+        if self.ssh_client:
+            self.ssh_client.close()

plugins/module_utils/_api/transport/ssladapter.py

@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+""" Resolves OpenSSL issues in some servers:
+      https://lukasa.co.uk/2013/01/Choosing_SSL_Version_In_Requests/
+      https://github.com/kennethreitz/requests/pull/799
+"""
+import sys
+
+from ansible_collections.community.docker.plugins.module_utils.version import StrictVersion
+
+from .._import_helper import HTTPAdapter, urllib3
+from .basehttpadapter import BaseHTTPAdapter
+
+
+PoolManager = urllib3.poolmanager.PoolManager
+
+
+class SSLHTTPAdapter(BaseHTTPAdapter):
+    '''An HTTPS Transport Adapter that uses an arbitrary SSL version.'''
+
+    __attrs__ = HTTPAdapter.__attrs__ + ['assert_fingerprint',
+                                         'assert_hostname',
+                                         'ssl_version']
+
+    def __init__(self, ssl_version=None, assert_hostname=None,
+                 assert_fingerprint=None, **kwargs):
+        self.ssl_version = ssl_version
+        self.assert_hostname = assert_hostname
+        self.assert_fingerprint = assert_fingerprint
+        super(SSLHTTPAdapter, self).__init__(**kwargs)
+
+    def init_poolmanager(self, connections, maxsize, block=False):
+        kwargs = {
+            'num_pools': connections,
+            'maxsize': maxsize,
+            'block': block,
+            'assert_hostname': self.assert_hostname,
+            'assert_fingerprint': self.assert_fingerprint,
+        }
+        if self.ssl_version and self.can_override_ssl_version():
+            kwargs['ssl_version'] = self.ssl_version
+
+        self.poolmanager = PoolManager(**kwargs)
+
+    def get_connection(self, *args, **kwargs):
+        """
+        Ensure assert_hostname is set correctly on our pool
+
+        We already take care of a normal poolmanager via init_poolmanager
+
+        But we still need to take care of when there is a proxy poolmanager
+        """
+        conn = super(SSLHTTPAdapter, self).get_connection(*args, **kwargs)
+        if conn.assert_hostname != self.assert_hostname:
+            conn.assert_hostname = self.assert_hostname
+        return conn
+
+    def can_override_ssl_version(self):
+        urllib_ver = urllib3.__version__.split('-')[0]
+        if urllib_ver is None:
+            return False
+        if urllib_ver == 'dev':
+            return True
+        return StrictVersion(urllib_ver) > StrictVersion('1.5')

plugins/module_utils/_api/transport/unixconn.py

@@ -0,0 +1,122 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import socket
+
+from ansible.module_utils.six import PY2
+from ansible.module_utils.six.moves import http_client as httplib
+
+from .basehttpadapter import BaseHTTPAdapter
+from .. import constants
+
+from .._import_helper import HTTPAdapter, urllib3
+
+
+RecentlyUsedContainer = urllib3._collections.RecentlyUsedContainer
+
+
+class UnixHTTPResponse(httplib.HTTPResponse, object):
+    def __init__(self, sock, *args, **kwargs):
+        disable_buffering = kwargs.pop('disable_buffering', False)
+        if PY2:
+            # FIXME: We may need to disable buffering on Py3 as well,
+            # but there's no clear way to do it at the moment. See:
+            # https://github.com/docker/docker-py/issues/1799
+            kwargs['buffering'] = not disable_buffering
+        super(UnixHTTPResponse, self).__init__(sock, *args, **kwargs)
+
+
+class UnixHTTPConnection(httplib.HTTPConnection, object):
+
+    def __init__(self, base_url, unix_socket, timeout=60):
+        super(UnixHTTPConnection, self).__init__(
+            'localhost', timeout=timeout
+        )
+        self.base_url = base_url
+        self.unix_socket = unix_socket
+        self.timeout = timeout
+        self.disable_buffering = False
+
+    def connect(self):
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        sock.settimeout(self.timeout)
+        sock.connect(self.unix_socket)
+        self.sock = sock
+
+    def putheader(self, header, *values):
+        super(UnixHTTPConnection, self).putheader(header, *values)
+        if header == 'Connection' and 'Upgrade' in values:
+            self.disable_buffering = True
+
+    def response_class(self, sock, *args, **kwargs):
+        if self.disable_buffering:
+            kwargs['disable_buffering'] = True
+
+        return UnixHTTPResponse(sock, *args, **kwargs)
+
+
+class UnixHTTPConnectionPool(urllib3.connectionpool.HTTPConnectionPool):
+    def __init__(self, base_url, socket_path, timeout=60, maxsize=10):
+        super(UnixHTTPConnectionPool, self).__init__(
+            'localhost', timeout=timeout, maxsize=maxsize
+        )
+        self.base_url = base_url
+        self.socket_path = socket_path
+        self.timeout = timeout
+
+    def _new_conn(self):
+        return UnixHTTPConnection(
+            self.base_url, self.socket_path, self.timeout
+        )
+
+
+class UnixHTTPAdapter(BaseHTTPAdapter):
+
+    __attrs__ = HTTPAdapter.__attrs__ + ['pools',
+                                         'socket_path',
+                                         'timeout',
+                                         'max_pool_size']
+
+    def __init__(self, socket_url, timeout=60,
+                 pool_connections=constants.DEFAULT_NUM_POOLS,
+                 max_pool_size=constants.DEFAULT_MAX_POOL_SIZE):
+        socket_path = socket_url.replace('http+unix://', '')
+        if not socket_path.startswith('/'):
+            socket_path = '/' + socket_path
+        self.socket_path = socket_path
+        self.timeout = timeout
+        self.max_pool_size = max_pool_size
+        self.pools = RecentlyUsedContainer(
+            pool_connections, dispose_func=lambda p: p.close()
+        )
+        super(UnixHTTPAdapter, self).__init__()
+
+    def get_connection(self, url, proxies=None):
+        with self.pools.lock:
+            pool = self.pools.get(url)
+            if pool:
+                return pool
+
+            pool = UnixHTTPConnectionPool(
+                url, self.socket_path, self.timeout,
+                maxsize=self.max_pool_size
+            )
+            self.pools[url] = pool
+
+        return pool
+
+    def request_url(self, request, proxies):
+        # The select_proxy utility in requests errors out when the provided URL
+        # doesn't have a hostname, like is the case when using a UNIX socket.
+        # Since proxies are an irrelevant notion in the case of UNIX sockets
+        # anyway, we simply return the path URL directly.
+        # See also: https://github.com/docker/docker-py/issues/811
+        return request.path_url

plugins/module_utils/_api/types/daemon.py

@@ -0,0 +1,82 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import socket
+
+from .._import_helper import urllib3
+
+from ..errors import DockerException
+
+
+class CancellableStream(object):
+    """
+    Stream wrapper for real-time events, logs, etc. from the server.
+
+    Example:
+        >>> events = client.events()
+        >>> for event in events:
+        ...   print(event)
+        >>> # and cancel from another thread
+        >>> events.close()
+    """
+
+    def __init__(self, stream, response):
+        self._stream = stream
+        self._response = response
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        try:
+            return next(self._stream)
+        except urllib3.exceptions.ProtocolError:
+            raise StopIteration
+        except socket.error:
+            raise StopIteration
+
+    next = __next__
+
+    def close(self):
+        """
+        Closes the event streaming.
+        """
+
+        if not self._response.raw.closed:
+            # find the underlying socket object
+            # based on api.client._get_raw_response_socket
+
+            sock_fp = self._response.raw._fp.fp
+
+            if hasattr(sock_fp, 'raw'):
+                sock_raw = sock_fp.raw
+
+                if hasattr(sock_raw, 'sock'):
+                    sock = sock_raw.sock
+
+                elif hasattr(sock_raw, '_sock'):
+                    sock = sock_raw._sock
+
+            elif hasattr(sock_fp, 'channel'):
+                # We're working with a paramiko (SSH) channel, which doesn't
+                # support cancelable streams with the current implementation
+                raise DockerException(
+                    'Cancellable streams not supported for the SSH protocol'
+                )
+            else:
+                sock = sock_fp._sock
+
+            if hasattr(urllib3.contrib, 'pyopenssl') and isinstance(
+                    sock, urllib3.contrib.pyopenssl.WrappedSocket):
+                sock = sock.socket
+
+            sock.shutdown(socket.SHUT_RDWR)
+            sock.close()

plugins/module_utils/_api/utils/build.py

@@ -0,0 +1,301 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import io
+import os
+import random
+import re
+import tarfile
+import tempfile
+
+from ansible.module_utils.six import PY3
+
+from . import fnmatch
+from ..constants import IS_WINDOWS_PLATFORM, WINDOWS_LONGPATH_PREFIX
+
+
+_SEP = re.compile('/|\\\\') if IS_WINDOWS_PLATFORM else re.compile('/')
+
+
+def tar(path, exclude=None, dockerfile=None, fileobj=None, gzip=False):
+    root = os.path.abspath(path)
+    exclude = exclude or []
+    dockerfile = dockerfile or (None, None)
+    extra_files = []
+    if dockerfile[1] is not None:
+        dockerignore_contents = '\n'.join(
+            (exclude or ['.dockerignore']) + [dockerfile[0]]
+        )
+        extra_files = [
+            ('.dockerignore', dockerignore_contents),
+            dockerfile,
+        ]
+    return create_archive(
+        files=sorted(exclude_paths(root, exclude, dockerfile=dockerfile[0])),
+        root=root, fileobj=fileobj, gzip=gzip, extra_files=extra_files
+    )
+
+
+def exclude_paths(root, patterns, dockerfile=None):
+    """
+    Given a root directory path and a list of .dockerignore patterns, return
+    an iterator of all paths (both regular files and directories) in the root
+    directory that do *not* match any of the patterns.
+
+    All paths returned are relative to the root.
+    """
+
+    if dockerfile is None:
+        dockerfile = 'Dockerfile'
+
+    patterns.append('!' + dockerfile)
+    pm = PatternMatcher(patterns)
+    return set(pm.walk(root))
+
+
+def build_file_list(root):
+    files = []
+    for dirname, dirnames, fnames in os.walk(root):
+        for filename in fnames + dirnames:
+            longpath = os.path.join(dirname, filename)
+            files.append(
+                longpath.replace(root, '', 1).lstrip('/')
+            )
+
+    return files
+
+
+def create_archive(root, files=None, fileobj=None, gzip=False,
+                   extra_files=None):
+    extra_files = extra_files or []
+    if not fileobj:
+        fileobj = tempfile.NamedTemporaryFile()
+    t = tarfile.open(mode='w:gz' if gzip else 'w', fileobj=fileobj)
+    if files is None:
+        files = build_file_list(root)
+    extra_names = set(e[0] for e in extra_files)
+    for path in files:
+        if path in extra_names:
+            # Extra files override context files with the same name
+            continue
+        full_path = os.path.join(root, path)
+
+        i = t.gettarinfo(full_path, arcname=path)
+        if i is None:
+            # This happens when we encounter a socket file. We can safely
+            # ignore it and proceed.
+            continue
+
+        # Workaround https://bugs.python.org/issue32713
+        if i.mtime < 0 or i.mtime > 8**11 - 1:
+            i.mtime = int(i.mtime)
+
+        if IS_WINDOWS_PLATFORM:
+            # Windows doesn't keep track of the execute bit, so we make files
+            # and directories executable by default.
+            i.mode = i.mode & 0o755 | 0o111
+
+        if i.isfile():
+            try:
+                with open(full_path, 'rb') as f:
+                    t.addfile(i, f)
+            except IOError:
+                raise IOError(
+                    'Can not read file in context: {0}'.format(full_path)
+                )
+        else:
+            # Directories, FIFOs, symlinks... don't need to be read.
+            t.addfile(i, None)
+
+    for name, contents in extra_files:
+        info = tarfile.TarInfo(name)
+        contents_encoded = contents.encode('utf-8')
+        info.size = len(contents_encoded)
+        t.addfile(info, io.BytesIO(contents_encoded))
+
+    t.close()
+    fileobj.seek(0)
+    return fileobj
+
+
+def mkbuildcontext(dockerfile):
+    f = tempfile.NamedTemporaryFile()
+    t = tarfile.open(mode='w', fileobj=f)
+    if isinstance(dockerfile, io.StringIO):
+        dfinfo = tarfile.TarInfo('Dockerfile')
+        if PY3:
+            raise TypeError('Please use io.BytesIO to create in-memory '
+                            'Dockerfiles with Python 3')
+        else:
+            dfinfo.size = len(dockerfile.getvalue())
+            dockerfile.seek(0)
+    elif isinstance(dockerfile, io.BytesIO):
+        dfinfo = tarfile.TarInfo('Dockerfile')
+        dfinfo.size = len(dockerfile.getvalue())
+        dockerfile.seek(0)
+    else:
+        dfinfo = t.gettarinfo(fileobj=dockerfile, arcname='Dockerfile')
+    t.addfile(dfinfo, dockerfile)
+    t.close()
+    f.seek(0)
+    return f
+
+
+def split_path(p):
+    return [pt for pt in re.split(_SEP, p) if pt and pt != '.']
+
+
+def normalize_slashes(p):
+    if IS_WINDOWS_PLATFORM:
+        return '/'.join(split_path(p))
+    return p
+
+
+def walk(root, patterns, default=True):
+    pm = PatternMatcher(patterns)
+    return pm.walk(root)
+
+
+# Heavily based on
+# https://github.com/moby/moby/blob/master/pkg/fileutils/fileutils.go
+class PatternMatcher(object):
+    def __init__(self, patterns):
+        self.patterns = list(filter(
+            lambda p: p.dirs, [Pattern(p) for p in patterns]
+        ))
+        self.patterns.append(Pattern('!.dockerignore'))
+
+    def matches(self, filepath):
+        matched = False
+        parent_path = os.path.dirname(filepath)
+        parent_path_dirs = split_path(parent_path)
+
+        for pattern in self.patterns:
+            negative = pattern.exclusion
+            match = pattern.match(filepath)
+            if not match and parent_path != '':
+                if len(pattern.dirs) <= len(parent_path_dirs):
+                    match = pattern.match(
+                        os.path.sep.join(parent_path_dirs[:len(pattern.dirs)])
+                    )
+
+            if match:
+                matched = not negative
+
+        return matched
+
+    def walk(self, root):
+        def rec_walk(current_dir):
+            for f in os.listdir(current_dir):
+                fpath = os.path.join(
+                    os.path.relpath(current_dir, root), f
+                )
+                if fpath.startswith('.' + os.path.sep):
+                    fpath = fpath[2:]
+                match = self.matches(fpath)
+                if not match:
+                    yield fpath
+
+                cur = os.path.join(root, fpath)
+                if not os.path.isdir(cur) or os.path.islink(cur):
+                    continue
+
+                if match:
+                    # If we want to skip this file and it's a directory
+                    # then we should first check to see if there's an
+                    # excludes pattern (e.g. !dir/file) that starts with this
+                    # dir. If so then we can't skip this dir.
+                    skip = True
+
+                    for pat in self.patterns:
+                        if not pat.exclusion:
+                            continue
+                        if pat.cleaned_pattern.startswith(
+                                normalize_slashes(fpath)):
+                            skip = False
+                            break
+                    if skip:
+                        continue
+                for sub in rec_walk(cur):
+                    yield sub
+
+        return rec_walk(root)
+
+
+class Pattern(object):
+    def __init__(self, pattern_str):
+        self.exclusion = False
+        if pattern_str.startswith('!'):
+            self.exclusion = True
+            pattern_str = pattern_str[1:]
+
+        self.dirs = self.normalize(pattern_str)
+        self.cleaned_pattern = '/'.join(self.dirs)
+
+    @classmethod
+    def normalize(cls, p):
+
+        # Leading and trailing slashes are not relevant. Yes,
+        # "foo.py/" must exclude the "foo.py" regular file. "."
+        # components are not relevant either, even if the whole
+        # pattern is only ".", as the Docker reference states: "For
+        # historical reasons, the pattern . is ignored."
+        # ".." component must be cleared with the potential previous
+        # component, regardless of whether it exists: "A preprocessing
+        # step [...]  eliminates . and .. elements using Go's
+        # filepath.".
+        i = 0
+        split = split_path(p)
+        while i < len(split):
+            if split[i] == '..':
+                del split[i]
+                if i > 0:
+                    del split[i - 1]
+                    i -= 1
+            else:
+                i += 1
+        return split
+
+    def match(self, filepath):
+        return fnmatch.fnmatch(normalize_slashes(filepath), self.cleaned_pattern)
+
+
+def process_dockerfile(dockerfile, path):
+    if not dockerfile:
+        return (None, None)
+
+    abs_dockerfile = dockerfile
+    if not os.path.isabs(dockerfile):
+        abs_dockerfile = os.path.join(path, dockerfile)
+        if IS_WINDOWS_PLATFORM and path.startswith(
+                WINDOWS_LONGPATH_PREFIX):
+            abs_dockerfile = '{0}{1}'.format(
+                WINDOWS_LONGPATH_PREFIX,
+                os.path.normpath(
+                    abs_dockerfile[len(WINDOWS_LONGPATH_PREFIX):]
+                )
+            )
+    if (os.path.splitdrive(path)[0] != os.path.splitdrive(abs_dockerfile)[0] or
+            os.path.relpath(abs_dockerfile, path).startswith('..')):
+        # Dockerfile not in context - read data to insert into tar later
+        with open(abs_dockerfile) as df:
+            return (
+                '.dockerfile.{random:x}'.format(random=random.getrandbits(160)),
+                df.read()
+            )
+
+    # Dockerfile is inside the context - return path relative to context root
+    if dockerfile == abs_dockerfile:
+        # Only calculate relpath if necessary to avoid errors
+        # on Windows client -> Linux Docker
+        # see https://github.com/docker/compose/issues/5969
+        dockerfile = os.path.relpath(abs_dockerfile, path)
+    return (dockerfile, None)

plugins/module_utils/_api/utils/config.py

@@ -0,0 +1,77 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import json
+import logging
+import os
+
+from ..constants import IS_WINDOWS_PLATFORM
+
+DOCKER_CONFIG_FILENAME = os.path.join('.docker', 'config.json')
+LEGACY_DOCKER_CONFIG_FILENAME = '.dockercfg'
+
+log = logging.getLogger(__name__)
+
+
+def find_config_file(config_path=None):
+    paths = list(filter(None, [
+        config_path,  # 1
+        config_path_from_environment(),  # 2
+        os.path.join(home_dir(), DOCKER_CONFIG_FILENAME),  # 3
+        os.path.join(home_dir(), LEGACY_DOCKER_CONFIG_FILENAME),  # 4
+    ]))
+
+    log.debug("Trying paths: %s", repr(paths))
+
+    for path in paths:
+        if os.path.exists(path):
+            log.debug("Found file at path: %s", path)
+            return path
+
+    log.debug("No config file found")
+
+    return None
+
+
+def config_path_from_environment():
+    config_dir = os.environ.get('DOCKER_CONFIG')
+    if not config_dir:
+        return None
+    return os.path.join(config_dir, os.path.basename(DOCKER_CONFIG_FILENAME))
+
+
+def home_dir():
+    """
+    Get the user's home directory, using the same logic as the Docker Engine
+    client - use %USERPROFILE% on Windows, $HOME/getuid on POSIX.
+    """
+    if IS_WINDOWS_PLATFORM:
+        return os.environ.get('USERPROFILE', '')
+    else:
+        return os.path.expanduser('~')
+
+
+def load_general_config(config_path=None):
+    config_file = find_config_file(config_path)
+
+    if not config_file:
+        return {}
+
+    try:
+        with open(config_file) as f:
+            return json.load(f)
+    except (IOError, ValueError) as e:
+        # In the case of a legacy `.dockercfg` file, we won't
+        # be able to load any JSON data.
+        log.debug(e)
+
+    log.debug("All parsing attempts failed - returning empty config")
+    return {}

plugins/module_utils/_api/utils/decorators.py

@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import functools
+
+from .. import errors
+from . import utils
+
+
+def check_resource(resource_name):
+    def decorator(f):
+        @functools.wraps(f)
+        def wrapped(self, resource_id=None, *args, **kwargs):
+            if resource_id is None and kwargs.get(resource_name):
+                resource_id = kwargs.pop(resource_name)
+            if isinstance(resource_id, dict):
+                resource_id = resource_id.get('Id', resource_id.get('ID'))
+            if not resource_id:
+                raise errors.NullResource(
+                    'Resource ID was not provided'
+                )
+            return f(self, resource_id, *args, **kwargs)
+        return wrapped
+    return decorator
+
+
+def minimum_version(version):
+    def decorator(f):
+        @functools.wraps(f)
+        def wrapper(self, *args, **kwargs):
+            if utils.version_lt(self._version, version):
+                raise errors.InvalidVersion(
+                    '{0} is not available for version < {1}'.format(
+                        f.__name__, version
+                    )
+                )
+            return f(self, *args, **kwargs)
+        return wrapper
+    return decorator
+
+
+def update_headers(f):
+    def inner(self, *args, **kwargs):
+        if 'HttpHeaders' in self._general_configs:
+            if not kwargs.get('headers'):
+                kwargs['headers'] = self._general_configs['HttpHeaders']
+            else:
+                kwargs['headers'].update(self._general_configs['HttpHeaders'])
+        return f(self, *args, **kwargs)
+    return inner

plugins/module_utils/_api/utils/fnmatch.py

@@ -0,0 +1,126 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+"""Filename matching with shell patterns.
+
+fnmatch(FILENAME, PATTERN) matches according to the local convention.
+fnmatchcase(FILENAME, PATTERN) always takes case in account.
+
+The functions operate by translating the pattern into a regular
+expression.  They cache the compiled regular expressions for speed.
+
+The function translate(PATTERN) returns a regular expression
+corresponding to PATTERN.  (It does not compile it.)
+"""
+
+import re
+
+__all__ = ["fnmatch", "fnmatchcase", "translate"]
+
+_cache = {}
+_MAXCACHE = 100
+
+
+def _purge():
+    """Clear the pattern cache"""
+    _cache.clear()
+
+
+def fnmatch(name, pat):
+    """Test whether FILENAME matches PATTERN.
+
+    Patterns are Unix shell style:
+
+    *       matches everything
+    ?       matches any single character
+    [seq]   matches any character in seq
+    [!seq]  matches any char not in seq
+
+    An initial period in FILENAME is not special.
+    Both FILENAME and PATTERN are first case-normalized
+    if the operating system requires it.
+    If you don't want this, use fnmatchcase(FILENAME, PATTERN).
+    """
+
+    name = name.lower()
+    pat = pat.lower()
+    return fnmatchcase(name, pat)
+
+
+def fnmatchcase(name, pat):
+    """Test whether FILENAME matches PATTERN, including case.
+    This is a version of fnmatch() which doesn't case-normalize
+    its arguments.
+    """
+
+    try:
+        re_pat = _cache[pat]
+    except KeyError:
+        res = translate(pat)
+        if len(_cache) >= _MAXCACHE:
+            _cache.clear()
+        _cache[pat] = re_pat = re.compile(res)
+    return re_pat.match(name) is not None
+
+
+def translate(pat):
+    """Translate a shell PATTERN to a regular expression.
+
+    There is no way to quote meta-characters.
+    """
+    i, n = 0, len(pat)
+    res = '^'
+    while i < n:
+        c = pat[i]
+        i = i + 1
+        if c == '*':
+            if i < n and pat[i] == '*':
+                # is some flavor of "**"
+                i = i + 1
+                # Treat **/ as ** so eat the "/"
+                if i < n and pat[i] == '/':
+                    i = i + 1
+                if i >= n:
+                    # is "**EOF" - to align with .gitignore just accept all
+                    res = res + '.*'
+                else:
+                    # is "**"
+                    # Note that this allows for any # of /'s (even 0) because
+                    # the .* will eat everything, even /'s
+                    res = res + '(.*/)?'
+            else:
+                # is "*" so map it to anything but "/"
+                res = res + '[^/]*'
+        elif c == '?':
+            # "?" is any char except "/"
+            res = res + '[^/]'
+        elif c == '[':
+            j = i
+            if j < n and pat[j] == '!':
+                j = j + 1
+            if j < n and pat[j] == ']':
+                j = j + 1
+            while j < n and pat[j] != ']':
+                j = j + 1
+            if j >= n:
+                res = res + '\\['
+            else:
+                stuff = pat[i:j].replace('\\', '\\\\')
+                i = j + 1
+                if stuff[0] == '!':
+                    stuff = '^' + stuff[1:]
+                elif stuff[0] == '^':
+                    stuff = '\\' + stuff
+                res = '%s[%s]' % (res, stuff)
+        else:
+            res = res + re.escape(c)
+
+    return res + '$'

plugins/module_utils/_api/utils/json_stream.py

@@ -0,0 +1,88 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import json
+import json.decoder
+
+from ansible.module_utils.six import text_type
+
+from ..errors import StreamParseError
+
+
+json_decoder = json.JSONDecoder()
+
+
+def stream_as_text(stream):
+    """
+    Given a stream of bytes or text, if any of the items in the stream
+    are bytes convert them to text.
+    This function can be removed once we return text streams
+    instead of byte streams.
+    """
+    for data in stream:
+        if not isinstance(data, text_type):
+            data = data.decode('utf-8', 'replace')
+        yield data
+
+
+def json_splitter(buffer):
+    """Attempt to parse a json object from a buffer. If there is at least one
+    object, return it and the rest of the buffer, otherwise return None.
+    """
+    buffer = buffer.strip()
+    try:
+        obj, index = json_decoder.raw_decode(buffer)
+        rest = buffer[json.decoder.WHITESPACE.match(buffer, index).end():]
+        return obj, rest
+    except ValueError:
+        return None
+
+
+def json_stream(stream):
+    """Given a stream of text, return a stream of json objects.
+    This handles streams which are inconsistently buffered (some entries may
+    be newline delimited, and others are not).
+    """
+    return split_buffer(stream, json_splitter, json_decoder.decode)
+
+
+def line_splitter(buffer, separator=u'\n'):
+    index = buffer.find(text_type(separator))
+    if index == -1:
+        return None
+    return buffer[:index + 1], buffer[index + 1:]
+
+
+def split_buffer(stream, splitter=None, decoder=lambda a: a):
+    """Given a generator which yields strings and a splitter function,
+    joins all input, splits on the separator and yields each chunk.
+    Unlike string.split(), each chunk includes the trailing
+    separator, except for the last one if none was found on the end
+    of the input.
+    """
+    splitter = splitter or line_splitter
+    buffered = text_type('')
+
+    for data in stream_as_text(stream):
+        buffered += data
+        while True:
+            buffer_split = splitter(buffered)
+            if buffer_split is None:
+                break
+
+            item, buffered = buffer_split
+            yield item
+
+    if buffered:
+        try:
+            yield decoder(buffered)
+        except Exception as e:
+            raise StreamParseError(e)

plugins/module_utils/_api/utils/ports.py

@@ -0,0 +1,94 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import re
+
+PORT_SPEC = re.compile(
+    "^"  # Match full string
+    "("  # External part
+    r"(\[?(?P<host>[a-fA-F\d.:]+)\]?:)?"  # Address
+    r"(?P<ext>[\d]*)(-(?P<ext_end>[\d]+))?:"  # External range
+    ")?"
+    r"(?P<int>[\d]+)(-(?P<int_end>[\d]+))?"  # Internal range
+    "(?P<proto>/(udp|tcp|sctp))?"  # Protocol
+    "$"  # Match full string
+)
+
+
+def add_port_mapping(port_bindings, internal_port, external):
+    if internal_port in port_bindings:
+        port_bindings[internal_port].append(external)
+    else:
+        port_bindings[internal_port] = [external]
+
+
+def add_port(port_bindings, internal_port_range, external_range):
+    if external_range is None:
+        for internal_port in internal_port_range:
+            add_port_mapping(port_bindings, internal_port, None)
+    else:
+        ports = zip(internal_port_range, external_range)
+        for internal_port, external_port in ports:
+            add_port_mapping(port_bindings, internal_port, external_port)
+
+
+def build_port_bindings(ports):
+    port_bindings = {}
+    for port in ports:
+        internal_port_range, external_range = split_port(port)
+        add_port(port_bindings, internal_port_range, external_range)
+    return port_bindings
+
+
+def _raise_invalid_port(port):
+    raise ValueError('Invalid port "%s", should be '
+                     '[[remote_ip:]remote_port[-remote_port]:]'
+                     'port[/protocol]' % port)
+
+
+def port_range(start, end, proto, randomly_available_port=False):
+    if not start:
+        return start
+    if not end:
+        return [start + proto]
+    if randomly_available_port:
+        return ['{0}-{1}'.format(start, end) + proto]
+    return [str(port) + proto for port in range(int(start), int(end) + 1)]
+
+
+def split_port(port):
+    if hasattr(port, 'legacy_repr'):
+        # This is the worst hack, but it prevents a bug in Compose 1.14.0
+        # https://github.com/docker/docker-py/issues/1668
+        # TODO: remove once fixed in Compose stable
+        port = port.legacy_repr()
+    port = str(port)
+    match = PORT_SPEC.match(port)
+    if match is None:
+        _raise_invalid_port(port)
+    parts = match.groupdict()
+
+    host = parts['host']
+    proto = parts['proto'] or ''
+    internal = port_range(parts['int'], parts['int_end'], proto)
+    external = port_range(
+        parts['ext'], parts['ext_end'], '', len(internal) == 1)
+
+    if host is None:
+        if external is not None and len(internal) != len(external):
+            raise ValueError('Port ranges don\'t match in length')
+        return internal, external
+    else:
+        if not external:
+            external = [None] * len(internal)
+        elif len(internal) != len(external):
+            raise ValueError('Port ranges don\'t match in length')
+        return internal, [(host, ext_port) for ext_port in external]

plugins/module_utils/_api/utils/proxy.py

@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+from .utils import format_environment
+
+
+class ProxyConfig(dict):
+    '''
+    Hold the client's proxy configuration
+    '''
+    @property
+    def http(self):
+        return self.get('http')
+
+    @property
+    def https(self):
+        return self.get('https')
+
+    @property
+    def ftp(self):
+        return self.get('ftp')
+
+    @property
+    def no_proxy(self):
+        return self.get('no_proxy')
+
+    @staticmethod
+    def from_dict(config):
+        '''
+        Instantiate a new ProxyConfig from a dictionary that represents a
+        client configuration, as described in `the documentation`_.
+
+        .. _the documentation:
+            https://docs.docker.com/network/proxy/#configure-the-docker-client
+        '''
+        return ProxyConfig(
+            http=config.get('httpProxy'),
+            https=config.get('httpsProxy'),
+            ftp=config.get('ftpProxy'),
+            no_proxy=config.get('noProxy'),
+        )
+
+    def get_environment(self):
+        '''
+        Return a dictionary representing the environment variables used to
+        set the proxy settings.
+        '''
+        env = {}
+        if self.http:
+            env['http_proxy'] = env['HTTP_PROXY'] = self.http
+        if self.https:
+            env['https_proxy'] = env['HTTPS_PROXY'] = self.https
+        if self.ftp:
+            env['ftp_proxy'] = env['FTP_PROXY'] = self.ftp
+        if self.no_proxy:
+            env['no_proxy'] = env['NO_PROXY'] = self.no_proxy
+        return env
+
+    def inject_proxy_environment(self, environment):
+        '''
+        Given a list of strings representing environment variables, prepend the
+        environment variables corresponding to the proxy settings.
+        '''
+        if not self:
+            return environment
+
+        proxy_env = format_environment(self.get_environment())
+        if not environment:
+            return proxy_env
+        # It is important to prepend our variables, because we want the
+        # variables defined in "environment" to take precedence.
+        return proxy_env + environment
+
+    def __str__(self):
+        return 'ProxyConfig(http={0}, https={1}, ftp={2}, no_proxy={3})'.format(
+            self.http, self.https, self.ftp, self.no_proxy)

plugins/module_utils/_api/utils/socket.py

@@ -0,0 +1,178 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import errno
+import os
+import select
+import socket as pysocket
+import struct
+
+from ansible.module_utils.six import PY3, binary_type
+
+from ..transport.npipesocket import NpipeSocket
+
+
+STDOUT = 1
+STDERR = 2
+
+
+class SocketError(Exception):
+    pass
+
+
+def read(socket, n=4096):
+    """
+    Reads at most n bytes from socket
+    """
+
+    recoverable_errors = (errno.EINTR, errno.EDEADLK, errno.EWOULDBLOCK)
+
+    if PY3 and not isinstance(socket, NpipeSocket):
+        select.select([socket], [], [])
+
+    try:
+        if hasattr(socket, 'recv'):
+            return socket.recv(n)
+        if PY3 and isinstance(socket, getattr(pysocket, 'SocketIO')):
+            return socket.read(n)
+        return os.read(socket.fileno(), n)
+    except EnvironmentError as e:
+        if e.errno not in recoverable_errors:
+            raise
+
+
+def read_exactly(socket, n):
+    """
+    Reads exactly n bytes from socket
+    Raises SocketError if there isn't enough data
+    """
+    data = binary_type()
+    while len(data) < n:
+        next_data = read(socket, n - len(data))
+        if not next_data:
+            raise SocketError("Unexpected EOF")
+        data += next_data
+    return data
+
+
+def next_frame_header(socket):
+    """
+    Returns the stream and size of the next frame of data waiting to be read
+    from socket, according to the protocol defined here:
+
+    https://docs.docker.com/engine/api/v1.24/#attach-to-a-container
+    """
+    try:
+        data = read_exactly(socket, 8)
+    except SocketError:
+        return (-1, -1)
+
+    stream, actual = struct.unpack('>BxxxL', data)
+    return (stream, actual)
+
+
+def frames_iter(socket, tty):
+    """
+    Return a generator of frames read from socket. A frame is a tuple where
+    the first item is the stream number and the second item is a chunk of data.
+
+    If the tty setting is enabled, the streams are multiplexed into the stdout
+    stream.
+    """
+    if tty:
+        return ((STDOUT, frame) for frame in frames_iter_tty(socket))
+    else:
+        return frames_iter_no_tty(socket)
+
+
+def frames_iter_no_tty(socket):
+    """
+    Returns a generator of data read from the socket when the tty setting is
+    not enabled.
+    """
+    while True:
+        (stream, n) = next_frame_header(socket)
+        if n < 0:
+            break
+        while n > 0:
+            result = read(socket, n)
+            if result is None:
+                continue
+            data_length = len(result)
+            if data_length == 0:
+                # We have reached EOF
+                return
+            n -= data_length
+            yield (stream, result)
+
+
+def frames_iter_tty(socket):
+    """
+    Return a generator of data read from the socket when the tty setting is
+    enabled.
+    """
+    while True:
+        result = read(socket)
+        if len(result) == 0:
+            # We have reached EOF
+            return
+        yield result
+
+
+def consume_socket_output(frames, demux=False):
+    """
+    Iterate through frames read from the socket and return the result.
+
+    Args:
+
+        demux (bool):
+            If False, stdout and stderr are multiplexed, and the result is the
+            concatenation of all the frames. If True, the streams are
+            demultiplexed, and the result is a 2-tuple where each item is the
+            concatenation of frames belonging to the same stream.
+    """
+    if demux is False:
+        # If the streams are multiplexed, the generator returns strings, that
+        # we just need to concatenate.
+        return binary_type().join(frames)
+
+    # If the streams are demultiplexed, the generator yields tuples
+    # (stdout, stderr)
+    out = [None, None]
+    for frame in frames:
+        # It is guaranteed that for each frame, one and only one stream
+        # is not None.
+        if frame == (None, None):
+            raise AssertionError('frame must be (None, None), but got %s' % (frame, ))
+        if frame[0] is not None:
+            if out[0] is None:
+                out[0] = frame[0]
+            else:
+                out[0] += frame[0]
+        else:
+            if out[1] is None:
+                out[1] = frame[1]
+            else:
+                out[1] += frame[1]
+    return tuple(out)
+
+
+def demux_adaptor(stream_id, data):
+    """
+    Utility to demultiplex stdout and stderr when reading frames from the
+    socket.
+    """
+    if stream_id == STDOUT:
+        return (data, None)
+    elif stream_id == STDERR:
+        return (None, data)
+    else:
+        raise ValueError('{0} is not a valid stream'.format(stream_id))

plugins/module_utils/_api/utils/utils.py

@@ -0,0 +1,514 @@
+# -*- coding: utf-8 -*-
+# This code is part of the Ansible collection community.docker, but is an independent component.
+# This particular file, and this file only, is based on the Docker SDK for Python (https://github.com/docker/docker-py/)
+#
+# Copyright (c) 2016-2022 Docker, Inc.
+#
+# It is licensed under the Apache 2.0 license (see Apache-2.0.txt in this collection)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import base64
+import json
+import os
+import os.path
+import shlex
+import string
+from datetime import datetime
+from ansible_collections.community.docker.plugins.module_utils.version import StrictVersion
+
+from ansible.module_utils.six import PY2, PY3, binary_type, integer_types, iteritems, string_types, text_type
+
+from .. import errors
+from .. import tls
+from ..constants import DEFAULT_HTTP_HOST
+from ..constants import DEFAULT_UNIX_SOCKET
+from ..constants import DEFAULT_NPIPE
+from ..constants import BYTE_UNITS
+
+if PY2:
+    from urllib import splitnport
+    from urlparse import urlparse
+else:
+    from urllib.parse import splitnport, urlparse
+
+
+def create_ipam_pool(*args, **kwargs):
+    raise errors.DeprecatedMethod(
+        'utils.create_ipam_pool has been removed. Please use a '
+        'docker.types.IPAMPool object instead.'
+    )
+
+
+def create_ipam_config(*args, **kwargs):
+    raise errors.DeprecatedMethod(
+        'utils.create_ipam_config has been removed. Please use a '
+        'docker.types.IPAMConfig object instead.'
+    )
+
+
+def decode_json_header(header):
+    data = base64.b64decode(header)
+    if PY3:
+        data = data.decode('utf-8')
+    return json.loads(data)
+
+
+def compare_version(v1, v2):
+    """Compare docker versions
+
+    >>> v1 = '1.9'
+    >>> v2 = '1.10'
+    >>> compare_version(v1, v2)
+    1
+    >>> compare_version(v2, v1)
+    -1
+    >>> compare_version(v2, v2)
+    0
+    """
+    s1 = StrictVersion(v1)
+    s2 = StrictVersion(v2)
+    if s1 == s2:
+        return 0
+    elif s1 > s2:
+        return -1
+    else:
+        return 1
+
+
+def version_lt(v1, v2):
+    return compare_version(v1, v2) > 0
+
+
+def version_gte(v1, v2):
+    return not version_lt(v1, v2)
+
+
+def _convert_port_binding(binding):
+    result = {'HostIp': '', 'HostPort': ''}
+    if isinstance(binding, tuple):
+        if len(binding) == 2:
+            result['HostPort'] = binding[1]
+            result['HostIp'] = binding[0]
+        elif isinstance(binding[0], string_types):
+            result['HostIp'] = binding[0]
+        else:
+            result['HostPort'] = binding[0]
+    elif isinstance(binding, dict):
+        if 'HostPort' in binding:
+            result['HostPort'] = binding['HostPort']
+            if 'HostIp' in binding:
+                result['HostIp'] = binding['HostIp']
+        else:
+            raise ValueError(binding)
+    else:
+        result['HostPort'] = binding
+
+    if result['HostPort'] is None:
+        result['HostPort'] = ''
+    else:
+        result['HostPort'] = str(result['HostPort'])
+
+    return result
+
+
+def convert_port_bindings(port_bindings):
+    result = {}
+    for k, v in iteritems(port_bindings):
+        key = str(k)
+        if '/' not in key:
+            key += '/tcp'
+        if isinstance(v, list):
+            result[key] = [_convert_port_binding(binding) for binding in v]
+        else:
+            result[key] = [_convert_port_binding(v)]
+    return result
+
+
+def convert_volume_binds(binds):
+    if isinstance(binds, list):
+        return binds
+
+    result = []
+    for k, v in binds.items():
+        if isinstance(k, binary_type):
+            k = k.decode('utf-8')
+
+        if isinstance(v, dict):
+            if 'ro' in v and 'mode' in v:
+                raise ValueError(
+                    'Binding cannot contain both "ro" and "mode": {0}'
+                    .format(repr(v))
+                )
+
+            bind = v['bind']
+            if isinstance(bind, binary_type):
+                bind = bind.decode('utf-8')
+
+            if 'ro' in v:
+                mode = 'ro' if v['ro'] else 'rw'
+            elif 'mode' in v:
+                mode = v['mode']
+            else:
+                mode = 'rw'
+
+            result.append(
+                text_type('{0}:{1}:{2}').format(k, bind, mode)
+            )
+        else:
+            if isinstance(v, binary_type):
+                v = v.decode('utf-8')
+            result.append(
+                text_type('{0}:{1}:rw').format(k, v)
+            )
+    return result
+
+
+def convert_tmpfs_mounts(tmpfs):
+    if isinstance(tmpfs, dict):
+        return tmpfs
+
+    if not isinstance(tmpfs, list):
+        raise ValueError(
+            'Expected tmpfs value to be either a list or a dict, found: {0}'
+            .format(type(tmpfs).__name__)
+        )
+
+    result = {}
+    for mount in tmpfs:
+        if isinstance(mount, string_types):
+            if ":" in mount:
+                name, options = mount.split(":", 1)
+            else:
+                name = mount
+                options = ""
+
+        else:
+            raise ValueError(
+                "Expected item in tmpfs list to be a string, found: {0}"
+                .format(type(mount).__name__)
+            )
+
+        result[name] = options
+    return result
+
+
+def convert_service_networks(networks):
+    if not networks:
+        return networks
+    if not isinstance(networks, list):
+        raise TypeError('networks parameter must be a list.')
+
+    result = []
+    for n in networks:
+        if isinstance(n, string_types):
+            n = {'Target': n}
+        result.append(n)
+    return result
+
+
+def parse_repository_tag(repo_name):
+    parts = repo_name.rsplit('@', 1)
+    if len(parts) == 2:
+        return tuple(parts)
+    parts = repo_name.rsplit(':', 1)
+    if len(parts) == 2 and '/' not in parts[1]:
+        return tuple(parts)
+    return repo_name, None
+
+
+def parse_host(addr, is_win32=False, tls=False):
+    path = ''
+    port = None
+    host = None
+
+    # Sensible defaults
+    if not addr and is_win32:
+        return DEFAULT_NPIPE
+    if not addr or addr.strip() == 'unix://':
+        return DEFAULT_UNIX_SOCKET
+
+    addr = addr.strip()
+
+    parsed_url = urlparse(addr)
+    proto = parsed_url.scheme
+    if not proto or any(x not in string.ascii_letters + '+' for x in proto):
+        # https://bugs.python.org/issue754016
+        parsed_url = urlparse('//' + addr, 'tcp')
+        proto = 'tcp'
+
+    if proto == 'fd':
+        raise errors.DockerException('fd protocol is not implemented')
+
+    # These protos are valid aliases for our library but not for the
+    # official spec
+    if proto == 'http' or proto == 'https':
+        tls = proto == 'https'
+        proto = 'tcp'
+    elif proto == 'http+unix':
+        proto = 'unix'
+
+    if proto not in ('tcp', 'unix', 'npipe', 'ssh'):
+        raise errors.DockerException(
+            "Invalid bind address protocol: {0}".format(addr)
+        )
+
+    if proto == 'tcp' and not parsed_url.netloc:
+        # "tcp://" is exceptionally disallowed by convention;
+        # omitting a hostname for other protocols is fine
+        raise errors.DockerException(
+            'Invalid bind address format: {0}'.format(addr)
+        )
+
+    if any([
+        parsed_url.params, parsed_url.query, parsed_url.fragment,
+        parsed_url.password
+    ]):
+        raise errors.DockerException(
+            'Invalid bind address format: {0}'.format(addr)
+        )
+
+    if parsed_url.path and proto == 'ssh':
+        raise errors.DockerException(
+            'Invalid bind address format: no path allowed for this protocol:'
+            ' {0}'.format(addr)
+        )
+    else:
+        path = parsed_url.path
+        if proto == 'unix' and parsed_url.hostname is not None:
+            # For legacy reasons, we consider unix://path
+            # to be valid and equivalent to unix:///path
+            path = '/'.join((parsed_url.hostname, path))
+
+    if proto in ('tcp', 'ssh'):
+        # parsed_url.hostname strips brackets from IPv6 addresses,
+        # which can be problematic hence our use of splitnport() instead.
+        host, port = splitnport(parsed_url.netloc)
+        if port is None or port < 0:
+            if proto != 'ssh':
+                raise errors.DockerException(
+                    'Invalid bind address format: port is required:'
+                    ' {0}'.format(addr)
+                )
+            port = 22
+
+        if not host:
+            host = DEFAULT_HTTP_HOST
+
+    # Rewrite schemes to fit library internals (requests adapters)
+    if proto == 'tcp':
+        proto = 'http{0}'.format('s' if tls else '')
+    elif proto == 'unix':
+        proto = 'http+unix'
+
+    if proto in ('http+unix', 'npipe'):
+        return "{0}://{1}".format(proto, path).rstrip('/')
+    return '{0}://{1}:{2}{3}'.format(proto, host, port, path).rstrip('/')
+
+
+def parse_devices(devices):
+    device_list = []
+    for device in devices:
+        if isinstance(device, dict):
+            device_list.append(device)
+            continue
+        if not isinstance(device, string_types):
+            raise errors.DockerException(
+                'Invalid device type {0}'.format(type(device))
+            )
+        device_mapping = device.split(':')
+        if device_mapping:
+            path_on_host = device_mapping[0]
+            if len(device_mapping) > 1:
+                path_in_container = device_mapping[1]
+            else:
+                path_in_container = path_on_host
+            if len(device_mapping) > 2:
+                permissions = device_mapping[2]
+            else:
+                permissions = 'rwm'
+            device_list.append({
+                'PathOnHost': path_on_host,
+                'PathInContainer': path_in_container,
+                'CgroupPermissions': permissions
+            })
+    return device_list
+
+
+def kwargs_from_env(ssl_version=None, assert_hostname=None, environment=None):
+    if not environment:
+        environment = os.environ
+    host = environment.get('DOCKER_HOST')
+
+    # empty string for cert path is the same as unset.
+    cert_path = environment.get('DOCKER_CERT_PATH') or None
+
+    # empty string for tls verify counts as "false".
+    # Any value or 'unset' counts as true.
+    tls_verify = environment.get('DOCKER_TLS_VERIFY')
+    if tls_verify == '':
+        tls_verify = False
+    else:
+        tls_verify = tls_verify is not None
+    enable_tls = cert_path or tls_verify
+
+    params = {}
+
+    if host:
+        params['base_url'] = host
+
+    if not enable_tls:
+        return params
+
+    if not cert_path:
+        cert_path = os.path.join(os.path.expanduser('~'), '.docker')
+
+    if not tls_verify and assert_hostname is None:
+        # assert_hostname is a subset of TLS verification,
+        # so if it's not set already then set it to false.
+        assert_hostname = False
+
+    params['tls'] = tls.TLSConfig(
+        client_cert=(os.path.join(cert_path, 'cert.pem'),
+                     os.path.join(cert_path, 'key.pem')),
+        ca_cert=os.path.join(cert_path, 'ca.pem'),
+        verify=tls_verify,
+        ssl_version=ssl_version,
+        assert_hostname=assert_hostname,
+    )
+
+    return params
+
+
+def convert_filters(filters):
+    result = {}
+    for k, v in iteritems(filters):
+        if isinstance(v, bool):
+            v = 'true' if v else 'false'
+        if not isinstance(v, list):
+            v = [v, ]
+        result[k] = [
+            str(item) if not isinstance(item, string_types) else item
+            for item in v
+        ]
+    return json.dumps(result)
+
+
+def datetime_to_timestamp(dt):
+    """Convert a UTC datetime to a Unix timestamp"""
+    delta = dt - datetime.utcfromtimestamp(0)
+    return delta.seconds + delta.days * 24 * 3600
+
+
+def parse_bytes(s):
+    if isinstance(s, integer_types + (float,)):
+        return s
+    if len(s) == 0:
+        return 0
+
+    if s[-2:-1].isalpha() and s[-1].isalpha():
+        if s[-1] == "b" or s[-1] == "B":
+            s = s[:-1]
+    units = BYTE_UNITS
+    suffix = s[-1].lower()
+
+    # Check if the variable is a string representation of an int
+    # without a units part. Assuming that the units are bytes.
+    if suffix.isdigit():
+        digits_part = s
+        suffix = 'b'
+    else:
+        digits_part = s[:-1]
+
+    if suffix in units.keys() or suffix.isdigit():
+        try:
+            digits = float(digits_part)
+        except ValueError:
+            raise errors.DockerException(
+                'Failed converting the string value for memory ({0}) to'
+                ' an integer.'.format(digits_part)
+            )
+
+        # Reconvert to long for the final result
+        s = int(digits * units[suffix])
+    else:
+        raise errors.DockerException(
+            'The specified value for memory ({0}) should specify the'
+            ' units. The postfix should be one of the `b` `k` `m` `g`'
+            ' characters'.format(s)
+        )
+
+    return s
+
+
+def normalize_links(links):
+    if isinstance(links, dict):
+        links = iteritems(links)
+
+    return ['{0}:{1}'.format(k, v) if v else k for k, v in sorted(links)]
+
+
+def parse_env_file(env_file):
+    """
+    Reads a line-separated environment file.
+    The format of each line should be "key=value".
+    """
+    environment = {}
+
+    with open(env_file, 'r') as f:
+        for line in f:
+
+            if line[0] == '#':
+                continue
+
+            line = line.strip()
+            if not line:
+                continue
+
+            parse_line = line.split('=', 1)
+            if len(parse_line) == 2:
+                k, v = parse_line
+                environment[k] = v
+            else:
+                raise errors.DockerException(
+                    'Invalid line in environment file {0}:\n{1}'.format(
+                        env_file, line))
+
+    return environment
+
+
+def split_command(command):
+    if PY2 and not isinstance(command, binary_type):
+        command = command.encode('utf-8')
+    return shlex.split(command)
+
+
+def format_environment(environment):
+    def format_env(key, value):
+        if value is None:
+            return key
+        if isinstance(value, binary_type):
+            value = value.decode('utf-8')
+
+        return u'{key}={value}'.format(key=key, value=value)
+    return [format_env(*var) for var in iteritems(environment)]
+
+
+def format_extra_hosts(extra_hosts, task=False):
+    # Use format dictated by Swarm API if container is part of a task
+    if task:
+        return [
+            '{0} {1}'.format(v, k) for k, v in sorted(iteritems(extra_hosts))
+        ]
+
+    return [
+        '{0}:{1}'.format(k, v) for k, v in sorted(iteritems(extra_hosts))
+    ]
+
+
+def create_host_config(self, *args, **kwargs):
+    raise errors.DeprecatedMethod(
+        'utils.create_host_config has been removed. Please use a '
+        'docker.types.HostConfig object instead.'
+    )