FileRepo.php

Go to the documentation of this file.

<?php
use MediaWiki\Context\RequestContext;
use MediaWiki\Linker\LinkTarget;
use MediaWiki\MainConfigNames;
use MediaWiki\MediaWikiServices;
use MediaWiki\Page\PageIdentity;
use MediaWiki\Permissions\Authority;
use MediaWiki\Status\Status;
use MediaWiki\Title\Title;
use MediaWiki\User\UserIdentity;
use MediaWiki\Utils\MWTimestamp;
use Wikimedia\AtEase\AtEase;
use Wikimedia\FileBackend\FileBackend;
 
class FileRepo {
    public const DELETE_SOURCE = 1;
    public const OVERWRITE = 2;
    public const OVERWRITE_SAME = 4;
    public const SKIP_LOCKING = 8;
 
    public const NAME_AND_TIME_ONLY = 1;
 
    public $fetchDescription;
 
    public $descriptionCacheExpiry;
 
    protected $hasSha1Storage = false;
 
    protected $supportsSha1URLs = false;
 
    protected $backend;
 
    protected $zones = [];
 
    protected $thumbScriptUrl;
 
    protected $transformVia404;
 
    protected $descBaseUrl;
 
    protected $scriptDirUrl;
 
    protected $articleUrl;
 
    protected $initialCapital;
 
    protected $pathDisclosureProtection = 'simple';
 
    protected $url;
 
    protected $thumbUrl;
 
    protected $hashLevels;
 
    protected $deletedHashLevels;
 
    protected $abbrvThreshold;
 
    protected $favicon = null;
 
    protected $isPrivate;
 
    protected $fileFactory = [ UnregisteredLocalFile::class, 'newFromTitle' ];
    protected $oldFileFactory = false;
    protected $fileFactoryKey = false;
    protected $oldFileFactoryKey = false;
 
    protected $thumbProxyUrl;
    protected $thumbProxySecret;
 
    protected $disableLocalTransform = false;
 
    protected $wanCache;
 
    public $name;
 
    public function __construct( array $info = null ) {
        // Verify required settings presence
        if (
            $info === null
            || !array_key_exists( 'name', $info )
            || !array_key_exists( 'backend', $info )
        ) {
            throw new InvalidArgumentException( __CLASS__ .
                " requires an array of options having both 'name' and 'backend' keys.\n" );
        }
 
        // Required settings
        $this->name = $info['name'];
        if ( $info['backend'] instanceof FileBackend ) {
            $this->backend = $info['backend']; // useful for testing
        } else {
            $this->backend =
                MediaWikiServices::getInstance()->getFileBackendGroup()->get( $info['backend'] );
        }
 
        // Optional settings that can have no value
        $optionalSettings = [
            'descBaseUrl', 'scriptDirUrl', 'articleUrl', 'fetchDescription',
            'thumbScriptUrl', 'pathDisclosureProtection', 'descriptionCacheExpiry',
            'favicon', 'thumbProxyUrl', 'thumbProxySecret', 'disableLocalTransform'
        ];
        foreach ( $optionalSettings as $var ) {
            if ( isset( $info[$var] ) ) {
                $this->$var = $info[$var];
            }
        }
 
        // Optional settings that have a default
        $localCapitalLinks =
            MediaWikiServices::getInstance()->getNamespaceInfo()->isCapitalized( NS_FILE );
        $this->initialCapital = $info['initialCapital'] ?? $localCapitalLinks;
        if ( $localCapitalLinks && !$this->initialCapital ) {
            // If the local wiki's file namespace requires an initial capital, but a foreign file
            // repo doesn't, complications will result. Linker code will want to auto-capitalize the
            // first letter of links to files, but those links might actually point to files on
            // foreign wikis with initial-lowercase names. This combination is not likely to be
            // used by anyone anyway, so we just outlaw it to save ourselves the bugs. If you want
            // to include a foreign file repo with initialCapital false, set your local file
            // namespace to not be capitalized either.
            throw new InvalidArgumentException(
                'File repos with initial capital false are not allowed on wikis where the File ' .
                'namespace has initial capital true' );
        }
 
        $this->url = $info['url'] ?? false; // a subclass may set the URL (e.g. ForeignAPIRepo)
        $defaultThumbUrl = $this->url ? $this->url . '/thumb' : false;
        $this->thumbUrl = $info['thumbUrl'] ?? $defaultThumbUrl;
        $this->hashLevels = $info['hashLevels'] ?? 2;
        $this->deletedHashLevels = $info['deletedHashLevels'] ?? $this->hashLevels;
        $this->transformVia404 = !empty( $info['transformVia404'] );
        $this->abbrvThreshold = $info['abbrvThreshold'] ?? 255;
        $this->isPrivate = !empty( $info['isPrivate'] );
        // Give defaults for the basic zones...
        $this->zones = $info['zones'] ?? [];
        foreach ( [ 'public', 'thumb', 'transcoded', 'temp', 'deleted' ] as $zone ) {
            if ( !isset( $this->zones[$zone]['container'] ) ) {
                $this->zones[$zone]['container'] = "{$this->name}-{$zone}";
            }
            if ( !isset( $this->zones[$zone]['directory'] ) ) {
                $this->zones[$zone]['directory'] = '';
            }
            if ( !isset( $this->zones[$zone]['urlsByExt'] ) ) {
                $this->zones[$zone]['urlsByExt'] = [];
            }
        }
 
        $this->supportsSha1URLs = !empty( $info['supportsSha1URLs'] );
 
        $this->wanCache = $info['wanCache'] ?? WANObjectCache::newEmpty();
    }
 
