#!/usr/bin/python

#

# CDDL HEADER START

#

# The contents of this file are subject to the terms of the

# Common Development and Distribution License (the "License").

# You may not use this file except in compliance with the License.

#

# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE

# or http://www.opensolaris.org/os/licensing.

# See the License for the specific language governing permissions

# and limitations under the License.

#

# When distributing Covered Code, include this CDDL HEADER in each

# file and include the License file at usr/src/OPENSOLARIS.LICENSE.

# If applicable, add the following below this CDDL HEADER, with the

# fields enclosed by brackets "[]" replaced with your own identifying

# information: Portions Copyright [yyyy] [name of copyright owner]

#

# CDDL HEADER END

#

#

#

'''

Class representing the Installation Execution Engine

'''

import decimal

import glob

import imp

import inspect

import logging

import os

import shutil

import string

import tempfile

import threading

import warnings

import osol_install.errsvc as errsvc

import osol_install.liberrsvc as liberrsvc

from logging import CRITICAL, ERROR, WARNING, INFO, DEBUG, NOTSET

from osol_install.install_utils import get_argspec

from solaris_install.data_object import DataObject

from solaris_install.data_object.cache import DataObjectCache

from solaris_install.engine.checkpoint_data import CheckpointData

from solaris_install.logger import InstallLogger, LogInitError, \

from solaris_install.target.logical import Filesystem

LOGGER = None

class EngineError(StandardError):

    '''Base class for engine specific errors'''

    pass

class RollbackError(EngineError):

    '''Error during an attempt to rollback'''

    _MSG = "Cannot rollback to '%s' checkpoint: %s"

    def __init__(self, cp_name, reason):

        msg = RollbackError._MSG % (cp_name, reason)

        self.checkpoint = cp_name

        EngineError.__init__(self, msg)

class SingletonError(EngineError):

    '''Occurs when one attempts to instantiate a second singleton'''

    pass

class UsageError(EngineError):

    '''General usage error for an engine call'''

    pass

class NoCacheError(RollbackError, IOError):

    '''Error during rollback - can't find the DOC'''

    def __init__(self, cp_name, cache_path):

        self.cache_path = cache_path

        RollbackError.__init__(self, cp_name,

                               "Cache does not exist at path: %s" % cache_path)

class ChkptRegistrationError(EngineError):

    '''Error occur while trying to register a checkpoint'''

    pass

class UnknownChkptError(UsageError):

    '''Error occurs when attempting to access a checkpoint that doesn't

    exist'''

    pass

class NoDatasetError(UsageError):

    '''ZFS dataset is not specified.'''

    pass

class FileNotFoundError(UsageError):

    ''' The specified zfs dataset is not found, or

        no DataObjectCache snapshot exist in the provided ZFS dataset.

    '''

    pass

class EngineData(DataObject):

    '''Root node below DataObjectCache for storing all install

       engine related data

    '''

    def __init__(self):

        DataObject.__init__(self, InstallEngine.ENGINE_DOC_ROOT)

    def to_xml(self):

        ''' This internal engine info node will not be saved to XML '''

        return None

    @classmethod

    def from_xml(cls, xml_node):

        ''' This internal engine info node will not be read from XML '''

        return None

    @classmethod

    def can_handle(cls, xml_node):

        ''' This internal engine info node will not be read from XML '''

        return False

