FileOp.php

Go to the documentation of this file.

<?php
abstract class FileOp {
    protected $params = [];

    protected $backend;

    protected $state = self::STATE_NEW;

    protected $failed = false;

    protected $async = false;

    protected $batchId;

    protected $doOperation = true;

    protected $sourceSha1;

    protected $overwriteSameCase;

    protected $destExists;

    /* Object life-cycle */
    const STATE_NEW = 1;
    const STATE_CHECKED = 2;
    const STATE_ATTEMPTED = 3;

    final public function __construct( FileBackendStore $backend, array $params ) {
        $this->backend = $backend;
        list( $required, $optional, $paths ) = $this->allowedParams();
        foreach ( $required as $name ) {
            if ( isset( $params[$name] ) ) {
                $this->params[$name] = $params[$name];
            } else {
                throw new FileBackendError( "File operation missing parameter '$name'." );
            }
        }
        foreach ( $optional as $name ) {
            if ( isset( $params[$name] ) ) {
                $this->params[$name] = $params[$name];
            }
        }
        foreach ( $paths as $name ) {
            if ( isset( $this->params[$name] ) ) {
                // Normalize paths so the paths to the same file have the same string
                $this->params[$name] = self::normalizeIfValidStoragePath( $this->params[$name] );
            }
        }
    }

    protected static function normalizeIfValidStoragePath( $path ) {
        if ( FileBackend::isStoragePath( $path ) ) {
            $res = FileBackend::normalizeStoragePath( $path );

            return ( $res !== null ) ? $res : $path;
        }

        return $path;
    }

    final public function setBatchId( $batchId ) {
        $this->batchId = $batchId;
    }

    final public function getParam( $name ) {
        return isset( $this->params[$name] ) ? $this->params[$name] : null;
    }

    final public function failed() {
        return $this->failed;
    }

    final public static function newPredicates() {
        return [ 'exists' => [], 'sha1' => [] ];
    }

    final public static function newDependencies() {
        return [ 'read' => [], 'write' => [] ];
    }

    final public function applyDependencies( array $deps ) {
        $deps['read'] += array_fill_keys( $this->storagePathsRead(), 1 );
        $deps['write'] += array_fill_keys( $this->storagePathsChanged(), 1 );

        return $deps;
    }

    final public function dependsOn( array $deps ) {
        foreach ( $this->storagePathsChanged() as $path ) {
            if ( isset( $deps['read'][$path] ) || isset( $deps['write'][$path] ) ) {
                return true; // "output" or "anti" dependency
            }
        }
        foreach ( $this->storagePathsRead() as $path ) {
            if ( isset( $deps['write'][$path] ) ) {
                return true; // "flow" dependency
            }
        }

        return false;
    }

    final public function getJournalEntries( array $oPredicates, array $nPredicates ) {
        if ( !$this->doOperation ) {
            return []; // this is a no-op
        }
        $nullEntries = [];
        $updateEntries = [];
        $deleteEntries = [];
        $pathsUsed = array_merge( $this->storagePathsRead(), $this->storagePathsChanged() );
        foreach ( array_unique( $pathsUsed ) as $path ) {
            $nullEntries[] = [ // assertion for recovery
                'op' => 'null',
                'path' => $path,
                'newSha1' => $this->fileSha1( $path, $oPredicates )
            ];
        }
        foreach ( $this->storagePathsChanged() as $path ) {
            if ( $nPredicates['sha1'][$path] === false ) { // deleted
                $deleteEntries[] = [
                    'op' => 'delete',
                    'path' => $path,
                    'newSha1' => ''
                ];
            } else { // created/updated
                $updateEntries[] = [
                    'op' => $this->fileExists( $path, $oPredicates ) ? 'update' : 'create',
                    'path' => $path,
                    'newSha1' => $nPredicates['sha1'][$path]
                ];
            }
        }

        return array_merge( $nullEntries, $updateEntries, $deleteEntries );
    }