    public function getBackend() {
        return $this->backend;
    }
 
    public function getReadOnlyReason() {
        return $this->backend->getReadOnlyReason();
    }
 
    protected function initZones( $doZones = [] ): void {
        foreach ( (array)$doZones as $zone ) {
            $root = $this->getZonePath( $zone );
            if ( $root === null ) {
                throw new RuntimeException( "No '$zone' zone defined in the {$this->name} repo." );
            }
        }
    }
 
    public static function isVirtualUrl( $url ) {
        return str_starts_with( $url, 'mwrepo://' );
    }
 
    public function getVirtualUrl( $suffix = false ) {
        $path = 'mwrepo://' . $this->name;
        if ( $suffix !== false ) {
            $path .= '/' . rawurlencode( $suffix );
        }
 
        return $path;
    }
 
    public function getZoneUrl( $zone, $ext = null ) {
        if ( in_array( $zone, [ 'public', 'thumb', 'transcoded' ] ) ) {
            // standard public zones
            if ( $ext !== null && isset( $this->zones[$zone]['urlsByExt'][$ext] ) ) {
                // custom URL for extension/zone
                // @phan-suppress-next-line PhanTypeArraySuspiciousNullable
                return $this->zones[$zone]['urlsByExt'][$ext];
            } elseif ( isset( $this->zones[$zone]['url'] ) ) {
                // custom URL for zone
                return $this->zones[$zone]['url'];
            }
        }
        switch ( $zone ) {
            case 'public':
                return $this->url;
            case 'temp':
            case 'deleted':
                return false; // no public URL
            case 'thumb':
                return $this->thumbUrl;
            case 'transcoded':
                return "{$this->url}/transcoded";
            default:
                return false;
        }
    }
 
    public function backendSupportsUnicodePaths() {
        return (bool)( $this->getBackend()->getFeatures() & FileBackend::ATTR_UNICODE_PATHS );
    }
 
    public function resolveVirtualUrl( $url ) {
        if ( !str_starts_with( $url, 'mwrepo://' ) ) {
            throw new InvalidArgumentException( __METHOD__ . ': unknown protocol' );
        }
        $bits = explode( '/', substr( $url, 9 ), 3 );
        if ( count( $bits ) != 3 ) {
            throw new InvalidArgumentException( __METHOD__ . ": invalid mwrepo URL: $url" );
        }
        [ $repo, $zone, $rel ] = $bits;
        if ( $repo !== $this->name ) {
            throw new InvalidArgumentException( __METHOD__ . ": fetching from a foreign repo is not supported" );
        }
        $base = $this->getZonePath( $zone );
        if ( !$base ) {
            throw new InvalidArgumentException( __METHOD__ . ": invalid zone: $zone" );
        }
 
        return $base . '/' . rawurldecode( $rel );
    }
 
    protected function getZoneLocation( $zone ) {
        if ( !isset( $this->zones[$zone] ) ) {
            return [ null, null ]; // bogus
        }
 
        return [ $this->zones[$zone]['container'], $this->zones[$zone]['directory'] ];
    }
 
    public function getZonePath( $zone ) {
        [ $container, $base ] = $this->getZoneLocation( $zone );
        if ( $container === null || $base === null ) {
            return null;
        }
        $backendName = $this->backend->getName();
        if ( $base != '' ) { // may not be set
            $base = "/{$base}";
        }
 
        return "mwstore://$backendName/{$container}{$base}";
    }
 
    public function newFile( $title, $time = false ) {
        $title = File::normalizeTitle( $title );
        if ( !$title ) {
            return null;
        }
        if ( $time ) {
            if ( $this->oldFileFactory ) {
                return call_user_func( $this->oldFileFactory, $title, $this, $time );
            } else {
                return null;
            }
        } else {
            return call_user_func( $this->fileFactory, $title, $this );
        }
    }
 
    public function findFile( $title, $options = [] ) {
        if ( !empty( $options['private'] ) && !( $options['private'] instanceof Authority ) ) {
            throw new InvalidArgumentException(
                __METHOD__ . ' called with the `private` option set to something ' .
                'other than an Authority object'
            );
        }
 
        $title = File::normalizeTitle( $title );
        if ( !$title ) {
            return false;
        }
        if ( isset( $options['bypassCache'] ) ) {
            $options['latest'] = $options['bypassCache']; // b/c
        }
        $time = $options['time'] ?? false;
        $flags = !empty( $options['latest'] ) ? IDBAccessObject::READ_LATEST : 0;
        # First try the current version of the file to see if it precedes the timestamp
        $img = $this->newFile( $title );
        if ( !$img ) {
            return false;
        }
        $img->load( $flags );
        if ( $img->exists() && ( !$time || $img->getTimestamp() == $time ) ) {
            return $img;
        }
        # Now try an old version of the file
        if ( $time !== false ) {
            $img = $this->newFile( $title, $time );
            if ( $img ) {
                $img->load( $flags );
                if ( $img->exists() ) {
                    if ( !$img->isDeleted( File::DELETED_FILE ) ) {
                        return $img; // always OK
                    } elseif (
                        // If its not empty, its an Authority object
                        !empty( $options['private'] ) &&
                        $img->userCan( File::DELETED_FILE, $options['private'] )
                    ) {
                        return $img;
                    }
                }
            }
        }
 
        # Now try redirects
        if ( !empty( $options['ignoreRedirect'] ) ) {
            return false;
        }
        $redir = $this->checkRedirect( $title );
        if ( $redir && $title->getNamespace() === NS_FILE ) {
            $img = $this->newFile( $redir );
            if ( !$img ) {
                return false;
            }
            $img->load( $flags );
            if ( $img->exists() ) {
                $img->redirectedFrom( $title->getDBkey() );
 
                return $img;
            }
        }
 
        return false;
    }
 
