[Summary view] [Print] [Text view]

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