    final public function precheck( array &$predicates ) {
        if ( $this->state !== self::STATE_NEW ) {
            return Status::newFatal( 'fileop-fail-state', self::STATE_NEW, $this->state );
        }
        $this->state = self::STATE_CHECKED;
        $status = $this->doPrecheck( $predicates );
        if ( !$status->isOK() ) {
            $this->failed = true;
        }

        return $status;
    }

    protected function doPrecheck( array &$predicates ) {
        return Status::newGood();
    }

    final public function attempt() {
        if ( $this->state !== self::STATE_CHECKED ) {
            return Status::newFatal( 'fileop-fail-state', self::STATE_CHECKED, $this->state );
        } elseif ( $this->failed ) { // failed precheck
            return Status::newFatal( 'fileop-fail-attempt-precheck' );
        }
        $this->state = self::STATE_ATTEMPTED;
        if ( $this->doOperation ) {
            $status = $this->doAttempt();
            if ( !$status->isOK() ) {
                $this->failed = true;
                $this->logFailure( 'attempt' );
            }
        } else { // no-op
            $status = Status::newGood();
        }

        return $status;
    }

    protected function doAttempt() {
        return Status::newGood();
    }

    final public function attemptAsync() {
        $this->async = true;
        $result = $this->attempt();
        $this->async = false;

        return $result;
    }

    protected function allowedParams() {
        return [ [], [], [] ];
    }

    protected function setFlags( array $params ) {
        return [ 'async' => $this->async ] + $params;
    }

    public function storagePathsRead() {
        return [];
    }

    public function storagePathsChanged() {
        return [];
    }

    protected function precheckDestExistence( array $predicates ) {
        $status = Status::newGood();
        // Get hash of source file/string and the destination file
        $this->sourceSha1 = $this->getSourceSha1Base36(); // FS file or data string
        if ( $this->sourceSha1 === null ) { // file in storage?
            $this->sourceSha1 = $this->fileSha1( $this->params['src'], $predicates );
        }
        $this->overwriteSameCase = false;
        $this->destExists = $this->fileExists( $this->params['dst'], $predicates );
        if ( $this->destExists ) {
            if ( $this->getParam( 'overwrite' ) ) {
                return $status; // OK
            } elseif ( $this->getParam( 'overwriteSame' ) ) {
                $dhash = $this->fileSha1( $this->params['dst'], $predicates );
                // Check if hashes are valid and match each other...
                if ( !strlen( $this->sourceSha1 ) || !strlen( $dhash ) ) {
                    $status->fatal( 'backend-fail-hashes' );
                } elseif ( $this->sourceSha1 !== $dhash ) {
                    // Give an error if the files are not identical
                    $status->fatal( 'backend-fail-notsame', $this->params['dst'] );
                } else {
                    $this->overwriteSameCase = true; // OK
                }

                return $status; // do nothing; either OK or bad status
            } else {
                $status->fatal( 'backend-fail-alreadyexists', $this->params['dst'] );

                return $status;
            }
        }

        return $status;
    }

    protected function getSourceSha1Base36() {
        return null; // N/A
    }

    final protected function fileExists( $source, array $predicates ) {
        if ( isset( $predicates['exists'][$source] ) ) {
            return $predicates['exists'][$source]; // previous op assures this
        } else {
            $params = [ 'src' => $source, 'latest' => true ];

            return $this->backend->fileExists( $params );
        }
    }

    final protected function fileSha1( $source, array $predicates ) {
        if ( isset( $predicates['sha1'][$source] ) ) {
            return $predicates['sha1'][$source]; // previous op assures this
        } elseif ( isset( $predicates['exists'][$source] ) && !$predicates['exists'][$source] ) {
            return false; // previous op assures this
        } else {
            $params = [ 'src' => $source, 'latest' => true ];

            return $this->backend->getFileSha1Base36( $params );
        }
    }

    public function getBackend() {
        return $this->backend;
    }

    final public function logFailure( $action ) {
        $params = $this->params;
        $params['failedAction'] = $action;
        try {
            wfDebugLog( 'FileOperation', get_class( $this ) .
                " failed (batch #{$this->batchId}): " . FormatJson::encode( $params ) );
        } catch ( Exception $e ) {
            // bad config? debug log error?
        }
    }
}