    public function findFiles( array $items, $flags = 0 ) {
        $result = [];
        foreach ( $items as $item ) {
            if ( is_array( $item ) ) {
                $title = $item['title'];
                $options = $item;
                unset( $options['title'] );
 
                if (
                    !empty( $options['private'] ) &&
                    !( $options['private'] instanceof Authority )
                ) {
                    $options['private'] = RequestContext::getMain()->getAuthority();
                }
            } else {
                $title = $item;
                $options = [];
            }
            $file = $this->findFile( $title, $options );
            if ( $file ) {
                $searchName = File::normalizeTitle( $title )->getDBkey(); // must be valid
                if ( $flags & self::NAME_AND_TIME_ONLY ) {
                    $result[$searchName] = [
                        'title' => $file->getTitle()->getDBkey(),
                        'timestamp' => $file->getTimestamp()
                    ];
                } else {
                    $result[$searchName] = $file;
                }
            }
        }
 
        return $result;
    }
 
    public function findFileFromKey( $sha1, $options = [] ) {
        if ( !empty( $options['private'] ) && !( $options['private'] instanceof Authority ) ) {
            throw new InvalidArgumentException(
                __METHOD__ . ' called with the `private` option set to something ' .
                'other than an Authority object'
            );
        }
 
        $time = $options['time'] ?? false;
        # First try to find a matching current version of a file...
        if ( !$this->fileFactoryKey ) {
            return false; // find-by-sha1 not supported
        }
        $img = call_user_func( $this->fileFactoryKey, $sha1, $this, $time );
        if ( $img && $img->exists() ) {
            return $img;
        }
        # Now try to find a matching old version of a file...
        if ( $time !== false && $this->oldFileFactoryKey ) { // find-by-sha1 supported?
            $img = call_user_func( $this->oldFileFactoryKey, $sha1, $this, $time );
            if ( $img && $img->exists() ) {
                if ( !$img->isDeleted( File::DELETED_FILE ) ) {
                    return $img; // always OK
                } elseif (
                    // If its not empty, its an Authority object
                    !empty( $options['private'] ) &&
                    $img->userCan( File::DELETED_FILE, $options['private'] )
                ) {
                    return $img;
                }
            }
        }
 
        return false;
    }
 
    public function findBySha1( $hash ) {
        return [];
    }
 
    public function findBySha1s( array $hashes ) {
        $result = [];
        foreach ( $hashes as $hash ) {
            $files = $this->findBySha1( $hash );
            if ( count( $files ) ) {
                $result[$hash] = $files;
            }
        }
 
        return $result;
    }
 
    public function findFilesByPrefix( $prefix, $limit ) {
        return [];
    }
 
    public function getThumbScriptUrl() {
        return $this->thumbScriptUrl;
    }
 
    public function getThumbProxyUrl() {
        return $this->thumbProxyUrl;
    }
 
    public function getThumbProxySecret() {
        return $this->thumbProxySecret;
    }
 
    public function canTransformVia404() {
        return $this->transformVia404;
    }
 
    public function canTransformLocally() {
        return !$this->disableLocalTransform;
    }
 
    public function getNameFromTitle( $title ) {
        if (
            $this->initialCapital !=
            MediaWikiServices::getInstance()->getNamespaceInfo()->isCapitalized( NS_FILE )
        ) {
            $name = $title->getDBkey();
            if ( $this->initialCapital ) {
                $name = MediaWikiServices::getInstance()->getContentLanguage()->ucfirst( $name );
            }
        } else {
            $name = $title->getDBkey();
        }
 
        return $name;
    }
 
    public function getRootDirectory() {
        return $this->getZonePath( 'public' );
    }
 
    public function getHashPath( $name ) {
        return self::getHashPathForLevel( $name, $this->hashLevels );
    }
 
    public function getTempHashPath( $suffix ) {
        $parts = explode( '!', $suffix, 2 ); // format is <timestamp>!<name> or just <name>
        $name = $parts[1] ?? $suffix; // hash path is not based on timestamp
        return self::getHashPathForLevel( $name, $this->hashLevels );
    }
 
    protected static function getHashPathForLevel( $name, $levels ) {
        if ( $levels == 0 ) {
            return '';
        } else {
            $hash = md5( $name );
            $path = '';
            for ( $i = 1; $i <= $levels; $i++ ) {
                $path .= substr( $hash, 0, $i ) . '/';
            }
 
            return $path;
        }
    }
 
