#!/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

#

#

# Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved.

#

"""This module provides the supported, documented interface for clients to

interface with the pkg(5) system.

Refer to pkg.api_common for additional core class documentation."""

import collections

import copy

import errno

import fnmatch

import os

import shutil

import sys

import threading

import urllib

import pkg.client.actuator as actuator

import pkg.client.api_errors as apx

import pkg.client.bootenv as bootenv

import pkg.client.history as history

import pkg.client.image as image

import pkg.client.imagetypes as imgtypes

import pkg.client.indexer as indexer

import pkg.client.publisher as publisher

import pkg.client.query_parser as query_p

import pkg.fmri as fmri

import pkg.misc as misc

import pkg.nrlock

import pkg.p5i as p5i

import pkg.search_errors as search_errors

import pkg.version

from pkg.api_common import (PackageInfo, LicenseInfo, PackageCategory,

    _get_pkg_cat_data)

from pkg.client.imageplan import EXECUTED_OK

from pkg.client import global_settings

CURRENT_API_VERSION = 43

CURRENT_P5I_VERSION = 1

# Image type constants.

IMG_TYPE_NONE = imgtypes.IMG_NONE # No image.

IMG_TYPE_ENTIRE = imgtypes.IMG_ENTIRE # Full image ('/').

IMG_TYPE_PARTIAL = imgtypes.IMG_PARTIAL  # Not yet implemented.

IMG_TYPE_USER = imgtypes.IMG_USER # Not '/'; some other location.

logger = global_settings.logger

