Session resume handling.
plainbox.impl.session.resume
– session resume handling¶
This module contains classes that can resume a dormant session from a binary representation. See docs for the suspend module for details.
The resume logic provides a compromise between usefulness and correctness so two assumptions are made:
We assume that a checksum of a job changes when their behavior changes. This way we can detect when job definitions were updated after suspending but before resuming.
We assume that software and hardware may change while the session is suspended but this is not something that framework (PlainBox) is concerned with. Applications should provide job definitions that are capable of detecting this and acting appropriately.
This is true since the user may install additional packages or upgrade existing packages. The user can also add or remove pluggable hardware. Lastly actual machine suspend (or hibernate) and resume may cause alterations to the hardware as it is visible from within the system. In any case the framework does not care about this.
-
exception
plainbox.impl.session.resume.
BrokenReferenceToExternalFile
[source]¶ Bases:
plainbox.impl.session.resume.SessionResumeError
Exception raised when suspended session needs an external file that’s gone.
Exception raised when
SessionResumeHelper
detects that a file needed by the session to resume is not present. This is typically used to signal inaccessible log files.-
args
¶
-
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
-
exception
plainbox.impl.session.resume.
CorruptedSessionError
[source]¶ Bases:
plainbox.impl.session.resume.SessionResumeError
Exception raised when suspended session is corrupted.
Exception raised when
SessionResumeHelper
cannot decode the session byte stream. This exception will be raised with additional context that captures the actual underlying cause. Having this exception class makes it easier to handle resume errors.-
args
¶
-
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
-
class
plainbox.impl.session.resume.
EnvelopeUnpackMixIn
[source]¶ Bases:
object
A mix-in class capable of unpacking the envelope of the session storage.
This class assists in unpacking the “envelope” in which the session data is actually stored. The envelope is simply gzip but other kinds of envelope can be added later.
-
unpack_envelope
(data)¶ Unpack the binary envelope and get access to a JSON object.
Parameters: data – Bytes representing the dormant session Returns: the JSON representation of a session stored in the envelope Raises CorruptedSessionError: if the representation of the session is corrupted in any way
-
-
exception
plainbox.impl.session.resume.
IncompatibleJobError
[source]¶ Bases:
plainbox.impl.session.resume.SessionResumeError
Exception raised when suspended session needs a different version of a job.
Exception raised when
SessionResumeHelper
detects that the set of jobs it knows about is incompatible with what was saved before.-
args
¶
-
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
-
exception
plainbox.impl.session.resume.
IncompatibleSessionError
[source]¶ Bases:
plainbox.impl.session.resume.SessionResumeError
Exception raised when suspended session is correct but incompatible.
Exception raised when
SessionResumeHelper
comes across malformed or unsupported data that was (presumably) produced bySessionSuspendHelper
-
args
¶
-
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
-
class
plainbox.impl.session.resume.
MetaDataHelper1MixIn
[source]¶ Bases:
object
Mix-in class for working with v1 meta-data.
-
class
plainbox.impl.session.resume.
MetaDataHelper2MixIn
[source]¶ Bases:
plainbox.impl.session.resume.MetaDataHelper1MixIn
Mix-in class for working with v2 meta-data.
-
class
plainbox.impl.session.resume.
MetaDataHelper3MixIn
[source]¶ Bases:
plainbox.impl.session.resume.MetaDataHelper2MixIn
Mix-in class for working with v3 meta-data.
-
class
plainbox.impl.session.resume.
ResumeDiscardQualifier
(retain_id_set)[source]¶ Bases:
plainbox.impl.secure.qualifiers.SimpleQualifier
Qualifier for jobs that need to be discarded after resume.
A job qualifier that designates jobs that should be removed after doing a session resume.
-
VOTE_EXCLUDE
= 0¶
-
VOTE_IGNORE
= 2¶
-
VOTE_INCLUDE
= 1¶
-
designates
(job)¶
-
get_primitive_qualifiers
()¶ Return a list of primitives that constitute this qualifier.
Returns: A list of IJobQualifier objects that each is the smallest, indivisible entity. Here it just returns a list of one element, itself.
-
get_simple_match
(job)¶ Check if a job should be listed by this qualifier.
-
get_vote
(job)¶ Get one of the
VOTE_IGNORE
,VOTE_INCLUDE
,VOTE_EXCLUDE
votes that this qualifier associated with the specified job.Parameters: job – A IJobDefinition instance that is to be visited Returns: VOTE_INCLUDE
if the job matches the simple qualifier concept embedded into this qualifier and this qualifier is inclusive.VOTE_EXCLUDE
if the job matches the simple qualifier concept embedded into this qualifier and this qualifier is not inclusive.VOTE_IGNORE
otherwise.
-
inclusive
¶
-
is_primitive
¶
-
origin
¶ Origin of this qualifier
This property can be used to trace the origin of a qualifier back to its definition point.
-
-
class
plainbox.impl.session.resume.
SessionPeekHelper
[source]¶ Bases:
plainbox.impl.session.resume.EnvelopeUnpackMixIn
A helper class to peek at session state meta-data quickly.
-
peek
(data)¶ Peek at the meta-data of a dormant session.
Parameters: data – Bytes representing the dormant session
Returns: a SessionMetaData object
Raises: - CorruptedSessionError – if the representation of the session is corrupted in any way
- IncompatibleSessionError – if session serialization format is not supported
-
unpack_envelope
(data)¶ Unpack the binary envelope and get access to a JSON object.
Parameters: data – Bytes representing the dormant session Returns: the JSON representation of a session stored in the envelope Raises CorruptedSessionError: if the representation of the session is corrupted in any way
-
-
class
plainbox.impl.session.resume.
SessionPeekHelper1
[source]¶ Bases:
plainbox.impl.session.resume.MetaDataHelper1MixIn
Helper class for implementing session peek feature.
This class works with data constructed by
SessionSuspendHelper1
which has been pre-processed bySessionPeekHelper
(to strip the initial envelope).The only goal of this class is to reconstruct session state meta-data.
-
peek_json
(json_repr)¶ Resume a SessionState object from the JSON representation.
This method is called by
peek()
after the initial envelope and parsing is done. The only error conditions that can happen are related to semantic incompatibilities or corrupted internal state.
-
-
class
plainbox.impl.session.resume.
SessionPeekHelper2
[source]¶ Bases:
plainbox.impl.session.resume.MetaDataHelper2MixIn
,plainbox.impl.session.resume.SessionPeekHelper1
Helper class for implementing session peek feature.
This class works with data constructed by
SessionSuspendHelper1
which has been pre-processed bySessionPeekHelper
(to strip the initial envelope).The only goal of this class is to reconstruct session state meta-data.
-
peek_json
(json_repr)¶ Resume a SessionState object from the JSON representation.
This method is called by
peek()
after the initial envelope and parsing is done. The only error conditions that can happen are related to semantic incompatibilities or corrupted internal state.
-
-
class
plainbox.impl.session.resume.
SessionPeekHelper3
[source]¶ Bases:
plainbox.impl.session.resume.MetaDataHelper3MixIn
,plainbox.impl.session.resume.SessionPeekHelper2
Helper class for implementing session peek feature.
This class works with data constructed by
SessionSuspendHelper1
which has been pre-processed bySessionPeekHelper
(to strip the initial envelope).The only goal of this class is to reconstruct session state meta-data.
-
peek_json
(json_repr)¶ Resume a SessionState object from the JSON representation.
This method is called by
peek()
after the initial envelope and parsing is done. The only error conditions that can happen are related to semantic incompatibilities or corrupted internal state.
-
-
class
plainbox.impl.session.resume.
SessionPeekHelper4
[source]¶ Bases:
plainbox.impl.session.resume.SessionPeekHelper3
Helper class for implementing session peek feature.
This class works with data constructed by
SessionSuspendHelper1
which has been pre-processed bySessionPeekHelper
(to strip the initial envelope).The only goal of this class is to reconstruct session state meta-data.
-
peek_json
(json_repr)¶ Resume a SessionState object from the JSON representation.
This method is called by
peek()
after the initial envelope and parsing is done. The only error conditions that can happen are related to semantic incompatibilities or corrupted internal state.
-
-
class
plainbox.impl.session.resume.
SessionPeekHelper5
[source]¶ Bases:
plainbox.impl.session.resume.SessionPeekHelper4
Helper class for implementing session peek feature.
This class works with data constructed by
SessionSuspendHelper5
which has been pre-processed bySessionPeekHelper
(to strip the initial envelope).The only goal of this class is to reconstruct session state meta-data.
-
peek_json
(json_repr)¶ Resume a SessionState object from the JSON representation.
This method is called by
peek()
after the initial envelope and parsing is done. The only error conditions that can happen are related to semantic incompatibilities or corrupted internal state.
-
-
class
plainbox.impl.session.resume.
SessionPeekHelper6
[source]¶ Bases:
plainbox.impl.session.resume.SessionPeekHelper5
Helper class for implementing session peek feature
This class works with data constructed by
SessionSuspendHelper6
which has been pre-processed bySessionPeekHelper
(to strip the initial envelope).The only goal of this class is to reconstruct session state meta-data.
-
peek_json
(json_repr)¶ Resume a SessionState object from the JSON representation.
This method is called by
peek()
after the initial envelope and parsing is done. The only error conditions that can happen are related to semantic incompatibilities or corrupted internal state.
-
-
exception
plainbox.impl.session.resume.
SessionResumeError
[source]¶ Bases:
Exception
Base for all session resume exceptions.
Base class for exceptions that can be raised when attempting to resume a dormant session.
-
args
¶
-
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
-
class
plainbox.impl.session.resume.
SessionResumeHelper
(job_list: 'List[JobDefinition]', flags: 'Optional[Iterable[str]]', location: 'Optional[str]')[source]¶ Bases:
plainbox.impl.session.resume.EnvelopeUnpackMixIn
Helper class for implementing session resume feature.
This class is a facade that does enough of the resume process to know which version is being resumed and delegate the rest of the process to an appropriate, format specific, resume class.
-
resume
(data, early_cb=None)¶ Resume a dormant session.
Parameters: - data – Bytes representing the dormant session
- early_cb – A callback that allows the caller to “see” the session object early, before the bulk of resume operation happens. This method can be used to register signal listeners on the new session before this method call returns. The callback accepts one argument, session, which is being resumed.
Returns: resumed session instance
Return type: This method validates the representation of a dormant session and re-creates an identical SessionState instance. It can fail in multiple ways, some of which are a part of normal operation and should always be handled (
IncompatibleJobError
andIncompatibleJobError
). Applications may wish to captureSessionResumeError
as a generic base exception for all the possible problems.Raises: - CorruptedSessionError – if the representation of the session is corrupted in any way
- IncompatibleSessionError – if session serialization format is not supported
- IncompatibleJobError – if serialized jobs are not the same as current jobs
-
unpack_envelope
(data)¶ Unpack the binary envelope and get access to a JSON object.
Parameters: data – Bytes representing the dormant session Returns: the JSON representation of a session stored in the envelope Raises CorruptedSessionError: if the representation of the session is corrupted in any way
-
-
class
plainbox.impl.session.resume.
SessionResumeHelper1
(job_list: 'List[JobDefinition]', flags: 'Optional[Iterable[str]]', location: 'Optional[str]')[source]¶ Bases:
plainbox.impl.session.resume.MetaDataHelper1MixIn
Helper class for implementing session resume feature.
This class works with data constructed by
SessionSuspendHelper1
which has been pre-processed bySessionResumeHelper
(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
resume()
-
FLAG_FILE_REFERENCE_CHECKS_F
= 1¶
-
FLAG_FILE_REFERENCE_CHECKS_S
= 'file-reference-checks'¶
-
FLAG_IGNORE_JOB_CHECKSUMS_F
= 4¶
-
FLAG_IGNORE_JOB_CHECKSUMS_S
= 'ignore-job-checksums'¶
-
FLAG_REWRITE_LOG_PATHNAMES_F
= 2¶
-
FLAG_REWRITE_LOG_PATHNAMES_S
= 'rewrite-log-pathnames'¶
-
resume_json
(json_repr, early_cb=None)¶ Resume a SessionState object from the JSON representation.
This method is called by
resume()
after the initial envelope and parsing is done. The only error conditions that can happen are related to semantic incompatibilities or corrupted internal state.
-
-
class
plainbox.impl.session.resume.
SessionResumeHelper2
(job_list: 'List[JobDefinition]', flags: 'Optional[Iterable[str]]', location: 'Optional[str]')[source]¶ Bases:
plainbox.impl.session.resume.MetaDataHelper2MixIn
,plainbox.impl.session.resume.SessionResumeHelper1
Helper class for implementing session resume feature.
This class works with data constructed by
SessionSuspendHelper2
which has been pre-processed bySessionResumeHelper
(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
resume()
-
FLAG_FILE_REFERENCE_CHECKS_F
= 1¶
-
FLAG_FILE_REFERENCE_CHECKS_S
= 'file-reference-checks'¶
-
FLAG_IGNORE_JOB_CHECKSUMS_F
= 4¶
-
FLAG_IGNORE_JOB_CHECKSUMS_S
= 'ignore-job-checksums'¶
-
FLAG_REWRITE_LOG_PATHNAMES_F
= 2¶
-
FLAG_REWRITE_LOG_PATHNAMES_S
= 'rewrite-log-pathnames'¶
-
resume_json
(json_repr, early_cb=None)¶ Resume a SessionState object from the JSON representation.
This method is called by
resume()
after the initial envelope and parsing is done. The only error conditions that can happen are related to semantic incompatibilities or corrupted internal state.
-
-
class
plainbox.impl.session.resume.
SessionResumeHelper3
(job_list: 'List[JobDefinition]', flags: 'Optional[Iterable[str]]', location: 'Optional[str]')[source]¶ Bases:
plainbox.impl.session.resume.MetaDataHelper3MixIn
,plainbox.impl.session.resume.SessionResumeHelper2
Helper class for implementing session resume feature.
This class works with data constructed by
SessionSuspendHelper3
which has been pre-processed bySessionResumeHelper
(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
resume()
-
FLAG_FILE_REFERENCE_CHECKS_F
= 1¶
-
FLAG_FILE_REFERENCE_CHECKS_S
= 'file-reference-checks'¶
-
FLAG_IGNORE_JOB_CHECKSUMS_F
= 4¶
-
FLAG_IGNORE_JOB_CHECKSUMS_S
= 'ignore-job-checksums'¶
-
FLAG_REWRITE_LOG_PATHNAMES_F
= 2¶
-
FLAG_REWRITE_LOG_PATHNAMES_S
= 'rewrite-log-pathnames'¶
-
resume_json
(json_repr, early_cb=None)¶ Resume a SessionState object from the JSON representation.
This method is called by
resume()
after the initial envelope and parsing is done. The only error conditions that can happen are related to semantic incompatibilities or corrupted internal state.
-
-
class
plainbox.impl.session.resume.
SessionResumeHelper4
(job_list: 'List[JobDefinition]', flags: 'Optional[Iterable[str]]', location: 'Optional[str]')[source]¶ Bases:
plainbox.impl.session.resume.SessionResumeHelper3
Helper class for implementing session resume feature.
This class works with data constructed by
SessionSuspendHelper4
which has been pre-processed bySessionResumeHelper
(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
resume()
-
FLAG_FILE_REFERENCE_CHECKS_F
= 1¶
-
FLAG_FILE_REFERENCE_CHECKS_S
= 'file-reference-checks'¶
-
FLAG_IGNORE_JOB_CHECKSUMS_F
= 4¶
-
FLAG_IGNORE_JOB_CHECKSUMS_S
= 'ignore-job-checksums'¶
-
FLAG_REWRITE_LOG_PATHNAMES_F
= 2¶
-
FLAG_REWRITE_LOG_PATHNAMES_S
= 'rewrite-log-pathnames'¶
-
resume_json
(json_repr, early_cb=None)¶ Resume a SessionState object from the JSON representation.
This method is called by
resume()
after the initial envelope and parsing is done. The only error conditions that can happen are related to semantic incompatibilities or corrupted internal state.
-
-
class
plainbox.impl.session.resume.
SessionResumeHelper5
(job_list: 'List[JobDefinition]', flags: 'Optional[Iterable[str]]', location: 'Optional[str]')[source]¶ Bases:
plainbox.impl.session.resume.SessionResumeHelper4
Helper class for implementing session resume feature.
This class works with data constructed by
SessionSuspendHelper5
which has been pre-processed bySessionResumeHelper
(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
resume()
-
FLAG_FILE_REFERENCE_CHECKS_F
= 1¶
-
FLAG_FILE_REFERENCE_CHECKS_S
= 'file-reference-checks'¶
-
FLAG_IGNORE_JOB_CHECKSUMS_F
= 4¶
-
FLAG_IGNORE_JOB_CHECKSUMS_S
= 'ignore-job-checksums'¶
-
FLAG_REWRITE_LOG_PATHNAMES_F
= 2¶
-
FLAG_REWRITE_LOG_PATHNAMES_S
= 'rewrite-log-pathnames'¶
-
resume_json
(json_repr, early_cb=None)¶ Resume a SessionState object from the JSON representation.
This method is called by
resume()
after the initial envelope and parsing is done. The only error conditions that can happen are related to semantic incompatibilities or corrupted internal state.
-
-
class
plainbox.impl.session.resume.
SessionResumeHelper6
(job_list: 'List[JobDefinition]', flags: 'Optional[Iterable[str]]', location: 'Optional[str]')[source]¶ Bases:
plainbox.impl.session.resume.SessionResumeHelper5
Helper class for implementing session resume feature
This class works with data constructed by
SessionSuspendHelper5
which has been pre-processed bySessionResumeHelper
(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
resume()
-
FLAG_FILE_REFERENCE_CHECKS_F
= 1¶
-
FLAG_FILE_REFERENCE_CHECKS_S
= 'file-reference-checks'¶
-
FLAG_IGNORE_JOB_CHECKSUMS_F
= 4¶
-
FLAG_IGNORE_JOB_CHECKSUMS_S
= 'ignore-job-checksums'¶
-
FLAG_REWRITE_LOG_PATHNAMES_F
= 2¶
-
FLAG_REWRITE_LOG_PATHNAMES_S
= 'rewrite-log-pathnames'¶
-
resume_json
(json_repr, early_cb=None)¶ Resume a SessionState object from the JSON representation.
This method is called by
resume()
after the initial envelope and parsing is done. The only error conditions that can happen are related to semantic incompatibilities or corrupted internal state.
-