FileOp.php

Go to the documentation of this file.

<?php
use Psr\Log\LoggerInterface;
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 $cancelled = false;
 
    protected $sourceSize;
    protected $sourceSha1;
 
    protected $overwriteSameCase;
 
    protected $destExists;
 
    /* Object life-cycle */
    private const STATE_NEW = 1;
    private const STATE_CHECKED = 2;
    private const STATE_ATTEMPTED = 3;
 
    protected const ASSUMED_SHA1 = 'sha1';
    protected const ASSUMED_EXISTS = 'exists';
    protected const ASSUMED_SIZE = 'size';
 
    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 newPredicates() {
        return [ self::ASSUMED_EXISTS => [], self::ASSUMED_SHA1 => [], self::ASSUMED_SIZE => [] ];
    }
 
    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( array &$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;
        }
 
        $status = $this->doPrecheck( $predicates );
        if ( !$status->isOK() ) {
            $this->failed = true;
        }
 
        return $status;
    }
 
    protected function doPrecheck( array &$predicates ) {
        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->cancelled ) {
            $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( array $predicates ) {
        $status = StatusValue::newGood();
        // Record the size of source file/string
        $this->sourceSize = $this->getSourceSize(); // FS file or data string
        // file in storage?
        $this->sourceSize ??= $this->fileSize( $this->params['src'], $predicates );
        // Record the hash of source file/string
        $this->sourceSha1 = $this->getSourceSha1Base36(); // FS file or data string
        // file in storage?
        $this->sourceSha1 ??= $this->fileSha1( $this->params['src'], $predicates );
        // Record the existence of destination file
        $this->destExists = $this->fileExists( $this->params['dst'], $predicates );
        // 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
                $dhash = $this->fileSha1( $this->params['dst'], $predicates );
                $dsize = $this->fileSize( $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 ( !is_int( $this->sourceSize ) || !is_int( $dsize ) ) {
                    $status->fatal( 'backend-fail-sizes' );
                } elseif ( $this->sourceSha1 !== $dhash || $this->sourceSize !== $dsize ) {
                    // 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;
    }
 
    protected function getSourceSize() {
        return null; // N/A
    }
 
    protected function getSourceSha1Base36() {
        return null; // N/A
    }
 
    final protected function fileExists( $source, array $predicates ) {
        if ( isset( $predicates[self::ASSUMED_EXISTS][$source] ) ) {
            return $predicates[self::ASSUMED_EXISTS][$source]; // previous op assures this
        } else {
            $params = [ 'src' => $source, 'latest' => true ];
 
            return $this->backend->fileExists( $params );
        }
    }
 
    final protected function fileSize( $source, array $predicates ) {
        if ( isset( $predicates[self::ASSUMED_SIZE][$source] ) ) {
            return $predicates[self::ASSUMED_SIZE][$source]; // previous op assures this
        } elseif (
            isset( $predicates[self::ASSUMED_EXISTS][$source] ) &&
            !$predicates[self::ASSUMED_EXISTS][$source]
        ) {
            return false; // previous op assures this
        } else {
            $params = [ 'src' => $source, 'latest' => true ];
 
            return $this->backend->getFileSize( $params );
        }
    }
 
    final protected function fileSha1( $source, array $predicates ) {
        if ( isset( $predicates[self::ASSUMED_SHA1][$source] ) ) {
            return $predicates[self::ASSUMED_SHA1][$source]; // previous op assures this
        } elseif (
            isset( $predicates[self::ASSUMED_EXISTS][$source] ) &&
            !$predicates[self::ASSUMED_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 {
            $this->logger->error( static::class .
                " failed: " . FormatJson::encode( $params ) );
        } catch ( TimeoutException $e ) {
            throw $e;
        } catch ( Exception $e ) {
            // bad config? debug log error?
        }
    }
}