    public function getHashLevels() {
        return $this->hashLevels;
    }
 
    public function getName() {
        return $this->name;
    }
 
    public function makeUrl( $query = '', $entry = 'index' ) {
        if ( isset( $this->scriptDirUrl ) ) {
            return wfAppendQuery( "{$this->scriptDirUrl}/{$entry}.php", $query );
        }
 
        return false;
    }
 
    public function getDescriptionUrl( $name ) {
        $encName = wfUrlencode( $name );
        if ( $this->descBaseUrl !== null ) {
            # "http://example.com/wiki/File:"
            return $this->descBaseUrl . $encName;
        }
        if ( $this->articleUrl !== null ) {
            # "http://example.com/wiki/$1"
            # We use "Image:" as the canonical namespace for
            # compatibility across all MediaWiki versions.
            return str_replace( '$1',
                "Image:$encName", $this->articleUrl );
        }
        if ( $this->scriptDirUrl !== null ) {
            # "http://example.com/w"
            # We use "Image:" as the canonical namespace for
            # compatibility across all MediaWiki versions,
            # and just sort of hope index.php is right. ;)
            return $this->makeUrl( "title=Image:$encName" );
        }
 
        return false;
    }
 
    public function getDescriptionRenderUrl( $name, $lang = null ) {
        $query = 'action=render';
        if ( $lang !== null ) {
            $query .= '&uselang=' . urlencode( $lang );
        }
        if ( isset( $this->scriptDirUrl ) ) {
            return $this->makeUrl(
                'title=' .
                wfUrlencode( 'Image:' . $name ) .
                "&$query" );
        } else {
            $descUrl = $this->getDescriptionUrl( $name );
            if ( $descUrl ) {
                return wfAppendQuery( $descUrl, $query );
            } else {
                return false;
            }
        }
    }
 
    public function getDescriptionStylesheetUrl() {
        if ( isset( $this->scriptDirUrl ) ) {
            // Must match canonical query parameter order for optimum caching
            // See HTMLCacheUpdater::getUrls
            return $this->makeUrl( 'title=MediaWiki:Filepage.css&action=raw&ctype=text/css' );
        }
 
        return false;
    }
 
    public function store( $srcPath, $dstZone, $dstRel, $flags = 0 ) {
        $this->assertWritableRepo(); // fail out if read-only
 
        $status = $this->storeBatch( [ [ $srcPath, $dstZone, $dstRel ] ], $flags );
        if ( $status->successCount == 0 ) {
            $status->setOK( false );
        }
 
        return $status;
    }
 
    public function storeBatch( array $triplets, $flags = 0 ) {
        $this->assertWritableRepo(); // fail out if read-only
 
        if ( $flags & self::DELETE_SOURCE ) {
            throw new InvalidArgumentException( "DELETE_SOURCE not supported in " . __METHOD__ );
        }
 
        $status = $this->newGood();
        $backend = $this->backend; // convenience
 
        $operations = [];
        // Validate each triplet and get the store operation...
        foreach ( $triplets as [ $src, $dstZone, $dstRel ] ) {
            $srcPath = ( $src instanceof FSFile ) ? $src->getPath() : $src;
            wfDebug( __METHOD__
                . "( \$src='$srcPath', \$dstZone='$dstZone', \$dstRel='$dstRel' )"
            );
            // Resolve source path
            if ( $src instanceof FSFile ) {
                $op = 'store';
            } else {
                $src = $this->resolveToStoragePathIfVirtual( $src );
                $op = FileBackend::isStoragePath( $src ) ? 'copy' : 'store';
            }
            // Resolve destination path
            $root = $this->getZonePath( $dstZone );
            if ( !$root ) {
                throw new RuntimeException( "Invalid zone: $dstZone" );
            }
            if ( !$this->validateFilename( $dstRel ) ) {
                throw new RuntimeException( 'Validation error in $dstRel' );
            }
            $dstPath = "$root/$dstRel";
            $dstDir = dirname( $dstPath );
            // Create destination directories for this triplet
            if ( !$this->initDirectory( $dstDir )->isOK() ) {
                return $this->newFatal( 'directorycreateerror', $dstDir );
            }
 
            // Copy the source file to the destination
            $operations[] = [
                'op' => $op,
                'src' => $src, // storage path (copy) or local file path (store)
                'dst' => $dstPath,
                'overwrite' => (bool)( $flags & self::OVERWRITE ),
                'overwriteSame' => (bool)( $flags & self::OVERWRITE_SAME ),
            ];
        }
 
        // Execute the store operation for each triplet
        $opts = [ 'force' => true ];
        if ( $flags & self::SKIP_LOCKING ) {
            $opts['nonLocking'] = true;
        }
 
        return $status->merge( $backend->doOperations( $operations, $opts ) );
    }
 
