includes/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  * @author Aaron Schulz
  28  */
  29
  30 /**
  31  * @brief Class for handling file operation journaling.
  32  *
  33  * Subclasses should avoid throwing exceptions at all costs.
  34  *
  35  * @ingroup FileJournal
  36  * @since 1.20
  37  */
  38 abstract class FileJournal {
  39         /** @var string */
  40         protected $backend;
  41
  42         /** @var int */
  43         protected $ttlDays;
  44
  45         /**
  46          * Construct a new instance from configuration.
  47          *
  48          * @param array $config Includes:
  49          *     'ttlDays' : days to keep log entries around (false means "forever")
  50          */
  51         protected function __construct( array $config ) {
  52                 $this->ttlDays = isset( $config['ttlDays'] ) ? $config['ttlDays'] : false;
  53         }
  54
  55         /**
  56          * Create an appropriate FileJournal object from config
  57          *
  58          * @param array $config
  59          * @param string $backend A registered file backend name
  60          * @throws Exception
  61          * @return FileJournal
  62          */
  63         final public static function factory( array $config, $backend ) {
  64                 $class = $config['class'];
  65                 $jrn = new $class( $config );
  66                 if ( !$jrn instanceof self ) {
  67                         throw new Exception( "Class given is not an instance of FileJournal." );
  68                 }
  69                 $jrn->backend = $backend;
  70
  71                 return $jrn;
  72         }
  73
  74         /**
  75          * Get a statistically unique ID string
  76          *
  77          * @return string <9 char TS_MW timestamp in base 36><22 random base 36 chars>
  78          */
  79         final public function getTimestampedUUID() {
  80                 $s = '';
  81                 for ( $i = 0; $i < 5; $i++ ) {
  82                         $s .= mt_rand( 0, 2147483647 );
  83                 }
  84                 $s = Wikimedia\base_convert( sha1( $s ), 16, 36, 31 );
  85
  86                 return substr( Wikimedia\base_convert( wfTimestamp( TS_MW ), 10, 36, 9 ) . $s, 0, 31 );
  87         }
  88
  89         /**
  90          * Log changes made by a batch file operation.
  91          *
  92          * @param array $entries List of file operations (each an array of parameters) which contain:
  93          *     op      : Basic operation name (create, update, delete)
  94          *     path    : The storage path of the file
  95          *     newSha1 : The final base 36 SHA-1 of the file
  96          *   Note that 'false' should be used as the SHA-1 for non-existing files.
  97          * @param string $batchId UUID string that identifies the operation batch
  98          * @return Status
  99          */
 100         final public function logChangeBatch( array $entries, $batchId ) {
 101                 if ( !count( $entries ) ) {
 102                         return Status::newGood();
 103                 }
 104
 105                 return $this->doLogChangeBatch( $entries, $batchId );
 106         }
 107
 108         /**
 109          * @see FileJournal::logChangeBatch()
 110          *
 111          * @param array $entries List of file operations (each an array of parameters)
 112          * @param string $batchId UUID string that identifies the operation batch
 113          * @return Status
 114          */
 115         abstract protected function doLogChangeBatch( array $entries, $batchId );
 116
 117         /**
 118          * Get the position ID of the latest journal entry
 119          *
 120          * @return int|bool
 121          */
 122         final public function getCurrentPosition() {
 123                 return $this->doGetCurrentPosition();
 124         }
 125
 126         /**
 127          * @see FileJournal::getCurrentPosition()
 128          * @return int|bool
 129          */
 130         abstract protected function doGetCurrentPosition();
 131
 132         /**
 133          * Get the position ID of the latest journal entry at some point in time
 134          *
 135          * @param int|string $time Timestamp
 136          * @return int|bool
 137          */
 138         final public function getPositionAtTime( $time ) {
 139                 return $this->doGetPositionAtTime( $time );
 140         }
 141
 142         /**
 143          * @see FileJournal::getPositionAtTime()
 144          * @param int|string $time Timestamp
 145          * @return int|bool
 146          */
 147         abstract protected function doGetPositionAtTime( $time );
 148
 149         /**
 150          * Get an array of file change log entries.
 151          * A starting change ID and/or limit can be specified.
 152          *
 153          * @param int $start Starting change ID or null
 154          * @param int $limit Maximum number of items to return
 155          * @param string &$next Updated to the ID of the next entry.
 156          * @return array List of associative arrays, each having:
 157          *     id         : unique, monotonic, ID for this change
 158          *     batch_uuid : UUID for an operation batch
 159          *     backend    : the backend name
 160          *     op         : primitive operation (create,update,delete,null)
 161          *     path       : affected storage path
 162          *     new_sha1   : base 36 sha1 of the new file had the operation succeeded
 163          *     timestamp  : TS_MW timestamp of the batch change
 164          *   Also, $next is updated to the ID of the next entry.
 165          */
 166         final public function getChangeEntries( $start = null, $limit = 0, &$next = null ) {
 167                 $entries = $this->doGetChangeEntries( $start, $limit ? $limit + 1 : 0 );
 168                 if ( $limit && count( $entries ) > $limit ) {
 169                         $last = array_pop( $entries ); // remove the extra entry
 170                         $next = $last['id']; // update for next call
 171                 } else {
 172                         $next = null; // end of list
 173                 }
 174
 175                 return $entries;
 176         }
 177
 178         /**
 179          * @see FileJournal::getChangeEntries()
 180          * @param int $start
 181          * @param int $limit
 182          * @return array
 183          */
 184         abstract protected function doGetChangeEntries( $start, $limit );
 185
 186         /**
 187          * Purge any old log entries
 188          *
 189          * @return Status
 190          */
 191         final public function purgeOldLogs() {
 192                 return $this->doPurgeOldLogs();
 193         }
 194
 195         /**
 196          * @see FileJournal::purgeOldLogs()
 197          * @return Status
 198          */
 199         abstract protected function doPurgeOldLogs();
 200 }
 201
 202 /**
 203  * Simple version of FileJournal that does nothing
 204  * @since 1.20
 205  */
 206 class NullFileJournal extends FileJournal {
 207         /**
 208          * @see FileJournal::doLogChangeBatch()
 209          * @param array $entries
 210          * @param string $batchId
 211          * @return Status
 212          */
 213         protected function doLogChangeBatch( array $entries, $batchId ) {
 214                 return Status::newGood();
 215         }
 216
 217         /**
 218          * @see FileJournal::doGetCurrentPosition()
 219          * @return int|bool
 220          */
 221         protected function doGetCurrentPosition() {
 222                 return false;
 223         }
 224
 225         /**
 226          * @see FileJournal::doGetPositionAtTime()
 227          * @param int|string $time Timestamp
 228          * @return int|bool
 229          */
 230         protected function doGetPositionAtTime( $time ) {
 231                 return false;
 232         }
 233
 234         /**
 235          * @see FileJournal::doGetChangeEntries()
 236          * @param int $start
 237          * @param int $limit
 238          * @return array
 239          */
 240         protected function doGetChangeEntries( $start, $limit ) {
 241                 return array();
 242         }
 243
 244         /**
 245          * @see FileJournal::doPurgeOldLogs()
 246          * @return Status
 247          */
 248         protected function doPurgeOldLogs() {
 249                 return Status::newGood();
 250         }
 251 }