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] );
88 * Normalize a string if it is a valid storage path
93 protected static function normalizeIfValidStoragePath( $path ) {
94 if ( FileBackend
::isStoragePath( $path ) ) {
95 $res = FileBackend
::normalizeStoragePath( $path );
96 return ( $res !== null ) ?
$res : $path;
102 * Set the batch UUID this operation belongs to
104 * @param string $batchId
107 final public function setBatchId( $batchId ) {
108 $this->batchId
= $batchId;
112 * Get the value of the parameter with the given name
114 * @param string $name
115 * @return mixed Returns null if the parameter is not set
117 final public function getParam( $name ) {
118 return isset( $this->params
[$name] ) ?
$this->params
[$name] : null;
122 * Check if this operation failed precheck() or attempt()
126 final public function failed() {
127 return $this->failed
;
131 * Get a new empty predicates array for precheck()
135 final public static function newPredicates() {
136 return array( 'exists' => array(), 'sha1' => array() );
140 * Get a new empty dependency tracking array for paths read/written to
144 final public static function newDependencies() {
145 return array( 'read' => array(), 'write' => array() );
149 * Update a dependency tracking array to account for this operation
151 * @param array $deps Prior path reads/writes; format of FileOp::newPredicates()
154 final public function applyDependencies( array $deps ) {
155 $deps['read'] +
= array_fill_keys( $this->storagePathsRead(), 1 );
156 $deps['write'] +
= array_fill_keys( $this->storagePathsChanged(), 1 );
161 * Check if this operation changes files listed in $paths
163 * @param array $paths Prior path reads/writes; format of FileOp::newPredicates()
166 final public function dependsOn( array $deps ) {
167 foreach ( $this->storagePathsChanged() as $path ) {
168 if ( isset( $deps['read'][$path] ) ||
isset( $deps['write'][$path] ) ) {
169 return true; // "output" or "anti" dependency
172 foreach ( $this->storagePathsRead() as $path ) {
173 if ( isset( $deps['write'][$path] ) ) {
174 return true; // "flow" dependency
181 * Get the file journal entries for this file operation
183 * @param array $oPredicates Pre-op info about files (format of FileOp::newPredicates)
184 * @param array $nPredicates Post-op info about files (format of FileOp::newPredicates)
187 final public function getJournalEntries( array $oPredicates, array $nPredicates ) {
188 if ( !$this->doOperation
) {
189 return array(); // this is a no-op
191 $nullEntries = array();
192 $updateEntries = array();
193 $deleteEntries = array();
194 $pathsUsed = array_merge( $this->storagePathsRead(), $this->storagePathsChanged() );
195 foreach ( array_unique( $pathsUsed ) as $path ) {
196 $nullEntries[] = array( // assertion for recovery
199 'newSha1' => $this->fileSha1( $path, $oPredicates )
202 foreach ( $this->storagePathsChanged() as $path ) {
203 if ( $nPredicates['sha1'][$path] === false ) { // deleted
204 $deleteEntries[] = array(
209 } else { // created/updated
210 $updateEntries[] = array(
211 'op' => $this->fileExists( $path, $oPredicates ) ?
'update' : 'create',
213 'newSha1' => $nPredicates['sha1'][$path]
217 return array_merge( $nullEntries, $updateEntries, $deleteEntries );
221 * Check preconditions of the operation without writing anything.
222 * This must update $predicates for each path that the op can change
223 * except when a failing status object is returned.
225 * @param Array $predicates
228 final public function precheck( array &$predicates ) {
229 if ( $this->state
!== self
::STATE_NEW
) {
230 return Status
::newFatal( 'fileop-fail-state', self
::STATE_NEW
, $this->state
);
232 $this->state
= self
::STATE_CHECKED
;
233 $status = $this->doPrecheck( $predicates );
234 if ( !$status->isOK() ) {
235 $this->failed
= true;
243 protected function doPrecheck( array &$predicates ) {
244 return Status
::newGood();
248 * Attempt the operation
252 final public function attempt() {
253 if ( $this->state
!== self
::STATE_CHECKED
) {
254 return Status
::newFatal( 'fileop-fail-state', self
::STATE_CHECKED
, $this->state
);
255 } elseif ( $this->failed
) { // failed precheck
256 return Status
::newFatal( 'fileop-fail-attempt-precheck' );
258 $this->state
= self
::STATE_ATTEMPTED
;
259 if ( $this->doOperation
) {
260 $status = $this->doAttempt();
261 if ( !$status->isOK() ) {
262 $this->failed
= true;
263 $this->logFailure( 'attempt' );
266 $status = Status
::newGood();
274 protected function doAttempt() {
275 return Status
::newGood();
279 * Attempt the operation in the background
283 final public function attemptAsync() {
285 $result = $this->attempt();
286 $this->async
= false;
291 * Get the file operation parameters
293 * @return Array (required params list, optional params list, list of params that are paths)
295 protected function allowedParams() {
296 return array( array(), array(), array() );
300 * Adjust params to FileBackendStore internal file calls
302 * @param Array $params
303 * @return Array (required params list, optional params list)
305 protected function setFlags( array $params ) {
306 return array( 'async' => $this->async
) +
$params;
310 * Get a list of storage paths read from for this operation
314 public function storagePathsRead() {
319 * Get a list of storage paths written to for this operation
323 public function storagePathsChanged() {
328 * Check for errors with regards to the destination file already existing.
329 * Also set the destExists, overwriteSameCase and sourceSha1 member variables.
330 * A bad status will be returned if there is no chance it can be overwritten.
332 * @param Array $predicates
335 protected function precheckDestExistence( array $predicates ) {
336 $status = Status
::newGood();
337 // Get hash of source file/string and the destination file
338 $this->sourceSha1
= $this->getSourceSha1Base36(); // FS file or data string
339 if ( $this->sourceSha1
=== null ) { // file in storage?
340 $this->sourceSha1
= $this->fileSha1( $this->params
['src'], $predicates );
342 $this->overwriteSameCase
= false;
343 $this->destExists
= $this->fileExists( $this->params
['dst'], $predicates );
344 if ( $this->destExists
) {
345 if ( $this->getParam( 'overwrite' ) ) {
346 return $status; // OK
347 } elseif ( $this->getParam( 'overwriteSame' ) ) {
348 $dhash = $this->fileSha1( $this->params
['dst'], $predicates );
349 // Check if hashes are valid and match each other...
350 if ( !strlen( $this->sourceSha1
) ||
!strlen( $dhash ) ) {
351 $status->fatal( 'backend-fail-hashes' );
352 } elseif ( $this->sourceSha1
!== $dhash ) {
353 // Give an error if the files are not identical
354 $status->fatal( 'backend-fail-notsame', $this->params
['dst'] );
356 $this->overwriteSameCase
= true; // OK
358 return $status; // do nothing; either OK or bad status
360 $status->fatal( 'backend-fail-alreadyexists', $this->params
['dst'] );
368 * precheckDestExistence() helper function to get the source file SHA-1.
369 * Subclasses should overwride this if the source is not in storage.
371 * @return string|bool Returns false on failure
373 protected function getSourceSha1Base36() {
378 * Check if a file will exist in storage when this operation is attempted
380 * @param string $source Storage path
381 * @param Array $predicates
384 final protected function fileExists( $source, array $predicates ) {
385 if ( isset( $predicates['exists'][$source] ) ) {
386 return $predicates['exists'][$source]; // previous op assures this
388 $params = array( 'src' => $source, 'latest' => true );
389 return $this->backend
->fileExists( $params );
394 * Get the SHA-1 of a file in storage when this operation is attempted
396 * @param string $source Storage path
397 * @param Array $predicates
398 * @return string|bool False on failure
400 final protected function fileSha1( $source, array $predicates ) {
401 if ( isset( $predicates['sha1'][$source] ) ) {
402 return $predicates['sha1'][$source]; // previous op assures this
403 } elseif ( isset( $predicates['exists'][$source] ) && !$predicates['exists'][$source] ) {
404 return false; // previous op assures this
406 $params = array( 'src' => $source, 'latest' => true );
407 return $this->backend
->getFileSha1Base36( $params );
412 * Get the backend this operation is for
414 * @return FileBackendStore
416 public function getBackend() {
417 return $this->backend
;
421 * Log a file operation failure and preserve any temp files
423 * @param string $action
426 final public function logFailure( $action ) {
427 $params = $this->params
;
428 $params['failedAction'] = $action;
430 wfDebugLog( 'FileOperation', get_class( $this ) .
431 " failed (batch #{$this->batchId}): " . FormatJson
::encode( $params ) );
432 } catch ( Exception
$e ) {
433 // bad config? debug log error?
439 * Create a file in the backend with the given content.
440 * Parameters for this operation are outlined in FileBackend::doOperations().
442 class CreateFileOp
extends FileOp
{
443 protected function allowedParams() {
445 array( 'content', 'dst' ),
446 array( 'overwrite', 'overwriteSame', 'headers' ),
451 protected function doPrecheck( array &$predicates ) {
452 $status = Status
::newGood();
453 // Check if the source data is too big
454 if ( strlen( $this->getParam( 'content' ) ) > $this->backend
->maxFileSizeInternal() ) {
455 $status->fatal( 'backend-fail-maxsize',
456 $this->params
['dst'], $this->backend
->maxFileSizeInternal() );
457 $status->fatal( 'backend-fail-create', $this->params
['dst'] );
459 // Check if a file can be placed/changed at the destination
460 } elseif ( !$this->backend
->isPathUsableInternal( $this->params
['dst'] ) ) {
461 $status->fatal( 'backend-fail-usable', $this->params
['dst'] );
462 $status->fatal( 'backend-fail-create', $this->params
['dst'] );
465 // Check if destination file exists
466 $status->merge( $this->precheckDestExistence( $predicates ) );
467 $this->params
['dstExists'] = $this->destExists
; // see FileBackendStore::setFileCache()
468 if ( $status->isOK() ) {
469 // Update file existence predicates
470 $predicates['exists'][$this->params
['dst']] = true;
471 $predicates['sha1'][$this->params
['dst']] = $this->sourceSha1
;
473 return $status; // safe to call attempt()
476 protected function doAttempt() {
477 if ( !$this->overwriteSameCase
) {
478 // Create the file at the destination
479 return $this->backend
->createInternal( $this->setFlags( $this->params
) );
481 return Status
::newGood();
484 protected function getSourceSha1Base36() {
485 return wfBaseConvert( sha1( $this->params
['content'] ), 16, 36, 31 );
488 public function storagePathsChanged() {
489 return array( $this->params
['dst'] );
494 * Store a file into the backend from a file on the file system.
495 * Parameters for this operation are outlined in FileBackend::doOperations().
497 class StoreFileOp
extends FileOp
{
498 protected function allowedParams() {
500 array( 'src', 'dst' ),
501 array( 'overwrite', 'overwriteSame', 'headers' ),
502 array( 'src', 'dst' )
506 protected function doPrecheck( array &$predicates ) {
507 $status = Status
::newGood();
508 // Check if the source file exists on the file system
509 if ( !is_file( $this->params
['src'] ) ) {
510 $status->fatal( 'backend-fail-notexists', $this->params
['src'] );
512 // Check if the source file is too big
513 } elseif ( filesize( $this->params
['src'] ) > $this->backend
->maxFileSizeInternal() ) {
514 $status->fatal( 'backend-fail-maxsize',
515 $this->params
['dst'], $this->backend
->maxFileSizeInternal() );
516 $status->fatal( 'backend-fail-store', $this->params
['src'], $this->params
['dst'] );
518 // Check if a file can be placed/changed at the destination
519 } elseif ( !$this->backend
->isPathUsableInternal( $this->params
['dst'] ) ) {
520 $status->fatal( 'backend-fail-usable', $this->params
['dst'] );
521 $status->fatal( 'backend-fail-store', $this->params
['src'], $this->params
['dst'] );
524 // Check if destination file exists
525 $status->merge( $this->precheckDestExistence( $predicates ) );
526 $this->params
['dstExists'] = $this->destExists
; // see FileBackendStore::setFileCache()
527 if ( $status->isOK() ) {
528 // Update file existence predicates
529 $predicates['exists'][$this->params
['dst']] = true;
530 $predicates['sha1'][$this->params
['dst']] = $this->sourceSha1
;
532 return $status; // safe to call attempt()
535 protected function doAttempt() {
536 if ( !$this->overwriteSameCase
) {
537 // Store the file at the destination
538 return $this->backend
->storeInternal( $this->setFlags( $this->params
) );
540 return Status
::newGood();
543 protected function getSourceSha1Base36() {
544 wfSuppressWarnings();
545 $hash = sha1_file( $this->params
['src'] );
547 if ( $hash !== false ) {
548 $hash = wfBaseConvert( $hash, 16, 36, 31 );
553 public function storagePathsChanged() {
554 return array( $this->params
['dst'] );
559 * Copy a file from one storage path to another in the backend.
560 * Parameters for this operation are outlined in FileBackend::doOperations().
562 class CopyFileOp
extends FileOp
{
563 protected function allowedParams() {
565 array( 'src', 'dst' ),
566 array( 'overwrite', 'overwriteSame', 'ignoreMissingSource', 'headers' ),
567 array( 'src', 'dst' )
571 protected function doPrecheck( array &$predicates ) {
572 $status = Status
::newGood();
573 // Check if the source file exists
574 if ( !$this->fileExists( $this->params
['src'], $predicates ) ) {
575 if ( $this->getParam( 'ignoreMissingSource' ) ) {
576 $this->doOperation
= false; // no-op
577 // Update file existence predicates (cache 404s)
578 $predicates['exists'][$this->params
['src']] = false;
579 $predicates['sha1'][$this->params
['src']] = false;
580 return $status; // nothing to do
582 $status->fatal( 'backend-fail-notexists', $this->params
['src'] );
585 // Check if a file can be placed/changed at the destination
586 } elseif ( !$this->backend
->isPathUsableInternal( $this->params
['dst'] ) ) {
587 $status->fatal( 'backend-fail-usable', $this->params
['dst'] );
588 $status->fatal( 'backend-fail-copy', $this->params
['src'], $this->params
['dst'] );
591 // Check if destination file exists
592 $status->merge( $this->precheckDestExistence( $predicates ) );
593 $this->params
['dstExists'] = $this->destExists
; // see FileBackendStore::setFileCache()
594 if ( $status->isOK() ) {
595 // Update file existence predicates
596 $predicates['exists'][$this->params
['dst']] = true;
597 $predicates['sha1'][$this->params
['dst']] = $this->sourceSha1
;
599 return $status; // safe to call attempt()
602 protected function doAttempt() {
603 if ( $this->overwriteSameCase
) {
604 $status = Status
::newGood(); // nothing to do
605 } elseif ( $this->params
['src'] === $this->params
['dst'] ) {
606 // Just update the destination file headers
607 $headers = $this->getParam( 'headers' ) ?
: array();
608 $status = $this->backend
->describeInternal( $this->setFlags( array(
609 'src' => $this->params
['dst'], 'headers' => $headers
612 // Copy the file to the destination
613 $status = $this->backend
->copyInternal( $this->setFlags( $this->params
) );
618 public function storagePathsRead() {
619 return array( $this->params
['src'] );
622 public function storagePathsChanged() {
623 return array( $this->params
['dst'] );
628 * Move a file from one storage path to another in the backend.
629 * Parameters for this operation are outlined in FileBackend::doOperations().
631 class MoveFileOp
extends FileOp
{
632 protected function allowedParams() {
634 array( 'src', 'dst' ),
635 array( 'overwrite', 'overwriteSame', 'ignoreMissingSource', 'headers' ),
636 array( 'src', 'dst' )
640 protected function doPrecheck( array &$predicates ) {
641 $status = Status
::newGood();
642 // Check if the source file exists
643 if ( !$this->fileExists( $this->params
['src'], $predicates ) ) {
644 if ( $this->getParam( 'ignoreMissingSource' ) ) {
645 $this->doOperation
= false; // no-op
646 // Update file existence predicates (cache 404s)
647 $predicates['exists'][$this->params
['src']] = false;
648 $predicates['sha1'][$this->params
['src']] = false;
649 return $status; // nothing to do
651 $status->fatal( 'backend-fail-notexists', $this->params
['src'] );
654 // Check if a file can be placed/changed at the destination
655 } elseif ( !$this->backend
->isPathUsableInternal( $this->params
['dst'] ) ) {
656 $status->fatal( 'backend-fail-usable', $this->params
['dst'] );
657 $status->fatal( 'backend-fail-move', $this->params
['src'], $this->params
['dst'] );
660 // Check if destination file exists
661 $status->merge( $this->precheckDestExistence( $predicates ) );
662 $this->params
['dstExists'] = $this->destExists
; // see FileBackendStore::setFileCache()
663 if ( $status->isOK() ) {
664 // Update file existence predicates
665 $predicates['exists'][$this->params
['src']] = false;
666 $predicates['sha1'][$this->params
['src']] = false;
667 $predicates['exists'][$this->params
['dst']] = true;
668 $predicates['sha1'][$this->params
['dst']] = $this->sourceSha1
;
670 return $status; // safe to call attempt()
673 protected function doAttempt() {
674 if ( $this->overwriteSameCase
) {
675 if ( $this->params
['src'] === $this->params
['dst'] ) {
676 // Do nothing to the destination (which is also the source)
677 $status = Status
::newGood();
679 // Just delete the source as the destination file needs no changes
680 $status = $this->backend
->deleteInternal( $this->setFlags(
681 array( 'src' => $this->params
['src'] )
684 } elseif ( $this->params
['src'] === $this->params
['dst'] ) {
685 // Just update the destination file headers
686 $headers = $this->getParam( 'headers' ) ?
: array();
687 $status = $this->backend
->describeInternal( $this->setFlags(
688 array( 'src' => $this->params
['dst'], 'headers' => $headers )
691 // Move the file to the destination
692 $status = $this->backend
->moveInternal( $this->setFlags( $this->params
) );
697 public function storagePathsRead() {
698 return array( $this->params
['src'] );
701 public function storagePathsChanged() {
702 return array( $this->params
['src'], $this->params
['dst'] );
707 * Delete a file at the given storage path from the backend.
708 * Parameters for this operation are outlined in FileBackend::doOperations().
710 class DeleteFileOp
extends FileOp
{
711 protected function allowedParams() {
712 return array( array( 'src' ), array( 'ignoreMissingSource' ), array( 'src' ) );
715 protected function doPrecheck( array &$predicates ) {
716 $status = Status
::newGood();
717 // Check if the source file exists
718 if ( !$this->fileExists( $this->params
['src'], $predicates ) ) {
719 if ( $this->getParam( 'ignoreMissingSource' ) ) {
720 $this->doOperation
= false; // no-op
721 // Update file existence predicates (cache 404s)
722 $predicates['exists'][$this->params
['src']] = false;
723 $predicates['sha1'][$this->params
['src']] = false;
724 return $status; // nothing to do
726 $status->fatal( 'backend-fail-notexists', $this->params
['src'] );
729 // Check if a file can be placed/changed at the source
730 } elseif ( !$this->backend
->isPathUsableInternal( $this->params
['src'] ) ) {
731 $status->fatal( 'backend-fail-usable', $this->params
['src'] );
732 $status->fatal( 'backend-fail-delete', $this->params
['src'] );
735 // Update file existence predicates
736 $predicates['exists'][$this->params
['src']] = false;
737 $predicates['sha1'][$this->params
['src']] = false;
738 return $status; // safe to call attempt()
741 protected function doAttempt() {
742 // Delete the source file
743 return $this->backend
->deleteInternal( $this->setFlags( $this->params
) );
746 public function storagePathsChanged() {
747 return array( $this->params
['src'] );
752 * Change metadata for a file at the given storage path in the backend.
753 * Parameters for this operation are outlined in FileBackend::doOperations().
755 class DescribeFileOp
extends FileOp
{
756 protected function allowedParams() {
757 return array( array( 'src' ), array( 'headers' ), array( 'src' ) );
760 protected function doPrecheck( array &$predicates ) {
761 $status = Status
::newGood();
762 // Check if the source file exists
763 if ( !$this->fileExists( $this->params
['src'], $predicates ) ) {
764 $status->fatal( 'backend-fail-notexists', $this->params
['src'] );
766 // Check if a file can be placed/changed at the source
767 } elseif ( !$this->backend
->isPathUsableInternal( $this->params
['src'] ) ) {
768 $status->fatal( 'backend-fail-usable', $this->params
['src'] );
769 $status->fatal( 'backend-fail-describe', $this->params
['src'] );
772 // Update file existence predicates
773 $predicates['exists'][$this->params
['src']] =
774 $this->fileExists( $this->params
['src'], $predicates );
775 $predicates['sha1'][$this->params
['src']] =
776 $this->fileSha1( $this->params
['src'], $predicates );
777 return $status; // safe to call attempt()
780 protected function doAttempt() {
781 // Update the source file's metadata
782 return $this->backend
->describeInternal( $this->setFlags( $this->params
) );
785 public function storagePathsChanged() {
786 return array( $this->params
['src'] );
791 * Placeholder operation that has no params and does nothing
793 class NullFileOp
extends FileOp
{}