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