class InstallEngine(object):

    ''' Install execution engine '''

    CP_THREAD = "CheckpointThread"

    EXEC_FAILED = "Execution Failed"

    EXEC_SUCCESS = "Execution Successful"

    EXEC_CANCELED = "Execution Canceled"

    CP_INIT_FAILED = "Checkpoint Initialization Failed"

    FATAL_INTERNAL = "InstallEngineInternal"

    TMP_CACHE_ENV = "TEMP_DOC_DIR"

    TMP_CACHE_PATH_ROOT_DEFAULT = "/var/run/install_engine"

    TMP_CACHE_PATH_PREFIX = "engine."

    CACHE_FILE_NAME_PREFIX = ".data_cache."

    CACHE_FILE_NAME = CACHE_FILE_NAME_PREFIX + "%(checkpoint)s"

    SNAPSHOT_NAME = ".step_%(checkpoint)s"

    CP_COMPLETED_SUFFIX = "-completed"

    ENGINE_DOC_ROOT = "Engine-DOC-Root-Node"

    NUM_CALLBACK_ARGS = 2

    # progress ratio for the preparing to execute checkpoints

    EXEC_PREP_RATIO = 0.05

    EXEC_PREP_RATIO_DECIMAL = decimal.Decimal(str(EXEC_PREP_RATIO))

    PREP_MSG = "Preparing for Installation"

    _instance = None

    class _PseudoThread(threading.Thread):

        ''' thread used for execute_checkpoints() for the blocking case '''

        start = threading.Thread.run

        if InstallEngine._instance is None:

            return object.__new__(cls)

        else:

            raise SingletonError("InstallEngine instance already exists",

                                 InstallEngine._instance)

        ''' Initializes the InstallEngine

        Input:

            - loglevel: Optional.  Defaults to None.

              Logging level to use for everything: application,

              engine and checkpoints.  This value is used while instantiating

              the logger.  If not specified, the default logging level for the

              logging service is used.

            - Debug: Optional.  Default to false.

              If true, copies of DataObjectCache snapshot will not be

              removed from the directory defined to store temporary snapshots

              of DataObjectCache.

            - Dataset: Optional.  Default to None.

              ZFS Dataset to be used by the engine to create ZFS snapshots

              and DataObjectCache snapshots for supporting stop and resume.

              This value can be set at a later time, if not set here.

              Value of ZFS dataset specified will not be validated here to

              ensure it exists.  If dataset does not exist at this point,

              it will not be created.

            - stop_on_error: Optional.  Default to True.

              This flag controls whether checkpoint execution should continue

              if a checkpoint fails.  This value can be set at a later time,

              if not set here.

        Output:

            None

        Raises:

            None

        '''

        InstallEngine._instance = self

        # Logging must be instantiated before instantiating the DataObjectCache

        # because data object cache might need to make logging calls.

        # initialize the data object cache

        self.data_object_cache = DataObjectCache()

        self.debug = debug

        self._dataset = None

        self.dataset = dataset

        self.stop_on_error = stop_on_error

        self.__currently_executing = None

        # Use 8 decimal precision for progress.  Using less precision

        # will cause problems when the estimated progress for some

        # checkpoints are drastically different than the others.

        # Always round down while calculating the progress ratios

        d_context = decimal.Context(prec=8, rounding=decimal.ROUND_DOWN)

        decimal.setcontext(d_context)

        self.__current_completed = decimal.Decimal("0")

        self.__blocking_results = None

        self.__resume_exec_cp_ok = True

        self._checkpoints = []

        self.checkpoint_thread = None

        self._tmp_cache_path = None

        self._checkpoint_lock = threading.Lock()

        self._cancel_event = threading.Event()

        # The following will be set to True anytime a ZFS snapshot call is made

        self.zfs_snapshots_modifed = False

        # in the process of preparing for execution

        self.exec_prep = False

    def __del__(self):

        if self._tmp_cache_path is not None and not self.debug:

            shutil.rmtree(self._tmp_cache_path, ignore_errors=True)

        self._tmp_cache_path = None

        ''' Initialize logging and set the loglevel if provided '''

        logging.setLoggerClass(InstallLogger)

        global LOGGER

        LOGGER = InstallLogger.manager.getLogger(INSTALL_LOGGER_NAME,

        InstallLogger.ENGINE = self

        if not isinstance(LOGGER, InstallLogger):

            # Occurs if some module has called logging.getLogger prior to

            # this function being run. As this means we don't have control

            # over the logger associated with INSTALL_LOGGER_NAME, there's

            # a programming error and we need to abort

            raise LogInitError("Wrong logger class: got %s, expected %s" %

                               (LOGGER.__class__, InstallLogger))

    @classmethod

    def get_instance(cls):

        '''Returns the InstallEngine singleton'''

        if cls._instance is None:

            raise SingletonError("%s not yet initialized" % cls)

        return cls._instance

    @property

    def dataset(self):

        ''' Returns the ZFS dataset to used for stop/resume '''

        return self._dataset

    @dataset.setter

    def dataset(self, dataset):

        ''' Sets the dataset to be used for stop/resume '''

        if dataset is not None and not isinstance(dataset, Filesystem):

            dataset = Filesystem(dataset)

        self._dataset = dataset

    def register_checkpoint(self, checkpoint_name, module_path,

                            checkpoint_class_name, insert_before=None,

                            loglevel=None, args=(), kwargs=None):

        '''Input:

            * checkpoint_name(required): Name used for referring to the

              checkpoint after registration.  This name must be unique among

              the list of registered checkpoints.  Furthermore,

              checkpoint names are restricted to have only

              ASCII letters, numbers, dots, dashes and underscore.

              Length of the name must be less than 256 characters.

            * module_path (required): Path of the module containing the

              checkpoint implementation.  Value provided will be used in the

              Python imp.find_module() call.  If a relative path is provided,

              it must be resolvable by the PYTHONPATH.  If a full path is

              provided and the path is outside of

              the python sys.path, the ImportWarning will be raised.

            * checkpoint_class_name(required): a string specifying the

              class name of the checkpoint object to be instantiated.

            * args (optional): One or more arguments can be specified for the

              constructor of the checkpoint object.  The order in which the

              arguments are specified will be the order in which they are

              passed.  By default, no arguments are passed.

            * insert_before(optional): Insert this checkpoint before the

              named checkpoint.  The named checkpoint must have been

              previously registered, and it must have not been executed.

              Even though this argument comes after the *args parameter,

              it will not be passed into the constructor of the checkpoint

              object.  Because Python does not allow keyword arguments to

              appear before arguments, it has to come after the args parameter.

            * Log level for checkpoint(optional): If the application wants to

              use a different log level for the checkpoint, it can specify

              it using the keyword argument loglevel=<log_level>.  The

              log level specified must be valid for the log service.

              The value specified in the loglevel keyword will be used by

              the engine as part of setup prior to a checkpoint's execution.

              The loglevel keyword argument will not get passed into the

              constructor of the checkpoint.

            * kwargs(optional): One or more keyword arguments can be

              specified for the constructor of the checkpoint object.

              The order in which the keyword arguments are specified will

              be the order in which they are passed.  By default, no keyword

              arguments are passed.

        Output:

            None

        Raise:

            * ImportError: Error in finding the specified module or

              checkpoint object in the module.

            * ChkptRegistrationError: This error will be raised for the

              any problem with registering the checkpoint.  The error message

              will indicate the exact cause of the problem.

            * UnknownChkptError: Name specified in insert_before argument

              is not found.

            * ChkptExecutedError: The checkpoint specified in the

              insert_before argument has been executed.

            * ValueError: Provided loglevel is not valid.

            * ImportWarning: The provide module path from which the module

              will be imported is outside of sys.path.

        '''

        # Checkpoint registration can not happen while checkpoint's execution

        # is in progress.  Make sure we are not in the middle of

        # executing checkpoints

        if self._is_executing_checkpoints():

            raise ChkptRegistrationError("Checkpoint registration is "

                "not allowed during checkpoint execution.")

        if checkpoint_name is None:

            raise ChkptRegistrationError("checkpoint_name must be specified.")

        if (len(checkpoint_name)) < 1 or (len(checkpoint_name) > 256):

            raise ChkptRegistrationError("Length of checkpoint_name must be "

                                         "between 1-256 characters.")

        # Verify checkpoint names are restricted to have only

        # ASCII letters, numbers, dots, dashes and underscore.

        allowed = set(string.ascii_letters + string.digits + '.' + '-' + '_')

        if set(checkpoint_name) > allowed:

            raise ChkptRegistrationError("checkpoint_name is restricted to "

                                         "have only ASCII letters, numbers, "

                                         "dots, dashes and underscore.")

        if (module_path is None) or (module_path == ""):

            raise ChkptRegistrationError("module_path must not be " +

                                         str(module_path))

        if (checkpoint_class_name is None) or (checkpoint_class_name == ""):

            raise ChkptRegistrationError("checkpoint_class_name must not be " +

                                         str(checkpoint_class_name))

        LOGGER.debug("Engine registering:")

        LOGGER.debug("name: " + str(checkpoint_name))

        LOGGER.debug("module_path: " + str(module_path))

        LOGGER.debug("checkpoint_class_name: " + str(checkpoint_class_name))

        LOGGER.debug("args: " + str(args))

        LOGGER.debug("kwargs: " + str(kwargs))

        LOGGER.debug("insert_before: " + str(insert_before))

        LOGGER.debug("log_level: " + str(loglevel))

        LOGGER.debug("=============================")

        # Go through list of existing checkpoints, and make sure the name

        # has not already been used, and insert_before value, if defined,

        # has not been executed.

        insert_index = len(self._checkpoints)

        for cp in self._checkpoints:

            if (cp.name == checkpoint_name):

                raise ChkptRegistrationError(checkpoint_name +

                                             " has already been used.")

            if (cp.name == insert_before):

                if cp.completed:

                    raise ChkptRegistrationError(insert_before +

                                                 " has been executed.")

                else:

                    insert_index = self._checkpoints.index(cp)

        if (insert_before is not None and

            insert_index == len(self._checkpoints)):

            raise ChkptRegistrationError("insert_before checkpoint: " + \

                insert_before + "is not a valid checkpoint")

        if module_path.startswith('/'):

            mod_name = os.path.basename(module_path)

            mod_path = os.path.dirname(module_path)

        else:

            mod_name = module_path

            mod_path = None

        chkp_data = CheckpointData(checkpoint_name, mod_name, mod_path,

                                   checkpoint_class_name, loglevel,

                                   args, kwargs)

        chkp_data.validate_checkpoint_info()

        self._checkpoints.insert(insert_index, chkp_data)

        LOGGER.debug("Current checkpoint list:")

        if LOGGER.isEnabledFor(logging.DEBUG):

            for cp in self._checkpoints:

                LOGGER.debug("\t" + str(cp))

    def execute_checkpoints(self, start_from=None, pause_before=None,

                            dry_run=False, callback=None):

        ''' Execute all checkpoints in registration order, from start_from to

            pause_before.  The checkpoint specified at pause_before is not

            executed.

        Input:

            * start_from: optional.  name of the checkpoint to start

              execution from. If start_from is None or not specified,

              the engine will look up the first unexecuted checkpoint

              and start from there. If given, and start_from is a

              previously completed checkpoint, the engine will rollback

              to that state before execution (reverting both the persistent

              DOC and ZFS dataset, if set, in the process)

            * pause_before: optional.  Name of checkpoint to stop execution at.

              If pause_before is None or not specified, execution will

              continue until all registered checkpoints are executed.

            * dry_run: optional.  This flag will be passed to the execute()

              function of the checkpoint.  It is up to the checkpoint to

              interpret this flag.

            * Callback: optional.  function to call immediately before the

              thread executing checkpoints exits.  If a callback function is

              provided, execute_checkpoints() will return immediately after

              all preparation for executing checkpoints are completed.

              If a callback function is not provided, the execute_checkpoints()

              function will not return until the thread executing

              checkpoints exits.

        Output:

            * If a callback function is provided, this function

              returns nothing.  The provided callback

              function will be called with status and failed_checkpoint_list

              information as specified below.

            * A tuple (status, failed_checkpoint_list) is returned if

              a callback function is not provided when the function is called.

                > status: indicates whether all checkpoints are executed

                  successfully.  It will have a value of

                  InstallEngine.EXEC_SUCCESS, InstallEngine.EXEC_FAILED or

                  InstallEngine.EXEC_CANCELED or InstallEngine.CP_INIT_FAILED

                > failed_checkpoint_list: The name(s) of checkpoints failed

                  if status is InstallEngine.EXEC_FAILED or

                  InstallEngine.CP_INIT_FAILED. The

                  exception(s) raised by checkpoint's methods

                  are stored in the errsvc.  The application should look

                  up exception associated with the failed checkpoints using

                  the checkpoint name.

        Raise:

            * UnknownCheckpointError: Name specified in start_from or

              pause_before argument is not found

            * CheckpointOrderError: 2 conditions can cause this error:

              1) There are unexecuted checkpoints before the start_from

              checkpoint.

              2) start_from checkpoint is not before pause_at checkpoint.

        '''

        blocking = callback is None

        if blocking:

            callback = self.__blocking_callback

            thread_cls = InstallEngine._PseudoThread

        else:

            thread_cls = threading.Thread