9 * Base class for all file backend classes (including multi-write backends).
10 * This class defines the methods as abstract that subclasses must implement.
11 * Outside callers can assume that all backends will have these functions.
13 * All "storage paths" are of the format "mwstore://backend/container/path".
14 * The paths use UNIX file system (FS) notation, though any particular backend may
15 * not actually be using a local filesystem. Therefore, the paths are only virtual.
17 * Backend contents are stored under wiki-specific container names by default.
18 * For legacy reasons, this has no effect for the FS backend class, and per-wiki
19 * segregation must be done by setting the container paths appropriately.
21 * FS-based backends are somewhat more restrictive due to the existence of real
22 * directory files; a regular file cannot have the same name as a directory. Other
23 * backends with virtual directories may not have this limitation. Callers should
24 * store files in such a way that no files and directories are under the same path.
26 * Methods should avoid throwing exceptions at all costs.
27 * As a corollary, external dependencies should be kept to a minimum.
29 * @ingroup FileBackend
32 abstract class FileBackendBase
{
33 protected $name; // unique backend name
34 protected $wikiId; // unique wiki name
35 protected $readOnly; // string
36 /** @var LockManager */
37 protected $lockManager;
40 * Create a new backend instance from configuration.
41 * This should only be called from within FileBackendGroup.
44 * 'name' : The unique name of this backend.
45 * 'wikiId' : Prefix to container names that is unique to this wiki.
46 * This should consist of alphanumberic, '-', and '_' chars.
47 * 'lockManager' : Registered name of a file lock manager to use.
48 * 'readOnly' : Write operations are disallowed if this is a non-empty string.
49 * It should be an explanation for the backend being read-only.
51 * @param $config Array
53 public function __construct( array $config ) {
54 $this->name
= $config['name'];
55 $this->wikiId
= isset( $config['wikiId'] )
57 : wfWikiID(); // e.g. "my_wiki-en_"
58 $this->wikiId
= $this->resolveWikiId( $this->wikiId
);
59 $this->lockManager
= LockManagerGroup
::singleton()->get( $config['lockManager'] );
60 $this->readOnly
= isset( $config['readOnly'] )
61 ?
(string)$config['readOnly']
66 * Normalize a wiki ID by replacing characters that are
67 * not supported by the backend as part of container names.
69 * @param $wikiId string
72 protected function resolveWikiId( $wikiId ) {
77 * Get the unique backend name.
79 * We may have multiple different backends of the same type.
80 * For example, we can have two Swift backends using different proxies.
84 final public function getName() {
89 * This is the main entry point into the backend for write operations.
90 * Callers supply an ordered list of operations to perform as a transaction.
91 * If any serious errors occur, all attempted operations will be rolled back.
93 * $ops is an array of arrays. The outer array holds a list of operations.
94 * Each inner array is a set of key value pairs that specify an operation.
96 * Supported operations and their parameters:
97 * a) Create a new file in storage with the contents of a string
100 * 'dst' => <storage path>,
101 * 'content' => <string of new file contents>,
102 * 'overwriteDest' => <boolean>,
103 * 'overwriteSame' => <boolean>
105 * b) Copy a file system file into storage
108 * 'src' => <file system path>,
109 * 'dst' => <storage path>,
110 * 'overwriteDest' => <boolean>,
111 * 'overwriteSame' => <boolean>
113 * c) Copy a file within storage
116 * 'src' => <storage path>,
117 * 'dst' => <storage path>,
118 * 'overwriteDest' => <boolean>,
119 * 'overwriteSame' => <boolean>
121 * d) Move a file within storage
124 * 'src' => <storage path>,
125 * 'dst' => <storage path>,
126 * 'overwriteDest' => <boolean>,
127 * 'overwriteSame' => <boolean>
129 * e) Delete a file within storage
132 * 'src' => <storage path>,
133 * 'ignoreMissingSource' => <boolean>
135 * f) Concatenate a list of files within storage into a single temp file
137 * 'op' => 'concatenate',
138 * 'srcs' => <ordered array of storage paths>,
139 * 'dst' => <file system path to 0-byte temp file>
141 * g) Do nothing (no-op)
146 * Boolean flags for operations (operation-specific):
147 * 'ignoreMissingSource' : The operation will simply succeed and do
148 * nothing if the source file does not exist.
149 * 'overwriteDest' : Any destination file will be overwritten.
150 * 'overwriteSame' : An error will not be given if a file already
151 * exists at the destination that has the same
152 * contents as the new contents to be written there.
154 * $opts is an associative of boolean flags, including:
155 * 'ignoreErrors' : Errors that would normally cause a rollback do not.
156 * The remaining operations are still attempted if any fail.
157 * 'nonLocking' : No locks are acquired for the operations.
158 * This can increase performance for non-critical writes.
159 * This has no effect unless the 'ignoreErrors' flag is set.
160 * 'allowStale' : Don't require the latest available data.
161 * This can increase performance for non-critical writes.
162 * This has no effect unless the 'ignoreErrors' flag is set.
165 * This returns a Status, which contains all warnings and fatals that occured
166 * during the operation. The 'failCount', 'successCount', and 'success' members
167 * will reflect each operation attempted. The status will be "OK" unless any
168 * of the operations failed and the 'ignoreErrors' parameter was not set.
170 * @param $ops Array List of operations to execute in order
171 * @param $opts Array Batch operation options
174 final public function doOperations( array $ops, array $opts = array() ) {
175 if ( $this->readOnly
!= '' ) {
176 return Status
::newFatal( 'backend-fail-readonly', $this->name
, $this->readOnly
);
178 if ( empty( $opts['ignoreErrors'] ) ) { // sanity
179 unset( $opts['nonLocking'] );
180 unset( $opts['allowStale'] );
182 return $this->doOperationsInternal( $ops, $opts );
186 * @see FileBackendBase::doOperations()
188 abstract protected function doOperationsInternal( array $ops, array $opts );
191 * Same as doOperations() except it takes a single operation.
192 * If you are doing a batch of operations that should either
193 * all succeed or all fail, then use that function instead.
195 * @see FileBackendBase::doOperations()
197 * @param $op Array Operation
198 * @param $opts Array Operation options
201 final public function doOperation( array $op, array $opts = array() ) {
202 return $this->doOperations( array( $op ), $opts );
206 * Performs a single store operation.
207 * This sets $params['op'] to 'store' and passes it to doOperation().
209 * @see FileBackendBase::doOperation()
211 * @param $params Array Operation parameters
212 * @param $opts Array Operation options
215 final public function store( array $params, array $opts = array() ) {
216 $params['op'] = 'store';
217 return $this->doOperation( $params, $opts );
221 * Performs a single copy operation.
222 * This sets $params['op'] to 'copy' and passes it to doOperation().
224 * @see FileBackendBase::doOperation()
226 * @param $params Array Operation parameters
227 * @param $opts Array Operation options
230 final public function copy( array $params, array $opts = array() ) {
231 $params['op'] = 'copy';
232 return $this->doOperation( $params, $opts );
236 * Performs a single move operation.
237 * This sets $params['op'] to 'move' and passes it to doOperation().
239 * @see FileBackendBase::doOperation()
241 * @param $params Array Operation parameters
242 * @param $opts Array Operation options
245 final public function move( array $params, array $opts = array() ) {
246 $params['op'] = 'move';
247 return $this->doOperation( $params, $opts );
251 * Performs a single delete operation.
252 * This sets $params['op'] to 'delete' and passes it to doOperation().
254 * @see FileBackendBase::doOperation()
256 * @param $params Array Operation parameters
257 * @param $opts Array Operation options
260 final public function delete( array $params, array $opts = array() ) {
261 $params['op'] = 'delete';
262 return $this->doOperation( $params, $opts );
266 * Performs a single create operation.
267 * This sets $params['op'] to 'create' and passes it to doOperation().
269 * @see FileBackendBase::doOperation()
271 * @param $params Array Operation parameters
272 * @param $opts Array Operation options
275 final public function create( array $params, array $opts = array() ) {
276 $params['op'] = 'create';
277 return $this->doOperation( $params, $opts );
281 * Performs a single concatenate operation.
282 * This sets $params['op'] to 'concatenate' and passes it to doOperation().
284 * @see FileBackendBase::doOperation()
286 * @param $params Array Operation parameters
287 * @param $opts Array Operation options
290 final public function concatenate( array $params, array $opts = array() ) {
291 $params['op'] = 'concatenate';
292 return $this->doOperation( $params, $opts );
296 * Prepare a storage path for usage. This will create containers
297 * that don't yet exist or, on FS backends, create parent directories.
300 * dir : storage directory
302 * @param $params Array
305 abstract public function prepare( array $params );
308 * Take measures to block web access to a directory and
309 * the container it belongs to. FS backends might add .htaccess
310 * files wheras backends like Swift this might restrict container
311 * access to backend user that represents end-users in web request.
312 * This is not guaranteed to actually do anything.
315 * dir : storage directory
316 * noAccess : try to deny file access
317 * noListing : try to deny file listing
319 * @param $params Array
322 abstract public function secure( array $params );
325 * Clean up an empty storage directory.
326 * On FS backends, the directory will be deleted. Others may do nothing.
329 * dir : storage directory
331 * @param $params Array
334 abstract public function clean( array $params );
337 * Check if a file exists at a storage path in the backend.
338 * This returns false if only a directory exists at the path.
341 * src : source storage path
342 * latest : use the latest available data
344 * @param $params Array
345 * @return bool|null Returns null on failure
347 abstract public function fileExists( array $params );
350 * Get the last-modified timestamp of the file at a storage path.
353 * src : source storage path
354 * latest : use the latest available data
356 * @param $params Array
357 * @return string|false TS_MW timestamp or false on failure
359 abstract public function getFileTimestamp( array $params );
362 * Get the contents of a file at a storage path in the backend.
363 * This should be avoided for potentially large files.
366 * src : source storage path
367 * latest : use the latest available data
369 * @param $params Array
370 * @return string|false Returns false on failure
372 abstract public function getFileContents( array $params );
375 * Get a SHA-1 hash of the file at a storage path in the backend.
378 * src : source storage path
379 * latest : use the latest available data
381 * @param $params Array
382 * @return string|false Hash string or false on failure
384 abstract public function getFileSha1Base36( array $params );
387 * Get the properties of the file at a storage path in the backend.
388 * Returns FSFile::placeholderProps() on failure.
391 * src : source storage path
392 * latest : use the latest available data
394 * @param $params Array
397 abstract public function getFileProps( array $params );
400 * Stream the file at a storage path in the backend.
401 * Appropriate HTTP headers (Status, Content-Type, Content-Length)
402 * must be sent if streaming began, while none should be sent otherwise.
403 * Implementations should flush the output buffer before sending data.
406 * src : source storage path
407 * headers : additional HTTP headers to send on success
408 * latest : use the latest available data
410 * @param $params Array
413 abstract public function streamFile( array $params );
416 * Returns a file system file, identical to the file at a storage path.
417 * The file returned is either:
418 * a) A local copy of the file at a storage path in the backend.
419 * The temporary copy will have the same extension as the source.
420 * b) An original of the file at a storage path in the backend.
421 * Temporary files may be purged when the file object falls out of scope.
423 * Write operations should *never* be done on this file as some backends
424 * may do internal tracking or may be instances of FileBackendMultiWrite.
425 * In that later case, there are copies of the file that must stay in sync.
428 * src : source storage path
429 * latest : use the latest available data
431 * @param $params Array
432 * @return FSFile|null Returns null on failure
434 abstract public function getLocalReference( array $params );
437 * Get a local copy on disk of the file at a storage path in the backend.
438 * The temporary copy will have the same file extension as the source.
439 * Temporary files may be purged when the file object falls out of scope.
442 * src : source storage path
443 * latest : use the latest available data
445 * @param $params Array
446 * @return TempFSFile|null Returns null on failure
448 abstract public function getLocalCopy( array $params );
451 * Get an iterator to list out all stored files under a storage directory.
452 * If the directory is of the form "mwstore://container", then all items in
453 * the container should be listed. If of the form "mwstore://container/dir",
454 * then all items under that container directory should be listed.
455 * Results should be storage paths relative to the given directory.
458 * dir : storage path directory
460 * @return Traversable|Array|null Returns null on failure
462 abstract public function getFileList( array $params );
465 * Lock the files at the given storage paths in the backend.
466 * This will either lock all the files or none (on failure).
468 * Callers should consider using getScopedFileLocks() instead.
470 * @param $paths Array Storage paths
471 * @param $type integer LockManager::LOCK_* constant
474 final public function lockFiles( array $paths, $type ) {
475 return $this->lockManager
->lock( $paths, $type );
479 * Unlock the files at the given storage paths in the backend.
481 * @param $paths Array Storage paths
482 * @param $type integer LockManager::LOCK_* constant
485 final public function unlockFiles( array $paths, $type ) {
486 return $this->lockManager
->unlock( $paths, $type );
490 * Lock the files at the given storage paths in the backend.
491 * This will either lock all the files or none (on failure).
492 * On failure, the status object will be updated with errors.
494 * Once the return value goes out scope, the locks will be released and
495 * the status updated. Unlock fatals will not change the status "OK" value.
497 * @param $paths Array Storage paths
498 * @param $type integer LockManager::LOCK_* constant
499 * @param $status Status Status to update on lock/unlock
500 * @return ScopedLock|null Returns null on failure
502 final public function getScopedFileLocks( array $paths, $type, Status
$status ) {
503 return ScopedLock
::factory( $this->lockManager
, $paths, $type, $status );
508 * Base class for all single-write backends.
509 * This class defines the methods as abstract that subclasses must implement.
510 * Callers outside of FileBackend and its helper classes, such as FileOp,
511 * should only call functions that are present in FileBackendBase.
513 * The FileBackendBase operations are implemented using primitive functions
514 * such as storeInternal(), copyInternal(), deleteInternal() and the like.
515 * This class is also responsible for path resolution and sanitization.
517 * @ingroup FileBackend
520 abstract class FileBackend
extends FileBackendBase
{
522 protected $cache = array(); // (storage path => key => value)
523 protected $maxCacheSize = 75; // integer; max paths with entries
525 protected $shardViaHashLevels = array(); // (container name => integer)
528 * Create a file in the backend with the given contents.
529 * Do not call this function from places outside FileBackend and FileOp.
532 * content : the raw file contents
533 * dst : destination storage path
534 * overwriteDest : overwrite any file that exists at the destination
536 * @param $params Array
539 final public function createInternal( array $params ) {
540 $status = $this->doCreateInternal( $params );
541 $this->clearCache( array( $params['dst'] ) );
546 * @see FileBackend::createInternal()
548 abstract protected function doCreateInternal( array $params );
551 * Store a file into the backend from a file on disk.
552 * Do not call this function from places outside FileBackend and FileOp.
555 * src : source path on disk
556 * dst : destination storage path
557 * overwriteDest : overwrite any file that exists at the destination
559 * @param $params Array
562 final public function storeInternal( array $params ) {
563 $status = $this->doStoreInternal( $params );
564 $this->clearCache( array( $params['dst'] ) );
569 * @see FileBackend::storeInternal()
571 abstract protected function doStoreInternal( array $params );
574 * Copy a file from one storage path to another in the backend.
575 * Do not call this function from places outside FileBackend and FileOp.
578 * src : source storage path
579 * dst : destination storage path
580 * overwriteDest : overwrite any file that exists at the destination
582 * @param $params Array
585 final public function copyInternal( array $params ) {
586 $status = $this->doCopyInternal( $params );
587 $this->clearCache( array( $params['dst'] ) );
592 * @see FileBackend::copyInternal()
594 abstract protected function doCopyInternal( array $params );
597 * Delete a file at the storage path.
598 * Do not call this function from places outside FileBackend and FileOp.
601 * src : source storage path
602 * ignoreMissingSource : do nothing if the source file does not exist
604 * @param $params Array
607 final public function deleteInternal( array $params ) {
608 $status = $this->doDeleteInternal( $params );
609 $this->clearCache( array( $params['src'] ) );
614 * @see FileBackend::deleteInternal()
616 abstract protected function doDeleteInternal( array $params );
619 * Move a file from one storage path to another in the backend.
620 * Do not call this function from places outside FileBackend and FileOp.
623 * src : source storage path
624 * dst : destination storage path
625 * overwriteDest : overwrite any file that exists at the destination
627 * @param $params Array
630 final public function moveInternal( array $params ) {
631 $status = $this->doMoveInternal( $params );
632 $this->clearCache( array( $params['src'], $params['dst'] ) );
637 * @see FileBackend::moveInternal()
639 protected function doMoveInternal( array $params ) {
640 // Copy source to dest
641 $status = $this->copyInternal( $params );
642 if ( !$status->isOK() ) {
645 // Delete source (only fails due to races or medium going down)
646 $status->merge( $this->deleteInternal( array( 'src' => $params['src'] ) ) );
647 $status->setResult( true, $status->value
); // ignore delete() errors
652 * Combines files from several storage paths into a new file in the backend.
653 * Do not call this function from places outside FileBackend and FileOp.
655 * srcs : ordered source storage paths (e.g. chunk1, chunk2, ...)
656 * dst : file system path to 0-byte temp file
658 * @param $params Array
661 final public function concatenateInternal( array $params ) {
662 $status = $this->doConcatenateInternal( $params );
667 * @see FileBackend::concatenateInternal()
669 protected function doConcatenateInternal( array $params ) {
670 $status = Status
::newGood();
671 $tmpPath = $params['dst']; // convenience
673 // Check that the specified temp file is valid...
674 wfSuppressWarnings();
675 $ok = ( is_file( $tmpPath ) && !filesize( $tmpPath ) );
677 if ( !$ok ) { // not present or not empty
678 $status->fatal( 'backend-fail-opentemp', $tmpPath );
682 // Build up the temp file using the source chunks (in order)...
683 $tmpHandle = fopen( $tmpPath, 'a' );
684 if ( $tmpHandle === false ) {
685 $status->fatal( 'backend-fail-opentemp', $tmpPath );
688 foreach ( $params['srcs'] as $virtualSource ) {
689 // Get a local FS version of the chunk
690 $tmpFile = $this->getLocalReference( array( 'src' => $virtualSource ) );
692 $status->fatal( 'backend-fail-read', $virtualSource );
695 // Get a handle to the local FS version
696 $sourceHandle = fopen( $tmpFile->getPath(), 'r' );
697 if ( $sourceHandle === false ) {
698 fclose( $tmpHandle );
699 $status->fatal( 'backend-fail-read', $virtualSource );
702 // Append chunk to file (pass chunk size to avoid magic quotes)
703 if ( !stream_copy_to_stream( $sourceHandle, $tmpHandle ) ) {
704 fclose( $sourceHandle );
705 fclose( $tmpHandle );
706 $status->fatal( 'backend-fail-writetemp', $tmpPath );
709 fclose( $sourceHandle );
711 if ( !fclose( $tmpHandle ) ) {
712 $status->fatal( 'backend-fail-closetemp', $tmpPath );
720 * @see FileBackendBase::prepare()
722 final public function prepare( array $params ) {
723 $status = Status
::newGood();
724 list( $fullCont, $dir, $shard ) = $this->resolveStoragePath( $params['dir'] );
725 if ( $dir === null ) {
726 $status->fatal( 'backend-fail-invalidpath', $params['dir'] );
727 return $status; // invalid storage path
729 if ( $shard !== null ) { // confined to a single container/shard
730 $status->merge( $this->doPrepare( $fullCont, $dir, $params ) );
731 } else { // directory is on several shards
732 wfDebug( __METHOD__
. ": iterating over all container shards.\n" );
733 list( $b, $shortCont, $r ) = self
::splitStoragePath( $params['dir'] );
734 foreach ( $this->getContainerSuffixes( $shortCont ) as $suffix ) {
735 $status->merge( $this->doPrepare( "{$fullCont}{$suffix}", $dir, $params ) );
742 * @see FileBackend::prepare()
744 protected function doPrepare( $container, $dir, array $params ) {
745 return Status
::newGood();
749 * @see FileBackendBase::secure()
751 final public function secure( array $params ) {
752 $status = Status
::newGood();
753 list( $fullCont, $dir, $shard ) = $this->resolveStoragePath( $params['dir'] );
754 if ( $dir === null ) {
755 $status->fatal( 'backend-fail-invalidpath', $params['dir'] );
756 return $status; // invalid storage path
758 if ( $shard !== null ) { // confined to a single container/shard
759 $status->merge( $this->doSecure( $fullCont, $dir, $params ) );
760 } else { // directory is on several shards
761 wfDebug( __METHOD__
. ": iterating over all container shards.\n" );
762 list( $b, $shortCont, $r ) = self
::splitStoragePath( $params['dir'] );
763 foreach ( $this->getContainerSuffixes( $shortCont ) as $suffix ) {
764 $status->merge( $this->doSecure( "{$fullCont}{$suffix}", $dir, $params ) );
771 * @see FileBackend::secure()
773 protected function doSecure( $container, $dir, array $params ) {
774 return Status
::newGood();
778 * @see FileBackendBase::clean()
780 final public function clean( array $params ) {
781 $status = Status
::newGood();
782 list( $fullCont, $dir, $shard ) = $this->resolveStoragePath( $params['dir'] );
783 if ( $dir === null ) {
784 $status->fatal( 'backend-fail-invalidpath', $params['dir'] );
785 return $status; // invalid storage path
787 if ( $shard !== null ) { // confined to a single container/shard
788 $status->merge( $this->doClean( $fullCont, $dir, $params ) );
789 } else { // directory is on several shards
790 wfDebug( __METHOD__
. ": iterating over all container shards.\n" );
791 list( $b, $shortCont, $r ) = self
::splitStoragePath( $params['dir'] );
792 foreach ( $this->getContainerSuffixes( $shortCont ) as $suffix ) {
793 $status->merge( $this->doClean( "{$fullCont}{$suffix}", $dir, $params ) );
800 * @see FileBackend::clean()
802 protected function doClean( $container, $dir, array $params ) {
803 return Status
::newGood();
807 * @see FileBackendBase::fileExists()
809 final public function fileExists( array $params ) {
810 $path = $params['src'];
811 if ( isset( $this->cache
[$path]['exists'] ) ) {
812 return $this->cache
[$path]['exists'];
814 $exists = $this->doFileExists( $params );
815 if ( $exists ) { // don't cache negatives
816 $this->trimCache(); // limit memory
817 $this->cache
[$path]['exists'] = $exists;
823 * @see FileBackend::fileExists()
825 abstract protected function doFileExists( array $params );
828 * @see FileBackendBase::getFileTimestamp()
830 final public function getFileTimestamp( array $params ) {
831 $path = $params['src'];
832 if ( isset( $this->cache
[$path]['timestamp'] ) ) {
833 return $this->cache
[$path]['timestamp'];
835 $timestamp = $this->doGetFileTimestamp( $params );
836 if ( $timestamp ) { // don't cache negatives
837 $this->trimCache(); // limit memory
838 $this->cache
[$path]['timestamp'] = $timestamp;
844 * @see FileBackend::getFileTimestamp()
846 abstract protected function doGetFileTimestamp( array $params );
849 * @see FileBackendBase::getFileContents()
851 public function getFileContents( array $params ) {
852 $tmpFile = $this->getLocalReference( $params );
856 wfSuppressWarnings();
857 $data = file_get_contents( $tmpFile->getPath() );
863 * @see FileBackendBase::getFileSha1Base36()
865 public function getFileSha1Base36( array $params ) {
866 $path = $params['src'];
867 if ( isset( $this->cache
[$path]['sha1'] ) ) {
868 return $this->cache
[$path]['sha1'];
870 $hash = $this->doGetFileSha1Base36( $params );
871 if ( $hash ) { // don't cache negatives
872 $this->trimCache(); // limit memory
873 $this->cache
[$path]['sha1'] = $hash;
879 * @see FileBackend::getFileSha1Base36()
881 protected function doGetFileSha1Base36( array $params ) {
882 $fsFile = $this->getLocalReference( $params );
886 return $fsFile->getSha1Base36();
891 * @see FileBackendBase::getFileProps()
893 public function getFileProps( array $params ) {
894 $fsFile = $this->getLocalReference( $params );
896 return FSFile
::placeholderProps();
898 return $fsFile->getProps();
903 * @see FileBackendBase::getLocalReference()
905 public function getLocalReference( array $params ) {
906 $path = $params['src'];
907 if ( isset( $this->cache
[$path]['localRef'] ) ) {
908 return $this->cache
[$path]['localRef'];
910 $tmpFile = $this->getLocalCopy( $params );
911 if ( $tmpFile ) { // don't cache negatives
912 $this->trimCache(); // limit memory
913 $this->cache
[$path]['localRef'] = $tmpFile;
919 * @see FileBackendBase::streamFile()
921 public function streamFile( array $params ) {
922 $status = Status
::newGood();
924 $fsFile = $this->getLocalReference( $params );
926 $status->fatal( 'backend-fail-stream', $params['src'] );
930 $extraHeaders = isset( $params['headers'] )
934 $ok = StreamFile
::stream( $fsFile->getPath(), $extraHeaders, false );
936 $status->fatal( 'backend-fail-stream', $params['src'] );
944 * @see FileBackendBase::getFileList()
946 final public function getFileList( array $params ) {
947 list( $fullCont, $dir, $shard ) = $this->resolveStoragePath( $params['dir'] );
948 if ( $dir === null ) { // invalid storage path
951 if ( $shard !== null ) {
952 // File listing is confined to a single container/shard
953 return $this->getFileListInternal( $fullCont, $dir, $params );
955 wfDebug( __METHOD__
. ": iterating over all container shards.\n" );
956 // File listing spans multiple containers/shards
957 list( $b, $shortCont, $r ) = self
::splitStoragePath( $params['dir'] );
958 return new ContainerShardListIterator( $this,
959 $fullCont, $this->getContainerSuffixes( $shortCont ), $params );
964 * Do not call this function from places outside FileBackend and ContainerFileListIterator
966 * @param $container string Resolved container name
967 * @param $dir string Resolved path relative to container
968 * @param $params Array
969 * @see FileBackend::getFileList()
971 abstract public function getFileListInternal( $container, $dir, array $params );
974 * Get the list of supported operations and their corresponding FileOp classes.
978 protected function supportedOperations() {
980 'store' => 'StoreFileOp',
981 'copy' => 'CopyFileOp',
982 'move' => 'MoveFileOp',
983 'delete' => 'DeleteFileOp',
984 'concatenate' => 'ConcatenateFileOp',
985 'create' => 'CreateFileOp',
986 'null' => 'NullFileOp'
991 * Return a list of FileOp objects from a list of operations.
992 * Do not call this function from places outside FileBackend.
994 * The result must have the same number of items as the input.
995 * An exception is thrown if an unsupported operation is requested.
997 * @param $ops Array Same format as doOperations()
998 * @return Array List of FileOp objects
999 * @throws MWException
1001 final public function getOperations( array $ops ) {
1002 $supportedOps = $this->supportedOperations();
1004 $performOps = array(); // array of FileOp objects
1005 // Build up ordered array of FileOps...
1006 foreach ( $ops as $operation ) {
1007 $opName = $operation['op'];
1008 if ( isset( $supportedOps[$opName] ) ) {
1009 $class = $supportedOps[$opName];
1010 // Get params for this operation
1011 $params = $operation;
1012 // Append the FileOp class
1013 $performOps[] = new $class( $this, $params );
1015 throw new MWException( "Operation `$opName` is not supported." );
1023 * @see FileBackendBase::doOperationsInternal()
1025 protected function doOperationsInternal( array $ops, array $opts ) {
1026 $status = Status
::newGood();
1028 // Build up a list of FileOps...
1029 $performOps = $this->getOperations( $ops );
1031 // Acquire any locks as needed...
1032 if ( empty( $opts['nonLocking'] ) ) {
1033 // Build up a list of files to lock...
1034 $filesLockEx = $filesLockSh = array();
1035 foreach ( $performOps as $fileOp ) {
1036 $filesLockSh = array_merge( $filesLockSh, $fileOp->storagePathsRead() );
1037 $filesLockEx = array_merge( $filesLockEx, $fileOp->storagePathsChanged() );
1039 // Optimization: if doing an EX lock anyway, don't also set an SH one
1040 $filesLockSh = array_diff( $filesLockSh, $filesLockEx );
1041 // Try to lock those files for the scope of this function...
1042 $scopeLockS = $this->getScopedFileLocks( $filesLockSh, LockManager
::LOCK_UW
, $status );
1043 $scopeLockE = $this->getScopedFileLocks( $filesLockEx, LockManager
::LOCK_EX
, $status );
1044 if ( !$status->isOK() ) {
1045 return $status; // abort
1049 // Clear any cache entries (after locks acquired)
1050 $this->clearCache();
1051 // Actually attempt the operation batch...
1052 $status->merge( FileOp
::attemptBatch( $performOps, $opts ) );
1058 * Invalidate the file existence and property cache
1060 * @param $paths Array Clear cache for specific files
1063 final public function clearCache( array $paths = null ) {
1064 if ( $paths === null ) {
1065 $this->cache
= array();
1067 foreach ( $paths as $path ) {
1068 unset( $this->cache
[$path] );
1074 * Prune the cache if it is too big to add an item
1078 protected function trimCache() {
1079 if ( count( $this->cache
) >= $this->maxCacheSize
) {
1080 reset( $this->cache
);
1081 $key = key( $this->cache
);
1082 unset( $this->cache
[$key] );
1087 * Check if a given path is a mwstore:// path.
1088 * This does not do any actual validation or existence checks.
1090 * @param $path string
1093 final public static function isStoragePath( $path ) {
1094 return ( strpos( $path, 'mwstore://' ) === 0 );
1098 * Split a storage path (e.g. "mwstore://backend/container/path/to/object")
1099 * into a backend name, a container name, and a relative object path.
1101 * @param $storagePath string
1102 * @return Array (backend, container, rel object) or (null, null, null)
1104 final public static function splitStoragePath( $storagePath ) {
1105 if ( self
::isStoragePath( $storagePath ) ) {
1106 // Note: strlen( 'mwstore://' ) = 10
1107 $parts = explode( '/', substr( $storagePath, 10 ), 3 );
1108 if ( count( $parts ) == 3 ) {
1109 return $parts; // e.g. "backend/container/path"
1110 } elseif ( count( $parts ) == 2 ) {
1111 return array( $parts[0], $parts[1], '' ); // e.g. "backend/container"
1114 return array( null, null, null );
1118 * Check if a container name is valid.
1119 * This checks for for length and illegal characters.
1121 * @param $container string
1124 final protected static function isValidContainerName( $container ) {
1125 // This accounts for Swift and S3 restrictions while leaving room
1126 // for things like '.xxx' (hex shard chars) or '.seg' (segments).
1127 // Note that matching strings URL encode to the same string;
1128 // in Swift, the length resriction is *after* URL encoding.
1129 return preg_match( '/^[a-z0-9][a-z0-9-_]{0,199}$/i', $container );
1133 * Validate and normalize a relative storage path.
1134 * Null is returned if the path involves directory traversal.
1135 * Traversal is insecure for FS backends and broken for others.
1137 * @param $path string
1138 * @return string|null
1140 final protected static function normalizeStoragePath( $path ) {
1141 // Normalize directory separators
1142 $path = strtr( $path, '\\', '/' );
1143 // Use the same traversal protection as Title::secureAndSplit()
1144 if ( strpos( $path, '.' ) !== false ) {
1148 strpos( $path, './' ) === 0 ||
1149 strpos( $path, '../' ) === 0 ||
1150 strpos( $path, '/./' ) !== false ||
1151 strpos( $path, '/../' ) !== false
1160 * Splits a storage path into an internal container name,
1161 * an internal relative file name, and a container shard suffix.
1162 * Any shard suffix is already appended to the internal container name.
1163 * This also checks that the storage path is valid and within this backend.
1165 * If the container is sharded but a suffix could not be determined,
1166 * this means that the path can only refer to a directory and can only
1167 * be scanned by looking in all the container shards.
1169 * @param $storagePath string
1170 * @return Array (container, path, container suffix) or (null, null, null) if invalid
1172 final protected function resolveStoragePath( $storagePath ) {
1173 list( $backend, $container, $relPath ) = self
::splitStoragePath( $storagePath );
1174 if ( $backend === $this->name
) { // must be for this backend
1175 $relPath = self
::normalizeStoragePath( $relPath );
1176 if ( $relPath !== null ) {
1177 // Get shard for the normalized path if this container is sharded
1178 $cShard = $this->getContainerShard( $container, $relPath );
1179 // Validate and sanitize the relative path (backend-specific)
1180 $relPath = $this->resolveContainerPath( $container, $relPath );
1181 if ( $relPath !== null ) {
1182 // Prepend any wiki ID prefix to the container name
1183 $container = $this->fullContainerName( $container );
1184 if ( self
::isValidContainerName( $container ) ) {
1185 // Validate and sanitize the container name (backend-specific)
1186 $container = $this->resolveContainerName( "{$container}{$cShard}" );
1187 if ( $container !== null ) {
1188 return array( $container, $relPath, $cShard );
1194 return array( null, null, null );
1198 * Like resolveStoragePath() except null values are returned if
1199 * the container is sharded and the shard could not be determined.
1201 * @see FileBackend::resolveStoragePath()
1203 * @param $storagePath string
1204 * @return Array (container, path) or (null, null) if invalid
1206 final protected function resolveStoragePathReal( $storagePath ) {
1207 list( $container, $relPath, $cShard ) = $this->resolveStoragePath( $storagePath );
1208 if ( $cShard !== null ) {
1209 return array( $container, $relPath );
1211 return array( null, null );
1215 * Get the container name shard suffix for a given path.
1216 * Any empty suffix means the container is not sharded.
1218 * @param $container string Container name
1219 * @param $relStoragePath string Storage path relative to the container
1220 * @return string|null Returns null if shard could not be determined
1222 final protected function getContainerShard( $container, $relPath ) {
1223 $hashLevels = $this->getContainerHashLevels( $container );
1224 if ( $hashLevels === 1 ) { // 16 shards per container
1225 $hashDirRegex = '(?P<shard>[0-9a-f])';
1226 } elseif ( $hashLevels === 2 ) { // 256 shards per container
1227 $hashDirRegex = '[0-9a-f]/(?P<shard>[0-9a-f]{2})';
1229 return ''; // no sharding
1231 // Allow certain directories to be above the hash dirs so as
1232 // to work with FileRepo (e.g. "archive/a/ab" or "temp/a/ab").
1233 // They must be 2+ chars to avoid any hash directory ambiguity.
1234 if ( preg_match( "!^(?:[^/]{2,}/)*$hashDirRegex(?:/|$)!", $relPath, $m ) ) {
1235 return '.' . str_pad( $m['shard'], $hashLevels, '0', STR_PAD_LEFT
);
1237 return null; // failed to match
1241 * Get the number of hash levels for a container.
1242 * If greater than 0, then all file storage paths within
1243 * the container are required to be hashed accordingly.
1245 * @param $container string
1248 final protected function getContainerHashLevels( $container ) {
1249 if ( isset( $this->shardViaHashLevels
[$container] ) ) {
1250 $hashLevels = (int)$this->shardViaHashLevels
[$container];
1251 if ( $hashLevels >= 0 && $hashLevels <= 2 ) {
1255 return 0; // no sharding
1259 * Get a list of full container shard suffixes for a container
1261 * @param $container string
1264 final protected function getContainerSuffixes( $container ) {
1266 $digits = $this->getContainerHashLevels( $container );
1267 if ( $digits > 0 ) {
1268 $numShards = 1 << ( $digits * 4 );
1269 for ( $index = 0; $index < $numShards; $index++
) {
1270 $shards[] = '.' . str_pad( dechex( $index ), $digits, '0', STR_PAD_LEFT
);
1277 * Get the full container name, including the wiki ID prefix
1279 * @param $container string
1282 final protected function fullContainerName( $container ) {
1283 if ( $this->wikiId
!= '' ) {
1284 return "{$this->wikiId}-$container";
1291 * Resolve a container name, checking if it's allowed by the backend.
1292 * This is intended for internal use, such as encoding illegal chars.
1293 * Subclasses can override this to be more restrictive.
1295 * @param $container string
1296 * @return string|null
1298 protected function resolveContainerName( $container ) {
1303 * Resolve a relative storage path, checking if it's allowed by the backend.
1304 * This is intended for internal use, such as encoding illegal chars or perhaps
1305 * getting absolute paths (e.g. FS based backends). Note that the relative path
1306 * may be the empty string (e.g. the path is simply to the container).
1308 * @param $container string Container name
1309 * @param $relStoragePath string Storage path relative to the container
1310 * @return string|null Path or null if not valid
1312 protected function resolveContainerPath( $container, $relStoragePath ) {
1313 return $relStoragePath;
1317 * Get the final extension from a storage or FS path
1319 * @param $path string
1322 final public static function extensionFromPath( $path ) {
1323 $i = strrpos( $path, '.' );
1324 return strtolower( $i ?
substr( $path, $i +
1 ) : '' );
1329 * FileBackend helper function to handle file listings that span container shards.
1330 * Do not use this class from places outside of FileBackend.
1332 * @ingroup FileBackend
1334 class ContainerShardListIterator
implements Iterator
{
1335 /* @var FileBackend */
1340 protected $shardSuffixes;
1341 protected $container; // string
1342 protected $directory; // string
1344 /* @var Traversable */
1346 protected $curShard = 0; // integer
1347 protected $pos = 0; // integer
1350 * @param $backend FileBackend
1351 * @param $container string Full storage container name
1352 * @param $dir string Storage directory relative to container
1353 * @param $suffixes Array List of container shard suffixes
1354 * @param $params Array
1356 public function __construct(
1357 FileBackend
$backend, $container, $dir, array $suffixes, array $params
1359 $this->backend
= $backend;
1360 $this->container
= $container;
1361 $this->directory
= $dir;
1362 $this->shardSuffixes
= $suffixes;
1363 $this->params
= $params;
1366 public function current() {
1367 if ( is_array( $this->iter
) ) {
1368 return current( $this->iter
);
1370 return $this->iter
->current();
1374 public function key() {
1378 public function next() {
1380 if ( is_array( $this->iter
) ) {
1381 next( $this->iter
);
1383 $this->iter
->next();
1385 // Find the next non-empty shard if no elements are left
1386 $this->nextShardIteratorIfNotValid();
1390 * If the iterator for this container shard is out of items,
1391 * then move on to the next container that has items.
1392 * If there are none, then it advances to the last container.
1394 protected function nextShardIteratorIfNotValid() {
1395 while ( !$this->valid() ) {
1396 if ( ++
$this->curShard
>= count( $this->shardSuffixes
) ) {
1397 break; // no more container shards
1399 $this->setIteratorFromCurrentShard();
1403 protected function setIteratorFromCurrentShard() {
1404 $suffix = $this->shardSuffixes
[$this->curShard
];
1405 $this->iter
= $this->backend
->getFileListInternal(
1406 "{$this->container}{$suffix}", $this->directory
, $this->params
);
1409 public function rewind() {
1411 $this->curShard
= 0;
1412 $this->setIteratorFromCurrentShard();
1413 // Find the next non-empty shard if this one has no elements
1414 $this->nextShardIteratorIfNotValid();
1417 public function valid() {
1418 if ( $this->iter
== null ) {
1419 return false; // some failure?
1420 } elseif ( is_array( $this->iter
) ) {
1421 return ( current( $this->iter
) !== false ); // no paths can have this value
1423 return $this->iter
->valid();