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 FileBackendStore $backend
  61          * @param Array $params
  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 string $item|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 string $path
 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 string $batchId
 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 string $name
 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 Array $predicates
 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 Array $params
 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 Array $predicates
 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 if 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 Array $predicates
 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 Array $predicates
 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 string $action
 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         protected function doAttempt() {
 492                 if ( !$this->overwriteSameCase ) {
 493                         // Create the file at the destination
 494                         return $this->backend->createInternal( $this->setFlags( $this->params ) );
 495                 }
 496                 return Status::newGood();
 497         }
 498
 499         protected function getSourceSha1Base36() {
 500                 return wfBaseConvert( sha1( $this->params['content'] ), 16, 36, 31 );
 501         }
 502
 503         public function storagePathsChanged() {
 504                 return array( $this->params['dst'] );
 505         }
 506 }
 507
 508 /**
 509  * Store a file into the backend from a file on the file system.
 510  * Parameters for this operation are outlined in FileBackend::doOperations().
 511  */
 512 class StoreFileOp extends FileOp {
 513         protected function allowedParams() {
 514                 return array( array( 'src', 'dst' ),
 515                         array( 'overwrite', 'overwriteSame', 'headers' ) );
 516         }
 517
 518         protected function doPrecheck( array &$predicates ) {
 519                 $status = Status::newGood();
 520                 // Check if the source file exists on the file system
 521                 if ( !is_file( $this->params['src'] ) ) {
 522                         $status->fatal( 'backend-fail-notexists', $this->params['src'] );
 523                         return $status;
 524                 // Check if the source file is too big
 525                 } elseif ( filesize( $this->params['src'] ) > $this->backend->maxFileSizeInternal() ) {
 526                         $status->fatal( 'backend-fail-maxsize',
 527                                 $this->params['dst'], $this->backend->maxFileSizeInternal() );
 528                         $status->fatal( 'backend-fail-store', $this->params['src'], $this->params['dst'] );
 529                         return $status;
 530                 // Check if a file can be placed/changed at the destination
 531                 } elseif ( !$this->backend->isPathUsableInternal( $this->params['dst'] ) ) {
 532                         $status->fatal( 'backend-fail-usable', $this->params['dst'] );
 533                         $status->fatal( 'backend-fail-store', $this->params['src'], $this->params['dst'] );
 534                         return $status;
 535                 }
 536                 // Check if destination file exists
 537                 $status->merge( $this->precheckDestExistence( $predicates ) );
 538                 $this->params['dstExists'] = $this->destExists; // see FileBackendStore::setFileCache()
 539                 if ( $status->isOK() ) {
 540                         // Update file existence predicates
 541                         $predicates['exists'][$this->params['dst']] = true;
 542                         $predicates['sha1'][$this->params['dst']] = $this->sourceSha1;
 543                 }
 544                 return $status; // safe to call attempt()
 545         }
 546
 547         protected function doAttempt() {
 548                 if ( !$this->overwriteSameCase ) {
 549                         // Store the file at the destination
 550                         return $this->backend->storeInternal( $this->setFlags( $this->params ) );
 551                 }
 552                 return Status::newGood();
 553         }
 554
 555         protected function getSourceSha1Base36() {
 556                 wfSuppressWarnings();
 557                 $hash = sha1_file( $this->params['src'] );
 558                 wfRestoreWarnings();
 559                 if ( $hash !== false ) {
 560                         $hash = wfBaseConvert( $hash, 16, 36, 31 );
 561                 }
 562                 return $hash;
 563         }
 564
 565         public function storagePathsChanged() {
 566                 return array( $this->params['dst'] );
 567         }
 568 }
 569
 570 /**
 571  * Copy a file from one storage path to another in the backend.
 572  * Parameters for this operation are outlined in FileBackend::doOperations().
 573  */
 574 class CopyFileOp extends FileOp {
 575         protected function allowedParams() {
 576                 return array( array( 'src', 'dst' ),
 577                         array( 'overwrite', 'overwriteSame', 'ignoreMissingSource', 'headers' ) );
 578         }
 579
 580         protected function doPrecheck( array &$predicates ) {
 581                 $status = Status::newGood();
 582                 // Check if the source file exists
 583                 if ( !$this->fileExists( $this->params['src'], $predicates ) ) {
 584                         if ( $this->getParam( 'ignoreMissingSource' ) ) {
 585                                 $this->doOperation = false; // no-op
 586                                 // Update file existence predicates (cache 404s)
 587                                 $predicates['exists'][$this->params['src']] = false;
 588                                 $predicates['sha1'][$this->params['src']] = false;
 589                                 return $status; // nothing to do
 590                         } else {
 591                                 $status->fatal( 'backend-fail-notexists', $this->params['src'] );
 592                                 return $status;
 593                         }
 594                 // Check if a file can be placed/changed at the destination
 595                 } elseif ( !$this->backend->isPathUsableInternal( $this->params['dst'] ) ) {
 596                         $status->fatal( 'backend-fail-usable', $this->params['dst'] );
 597                         $status->fatal( 'backend-fail-copy', $this->params['src'], $this->params['dst'] );
 598                         return $status;
 599                 }
 600                 // Check if destination file exists
 601                 $status->merge( $this->precheckDestExistence( $predicates ) );
 602                 $this->params['dstExists'] = $this->destExists; // see FileBackendStore::setFileCache()
 603                 if ( $status->isOK() ) {
 604                         // Update file existence predicates
 605                         $predicates['exists'][$this->params['dst']] = true;
 606                         $predicates['sha1'][$this->params['dst']] = $this->sourceSha1;
 607                 }
 608                 return $status; // safe to call attempt()
 609         }
 610
 611         protected function doAttempt() {
 612                 if ( $this->overwriteSameCase ) {
 613                         $status = Status::newGood(); // nothing to do
 614                 } elseif ( $this->params['src'] === $this->params['dst'] ) {
 615                         // Just update the destination file headers
 616                         $headers = $this->getParam( 'headers' ) ?: array();
 617                         $status = $this->backend->describeInternal( $this->setFlags( array(
 618                                 'src' => $this->params['dst'], 'headers' => $headers
 619                         ) ) );
 620                 } else {
 621                         // Copy the file to the destination
 622                         $status = $this->backend->copyInternal( $this->setFlags( $this->params ) );
 623                 }
 624                 return $status;
 625         }
 626
 627         public function storagePathsRead() {
 628                 return array( $this->params['src'] );
 629         }
 630
 631         public function storagePathsChanged() {
 632                 return array( $this->params['dst'] );
 633         }
 634 }
 635
 636 /**
 637  * Move a file from one storage path to another in the backend.
 638  * Parameters for this operation are outlined in FileBackend::doOperations().
 639  */
 640 class MoveFileOp extends FileOp {
 641         protected function allowedParams() {
 642                 return array( array( 'src', 'dst' ),
 643                         array( 'overwrite', 'overwriteSame', 'ignoreMissingSource', 'headers' ) );
 644         }
 645
 646         protected function doPrecheck( array &$predicates ) {
 647                 $status = Status::newGood();
 648                 // Check if the source file exists
 649                 if ( !$this->fileExists( $this->params['src'], $predicates ) ) {
 650                         if ( $this->getParam( 'ignoreMissingSource' ) ) {
 651                                 $this->doOperation = false; // no-op
 652                                 // Update file existence predicates (cache 404s)
 653                                 $predicates['exists'][$this->params['src']] = false;
 654                                 $predicates['sha1'][$this->params['src']] = false;
 655                                 return $status; // nothing to do
 656                         } else {
 657                                 $status->fatal( 'backend-fail-notexists', $this->params['src'] );
 658                                 return $status;
 659                         }
 660                 // Check if a file can be placed/changed at the destination
 661                 } elseif ( !$this->backend->isPathUsableInternal( $this->params['dst'] ) ) {
 662                         $status->fatal( 'backend-fail-usable', $this->params['dst'] );
 663                         $status->fatal( 'backend-fail-move', $this->params['src'], $this->params['dst'] );
 664                         return $status;
 665                 }
 666                 // Check if destination file exists
 667                 $status->merge( $this->precheckDestExistence( $predicates ) );
 668                 $this->params['dstExists'] = $this->destExists; // see FileBackendStore::setFileCache()
 669                 if ( $status->isOK() ) {
 670                         // Update file existence predicates
 671                         $predicates['exists'][$this->params['src']] = false;
 672                         $predicates['sha1'][$this->params['src']] = false;
 673                         $predicates['exists'][$this->params['dst']] = true;
 674                         $predicates['sha1'][$this->params['dst']] = $this->sourceSha1;
 675                 }
 676                 return $status; // safe to call attempt()
 677         }
 678
 679         protected function doAttempt() {
 680                 if ( $this->overwriteSameCase ) {
 681                         if ( $this->params['src'] === $this->params['dst'] ) {
 682                                 // Do nothing to the destination (which is also the source)
 683                                 $status = Status::newGood();
 684                         } else {
 685                                 // Just delete the source as the destination file needs no changes
 686                                 $status = $this->backend->deleteInternal( $this->setFlags(
 687                                         array( 'src' => $this->params['src'] )
 688                                 ) );
 689                         }
 690                 } elseif ( $this->params['src'] === $this->params['dst'] ) {
 691                         // Just update the destination file headers
 692                         $headers = $this->getParam( 'headers' ) ?: array();
 693                         $status = $this->backend->describeInternal( $this->setFlags(
 694                                 array( 'src' => $this->params['dst'], 'headers' => $headers )
 695                         ) );
 696                 } else {
 697                         // Move the file to the destination
 698                         $status = $this->backend->moveInternal( $this->setFlags( $this->params ) );
 699                 }
 700                 return $status;
 701         }
 702
 703         public function storagePathsRead() {
 704                 return array( $this->params['src'] );
 705         }
 706
 707         public function storagePathsChanged() {
 708                 return array( $this->params['src'], $this->params['dst'] );
 709         }
 710 }
 711
 712 /**
 713  * Delete a file at the given storage path from the backend.
 714  * Parameters for this operation are outlined in FileBackend::doOperations().
 715  */
 716 class DeleteFileOp extends FileOp {
 717         protected function allowedParams() {
 718                 return array( array( 'src' ), array( 'ignoreMissingSource' ) );
 719         }
 720
 721         protected function doPrecheck( array &$predicates ) {
 722                 $status = Status::newGood();
 723                 // Check if the source file exists
 724                 if ( !$this->fileExists( $this->params['src'], $predicates ) ) {
 725                         if ( $this->getParam( 'ignoreMissingSource' ) ) {
 726                                 $this->doOperation = false; // no-op
 727                                 // Update file existence predicates (cache 404s)
 728                                 $predicates['exists'][$this->params['src']] = false;
 729                                 $predicates['sha1'][$this->params['src']] = false;
 730                                 return $status; // nothing to do
 731                         } else {
 732                                 $status->fatal( 'backend-fail-notexists', $this->params['src'] );
 733                                 return $status;
 734                         }
 735                 // Check if a file can be placed/changed at the source
 736                 } elseif ( !$this->backend->isPathUsableInternal( $this->params['src'] ) ) {
 737                         $status->fatal( 'backend-fail-usable', $this->params['src'] );
 738                         $status->fatal( 'backend-fail-delete', $this->params['src'] );
 739                         return $status;
 740                 }
 741                 // Update file existence predicates
 742                 $predicates['exists'][$this->params['src']] = false;
 743                 $predicates['sha1'][$this->params['src']] = false;
 744                 return $status; // safe to call attempt()
 745         }
 746
 747         protected function doAttempt() {
 748                 // Delete the source file
 749                 return $this->backend->deleteInternal( $this->setFlags( $this->params ) );
 750         }
 751
 752         public function storagePathsChanged() {
 753                 return array( $this->params['src'] );
 754         }
 755 }
 756
 757 /**
 758  * Change metadata for a file at the given storage path in the backend.
 759  * Parameters for this operation are outlined in FileBackend::doOperations().
 760  */
 761 class DescribeFileOp extends FileOp {
 762         protected function allowedParams() {
 763                 return array( array( 'src' ), array( 'headers' ) );
 764         }
 765
 766         protected function doPrecheck( array &$predicates ) {
 767                 $status = Status::newGood();
 768                 // Check if the source file exists
 769                 if ( !$this->fileExists( $this->params['src'], $predicates ) ) {
 770                         $status->fatal( 'backend-fail-notexists', $this->params['src'] );
 771                         return $status;
 772                 // Check if a file can be placed/changed at the source
 773                 } elseif ( !$this->backend->isPathUsableInternal( $this->params['src'] ) ) {
 774                         $status->fatal( 'backend-fail-usable', $this->params['src'] );
 775                         $status->fatal( 'backend-fail-describe', $this->params['src'] );
 776                         return $status;
 777                 }
 778                 // Update file existence predicates
 779                 $predicates['exists'][$this->params['src']] =
 780                         $this->fileExists( $this->params['src'], $predicates );
 781                 $predicates['sha1'][$this->params['src']] =
 782                         $this->fileSha1( $this->params['src'], $predicates );
 783                 return $status; // safe to call attempt()
 784         }
 785
 786         protected function doAttempt() {
 787                 // Update the source file's metadata
 788                 return $this->backend->describeInternal( $this->setFlags( $this->params ) );
 789         }
 790
 791         public function storagePathsChanged() {
 792                 return array( $this->params['src'] );
 793         }
 794 }
 795
 796 /**
 797  * Placeholder operation that has no params and does nothing
 798  */
 799 class NullFileOp extends FileOp {}