zypp/Fetcher.h

   1 /*---------------------------------------------------------------------\
   2 |                          ____ _   __ __ ___                          |
   3 |                         |__  / \ / / . \ . \                         |
   4 |                           / / \ V /|  _/  _/                         |
   5 |                          / /__ | | | | | |                           |
   6 |                         /_____||_| |_| |_|                           |
   7 |                                                                      |
   8 \---------------------------------------------------------------------*/
   9 /** \file       zypp/Fetcher.h
  10  *
  11 */
  12 #ifndef ZYPP_FETCHER_H
  13 #define ZYPP_FETCHER_H
  14
  15 #include <iosfwd>
  16 #include <list>
  17
  18 #include "zypp/base/Flags.h"
  19 #include "zypp/base/PtrTypes.h"
  20 #include "zypp/Pathname.h"
  21 #include "zypp/Url.h"
  22 #include "zypp/OnMediaLocation.h"
  23 #include "zypp/Digest.h"
  24 #include "zypp/MediaSetAccess.h"
  25 #include "zypp/FileChecker.h"
  26 #include "zypp/ProgressData.h"
  27
  28 ///////////////////////////////////////////////////////////////////
  29 namespace zypp
  30 { /////////////////////////////////////////////////////////////////
  31
  32   /**
  33   * This class allows to retrieve a group of files in a confortable
  34   * way, providing some smartness that does not belong to the
  35   * media layer like:
  36   *
  37   * \li Configurable local caches to retrieve already
  38   *     donwloaded files.
  39   * \li File checkers that can check for right checksums
  40   *     digital signatures, etc.
  41   *
  42   * \code
  43   * MediaSetAccess access(url, path);
  44   * Fetcher fetcher;
  45   * fetcher.enqueue( OnMediaLocation().setLocation("/somefile") );
  46   * fetcher.addCachePath("/tmp/cache")
  47   * fetcher.start( "/download-dir, access );
  48   * fetcher.reset();
  49   * \endcode
  50   *
  51   * To use the checkers. just create a functor implementing
  52   * bool operator()(const Pathname &file) \see FileChecker.
  53   * Pass the necessary validation data in the constructor
  54   * of the functor, and pass the object to the \ref enqueue
  55   * method.
  56   *
  57   * \code
  58   * ChecksumFileChecker checker(CheckSum("sha1", "....");
  59   * fetcher.enqueue( location, checker);
  60   * \endcode
  61   *
  62   * If you need to use more than one checker
  63   * \see CompositeFileChecker
  64   *
  65   * Additionally, you can automatically enqueue a job
  66   * with a checksum checker by using \ref enqueueDigested
  67   * which will use the \ref OnMediaLocation checksum
  68   * automatically.
  69   *
  70   * \code
  71   * location.setChecksum(CheckSum("sha1", "...."));
  72   * fetcher.enqueueDigested(location);
  73   * \endcode
  74   *
  75   * \note If the checksum of the location is empty, but
  76   * \ref enqueueDigested is used, then the user will get a
  77   * warning that the file has no checksum.
  78   *
  79   * Additionally, Fetcher supports checking the downloaded
  80   * content by using signed indexes on the remote side.
  81   *
  82   * \code
  83   * MediaSetAccess access(url, path);
  84   * Fetcher fetcher;
  85   * fetcher.addIndex(OnMediaLocation("/content"));
  86   * fetcher.enqueue( OnMediaLocation().setLocation("/somefile") );
  87   * fetcher.start( "/download-dir, access );
  88   * fetcher.reset();
  89   * \endcode
  90   *
  91   * Indexes are supported in CHECKSUMS format (simple text file)
  92   * with checksum and file name, or content file, whith
  93   * HASH SHA1 line entries.
  94   *
  95   * \note The indexes file names are relative to the directory
  96   * where the index is.
  97   *
  98   * \note libzypp-11.x: Introduction of sha256 lead to the insight
  99   * that using SHA1SUMS as filename was a bad choice. New media store
 100   * the checksums in a CHECKSUMS file. If a CHECKSUMS file is not
 101   * present, we fall back looking for a SHA1SUMS file. The checksum
 102   * type (md5,sha1,sha256) is auto detected by looking at the cheksums
 103   * length. No need to somehow encode it in the filename.
 104   */
 105   class Fetcher
 106   {
 107     friend std::ostream & operator<<( std::ostream & str,
 108                                       const Fetcher & obj );
 109   public:
 110     /** Implementation  */
 111     class Impl;
 112   public:
 113
 114     /**
 115      * Various option flags to change behavior
 116      */
 117     enum Option
 118     {
 119       /**
 120        * If a content file is found, it is
 121        * downloaded and read.
 122        */
 123       AutoAddContentFileIndexes = 0x0001,
 124       /**
 125        * If a CHECKSUMS file is found, it is
 126        * downloaded and read.
 127        */
 128       AutoAddChecksumsIndexes = 0x0002,
 129       /**
 130        * If a content or CHECKSUMS file is found,
 131        * it is downloaded and read.
 132        */
 133       AutoAddIndexes = AutoAddContentFileIndexes | AutoAddChecksumsIndexes,
 134     };
 135     ZYPP_DECLARE_FLAGS(Options, Option);
 136
 137     /** Default ctor */
 138     Fetcher();
 139     /** Dtor */
 140     virtual ~Fetcher();
 141
 142   public:
 143
 144    /**
 145     * Set the Fetcher options
 146     * \see Fetcher::Options
 147     */
 148     void setOptions( Options options );
 149
 150    /**
 151     * Get current options
 152     * \see Fetcher::Options
 153     */
 154     Options options() const;
 155
 156    /**
 157     * Adds an index containing metadata (for example
 158     * checksums ) that will be retrieved and read
 159     * before the job processing starts.
 160     *
 161     * Nothing will be transferred or checked
 162     * until \ref start() is called.
 163     *
 164     * The index is relative to the media path, and
 165     * the listed files too.
 166     *
 167     * Indexes in the SHA1SUM format, and YaST
 168     * content file
 169     *
 170     * The file has to be signed or the user will be
 171     * warned that the file is unsigned. You can
 172     * place the signature next to the file adding the
 173     * .asc extension.
 174     *
 175     * If you expect the key to not to be in the target
 176     * system, then you can place it next to the index
 177     * using adding the .key extension.
 178     *
 179     */
 180     void addIndex( const OnMediaLocation &resource );
 181
 182    /**
 183     * Enqueue a object for transferal, they will not
 184     * be transferred until \ref start() is called
 185     *
 186     */
 187     void enqueue( const OnMediaLocation &resource,
 188                   const FileChecker &checker = FileChecker() );
 189
 190     /**
 191     * Enqueue a object for transferal, they will not
 192     * be transferred until \ref start() is called
 193     *
 194     * \note As \ref OnMediaLocation contains the digest information,
 195     * a \ref ChecksumFileChecker is automatically added to the
 196     * transfer job, so make sure you don't add another one or
 197     * the user could be asked twice.
 198     *
 199     * \todo FIXME implement checker == operator to avoid this.
 200     *
 201     * the optional deltafile argument describes a file that can
 202     * be used for delta download algorithms. Usable files are
 203     * uncompressed files or files compressed with gzip --rsyncable.
 204     * Other files like rpms do not work, as the compression
 205     * breaks the delta algorithm.
 206     */
 207     void enqueueDigested( const OnMediaLocation &resource,
 208                           const FileChecker &checker = FileChecker(), const Pathname &deltafile = Pathname());
 209
 210
 211     /**
 212      * Enqueue a directory
 213      *
 214      * As the files to be enqueued are not known
 215      * in advance, all files whose checksum can
 216      * be found in some index are enqueued with
 217      * checksum checking. Otherwise they are not.
 218      *
 219      * Some index may provide
 220      * the checksums, either by \ref addIndex or
 221      * using \ref AutoAddIndexes flag.
 222      *
 223      * Files are checked by providing a
 224      * CHECKSUMS or content file listing
 225      * <checksum> filename
 226      * and a respective CHECKSUMS.asc/content.asc which has
 227      * the signature for the checksums.
 228      *
 229      * If you expect the user to not have the key of
 230      * the signature either in the trusted or untrusted
 231      * keyring, you can offer it as CHECKSUMS.key (or content.key)
 232      *
 233      * \param recursive True if the complete tree should
 234      * be enqueued.
 235      *
 236      * \note As \ref checksums are read from the index,
 237      * a \ref ChecksumFileChecker is automatically added to
 238      * transfer jobs having a checksum available,
 239      * so make sure you don't add another one or
 240      * the user could be asked twice.
 241      *
 242      * \note The format of the file CHECKSUMS is the output of:
 243      * ls | grep -v CHECKSUMS | xargs sha256sum > CHECKSUMS
 244      * in each subdirectory.
 245      *
 246      * \note Every file CHECKSUMS.* except of CHECKSUMS.(asc|key|(void)) will
 247      * not be transferred and will be ignored.
 248      *
 249      */
 250     void enqueueDir( const OnMediaLocation &resource,
 251                      bool recursive = false,
 252                      const FileChecker &checker = FileChecker() );
 253
 254     /**
 255      * Enqueue a directory and always check for
 256      * checksums.
 257      *
 258      * As the files to be enqueued are not known
 259      * in advance, all files are enqueued with
 260      * checksum checking. If the checksum of some file is
 261      * not in some index, then there will be a verification
 262      * warning ( \ref DigestReport ).
 263      *
 264      * Therefore some index will need to provide
 265      * the checksums, either by \ref addIndex or
 266      * using \ref AutoAddIndexes flag.
 267      *
 268      * Files are checked by providing a
 269      * CHECKSUMS or content file listing
 270      * <checksum> filename
 271      * and a respective CHECKSUMS.asc/content.asc which has
 272      * the signature for the checksums.
 273      *
 274      * If you expect the user to not have the key of
 275      * the signature either in the trusted or untrusted
 276      * keyring, you can offer it as CHECKSUMS.key (or content.key)
 277      *
 278      * \param recursive True if the complete tree should
 279      * be enqueued.
 280      *
 281      * \note As \ref checksums are read from the index,
 282      * a \ref ChecksumFileChecker is automatically added to every
 283      * transfer job, so make sure you don't add another one or
 284      * the user could be asked twice.
 285      *
 286      * \note The format of the file CHECKSUMS is the output of:
 287      * ls | grep -v CHECKSUMS | xargs sha256sum > CHECKSUMS
 288      * in each subdirectory.
 289      *
 290      * \note Every file CHECKSUMS.* except of CHECKSUMS.(asc|key|(void)) will
 291      * not be transferred and will be ignored.
 292      *
 293      */
 294     void enqueueDigestedDir( const OnMediaLocation &resource,
 295                              bool recursive = false,
 296                              const FileChecker &checker = FileChecker() );
 297
 298     /**
 299     * adds a directory to the list of directories
 300     * where to look for cached files
 301     */
 302     void addCachePath( const Pathname &cache_dir );
 303
 304     /**
 305      * Reset the transfer (jobs) list
 306      * \note It does not reset the cache directory list
 307      */
 308     void reset();
 309
 310     /**
 311     * start the transfer to a destination directory
 312     * \a dest_dir
 313     * You have to provde a media set access
 314     * \a media to get the files from
 315     * The file tree will be replicated inside this
 316     * directory
 317     *
 318     */
 319     void start( const Pathname &dest_dir,
 320                 MediaSetAccess &media,
 321                 const ProgressData::ReceiverFnc & progress = ProgressData::ReceiverFnc() );
 322
 323   private:
 324     /** Pointer to implementation */
 325     RWCOW_pointer<Impl> _pimpl;
 326   };
 327   ///////////////////////////////////////////////////////////////////
 328   ZYPP_DECLARE_OPERATORS_FOR_FLAGS(Fetcher::Options);
 329
 330   /** \relates Fetcher Stream output */
 331   std::ostream & operator<<( std::ostream & str, const Fetcher & obj );
 332
 333   /////////////////////////////////////////////////////////////////
 334 } // namespace zypp
 335 ///////////////////////////////////////////////////////////////////
 336 #endif // ZYPP_FETCHER_H