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