    public function cleanupBatch( array $files, $flags = 0 ) {
        $this->assertWritableRepo(); // fail out if read-only
 
        $status = $this->newGood();
 
        $operations = [];
        foreach ( $files as $path ) {
            if ( is_array( $path ) ) {
                // This is a pair, extract it
                [ $zone, $rel ] = $path;
                $path = $this->getZonePath( $zone ) . "/$rel";
            } else {
                // Resolve source to a storage path if virtual
                $path = $this->resolveToStoragePathIfVirtual( $path );
            }
            $operations[] = [ 'op' => 'delete', 'src' => $path ];
        }
        // Actually delete files from storage...
        $opts = [ 'force' => true ];
        if ( $flags & self::SKIP_LOCKING ) {
            $opts['nonLocking'] = true;
        }
 
        return $status->merge( $this->backend->doOperations( $operations, $opts ) );
    }
 
    final public function quickImport( $src, $dst, $options = null ) {
        return $this->quickImportBatch( [ [ $src, $dst, $options ] ] );
    }
 
    public function quickImportBatch( array $triples ) {
        $status = $this->newGood();
        $operations = [];
        foreach ( $triples as $triple ) {
            [ $src, $dst ] = $triple;
            if ( $src instanceof FSFile ) {
                $op = 'store';
            } else {
                $src = $this->resolveToStoragePathIfVirtual( $src );
                $op = FileBackend::isStoragePath( $src ) ? 'copy' : 'store';
            }
            $dst = $this->resolveToStoragePathIfVirtual( $dst );
 
            if ( !isset( $triple[2] ) ) {
                $headers = [];
            } elseif ( is_string( $triple[2] ) ) {
                // back-compat
                $headers = [ 'Content-Disposition' => $triple[2] ];
            } elseif ( is_array( $triple[2] ) && isset( $triple[2]['headers'] ) ) {
                $headers = $triple[2]['headers'];
            } else {
                $headers = [];
            }
 
            $operations[] = [
                'op' => $op,
                'src' => $src, // storage path (copy) or local path/FSFile (store)
                'dst' => $dst,
                'headers' => $headers
            ];
            $status->merge( $this->initDirectory( dirname( $dst ) ) );
        }
 
        return $status->merge( $this->backend->doQuickOperations( $operations ) );
    }
 
    final public function quickPurge( $path ) {
        return $this->quickPurgeBatch( [ $path ] );
    }
 
    public function quickCleanDir( $dir ) {
        return $this->newGood()->merge(
            $this->backend->clean(
                [ 'dir' => $this->resolveToStoragePathIfVirtual( $dir ) ]
            )
        );
    }
 
    public function quickPurgeBatch( array $paths ) {
        $status = $this->newGood();
        $operations = [];
        foreach ( $paths as $path ) {
            $operations[] = [
                'op' => 'delete',
                'src' => $this->resolveToStoragePathIfVirtual( $path ),
                'ignoreMissingSource' => true
            ];
        }
        $status->merge( $this->backend->doQuickOperations( $operations ) );
 
        return $status;
    }
 
    public function storeTemp( $originalName, $srcPath ) {
        $this->assertWritableRepo(); // fail out if read-only
 
        $date = MWTimestamp::getInstance()->format( 'YmdHis' );
        $hashPath = $this->getHashPath( $originalName );
        $dstUrlRel = $hashPath . $date . '!' . rawurlencode( $originalName );
        $virtualUrl = $this->getVirtualUrl( 'temp' ) . '/' . $dstUrlRel;
 
        $result = $this->quickImport( $srcPath, $virtualUrl );
        $result->value = $virtualUrl;
 
        return $result;
    }
 
    public function freeTemp( $virtualUrl ) {
        $this->assertWritableRepo(); // fail out if read-only
 
        $temp = $this->getVirtualUrl( 'temp' );
        if ( !str_starts_with( $virtualUrl, $temp ) ) {
            wfDebug( __METHOD__ . ": Invalid temp virtual URL" );
 
            return false;
        }
 
        return $this->quickPurge( $virtualUrl )->isOK();
    }
 
    public function concatenate( array $srcPaths, $dstPath, $flags = 0 ) {
        $this->assertWritableRepo(); // fail out if read-only
 
        $status = $this->newGood();
 
        $sources = [];
        foreach ( $srcPaths as $srcPath ) {
            // Resolve source to a storage path if virtual
            $source = $this->resolveToStoragePathIfVirtual( $srcPath );
            $sources[] = $source; // chunk to merge
        }
 
        // Concatenate the chunks into one FS file
        $params = [ 'srcs' => $sources, 'dst' => $dstPath ];
        $status->merge( $this->backend->concatenate( $params ) );
        if ( !$status->isOK() ) {
            return $status;
        }
 
        // Delete the sources if required
        if ( $flags & self::DELETE_SOURCE ) {
            $status->merge( $this->quickPurgeBatch( $srcPaths ) );
        }
 
        // Make sure status is OK, despite any quickPurgeBatch() fatals
        $status->setResult( true );
 
        return $status;
    }
 
    public function publish(
        $src, $dstRel, $archiveRel, $flags = 0, array $options = []
    ) {
        $this->assertWritableRepo(); // fail out if read-only
 
        $status = $this->publishBatch(
            [ [ $src, $dstRel, $archiveRel, $options ] ], $flags );
        if ( $status->successCount == 0 ) {
            $status->setOK( false );
        }
        $status->value = $status->value[0] ?? false;
 
        return $status;
    }
 
