Merge lp:~zyga/checkbox/fix-1378295 into lp:checkbox

[Zygmunt Krynicki]

This branch contains a fix for the referenced bug. I took the approach of modifying the result class
to require session_dir argument to reconstruct the IO log records from relative pathnames. Then I realized it's easier to keep the in-memory representation based on absolute pathnames and only save relative pathanmes. This gave birth to the fifth suspend/resume format.

All of the patches below build towards the solution.

71d0a69 plainbox:result: fix typo
b3f66e6 plainbox:suspend: refresh copyright
e612885 plainbox:suspend: fix PEP257 issues
fa597be plainbox:suspend: add session_dir argument to suspend()
97e3ccc plainbox:suspend: push session_dir to all helper methods
c7cfc96 plainbox:session: decouple helper class from tests
6420c49 plainbox:suspend: use a more convenient io_log_pathname
1a0879b plainbox:suspend: add 5th suspend format
f54312f plainbox:suspend: switch to 5th format by default
6d8e349 plainbox:manager: pass 2nd argument to suspend()
f17216a plainbox:resume: fix typo
62dc81b plainbox:resume: fix PEP-8 issue
1f4da26 plainbox:resume: make SessionResumeHelper.__init__() args mandatory
c25ea18 plainbox:resume: pass flags and location to _build_JobResult()
47a9850 plainbox:resume: make _build_JobResult(flags, location) mandatory
3a7c7bb plainbox:resume: better docstring for SessionResumeHelper.__init__()
b285ee9 plainbox:resume: better docstring for SessionResumeHelper1.__init__()
e5608b2 plainbox:resume: make SessionResumeHelper1.__init__(...) arguments mandatory
7e73a5a plainbox:resume: enable extra testing for 4th format
29a1c38 plainbox:resume: add SessionResumeHelper1._load_io_log_filename()
c855762 plainbox:resume: use absolute path for DiskJobResult resume test
d849000 plainbox:resume: add 5th resume helper
31ef1ce plainbox:resume: split tests for DiskJobResult 1-4 and 5
a1990f4 plainbox:resume: enable 5th resume helper

[Maciej Kisielewski (kissiel)]

LGTM
Big +1 for docstring upgrades.

review: Approve

=== modified file 'plainbox/plainbox/impl/result.py'
--- plainbox/plainbox/impl/result.py	2015-03-30 19:25:56 +0000
+++ plainbox/plainbox/impl/result.py	2015-04-13 18:23:59 +0000
@@ -73,7 +73,7 @@
 # Tuple representing meta-data associated with each possible value of "outcome"
 #
 # This tuple replaces various ad-hoc mapping that keyed off the outcome field
-# to compute something. Currently the following fields are suppoted:
+# to compute something. Currently the following fields are supported:
 #
 #   value - the actual constant like IJobResult.OUTCOME_NONE (for completeness)
 #

=== modified file 'plainbox/plainbox/impl/session/manager.py'
--- plainbox/plainbox/impl/session/manager.py	2015-02-25 23:54:36 +0000
+++ plainbox/plainbox/impl/session/manager.py	2015-04-13 18:23:59 +0000
@@ -355,7 +355,8 @@
         :meth:`SessionManager.load_session()`.
         """
         logger.debug("SessionManager.checkpoint()")
-        data = SessionSuspendHelper().suspend(self.state)
+        data = SessionSuspendHelper().suspend(
+            self.state, self.storage.location)
         logger.debug(
             ngettext(
                 "Saving %d byte of checkpoint data to %r",

=== modified file 'plainbox/plainbox/impl/session/resume.py'
--- plainbox/plainbox/impl/session/resume.py	2015-01-26 15:38:31 +0000
+++ plainbox/plainbox/impl/session/resume.py	2015-04-13 18:23:59 +0000
@@ -172,6 +172,8 @@
             return SessionPeekHelper3().peek_json(json_repr)
         elif version == 4:
             return SessionPeekHelper4().peek_json(json_repr)
+        elif version == 5:
+            return SessionPeekHelper5().peek_json(json_repr)
         else:
             raise IncompatibleSessionError(
                 _("Unsupported version {}").format(version))
@@ -186,9 +188,48 @@
     appropriate, format specific, resume class.
     """
 
-    def __init__(self, job_list, flags=None, location=None):
+    def __init__(
+        self, job_list: 'List[JobDefinition]',
+        flags: 'Optional[Iterable[str]]', location: 'Optional[str]'
+    ):
         """
-        Initialize the helper with a list of known jobs.
+        Initialize the helper with a list of known jobs and support data.
+
+        :param job_list:
+            List of known jobs
+        :param flags:
+            Any iterable object with string versions of resume support flags.
+            This can be None, if the application doesn't wish to enable any of
+            the feature flags.
+        :param location:
+            Location of the session directory. This is the same as
+            ``session_dir`` in the corresponding suspend API. It is also the
+            same as ``storage.location`` (where ``storage`` is a
+            :class:`plainbox.impl.session.storage.SessionStorage` object.
+
+        Applicable flags are ``FLAG_FILE_REFERENCE_CHECKS_S``,
+        ``FLAG_REWRITE_LOG_PATHNAMES_S`` and ``FLAG_IGNORE_JOB_CHECKSUMS_S``.
+        Their meaning is described below.
+
+        ``FLAG_FILE_REFERENCE_CHECKS_S``:
+            Flag controlling reference checks from within the session file to
+            external files. If enabled such checks are performed and can cause
+            additional exceptions to be raised. Currently this only affects the
+            representation of the DiskJobResult instances.
+
+        ``FLAG_REWRITE_LOG_PATHNAMES_S``:
+            Flag controlling rewriting of log file pathnames. It depends on the
+            location to be non-None and then rewrites pathnames of all them
+            missing log files to be relative to the session storage location.
+            It effectively depends on FLAG_FILE_REFERENCE_CHECKS_F being set at
+            the same time, otherwise it is ignored.
+
+        ``FLAG_IGNORE_JOB_CHECKSUMS_S``:
+            Flag controlling integrity checks between jobs present at resume
+            time and jobs present at suspend time. Since providers cannot be
+            serialized (nor should they) this integrity check prevents anyone
+            from resuming a session if job definitions have changed. Using this
+            flag effectively disables that check.
         """
         self.job_list = job_list
         logger.debug("Session Resume Helper started with jobs: %r", job_list)
@@ -254,6 +295,9 @@
         elif version == 4:
             helper = SessionResumeHelper4(
                 self.job_list, self.flags, self.location)
+        elif version == 5:
+            helper = SessionResumeHelper5(
+                self.job_list, self.flags, self.location)
         else:
             raise IncompatibleSessionError(
                 _("Unsupported version {}").format(version))
@@ -423,6 +467,19 @@
     """
 
 
+class SessionPeekHelper5(SessionPeekHelper4):
+    """
+    Helper class for implementing session peek feature
+
+    This class works with data constructed by
+    :class:`~plainbox.impl.session.suspend.SessionSuspendHelper5` which has
+    been pre-processed by :class:`SessionPeekHelper` (to strip the initial
+    envelope).
+
+    The only goal of this class is to reconstruct session state meta-data.
+    """
+
+
 class SessionResumeHelper1(MetaDataHelper1MixIn):
     """
     Helper class for implementing session resume feature
@@ -441,10 +498,10 @@
     failure modes are possible. Those are documented in :meth:`resume()`
     """
 
-    # Flag controling reference checks from within the session file to external
-    # files. If enabled such checks are performed and can cause additional
-    # exceptions to be raised. Currently this only affects the representation
-    # of the DiskJobResult instances.
+    # Flag controlling reference checks from within the session file to
+    # external files. If enabled such checks are performed and can cause
+    # additional exceptions to be raised. Currently this only affects the
+    # representation of the DiskJobResult instances.
     FLAG_FILE_REFERENCE_CHECKS_S = 'file-reference-checks'
     FLAG_FILE_REFERENCE_CHECKS_F = 0x01
     # Flag controlling rewriting of log file pathnames. It depends on the
@@ -462,9 +519,27 @@
     FLAG_IGNORE_JOB_CHECKSUMS_S = 'ignore-job-checksums'
     FLAG_IGNORE_JOB_CHECKSUMS_F = 0x04
 
-    def __init__(self, job_list, flags=None, location=None):
+    def __init__(
+        self, job_list: 'List[JobDefinition]',
+        flags: 'Optional[Iterable[str]]', location: 'Optional[str]'
+    ):
         """
