3 * @defgroup FileJournal File journal
8 * File operation journaling.
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.
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.
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
26 * @ingroup FileJournal
29 use Wikimedia\Timestamp\ConvertibleTimestamp
;
32 * @brief Class for handling file operation journaling.
34 * Subclasses should avoid throwing exceptions at all costs.
36 * @ingroup FileJournal
39 abstract class FileJournal
{
46 * Construct a new instance from configuration.
48 * @param array $config Includes:
49 * 'ttlDays' : days to keep log entries around (false means "forever")
51 protected function __construct( array $config ) {
52 $this->ttlDays
= $config['ttlDays'] ??
false;
56 * Create an appropriate FileJournal object from config
58 * @param array $config
59 * @param string $backend A registered file backend name
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__
);
69 $jrn->backend
= $backend;
75 * Get a statistically unique ID string
77 * @return string <9 char TS_MW timestamp in base 36><22 random base 36 chars>
79 final public function getTimestampedUUID() {
81 for ( $i = 0; $i < 5; $i++
) {
82 $s .= mt_rand( 0, 2147483647 );
84 $s = Wikimedia\base_convert
( sha1( $s ), 16, 36, 31 );
86 $timestamp = ConvertibleTimestamp
::convert( TS_MW
, time() );
88 return substr( Wikimedia\base_convert
( $timestamp, 10, 36, 9 ) . $s, 0, 31 );
92 * Log changes made by a batch file operation.
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
102 final public function logChangeBatch( array $entries, $batchId ) {
103 if ( $entries === [] ) {
104 return StatusValue
::newGood();
107 return $this->doLogChangeBatch( $entries, $batchId );
111 * @see FileJournal::logChangeBatch()
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
117 abstract protected function doLogChangeBatch( array $entries, $batchId );
120 * Get the position ID of the latest journal entry
124 final public function getCurrentPosition() {
125 return $this->doGetCurrentPosition();
129 * @see FileJournal::getCurrentPosition()
132 abstract protected function doGetCurrentPosition();
135 * Get the position ID of the latest journal entry at some point in time
137 * @param int|string $time Timestamp
140 final public function getPositionAtTime( $time ) {
141 return $this->doGetPositionAtTime( $time );
145 * @see FileJournal::getPositionAtTime()
146 * @param int|string $time Timestamp
149 abstract protected function doGetPositionAtTime( $time );
152 * Get an array of file change log entries.
153 * A starting change ID and/or limit can be specified.
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.
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
174 $next = null; // end of list
181 * @see FileJournal::getChangeEntries()
186 abstract protected function doGetChangeEntries( $start, $limit );
189 * Purge any old log entries
191 * @return StatusValue
193 final public function purgeOldLogs() {
194 return $this->doPurgeOldLogs();
198 * @see FileJournal::purgeOldLogs()
199 * @return StatusValue
201 abstract protected function doPurgeOldLogs();