    public function publishBatch( array $ntuples, $flags = 0 ) {
        $this->assertWritableRepo(); // fail out if read-only
 
        $backend = $this->backend; // convenience
        // Try creating directories
        $this->initZones( 'public' );
 
        $status = $this->newGood( [] );
 
        $operations = [];
        $sourceFSFilesToDelete = []; // cleanup for disk source files
        // Validate each triplet and get the store operation...
        foreach ( $ntuples as $ntuple ) {
            [ $src, $dstRel, $archiveRel ] = $ntuple;
            $srcPath = ( $src instanceof FSFile ) ? $src->getPath() : $src;
 
            $options = $ntuple[3] ?? [];
            // Resolve source to a storage path if virtual
            $srcPath = $this->resolveToStoragePathIfVirtual( $srcPath );
            if ( !$this->validateFilename( $dstRel ) ) {
                throw new RuntimeException( 'Validation error in $dstRel' );
            }
            if ( !$this->validateFilename( $archiveRel ) ) {
                throw new RuntimeException( 'Validation error in $archiveRel' );
            }
 
            $publicRoot = $this->getZonePath( 'public' );
            $dstPath = "$publicRoot/$dstRel";
            $archivePath = "$publicRoot/$archiveRel";
 
            $dstDir = dirname( $dstPath );
            $archiveDir = dirname( $archivePath );
            // Abort immediately on directory creation errors since they're likely to be repetitive
            if ( !$this->initDirectory( $dstDir )->isOK() ) {
                return $this->newFatal( 'directorycreateerror', $dstDir );
            }
            if ( !$this->initDirectory( $archiveDir )->isOK() ) {
                return $this->newFatal( 'directorycreateerror', $archiveDir );
            }
 
            // Set any desired headers to be use in GET/HEAD responses
            $headers = $options['headers'] ?? [];
 
            // Archive destination file if it exists.
            // This will check if the archive file also exists and fail if does.
            // This is a check to avoid data loss. On Windows and Linux,
            // copy() will overwrite, so the existence check is vulnerable to
            // race conditions unless a functioning LockManager is used.
            // LocalFile also uses SELECT FOR UPDATE for synchronization.
            $operations[] = [
                'op' => 'copy',
                'src' => $dstPath,
                'dst' => $archivePath,
                'ignoreMissingSource' => true
            ];
 
            // Copy (or move) the source file to the destination
            if ( FileBackend::isStoragePath( $srcPath ) ) {
                $operations[] = [
                    'op' => ( $flags & self::DELETE_SOURCE ) ? 'move' : 'copy',
                    'src' => $srcPath,
                    'dst' => $dstPath,
                    'overwrite' => true, // replace current
                    'headers' => $headers
                ];
            } else {
                $operations[] = [
                    'op' => 'store',
                    'src' => $src, // storage path (copy) or local path/FSFile (store)
                    'dst' => $dstPath,
                    'overwrite' => true, // replace current
                    'headers' => $headers
                ];
                if ( $flags & self::DELETE_SOURCE ) {
                    $sourceFSFilesToDelete[] = $srcPath;
                }
            }
        }
 
        // Execute the operations for each triplet
        $status->merge( $backend->doOperations( $operations ) );
        // Find out which files were archived...
        foreach ( $ntuples as $i => $ntuple ) {
            [ , , $archiveRel ] = $ntuple;
            $archivePath = $this->getZonePath( 'public' ) . "/$archiveRel";
            if ( $this->fileExists( $archivePath ) ) {
                $status->value[$i] = 'archived';
            } else {
                $status->value[$i] = 'new';
            }
        }
        // Cleanup for disk source files...
        foreach ( $sourceFSFilesToDelete as $file ) {
            AtEase::suppressWarnings();
            unlink( $file ); // FS cleanup
            AtEase::restoreWarnings();
        }
 
        return $status;
    }
 
    protected function initDirectory( $dir ) {
        $path = $this->resolveToStoragePathIfVirtual( $dir );
        [ , $container, ] = FileBackend::splitStoragePath( $path );
 
        $params = [ 'dir' => $path ];
        if ( $this->isPrivate
            || $container === $this->zones['deleted']['container']
            || $container === $this->zones['temp']['container']
        ) {
            # Take all available measures to prevent web accessibility of new deleted
            # directories, in case the user has not configured offline storage
            $params = [ 'noAccess' => true, 'noListing' => true ] + $params;
        }
 
        return $this->newGood()->merge( $this->backend->prepare( $params ) );
    }
 
    public function cleanDir( $dir ) {
        $this->assertWritableRepo(); // fail out if read-only
 
        return $this->newGood()->merge(
            $this->backend->clean(
                [ 'dir' => $this->resolveToStoragePathIfVirtual( $dir ) ]
            )
        );
    }
 
    public function fileExists( $file ) {
        $result = $this->fileExistsBatch( [ $file ] );
 
        return $result[0];
    }
 
    public function fileExistsBatch( array $files ) {
        $paths = array_map( [ $this, 'resolveToStoragePathIfVirtual' ], $files );
        $this->backend->preloadFileStat( [ 'srcs' => $paths ] );
 
        $result = [];
        foreach ( $paths as $key => $path ) {
            $result[$key] = $this->backend->fileExists( [ 'src' => $path ] );
        }
 
        return $result;
    }
 
    public function delete( $srcRel, $archiveRel ) {
        $this->assertWritableRepo(); // fail out if read-only
 
        return $this->deleteBatch( [ [ $srcRel, $archiveRel ] ] );
    }
 
