Add SSH transport (#32)

Signed-off-by: Jesse Gorzinski <jgorzinski@gmail.com>

Author: ThePrez

docs/api.rst

@@ -73,6 +73,13 @@ Database Transport
    :members:
    :inherited-members:
 
+SSH Transport
+~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: SshTransport
+   :members:
+   :inherited-members:
+
 
 Direct Memory Transport
 ~~~~~~~~~~~~~~~~~~~~~~~

samples/config.py.sample

@@ -25,6 +25,13 @@ Transports:
   3) XMLSERVICE http/rest/web call (Apache job)
   from itoolkit.transport import HttpTransport
   itransport = HttpTransport(url, user, password)
+
+  4) XMLService ssh call
+  import paramiko
+  ssh = paramiko.SSHClient()
+  ssh.set_missing_host_key_policy(paramiko.WarningPolicy())
+  ssh.connect("hostname", username="username", password="password")
+  itransport = SshTransport(ssh)
 """
 from itoolkit.transport import DirectTransport
 itransport = DirectTransport()

src/itoolkit/README

@@ -29,6 +29,7 @@ Transport classes:
   class DirectTransport:      Transport XMLSERVICE direct job call (within job/process calls).
   class DatabaseTransport:    Transport XMLSERVICE calls over database connection.
   class HttpTransport:        Transport XMLSERVICE calls over standard HTTP rest.
+  class SshTransport:         Transport XMLSERVICE calls over SSH.
 
 XMLSERVICE classes:
   Base:

src/itoolkit/transport/__init__.py

@@ -3,10 +3,12 @@
 from .database import DatabaseTransport
 from .direct import DirectTransport
 from .http import HttpTransport
+from .ssh import SshTransport
 
 __all__ = [
     'XmlServiceTransport',
     'DatabaseTransport',
     'DirectTransport',
     'HttpTransport',
+    'SshTransport',
 ]

src/itoolkit/transport/ssh.py

@@ -0,0 +1,95 @@
+# -*- coding: utf-8 -*-
+"""
+XMLSERVICE ssh call (ssh job, often in QUSRWRK)
+
+License:
+  BSD (LICENSE)
+  -- or --
+  http://yips.idevcloud.com/wiki/index.php/XMLService/LicenseXMLService
+
+Example:
+    from itoolkit.transport import SshTransport
+    import paramiko
+    ssh = paramiko.SSHClient()
+    # configure paramiko. Using only WarningPolicy() is not secure
+    ssh.set_missing_host_key_policy(paramiko.WarningPolicy())
+    ssh.connect(host, username="linux", password="linux1")
+    itransport = SshTransport(ssh)
+
+Notes:
+    1) Always uses XMLSERVICE shipped in the QXMLSERV library
+    2) does not disconnect the given SSHClient object when finished
+
+"""
+from .base import XmlServiceTransport
+
+__all__ = [
+    'SshTransport'
+]
+
+
+class SshTransport(XmlServiceTransport):
+    """
+    Transport XMLSERVICE calls over SSH connection.
+
+    Args:
+        sshclient (paramiko.SSHClient): connected and authenticated connection
+
+    Example:
+        from itoolkit.transport import SshTransport
+        import paramiko
+        ssh = paramiko.SSHClient()
+        # configure paramiko. Using only WarningPolicy() is not secure
+        ssh.set_missing_host_key_policy(paramiko.WarningPolicy())
+        ssh.connect(host, username="linux", password="linux1")
+        itransport = SshTransport(ssh)
+
+    Returns:
+       (obj)
+    """
+
+    def __init__(self, sshclient=None):
+        # TODO: allow connection to be materialized from IBM Cloud deployments
+        if not hasattr(sshclient, "exec_command"):
+            raise Exception("An instance of paramiko.SSHClient is required")
+        self.conn = sshclient
+
+    def call(self, tk):
+        """Call xmlservice with accumulated input XML.
+
+        Args:
+            tk  - iToolkit object
+
+        Returns:
+            xml
+        """
+        command = "/QOpenSys/pkgs/bin/xmlservice-cli"
+        stdin, stdout, stderr = self.conn.exec_command(command)
+        xml_in = tk.xml_in()
+        stdin.write(xml_in.encode())
+        stdin.flush()
+        stdin.channel.shutdown_write()
+
+        # rather than doing all this loop-de-loop, we could instead just use
+        # a single call to stdout.readlines(), but there is a remote
+        # possibility that the process is hanging writing to a filled-up
+        # stderr pipe. So, we read a little from both until we're all done
+        err_out = b""
+        xml_out = b""
+        blockSize = 64  # arbitrary
+        while not stderr.closed or not stdout.closed:
+            if not stderr.closed:
+                newData = stderr.read(blockSize)
+            if not newData:
+                stderr.close()  # reaching EOF doesn't implicitly close
+            else:
+                err_out += newData
+            if not stdout.closed:
+                newData = stdout.read(blockSize)
+            if not newData:
+                stdout.close()  # reaching EOF doesn't implicitly close
+            else:
+                xml_out += newData
+        stdout.channel.close()
+        stderr.channel.close()
+        return xml_out