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 use Wikimedia\Timestamp\ConvertibleTimestamp;
  30
  31 /**
  32  * @brief Class for handling file operation journaling.
  33  *
  34  * Subclasses should avoid throwing exceptions at all costs.
  35  *
  36  * @ingroup FileJournal
  37  * @since 1.20
  38  */
  39 abstract class FileJournal {
  40         /** @var string */
  41         protected $backend;
  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 = $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 InvalidArgumentException( "$class is not an instance of " . __CLASS__ );
  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                 $timestamp = ConvertibleTimestamp::convert( TS_MW, time() );
  87
  88                 return substr( Wikimedia\base_convert( $timestamp, 10, 36, 9 ) . $s, 0, 31 );
  89         }
  90
  91         /**
  92          * Log changes made by a batch file operation.
  93          *
  94          * @param array $entries List of file operations (each an array of parameters) which contain:
  95          *     op      : Basic operation name (create, update, delete)
  96          *     path    : The storage path of the file
  97          *     newSha1 : The final base 36 SHA-1 of the file
  98          *   Note that 'false' should be used as the SHA-1 for non-existing files.
  99          * @param string $batchId UUID string that identifies the operation batch
 100          * @return StatusValue
 101          */
 102         final public function logChangeBatch( array $entries, $batchId ) {
 103                 if ( $entries === [] ) {
 104                         return StatusValue::newGood();
 105                 }
 106
 107                 return $this->doLogChangeBatch( $entries, $batchId );
 108         }
 109
 110         /**
 111          * @see FileJournal::logChangeBatch()
 112          *
 113          * @param array $entries List of file operations (each an array of parameters)
 114          * @param string $batchId UUID string that identifies the operation batch
 115          * @return StatusValue
 116          */
 117         abstract protected function doLogChangeBatch( array $entries, $batchId );
 118
 119         /**
 120          * Get the position ID of the latest journal entry
 121          *
 122          * @return int|bool
 123          */
 124         final public function getCurrentPosition() {
 125                 return $this->doGetCurrentPosition();
 126         }
 127
 128         /**
 129          * @see FileJournal::getCurrentPosition()
 130          * @return int|bool
 131          */
 132         abstract protected function doGetCurrentPosition();
 133
 134         /**
 135          * Get the position ID of the latest journal entry at some point in time
 136          *
 137          * @param int|string $time Timestamp
 138          * @return int|bool
 139          */
 140         final public function getPositionAtTime( $time ) {
 141                 return $this->doGetPositionAtTime( $time );
 142         }
 143
 144         /**
 145          * @see FileJournal::getPositionAtTime()
 146          * @param int|string $time Timestamp
 147          * @return int|bool
 148          */
 149         abstract protected function doGetPositionAtTime( $time );
 150
 151         /**
 152          * Get an array of file change log entries.
 153          * A starting change ID and/or limit can be specified.
 154          *
 155          * @param int|null $start Starting change ID or null
 156          * @param int $limit Maximum number of items to return
 157          * @param string|null &$next Updated to the ID of the next entry.
 158          * @return array List of associative arrays, each having:
 159          *     id         : unique, monotonic, ID for this change
 160          *     batch_uuid : UUID for an operation batch
 161          *     backend    : the backend name
 162          *     op         : primitive operation (create,update,delete,null)
 163          *     path       : affected storage path
 164          *     new_sha1   : base 36 sha1 of the new file had the operation succeeded
 165          *     timestamp  : TS_MW timestamp of the batch change
 166          *   Also, $next is updated to the ID of the next entry.
 167          */
 168         final public function getChangeEntries( $start = null, $limit = 0, &$next = null ) {
 169                 $entries = $this->doGetChangeEntries( $start, $limit ? $limit + 1 : 0 );
 170                 if ( $limit && count( $entries ) > $limit ) {
 171                         $last = array_pop( $entries ); // remove the extra entry
 172                         $next = $last['id']; // update for next call
 173                 } else {
 174                         $next = null; // end of list
 175                 }
 176
 177                 return $entries;
 178         }
 179
 180         /**
 181          * @see FileJournal::getChangeEntries()
 182          * @param int $start
 183          * @param int $limit
 184          * @return array
 185          */
 186         abstract protected function doGetChangeEntries( $start, $limit );
 187
 188         /**
 189          * Purge any old log entries
 190          *
 191          * @return StatusValue
 192          */
 193         final public function purgeOldLogs() {
 194                 return $this->doPurgeOldLogs();
 195         }
 196
 197         /**
 198          * @see FileJournal::purgeOldLogs()
 199          * @return StatusValue
 200          */
 201         abstract protected function doPurgeOldLogs();
 202 }