    public function deleteBatch( array $sourceDestPairs ) {
        $this->assertWritableRepo(); // fail out if read-only
 
        // Try creating directories
        $this->initZones( [ 'public', 'deleted' ] );
 
        $status = $this->newGood();
 
        $backend = $this->backend; // convenience
        $operations = [];
        // Validate filenames and create archive directories
        foreach ( $sourceDestPairs as [ $srcRel, $archiveRel ] ) {
            if ( !$this->validateFilename( $srcRel ) ) {
                throw new RuntimeException( __METHOD__ . ':Validation error in $srcRel' );
            } elseif ( !$this->validateFilename( $archiveRel ) ) {
                throw new RuntimeException( __METHOD__ . ':Validation error in $archiveRel' );
            }
 
            $publicRoot = $this->getZonePath( 'public' );
            $srcPath = "{$publicRoot}/$srcRel";
 
            $deletedRoot = $this->getZonePath( 'deleted' );
            $archivePath = "{$deletedRoot}/{$archiveRel}";
            $archiveDir = dirname( $archivePath ); // does not touch FS
 
            // Create destination directories
            if ( !$this->initDirectory( $archiveDir )->isGood() ) {
                return $this->newFatal( 'directorycreateerror', $archiveDir );
            }
 
            $operations[] = [
                'op' => 'move',
                'src' => $srcPath,
                'dst' => $archivePath,
                // We may have 2+ identical files being deleted,
                // all of which will map to the same destination file
                'overwriteSame' => true // also see T33792
            ];
        }
 
        // Move the files by execute the operations for each pair.
        // We're now committed to returning an OK result, which will
        // lead to the files being moved in the DB also.
        $opts = [ 'force' => true ];
        return $status->merge( $backend->doOperations( $operations, $opts ) );
    }
 
    public function cleanupDeletedBatch( array $storageKeys ) {
        $this->assertWritableRepo();
    }
 
    public function getDeletedHashPath( $key ) {
        if ( strlen( $key ) < 31 ) {
            throw new InvalidArgumentException( "Invalid storage key '$key'." );
        }
        $path = '';
        for ( $i = 0; $i < $this->deletedHashLevels; $i++ ) {
            $path .= $key[$i] . '/';
        }
 
        return $path;
    }
 
    protected function resolveToStoragePathIfVirtual( $path ) {
        if ( self::isVirtualUrl( $path ) ) {
            return $this->resolveVirtualUrl( $path );
        }
 
        return $path;
    }
 
    public function getLocalCopy( $virtualUrl ) {
        $path = $this->resolveToStoragePathIfVirtual( $virtualUrl );
 
        return $this->backend->getLocalCopy( [ 'src' => $path ] );
    }
 
    public function getLocalReference( $virtualUrl ) {
        $path = $this->resolveToStoragePathIfVirtual( $virtualUrl );
 
        return $this->backend->getLocalReference( [ 'src' => $path ] );
    }
 
    public function getFileProps( $virtualUrl ) {
        $fsFile = $this->getLocalReference( $virtualUrl );
        $mwProps = new MWFileProps( MediaWikiServices::getInstance()->getMimeAnalyzer() );
        if ( $fsFile ) {
            $props = $mwProps->getPropsFromPath( $fsFile->getPath(), true );
        } else {
            $props = $mwProps->newPlaceholderProps();
        }
 
        return $props;
    }
 
    public function getFileTimestamp( $virtualUrl ) {
        $path = $this->resolveToStoragePathIfVirtual( $virtualUrl );
 
        return $this->backend->getFileTimestamp( [ 'src' => $path ] );
    }
 
    public function getFileSize( $virtualUrl ) {
        $path = $this->resolveToStoragePathIfVirtual( $virtualUrl );
 
        return $this->backend->getFileSize( [ 'src' => $path ] );
    }
 
    public function getFileSha1( $virtualUrl ) {
        $path = $this->resolveToStoragePathIfVirtual( $virtualUrl );
 
        return $this->backend->getFileSha1Base36( [ 'src' => $path ] );
    }
 
    public function streamFileWithStatus( $virtualUrl, $headers = [], $optHeaders = [] ) {
        $path = $this->resolveToStoragePathIfVirtual( $virtualUrl );
        $params = [ 'src' => $path, 'headers' => $headers, 'options' => $optHeaders ];
 
        // T172851: HHVM does not flush the output properly, causing OOM
        ob_start( null, 1_048_576 );
        ob_implicit_flush( true );
 
        $status = $this->newGood()->merge( $this->backend->streamFile( $params ) );
 
        // T186565: Close the buffer, unless it has already been closed
        // in HTTPFileStreamer::resetOutputBuffers().
        if ( ob_get_status() ) {
            ob_end_flush();
        }
 
        return $status;
    }
 
    public function enumFiles( $callback ) {
        $this->enumFilesInStorage( $callback );
    }
 