class CreateFileOp extends FileOp {
    protected function allowedParams() {
        return [
            [ 'content', 'dst' ],
            [ 'overwrite', 'overwriteSame', 'headers' ],
            [ 'dst' ]
        ];
    }

    protected function doPrecheck( array &$predicates ) {
        $status = Status::newGood();
        // Check if the source data is too big
        if ( strlen( $this->getParam( 'content' ) ) > $this->backend->maxFileSizeInternal() ) {
            $status->fatal( 'backend-fail-maxsize',
                $this->params['dst'], $this->backend->maxFileSizeInternal() );
            $status->fatal( 'backend-fail-create', $this->params['dst'] );

            return $status;
        // Check if a file can be placed/changed at the destination
        } elseif ( !$this->backend->isPathUsableInternal( $this->params['dst'] ) ) {
            $status->fatal( 'backend-fail-usable', $this->params['dst'] );
            $status->fatal( 'backend-fail-create', $this->params['dst'] );

            return $status;
        }
        // Check if destination file exists
        $status->merge( $this->precheckDestExistence( $predicates ) );
        $this->params['dstExists'] = $this->destExists; // see FileBackendStore::setFileCache()
        if ( $status->isOK() ) {
            // Update file existence predicates
            $predicates['exists'][$this->params['dst']] = true;
            $predicates['sha1'][$this->params['dst']] = $this->sourceSha1;
        }

        return $status; // safe to call attempt()
    }

    protected function doAttempt() {
        if ( !$this->overwriteSameCase ) {
            // Create the file at the destination
            return $this->backend->createInternal( $this->setFlags( $this->params ) );
        }

        return Status::newGood();
    }

    protected function getSourceSha1Base36() {
        return Wikimedia\base_convert( sha1( $this->params['content'] ), 16, 36, 31 );
    }

    public function storagePathsChanged() {
        return [ $this->params['dst'] ];
    }
}

class StoreFileOp extends FileOp {
    protected function allowedParams() {
        return [
            [ 'src', 'dst' ],
            [ 'overwrite', 'overwriteSame', 'headers' ],
            [ 'src', 'dst' ]
        ];
    }

    protected function doPrecheck( array &$predicates ) {
        $status = Status::newGood();
        // Check if the source file exists on the file system
        if ( !is_file( $this->params['src'] ) ) {
            $status->fatal( 'backend-fail-notexists', $this->params['src'] );

            return $status;
        // Check if the source file is too big
        } elseif ( filesize( $this->params['src'] ) > $this->backend->maxFileSizeInternal() ) {
            $status->fatal( 'backend-fail-maxsize',
                $this->params['dst'], $this->backend->maxFileSizeInternal() );
            $status->fatal( 'backend-fail-store', $this->params['src'], $this->params['dst'] );

            return $status;
        // Check if a file can be placed/changed at the destination
        } elseif ( !$this->backend->isPathUsableInternal( $this->params['dst'] ) ) {
            $status->fatal( 'backend-fail-usable', $this->params['dst'] );
            $status->fatal( 'backend-fail-store', $this->params['src'], $this->params['dst'] );

            return $status;
        }
        // Check if destination file exists
        $status->merge( $this->precheckDestExistence( $predicates ) );
        $this->params['dstExists'] = $this->destExists; // see FileBackendStore::setFileCache()
        if ( $status->isOK() ) {
            // Update file existence predicates
            $predicates['exists'][$this->params['dst']] = true;
            $predicates['sha1'][$this->params['dst']] = $this->sourceSha1;
        }

        return $status; // safe to call attempt()
    }

    protected function doAttempt() {
        if ( !$this->overwriteSameCase ) {
            // Store the file at the destination
            return $this->backend->storeInternal( $this->setFlags( $this->params ) );
        }

        return Status::newGood();
    }

    protected function getSourceSha1Base36() {
        MediaWiki\suppressWarnings();
        $hash = sha1_file( $this->params['src'] );
        MediaWiki\restoreWarnings();
        if ( $hash !== false ) {
            $hash = Wikimedia\base_convert( $hash, 16, 36, 31 );
        }

        return $hash;
    }