-        Initialize the helper with a list of known jobs.
+        Initialize the helper with a list of known jobs and support data.
+
+        :param job_list:
+            List of known jobs
+        :param flags:
+            Any iterable object with string versions of resume support flags.
+            This can be None, if the application doesn't wish to enable any of
+            the feature flags.
+        :param location:
+            Location of the session directory. This is the same as
+            ``session_dir`` in the corresponding suspend API. It is also the
+            same as ``storage.location`` (where ``storage`` is a
+            :class:`plainbox.impl.session.storage.SessionStorage` object.
+
+        See :meth:`SessionResumeHelper.__init__()` for description and meaning
+        of each flag.
         """
         self.job_list = job_list
         self.flags = 0
@@ -703,7 +778,7 @@
             raise
 
     @classmethod
-    def _build_JobResult(cls, result_repr, flags=0, location=None):
+    def _build_JobResult(cls, result_repr, flags, location):
         """
         Convert the representation of MemoryJobResult or DiskJobResult
         back into an actual instance.
@@ -724,8 +799,8 @@
             value_none=True)
         # Construct either DiskJobResult or MemoryJobResult
         if 'io_log_filename' in result_repr:
-            io_log_filename = _validate(
-                result_repr, key='io_log_filename', value_type=str)
+            io_log_filename = cls._load_io_log_filename(
+                result_repr, flags, location)
             if (flags & cls.FLAG_FILE_REFERENCE_CHECKS_F
                     and not os.path.isfile(io_log_filename)
                     and flags & cls.FLAG_REWRITE_LOG_PATHNAMES_F):
@@ -759,6 +834,10 @@
             })
 
     @classmethod
+    def _load_io_log_filename(cls, result_repr, flags, location):
+        return _validate(result_repr, key='io_log_filename', value_type=str)
+
+    @classmethod
     def _rewrite_pathname(cls, pathname, location):
         return re.sub(
             '.*\/\.cache\/plainbox\/sessions/[^//]+', location, pathname)
@@ -850,6 +929,35 @@
     """
 
 
+class SessionResumeHelper5(SessionResumeHelper4):
+    """
+    Helper class for implementing session resume feature
+
+    This class works with data constructed by
+    :class:`~plainbox.impl.session.suspend.SessionSuspendHelper5` which has
+    been pre-processed by :class:`SessionResumeHelper` (to strip the initial
+    envelope).
+
+    Due to the constraints of what can be represented in a suspended session,
+    this class cannot work in isolation. It must operate with a list of know
+    jobs.
+
+    Since (most of the) jobs are being provided externally (as they represent
+    the non-serialized parts of checkbox or other job providers) several
+    failure modes are possible. Those are documented in :meth:`resume()`
+    """
+
+    @classmethod
+    def _load_io_log_filename(cls, result_repr, flags, location):
+        io_log_filename = super()._load_io_log_filename(
+            result_repr, flags, location)
+        if os.path.isabs(io_log_filename):
+            return io_log_filename
+        if location is None:
+            raise ValueError("Location must be a directory name")
+        return os.path.join(location, io_log_filename)
+
+
 def _validate(obj, **flags):
     """
     Multi-purpose extraction and validation function.

=== modified file 'plainbox/plainbox/impl/session/suspend.py'
--- plainbox/plainbox/impl/session/suspend.py	2014-11-13 09:38:20 +0000
+++ plainbox/plainbox/impl/session/suspend.py	2015-04-13 18:23:59 +0000
@@ -1,13 +1,12 @@
 # This file is part of Checkbox.
 #
-# Copyright 2012, 2013 Canonical Ltd.
+# Copyright 2012-2015 Canonical Ltd.
 # Written by:
 #   Zygmunt Krynicki <[e-mail]>
 #
 # Checkbox is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License version 3,
 # as published by the Free Software Foundation.
-
 #
 # Checkbox is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
@@ -18,6 +17,8 @@
 # along with Checkbox.  If not, see <http://www.gnu.org/licenses/>.
 
 """
+Implementation of session suspend feature.
+
 :mod:`plainbox.impl.session.suspend` -- session suspend support
 ===============================================================
 
@@ -79,12 +80,15 @@
    :attr:`plainbox.impl.session.state.SessionMetaData.app_id`
 4) Same as '3' but hollow results are not saved and jobs that only
    have hollow results are not mentioned in the job -> checksum map.
+5) Same as '4' but DiskJobResult is stored with a relative pathname to the log
+   file if session_dir is provided.
 """
 
+import base64
 import gzip
 import json
 import logging
-import base64
+import os
 
 from plainbox.impl.result import DiskJobResult
 from plainbox.impl.result import MemoryJobResult
@@ -93,6 +97,7 @@
 
 
 class SessionSuspendHelper1:
+
     """
     Helper class for computing binary representation of a session.
 
@@ -105,14 +110,24 @@
 
     VERSION = 1
 
-    def suspend(self, session):
+    def suspend(self, session, session_dir=None):
         """
+        Compute suspend representation.
+
         Compute the data that is saved by :class:`SessionStorage` as a
         part of :meth:`SessionStorage.save_checkpoint()`.
 
+        :param session:
+            The SessionState object to represent.
+        :param session_dir:
+            (optional) The base directory of the session. If this argument is
+            used then it can alter the representation of some objects related
+            to filesystem artefacts. It is recommended to always pass the
+            session directory.
+
         :returns bytes: the serialized data
         """
-        json_repr = self._json_repr(session)
+        json_repr = self._json_repr(session, session_dir)
         data = json.dumps(
             json_repr,
             ensure_ascii=False,
@@ -123,7 +138,7 @@
         # NOTE: gzip.compress is not deterministic on python3.2
         return gzip.compress(data)
 
-    def _json_repr(self, session):
+    def _json_repr(self, session, session_dir):
         """
         Compute the representation of all of the data that needs to be saved.
 
@@ -144,12 +159,12 @@
         """
         return {
             "version": self.VERSION,
-            "session": self._repr_SessionState(session),
+            "session": self._repr_SessionState(session, session_dir),
         }
 
-    def _repr_SessionState(self, obj):
+    def _repr_SessionState(self, obj, session_dir):
         """
-        Compute the representation of :class:`SessionState`
+        Compute the representation of SessionState.
 
         :returns:
             JSON-friendly representation
@@ -183,18 +198,18 @@
             "results": {
                 # Currently we store only one result but we may store
                 # more than that in a later version.
-                state.job.id: [self._repr_JobResult(state.result)]
+                state.job.id: [self._repr_JobResult(state.result, session_dir)]
                 for state in obj.job_state_map.values()
             },
             "desired_job_list": [
                 job.id for job in obj.desired_job_list
             ],
-            "metadata": self._repr_SessionMetaData(obj.metadata),
+            "metadata": self._repr_SessionMetaData(obj.metadata, session_dir),
         }
 
-    def _repr_SessionMetaData(self, obj):
+    def _repr_SessionMetaData(self, obj, session_dir):
         """
-        Compute the representation of :class:`SessionMetaData`.
+        Compute the representation of SessionMetaData.
 
         :returns:
             JSON-friendly representation.
@@ -222,21 +237,19 @@
             "running_job_name": obj.running_job_name
         }
 
-    def _repr_JobResult(self, obj):
-        """
-        Compute the representation of one of IJobResult subclasses
-        """
+    def _repr_JobResult(self, obj, session_dir):
+        """ Compute the representation of one of IJobResult subclasses.  """
         if isinstance(obj, DiskJobResult):
-            return self._repr_DiskJobResult(obj)
+            return self._repr_DiskJobResult(obj, session_dir)
         elif isinstance(obj, MemoryJobResult):
-            return self._repr_MemoryJobResult(obj)
+            return self._repr_MemoryJobResult(obj, session_dir)
         else:
             raise TypeError(
                 "_repr_JobResult() supports DiskJobResult or MemoryJobResult")
 
-    def _repr_JobResultBase(self, obj):
+    def _repr_JobResultBase(self, obj, session_dir):
         """
-        Compute the representation of :class:`plainbox.impl.job._JobResultBase`
+        Compute the representation of _JobResultBase.
 
         :returns:
             JSON-friendly representation
