[#606] attach server response message to exception as 'server_msg' attribute

Includes test with atomic_metadata.
Other APIs that could use this feature include:
  replica_truncate
  atomic_apply_acls

Author: d-w-moore

README.md

@@ -732,6 +732,30 @@ from an object:
 ...     Object.metadata.apply_atomic_operations( *[AVUOperation(operation='remove', avu=i) for i in avus_on_Object] )
 ```
 
+Extracting JSON encoded server information in case of error
+-----------------------------------------------------------
+
+Some server apis, including atomic metadata and replica truncation, can fail for various reasons and generate an
+exception.  In these cases the message object returned from the server is made available in the 'server_msg' attribute
+of the iRODSException object.
+
+This enables an approach like the following, which logs server information possibly underlying the error that was evoked:
+
+```python
+    try:
+        Object.metadata.apply_atomic_operations( ops )
+        # or:
+        DataObject.replica_truncate( size )
+    except iRODSException as exc:
+        log.error('Server API call failure. Traceback = %r ; iRODS Server info = %r',
+            traceback.extract_tb(sys.exc_info()[2]),
+            exc.server_msg.get_json_encoded_struct())
+```
+
+For `DataObject.replica_truncate(...)`, note that exc.server_msg.get_json_encoded_struct() can be used in the exception-handling
+code path to retrieve the same information that would have been routinely returned from the truncate call itself, had it actually
+completed without error.
+
 Special Characters
 ------------------
 

irods/connection.py

@@ -149,7 +149,9 @@ def recv(self, into_buffer = None
             except TypeError:
                 err_msg = None
             if nominal_code(msg.int_info) not in acceptable_codes:
-                raise get_exception_by_code(msg.int_info, err_msg)
+                exc = get_exception_by_code(msg.int_info, err_msg)
+                exc.server_msg = msg
+                raise exc
         return msg
 
     def recv_into(self, buffer, **options):

irods/message/__init__.py

@@ -265,6 +265,9 @@ class BinBytesBuf(Message):
 class JSON_Binary_Response(BinBytesBuf):
     pass
 
+class XMLMessageNotConvertibleToJSON(Exception):
+    pass
+
 class iRODSMessage(object):
 
     class ResponseNotParseable(Exception):
@@ -285,13 +288,35 @@ def __init__(self, msg_type=b'', msg=None, error=b'', bs=b'', int_info=0):
         self.int_info = int_info
 
     def get_json_encoded_struct (self):
+        """For messages having STR_PI and *BytesBuf_PI in the highest level XML tag.
+
+           Invoke this method to recover a (usually JSON-formatted) server message
+           returned by a server API.
+        """
         Xml = ET().fromstring(self.msg.replace(b'\0',b''))
-        json_str = Xml.find('buf').text
+
+        # Handle STR_PI case, which corresponds to server APIs with a 'char**' output parameter.
+        if Xml.tag == 'STR_PI':
+            STR_PI_element = Xml.find('myStr')
+            if STR_PI_element is not None:
+                return json.loads( STR_PI_element.text )
+
+        # Handle remaining cases, i.e. BinBytesBuf_PI and BytesBuf_PI.
+        json_str = getattr(Xml.find('buf'), 'text', None)
+        if json_str is None:
+            error_text = "Message does not have a suitable 'buf' tag from which to extract text or binary content."
+            raise XMLMessageNotConvertibleToJSON(error_text)
+
         if Xml.tag == 'BinBytesBuf_PI':
             mybin = JSON_Binary_Response()
             mybin.unpack(Xml)
             json_str = mybin.buf.replace(b'\0',b'').decode()
-        return json.loads( json_str )
+
+        if Xml.tag in ('BinBytesBuf_PI', 'BytesBuf_PI'):
+            return json.loads( json_str )
+
+        error_text = "Inappropriate top-level tag '{Xml.tag}' used in iRODSMessage.get_json_encoded_struct".format(**locals())
+        raise XMLMessageNotConvertibleToJSON(error_text)
 
     @staticmethod
     def recv(sock):

irods/test/meta_test.py

@@ -6,8 +6,9 @@
 import time
 import datetime
 import unittest
-from irods.meta import (iRODSMeta, AVUOperation, BadAVUOperationValue, BadAVUOperationKeyword)
+import irods.exception as ex
 from irods.manager.metadata_manager import InvalidAtomicAVURequest
+from irods.meta import (iRODSMeta, AVUOperation, BadAVUOperationValue, BadAVUOperationKeyword)
 from irods.models import (DataObject, Collection, Resource, CollectionMeta)
 import irods.test.helpers as helpers
 import irods.keywords as kw
@@ -119,7 +120,39 @@ def tearDown(self):
         helpers.remove_unused_metadata(self.sess)
         self.sess.cleanup()
 
-    from irods.test.helpers import create_simple_resc_hierarchy
+    from irods.test.helpers import (create_simple_resc, create_simple_resc_hierarchy)
+
+    def test_replica_truncate_json_error__issue_606(self):
+        path = self.coll_path + "/atomic_meta_issue_606"
+        obj = self.sess.data_objects.create(path)
+        with self.create_simple_resc('repl_trunc_test_resc__issue_606') as f:
+            try:
+                obj.replica_truncate(1,**{kw.RESC_NAME_KW:f})
+            except ex.iRODSException as e:
+                resp = e.server_msg.get_json_encoded_struct()
+                # Test that returned structure is a dict containing at least one item.
+                self.assertIsInstance(resp, dict)
+                self.assertTrue(resp)
+
+    def test_atomic_metadata_json_error__issue_606(self):
+        path = self.coll_path + "/atomic_meta_issue_606"
+        obj = self.sess.data_objects.create(path)
+        obj.unlink(force = True)
+        fail_message = ''
+        try:
+            obj.metadata.apply_atomic_operations(AVUOperation(operation="add", avu=iRODSMeta('a','b','c')))
+        except ex.iRODSException as e:
+            resp = e.server_msg.get_json_encoded_struct()
+            self.assertIn(
+                'Entity does not exist [entity_name={}]'.format(obj.path),
+                resp['error_message'])
+        except Exception as e:
+            fail_message = 'apply_atomic_operations on a nonexistent object raised an unexpected exception {e!r}'.format(**locals())
+        else:
+            fail_message = 'apply_atomic_operations on a nonexistent object did not raise an exception as expected.'
+
+        if fail_message:
+            self.fail(fail_message)
 
     def test_atomic_metadata_operations_244(self):
         user = self.sess.users.get("rods")