    public function storagePathsChanged() {
        return [ $this->params['dst'] ];
    }
}

class CopyFileOp extends FileOp {
    protected function allowedParams() {
        return [
            [ 'src', 'dst' ],
            [ 'overwrite', 'overwriteSame', 'ignoreMissingSource', 'headers' ],
            [ 'src', 'dst' ]
        ];
    }

    protected function doPrecheck( array &$predicates ) {
        $status = Status::newGood();
        // Check if the source file exists
        if ( !$this->fileExists( $this->params['src'], $predicates ) ) {
            if ( $this->getParam( 'ignoreMissingSource' ) ) {
                $this->doOperation = false; // no-op
                // Update file existence predicates (cache 404s)
                $predicates['exists'][$this->params['src']] = false;
                $predicates['sha1'][$this->params['src']] = false;

                return $status; // nothing to do
            } else {
                $status->fatal( 'backend-fail-notexists', $this->params['src'] );

                return $status;
            }
            // Check if a file can be placed/changed at the destination
        } elseif ( !$this->backend->isPathUsableInternal( $this->params['dst'] ) ) {
            $status->fatal( 'backend-fail-usable', $this->params['dst'] );
            $status->fatal( 'backend-fail-copy', $this->params['src'], $this->params['dst'] );

            return $status;
        }
        // Check if destination file exists
        $status->merge( $this->precheckDestExistence( $predicates ) );
        $this->params['dstExists'] = $this->destExists; // see FileBackendStore::setFileCache()
        if ( $status->isOK() ) {
            // Update file existence predicates
            $predicates['exists'][$this->params['dst']] = true;
            $predicates['sha1'][$this->params['dst']] = $this->sourceSha1;
        }

        return $status; // safe to call attempt()
    }

    protected function doAttempt() {
        if ( $this->overwriteSameCase ) {
            $status = Status::newGood(); // nothing to do
        } elseif ( $this->params['src'] === $this->params['dst'] ) {
            // Just update the destination file headers
            $headers = $this->getParam( 'headers' ) ?: [];
            $status = $this->backend->describeInternal( $this->setFlags( [
                'src' => $this->params['dst'], 'headers' => $headers
            ] ) );
        } else {
            // Copy the file to the destination
            $status = $this->backend->copyInternal( $this->setFlags( $this->params ) );
        }

        return $status;
    }

    public function storagePathsRead() {
        return [ $this->params['src'] ];
    }

    public function storagePathsChanged() {
        return [ $this->params['dst'] ];
    }
}

class MoveFileOp extends FileOp {
    protected function allowedParams() {
        return [
            [ 'src', 'dst' ],
            [ 'overwrite', 'overwriteSame', 'ignoreMissingSource', 'headers' ],
            [ 'src', 'dst' ]
        ];
    }

    protected function doPrecheck( array &$predicates ) {
        $status = Status::newGood();
        // Check if the source file exists
        if ( !$this->fileExists( $this->params['src'], $predicates ) ) {
            if ( $this->getParam( 'ignoreMissingSource' ) ) {
                $this->doOperation = false; // no-op
                // Update file existence predicates (cache 404s)
                $predicates['exists'][$this->params['src']] = false;
                $predicates['sha1'][$this->params['src']] = false;

                return $status; // nothing to do
            } else {
                $status->fatal( 'backend-fail-notexists', $this->params['src'] );

                return $status;
            }
        // Check if a file can be placed/changed at the destination
        } elseif ( !$this->backend->isPathUsableInternal( $this->params['dst'] ) ) {
            $status->fatal( 'backend-fail-usable', $this->params['dst'] );
            $status->fatal( 'backend-fail-move', $this->params['src'], $this->params['dst'] );

            return $status;
        }
        // Check if destination file exists
        $status->merge( $this->precheckDestExistence( $predicates ) );
        $this->params['dstExists'] = $this->destExists; // see FileBackendStore::setFileCache()
        if ( $status->isOK() ) {
            // Update file existence predicates
            $predicates['exists'][$this->params['src']] = false;
            $predicates['sha1'][$this->params['src']] = false;
            $predicates['exists'][$this->params['dst']] = true;
            $predicates['sha1'][$this->params['dst']] = $this->sourceSha1;
        }

        return $status; // safe to call attempt()
    }