@@ -268,10 +281,9 @@
             "return_code": obj.return_code,
         }
 
-    def _repr_MemoryJobResult(self, obj):
+    def _repr_MemoryJobResult(self, obj, session_dir):
         """
-        Compute the representation of
-        :class:`plainbox.impl.job.MemoryJobResult`
+        Compute the representation of MemoryJobResult.
 
         :returns:
             JSON-friendly representation
@@ -285,16 +297,16 @@
                 Representation of the list of IO Log records
         """
         assert isinstance(obj, MemoryJobResult)
-        result = self._repr_JobResultBase(obj)
+        result = self._repr_JobResultBase(obj, session_dir)
         result.update({
             "io_log": [self._repr_IOLogRecord(record)
                        for record in obj.io_log],
         })
         return result
 
-    def _repr_DiskJobResult(self, obj):
+    def _repr_DiskJobResult(self, obj, session_dir):
         """
-        Compute the representation of :class:`plainbox.impl.job.DiskJobResult`
+        Compute the representation of DiskJobResult.
 
         :returns:
             JSON-friendly representation
@@ -308,7 +320,7 @@
                 The name of the file that keeps the serialized IO log
         """
         assert isinstance(obj, DiskJobResult)
-        result = self._repr_JobResultBase(obj)
+        result = self._repr_JobResultBase(obj, session_dir)
         result.update({
             "io_log_filename": obj.io_log_filename,
         })
@@ -316,8 +328,7 @@
 
     def _repr_IOLogRecord(self, obj):
         """
-        Compute the representation of
-        :class:`plainbox.impl.result.IOLogRecord`
+        Compute the representation of IOLogRecord.
 
         :returns:
             JSON-friendly representation
@@ -337,6 +348,7 @@
 
 
 class SessionSuspendHelper2(SessionSuspendHelper1):
+
     """
     Helper class for computing binary representation of a session.
 
@@ -349,7 +361,7 @@
 
     VERSION = 2
 
-    def _repr_SessionMetaData(self, obj):
+    def _repr_SessionMetaData(self, obj, session_dir):
         """
         Compute the representation of :class:`SessionMetaData`.
 
@@ -377,7 +389,8 @@
                 Arbitrary application specific binary blob encoded with base64.
                 This field may be null.
         """
-        data = super(SessionSuspendHelper2, self)._repr_SessionMetaData(obj)
+        data = super(SessionSuspendHelper2, self)._repr_SessionMetaData(
+            obj, session_dir)
         if obj.app_blob is None:
             data['app_blob'] = None
         else:
@@ -388,6 +401,7 @@
 
 
 class SessionSuspendHelper3(SessionSuspendHelper2):
+
     """
     Helper class for computing binary representation of a session.
 
@@ -400,7 +414,7 @@
 
     VERSION = 3
 
-    def _repr_SessionMetaData(self, obj):
+    def _repr_SessionMetaData(self, obj, session_dir):
         """
         Compute the representation of :class:`SessionMetaData`.
 
@@ -432,12 +446,14 @@
                 A string identifying the application that stored app_blob.
                 Thirs field may be null.
         """
-        data = super(SessionSuspendHelper3, self)._repr_SessionMetaData(obj)
+        data = super(SessionSuspendHelper3, self)._repr_SessionMetaData(
+            obj, session_dir)
         data['app_id'] = obj.app_id
         return data
 
 
 class SessionSuspendHelper4(SessionSuspendHelper3):
+
     """
     Helper class for computing binary representation of a session.
 
@@ -450,9 +466,9 @@
 
     VERSION = 4
 
-    def _repr_SessionState(self, obj):
+    def _repr_SessionState(self, obj, session_dir):
         """
-        Compute the representation of :class:`SessionState`
+        Compute the representation of :class:`SessionState`.
 
         :returns:
             JSON-friendly representation
@@ -496,16 +512,53 @@
             "results": {
                 # Currently we store only one result but we may store
                 # more than that in a later version.
-                state.job.id: [self._repr_JobResult(state.result)]
+                state.job.id: [self._repr_JobResult(state.result, session_dir)]
                 for state in obj.job_state_map.values()
                 if not state.result.is_hollow
             },
             "desired_job_list": [
                 job.id for job in obj.desired_job_list
             ],
-            "metadata": self._repr_SessionMetaData(obj.metadata),
+            "metadata": self._repr_SessionMetaData(obj.metadata, session_dir),
         }
 
 
+class SessionSuspendHelper5(SessionSuspendHelper4):
+
+    """
+    Helper class for computing binary representation of a session.
+
+    The helper only creates a bytes object to save. Actual saving should
+    be performed using some other means, preferably using
+    :class:`~plainbox.impl.session.storage.SessionStorage`.
+
+    This class creates version '5' snapshots.
+    """
+
+    VERSION = 5
+
+    def _repr_DiskJobResult(self, obj, session_dir):
+        """
+        Compute the representation of DiskJobResult.
+
+        :returns:
+            JSON-friendly representation
+        :rtype:
+            dict
+
+        The dictionary has the following keys *in addition to* what is
+        produced by :meth:`_repr_JobResultBase()`:
+
+            ``io_log_filename``
+                The path of the file that keeps the serialized IO log relative
+                to the session directory.
+        """
+        result = super()._repr_DiskJobResult(obj, session_dir)
+        if session_dir is not None:
+            result["io_log_filename"] = os.path.relpath(
+                obj.io_log_filename, session_dir)
+        return result
+
+
 # Alias for the most recent version
-SessionSuspendHelper = SessionSuspendHelper4
+SessionSuspendHelper = SessionSuspendHelper5

=== modified file 'plainbox/plainbox/impl/session/test_manager.py'
--- plainbox/plainbox/impl/session/test_manager.py	2015-02-25 23:54:36 +0000
+++ plainbox/plainbox/impl/session/test_manager.py	2015-04-13 18:23:59 +0000
@@ -93,7 +93,8 @@
             # Ensure that a fresh instance of the suspend helper was used to
             # call the suspend() method and that the session state parameter
             # was passed to it.
-            helper_cls().suspend.assert_called_with(self.context.state)
+            helper_cls().suspend.assert_called_with(
+                self.context.state, self.storage.location)
         # Ensure that save_checkpoint() was called on the storage object with
         # the return value of what the suspend helper produced.
         self.storage.save_checkpoint.assert_called_with(

=== modified file 'plainbox/plainbox/impl/session/test_resume.py'
--- plainbox/plainbox/impl/session/test_resume.py	2015-01-26 15:38:31 +0000
+++ plainbox/plainbox/impl/session/test_resume.py	2015-04-13 18:23:59 +0000
@@ -48,6 +48,7 @@
 from plainbox.impl.session.resume import SessionResumeHelper2
 from plainbox.impl.session.resume import SessionResumeHelper3
 from plainbox.impl.session.resume import SessionResumeHelper4
+from plainbox.impl.session.resume import SessionResumeHelper5
 from plainbox.impl.session.state import SessionState
 from plainbox.impl.testing_utils import make_job
 from plainbox.testing_utils.testcases import TestCaseWithParameters
@@ -122,7 +123,7 @@
             b'{"session":{"desired_job_list":[],"jobs":{},"metadata":'
             b'{"app_blob":null,"flags":[],"running_job_name":null,"title":null'
             b'},"results":{}},"version":1}')
-        SessionResumeHelper([]).resume(data)
+        SessionResumeHelper([], None, None).resume(data)
         mocked_helper1.resume_json.assertCalledOnce()
 
     @mock.patch('plainbox.impl.session.resume.SessionResumeHelper2')
@@ -131,7 +132,7 @@
             b'{"session":{"desired_job_list":[],"jobs":{},"metadata":'
             b'{"app_blob":null,"flags":[],"running_job_name":null,"title":null'
             b'},"results":{}},"version":2}')
-        SessionResumeHelper([]).resume(data)
+        SessionResumeHelper([], None, None).resume(data)
         mocked_helper2.resume_json.assertCalledOnce()
 
     @mock.patch('plainbox.impl.session.resume.SessionResumeHelper3')
@@ -141,7 +142,7 @@
             b'{"app_blob":null,"app_id":null,"flags":[],'
             b'"running_job_name":null,"title":null'
             b'},"results":{}},"version":3}')
-        SessionResumeHelper([]).resume(data)
+        SessionResumeHelper([], None, None).resume(data)
         mocked_helper3.resume_json.assertCalledOnce()
 
     @mock.patch('plainbox.impl.session.resume.SessionResumeHelper4')
@@ -151,15 +152,25 @@
             b'{"app_blob":null,"app_id":null,"flags":[],'
             b'"running_job_name":null,"title":null'
             b'},"results":{}},"version":4}')
-        SessionResumeHelper([]).resume(data)
+        SessionResumeHelper([], None, None).resume(data)
         mocked_helper4.resume_json.assertCalledOnce()
 
-    def test_resume_dispatch_v5(self):
-        data = gzip.compress(
-            b'{"version":5}')
+    @mock.patch('plainbox.impl.session.resume.SessionResumeHelper5')
+    def test_resume_dispatch_v5(self, mocked_helper5):
+        data = gzip.compress(
+            b'{"session":{"desired_job_list":[],"jobs":{},"metadata":'
+            b'{"app_blob":null,"app_id":null,"flags":[],'
+            b'"running_job_name":null,"title":null'
+            b'},"results":{}},"version":5}')
+        SessionResumeHelper([], None, None).resume(data)
+        mocked_helper5.resume_json.assertCalledOnce()
+
+    def test_resume_dispatch_v6(self):
+        data = gzip.compress(
+            b'{"version":6}')
         with self.assertRaises(IncompatibleSessionError) as boom:
-            SessionResumeHelper([]).resume(data)
-        self.assertEqual(str(boom.exception), "Unsupported version 5")
+            SessionResumeHelper([], None, None).resume(data)
+        self.assertEqual(str(boom.exception), "Unsupported version 6")
 
 
 class SessionResumeTests(TestCase):
@@ -177,7 +188,7 @@
         """
         data = b"foo"
         with self.assertRaises(CorruptedSessionError) as boom:
