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

#

#

#

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

interface with the pkg(5) system.

Refer to pkg.api_common and pkg.plandesc for additional core class

documentation.

Consumers should catch ApiException when calling any API function, and

may optionally catch any subclass of ApiException for further, specific

error handling.

"""

#

# this file is not completely pylint clean

#

# pylint: disable=C0111,C0301,C0321,E0702,R0201,W0102

# pylint: disable=W0212,W0511,W0612,W0613,W0702

#

# C0111 Missing docstring

# C0301 Line too long

# C0321 More than one statement on a single line

# E0702 Raising NoneType while only classes, instances or string are allowed

# R0201 Method could be a function

# W0102 Dangerous default value %s as argument

# W0212 Access to a protected member %s of a client class

# W0511 XXX

# W0612 Unused variable '%s'

# W0613 Unused argument '%s'

# W0702 No exception type(s) specified

#

import collections

import copy

import datetime

import errno

import fnmatch

import glob

import os

import shutil

import simplejson as json

import sys

import tempfile

import threading

import time

import urllib

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.imageconfig as imgcfg

import pkg.client.imageplan as imageplan

import pkg.client.imagetypes as imgtypes

import pkg.client.indexer as indexer

import pkg.client.pkgdefs as pkgdefs

import pkg.client.plandesc as plandesc

import pkg.client.publisher as publisher

import pkg.client.query_parser as query_p

import pkg.fmri as fmri

import pkg.mediator as med

import pkg.misc as misc

import pkg.nrlock

import pkg.p5i as p5i

import pkg.p5s as p5s

import pkg.portable as portable

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 import global_settings

from pkg.client.debugvalues import DebugValues

from pkg.client.pkgdefs import * # pylint: disable=W0401

from pkg.smf import NonzeroExitException

# we import PlanDescription here even though it isn't used so that consumers

# of the api still have access to the class definition and are able to do

# things like help(pkg.client.api.PlanDescription)

from pkg.client.plandesc import PlanDescription # pylint: disable=W0611

CURRENT_API_VERSION = 76

COMPATIBLE_API_VERSIONS = frozenset([72, 73, 74, 75, CURRENT_API_VERSION])

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.

# History result constants.

RESULT_CANCELED = history.RESULT_CANCELED

RESULT_NOTHING_TO_DO = history.RESULT_NOTHING_TO_DO

RESULT_SUCCEEDED = history.RESULT_SUCCEEDED

RESULT_FAILED_BAD_REQUEST = history.RESULT_FAILED_BAD_REQUEST

RESULT_FAILED_CONFIGURATION = history.RESULT_FAILED_CONFIGURATION

RESULT_FAILED_CONSTRAINED = history.RESULT_FAILED_CONSTRAINED

RESULT_FAILED_LOCKED = history.RESULT_FAILED_LOCKED

RESULT_FAILED_SEARCH = history.RESULT_FAILED_SEARCH

RESULT_FAILED_STORAGE = history.RESULT_FAILED_STORAGE

RESULT_FAILED_TRANSPORT = history.RESULT_FAILED_TRANSPORT

RESULT_FAILED_ACTUATOR = history.RESULT_FAILED_ACTUATOR

RESULT_FAILED_OUTOFMEMORY = history.RESULT_FAILED_OUTOFMEMORY

RESULT_CONFLICTING_ACTIONS = history.RESULT_CONFLICTING_ACTIONS

RESULT_FAILED_UNKNOWN = history.RESULT_FAILED_UNKNOWN

# Globals.

logger = global_settings.logger

class _LockedGenerator(object):

        """This is a private class and should not be used by API consumers.

        This decorator class wraps API generator functions, managing the

        activity and cancelation locks.  Due to implementation differences

        in the decorator protocol, the decorator must be used with

        parenthesis in order for this to function correctly.  Always

        decorate functions @_LockedGenerator()."""

        def __init__(self, *d_args, **d_kwargs):

                object.__init__(self)

        def __call__(self, f):

                def wrapper(*fargs, **f_kwargs):

                        instance, fargs = fargs[0], fargs[1:]

                        instance._acquire_activity_lock()

                        instance._enable_cancel()

                        clean_exit = True

                        canceled = False

                        try:

                                for v in f(instance, *fargs, **f_kwargs):

                                        yield v

                        except GeneratorExit:

                                return

                        except apx.CanceledException:

                                canceled = True

                                raise

                        except Exception:

                                clean_exit = False

                                raise

                        finally:

                                if canceled:

                                        instance._cancel_done()

                                elif clean_exit:

                                        try:

                                                instance._disable_cancel()

                                        except apx.CanceledException:

                                                instance._cancel_done()

                                                instance._activity_lock.release()

                                                raise

                                else:

                                        instance._cancel_cleanup_exception()

                                instance._activity_lock.release()

                return wrapper

class _LockedCancelable(object):

        """This is a private class and should not be used by API consumers.

        This decorator class wraps non-generator cancelable API functions,

        managing the activity and cancelation locks.  Due to implementation

        differences in the decorator protocol, the decorator must be used with

        parenthesis in order for this to function correctly.  Always

        decorate functions @_LockedCancelable()."""

        def __init__(self, *d_args, **d_kwargs):

                object.__init__(self)

        def __call__(self, f):

                def wrapper(*fargs, **f_kwargs):

                        instance, fargs = fargs[0], fargs[1:]

                        instance._acquire_activity_lock()

                        instance._enable_cancel()

                        clean_exit = True

                        canceled = False

                        try:

                                return f(instance, *fargs, **f_kwargs)

                        except apx.CanceledException:

                                canceled = True

                                raise

                        except Exception:

                                clean_exit = False

                                raise

                        finally:

                                instance._img.cleanup_downloads()

                                try:

                                        if int(os.environ.get("PKG_DUMP_STATS",

                                            0)) > 0:

                                                instance._img.transport.stats.dump()

                                except ValueError:

                                        # Don't generate stats if an invalid

                                        # value is supplied.

                                        pass

                                if canceled:

                                        instance._cancel_done()

                                elif clean_exit:

                                        try:

                                                instance._disable_cancel()

                                        except apx.CanceledException:

                                                instance._cancel_done()

                                                # if f() acquired the image

                                                # lock, drop it

                                                if instance._img.locked:

                                                        instance._img.unlock()

                                                instance._activity_lock.release()

                                                raise

                                else:

                                        instance._cancel_cleanup_exception()

                                # if f() acquired the image lock, drop it

                                if instance._img.locked:

                                        instance._img.unlock()

                                instance._activity_lock.release()

                return wrapper

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, a gen_plan_* method

        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."""

        FACET_ALL = 0

        FACET_IMAGE = 1

        FACET_INSTALLED = 2

        FACET_SRC_SYSTEM = pkg.facet.Facets.FACET_SRC_SYSTEM

        FACET_SRC_LOCAL = pkg.facet.Facets.FACET_SRC_LOCAL

        FACET_SRC_PARENT = pkg.facet.Facets.FACET_SRC_PARENT

        # 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

        VARIANT_ALL = 0

        VARIANT_ALL_POSSIBLE = 1

        VARIANT_IMAGE = 2

        VARIANT_IMAGE_POSSIBLE = 3

        VARIANT_INSTALLED = 4

        VARIANT_INSTALLED_POSSIBLE = 5

        def __init__(self, img_path, version_id, progresstracker,

            cancel_state_callable, pkg_client_name, exact_match=True,

            cmdpath=None):

                """Constructs an ImageInterface object.

                'img_path' is the absolute path to an existing image or to a

                path from which to start looking for an image.  To control this

                behaviour use the 'exact_match' parameter.

                '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".

                'exact_match' is a boolean indicating whether the API should

                attempt to find a usable image starting from the specified

                directory, going up to the filesystem root until it finds one.

                If set to True, an image must exist at the location indicated

                by 'img_path'.

                """

                if version_id not in COMPATIBLE_API_VERSIONS:

                        raise apx.VersionException(CURRENT_API_VERSION,

                            version_id)

                if sys.path[0].startswith("/dev/fd/"):

                        #

                        # Normally when the kernel forks off an interpreted

                        # program, it executes the interpreter with the first

                        # argument being the path to the interpreted program

                        # we're executing.  But in the case of suid scripts

                        # this presents a security problem because that path

                        # could be updated after exec but before the

                        # interpreter opens reads the program.  To avoid this

                        # race, for suid script the kernel replaces the name

                        # of the interpreted program with /dev/fd/###, and

                        # opens the interpreted program such that it can be

                        # read from the specified file descriptor device node.

                        # So if we detect that path[0] (which should be then

                        # interpreted program name) is a /dev/fd/ path, that

                        # means we're being run as an suid script, which we

                        # don't really want to support.  (Since this breaks

                        # our subsequent code that attempt to determine the

                        # name of the executable we are running as.)

                        #

                        raise apx.SuidUnsupportedError()

                # 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 cmdpath == None:

                        cmdpath = misc.api_cmdpath()

                self.cmdpath = cmdpath

                # prevent brokeness in the test suite

                if self.cmdpath and \

                    "PKG_NO_RUNPY_CMDPATH" in os.environ and \

                    self.cmdpath.endswith(os.sep + "run.py"):

                        raise RuntimeError, """

An ImageInterface object was allocated from within ipkg test suite and

cmdpath was not explicitly overridden.  Please make sure to set

explicitly set cmdpath when allocating an ImageInterface object, or

override cmdpath when allocating an Image object by setting PKG_CMDPATH

in the environment or by setting simulate_cmdpath in DebugValues."""

                if isinstance(img_path, basestring):

                        # Store this for reset().

                        self._img_path = img_path

                        self._img = image.Image(img_path,

                            progtrack=progresstracker,

                            user_provided_dir=exact_match,

                            cmdpath=self.cmdpath)

                        # Store final image path.

                        self._img_path = self._img.get_root()

                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

                lin = None

                if self._img.linked.ischild():

                        lin = self._img.linked.child_name

                self.__progresstracker.set_linked_name(lin)

                self.__cancel_state_callable = cancel_state_callable

                self.__plan_type = None

                self.__api_op = None

                self.__plan_desc = None

                self.__planned_children = False

                self.__prepared = False

                self.__executed = False

                self.__be_activate = True

                self.__backup_be_name = None

                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.__backup_be = None # create if needed

                self.__new_be = None # create if needed

                self.__alt_sources = {}

        def __set_blocking_locks(self, value):

                self._activity_lock.acquire()

                self.__blocking_locks = value

                self._img.blocking_locks = value

                self._activity_lock.release()

        def __set_img_alt_sources(self, repos):

                """Private helper function to change image to use alternate

                package sources if applicable."""

                # When using alternate package sources with the image, the

                # result is a composite of the package data already known

                # by the image and the alternate sources.

                if repos:

                        self._img.set_alt_pkg_sources(

                            self.__get_alt_pkg_data(repos))

                else:

                        self._img.set_alt_pkg_sources(None)

        @_LockedCancelable()

        def set_alt_repos(self, repos):

                """Public function to specify alternate package sources."""

                self.__set_img_alt_sources(repos)

        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_liveroot(self):

                """A boolean indicating whether the image to be modified is

                for the live system root."""

                return self._img.is_liveroot()

        @property

        def is_zone(self):

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

                return self._img.is_zone()

        @property

        def is_active_liveroot_be(self):

                """A boolean indicating whether the image to be modified is

                the active BE for the system's root image."""

                if not self._img.is_liveroot():

                        return False

                try:

                        be_name, be_uuid = bootenv.BootEnv.get_be_name(

                            self._img.root)

                        return be_name == \

                            bootenv.BootEnv.get_activated_be_name()

                except apx.BEException:

                        # If boot environment logic isn't supported, return

                        # False.  This is necessary for user images and for

                        # the test suite.

                        return False

        @property