    protected function doAttempt() {
        if ( $this->overwriteSameCase ) {
            if ( $this->params['src'] === $this->params['dst'] ) {
                // Do nothing to the destination (which is also the source)
                $status = Status::newGood();
            } else {
                // Just delete the source as the destination file needs no changes
                $status = $this->backend->deleteInternal( $this->setFlags(
                    [ 'src' => $this->params['src'] ]
                ) );
            }
        } elseif ( $this->params['src'] === $this->params['dst'] ) {
            // Just update the destination file headers
            $headers = $this->getParam( 'headers' ) ?: [];
            $status = $this->backend->describeInternal( $this->setFlags(
                [ 'src' => $this->params['dst'], 'headers' => $headers ]
            ) );
        } else {
            // Move the file to the destination
            $status = $this->backend->moveInternal( $this->setFlags( $this->params ) );
        }

        return $status;
    }

    public function storagePathsRead() {
        return [ $this->params['src'] ];
    }

    public function storagePathsChanged() {
        return [ $this->params['src'], $this->params['dst'] ];
    }
}

class DeleteFileOp extends FileOp {
    protected function allowedParams() {
        return [ [ 'src' ], [ 'ignoreMissingSource' ], [ 'src' ] ];
    }

    protected function doPrecheck( array &$predicates ) {
        $status = Status::newGood();
        // Check if the source file exists
        if ( !$this->fileExists( $this->params['src'], $predicates ) ) {
            if ( $this->getParam( 'ignoreMissingSource' ) ) {
                $this->doOperation = false; // no-op
                // Update file existence predicates (cache 404s)
                $predicates['exists'][$this->params['src']] = false;
                $predicates['sha1'][$this->params['src']] = false;

                return $status; // nothing to do
            } else {
                $status->fatal( 'backend-fail-notexists', $this->params['src'] );

                return $status;
            }
        // Check if a file can be placed/changed at the source
        } elseif ( !$this->backend->isPathUsableInternal( $this->params['src'] ) ) {
            $status->fatal( 'backend-fail-usable', $this->params['src'] );
            $status->fatal( 'backend-fail-delete', $this->params['src'] );

            return $status;
        }
        // Update file existence predicates
        $predicates['exists'][$this->params['src']] = false;
        $predicates['sha1'][$this->params['src']] = false;

        return $status; // safe to call attempt()
    }

    protected function doAttempt() {
        // Delete the source file
        return $this->backend->deleteInternal( $this->setFlags( $this->params ) );
    }

    public function storagePathsChanged() {
        return [ $this->params['src'] ];
    }
}

class DescribeFileOp extends FileOp {
    protected function allowedParams() {
        return [ [ 'src' ], [ 'headers' ], [ 'src' ] ];
    }

    protected function doPrecheck( array &$predicates ) {
        $status = Status::newGood();
        // Check if the source file exists
        if ( !$this->fileExists( $this->params['src'], $predicates ) ) {
            $status->fatal( 'backend-fail-notexists', $this->params['src'] );

            return $status;
        // Check if a file can be placed/changed at the source
        } elseif ( !$this->backend->isPathUsableInternal( $this->params['src'] ) ) {
            $status->fatal( 'backend-fail-usable', $this->params['src'] );
            $status->fatal( 'backend-fail-describe', $this->params['src'] );

            return $status;
        }
        // Update file existence predicates
        $predicates['exists'][$this->params['src']] =
            $this->fileExists( $this->params['src'], $predicates );
        $predicates['sha1'][$this->params['src']] =
            $this->fileSha1( $this->params['src'], $predicates );

        return $status; // safe to call attempt()
    }

    protected function doAttempt() {
        // Update the source file's metadata
        return $this->backend->describeInternal( $this->setFlags( $this->params ) );
    }

    public function storagePathsChanged() {
        return [ $this->params['src'] ];
    }
}

class NullFileOp extends FileOp {
}