-            SessionResumeHelper([]).resume(data)
+            SessionResumeHelper([], None, None).resume(data)
         self.assertIsInstance(boom.exception.__context__, IOError)
 
     def test_resume_garbage_unicode(self):
@@ -191,7 +202,7 @@
             b"\xff".decode('UTF-8')
         data = gzip.compress(b"\xff")
         with self.assertRaises(CorruptedSessionError) as boom:
-            SessionResumeHelper([]).resume(data)
+            SessionResumeHelper([], None, None).resume(data)
         self.assertIsInstance(boom.exception.__context__, UnicodeDecodeError)
 
     def test_resume_garbage_json(self):
@@ -202,7 +213,7 @@
         """
         data = gzip.compress(b"{")
         with self.assertRaises(CorruptedSessionError) as boom:
-            SessionResumeHelper([]).resume(data)
+            SessionResumeHelper([], None, None).resume(data)
         self.assertIsInstance(boom.exception.__context__, ValueError)
 
 
@@ -322,7 +333,7 @@
         """
         def early_cb(session):
             self.seen_session = session
-        session = SessionResumeHelper(self.job_list).resume(
+        session = SessionResumeHelper(self.job_list, None, None).resume(
             self.suspend_data, early_cb)
         self.assertIs(session, self.seen_session)
 
@@ -337,11 +348,12 @@
 
     parameter_names = ('resume_cls',)
     parameter_values = ((SessionResumeHelper1,), (SessionResumeHelper2,),
-                        (SessionResumeHelper3,))
+                        (SessionResumeHelper3,), (SessionResumeHelper4,),
+                        (SessionResumeHelper5,))
 
     def setUp(self):
         self.session_repr = {}
-        self.helper = self.parameters.resume_cls([])
+        self.helper = self.parameters.resume_cls([], None, None)
 
     def test_calls_build_SessionState(self):
         """
@@ -411,7 +423,8 @@
 
     parameter_names = ('resume_cls',)
     parameter_values = ((SessionResumeHelper1,), (SessionResumeHelper2,),
-                        (SessionResumeHelper3,))
+                        (SessionResumeHelper3,), (SessionResumeHelper4,),
+                        (SessionResumeHelper5,))
 
     def test_build_IOLogRecord_missing_delay(self):
         """
@@ -511,7 +524,7 @@
         with self.assertRaises(CorruptedSessionError) as boom:
             obj_repr = copy.copy(self.good_repr)
             del obj_repr['outcome']
-            self.parameters.resume_cls._build_JobResult(obj_repr)
+            self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(
             str(boom.exception), "Missing value for key 'outcome'")
 
@@ -522,7 +535,7 @@
         with self.assertRaises(CorruptedSessionError) as boom:
             obj_repr = copy.copy(self.good_repr)
             obj_repr['outcome'] = 42
-            self.parameters.resume_cls._build_JobResult(obj_repr)
+            self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(
             str(boom.exception),
             "Value of key 'outcome' is of incorrect type int")
@@ -535,7 +548,7 @@
         with self.assertRaises(CorruptedSessionError) as boom:
             obj_repr = copy.copy(self.good_repr)
             obj_repr['outcome'] = 'maybe'
