3 * Helper class for representing operations with transaction support.
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.
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.
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
21 * @ingroup FileBackend
22 * @author Aaron Schulz
26 * FileBackend helper class for representing operations.
27 * Do not use this class from places outside FileBackend.
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.
33 * @ingroup FileBackend
36 abstract class FileOp
{
38 protected $params = array();
39 /** @var FileBackendStore */
42 protected $state = self
::STATE_NEW
; // integer
43 protected $failed = false; // boolean
44 protected $async = false; // boolean
45 protected $batchId; // string
47 protected $doOperation = true; // boolean; operation is not a no-op
48 protected $sourceSha1; // string
49 protected $overwriteSameCase; // boolean
50 protected $destExists; // boolean
52 /* Object life-cycle */
54 const STATE_CHECKED
= 2;
55 const STATE_ATTEMPTED
= 3;
58 * Build a new batch file operation transaction
60 * @param FileBackendStore $backend
61 * @param Array $params
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];
71 throw new MWException( "File operation missing parameter '$name'." );
74 foreach ( $optional as $name ) {
75 if ( isset( $params[$name] ) ) {
76 $this->params
[$name] = $params[$name];
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] );
89 * Normalize a string if it is a valid storage path
94 protected static function normalizeIfValidStoragePath( $path ) {
95 if ( FileBackend
::isStoragePath( $path ) ) {
96 $res = FileBackend
::normalizeStoragePath( $path );
97 return ( $res !== null ) ?
$res : $path;
103 * Set the batch UUID this operation belongs to
105 * @param string $batchId
108 final public function setBatchId( $batchId ) {
109 $this->batchId
= $batchId;
113 * Get the value of the parameter with the given name
115 * @param string $name
116 * @return mixed Returns null if the parameter is not set
118 final public function getParam( $name ) {
119 return isset( $this->params
[$name] ) ?
$this->params
[$name] : null;
123 * Check if this operation failed precheck() or attempt()
127 final public function failed() {
128 return $this->failed
;
132 * Get a new empty predicates array for precheck()
136 final public static function newPredicates() {
137 return array( 'exists' => array(), 'sha1' => array() );
141 * Get a new empty dependency tracking array for paths read/written to
145 final public static function newDependencies() {
146 return array( 'read' => array(), 'write' => array() );
150 * Update a dependency tracking array to account for this operation
152 * @param array $deps Prior path reads/writes; format of FileOp::newPredicates()
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 );
162 * Check if this operation changes files listed in $paths
164 * @param array $paths Prior path reads/writes; format of FileOp::newPredicates()
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
173 foreach ( $this->storagePathsRead() as $path ) {
174 if ( isset( $deps['write'][$path] ) ) {
175 return true; // "flow" dependency
182 * Get the file journal entries for this file operation
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)
188 final public function getJournalEntries( array $oPredicates, array $nPredicates ) {
189 if ( !$this->doOperation
) {
190 return array(); // this is a no-op
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
200 'newSha1' => $this->fileSha1( $path, $oPredicates )
203 foreach ( $this->storagePathsChanged() as $path ) {
204 if ( $nPredicates['sha1'][$path] === false ) { // deleted
205 $deleteEntries[] = array(
210 } else { // created/updated
211 $updateEntries[] = array(
212 'op' => $this->fileExists( $path, $oPredicates ) ?
'update' : 'create',
214 'newSha1' => $nPredicates['sha1'][$path]
218 return array_merge( $nullEntries, $updateEntries, $deleteEntries );
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.
226 * @param Array $predicates
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
);
233 $this->state
= self
::STATE_CHECKED
;
234 $status = $this->doPrecheck( $predicates );
235 if ( !$status->isOK() ) {
236 $this->failed
= true;
244 protected function doPrecheck( array &$predicates ) {
245 return Status
::newGood();
249 * Attempt the operation
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' );
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' );
267 $status = Status
::newGood();
275 protected function doAttempt() {
276 return Status
::newGood();
280 * Attempt the operation in the background
284 final public function attemptAsync() {
286 $result = $this->attempt();
287 $this->async
= false;
292 * Get the file operation parameters
294 * @return Array (required params list, optional params list, list of params that are paths)
296 protected function allowedParams() {
297 return array( array(), array(), array() );
301 * Adjust params to FileBackendStore internal file calls
303 * @param Array $params
304 * @return Array (required params list, optional params list)
306 protected function setFlags( array $params ) {
307 return array( 'async' => $this->async
) +
$params;
311 * Get a list of storage paths read from for this operation
315 public function storagePathsRead() {
320 * Get a list of storage paths written to for this operation
324 public function storagePathsChanged() {
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.
333 * @param Array $predicates
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 );
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'] );
357 $this->overwriteSameCase
= true; // OK
359 return $status; // do nothing; either OK or bad status
361 $status->fatal( 'backend-fail-alreadyexists', $this->params
['dst'] );
369 * precheckDestExistence() helper function to get the source file SHA-1.
370 * Subclasses should overwride this if the source is not in storage.
372 * @return string|bool Returns false on failure
374 protected function getSourceSha1Base36() {
379 * Check if a file will exist in storage when this operation is attempted
381 * @param string $source Storage path
382 * @param Array $predicates
385 final protected function fileExists( $source, array $predicates ) {
386 if ( isset( $predicates['exists'][$source] ) ) {
387 return $predicates['exists'][$source]; // previous op assures this
389 $params = array( 'src' => $source, 'latest' => true );
390 return $this->backend
->fileExists( $params );
395 * Get the SHA-1 of a file in storage when this operation is attempted
397 * @param string $source Storage path
398 * @param Array $predicates
399 * @return string|bool False on failure
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
407 $params = array( 'src' => $source, 'latest' => true );
408 return $this->backend
->getFileSha1Base36( $params );
413 * Get the backend this operation is for
415 * @return FileBackendStore
417 public function getBackend() {
418 return $this->backend
;
422 * Log a file operation failure and preserve any temp files
424 * @param string $action
427 final public function logFailure( $action ) {
428 $params = $this->params
;
429 $params['failedAction'] = $action;
431 wfDebugLog( 'FileOperation', get_class( $this ) .
432 " failed (batch #{$this->batchId}): " . FormatJson
::encode( $params ) );
433 } catch ( Exception
$e ) {
434 // bad config? debug log error?
440 * Create a file in the backend with the given content.
441 * Parameters for this operation are outlined in FileBackend::doOperations().
443 class CreateFileOp
extends FileOp
{
444 protected function allowedParams() {
446 array( 'content', 'dst' ),
447 array( 'overwrite', 'overwriteSame', 'headers' ),
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'] );
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'] );
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
;
474 return $status; // safe to call attempt()
477 protected function doAttempt() {
478 if ( !$this->overwriteSameCase
) {
479 // Create the file at the destination
480 return $this->backend
->createInternal( $this->setFlags( $this->params
) );
482 return Status
::newGood();
485 protected function getSourceSha1Base36() {
486 return wfBaseConvert( sha1( $this->params
['content'] ), 16, 36, 31 );
489 public function storagePathsChanged() {
490 return array( $this->params
['dst'] );
495 * Store a file into the backend from a file on the file system.
496 * Parameters for this operation are outlined in FileBackend::doOperations().
498 class StoreFileOp
extends FileOp
{
499 protected function allowedParams() {
501 array( 'src', 'dst' ),
502 array( 'overwrite', 'overwriteSame', 'headers' ),
503 array( 'src', 'dst' )
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'] );
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'] );
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'] );
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
;
533 return $status; // safe to call attempt()
536 protected function doAttempt() {
537 if ( !$this->overwriteSameCase
) {
538 // Store the file at the destination
539 return $this->backend
->storeInternal( $this->setFlags( $this->params
) );
541 return Status
::newGood();
544 protected function getSourceSha1Base36() {
545 wfSuppressWarnings();
546 $hash = sha1_file( $this->params
['src'] );
548 if ( $hash !== false ) {
549 $hash = wfBaseConvert( $hash, 16, 36, 31 );
554 public function storagePathsChanged() {
555 return array( $this->params
['dst'] );
560 * Copy a file from one storage path to another in the backend.
561 * Parameters for this operation are outlined in FileBackend::doOperations().
563 class CopyFileOp
extends FileOp
{
564 protected function allowedParams() {
566 array( 'src', 'dst' ),
567 array( 'overwrite', 'overwriteSame', 'ignoreMissingSource', 'headers' ),
568 array( 'src', 'dst' )
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
583 $status->fatal( 'backend-fail-notexists', $this->params
['src'] );
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'] );
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
;
600 return $status; // safe to call attempt()
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
613 // Copy the file to the destination
614 $status = $this->backend
->copyInternal( $this->setFlags( $this->params
) );
619 public function storagePathsRead() {
620 return array( $this->params
['src'] );
623 public function storagePathsChanged() {
624 return array( $this->params
['dst'] );
629 * Move a file from one storage path to another in the backend.
630 * Parameters for this operation are outlined in FileBackend::doOperations().
632 class MoveFileOp
extends FileOp
{
633 protected function allowedParams() {
635 array( 'src', 'dst' ),
636 array( 'overwrite', 'overwriteSame', 'ignoreMissingSource', 'headers' ),
637 array( 'src', 'dst' )
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
652 $status->fatal( 'backend-fail-notexists', $this->params
['src'] );
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'] );
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
;
671 return $status; // safe to call attempt()
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();
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'] )
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 )
692 // Move the file to the destination
693 $status = $this->backend
->moveInternal( $this->setFlags( $this->params
) );
698 public function storagePathsRead() {
699 return array( $this->params
['src'] );
702 public function storagePathsChanged() {
703 return array( $this->params
['src'], $this->params
['dst'] );
708 * Delete a file at the given storage path from the backend.
709 * Parameters for this operation are outlined in FileBackend::doOperations().
711 class DeleteFileOp
extends FileOp
{
712 protected function allowedParams() {
713 return array( array( 'src' ), array( 'ignoreMissingSource' ), array( 'src' ) );
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
727 $status->fatal( 'backend-fail-notexists', $this->params
['src'] );
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'] );
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()
742 protected function doAttempt() {
743 // Delete the source file
744 return $this->backend
->deleteInternal( $this->setFlags( $this->params
) );
747 public function storagePathsChanged() {
748 return array( $this->params
['src'] );
753 * Change metadata for a file at the given storage path in the backend.
754 * Parameters for this operation are outlined in FileBackend::doOperations().
756 class DescribeFileOp
extends FileOp
{
757 protected function allowedParams() {
758 return array( array( 'src' ), array( 'headers' ), array( 'src' ) );
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'] );
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'] );
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()
781 protected function doAttempt() {
782 // Update the source file's metadata
783 return $this->backend
->describeInternal( $this->setFlags( $this->params
) );
786 public function storagePathsChanged() {
787 return array( $this->params
['src'] );
792 * Placeholder operation that has no params and does nothing
794 class NullFileOp
extends FileOp
{}