mantis-cli 22.3.0__tar.gz → 22.5.0__tar.gz

{mantis_cli-22.3.0/mantis_cli.egg-info → mantis_cli-22.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.1
 Name: mantis_cli
-Version: 22.3.0
+Version: 22.5.0
 Summary: Management command to build and deploy webapps, especially based on Django
 Home-page: https://github.com/PragmaticMates/mantis-cli
 Author: Erik Telepovský
@@ -9,6 +9,7 @@ Maintainer: Pragmatic Mates
 Maintainer-email: info@pragmaticmates.com
 License: GNU General Public License (GPL)
 Keywords: management deployment docker command
+Platform: UNKNOWN
 Classifier: Programming Language :: Python
 Classifier: Operating System :: OS Independent
 Classifier: Environment :: Web Environment
@@ -18,27 +19,6 @@ Classifier: License :: OSI Approved :: GNU General Public License (GPL)
 Classifier: Development Status :: 5 - Production/Stable
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: cffi
-Requires-Dist: click
-Requires-Dist: cryptography
-Requires-Dist: pycryptodome
-Requires-Dist: pydantic
-Requires-Dist: PyYAML
-Requires-Dist: rich
-Requires-Dist: typer
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: keywords
-Dynamic: license
-Dynamic: license-file
-Dynamic: maintainer
-Dynamic: maintainer-email
-Dynamic: requires-dist
-Dynamic: summary
 
 # mantis-cli
 
@@ -210,10 +190,39 @@ alone: `ssh -L` to a unix socket succeeds even when nothing listens on the far e
 tunnel only proves itself once the daemon has replied. Set `enabled` explicitly once
 `check-tunnel` (below) confirms a server, and that round-trip goes away.
 
-Requirements on the server: the connecting user must be able to read the docker socket
-(typically membership in the `docker` group), and `AllowStreamLocalForwarding` must not
-be disabled — it defaults to `yes`. Whenever the tunnel cannot be used, mantis warns and
-falls back to a connection per docker command, so deployments keep working either way.
+Requirements on the server: it must be an OpenSSH server (see below), the connecting user
+must be able to read the docker socket (typically membership in the `docker` group), and
+`AllowStreamLocalForwarding` must not be disabled — it defaults to `yes`. Whenever the
+tunnel cannot be used, mantis warns and falls back to a connection per docker command, so
+deployments keep working either way.
+
+#### Servers that cannot forward a unix socket
+
+Forwarding one is `direct-streamlocal@openssh.com`, an OpenSSH extension, and SSH front-ends
+built on other implementations do not have it. [ssh2incus](https://ssh2incus.com), which
+routes connections into Incus instances by login name, rejects the channel outright:
+
+```
+channel 2: open failed: unknown channel type: unsupported channel type
+```
+
+No `remote_socket` helps there — the socket is never reached. What works instead is
+multiplexing the per-command connections, which needs no forward at all:
+
+```
+Host <server>
+    ControlMaster auto
+    ControlPath ~/.ssh/mantis-%r@%h:%p
+    ControlPersist 5m
+```
+
+Docker spawns a plain `ssh` per command and passes it no options of its own, so the ssh
+client reads this block by itself and every command reuses one connection. Measured against
+an ssh2incus server, that took a docker command from 0.29 s to 0.09 s. This is a weaker
+guarantee than the tunnel — sessions do count against sshd's `MaxSessions`, where forwarded
+channels do not — so on OpenSSH prefer the tunnel and keep multiplexing for the servers that
+cannot offer it. Set `"tunnel": {"enabled": false}` there, so no run pays for a probe that
+cannot succeed.
 
 The check ignores `tunnel.enabled`, so it answers "would this work" rather than "is this
 on" — use it before setting `enabled` to `true`:
@@ -611,3 +620,4 @@ Works as follows:
 ## Release notes
 
 Mantis uses semantic versioning. See more in [changelog](https://github.com/PragmaticMates/mantis-cli/blob/master/CHANGES.md).
+

{mantis_cli-22.3.0 → mantis_cli-22.5.0}/README.md

@@ -168,10 +168,39 @@ alone: `ssh -L` to a unix socket succeeds even when nothing listens on the far e
 tunnel only proves itself once the daemon has replied. Set `enabled` explicitly once
 `check-tunnel` (below) confirms a server, and that round-trip goes away.
 
-Requirements on the server: the connecting user must be able to read the docker socket
-(typically membership in the `docker` group), and `AllowStreamLocalForwarding` must not
-be disabled — it defaults to `yes`. Whenever the tunnel cannot be used, mantis warns and
-falls back to a connection per docker command, so deployments keep working either way.
+Requirements on the server: it must be an OpenSSH server (see below), the connecting user
+must be able to read the docker socket (typically membership in the `docker` group), and
+`AllowStreamLocalForwarding` must not be disabled — it defaults to `yes`. Whenever the
+tunnel cannot be used, mantis warns and falls back to a connection per docker command, so
+deployments keep working either way.
+
+#### Servers that cannot forward a unix socket
+
+Forwarding one is `direct-streamlocal@openssh.com`, an OpenSSH extension, and SSH front-ends
+built on other implementations do not have it. [ssh2incus](https://ssh2incus.com), which
+routes connections into Incus instances by login name, rejects the channel outright:
+
+```
+channel 2: open failed: unknown channel type: unsupported channel type
+```
+
+No `remote_socket` helps there — the socket is never reached. What works instead is
+multiplexing the per-command connections, which needs no forward at all:
+
+```
+Host <server>
+    ControlMaster auto
+    ControlPath ~/.ssh/mantis-%r@%h:%p
+    ControlPersist 5m
+```
+
+Docker spawns a plain `ssh` per command and passes it no options of its own, so the ssh
+client reads this block by itself and every command reuses one connection. Measured against
+an ssh2incus server, that took a docker command from 0.29 s to 0.09 s. This is a weaker
+guarantee than the tunnel — sessions do count against sshd's `MaxSessions`, where forwarded
+channels do not — so on OpenSSH prefer the tunnel and keep multiplexing for the servers that
+cannot offer it. Set `"tunnel": {"enabled": false}` there, so no run pays for a probe that
+cannot succeed.
 
 The check ignores `tunnel.enabled`, so it answers "would this work" rather than "is this
 on" — use it before setting `enabled` to `true`:

mantis_cli-22.5.0/mantis/__init__.py

@@ -0,0 +1 @@
+VERSION = '22.5.0'

{mantis_cli-22.3.0 → mantis_cli-22.5.0}/mantis/managers.py

@@ -136,6 +136,10 @@ class AbstractManager(object):
     def tunnel_config(self) -> Dict[str, Any]:
         return self.config.get('tunnel', {})
 
+    @property
+    def tunnel_remote_socket(self) -> str:
+        return self.tunnel_config.get('remote_socket', '/var/run/docker.sock')
+
     def ensure_tunnel(self) -> Optional[str]:
         """
         Returns path of a local unix socket forwarded to the remote docker socket,
@@ -187,8 +191,9 @@ class AbstractManager(object):
                     CLI.success(f'Tunnel is available (docker {version}). '
                                 f'Enable it in config to skip this check.')
                 else:
+                    reason, remedy = self.diagnose_tunnel()
                     CLI.warning(
-                        'Docker daemon did not answer through the SSH tunnel.\n'
+                        f'{reason}\n{remedy}\n'
                         'Falling back to a separate SSH connection per docker command.'
                     )
                     self.stop_tunnel()
@@ -212,7 +217,7 @@ class AbstractManager(object):
         Opens a single backgrounded SSH master forwarding the remote docker socket.
         Every docker command then reuses it instead of opening its own connection.
         """
-        remote_socket = self.tunnel_config.get('remote_socket', '/var/run/docker.sock')
+        remote_socket = self.tunnel_remote_socket
         ssh_options = self.tunnel_config.get('ssh_options', [])
 
         # unix socket paths are limited to ~104 characters, so prefer a shallow base
@@ -224,7 +229,9 @@ class AbstractManager(object):
         control_socket = str(Path(self._tunnel_dir) / 'ssh.ctl')
 
         command = [
-            'ssh', '-f', '-N', '-M',
+            # -v, because a channel the server refuses is only reported at verbose level,
+            # and the master writes to a file nobody reads unless something goes wrong
+            'ssh', '-f', '-N', '-M', '-v',
             '-S', control_socket,
             '-o', 'ExitOnForwardFailure=yes',
             '-o', 'ServerAliveInterval=30',
@@ -251,7 +258,7 @@ class AbstractManager(object):
 
         if result.returncode != 0:
             CLI.warning(
-                f'Failed to open SSH tunnel: {output_file.read_text().strip()}\n'
+                f'Failed to open SSH tunnel: {self.ssh_log_errors(output_file.read_text())}\n'
                 f'Falling back to a separate SSH connection per docker command.'
             )
             self.remove_tunnel_dir()
@@ -281,6 +288,62 @@ class AbstractManager(object):
             shutil.rmtree(self._tunnel_dir, ignore_errors=True)
             self._tunnel_dir = None
 
+    @staticmethod
+    def ssh_log_errors(log: str) -> str:
+        """Keeps the lines worth showing, dropping the debug chatter -v produces."""
+        return '\n'.join(line for line in log.splitlines() if not line.startswith('debug')).strip()
+
+    def read_tunnel_log(self) -> str:
+        """
+        Returns whatever the SSH master has written so far.
+
+        The master is backgrounded with -f and keeps writing to the same file long after it
+        exited successfully, so a channel it refuses later is only ever reported there.
+        """
+        if not self._tunnel_dir:
+            return ''
+
+        try:
+            return (Path(self._tunnel_dir) / 'ssh.log').read_text()
+        except OSError:
+            return ''
+
+    def diagnose_tunnel(self) -> Tuple[str, str]:
+        """
+        Explains why nothing answered through the forward, as (reason, remedy).
+
+        Opening the forward proves nothing: `ssh -L` to a unix socket succeeds even when the
+        far end is dead, so the reason only appears once a connection is made through it.
+        Reads the master's log, and therefore has to run before the tunnel is stopped.
+        """
+        log = self.read_tunnel_log()
+
+        if 'unknown channel type' in log:
+            return (
+                'The server refused to forward a unix socket: it does not implement '
+                'direct-streamlocal, so it is not an OpenSSH server. SSH front-ends such as '
+                'ssh2incus reject that channel outright, and no remote_socket can help.',
+                'Share one connection without a forward instead, by adding to ~/.ssh/config:\n'
+                f'    Host {self.host}\n'
+                '        ControlMaster auto\n'
+                '        ControlPath ~/.ssh/mantis-%r@%h:%p\n'
+                '        ControlPersist 5m\n'
+                'Every docker command then reuses that connection, and setting '
+                '"tunnel": {"enabled": false} skips this check from now on.',
+            )
+
+        if 'administratively prohibited' in log:
+            return (
+                'The server refused the forward.',
+                'Check "AllowStreamLocalForwarding" in its sshd_config. It defaults to "yes", '
+                'so it has been turned off.',
+            )
+
+        return (
+            f'The forward works, but the docker daemon did not answer on {self.tunnel_remote_socket}.',
+            f'Make sure user "{self.user}" can access it (usually by being in the "docker" group).',
+        )
+
     def check_tunnel(self) -> bool:
         """
         Verifies the SSH tunnel can be used for this connection, regardless of whether it
@@ -297,7 +360,7 @@ class AbstractManager(object):
         if not self.connection.startswith('ssh://'):
             CLI.error(f'Tunnel requires an ssh:// connection, but this one is "{self.connection}".')
 
-        remote_socket = self.tunnel_config.get('remote_socket', '/var/run/docker.sock')
+        remote_socket = self.tunnel_remote_socket
 
         if self.tunnel_config.get('enabled') is False:
             CLI.warning('Tunnel is disabled in config, checking anyway...')
@@ -317,12 +380,14 @@ class AbstractManager(object):
 
         version = self.probe_tunnel()
 
+        # the master's log goes away with the tunnel directory
+        reason, remedy = ('', '') if version else self.diagnose_tunnel()
+
         self.stop_tunnel()
 
         if not version:
             CLI.danger('Tunnel is NOT available.')
-            CLI.info(f'The forward works, but the docker daemon did not answer on {remote_socket}. '
-                     f'Make sure user "{self.user}" can access it (usually by being in the "docker" group).')
+            CLI.info(f'{reason}\n{remedy}')
             return False
 
         CLI.success(f'Tunnel is available (docker {version}).')
@@ -521,6 +586,16 @@ class AbstractManager(object):
         except OSError as e:
             CLI.error(f"{error_message}: {e}")
 
+    @property
+    def quiet_flag(self) -> str:
+        """
+        Layer progress is meant to be repainted in place, which needs a terminal. Redirected
+        to a log file or a CI pipe, docker prints every progress event on its own line
+        instead -- hundreds per image -- so ask for no progress at all when there is nobody
+        to watch it move. Errors and the final result are not progress and still print.
+        """
+        return '' if sys.stdout.isatty() else '--quiet'
+
     def build_docker_command(self, command: str, use_connection: bool = True) -> str:
         docker_connection = self.docker_connection if use_connection else ''
 
@@ -1229,7 +1304,7 @@ class BaseManager(AbstractManager):
         CLI.info(f'Services = {params}')
 
         # Push using docker compose
-        self.docker_compose(f'push {params}', use_connection=False)
+        self.docker_compose(f'push {self.quiet_flag} {params}', use_connection=False)
 
     def pull(self, services: Optional[List[str]] = None) -> None:
         """
@@ -1240,7 +1315,7 @@ class BaseManager(AbstractManager):
         CLI.info(f'Services = {params}')
 
         # Pull using docker compose
-        self.docker_compose(f'pull {params}')
+        self.docker_compose(f'pull {self.quiet_flag} {params}')
 
     def upload(self) -> None:
         """

{mantis_cli-22.3.0 → mantis_cli-22.5.0/mantis_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
-Name: mantis_cli
-Version: 22.3.0
+Metadata-Version: 2.1
+Name: mantis-cli
+Version: 22.5.0
 Summary: Management command to build and deploy webapps, especially based on Django
 Home-page: https://github.com/PragmaticMates/mantis-cli
 Author: Erik Telepovský
@@ -9,6 +9,7 @@ Maintainer: Pragmatic Mates
 Maintainer-email: info@pragmaticmates.com
 License: GNU General Public License (GPL)
 Keywords: management deployment docker command
+Platform: UNKNOWN
 Classifier: Programming Language :: Python
 Classifier: Operating System :: OS Independent
 Classifier: Environment :: Web Environment
@@ -18,27 +19,6 @@ Classifier: License :: OSI Approved :: GNU General Public License (GPL)
 Classifier: Development Status :: 5 - Production/Stable
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: cffi
-Requires-Dist: click
-Requires-Dist: cryptography
-Requires-Dist: pycryptodome
-Requires-Dist: pydantic
-Requires-Dist: PyYAML
-Requires-Dist: rich
-Requires-Dist: typer
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: keywords
-Dynamic: license
-Dynamic: license-file
-Dynamic: maintainer
-Dynamic: maintainer-email
-Dynamic: requires-dist
-Dynamic: summary
 
 # mantis-cli
 
@@ -210,10 +190,39 @@ alone: `ssh -L` to a unix socket succeeds even when nothing listens on the far e
 tunnel only proves itself once the daemon has replied. Set `enabled` explicitly once
 `check-tunnel` (below) confirms a server, and that round-trip goes away.
 
-Requirements on the server: the connecting user must be able to read the docker socket
-(typically membership in the `docker` group), and `AllowStreamLocalForwarding` must not
-be disabled — it defaults to `yes`. Whenever the tunnel cannot be used, mantis warns and
-falls back to a connection per docker command, so deployments keep working either way.
+Requirements on the server: it must be an OpenSSH server (see below), the connecting user
+must be able to read the docker socket (typically membership in the `docker` group), and
+`AllowStreamLocalForwarding` must not be disabled — it defaults to `yes`. Whenever the
+tunnel cannot be used, mantis warns and falls back to a connection per docker command, so
+deployments keep working either way.
+
+#### Servers that cannot forward a unix socket
+
+Forwarding one is `direct-streamlocal@openssh.com`, an OpenSSH extension, and SSH front-ends
+built on other implementations do not have it. [ssh2incus](https://ssh2incus.com), which
+routes connections into Incus instances by login name, rejects the channel outright:
+
+```
+channel 2: open failed: unknown channel type: unsupported channel type
+```
+
+No `remote_socket` helps there — the socket is never reached. What works instead is
+multiplexing the per-command connections, which needs no forward at all:
+
+```
+Host <server>
+    ControlMaster auto
+    ControlPath ~/.ssh/mantis-%r@%h:%p
+    ControlPersist 5m
+```
+
+Docker spawns a plain `ssh` per command and passes it no options of its own, so the ssh
+client reads this block by itself and every command reuses one connection. Measured against
+an ssh2incus server, that took a docker command from 0.29 s to 0.09 s. This is a weaker
+guarantee than the tunnel — sessions do count against sshd's `MaxSessions`, where forwarded
+channels do not — so on OpenSSH prefer the tunnel and keep multiplexing for the servers that
+cannot offer it. Set `"tunnel": {"enabled": false}` there, so no run pays for a probe that
+cannot succeed.
 
 The check ignores `tunnel.enabled`, so it answers "would this work" rather than "is this
 on" — use it before setting `enabled` to `true`:
@@ -611,3 +620,4 @@ Works as follows:
 ## Release notes
 
 Mantis uses semantic versioning. See more in [changelog](https://github.com/PragmaticMates/mantis-cli/blob/master/CHANGES.md).
+

{mantis_cli-22.3.0 → mantis_cli-22.5.0}/mantis_cli.egg-info/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
 mantis = mantis.command_line:run
+

{mantis_cli-22.3.0 → mantis_cli-22.5.0}/tests/test_managers.py

@@ -512,3 +512,38 @@ class TestResolveContainers:
         manager.get_containers = lambda *args, **kwargs: pytest.fail('containers listed again')
 
         assert manager.resolve_container('app', ['itfitness-app']) == 'itfitness-app'
+
+
+class TestQuietProgress:
+    """Layer progress is repainted in place, which only works on a terminal."""
+
+    @staticmethod
+    def _manager():
+        manager = BaseManager.__new__(BaseManager)
+        manager.commands = []
+        manager.docker_compose = lambda command, **kwargs: manager.commands.append(
+            ' '.join(command.split())
+        )
+        return manager
+
+    @patch('sys.stdout', new_callable=MagicMock)
+    def test_push_and_pull_are_quiet_off_a_terminal(self, mock_stdout):
+        """A log file or a CI pipe would otherwise get every progress event as its own line."""
+        mock_stdout.isatty.return_value = False
+        manager = self._manager()
+
+        manager.push()
+        manager.pull()
+
+        assert manager.commands == ['push --quiet', 'pull --quiet']
+
+    @patch('sys.stdout', new_callable=MagicMock)
+    def test_push_and_pull_keep_progress_on_a_terminal(self, mock_stdout):
+        """Interactively the progress is the point, so nothing changes."""
+        mock_stdout.isatty.return_value = True
+        manager = self._manager()
+
+        manager.push(['app'])
+        manager.pull(['app'])
+
+        assert manager.commands == ['push app', 'pull app']

{mantis_cli-22.3.0 → mantis_cli-22.5.0}/tests/test_tunnel.py

@@ -114,6 +114,8 @@ class TestTunnelEnabled:
         assert command[0] == 'ssh'
         # backgrounded master with a control socket we can close deterministically
         assert '-f' in command and '-N' in command and '-M' in command
+        # a refused channel is only reported at verbose level, and only in the log file
+        assert '-v' in command
         assert command[command.index('-S') + 1] == f'{ssh.dir}/ssh.ctl'
         # a refused forward must fail loudly instead of yielding a dead socket
         assert 'ExitOnForwardFailure=yes' in command
@@ -207,6 +209,17 @@ class TestTunnelAutoDetection:
 
         assert 'did not answer' in warning.call_args[0][0]
 
+    def test_fallback_says_why(self, ssh):
+        ssh.result.stdout = ''
+        ssh.result.output = 'channel 2: open failed: unknown channel type: unsupported channel type\n'
+        manager = _manager(tunnel={})
+
+        with patch('mantis.managers.CLI.warning') as warning:
+            manager.docker_connection
+
+        assert 'direct-streamlocal' in warning.call_args[0][0]
+        assert 'ControlMaster' in warning.call_args[0][0]
+
     def test_failed_detection_closes_the_tunnel(self, ssh):
         ssh.result.stdout = ''
         manager = _manager(tunnel={})
@@ -259,7 +272,7 @@ class TestTunnelAutoDetection:
 
 
 class TestCheckTunnel:
-    """check-tunnel tells apart a refused forward from a missing socket access."""
+    """check-tunnel tells apart the reasons a tunnel can be unusable."""
 
     def test_reports_available(self, ssh):
         ssh.result.stdout = '24.0.6\n'
@@ -311,6 +324,62 @@ class TestCheckTunnel:
         assert 'docker' in info.call_args[0][0]
         assert 'deploy' in info.call_args[0][0]
 
+    def test_debug_chatter_is_not_reported_to_the_user(self, ssh):
+        """The master runs with -v, so its log cannot be shown as it is."""
+        ssh.result.returncode = 255
+        ssh.result.output = (
+            'debug1: Connecting to example.com port 2222.\n'
+            'ssh: connect to host example.com port 2222: Connection refused\n'
+        )
+        manager = _manager(tunnel={'enabled': True})
+
+        with patch('mantis.managers.CLI.warning') as warning, patch('mantis.managers.CLI.danger'), \
+                patch('mantis.managers.CLI.info'):
+            manager.check_tunnel()
+
+        message = warning.call_args[0][0]
+
+        assert 'Connection refused' in message
+        assert 'debug1' not in message
+
+    def test_unsupported_channel_points_at_multiplexing(self, ssh):
+        """Not every SSH server is OpenSSH: some reject the forward channel outright."""
+        ssh.result.stdout = ''
+        ssh.result.output = 'channel 2: open failed: unknown channel type: unsupported channel type\n'
+        manager = _manager(tunnel={'enabled': True})
+
+        with patch('mantis.managers.CLI.danger'), patch('mantis.managers.CLI.info') as info:
+            assert manager.check_tunnel() is False
+
+        message = info.call_args[0][0]
+
+        # no remote_socket can fix this, so the advice must not be about the socket
+        assert 'direct-streamlocal' in message
+        assert 'ControlMaster' in message
+        assert 'docker' not in message.split('ControlMaster')[0]
+
+    def test_prohibited_forward_points_at_sshd_config(self, ssh):
+        ssh.result.stdout = ''
+        ssh.result.output = 'channel 2: open failed: administratively prohibited: open failed\n'
+        manager = _manager(tunnel={'enabled': True})
+
+        with patch('mantis.managers.CLI.danger'), patch('mantis.managers.CLI.info') as info:
+            assert manager.check_tunnel() is False
+
+        assert 'AllowStreamLocalForwarding' in info.call_args[0][0]
+
+    def test_reason_is_read_before_the_tunnel_is_removed(self, ssh):
+        """The log lives in the tunnel directory, which stop_tunnel deletes."""
+        ssh.result.stdout = ''
+        ssh.result.output = 'channel 2: open failed: unknown channel type: unsupported channel type\n'
+        manager = _manager(tunnel={'enabled': True})
+
+        with patch('mantis.managers.CLI.danger'), patch('mantis.managers.CLI.info') as info:
+            manager.check_tunnel()
+
+        assert not ssh.dir.exists()
+        assert 'direct-streamlocal' in info.call_args[0][0]
+
     def test_non_ssh_connection_is_an_error(self, ssh):
         manager = _manager(connection='context://production', tunnel={'enabled': True})
 

mantis_cli-22.3.0/mantis/__init__.py

@@ -1 +0,0 @@
-VERSION = '22.3.0'