-            self.parameters.resume_cls._build_JobResult(obj_repr)
+            self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(
             str(boom.exception), (
                 "Value for key 'outcome' not in allowed set ['crash', 'fail',"
@@ -549,7 +562,7 @@
         """
         obj_repr = copy.copy(self.good_repr)
         obj_repr['outcome'] = None
-        obj = self.parameters.resume_cls._build_JobResult(obj_repr)
+        obj = self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(obj.outcome, None)
 
     def test_build_JobResult_restores_outcome(self):
@@ -558,7 +571,7 @@
         """
         obj_repr = copy.copy(self.good_repr)
         obj_repr['outcome'] = 'fail'
-        obj = self.parameters.resume_cls._build_JobResult(obj_repr)
+        obj = self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(obj.outcome, 'fail')
 
     def test_build_JobResult_checks_for_missing_comments(self):
@@ -568,7 +581,7 @@
         with self.assertRaises(CorruptedSessionError) as boom:
             obj_repr = copy.copy(self.good_repr)
             del obj_repr['comments']
-            self.parameters.resume_cls._build_JobResult(obj_repr)
+            self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(
             str(boom.exception), "Missing value for key 'comments'")
 
@@ -579,7 +592,7 @@
         with self.assertRaises(CorruptedSessionError) as boom:
             obj_repr = copy.copy(self.good_repr)
             obj_repr['comments'] = False
-            self.parameters.resume_cls._build_JobResult(obj_repr)
+            self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(
             str(boom.exception),
             "Value of key 'comments' is of incorrect type bool")
@@ -591,7 +604,7 @@
         """
         obj_repr = copy.copy(self.good_repr)
         obj_repr['comments'] = None
-        obj = self.parameters.resume_cls._build_JobResult(obj_repr)
+        obj = self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(obj.comments, None)
 
     def test_build_JobResult_restores_comments(self):
@@ -600,7 +613,7 @@
         """
         obj_repr = copy.copy(self.good_repr)
         obj_repr['comments'] = 'this is a comment'
-        obj = self.parameters.resume_cls._build_JobResult(obj_repr)
+        obj = self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(obj.comments, 'this is a comment')
 
     def test_build_JobResult_checks_for_missing_return_code(self):
@@ -610,7 +623,7 @@
         with self.assertRaises(CorruptedSessionError) as boom:
             obj_repr = copy.copy(self.good_repr)
             del obj_repr['return_code']
-            self.parameters.resume_cls._build_JobResult(obj_repr)
+            self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(
             str(boom.exception), "Missing value for key 'return_code'")
 
@@ -621,7 +634,7 @@
         with self.assertRaises(CorruptedSessionError) as boom:
             obj_repr = copy.copy(self.good_repr)
             obj_repr['return_code'] = "text"
-            self.parameters.resume_cls._build_JobResult(obj_repr)
+            self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(
             str(boom.exception),
             "Value of key 'return_code' is of incorrect type str")
@@ -633,7 +646,7 @@
         """
         obj_repr = copy.copy(self.good_repr)
         obj_repr['return_code'] = None
-        obj = self.parameters.resume_cls._build_JobResult(obj_repr)
+        obj = self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(obj.return_code, None)
 
     def test_build_JobResult_restores_return_code(self):
@@ -642,7 +655,7 @@
         """
         obj_repr = copy.copy(self.good_repr)
         obj_repr['return_code'] = 42
-        obj = self.parameters.resume_cls._build_JobResult(obj_repr)
+        obj = self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(obj.return_code, 42)
 
     def test_build_JobResult_checks_for_missing_execution_duration(self):
@@ -653,7 +666,7 @@
         with self.assertRaises(CorruptedSessionError) as boom:
             obj_repr = copy.copy(self.good_repr)
             del obj_repr['execution_duration']
-            self.parameters.resume_cls._build_JobResult(obj_repr)
+            self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(
             str(boom.exception), "Missing value for key 'execution_duration'")
 
@@ -665,7 +678,7 @@
         with self.assertRaises(CorruptedSessionError) as boom:
             obj_repr = copy.copy(self.good_repr)
             obj_repr['execution_duration'] = "text"
-            self.parameters.resume_cls._build_JobResult(obj_repr)
+            self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(
             str(boom.exception),
             "Value of key 'execution_duration' is of incorrect type str")
@@ -677,7 +690,7 @@
         """
         obj_repr = copy.copy(self.good_repr)
         obj_repr['execution_duration'] = None
-        obj = self.parameters.resume_cls._build_JobResult(obj_repr)
+        obj = self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(obj.execution_duration, None)
 
     def test_build_JobResult_restores_execution_duration(self):
@@ -687,7 +700,7 @@
         """
         obj_repr = copy.copy(self.good_repr)
         obj_repr['execution_duration'] = 5.1
-        obj = self.parameters.resume_cls._build_JobResult(obj_repr)
+        obj = self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertAlmostEqual(obj.execution_duration, 5.1)
 
 
@@ -701,7 +714,8 @@
 
     parameter_names = ('resume_cls',)
     parameter_values = ((SessionResumeHelper1,), (SessionResumeHelper2,),
-                        (SessionResumeHelper3,))
+                        (SessionResumeHelper3,), (SessionResumeHelper4,),
+                        (SessionResumeHelper5,))
     good_repr = {
         'outcome': "pass",
         'comments': None,
@@ -711,7 +725,7 @@
     }
 
     def test_build_JobResult_restores_MemoryJobResult_representations(self):
-        obj = self.parameters.resume_cls._build_JobResult(self.good_repr)
+        obj = self.parameters.resume_cls._build_JobResult(self.good_repr, 0, None)
         self.assertIsInstance(obj, MemoryJobResult)
 
     def test_build_JobResult_checks_for_missing_io_log(self):
@@ -721,7 +735,7 @@
         with self.assertRaises(CorruptedSessionError) as boom:
             obj_repr = copy.copy(self.good_repr)
             del obj_repr['io_log']
-            self.parameters.resume_cls._build_JobResult(obj_repr)
+            self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(
             str(boom.exception), "Missing value for key 'io_log'")
 
@@ -733,7 +747,7 @@
         with self.assertRaises(CorruptedSessionError) as boom:
             obj_repr = copy.copy(self.good_repr)
             obj_repr['io_log'] = "text"
-            self.parameters.resume_cls._build_JobResult(obj_repr)
+            self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(
             str(boom.exception),
             "Value of key 'io_log' is of incorrect type str")
@@ -746,7 +760,7 @@
         with self.assertRaises(CorruptedSessionError) as boom:
             obj_repr = copy.copy(self.good_repr)
             obj_repr['io_log'] = None
-            self.parameters.resume_cls._build_JobResult(obj_repr)
+            self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(
             str(boom.exception),
             "Value of key 'io_log' cannot be None")
@@ -758,7 +772,7 @@
         """
         obj_repr = copy.copy(self.good_repr)
         obj_repr['io_log'] = [[0.0, 'stdout', '']]
-        obj = self.parameters.resume_cls._build_JobResult(obj_repr)
+        obj = self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         # NOTE: MemoryJobResult.io_log is a property that converts
         # whatever was stored to IOLogRecord and returns a _tuple_
         # so the original list is not visible
@@ -767,27 +781,26 @@
         ]))
 
 
-class DiskJobResultResumeTests(JobResultResumeMixIn, TestCaseWithParameters):
-    """
-    Tests for :class:`~plainbox.impl.session.resume.SessionResumeHelper1`,
-    :class:`~plainbox.impl.session.resume.SessionResumeHelper2' and
-    :class:`~plainbox.impl.session.resume.SessionResumeHelper3' and how they
-    handle recreating DiskJobResult form their representations
-    """
+class DiskJobResultResumeTestsCommon(JobResultResumeMixIn, TestCaseWithParameters):
+
+    """ Tests for common behavior of DiskJobResult resume for all formats.  """
 
     parameter_names = ('resume_cls',)
     parameter_values = ((SessionResumeHelper1,), (SessionResumeHelper2,),
-                        (SessionResumeHelper3,))
+                        (SessionResumeHelper3,), (SessionResumeHelper4,),
+                        (SessionResumeHelper5,))
     good_repr = {
         'outcome': "pass",
         'comments': None,
         'return_code': None,
         'execution_duration': None,
-        'io_log_filename': "file.txt"
+        # NOTE: path is absolute (realistic data required by most of tests)
+        'io_log_filename': "/file.txt"
     }
 
     def test_build_JobResult_restores_DiskJobResult_representations(self):
-        obj = self.parameters.resume_cls._build_JobResult(self.good_repr)
+        obj = self.parameters.resume_cls._build_JobResult(
+            self.good_repr, 0, None)
         self.assertIsInstance(obj, DiskJobResult)
 
     def test_build_JobResult_does_not_check_for_missing_io_log_filename(self):
@@ -799,7 +812,7 @@
         with self.assertRaises(CorruptedSessionError) as boom:
             obj_repr = copy.copy(self.good_repr)
             del obj_repr['io_log_filename']
-            self.parameters.resume_cls._build_JobResult(obj_repr)
+            self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         # NOTE: the error message explicitly talks about 'io_log', not
         # about 'io_log_filename' because we're hitting the other path
         # of the restore function
@@ -814,7 +827,7 @@
         with self.assertRaises(CorruptedSessionError) as boom:
             obj_repr = copy.copy(self.good_repr)
             obj_repr['io_log_filename'] = False
-            self.parameters.resume_cls._build_JobResult(obj_repr)
+            self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(
             str(boom.exception),
             "Value of key 'io_log_filename' is of incorrect type bool")
@@ -827,20 +840,87 @@
         with self.assertRaises(CorruptedSessionError) as boom:
             obj_repr = copy.copy(self.good_repr)
             obj_repr['io_log_filename'] = None
-            self.parameters.resume_cls._build_JobResult(obj_repr)
+            self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
         self.assertEqual(
             str(boom.exception),
             "Value of key 'io_log_filename' cannot be None")
 
-    def test_build_JobResult_restores_io_log_filename(self):
-        """
-        verify that _build_JobResult() restores the value of
-        ``io_log_filename`` DiskJobResult representations
-        """
-        obj_repr = copy.copy(self.good_repr)
-        obj_repr['io_log_filename'] = "some-file.txt"
-        obj = self.parameters.resume_cls._build_JobResult(obj_repr)
-        self.assertEqual(obj.io_log_filename, "some-file.txt")
+
+class DiskJobResultResumeTests1to4(TestCaseWithParameters):
+
+    """ Tests for behavior of DiskJobResult resume for formats 1 to 4. """
+
+    parameter_names = ('resume_cls',)
+    parameter_values = ((SessionResumeHelper1,), (SessionResumeHelper2,),
+                        (SessionResumeHelper3,), (SessionResumeHelper4,))
+    good_repr = {
+        'outcome': "pass",
+        'comments': None,
+        'return_code': None,
+        'execution_duration': None,
+        'io_log_filename': "/file.txt"
+    }
+
+    def test_build_JobResult_restores_io_log_filename(self):
+        """ _build_JobResult() accepts relative paths without location. """
+        obj_repr = copy.copy(self.good_repr)
+        obj_repr['io_log_filename'] = "some-file.txt"
+        obj = self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
+        self.assertEqual(obj.io_log_filename, "some-file.txt")
+
+    def test_build_JobResult_restores_relative_io_log_filename(self):
+        """ _build_JobResult() ignores location for relative paths. """
+        obj_repr = copy.copy(self.good_repr)
+        obj_repr['io_log_filename'] = "some-file.txt"
+        obj = self.parameters.resume_cls._build_JobResult(
+            obj_repr, 0, '/path/to')
+        self.assertEqual(obj.io_log_filename, "some-file.txt")
+
+    def test_build_JobResult_restores_absolute_io_log_filename(self):
+        """ _build_JobResult() preserves absolute paths. """
+        obj_repr = copy.copy(self.good_repr)
+        obj_repr['io_log_filename'] = "/some-file.txt"
+        obj = self.parameters.resume_cls._build_JobResult(
+            obj_repr, 0, '/path/to')
+        self.assertEqual(obj.io_log_filename, "/some-file.txt")
+
+
+class DiskJobResultResumeTests5(TestCaseWithParameters):
+
+    """ Tests for behavior of DiskJobResult resume for format 5. """
+
+    parameter_names = ('resume_cls',)
+    parameter_values = ((SessionResumeHelper5,),)
+    good_repr = {
+        'outcome': "pass",
+        'comments': None,
+        'return_code': None,
+        'execution_duration': None,
+        'io_log_filename': "/file.txt"
+    }
+
+    def test_build_JobResult_restores_io_log_filename(self):
+        """ _build_JobResult() rejects relative paths without location. """
+        obj_repr = copy.copy(self.good_repr)
+        obj_repr['io_log_filename'] = "some-file.txt"
+        with self.assertRaisesRegex(ValueError, "Location "):
+            self.parameters.resume_cls._build_JobResult(obj_repr, 0, None)
+
+    def test_build_JobResult_restores_relative_io_log_filename(self):
+        """ _build_JobResult() uses location for relative paths. """
+        obj_repr = copy.copy(self.good_repr)
+        obj_repr['io_log_filename'] = "some-file.txt"
+        obj = self.parameters.resume_cls._build_JobResult(
+            obj_repr, 0, '/path/to')
+        self.assertEqual(obj.io_log_filename, "/path/to/some-file.txt")
+
+    def test_build_JobResult_restores_absolute_io_log_filename(self):
+        """ _build_JobResult() preserves absolute paths. """
+        obj_repr = copy.copy(self.good_repr)
+        obj_repr['io_log_filename'] = "/some-file.txt"
+        obj = self.parameters.resume_cls._build_JobResult(
+            obj_repr, 0, '/path/to')
+        self.assertEqual(obj.io_log_filename, "/some-file.txt")
 
 
 class DesiredJobListResumeTests(TestCaseWithParameters):
@@ -853,7 +933,8 @@
 
     parameter_names = ('resume_cls',)
     parameter_values = ((SessionResumeHelper1,), (SessionResumeHelper2,),
-                        (SessionResumeHelper3,))
+                        (SessionResumeHelper3,), (SessionResumeHelper4,),
+                        (SessionResumeHelper5,))
 
     def setUp(self):
         # All of the tests need a SessionState object and some jobs to work
@@ -1229,7 +1310,8 @@
 
     parameter_names = ('resume_cls',)
     parameter_values = ((SessionResumeHelper1,), (SessionResumeHelper2,),
-                        (SessionResumeHelper3,))
+                        (SessionResumeHelper3,), (SessionResumeHelper4,),
+                        (SessionResumeHelper5,))
 
     def setUp(self):
         self.job_id = 'job'
@@ -1246,7 +1328,7 @@
                 'io_log': [],
             }]
         }
-        self.helper = self.parameters.resume_cls([self.job])
+        self.helper = self.parameters.resume_cls([self.job], None, None)
         # This object is artificial and would be constructed internally
         # by the helper but having it here makes testing easier as we
         # can reliably test a single method in isolation.
@@ -1392,7 +1474,8 @@
 
     parameter_names = ('resume_cls',)
     parameter_values = ((SessionResumeHelper1,), (SessionResumeHelper2,),
-                        (SessionResumeHelper3,))
+                        (SessionResumeHelper3,), (SessionResumeHelper4,),
+                        (SessionResumeHelper5,))
 
     def test_process_job_restores_resources(self):
         """
@@ -1422,7 +1505,7 @@
                 ],
             }]
         }
