FileOp.php

Go to the documentation of this file.

<?php
use Psr\Log\LoggerInterface;

abstract class FileOp {
    protected $params = [];

    protected $backend;
    protected $logger;

    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, LoggerInterface $logger
    ) {
        $this->backend = $backend;
        $this->logger = $logger;
        list( $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 setBatchId( $batchId ) {
        $this->batchId = $batchId;
    }

    final public function getParam( $name ) {
        return $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 = [];
        foreach ( $this->storagePathsReadOrChanged() 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 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->doOperation ) {
            $status = $this->doAttempt();
            if ( !$status->isOK() ) {
                $this->failed = true;
                $this->logFailure( 'attempt' );
            }
        } else { // no-op
            $status = StatusValue::newGood();
        }

        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();
        // 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;
            }
        } elseif ( $this->destExists === FileBackend::EXISTENCE_ERROR ) {
            $status->fatal( 'backend-fail-stat', $this->params['dst'] );
        }

        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 {
            $this->logger->error( static::class .
                " failed (batch #{$this->batchId}): " . FormatJson::encode( $params ) );
        } catch ( Exception $e ) {
            // bad config? debug log error?
        }
    }
}