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