-        helper = self.parameters.resume_cls([job])
+        helper = self.parameters.resume_cls([job], None, None)
         session = SessionState([job])
         # Ensure that the resource was not there initially
         self.assertNotIn(job_id, session.resource_map)
@@ -1466,7 +1549,7 @@
                 ],
             }]
         }
-        helper = self.parameters.resume_cls([job])
+        helper = self.parameters.resume_cls([job], None, None)
         session = SessionState([job])
         # Ensure that the 'generated' job was not there initially
         self.assertNotIn('generated', session.job_state_map)
@@ -1493,7 +1576,8 @@
 
     parameter_names = ('resume_cls',)
     parameter_values = ((SessionResumeHelper1,), (SessionResumeHelper2,),
-                        (SessionResumeHelper3,))
+                        (SessionResumeHelper3,), (SessionResumeHelper4,),
+                        (SessionResumeHelper5,))
 
     def test_empty_session(self):
         """
@@ -1506,7 +1590,7 @@
             'jobs': {},
             'results': {}
         }
-        helper = self.parameters.resume_cls([])
+        helper = self.parameters.resume_cls([], None, None)
         session = SessionState([])
         helper._restore_SessionState_jobs_and_results(session, session_repr)
         self.assertEqual(session.job_list, [])
@@ -1534,7 +1618,7 @@
                 }]
             }
         }
-        helper = self.parameters.resume_cls([])
+        helper = self.parameters.resume_cls([], None, None)
         session = SessionState([job])
         helper._restore_SessionState_jobs_and_results(session, session_repr)
         # Session still has one job in it
@@ -1587,7 +1671,7 @@
             }
         }
         # We only pass the parent to the helper! Child will be re-created
-        helper = self.parameters.resume_cls([parent])
+        helper = self.parameters.resume_cls([parent], None, None)
         session = SessionState([parent])
         helper._restore_SessionState_jobs_and_results(session, session_repr)
         # We should now have two jobs, parent and child
@@ -1671,7 +1755,7 @@
         }
         # We only pass the parent to the helper!
         # The 'child' and 'grandchild' jobs will be re-created
-        helper = self.parameters.resume_cls([parent])
+        helper = self.parameters.resume_cls([parent], None, None)
         session = SessionState([parent])
         helper._restore_SessionState_jobs_and_results(session, session_repr)
         # We should now have two jobs, parent and child
@@ -1692,7 +1776,7 @@
                 'job-id': []
             }
         }
-        helper = self.parameters.resume_cls([])
+        helper = self.parameters.resume_cls([], None, None)
         session = SessionState([])
         with self.assertRaises(CorruptedSessionError) as boom:
             helper._restore_SessionState_jobs_and_results(
@@ -1712,7 +1796,8 @@
 
     parameter_names = ('resume_cls',)
     parameter_values = ((SessionResumeHelper1,), (SessionResumeHelper2,),
-                        (SessionResumeHelper3,), (SessionResumeHelper4,))
+                        (SessionResumeHelper3,), (SessionResumeHelper4,),
+                        (SessionResumeHelper5,))
 
     def test_simple_session(self):
         """
@@ -1731,7 +1816,7 @@
                 job_a.id: [],
             }
         }
-        helper = self.parameters.resume_cls([job_a, job_b])
+        helper = self.parameters.resume_cls([job_a, job_b], None, None)
         session = SessionState([job_a, job_b])
         helper._restore_SessionState_job_list(session, session_repr)
         # Job "a" is still in the list but job "b" got removed
@@ -1760,7 +1845,7 @@
                 'results': {},  # nothing ran yet
             },
         }
-        helper = SessionResumeHelper4([job_a, job_a_dep, job_unrelated])
+        helper = SessionResumeHelper4([job_a, job_a_dep, job_unrelated], None, None)
         # Mock away meta-data restore code as we're not testing that
         with mock.patch.object(helper, '_restore_SessionState_metadata'):
             session = helper.resume_json(session_repr)
@@ -1787,7 +1872,7 @@
                 'results': {},  # nothing ran yet
             }
         }
-        helper = SessionResumeHelper4([job_a])
+        helper = SessionResumeHelper4([job_a], None, None)
         # Mock away meta-data restore code as we're not testing that
         with mock.patch.object(helper, '_restore_SessionState_metadata'):
             session = helper.resume_json(session_repr)

