includes/externalstore/ExternalStore.php

   1 <?php
   2 /**
   3  * @defgroup ExternalStorage ExternalStorage
   4  */
   5
   6 /**
   7  * Interface for data storage in external repositories.
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License along
  20  * with this program; if not, write to the Free Software Foundation, Inc.,
  21  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  22  * http://www.gnu.org/copyleft/gpl.html
  23  *
  24  * @file
  25  */
  26
  27 /**
  28  * Constructor class for key/value blob data kept in external repositories.
  29  *
  30  * Objects in external stores are defined by a special URL. The URL is of
  31  * the form "<store protocol>://<location>/<object name>". The protocol is used
  32  * to determine what ExternalStoreMedium class is used. The location identifies
  33  * particular storage instances or database clusters for store class to use.
  34  *
  35  * When an object is inserted into a store, the calling code uses a partial URL of
  36  * the form "<store protocol>://<location>" and receives the full object URL on success.
  37  * This is useful since object names can be sequential IDs, UUIDs, or hashes.
  38  * Callers are not responsible for unique name generation.
  39  *
  40  * External repositories might be populated by maintenance/async
  41  * scripts, thus partial moving of data may be possible, as well
  42  * as the possibility to have any storage format (i.e. for archives).
  43  *
  44  * @ingroup ExternalStorage
  45  */
  46 class ExternalStore {
  47         /**
  48          * Get an external store object of the given type, with the given parameters
  49          *
  50          * @param string $proto Type of external storage, should be a value in $wgExternalStores
  51          * @param array $params Associative array of ExternalStoreMedium parameters
  52          * @return ExternalStoreMedium|bool The store class or false on error
  53          */
  54         public static function getStoreObject( $proto, array $params = array() ) {
  55                 global $wgExternalStores;
  56
  57                 if ( !$wgExternalStores || !in_array( $proto, $wgExternalStores ) ) {
  58                         return false; // protocol not enabled
  59                 }
  60
  61                 $class = 'ExternalStore' . ucfirst( $proto );
  62                 // Any custom modules should be added to $wgAutoLoadClasses for on-demand loading
  63                 return class_exists( $class ) ? new $class( $params ) : false;
  64         }
  65
  66         /**
  67          * Fetch data from given URL
  68          *
  69          * @param string $url The URL of the text to get
  70          * @param array $params Associative array of ExternalStoreMedium parameters
  71          * @return string|bool The text stored or false on error
  72          * @throws MWException
  73          */
  74         public static function fetchFromURL( $url, array $params = array() ) {
  75                 $parts = explode( '://', $url, 2 );
  76                 if ( count( $parts ) != 2 ) {
  77                         return false; // invalid URL
  78                 }
  79
  80                 list( $proto, $path ) = $parts;
  81                 if ( $path == '' ) { // bad URL
  82                         return false;
  83                 }
  84
  85                 $store = self::getStoreObject( $proto, $params );
  86                 if ( $store === false ) {
  87                         return false;
  88                 }
  89
  90                 return $store->fetchFromURL( $url );
  91         }
  92
  93         /**
  94          * Fetch data from multiple URLs with a minimum of round trips
  95          *
  96          * @param array $urls The URLs of the text to get
  97          * @return array Map from url to its data.  Data is either string when found
  98          *     or false on failure.
  99          */
 100         public static function batchFetchFromURLs( array $urls ) {
 101                 $batches = array();
 102                 foreach ( $urls as $url ) {
 103                         $scheme = parse_url( $url, PHP_URL_SCHEME );
 104                         if ( $scheme ) {
 105                                 $batches[$scheme][] = $url;
 106                         }
 107                 }
 108                 $retval = array();
 109                 foreach ( $batches as $proto => $batchedUrls ) {
 110                         $store = self::getStoreObject( $proto );
 111                         if ( $store === false ) {
 112                                 continue;
 113                         }
 114                         $retval += $store->batchFetchFromURLs( $batchedUrls );
 115                 }
 116                 // invalid, not found, db dead, etc.
 117                 $missing = array_diff( $urls, array_keys( $retval ) );
 118                 if ( $missing ) {
 119                         foreach ( $missing as $url ) {
 120                                 $retval[$url] = false;
 121                         }
 122                 }
 123                 return $retval;
 124         }
 125
 126         /**
 127          * Store a data item to an external store, identified by a partial URL
 128          * The protocol part is used to identify the class, the rest is passed to the
 129          * class itself as a parameter.
 130          *
 131          * @param string $url A partial external store URL ("<store type>://<location>")
 132          * @param $data string
 133          * @param array $params Associative array of ExternalStoreMedium parameters
 134          * @return string|bool The URL of the stored data item, or false on error
 135          * @throws MWException
 136          */
 137         public static function insert( $url, $data, array $params = array() ) {
 138                 $parts = explode( '://', $url, 2 );
 139                 if ( count( $parts ) != 2 ) {
 140                         return false; // invalid URL
 141                 }
 142
 143                 list( $proto, $path ) = $parts;
 144                 if ( $path == '' ) { // bad URL
 145                         return false;
 146                 }
 147
 148                 $store = self::getStoreObject( $proto, $params );
 149                 if ( $store === false ) {
 150                         return false;
 151                 } else {
 152                         return $store->store( $path, $data );
 153                 }
 154         }
 155
 156         /**
 157          * Like insert() above, but does more of the work for us.
 158          * This function does not need a url param, it builds it by
 159          * itself. It also fails-over to the next possible clusters.
 160          *
 161          * @param $data string
 162          * @param array $params Associative array of ExternalStoreMedium parameters
 163          * @return string|bool The URL of the stored data item, or false on error
 164          * @throws MWException
 165          */
 166         public static function insertToDefault( $data, array $params = array() ) {
 167                 global $wgDefaultExternalStore;
 168
 169                 $error = false;
 170                 $tryStores = (array)$wgDefaultExternalStore;
 171                 while ( count( $tryStores ) > 0 ) {
 172                         $index = mt_rand( 0, count( $tryStores ) - 1 );
 173                         $storeUrl = $tryStores[$index];
 174                         wfDebug( __METHOD__ . ": trying $storeUrl\n" );
 175                         list( $proto, $path ) = explode( '://', $storeUrl, 2 );
 176                         $store = self::getStoreObject( $proto, $params );
 177                         if ( $store === false ) {
 178                                 throw new MWException( "Invalid external storage protocol - $storeUrl" );
 179                         }
 180                         try {
 181                                 $url = $store->store( $path, $data ); // Try to save the object
 182                         } catch ( MWException $error ) {
 183                                 $url = false;
 184                         }
 185                         if ( strlen( $url ) ) {
 186                                 return $url; // Done!
 187                         } else {
 188                                 unset( $tryStores[$index] ); // Don't try this one again!
 189                                 $tryStores = array_values( $tryStores ); // Must have consecutive keys
 190                                 wfDebugLog( 'ExternalStorage',
 191                                         "Unable to store text to external storage $storeUrl" );
 192                         }
 193                 }
 194                 // All stores failed
 195                 if ( $error ) {
 196                         throw $error; // rethrow the last error
 197                 } else {
 198                         throw new MWException( "Unable to store text to external storage" );
 199                 }
 200         }
 201
 202         /**
 203          * @param $data string
 204          * @param $wiki string
 205          * @return string|bool The URL of the stored data item, or false on error
 206          * @throws MWException
 207          */
 208         public static function insertToForeignDefault( $data, $wiki ) {
 209                 return self::insertToDefault( $data, array( 'wiki' => $wiki ) );
 210         }
 211 }