class ImageInterface(object):

        """This class presents an interface to images that clients may use.

        There is a specific order of methods which must be used to install

        or uninstall packages, or update an image. First, plan_install,

        plan_uninstall, plan_update_all or plan_change_variant must be

        called.  After that method completes successfully, describe may be

        called, and prepare must be called. Finally, execute_plan may be

        called to implement the previous created plan. The other methods

        do not have an ordering imposed upon them, and may be used as

        needed. Cancel may only be invoked while a cancelable method is

        running."""

        # Constants used to reference specific values that info can return.

        INFO_FOUND = 0

        INFO_MISSING = 1

        INFO_ILLEGALS = 3

        LIST_ALL = 0

        LIST_INSTALLED = 1

        LIST_INSTALLED_NEWEST = 2

        LIST_NEWEST = 3

        LIST_UPGRADABLE = 4

        MATCH_EXACT = 0

        MATCH_FMRI = 1

        MATCH_GLOB = 2

        # Private constants used for tracking which type of plan was made.

        __INSTALL = 1

        __UNINSTALL = 2

        __IMAGE_UPDATE = 3

        def __init__(self, img_path, version_id, progresstracker,

            cancel_state_callable, pkg_client_name):

                """Constructs an ImageInterface object.

                'img_path' is the absolute path to an existing image.

                'version_id' indicates the version of the api the client is

                expecting to use.

                'progresstracker' is the ProgressTracker object the client wants

                the api to use for UI progress callbacks.

                'cancel_state_callable' is an optional function reference that

                will be called if the cancellable status of an operation

                changes.

                'pkg_client_name' is a string containing the name of the client,

                such as "pkg" or "packagemanager".

                This function can raise VersionException and

                ImageNotFoundException."""

                if version_id not in compatible_versions:

                        raise apx.VersionException(CURRENT_API_VERSION,

                            version_id)

                # The image's History object will use client_name from

                # global_settings, but if the program forgot to set it,

                # we'll go ahead and do so here.

                if global_settings.client_name is None:

                        global_settings.client_name = pkg_client_name

                if isinstance(img_path, basestring):

                        # Store this for reset().

                        self.__img_path = img_path

                        self.__img = image.Image(img_path,

                            progtrack=progresstracker)

                elif isinstance(img_path, image.Image):

                        # This is a temporary, special case for client.py

                        # until the image api is complete.

                        self.__img = img_path

                        self.__img_path = img_path.get_root()

                else:

                        # API consumer passed an unknown type for img_path.

                        raise TypeError(_("Unknown img_path type."))

                self.__progresstracker = progresstracker

                self.__cancel_state_callable = cancel_state_callable

                self.__plan_type = None

                self.__plan_desc = None

                self.__prepared = False

                self.__executed = False

                self.__be_name = None

                self.__can_be_canceled = False

                self.__canceling = False

                self.__activity_lock = pkg.nrlock.NRLock()

                self.__blocking_locks = False

                self.__img.blocking_locks = self.__blocking_locks

                self.__cancel_lock = pkg.nrlock.NRLock()

                self.__cancel_cv = threading.Condition(self.__cancel_lock)

                self.__new_be = None # create if needed

        def __set_blocking_locks(self, value):

                self.__activity_lock.acquire()

                self.__blocking_locks = value

                self.__img.blocking_locks = value

                self.__activity_lock.release()

        blocking_locks = property(lambda self: self.__blocking_locks,

            __set_blocking_locks, doc="A boolean value indicating whether "

            "the API should wait until the image interface can be locked if "

            "it is in use by another thread or process.  Clients should be "

            "aware that there is no timeout mechanism in place if blocking is "

            "enabled, and so should take steps to remain responsive to user "

            "input or provide a way for users to cancel operations.")

        @property

        def excludes(self):

                """The list of excludes for the image."""

                return self.__img.list_excludes()

        @property

        def img(self):

                """Private; public access to this property will be removed at

                a later date.  Do not use."""

                return self.__img

        @property

        def img_type(self):

                """Returns the IMG_TYPE constant for the image's type."""

                if not self.__img:

                        return None

                return self.__img.image_type(self.__img.root)

        @property

        def is_zone(self):

                """A boolean value indicating whether the image is a zone."""

                return self.__img.is_zone()

        @property

        def root(self):

                """The absolute pathname of the filesystem root of the image.

                This property is read-only."""

                if not self.__img:

                        return None

                return self.__img.root

        @staticmethod

        def check_be_name(be_name):

                bootenv.BootEnv.check_be_name(be_name)

                return True

        def __cert_verify(self, log_op_end=None):

                """Verify validity of certificates.  Any apx.ExpiringCertificate

                exceptions are caught here, a message is displayed, and

                execution continues.

                All other exceptions will be passed to the calling context.

                The caller can also set log_op_end to a list of exceptions

                that should result in a call to self.log_operation_end()

                before the exception is passed on.

                """

                if log_op_end == None:

                        log_op_end = []

                # we always explicitly handle apx.ExpiringCertificate

                assert apx.ExpiringCertificate not in log_op_end

                try:

                        self.__img.check_cert_validity()

                except apx.ExpiringCertificate, e:

                        logger.error(e)

                except:

                        exc_type, exc_value, exc_traceback = sys.exc_info()

                        if exc_type in log_op_end:

                                self.log_operation_end(error=exc_value)

                        raise

        def __refresh_publishers(self):

                """Refresh publisher metadata."""

                #

                # Verify validity of certificates before possibly

                # attempting network operations.

                #

                self.__cert_verify()

                self.__img.refresh_publishers(immediate=True,

                    progtrack=self.__progresstracker)

        def __acquire_activity_lock(self):

                """Private helper method to aqcuire activity lock."""

                rc = self.__activity_lock.acquire(

                    blocking=self.__blocking_locks)

                if not rc:

                        raise apx.ImageLockedError()

        def __plan_common_start(self, operation, noexecute, new_be, be_name):

                """Start planning an operation:  

                    Acquire locks.

                    Log the start of the operation.

                    Check be_name."""

                self.__acquire_activity_lock()

                try:

                        self.__enable_cancel()

                        if self.__plan_type is not None:

                                raise apx.PlanExistsException(

                                    self.__plan_type)

                        self.__img.lock(allow_unprivileged=noexecute)

                except:

                        self.__cancel_cleanup_exception()

                        self.__activity_lock.release()

                        raise

                assert self.__activity_lock._is_owned()

                self.log_operation_start(operation)

                self.__new_be = new_be

                self.__be_name = be_name

                if self.__be_name is not None:

                        self.check_be_name(be_name)

                        if not self.__img.is_liveroot():

                                raise apx.BENameGivenOnDeadBE(self.__be_name)

        def __plan_common_finish(self):

                """Finish planning an operation."""

                assert self.__activity_lock._is_owned()

                self.__img.cleanup_downloads()

                self.__img.unlock()

                try:

                        if int(os.environ.get("PKG_DUMP_STATS", 0)) > 0:

                                self.__img.transport.stats.dump()

                except ValueError:

                        # Don't generate stats if an invalid value

                        # is supplied.

                        pass

                self.__activity_lock.release()

        def __set_new_be(self):

                """Figure out whether or not we'd create a new boot environment

                given inputs and plan.  Toss cookies if we need a new be and 

                can't have one."""

                # decide whether or not to create new BE.

                if self.__img.is_liveroot():

                        if self.__new_be is None:

                                self.__new_be = self.__img.imageplan.reboot_needed()

                        elif self.__new_be is False and \

                            self.__img.imageplan.reboot_needed():

                                raise apx.ImageUpdateOnLiveImageException()

                else:

                        self.__new_be = False

        def __plan_common_exception(self, log_op_end=None):

                """Deal with exceptions that can occur while planning an

                operation.  Any exceptions generated here are passed

                onto the calling context.  By default all exceptions

                will result in a call to self.log_operation_end() before

                they are passed onto the calling context.  Optionally,

                the caller can specify the exceptions that should result

                in a call to self.log_operation_end() by setting

                log_op_end."""

                if log_op_end == None:

                        log_op_end = []

                # we always explicity handle apx.PlanCreationException

                assert apx.PlanCreationException not in log_op_end

                exc_type, exc_value, exc_traceback = sys.exc_info()

                if exc_type == apx.PlanCreationException:

                        self.__set_history_PlanCreationException(exc_value)

                elif exc_type == apx.CanceledException:

                        self.__cancel_done()

                elif not log_op_end or exc_type in log_op_end:

                        self.log_operation_end(error=exc_value)

                if exc_type != apx.ImageLockedError:

                        # Must be called before reset_unlock, and only if

                        # the exception was not a locked error.

                        self.__img.unlock()

                try:

                        if int(os.environ.get("PKG_DUMP_STATS", 0)) > 0:

                                self.__img.transport.stats.dump()

                except ValueError:

                        # Don't generate stats if an invalid value

                        # is supplied.

                        pass

                self.__reset_unlock()

                self.__activity_lock.release()

                raise

        def plan_install(self, pkg_list, refresh_catalogs=True,

            noexecute=False, update_index=True, be_name=None, new_be=False):

                """Contructs a plan to install the packages provided

                in pkg_list.  pkg_list is a list of packages to

                install.  refresh_catalogs controls whether the

                catalogs will automatically be refreshed. noexecute

                determines whether the history will be recorded after

                planning is finished.  It returns a boolean which

                tells the client whether there is anything to do.  It

                can raise PlanCreationException, PermissionsException

                and InventoryException. The noexecute argument is

                included for compatibility with operational history.

                The hope is it can be removed in the future."""

                self.__plan_common_start("install", noexecute, new_be, be_name)

                try:

                        if refresh_catalogs:

                                self.__refresh_publishers()

                        self.__img.make_install_plan(pkg_list,

                            self.__progresstracker,

                            self.__check_cancelation, noexecute)

                        assert self.__img.imageplan

                        self.__disable_cancel()

                        if not noexecute:

                                self.__plan_type = self.__INSTALL

                        self.__set_new_be()

                        self.__plan_desc = PlanDescription(self.__img, self.__new_be)

                        if self.__img.imageplan.nothingtodo() or noexecute:

                                self.log_operation_end(

                                    result=history.RESULT_NOTHING_TO_DO)

                        self.__img.imageplan.update_index = update_index

                except:

                        self.__plan_common_exception(log_op_end=[

                            apx.CanceledException, fmri.IllegalFmri,

                            Exception])

                        # NOTREACHED

                self.__plan_common_finish()

                res = not self.__img.imageplan.nothingtodo()

                return res

        def plan_uninstall(self, pkg_list, recursive_removal, noexecute=False,

            update_index=True, be_name=None, new_be=False):

                """Contructs a plan to uninstall the packages provided

                in pkg_list. pkg_list is a list of packages to

                install.  recursive_removal controls whether recursive

                removal is allowed. noexecute determines whether the

                history will be recorded after planning is finished.

                If there are things to do to complete the uninstall,

                it returns True, otherwise it returns False. It can

                raise NonLeafPackageException and

                PlanCreationException."""

                self.__plan_common_start("uninstall", noexecute, new_be, be_name)

                try:

                        self.__img.make_uninstall_plan(pkg_list,

                            recursive_removal, self.__progresstracker,

                            self.__check_cancelation, noexecute)

                        assert self.__img.imageplan

                        self.__disable_cancel()

                        if not noexecute:

                                self.__plan_type = self.__UNINSTALL

                        self.__set_new_be()

                        self.__plan_desc = PlanDescription(self.__img, self.__new_be)

                        if noexecute:

                                self.log_operation_end(

                                    result=history.RESULT_NOTHING_TO_DO)

                        self.__img.imageplan.update_index = update_index

                except:

                        self.__plan_common_exception()

                        # NOTREACHED

                self.__plan_common_finish()

                res = not self.__img.imageplan.nothingtodo()

                return res

        def __is_pkg5_native_packaging(self):

                """Helper routine that returns True if this object represents an

                image where pkg(5) is the native packaging system and needs to

                be upgraded before the image can be."""

                # First check to see if the special package "release/name"

                # exists and contains metadata saying this is Solaris.

                results = self.get_pkg_list(self.LIST_INSTALLED,

                    patterns=["release/name"], return_fmris=True)

                results = [e for e in results]

                if results:

                        pfmri, summary, categories, states = \

                            results[0]

                        mfst = self.__img.get_manifest(pfmri)

                        osname = mfst.get("pkg.release.osname", None)

                        if osname == "sunos":

                                return True

                # Otherwise, see if we can find package/pkg (or SUNWipkg) and

                # SUNWcs.

                results = self.get_pkg_list(self.LIST_INSTALLED,

                    patterns=["pkg:/package/pkg", "SUNWipkg", "SUNWcs"])

                installed = set(e[0][1] for e in results)

                if "SUNWcs" in installed and ("SUNWipkg" in installed or

                    "package/pkg" in installed):

                        return True

                return False

        def plan_update_all(self, actual_cmd, refresh_catalogs=True,