=== modified file 'plainbox/plainbox/impl/session/test_suspend.py'
--- plainbox/plainbox/impl/session/test_suspend.py	2015-01-07 14:52:42 +0000
+++ plainbox/plainbox/impl/session/test_suspend.py	2015-04-13 18:23:59 +0000
@@ -39,6 +39,7 @@
 from plainbox.impl.session.suspend import SessionSuspendHelper2
 from plainbox.impl.session.suspend import SessionSuspendHelper3
 from plainbox.impl.session.suspend import SessionSuspendHelper4
+from plainbox.impl.session.suspend import SessionSuspendHelper5
 from plainbox.impl.testing_utils import make_job
 from plainbox.vendor import mock
 
@@ -60,7 +61,7 @@
     """
 
     def setUp(self):
-        self.helper = SessionSuspendHelper1()
+        self.helper = self.HELPER_CLS()
         self.empty_result = self.TESTED_CLS({})
         self.typical_result = self.TESTED_CLS({
             "outcome": self.TESTED_CLS.OUTCOME_PASS,
@@ -69,39 +70,40 @@
             "return_code": 1,
             # NOTE: those are actually specific to TESTED_CLS but it is
             # a simple hack that gets the job done
-            "io_log_filename": "/nonexistent.log",
+            "io_log_filename": "/path/to/log.txt",
             "io_log": [
                 (0, 'stdout', b'first part\n'),
                 (0.1, 'stdout', b'second part\n'),
             ]
         })
+        self.session_dir = None
 
     def test_repr_xxxJobResult_outcome(self):
         """
         verify that DiskJobResult.outcome is serialized correctly
         """
-        data = self.repr_method(self.typical_result)
+        data = self.repr_method(self.typical_result, self.session_dir)
         self.assertEqual(data['outcome'], DiskJobResult.OUTCOME_PASS)
 
     def test_repr_xxxJobResult_execution_duration(self):
         """
         verify that DiskJobResult.execution_duration is serialized correctly
         """
-        data = self.repr_method(self.typical_result)
+        data = self.repr_method(self.typical_result, self.session_dir)
         self.assertAlmostEqual(data['execution_duration'], 42.5)
 
     def test_repr_xxxJobResult_comments(self):
         """
         verify that DiskJobResult.comments is serialized correctly
         """
-        data = self.repr_method(self.typical_result)
+        data = self.repr_method(self.typical_result, self.session_dir)
         self.assertEqual(data['comments'], "the screen was corrupted")
 
     def test_repr_xxxJobResult_return_code(self):
         """
         verify that DiskJobResult.return_code is serialized correctly
         """
-        data = self.repr_method(self.typical_result)
+        data = self.repr_method(self.typical_result, self.session_dir)
         self.assertEqual(data['return_code'], 1)
 
 
@@ -111,6 +113,7 @@
     """
 
     TESTED_CLS = MemoryJobResult
+    HELPER_CLS = SessionSuspendHelper1
 
     def setUp(self):
         super(SuspendMemoryJobResultTests, self).setUp()
@@ -120,7 +123,7 @@
         """
         verify that the representation of an empty MemoryJobResult is okay
         """