    protected function enumFilesInStorage( $callback ) {
        $publicRoot = $this->getZonePath( 'public' );
        $numDirs = 1 << ( $this->hashLevels * 4 );
        // Use a priori assumptions about directory structure
        // to reduce the tree height of the scanning process.
        for ( $flatIndex = 0; $flatIndex < $numDirs; $flatIndex++ ) {
            $hexString = sprintf( "%0{$this->hashLevels}x", $flatIndex );
            $path = $publicRoot;
            for ( $hexPos = 0; $hexPos < $this->hashLevels; $hexPos++ ) {
                $path .= '/' . substr( $hexString, 0, $hexPos + 1 );
            }
            $iterator = $this->backend->getFileList( [ 'dir' => $path ] );
            if ( $iterator === null ) {
                throw new RuntimeException( __METHOD__ . ': could not get file listing for ' . $path );
            }
            foreach ( $iterator as $name ) {
                // Each item returned is a public file
                call_user_func( $callback, "{$path}/{$name}" );
            }
        }
    }
 
    public function validateFilename( $filename ) {
        if ( strval( $filename ) == '' ) {
            return false;
        }
 
        return FileBackend::isPathTraversalFree( $filename );
    }
 
    private function getErrorCleanupFunction() {
        switch ( $this->pathDisclosureProtection ) {
            case 'none':
            case 'simple': // b/c
                $callback = [ $this, 'passThrough' ];
                break;
            default: // 'paranoid'
                $callback = [ $this, 'paranoidClean' ];
        }
        return $callback;
    }
 
    public function paranoidClean( $param ) {
        return '[hidden]';
    }
 
    public function passThrough( $param ) {
        return $param;
    }
 
    public function newFatal( $message, ...$parameters ) {
        $status = Status::newFatal( $message, ...$parameters );
        $status->cleanCallback = $this->getErrorCleanupFunction();
 
        return $status;
    }
 
    public function newGood( $value = null ) {
        $status = Status::newGood( $value );
        $status->cleanCallback = $this->getErrorCleanupFunction();
 
        return $status;
    }
 
    public function checkRedirect( $title ) {
        return false;
    }
 
    public function invalidateImageRedirect( $title ) {
    }
 
    public function getDisplayName() {
        $sitename = MediaWikiServices::getInstance()->getMainConfig()->get( MainConfigNames::Sitename );
 
        if ( $this->isLocal() ) {
            return $sitename;
        }
 
        // 'shared-repo-name-wikimediacommons' is used when $wgUseInstantCommons = true
        return wfMessageFallback( 'shared-repo-name-' . $this->name, 'shared-repo' )->text();
    }
 
    public function nameForThumb( $name ) {
        if ( strlen( $name ) > $this->abbrvThreshold ) {
            $ext = FileBackend::extensionFromPath( $name );
            $name = ( $ext == '' ) ? 'thumbnail' : "thumbnail.$ext";
        }
 
        return $name;
    }
 
    public function isLocal() {
        return $this->getName() == 'local';
    }
 
    public function getSharedCacheKey( $kClassSuffix, ...$components ) {
        return false;
    }
 
    public function getLocalCacheKey( $kClassSuffix, ...$components ) {
        return $this->wanCache->makeKey(
            'filerepo-' . $kClassSuffix,
            $this->getName(),
            ...$components
        );
    }
 
    public function getTempRepo() {
        return new TempFileRepo( [
            'name' => "{$this->name}-temp",
            'backend' => $this->backend,
            'zones' => [
                'public' => [
                    // Same place storeTemp() uses in the base repo, though
                    // the path hashing is mismatched, which is annoying.
                    'container' => $this->zones['temp']['container'],
                    'directory' => $this->zones['temp']['directory']
                ],
                'thumb' => [
                    'container' => $this->zones['temp']['container'],
                    'directory' => $this->zones['temp']['directory'] == ''
                        ? 'thumb'
                        : $this->zones['temp']['directory'] . '/thumb'
                ],
                'transcoded' => [
                    'container' => $this->zones['temp']['container'],
                    'directory' => $this->zones['temp']['directory'] == ''
                        ? 'transcoded'
                        : $this->zones['temp']['directory'] . '/transcoded'
                ]
            ],
            'hashLevels' => $this->hashLevels, // performance
            'isPrivate' => true // all in temp zone
        ] );
    }
 
    public function getUploadStash( UserIdentity $user = null ) {
        return new UploadStash( $this, $user );
    }
 
    protected function assertWritableRepo() {
    }
 
    public function getInfo() {
        $ret = [
            'name' => $this->getName(),
            'displayname' => $this->getDisplayName(),
            'rootUrl' => $this->getZoneUrl( 'public' ),
            'local' => $this->isLocal(),
        ];
 
        $optionalSettings = [
            'url',
            'thumbUrl',
            'initialCapital',
            'descBaseUrl',
            'scriptDirUrl',
            'articleUrl',
            'fetchDescription',
            'descriptionCacheExpiry',
        ];
        foreach ( $optionalSettings as $k ) {
            if ( isset( $this->$k ) ) {
                $ret[$k] = $this->$k;
            }
        }
        if ( isset( $this->favicon ) ) {
            // Expand any local path to full URL to improve API usability (T77093).
            $ret['favicon'] = MediaWikiServices::getInstance()->getUrlUtils()
                ->expand( $this->favicon );
        }
 
        return $ret;
    }
 
    public function hasSha1Storage() {
        return $this->hasSha1Storage;
    }
 
    public function supportsSha1URLs() {
        return $this->supportsSha1URLs;
    }
}