FileOp.php

Go to the documentation of this file.

<?php
use MediaWiki\Json\FormatJson;
use Psr\Log\LoggerInterface;
use Wikimedia\FileBackend\FileBackend;
use Wikimedia\RequestTimeout\TimeoutException;
 
abstract class FileOp {
    protected $backend;
    protected $logger;
 
    protected $params = [];
 
    protected $state = self::STATE_NEW;
    protected $failed = false;
    protected $async = false;
    protected $noOp = false;
 
    protected $overwriteSameCase;
    protected $destExists;
 
    private const STATE_NEW = 1;
    private const STATE_CHECKED = 2;
    private const STATE_ATTEMPTED = 3;
 
    final public function __construct(
        FileBackendStore $backend, array $params, LoggerInterface $logger
    ) {
        $this->backend = $backend;
        $this->logger = $logger;
        [ $required, $optional, $paths ] = $this->allowedParams();
        foreach ( $required as $name ) {
            if ( isset( $params[$name] ) ) {
                $this->params[$name] = $params[$name];
            } else {
                throw new InvalidArgumentException( "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 ?? $path;
        }
 
        return $path;
    }
 
    final public function getParam( $name ) {
        return $this->params[$name] ?? null;
    }
 
    final public function failed() {
        return $this->failed;
    }
 
    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 precheck( FileStatePredicates $predicates ) {
        if ( $this->state !== self::STATE_NEW ) {
            return StatusValue::newFatal( 'fileop-fail-state', self::STATE_NEW, $this->state );
        }
        $this->state = self::STATE_CHECKED;
 
        $status = StatusValue::newGood();
        foreach ( $this->storagePathsReadOrChanged() as $path ) {
            if ( !$this->backend->isPathUsableInternal( $path ) ) {
                $status->fatal( 'backend-fail-usable', $path );
            }
        }
        if ( !$status->isOK() ) {
            return $status;
        }
 
        $opPredicates = $predicates->snapshot( $this->storagePathsReadOrChanged() );
        $status = $this->doPrecheck( $opPredicates, $predicates );
        if ( !$status->isOK() ) {
            $this->failed = true;
        }
 
        return $status;
    }
 
    protected function doPrecheck(
        FileStatePredicates $opPredicates,
        FileStatePredicates $batchPredicates
    ) {
        return StatusValue::newGood();
    }
 
    final public function attempt() {
        if ( $this->state !== self::STATE_CHECKED ) {
            return StatusValue::newFatal( 'fileop-fail-state', self::STATE_CHECKED, $this->state );
        } elseif ( $this->failed ) { // failed precheck
            return StatusValue::newFatal( 'fileop-fail-attempt-precheck' );
        }
        $this->state = self::STATE_ATTEMPTED;
        if ( $this->noOp ) {
            $status = StatusValue::newGood(); // no-op
        } else {
            $status = $this->doAttempt();
            if ( !$status->isOK() ) {
                $this->failed = true;
                $this->logFailure( 'attempt' );
            }
        }
 
        return $status;
    }
 
    protected function doAttempt() {
        return StatusValue::newGood();
    }
 
    final public function attemptAsync() {
        $this->async = true;
        $result = $this->attempt();
        $this->async = false;
 
        return $result;
    }
 
    final public function attemptQuick() {
        $this->state = self::STATE_CHECKED; // bypassed
 
        return $this->attempt();
    }
 
    final public function attemptAsyncQuick() {
        $this->state = self::STATE_CHECKED; // bypassed
 
        return $this->attemptAsync();
    }
 
    protected function allowedParams() {
        return [ [], [], [] ];
    }
 
    protected function setFlags( array $params ) {
        return [ 'async' => $this->async ] + $params;
    }
 
    public function storagePathsRead() {
        return [];
    }
 
    public function storagePathsChanged() {
        return [];
    }
 
    final public function storagePathsReadOrChanged() {
        return array_values( array_unique(
            array_merge( $this->storagePathsRead(), $this->storagePathsChanged() )
        ) );
    }
 
    protected function precheckDestExistence(
        FileStatePredicates $opPredicates,
        $sourceSize,
        $sourceSha1
    ) {
        $status = StatusValue::newGood();
        // Record the existence of destination file
        $this->destExists = $this->resolveFileExistence( $this->params['dst'], $opPredicates );
        // Check if an incompatible file exists at the destination
        $this->overwriteSameCase = false;
        if ( $this->destExists ) {
            if ( $this->getParam( 'overwrite' ) ) {
                return $status; // OK, no conflict
            } elseif ( $this->getParam( 'overwriteSame' ) ) {
                // Operation does nothing other than return an OK or bad status
                $sourceSize = ( $sourceSize instanceof Closure ) ? $sourceSize() : $sourceSize;
                $sourceSha1 = ( $sourceSha1 instanceof Closure ) ? $sourceSha1() : $sourceSha1;
                $dstSha1 = $this->resolveFileSha1Base36( $this->params['dst'], $opPredicates );
                $dstSize = $this->resolveFileSize( $this->params['dst'], $opPredicates );
                // Check if hashes are valid and match each other...
                if ( !strlen( $sourceSha1 ) || !strlen( $dstSha1 ) ) {
                    $status->fatal( 'backend-fail-hashes' );
                } elseif ( !is_int( $sourceSize ) || !is_int( $dstSize ) ) {
                    $status->fatal( 'backend-fail-sizes' );
                } elseif ( $sourceSha1 !== $dstSha1 || $sourceSize !== $dstSize ) {
                    // Give an error if the files are not identical
                    $status->fatal( 'backend-fail-notsame', $this->params['dst'] );
                } else {
                    $this->overwriteSameCase = true; // OK
                }
            } else {
                $status->fatal( 'backend-fail-alreadyexists', $this->params['dst'] );
            }
        } elseif ( $this->destExists === FileBackend::EXISTENCE_ERROR ) {
            $status->fatal( 'backend-fail-stat', $this->params['dst'] );
        }
 
        return $status;
    }
 
    final protected function resolveFileExistence( $source, FileStatePredicates $opPredicates ) {
        return $opPredicates->resolveFileExistence(
            $source,
            function ( $path ) {
                return $this->backend->fileExists( [ 'src' => $path, 'latest' => true ] );
            }
        );
    }
 
    final protected function resolveFileSize( $source, FileStatePredicates $opPredicates ) {
        return $opPredicates->resolveFileSize(
            $source,
            function ( $path ) {
                return $this->backend->getFileSize( [ 'src' => $path, 'latest' => true ] );
            }
        );
    }
 
    final protected function resolveFileSha1Base36( $source, FileStatePredicates $opPredicates ) {
        return $opPredicates->resolveFileSha1Base36(
            $source,
            function ( $path ) {
                return $this->backend->getFileSha1Base36( [ 'src' => $path, 'latest' => true ] );
            }
        );
    }
 
    public function getBackend() {
        return $this->backend;
    }
 
    final public function logFailure( $action ) {
        $params = $this->params;
        $params['failedAction'] = $action;
        try {
            $this->logger->error( static::class .
                " failed: " . FormatJson::encode( $params ) );
        } catch ( TimeoutException $e ) {
            throw $e;
        } catch ( Exception $e ) {
            // bad config? debug log error?
        }
    }
}