includes/filebackend/FileOp.php

   1 <?php
   2 /**
   3  * Helper class for representing operations with transaction support.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @ingroup FileBackend
  22  * @author Aaron Schulz
  23  */
  24
  25 /**
  26  * FileBackend helper class for representing operations.
  27  * Do not use this class from places outside FileBackend.
  28  *
  29  * Methods called from FileOpBatch::attempt() should avoid throwing
  30  * exceptions at all costs. FileOp objects should be lightweight in order
  31  * to support large arrays in memory and serialization.
  32  *
  33  * @ingroup FileBackend
  34  * @since 1.19
  35  */
  36 abstract class FileOp {
  37         /** @var Array */
  38         protected $params = array();
  39         /** @var FileBackendStore */
  40         protected $backend;
  41
  42         protected $state = self::STATE_NEW; // integer
  43         protected $failed = false; // boolean
  44         protected $async = false; // boolean
  45         protected $useLatest = true; // boolean
  46         protected $batchId; // string
  47
  48         protected $doOperation = true; // boolean; operation is not a no-op
  49         protected $sourceSha1; // string
  50         protected $destSameAsSource; // boolean
  51
  52         /* Object life-cycle */
  53         const STATE_NEW = 1;
  54         const STATE_CHECKED = 2;
  55         const STATE_ATTEMPTED = 3;
  56
  57         /**
  58          * Build a new file operation transaction
  59          *
  60          * @param $backend FileBackendStore
  61          * @param $params Array
  62          * @throws MWException
  63          */
  64         final public function __construct( FileBackendStore $backend, array $params ) {
  65                 $this->backend = $backend;
  66                 list( $required, $optional ) = $this->allowedParams();
  67                 foreach ( $required as $name ) {
  68                         if ( isset( $params[$name] ) ) {
  69                                 $this->params[$name] = self::normalizeAnyStoragePaths( $params[$name] );
  70                         } else {
  71                                 throw new MWException( "File operation missing parameter '$name'." );
  72                         }
  73                 }
  74                 foreach ( $optional as $name ) {
  75                         if ( isset( $params[$name] ) ) {
  76                                 $this->params[$name] = self::normalizeAnyStoragePaths( $params[$name] );
  77                         }
  78                 }
  79                 $this->params = $params;
  80         }
  81
  82         /**
  83          * Normalize $item or anything in $item that is a valid storage path
  84          *
  85          * @param $item string|array
  86          * @return string|Array
  87          */
  88         protected function normalizeAnyStoragePaths( $item ) {
  89                 if ( is_array( $item ) ) {
  90                         $res = array();
  91                         foreach ( $item as $k => $v ) {
  92                                 $k = self::normalizeIfValidStoragePath( $k );
  93                                 $v = self::normalizeIfValidStoragePath( $v );
  94                                 $res[$k] = $v;
  95                         }
  96                         return $res;
  97                 } else {
  98                         return self::normalizeIfValidStoragePath( $item );
  99                 }
 100         }
 101
 102         /**
 103          * Normalize a string if it is a valid storage path
 104          *
 105          * @param $path string
 106          * @return string
 107          */
 108         protected static function normalizeIfValidStoragePath( $path ) {
 109                 if ( FileBackend::isStoragePath( $path ) ) {
 110                         $res = FileBackend::normalizeStoragePath( $path );
 111                         return ( $res !== null ) ? $res : $path;
 112                 }
 113                 return $path;
 114         }
 115
 116         /**
 117          * Set the batch UUID this operation belongs to
 118          *
 119          * @param $batchId string
 120          * @return void
 121          */
 122         final public function setBatchId( $batchId ) {
 123                 $this->batchId = $batchId;
 124         }
 125
 126         /**
 127          * Whether to allow stale data for file reads and stat checks
 128          *
 129          * @param $allowStale bool
 130          * @return void
 131          */
 132         final public function allowStaleReads( $allowStale ) {
 133                 $this->useLatest = !$allowStale;
 134         }
 135
 136         /**
 137          * Get the value of the parameter with the given name
 138          *
 139          * @param $name string
 140          * @return mixed Returns null if the parameter is not set
 141          */
 142         final public function getParam( $name ) {
 143                 return isset( $this->params[$name] ) ? $this->params[$name] : null;
 144         }
 145
 146         /**
 147          * Check if this operation failed precheck() or attempt()
 148          *
 149          * @return bool
 150          */
 151         final public function failed() {
 152                 return $this->failed;
 153         }
 154
 155         /**
 156          * Get a new empty predicates array for precheck()
 157          *
 158          * @return Array
 159          */
 160         final public static function newPredicates() {
 161                 return array( 'exists' => array(), 'sha1' => array() );
 162         }
 163
 164         /**
 165          * Get a new empty dependency tracking array for paths read/written to
 166          *
 167          * @return Array
 168          */
 169         final public static function newDependencies() {
 170                 return array( 'read' => array(), 'write' => array() );
 171         }
 172
 173         /**
 174          * Update a dependency tracking array to account for this operation
 175          *
 176          * @param $deps Array Prior path reads/writes; format of FileOp::newPredicates()
 177          * @return Array
 178          */
 179         final public function applyDependencies( array $deps ) {
 180                 $deps['read']  += array_fill_keys( $this->storagePathsRead(), 1 );
 181                 $deps['write'] += array_fill_keys( $this->storagePathsChanged(), 1 );
 182                 return $deps;
 183         }
 184
 185         /**
 186          * Check if this operation changes files listed in $paths
 187          *
 188          * @param $paths Array Prior path reads/writes; format of FileOp::newPredicates()
 189          * @return boolean
 190          */
 191         final public function dependsOn( array $deps ) {
 192                 foreach ( $this->storagePathsChanged() as $path ) {
 193                         if ( isset( $deps['read'][$path] ) || isset( $deps['write'][$path] ) ) {
 194                                 return true; // "output" or "anti" dependency
 195                         }
 196                 }
 197                 foreach ( $this->storagePathsRead() as $path ) {
 198                         if ( isset( $deps['write'][$path] ) ) {
 199                                 return true; // "flow" dependency
 200                         }
 201                 }
 202                 return false;
 203         }
 204
 205         /**
 206          * Get the file journal entries for this file operation
 207          *
 208          * @param $oPredicates Array Pre-op info about files (format of FileOp::newPredicates)
 209          * @param $nPredicates Array Post-op info about files (format of FileOp::newPredicates)
 210          * @return Array
 211          */
 212         final public function getJournalEntries( array $oPredicates, array $nPredicates ) {
 213                 if ( !$this->doOperation ) {
 214                         return array(); // this is a no-op
 215                 }
 216                 $nullEntries = array();
 217                 $updateEntries = array();
 218                 $deleteEntries = array();
 219                 $pathsUsed = array_merge( $this->storagePathsRead(), $this->storagePathsChanged() );
 220                 foreach ( array_unique( $pathsUsed ) as $path ) {
 221                         $nullEntries[] = array( // assertion for recovery
 222                                 'op'      => 'null',
 223                                 'path'    => $path,
 224                                 'newSha1' => $this->fileSha1( $path, $oPredicates )
 225                         );
 226                 }
 227                 foreach ( $this->storagePathsChanged() as $path ) {
 228                         if ( $nPredicates['sha1'][$path] === false ) { // deleted
 229                                 $deleteEntries[] = array(
 230                                         'op'      => 'delete',
 231                                         'path'    => $path,
 232                                         'newSha1' => ''
 233                                 );
 234                         } else { // created/updated
 235                                 $updateEntries[] = array(
 236                                         'op'      => $this->fileExists( $path, $oPredicates ) ? 'update' : 'create',
 237                                         'path'    => $path,
 238                                         'newSha1' => $nPredicates['sha1'][$path]
 239                                 );
 240                         }
 241                 }
 242                 return array_merge( $nullEntries, $updateEntries, $deleteEntries );
 243         }
 244
 245         /**
 246          * Check preconditions of the operation without writing anything.
 247          * This must update $predicates for each path that the op can change
 248          * except when a failing status object is returned.
 249          *
 250          * @param $predicates Array
 251          * @return Status
 252          */
 253         final public function precheck( array &$predicates ) {
 254                 if ( $this->state !== self::STATE_NEW ) {
 255                         return Status::newFatal( 'fileop-fail-state', self::STATE_NEW, $this->state );
 256                 }
 257                 $this->state = self::STATE_CHECKED;
 258                 $status = $this->doPrecheck( $predicates );
 259                 if ( !$status->isOK() ) {
 260                         $this->failed = true;
 261                 }
 262                 return $status;
 263         }
 264
 265         /**
 266          * @return Status
 267          */
 268         protected function doPrecheck( array &$predicates ) {
 269                 return Status::newGood();
 270         }
 271
 272         /**
 273          * Attempt the operation
 274          *
 275          * @return Status
 276          */
 277         final public function attempt() {
 278                 if ( $this->state !== self::STATE_CHECKED ) {
 279                         return Status::newFatal( 'fileop-fail-state', self::STATE_CHECKED, $this->state );
 280                 } elseif ( $this->failed ) { // failed precheck
 281                         return Status::newFatal( 'fileop-fail-attempt-precheck' );
 282                 }
 283                 $this->state = self::STATE_ATTEMPTED;
 284                 if ( $this->doOperation ) {
 285                         $status = $this->doAttempt();
 286                         if ( !$status->isOK() ) {
 287                                 $this->failed = true;
 288                                 $this->logFailure( 'attempt' );
 289                         }
 290                 } else { // no-op
 291                         $status = Status::newGood();
 292                 }
 293                 return $status;
 294         }
 295
 296         /**
 297          * @return Status
 298          */
 299         protected function doAttempt() {
 300                 return Status::newGood();
 301         }
 302
 303         /**
 304          * Attempt the operation in the background
 305          *
 306          * @return Status
 307          */
 308         final public function attemptAsync() {
 309                 $this->async = true;
 310                 $result = $this->attempt();
 311                 $this->async = false;
 312                 return $result;
 313         }
 314
 315         /**
 316          * Get the file operation parameters
 317          *
 318          * @return Array (required params list, optional params list)
 319          */
 320         protected function allowedParams() {
 321                 return array( array(), array() );
 322         }
 323
 324         /**
 325          * Adjust params to FileBackendStore internal file calls
 326          *
 327          * @param $params Array
 328          * @return Array (required params list, optional params list)
 329          */
 330         protected function setFlags( array $params ) {
 331                 return array( 'async' => $this->async ) + $params;
 332         }
 333
 334         /**
 335          * Get a list of storage paths read from for this operation
 336          *
 337          * @return Array
 338          */
 339         public function storagePathsRead() {
 340                 return array();
 341         }
 342
 343         /**
 344          * Get a list of storage paths written to for this operation
 345          *
 346          * @return Array
 347          */
 348         public function storagePathsChanged() {
 349                 return array();
 350         }
 351
 352         /**
 353          * Check for errors with regards to the destination file already existing.
 354          * This also updates the destSameAsSource and sourceSha1 member variables.
 355          * A bad status will be returned if there is no chance it can be overwritten.
 356          *
 357          * @param $predicates Array
 358          * @return Status
 359          */
 360         protected function precheckDestExistence( array $predicates ) {
 361                 $status = Status::newGood();
 362                 // Get hash of source file/string and the destination file
 363                 $this->sourceSha1 = $this->getSourceSha1Base36(); // FS file or data string
 364                 if ( $this->sourceSha1 === null ) { // file in storage?
 365                         $this->sourceSha1 = $this->fileSha1( $this->params['src'], $predicates );
 366                 }
 367                 $this->destSameAsSource = false;
 368                 if ( $this->fileExists( $this->params['dst'], $predicates ) ) {
 369                         if ( $this->getParam( 'overwrite' ) ) {
 370                                 return $status; // OK
 371                         } elseif ( $this->getParam( 'overwriteSame' ) ) {
 372                                 $dhash = $this->fileSha1( $this->params['dst'], $predicates );
 373                                 // Check if hashes are valid and match each other...
 374                                 if ( !strlen( $this->sourceSha1 ) || !strlen( $dhash ) ) {
 375                                         $status->fatal( 'backend-fail-hashes' );
 376                                 } elseif ( $this->sourceSha1 !== $dhash ) {
 377                                         // Give an error if the files are not identical
 378                                         $status->fatal( 'backend-fail-notsame', $this->params['dst'] );
 379                                 } else {
 380                                         $this->destSameAsSource = true; // OK
 381                                 }
 382                                 return $status; // do nothing; either OK or bad status
 383                         } else {
 384                                 $status->fatal( 'backend-fail-alreadyexists', $this->params['dst'] );
 385                                 return $status;
 386                         }
 387                 }
 388                 return $status;
 389         }
 390
 391         /**
 392          * precheckDestExistence() helper function to get the source file SHA-1.
 393          * Subclasses should overwride this iff the source is not in storage.
 394          *
 395          * @return string|bool Returns false on failure
 396          */
 397         protected function getSourceSha1Base36() {
 398                 return null; // N/A
 399         }
 400
 401         /**
 402          * Check if a file will exist in storage when this operation is attempted
 403          *
 404          * @param $source string Storage path
 405          * @param $predicates Array
 406          * @return bool
 407          */
 408         final protected function fileExists( $source, array $predicates ) {
 409                 if ( isset( $predicates['exists'][$source] ) ) {
 410                         return $predicates['exists'][$source]; // previous op assures this
 411                 } else {
 412                         $params = array( 'src' => $source, 'latest' => $this->useLatest );
 413                         return $this->backend->fileExists( $params );
 414                 }
 415         }
 416
 417         /**
 418          * Get the SHA-1 of a file in storage when this operation is attempted
 419          *
 420          * @param $source string Storage path
 421          * @param $predicates Array
 422          * @return string|bool False on failure
 423          */
 424         final protected function fileSha1( $source, array $predicates ) {
 425                 if ( isset( $predicates['sha1'][$source] ) ) {
 426                         return $predicates['sha1'][$source]; // previous op assures this
 427                 } elseif ( isset( $predicates['exists'][$source] ) && !$predicates['exists'][$source] ) {
 428                         return false; // previous op assures this
 429                 } else {
 430                         $params = array( 'src' => $source, 'latest' => $this->useLatest );
 431                         return $this->backend->getFileSha1Base36( $params );
 432                 }
 433         }
 434
 435         /**
 436          * Get the backend this operation is for
 437          *
 438          * @return FileBackendStore
 439          */
 440         public function getBackend() {
 441                 return $this->backend;
 442         }
 443
 444         /**
 445          * Log a file operation failure and preserve any temp files
 446          *
 447          * @param $action string
 448          * @return void
 449          */
 450         final public function logFailure( $action ) {
 451                 $params = $this->params;
 452                 $params['failedAction'] = $action;
 453                 try {
 454                         wfDebugLog( 'FileOperation', get_class( $this ) .
 455                                 " failed (batch #{$this->batchId}): " . FormatJson::encode( $params ) );
 456                 } catch ( Exception $e ) {
 457                         // bad config? debug log error?
 458                 }
 459         }
 460 }
 461
 462 /**
 463  * Create a file in the backend with the given content.
 464  * Parameters for this operation are outlined in FileBackend::doOperations().
 465  */
 466 class CreateFileOp extends FileOp {
 467         protected function allowedParams() {
 468                 return array( array( 'content', 'dst' ),
 469                         array( 'overwrite', 'overwriteSame', 'disposition' ) );
 470         }
 471
 472         protected function doPrecheck( array &$predicates ) {
 473                 $status = Status::newGood();
 474                 // Check if the source data is too big
 475                 if ( strlen( $this->getParam( 'content' ) ) > $this->backend->maxFileSizeInternal() ) {
 476                         $status->fatal( 'backend-fail-maxsize',
 477                                 $this->params['dst'], $this->backend->maxFileSizeInternal() );
 478                         $status->fatal( 'backend-fail-create', $this->params['dst'] );
 479                         return $status;
 480                 // Check if a file can be placed/changed at the destination
 481                 } elseif ( !$this->backend->isPathUsableInternal( $this->params['dst'] ) ) {
 482                         $status->fatal( 'backend-fail-usable', $this->params['dst'] );
 483                         $status->fatal( 'backend-fail-create', $this->params['dst'] );
 484                         return $status;
 485                 }
 486                 // Check if destination file exists
 487                 $status->merge( $this->precheckDestExistence( $predicates ) );
 488                 if ( $status->isOK() ) {
 489                         // Update file existence predicates
 490                         $predicates['exists'][$this->params['dst']] = true;
 491                         $predicates['sha1'][$this->params['dst']] = $this->sourceSha1;
 492                 }
 493                 return $status; // safe to call attempt()
 494         }
 495
 496         /**
 497          * @return Status
 498          */
 499         protected function doAttempt() {
 500                 if ( !$this->destSameAsSource ) {
 501                         // Create the file at the destination
 502                         return $this->backend->createInternal( $this->setFlags( $this->params ) );
 503                 }
 504                 return Status::newGood();
 505         }
 506
 507         /**
 508          * @return bool|String
 509          */
 510         protected function getSourceSha1Base36() {
 511                 return wfBaseConvert( sha1( $this->params['content'] ), 16, 36, 31 );
 512         }
 513
 514         /**
 515          * @return array
 516          */
 517         public function storagePathsChanged() {
 518                 return array( $this->params['dst'] );
 519         }
 520 }
 521
 522 /**
 523  * Store a file into the backend from a file on the file system.
 524  * Parameters for this operation are outlined in FileBackend::doOperations().
 525  */
 526 class StoreFileOp extends FileOp {
 527         /**
 528          * @return array
 529          */
 530         protected function allowedParams() {
 531                 return array( array( 'src', 'dst' ),
 532                         array( 'overwrite', 'overwriteSame', 'disposition' ) );
 533         }
 534
 535         /**
 536          * @param $predicates array
 537          * @return Status
 538          */
 539         protected function doPrecheck( array &$predicates ) {
 540                 $status = Status::newGood();
 541                 // Check if the source file exists on the file system
 542                 if ( !is_file( $this->params['src'] ) ) {
 543                         $status->fatal( 'backend-fail-notexists', $this->params['src'] );
 544                         return $status;
 545                 // Check if the source file is too big
 546                 } elseif ( filesize( $this->params['src'] ) > $this->backend->maxFileSizeInternal() ) {
 547                         $status->fatal( 'backend-fail-maxsize',
 548                                 $this->params['dst'], $this->backend->maxFileSizeInternal() );
 549                         $status->fatal( 'backend-fail-store', $this->params['src'], $this->params['dst'] );
 550                         return $status;
 551                 // Check if a file can be placed/changed at the destination
 552                 } elseif ( !$this->backend->isPathUsableInternal( $this->params['dst'] ) ) {
 553                         $status->fatal( 'backend-fail-usable', $this->params['dst'] );
 554                         $status->fatal( 'backend-fail-store', $this->params['src'], $this->params['dst'] );
 555                         return $status;
 556                 }
 557                 // Check if destination file exists
 558                 $status->merge( $this->precheckDestExistence( $predicates ) );
 559                 if ( $status->isOK() ) {
 560                         // Update file existence predicates
 561                         $predicates['exists'][$this->params['dst']] = true;
 562                         $predicates['sha1'][$this->params['dst']] = $this->sourceSha1;
 563                 }
 564                 return $status; // safe to call attempt()
 565         }
 566
 567         /**
 568          * @return Status
 569          */
 570         protected function doAttempt() {
 571                 // Store the file at the destination
 572                 if ( !$this->destSameAsSource ) {
 573                         return $this->backend->storeInternal( $this->setFlags( $this->params ) );
 574                 }
 575                 return Status::newGood();
 576         }
 577
 578         /**
 579          * @return bool|string
 580          */
 581         protected function getSourceSha1Base36() {
 582                 wfSuppressWarnings();
 583                 $hash = sha1_file( $this->params['src'] );
 584                 wfRestoreWarnings();
 585                 if ( $hash !== false ) {
 586                         $hash = wfBaseConvert( $hash, 16, 36, 31 );
 587                 }
 588                 return $hash;
 589         }
 590
 591         public function storagePathsChanged() {
 592                 return array( $this->params['dst'] );
 593         }
 594 }
 595
 596 /**
 597  * Copy a file from one storage path to another in the backend.
 598  * Parameters for this operation are outlined in FileBackend::doOperations().
 599  */
 600 class CopyFileOp extends FileOp {
 601         /**
 602          * @return array
 603          */
 604         protected function allowedParams() {
 605                 return array( array( 'src', 'dst' ),
 606                         array( 'overwrite', 'overwriteSame', 'ignoreMissingSource', 'disposition' ) );
 607         }
 608
 609         /**
 610          * @param $predicates array
 611          * @return Status
 612          */
 613         protected function doPrecheck( array &$predicates ) {
 614                 $status = Status::newGood();
 615                 // Check if the source file exists
 616                 if ( !$this->fileExists( $this->params['src'], $predicates ) ) {
 617                         if ( $this->getParam( 'ignoreMissingSource' ) ) {
 618                                 $this->doOperation = false; // no-op
 619                                 // Update file existence predicates (cache 404s)
 620                                 $predicates['exists'][$this->params['src']] = false;
 621                                 $predicates['sha1'][$this->params['src']] = false;
 622                                 return $status; // nothing to do
 623                         } else {
 624                                 $status->fatal( 'backend-fail-notexists', $this->params['src'] );
 625                                 return $status;
 626                         }
 627                 // Check if a file can be placed/changed at the destination
 628                 } elseif ( !$this->backend->isPathUsableInternal( $this->params['dst'] ) ) {
 629                         $status->fatal( 'backend-fail-usable', $this->params['dst'] );
 630                         $status->fatal( 'backend-fail-copy', $this->params['src'], $this->params['dst'] );
 631                         return $status;
 632                 }
 633                 // Check if destination file exists
 634                 $status->merge( $this->precheckDestExistence( $predicates ) );
 635                 if ( $status->isOK() ) {
 636                         // Update file existence predicates
 637                         $predicates['exists'][$this->params['dst']] = true;
 638                         $predicates['sha1'][$this->params['dst']] = $this->sourceSha1;
 639                 }
 640                 return $status; // safe to call attempt()
 641         }
 642
 643         /**
 644          * @return Status
 645          */
 646         protected function doAttempt() {
 647                 // Do nothing if the src/dst paths are the same
 648                 if ( $this->params['src'] !== $this->params['dst'] ) {
 649                         // Copy the file into the destination
 650                         if ( !$this->destSameAsSource ) {
 651                                 return $this->backend->copyInternal( $this->setFlags( $this->params ) );
 652                         }
 653                 }
 654                 return Status::newGood();
 655         }
 656
 657         /**
 658          * @return array
 659          */
 660         public function storagePathsRead() {
 661                 return array( $this->params['src'] );
 662         }
 663
 664         /**
 665          * @return array
 666          */
 667         public function storagePathsChanged() {
 668                 return array( $this->params['dst'] );
 669         }
 670 }
 671
 672 /**
 673  * Move a file from one storage path to another in the backend.
 674  * Parameters for this operation are outlined in FileBackend::doOperations().
 675  */
 676 class MoveFileOp extends FileOp {
 677         /**
 678          * @return array
 679          */
 680         protected function allowedParams() {
 681                 return array( array( 'src', 'dst' ),
 682                         array( 'overwrite', 'overwriteSame', 'ignoreMissingSource', 'disposition' ) );
 683         }
 684
 685         /**
 686          * @param $predicates array
 687          * @return Status
 688          */
 689         protected function doPrecheck( array &$predicates ) {
 690                 $status = Status::newGood();
 691                 // Check if the source file exists
 692                 if ( !$this->fileExists( $this->params['src'], $predicates ) ) {
 693                         if ( $this->getParam( 'ignoreMissingSource' ) ) {
 694                                 $this->doOperation = false; // no-op
 695                                 // Update file existence predicates (cache 404s)
 696                                 $predicates['exists'][$this->params['src']] = false;
 697                                 $predicates['sha1'][$this->params['src']] = false;
 698                                 return $status; // nothing to do
 699                         } else {
 700                                 $status->fatal( 'backend-fail-notexists', $this->params['src'] );
 701                                 return $status;
 702                         }
 703                 // Check if a file can be placed/changed at the destination
 704                 } elseif ( !$this->backend->isPathUsableInternal( $this->params['dst'] ) ) {
 705                         $status->fatal( 'backend-fail-usable', $this->params['dst'] );
 706                         $status->fatal( 'backend-fail-move', $this->params['src'], $this->params['dst'] );
 707                         return $status;
 708                 }
 709                 // Check if destination file exists
 710                 $status->merge( $this->precheckDestExistence( $predicates ) );
 711                 if ( $status->isOK() ) {
 712                         // Update file existence predicates
 713                         $predicates['exists'][$this->params['src']] = false;
 714                         $predicates['sha1'][$this->params['src']] = false;
 715                         $predicates['exists'][$this->params['dst']] = true;
 716                         $predicates['sha1'][$this->params['dst']] = $this->sourceSha1;
 717                 }
 718                 return $status; // safe to call attempt()
 719         }
 720
 721         /**
 722          * @return Status
 723          */
 724         protected function doAttempt() {
 725                 // Do nothing if the src/dst paths are the same
 726                 if ( $this->params['src'] !== $this->params['dst'] ) {
 727                         if ( !$this->destSameAsSource ) {
 728                                 // Move the file into the destination
 729                                 return $this->backend->moveInternal( $this->setFlags( $this->params ) );
 730                         } else {
 731                                 // Just delete source as the destination needs no changes
 732                                 $params = array( 'src' => $this->params['src'] );
 733                                 return $this->backend->deleteInternal( $this->setFlags( $params ) );
 734                         }
 735                 }
 736                 return Status::newGood();
 737         }
 738
 739         /**
 740          * @return array
 741          */
 742         public function storagePathsRead() {
 743                 return array( $this->params['src'] );
 744         }
 745
 746         /**
 747          * @return array
 748          */
 749         public function storagePathsChanged() {
 750                 return array( $this->params['src'], $this->params['dst'] );
 751         }
 752 }
 753
 754 /**
 755  * Delete a file at the given storage path from the backend.
 756  * Parameters for this operation are outlined in FileBackend::doOperations().
 757  */
 758 class DeleteFileOp extends FileOp {
 759         /**
 760          * @return array
 761          */
 762         protected function allowedParams() {
 763                 return array( array( 'src' ), array( 'ignoreMissingSource' ) );
 764         }
 765
 766         /**
 767          * @param $predicates array
 768          * @return Status
 769          */
 770         protected function doPrecheck( array &$predicates ) {
 771                 $status = Status::newGood();
 772                 // Check if the source file exists
 773                 if ( !$this->fileExists( $this->params['src'], $predicates ) ) {
 774                         if ( $this->getParam( 'ignoreMissingSource' ) ) {
 775                                 $this->doOperation = false; // no-op
 776                                 // Update file existence predicates (cache 404s)
 777                                 $predicates['exists'][$this->params['src']] = false;
 778                                 $predicates['sha1'][$this->params['src']] = false;
 779                                 return $status; // nothing to do
 780                         } else {
 781                                 $status->fatal( 'backend-fail-notexists', $this->params['src'] );
 782                                 return $status;
 783                         }
 784                 // Check if a file can be placed/changed at the source
 785                 } elseif ( !$this->backend->isPathUsableInternal( $this->params['src'] ) ) {
 786                         $status->fatal( 'backend-fail-usable', $this->params['src'] );
 787                         $status->fatal( 'backend-fail-delete', $this->params['src'] );
 788                         return $status;
 789                 }
 790                 // Update file existence predicates
 791                 $predicates['exists'][$this->params['src']] = false;
 792                 $predicates['sha1'][$this->params['src']] = false;
 793                 return $status; // safe to call attempt()
 794         }
 795
 796         /**
 797          * @return Status
 798          */
 799         protected function doAttempt() {
 800                 // Delete the source file
 801                 return $this->backend->deleteInternal( $this->setFlags( $this->params ) );
 802         }
 803
 804         /**
 805          * @return array
 806          */
 807         public function storagePathsChanged() {
 808                 return array( $this->params['src'] );
 809         }
 810 }
 811
 812 /**
 813  * Placeholder operation that has no params and does nothing
 814  */
 815 class NullFileOp extends FileOp {}