-        data = self.repr_method(self.empty_result)
+        data = self.repr_method(self.empty_result, self.session_dir)
         self.assertEqual(data, {
             "outcome": None,
             "execution_duration": None,
@@ -133,7 +136,8 @@
         """
         verify that MemoryJobResult.io_log is serialized correctly
         """
-        data = self.helper._repr_MemoryJobResult(self.typical_result)
+        data = self.helper._repr_MemoryJobResult(
+            self.typical_result, self.session_dir)
         self.assertEqual(data['io_log'], [
             [0, 'stdout', 'Zmlyc3QgcGFydAo='],
             [0.1, 'stdout', 'c2Vjb25kIHBhcnQK'],
@@ -146,6 +150,7 @@
     """
 
     TESTED_CLS = DiskJobResult
+    HELPER_CLS = SessionSuspendHelper1
 
     def setUp(self):
         super(SuspendDiskJobResultTests, self).setUp()
@@ -155,7 +160,7 @@
         """
         verify that the representation of an empty DiskJobResult is okay
         """
-        data = self.repr_method(self.empty_result)
+        data = self.repr_method(self.empty_result, self.session_dir)
         self.assertEqual(data, {
             "outcome": None,
             "execution_duration": None,
@@ -168,8 +173,30 @@
         """
         verify that DiskJobResult.io_log_filename is serialized correctly
         """
-        data = self.helper._repr_DiskJobResult(self.typical_result)
-        self.assertEqual(data['io_log_filename'], "/nonexistent.log")
+        data = self.helper._repr_DiskJobResult(
+            self.typical_result, self.session_dir)
+        self.assertEqual(data['io_log_filename'], "/path/to/log.txt")
+
+
+class Suspend5DiskJobResultTests(SuspendDiskJobResultTests):
+    """
+    Tests that check how DiskJobResult is represented by SessionSuspendHelper5
+    """
+
+    TESTED_CLS = DiskJobResult
+    HELPER_CLS = SessionSuspendHelper5
+
+    def test_repr_DiskJobResult_io_log_filename__no_session_dir(self):
+        """ io_log_filename is absolute in session_dir is not used.  """
+        data = self.helper._repr_DiskJobResult(
+            self.typical_result, None)
+        self.assertEqual(data['io_log_filename'], "/path/to/log.txt")
+
+    def test_repr_DiskJobResult_io_log_filename__session_dir(self):
+        """ io_log_filename is relative if session_dir is used. """
+        data = self.helper._repr_DiskJobResult(
+            self.typical_result, "/path/to")
+        self.assertEqual(data['io_log_filename'], "log.txt")
 
 
 class SessionSuspendHelper1Tests(TestCase):
@@ -179,6 +206,7 @@
 
     def setUp(self):
         self.helper = SessionSuspendHelper1()
+        self.session_dir = None
 
     def test_repr_IOLogRecord(self):
         """
@@ -195,7 +223,7 @@
         calls _repr_MemoryJobResult
         """
         result = MemoryJobResult({})
-        self.helper._repr_JobResult(result)
+        self.helper._repr_JobResult(result, self.session_dir)
         mocked_helper._repr_MemoryJobResult.assertCalledOnceWith(result)
 
     @mock.patch('plainbox.impl.session.suspend.SessionSuspendHelper')
@@ -205,7 +233,7 @@
         calls _repr_DiskJobResult
         """
         result = DiskJobResult({})
-        self.helper._repr_JobResult(result)
+        self.helper._repr_JobResult(result, self.session_dir)
         mocked_helper._repr_DiskJobResult.assertCalledOnceWith(result)
 
     def test_repr_JobResult_with_junk(self):
@@ -221,7 +249,8 @@
         verify that representation of empty SessionMetaData is okay
         """
         # all defaults with empty values
-        data = self.helper._repr_SessionMetaData(SessionMetaData())
+        data = self.helper._repr_SessionMetaData(
+            SessionMetaData(), self.session_dir)
         self.assertEqual(data, {
             'title': None,
             'flags': [],
@@ -237,7 +266,7 @@
             title='USB Testing session',
             flags=['incomplete'],
             running_job_name='usb/detect'
-        ))
+        ), self.session_dir)
         self.assertEqual(data, {
             'title': 'USB Testing session',
             'flags': ['incomplete'],
@@ -248,7 +277,8 @@
         """
         verify that representation of empty SessionState is okay
         """
-        data = self.helper._repr_SessionState(SessionState([]))
+        data = self.helper._repr_SessionState(
+            SessionState([]), self.session_dir)
         self.assertEqual(data, {
             'jobs': {},
             'results': {},
@@ -264,28 +294,28 @@
         """
         verify that the json representation has the 'version' field
         """
-        data = self.helper._json_repr(SessionState([]))
+        data = self.helper._json_repr(SessionState([]), self.session_dir)
         self.assertIn("version", data)
 
     def test_json_repr_current_version(self):
         """
         verify what the version field is
         """
-        data = self.helper._json_repr(SessionState([]))
+        data = self.helper._json_repr(SessionState([]), self.session_dir)
         self.assertEqual(data['version'], 1)
 
     def test_json_repr_stores_session_state(self):
         """
         verify that the json representation has the 'session' field
         """
-        data = self.helper._json_repr(SessionState([]))
+        data = self.helper._json_repr(SessionState([]), self.session_dir)
         self.assertIn("session", data)
 
     def test_suspend(self):
         """
         verify that the suspend() method returns gzipped JSON representation
         """
-        data = self.helper.suspend(SessionState([]))
+        data = self.helper.suspend(SessionState([]), self.session_dir)
         # XXX: we cannot really test what the compressed data looks like
         # because apparently python3.2 gzip output is non-deterministic.
         # It seems to be an instance of the gzip bug that was fixed a few
@@ -321,6 +351,7 @@
     """
 
     def setUp(self):
+        self.session_dir = None
         # Crete a "__category__" job
         self.category_job = JobDefinition({
             "plugin": "local",
@@ -387,7 +418,8 @@
         # and use the data we've defined so far to create JSON-friendly
         # description of the session state.
         self.helper = SessionSuspendHelper1()
-        self.data = self.helper._repr_SessionState(self.session_state)
+        self.data = self.helper._repr_SessionState(
+            self.session_state, self.session_dir)
 
     def test_state_tracked_for_all_jobs(self):
         """
@@ -524,12 +556,13 @@
 
     def setUp(self):
         self.helper = SessionSuspendHelper2()
+        self.session_dir = None
 
     def test_json_repr_current_version(self):
         """
         verify what the version field is
         """
-        data = self.helper._json_repr(SessionState([]))
+        data = self.helper._json_repr(SessionState([]), self.session_dir)
         self.assertEqual(data['version'], 2)
 
     def test_repr_SessionMetaData_empty_metadata(self):
@@ -537,7 +570,8 @@
         verify that representation of empty SessionMetaData is okay
         """
         # all defaults with empty values
-        data = self.helper._repr_SessionMetaData(SessionMetaData())
+        data = self.helper._repr_SessionMetaData(
+            SessionMetaData(), self.session_dir)
         self.assertEqual(data, {
             'title': None,
             'flags': [],
@@ -555,7 +589,7 @@
             flags=['incomplete'],
             running_job_name='usb/detect',
             app_blob=b'blob',
-        ))
+        ), self.session_dir)
         self.assertEqual(data, {
             'title': 'USB Testing session',
             'flags': ['incomplete'],
@@ -567,7 +601,8 @@
         """
         verify that representation of empty SessionState is okay
         """
-        data = self.helper._repr_SessionState(SessionState([]))
+        data = self.helper._repr_SessionState(
+            SessionState([]), self.session_dir)
         self.assertEqual(data, {
             'jobs': {},
             'results': {},
@@ -584,7 +619,8 @@
         """
         verify that the suspend() method returns gzipped JSON representation
         """
-        data = self.helper.suspend(SessionState([]))
+        data = self.helper.suspend(
+            SessionState([]), self.session_dir)
         # XXX: we cannot really test what the compressed data looks like
         # because apparently python3.2 gzip output is non-deterministic.
         # It seems to be an instance of the gzip bug that was fixed a few
@@ -609,12 +645,13 @@
 
     def setUp(self):
         self.helper = SessionSuspendHelper3()
+        self.session_dir = None
 
     def test_json_repr_current_version(self):
         """
         verify what the version field is
         """
-        data = self.helper._json_repr(SessionState([]))
+        data = self.helper._json_repr(SessionState([]), self.session_dir)
         self.assertEqual(data['version'], 3)
 
     def test_repr_SessionMetaData_empty_metadata(self):
@@ -622,7 +659,8 @@
         verify that representation of empty SessionMetaData is okay
         """
         # all defaults with empty values
-        data = self.helper._repr_SessionMetaData(SessionMetaData())
+        data = self.helper._repr_SessionMetaData(
+            SessionMetaData(), self.session_dir)
         self.assertEqual(data, {
             'title': None,
             'flags': [],
@@ -642,7 +680,7 @@
             running_job_name='usb/detect',
             app_blob=b'blob',
             app_id='com.canonical.certification.plainbox',
-        ))
+        ), self.session_dir)
         self.assertEqual(data, {
             'title': 'USB Testing session',
             'flags': ['incomplete'],
@@ -655,7 +693,8 @@
         """
         verify that representation of empty SessionState is okay
         """
-        data = self.helper._repr_SessionState(SessionState([]))
+        data = self.helper._repr_SessionState(
+            SessionState([]), self.session_dir)
         self.assertEqual(data, {
             'jobs': {},
             'results': {},
@@ -673,7 +712,7 @@
         """
         verify that the suspend() method returns gzipped JSON representation
         """
-        data = self.helper.suspend(SessionState([]))
+        data = self.helper.suspend(SessionState([]), self.session_dir)
         # XXX: we cannot really test what the compressed data looks like
         # because apparently python3.2 gzip output is non-deterministic.
         # It seems to be an instance of the gzip bug that was fixed a few
@@ -699,12 +738,13 @@
 
     def setUp(self):
         self.helper = SessionSuspendHelper4()
+        self.session_dir = None
 
     def test_json_repr_current_version(self):
         """
         verify what the version field is
         """
-        data = self.helper._json_repr(SessionState([]))
+        data = self.helper._json_repr(SessionState([]), self.session_dir)
         self.assertEqual(data['version'], 4)
 
     def test_repr_SessionState_typical_session(self):
@@ -734,7 +774,7 @@
         session_state = SessionState([used_job, unused_job])
         session_state.update_desired_job_list([used_job])
         session_state.update_job_result(used_job, used_result)
-        data = self.helper._repr_SessionState(session_state)
+        data = self.helper._repr_SessionState(session_state, self.session_dir)
         self.assertEqual(data, {
             'jobs': {
                 'used': ('8c393c19fdfde1b6afc5b79d0a1617ecf7531cd832a16450dc'
@@ -763,7 +803,7 @@
         """
         verify that the suspend() method returns gzipped JSON representation
         """
-        data = self.helper.suspend(SessionState([]))
+        data = self.helper.suspend(SessionState([]), self.session_dir)
         # XXX: we cannot really test what the compressed data looks like
         # because apparently python3.2 gzip output is non-deterministic.
         # It seems to be an instance of the gzip bug that was fixed a few
@@ -782,6 +822,45 @@
             b'"version":4}'))
 
 
+class SessionSuspendHelper5Tests(SessionSuspendHelper4Tests):
+    """
+    Tests for various methods of SessionSuspendHelper5
+    """
+
+    def setUp(self):
+        self.helper = SessionSuspendHelper5()
+        self.session_dir = None
+
+    def test_json_repr_current_version(self):
+        """
+        verify what the version field is
+        """
+        data = self.helper._json_repr(SessionState([]), self.session_dir)
+        self.assertEqual(data['version'], 5)
+
+    def test_suspend(self):
+        """
+        verify that the suspend() method returns gzipped JSON representation
+        """
+        data = self.helper.suspend(SessionState([]), self.session_dir)
+        # XXX: we cannot really test what the compressed data looks like
+        # because apparently python3.2 gzip output is non-deterministic.
+        # It seems to be an instance of the gzip bug that was fixed a few
+        # years ago.
+        #
+        # I've filed a bug on python3.2 in Ubuntu and Python upstream project
+        # https://bugs.launchpad.net/ubuntu/+source/python3.2/+bug/871083
+        #
+        # In the meantime we can only test that we got bytes out
+        self.assertIsInstance(data, bytes)
+        # And that we can gzip uncompress them and get what we expected
+        self.assertEqual(gzip.decompress(data), (
+            b'{"session":{"desired_job_list":[],"jobs":{},"metadata":'
+            b'{"app_blob":null,"app_id":null,"flags":[],'
+            b'"running_job_name":null,"title":null},"results":{}},'
+            b'"version":5}'))
+
+
 class RegressionTests(TestCase):
 
     def test_1388055(self):
@@ -800,10 +879,11 @@
         self.assertEqual(state.run_list, [job_a_dep, job_a])
         self.assertEqual(state.desired_job_list, [job_a])
         helper = SessionSuspendHelper4()
+        session_dir = None
         # Mock away the meta-data as we're not testing that
         with mock.patch.object(helper, '_repr_SessionMetaData') as m:
             m.return_value = 'mocked'
-            actual = helper._repr_SessionState(state)
+            actual = helper._repr_SessionState(state, session_dir)
         expected = {
             'jobs': {
                 job_a_dep.id: job_a_dep.checksum,