includes/libs/filebackend/filejournal/FileJournal.php

   1 <?php
   2 /**
   3  * @defgroup FileJournal File journal
   4  * @ingroup FileBackend
   5  */
   6
   7 /**
   8  * File operation journaling.
   9  *
  10  * This program is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License as published by
  12  * the Free Software Foundation; either version 2 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License along
  21  * with this program; if not, write to the Free Software Foundation, Inc.,
  22  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  23  * http://www.gnu.org/copyleft/gpl.html
  24  *
  25  * @file
  26  * @ingroup FileJournal
  27  */
  28
  29 /**
  30  * @brief Class for handling file operation journaling.
  31  *
  32  * Subclasses should avoid throwing exceptions at all costs.
  33  *
  34  * @ingroup FileJournal
  35  * @since 1.20
  36  */
  37 abstract class FileJournal {
  38         /** @var string */
  39         protected $backend;
  40
  41         /** @var int */
  42         protected $ttlDays;
  43
  44         /**
  45          * Construct a new instance from configuration.
  46          *
  47          * @param array $config Includes:
  48          *     'ttlDays' : days to keep log entries around (false means "forever")
  49          */
  50         protected function __construct( array $config ) {
  51                 $this->ttlDays = isset( $config['ttlDays'] ) ? $config['ttlDays'] : false;
  52         }
  53
  54         /**
  55          * Create an appropriate FileJournal object from config
  56          *
  57          * @param array $config
  58          * @param string $backend A registered file backend name
  59          * @throws Exception
  60          * @return FileJournal
  61          */
  62         final public static function factory( array $config, $backend ) {
  63                 $class = $config['class'];
  64                 $jrn = new $class( $config );
  65                 if ( !$jrn instanceof self ) {
  66                         throw new InvalidArgumentException( "Class given is not an instance of FileJournal." );
  67                 }
  68                 $jrn->backend = $backend;
  69
  70                 return $jrn;
  71         }
  72
  73         /**
  74          * Get a statistically unique ID string
  75          *
  76          * @return string <9 char TS_MW timestamp in base 36><22 random base 36 chars>
  77          */
  78         final public function getTimestampedUUID() {
  79                 $s = '';
  80                 for ( $i = 0; $i < 5; $i++ ) {
  81                         $s .= mt_rand( 0, 2147483647 );
  82                 }
  83                 $s = Wikimedia\base_convert( sha1( $s ), 16, 36, 31 );
  84
  85                 return substr( Wikimedia\base_convert( wfTimestamp( TS_MW ), 10, 36, 9 ) . $s, 0, 31 );
  86         }
  87
  88         /**
  89          * Log changes made by a batch file operation.
  90          *
  91          * @param array $entries List of file operations (each an array of parameters) which contain:
  92          *     op      : Basic operation name (create, update, delete)
  93          *     path    : The storage path of the file
  94          *     newSha1 : The final base 36 SHA-1 of the file
  95          *   Note that 'false' should be used as the SHA-1 for non-existing files.
  96          * @param string $batchId UUID string that identifies the operation batch
  97          * @return StatusValue
  98          */
  99         final public function logChangeBatch( array $entries, $batchId ) {
 100                 if ( !count( $entries ) ) {
 101                         return StatusValue::newGood();
 102                 }
 103
 104                 return $this->doLogChangeBatch( $entries, $batchId );
 105         }
 106
 107         /**
 108          * @see FileJournal::logChangeBatch()
 109          *
 110          * @param array $entries List of file operations (each an array of parameters)
 111          * @param string $batchId UUID string that identifies the operation batch
 112          * @return StatusValue
 113          */
 114         abstract protected function doLogChangeBatch( array $entries, $batchId );
 115
 116         /**
 117          * Get the position ID of the latest journal entry
 118          *
 119          * @return int|bool
 120          */
 121         final public function getCurrentPosition() {
 122                 return $this->doGetCurrentPosition();
 123         }
 124
 125         /**
 126          * @see FileJournal::getCurrentPosition()
 127          * @return int|bool
 128          */
 129         abstract protected function doGetCurrentPosition();
 130
 131         /**
 132          * Get the position ID of the latest journal entry at some point in time
 133          *
 134          * @param int|string $time Timestamp
 135          * @return int|bool
 136          */
 137         final public function getPositionAtTime( $time ) {
 138                 return $this->doGetPositionAtTime( $time );
 139         }
 140
 141         /**
 142          * @see FileJournal::getPositionAtTime()
 143          * @param int|string $time Timestamp
 144          * @return int|bool
 145          */
 146         abstract protected function doGetPositionAtTime( $time );
 147
 148         /**
 149          * Get an array of file change log entries.
 150          * A starting change ID and/or limit can be specified.
 151          *
 152          * @param int $start Starting change ID or null
 153          * @param int $limit Maximum number of items to return
 154          * @param string &$next Updated to the ID of the next entry.
 155          * @return array List of associative arrays, each having:
 156          *     id         : unique, monotonic, ID for this change
 157          *     batch_uuid : UUID for an operation batch
 158          *     backend    : the backend name
 159          *     op         : primitive operation (create,update,delete,null)
 160          *     path       : affected storage path
 161          *     new_sha1   : base 36 sha1 of the new file had the operation succeeded
 162          *     timestamp  : TS_MW timestamp of the batch change
 163          *   Also, $next is updated to the ID of the next entry.
 164          */
 165         final public function getChangeEntries( $start = null, $limit = 0, &$next = null ) {
 166                 $entries = $this->doGetChangeEntries( $start, $limit ? $limit + 1 : 0 );
 167                 if ( $limit && count( $entries ) > $limit ) {
 168                         $last = array_pop( $entries ); // remove the extra entry
 169                         $next = $last['id']; // update for next call
 170                 } else {
 171                         $next = null; // end of list
 172                 }
 173
 174                 return $entries;
 175         }
 176
 177         /**
 178          * @see FileJournal::getChangeEntries()
 179          * @param int $start
 180          * @param int $limit
 181          * @return array
 182          */
 183         abstract protected function doGetChangeEntries( $start, $limit );
 184
 185         /**
 186          * Purge any old log entries
 187          *
 188          * @return StatusValue
 189          */
 190         final public function purgeOldLogs() {
 191                 return $this->doPurgeOldLogs();
 192         }
 193
 194         /**
 195          * @see FileJournal::purgeOldLogs()
 196          * @return StatusValue
 197          */
 198         abstract protected function doPurgeOldLogs();
 199 }