includes/filebackend/FileBackend.php

   1 <?php
   2 /**
   3  * @defgroup FileBackend File backend
   4  *
   5  * File backend is used to interact with file storage systems,
   6  * such as the local file system, NFS, or cloud storage systems.
   7  */
   8
   9 /**
  10  * Base class for all file backends.
  11  *
  12  * This program is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 2 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License along
  23  * with this program; if not, write to the Free Software Foundation, Inc.,
  24  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  25  * http://www.gnu.org/copyleft/gpl.html
  26  *
  27  * @file
  28  * @ingroup FileBackend
  29  * @author Aaron Schulz
  30  */
  31
  32 /**
  33  * @brief Base class for all file backend classes (including multi-write backends).
  34  *
  35  * This class defines the methods as abstract that subclasses must implement.
  36  * Outside callers can assume that all backends will have these functions.
  37  *
  38  * All "storage paths" are of the format "mwstore://<backend>/<container>/<path>".
  39  * The "backend" portion is unique name for MediaWiki to refer to a backend, while
  40  * the "container" portion is a top-level directory of the backend. The "path" portion
  41  * is a relative path that uses UNIX file system (FS) notation, though any particular
  42  * backend may not actually be using a local filesystem. Therefore, the relative paths
  43  * are only virtual.
  44  *
  45  * Backend contents are stored under wiki-specific container names by default.
  46  * Global (qualified) backends are achieved by configuring the "wiki ID" to a constant.
  47  * For legacy reasons, the FSFileBackend class allows manually setting the paths of
  48  * containers to ones that do not respect the "wiki ID".
  49  *
  50  * In key/value stores, the container is the only hierarchy (the rest is emulated).
  51  * FS-based backends are somewhat more restrictive due to the existence of real
  52  * directory files; a regular file cannot have the same name as a directory. Other
  53  * backends with virtual directories may not have this limitation. Callers should
  54  * store files in such a way that no files and directories are under the same path.
  55  *
  56  * Methods of subclasses should avoid throwing exceptions at all costs.
  57  * As a corollary, external dependencies should be kept to a minimum.
  58  *
  59  * @ingroup FileBackend
  60  * @since 1.19
  61  */
  62 abstract class FileBackend {
  63         protected $name; // string; unique backend name
  64         protected $wikiId; // string; unique wiki name
  65         protected $readOnly; // string; read-only explanation message
  66         protected $parallelize; // string; when to do operations in parallel
  67         protected $concurrency; // integer; how many operations can be done in parallel
  68
  69         /** @var LockManager */
  70         protected $lockManager;
  71         /** @var FileJournal */
  72         protected $fileJournal;
  73
  74         /**
  75          * Create a new backend instance from configuration.
  76          * This should only be called from within FileBackendGroup.
  77          *
  78          * $config includes:
  79          *   - name        : The unique name of this backend.
  80          *                   This should consist of alphanumberic, '-', and '_' characters.
  81          *                   This name should not be changed after use (e.g. with journaling).
  82          *                   Note that the name is *not* used in actual container names.
  83          *   - wikiId      : Prefix to container names that is unique to this backend.
  84          *                   If not provided, this defaults to the current wiki ID.
  85          *                   It should only consist of alphanumberic, '-', and '_' characters.
  86          *                   This ID is what avoids collisions if multiple logical backends
  87          *                   use the same storage system, so this should be set carefully.
  88          *   - lockManager : Registered name of a file lock manager to use.
  89          *   - fileJournal : File journal configuration; see FileJournal::factory().
  90          *                   Journals simply log changes to files stored in the backend.
  91          *   - readOnly    : Write operations are disallowed if this is a non-empty string.
  92          *                   It should be an explanation for the backend being read-only.
  93          *   - parallelize : When to do file operations in parallel (when possible).
  94          *                   Allowed values are "implicit", "explicit" and "off".
  95          *   - concurrency : How many file operations can be done in parallel.
  96          *
  97          * @param array $config
  98          * @throws MWException
  99          */
 100         public function __construct( array $config ) {
 101                 $this->name = $config['name'];
 102                 if ( !preg_match( '!^[a-zA-Z0-9-_]{1,255}$!', $this->name ) ) {
 103                         throw new MWException( "Backend name `{$this->name}` is invalid." );
 104                 }
 105                 $this->wikiId = isset( $config['wikiId'] )
 106                         ? $config['wikiId']
 107                         : wfWikiID(); // e.g. "my_wiki-en_"
 108                 $this->lockManager = ( $config['lockManager'] instanceof LockManager )
 109                         ? $config['lockManager']
 110                         : LockManagerGroup::singleton( $this->wikiId )->get( $config['lockManager'] );
 111                 $this->fileJournal = isset( $config['fileJournal'] )
 112                         ? ( ( $config['fileJournal'] instanceof FileJournal )
 113                                 ? $config['fileJournal']
 114                                 : FileJournal::factory( $config['fileJournal'], $this->name ) )
 115                         : FileJournal::factory( array( 'class' => 'NullFileJournal' ), $this->name );
 116                 $this->readOnly = isset( $config['readOnly'] )
 117                         ? (string)$config['readOnly']
 118                         : '';
 119                 $this->parallelize = isset( $config['parallelize'] )
 120                         ? (string)$config['parallelize']
 121                         : 'off';
 122                 $this->concurrency = isset( $config['concurrency'] )
 123                         ? (int)$config['concurrency']
 124                         : 50;
 125         }
 126
 127         /**
 128          * Get the unique backend name.
 129          * We may have multiple different backends of the same type.
 130          * For example, we can have two Swift backends using different proxies.
 131          *
 132          * @return string
 133          */
 134         final public function getName() {
 135                 return $this->name;
 136         }
 137
 138         /**
 139          * Get the wiki identifier used for this backend (possibly empty).
 140          * Note that this might *not* be in the same format as wfWikiID().
 141          *
 142          * @return string
 143          * @since 1.20
 144          */
 145         final public function getWikiId() {
 146                 return $this->wikiId;
 147         }
 148
 149         /**
 150          * Check if this backend is read-only
 151          *
 152          * @return bool
 153          */
 154         final public function isReadOnly() {
 155                 return ( $this->readOnly != '' );
 156         }
 157
 158         /**
 159          * Get an explanatory message if this backend is read-only
 160          *
 161          * @return string|bool Returns false if the backend is not read-only
 162          */
 163         final public function getReadOnlyReason() {
 164                 return ( $this->readOnly != '' ) ? $this->readOnly : false;
 165         }
 166
 167         /**
 168          * This is the main entry point into the backend for write operations.
 169          * Callers supply an ordered list of operations to perform as a transaction.
 170          * Files will be locked, the stat cache cleared, and then the operations attempted.
 171          * If any serious errors occur, all attempted operations will be rolled back.
 172          *
 173          * $ops is an array of arrays. The outer array holds a list of operations.
 174          * Each inner array is a set of key value pairs that specify an operation.
 175          *
 176          * Supported operations and their parameters. The supported actions are:
 177          *  - create
 178          *  - store
 179          *  - copy
 180          *  - move
 181          *  - delete
 182          *  - describe (since 1.21)
 183          *  - null
 184          *
 185          * a) Create a new file in storage with the contents of a string
 186          * @code
 187          *     array(
 188          *         'op'                  => 'create',
 189          *         'dst'                 => <storage path>,
 190          *         'content'             => <string of new file contents>,
 191          *         'overwrite'           => <boolean>,
 192          *         'overwriteSame'       => <boolean>,
 193          *         'headers'             => <HTTP header name/value map> # since 1.21
 194          *     );
 195          * @endcode
 196          *
 197          * b) Copy a file system file into storage
 198          * @code
 199          *     array(
 200          *         'op'                  => 'store',
 201          *         'src'                 => <file system path>,
 202          *         'dst'                 => <storage path>,
 203          *         'overwrite'           => <boolean>,
 204          *         'overwriteSame'       => <boolean>,
 205          *         'headers'             => <HTTP header name/value map> # since 1.21
 206          *     )
 207          * @endcode
 208          *
 209          * c) Copy a file within storage
 210          * @code
 211          *     array(
 212          *         'op'                  => 'copy',
 213          *         'src'                 => <storage path>,
 214          *         'dst'                 => <storage path>,
 215          *         'overwrite'           => <boolean>,
 216          *         'overwriteSame'       => <boolean>,
 217          *         'ignoreMissingSource' => <boolean>, # since 1.21
 218          *         'headers'             => <HTTP header name/value map> # since 1.21
 219          *     )
 220          * @endcode
 221          *
 222          * d) Move a file within storage
 223          * @code
 224          *     array(
 225          *         'op'                  => 'move',
 226          *         'src'                 => <storage path>,
 227          *         'dst'                 => <storage path>,
 228          *         'overwrite'           => <boolean>,
 229          *         'overwriteSame'       => <boolean>,
 230          *         'ignoreMissingSource' => <boolean>, # since 1.21
 231          *         'headers'             => <HTTP header name/value map> # since 1.21
 232          *     )
 233          * @endcode
 234          *
 235          * e) Delete a file within storage
 236          * @code
 237          *     array(
 238          *         'op'                  => 'delete',
 239          *         'src'                 => <storage path>,
 240          *         'ignoreMissingSource' => <boolean>
 241          *     )
 242          * @endcode
 243          *
 244          * f) Update metadata for a file within storage
 245          * @code
 246          *     array(
 247          *         'op'                  => 'describe',
 248          *         'src'                 => <storage path>,
 249          *         'headers'             => <HTTP header name/value map>
 250          *     )
 251          * @endcode
 252          *
 253          * g) Do nothing (no-op)
 254          * @code
 255          *     array(
 256          *         'op'                  => 'null',
 257          *     )
 258          * @endcode
 259          *
 260          * Boolean flags for operations (operation-specific):
 261          *   - ignoreMissingSource : The operation will simply succeed and do
 262          *                           nothing if the source file does not exist.
 263          *   - overwrite           : Any destination file will be overwritten.
 264          *   - overwriteSame       : If a file already exists at the destination with the
 265          *                           same contents, then do nothing to the destination file
 266          *                           instead of giving an error. This does not compare headers.
 267          *                           This option is ignored if 'overwrite' is already provided.
 268          *   - headers             : If supplied, the result of merging these headers with any
 269          *                           existing source file headers (replacing conflicting ones)
 270          *                           will be set as the destination file headers. Headers are
 271          *                           deleted if their value is set to the empty string. When a
 272          *                           file has headers they are included in responses to GET and
 273          *                           HEAD requests to the backing store for that file.
 274          *                           Header values should be no larger than 255 bytes, except for
 275          *                           Content-Disposition. The system might ignore or truncate any
 276          *                           headers that are too long to store (exact limits will vary).
 277          *                           Backends that don't support metadata ignore this. (since 1.21)
 278          *
 279          * $opts is an associative of boolean flags, including:
 280          *   - force               : Operation precondition errors no longer trigger an abort.
 281          *                           Any remaining operations are still attempted. Unexpected
 282          *                           failures may still cause remaining operations to be aborted.
 283          *   - nonLocking          : No locks are acquired for the operations.
 284          *                           This can increase performance for non-critical writes.
 285          *                           This has no effect unless the 'force' flag is set.
 286          *   - nonJournaled        : Don't log this operation batch in the file journal.
 287          *                           This limits the ability of recovery scripts.
 288          *   - parallelize         : Try to do operations in parallel when possible.
 289          *   - bypassReadOnly      : Allow writes in read-only mode. (since 1.20)
 290          *   - preserveCache       : Don't clear the process cache before checking files.
 291          *                           This should only be used if all entries in the process
 292          *                           cache were added after the files were already locked. (since 1.20)
 293          *
 294          * @remarks Remarks on locking:
 295          * File system paths given to operations should refer to files that are
 296          * already locked or otherwise safe from modification from other processes.
 297          * Normally these files will be new temp files, which should be adequate.
 298          *
 299          * @par Return value:
 300          *
 301          * This returns a Status, which contains all warnings and fatals that occurred
 302          * during the operation. The 'failCount', 'successCount', and 'success' members
 303          * will reflect each operation attempted.
 304          *
 305          * The status will be "OK" unless:
 306          *   - a) unexpected operation errors occurred (network partitions, disk full...)
 307          *   - b) significant operation errors occurred and 'force' was not set
 308          *
 309          * @param array $ops List of operations to execute in order
 310          * @param array $opts Batch operation options
 311          * @return Status
 312          */
 313         final public function doOperations( array $ops, array $opts = array() ) {
 314                 if ( empty( $opts['bypassReadOnly'] ) && $this->isReadOnly() ) {
 315                         return Status::newFatal( 'backend-fail-readonly', $this->name, $this->readOnly );
 316                 }
 317                 if ( !count( $ops ) ) {
 318                         return Status::newGood(); // nothing to do
 319                 }
 320                 if ( empty( $opts['force'] ) ) { // sanity
 321                         unset( $opts['nonLocking'] );
 322                 }
 323                 foreach ( $ops as &$op ) {
 324                         if ( isset( $op['disposition'] ) ) { // b/c (MW 1.20)
 325                                 $op['headers']['Content-Disposition'] = $op['disposition'];
 326                         }
 327                 }
 328                 $scope = $this->getScopedPHPBehaviorForOps(); // try to ignore client aborts
 329                 return $this->doOperationsInternal( $ops, $opts );
 330         }
 331
 332         /**
 333          * @see FileBackend::doOperations()
 334          */
 335         abstract protected function doOperationsInternal( array $ops, array $opts );
 336
 337         /**
 338          * Same as doOperations() except it takes a single operation.
 339          * If you are doing a batch of operations that should either
 340          * all succeed or all fail, then use that function instead.
 341          *
 342          * @see FileBackend::doOperations()
 343          *
 344          * @param array $op Operation
 345          * @param array $opts Operation options
 346          * @return Status
 347          */
 348         final public function doOperation( array $op, array $opts = array() ) {
 349                 return $this->doOperations( array( $op ), $opts );
 350         }
 351
 352         /**
 353          * Performs a single create operation.
 354          * This sets $params['op'] to 'create' and passes it to doOperation().
 355          *
 356          * @see FileBackend::doOperation()
 357          *
 358          * @param array $params Operation parameters
 359          * @param array $opts Operation options
 360          * @return Status
 361          */
 362         final public function create( array $params, array $opts = array() ) {
 363                 return $this->doOperation( array( 'op' => 'create' ) + $params, $opts );
 364         }
 365
 366         /**
 367          * Performs a single store operation.
 368          * This sets $params['op'] to 'store' and passes it to doOperation().
 369          *
 370          * @see FileBackend::doOperation()
 371          *
 372          * @param array $params Operation parameters
 373          * @param array $opts Operation options
 374          * @return Status
 375          */
 376         final public function store( array $params, array $opts = array() ) {
 377                 return $this->doOperation( array( 'op' => 'store' ) + $params, $opts );
 378         }
 379
 380         /**
 381          * Performs a single copy operation.
 382          * This sets $params['op'] to 'copy' and passes it to doOperation().
 383          *
 384          * @see FileBackend::doOperation()
 385          *
 386          * @param array $params Operation parameters
 387          * @param array $opts Operation options
 388          * @return Status
 389          */
 390         final public function copy( array $params, array $opts = array() ) {
 391                 return $this->doOperation( array( 'op' => 'copy' ) + $params, $opts );
 392         }
 393
 394         /**
 395          * Performs a single move operation.
 396          * This sets $params['op'] to 'move' and passes it to doOperation().
 397          *
 398          * @see FileBackend::doOperation()
 399          *
 400          * @param array $params Operation parameters
 401          * @param array $opts Operation options
 402          * @return Status
 403          */
 404         final public function move( array $params, array $opts = array() ) {
 405                 return $this->doOperation( array( 'op' => 'move' ) + $params, $opts );
 406         }
 407
 408         /**
 409          * Performs a single delete operation.
 410          * This sets $params['op'] to 'delete' and passes it to doOperation().
 411          *
 412          * @see FileBackend::doOperation()
 413          *
 414          * @param array $params Operation parameters
 415          * @param array $opts Operation options
 416          * @return Status
 417          */
 418         final public function delete( array $params, array $opts = array() ) {
 419                 return $this->doOperation( array( 'op' => 'delete' ) + $params, $opts );
 420         }
 421
 422         /**
 423          * Performs a single describe operation.
 424          * This sets $params['op'] to 'describe' and passes it to doOperation().
 425          *
 426          * @see FileBackend::doOperation()
 427          *
 428          * @param array $params Operation parameters
 429          * @param array $opts Operation options
 430          * @return Status
 431          * @since 1.21
 432          */
 433         final public function describe( array $params, array $opts = array() ) {
 434                 return $this->doOperation( array( 'op' => 'describe' ) + $params, $opts );
 435         }
 436
 437         /**
 438          * Perform a set of independent file operations on some files.
 439          *
 440          * This does no locking, nor journaling, and possibly no stat calls.
 441          * Any destination files that already exist will be overwritten.
 442          * This should *only* be used on non-original files, like cache files.
 443          *
 444          * Supported operations and their parameters:
 445          *  - create
 446          *  - store
 447          *  - copy
 448          *  - move
 449          *  - delete
 450          *  - describe (since 1.21)
 451          *  - null
 452          *
 453          * a) Create a new file in storage with the contents of a string
 454          * @code
 455          *     array(
 456          *         'op'                  => 'create',
 457          *         'dst'                 => <storage path>,
 458          *         'content'             => <string of new file contents>,
 459          *         'headers'             => <HTTP header name/value map> # since 1.21
 460          *     )
 461          * @endcode
 462          *
 463          * b) Copy a file system file into storage
 464          * @code
 465          *     array(
 466          *         'op'                  => 'store',
 467          *         'src'                 => <file system path>,
 468          *         'dst'                 => <storage path>,
 469          *         'headers'             => <HTTP header name/value map> # since 1.21
 470          *     )
 471          * @endcode
 472          *
 473          * c) Copy a file within storage
 474          * @code
 475          *     array(
 476          *         'op'                  => 'copy',
 477          *         'src'                 => <storage path>,
 478          *         'dst'                 => <storage path>,
 479          *         'ignoreMissingSource' => <boolean>, # since 1.21
 480          *         'headers'             => <HTTP header name/value map> # since 1.21
 481          *     )
 482          * @endcode
 483          *
 484          * d) Move a file within storage
 485          * @code
 486          *     array(
 487          *         'op'                  => 'move',
 488          *         'src'                 => <storage path>,
 489          *         'dst'                 => <storage path>,
 490          *         'ignoreMissingSource' => <boolean>, # since 1.21
 491          *         'headers'             => <HTTP header name/value map> # since 1.21
 492          *     )
 493          * @endcode
 494          *
 495          * e) Delete a file within storage
 496          * @code
 497          *     array(
 498          *         'op'                  => 'delete',
 499          *         'src'                 => <storage path>,
 500          *         'ignoreMissingSource' => <boolean>
 501          *     )
 502          * @endcode
 503          *
 504          * f) Update metadata for a file within storage
 505          * @code
 506          *     array(
 507          *         'op'                  => 'describe',
 508          *         'src'                 => <storage path>,
 509          *         'headers'             => <HTTP header name/value map>
 510          *     )
 511          * @endcode
 512          *
 513          * g) Do nothing (no-op)
 514          * @code
 515          *     array(
 516          *         'op'                  => 'null',
 517          *     )
 518          * @endcode
 519          *
 520          * @par Boolean flags for operations (operation-specific):
 521          *   - ignoreMissingSource : The operation will simply succeed and do
 522          *                           nothing if the source file does not exist.
 523          *   - headers             : If supplied with a header name/value map, the backend will
 524          *                           reply with these headers when GETs/HEADs of the destination
 525          *                           file are made. Header values should be smaller than 256 bytes.
 526          *                           Content-Disposition headers can be longer, though the system
 527          *                           might ignore or truncate ones that are too long to store.
 528          *                           Existing headers will remain, but these will replace any
 529          *                           conflicting previous headers, and headers will be removed
 530          *                           if they are set to an empty string.
 531          *                           Backends that don't support metadata ignore this. (since 1.21)
 532          *
 533          * $opts is an associative of boolean flags, including:
 534          *   - bypassReadOnly      : Allow writes in read-only mode (since 1.20)
 535          *
 536          * @par Return value:
 537          * This returns a Status, which contains all warnings and fatals that occurred
 538          * during the operation. The 'failCount', 'successCount', and 'success' members
 539          * will reflect each operation attempted for the given files. The status will be
 540          * considered "OK" as long as no fatal errors occurred.
 541          *
 542          * @param array $ops Set of operations to execute
 543          * @param array $opts Batch operation options
 544          * @return Status
 545          * @since 1.20
 546          */
 547         final public function doQuickOperations( array $ops, array $opts = array() ) {
 548                 if ( empty( $opts['bypassReadOnly'] ) && $this->isReadOnly() ) {
 549                         return Status::newFatal( 'backend-fail-readonly', $this->name, $this->readOnly );
 550                 }
 551                 if ( !count( $ops ) ) {
 552                         return Status::newGood(); // nothing to do
 553                 }
 554                 foreach ( $ops as &$op ) {
 555                         $op['overwrite'] = true; // avoids RTTs in key/value stores
 556                         if ( isset( $op['disposition'] ) ) { // b/c (MW 1.20)
 557                                 $op['headers']['Content-Disposition'] = $op['disposition'];
 558                         }
 559                 }
 560                 $scope = $this->getScopedPHPBehaviorForOps(); // try to ignore client aborts
 561                 return $this->doQuickOperationsInternal( $ops );
 562         }
 563
 564         /**
 565          * @see FileBackend::doQuickOperations()
 566          * @since 1.20
 567          */
 568         abstract protected function doQuickOperationsInternal( array $ops );
 569
 570         /**
 571          * Same as doQuickOperations() except it takes a single operation.
 572          * If you are doing a batch of operations, then use that function instead.
 573          *
 574          * @see FileBackend::doQuickOperations()
 575          *
 576          * @param array $op Operation
 577          * @return Status
 578          * @since 1.20
 579          */
 580         final public function doQuickOperation( array $op ) {
 581                 return $this->doQuickOperations( array( $op ) );
 582         }
 583
 584         /**
 585          * Performs a single quick create operation.
 586          * This sets $params['op'] to 'create' and passes it to doQuickOperation().
 587          *
 588          * @see FileBackend::doQuickOperation()
 589          *
 590          * @param array $params Operation parameters
 591          * @return Status
 592          * @since 1.20
 593          */
 594         final public function quickCreate( array $params ) {
 595                 return $this->doQuickOperation( array( 'op' => 'create' ) + $params );
 596         }
 597
 598         /**
 599          * Performs a single quick store operation.
 600          * This sets $params['op'] to 'store' and passes it to doQuickOperation().
 601          *
 602          * @see FileBackend::doQuickOperation()
 603          *
 604          * @param array $params Operation parameters
 605          * @return Status
 606          * @since 1.20
 607          */
 608         final public function quickStore( array $params ) {
 609                 return $this->doQuickOperation( array( 'op' => 'store' ) + $params );
 610         }
 611
 612         /**
 613          * Performs a single quick copy operation.
 614          * This sets $params['op'] to 'copy' and passes it to doQuickOperation().
 615          *
 616          * @see FileBackend::doQuickOperation()
 617          *
 618          * @param array $params Operation parameters
 619          * @return Status
 620          * @since 1.20
 621          */
 622         final public function quickCopy( array $params ) {
 623                 return $this->doQuickOperation( array( 'op' => 'copy' ) + $params );
 624         }
 625
 626         /**
 627          * Performs a single quick move operation.
 628          * This sets $params['op'] to 'move' and passes it to doQuickOperation().
 629          *
 630          * @see FileBackend::doQuickOperation()
 631          *
 632          * @param array $params Operation parameters
 633          * @return Status
 634          * @since 1.20
 635          */
 636         final public function quickMove( array $params ) {
 637                 return $this->doQuickOperation( array( 'op' => 'move' ) + $params );
 638         }
 639
 640         /**
 641          * Performs a single quick delete operation.
 642          * This sets $params['op'] to 'delete' and passes it to doQuickOperation().
 643          *
 644          * @see FileBackend::doQuickOperation()
 645          *
 646          * @param array $params Operation parameters
 647          * @return Status
 648          * @since 1.20
 649          */
 650         final public function quickDelete( array $params ) {
 651                 return $this->doQuickOperation( array( 'op' => 'delete' ) + $params );
 652         }
 653
 654         /**
 655          * Performs a single quick describe operation.
 656          * This sets $params['op'] to 'describe' and passes it to doQuickOperation().
 657          *
 658          * @see FileBackend::doQuickOperation()
 659          *
 660          * @param array $params Operation parameters
 661          * @return Status
 662          * @since 1.21
 663          */
 664         final public function quickDescribe( array $params ) {
 665                 return $this->doQuickOperation( array( 'op' => 'describe' ) + $params );
 666         }
 667
 668         /**
 669          * Concatenate a list of storage files into a single file system file.
 670          * The target path should refer to a file that is already locked or
 671          * otherwise safe from modification from other processes. Normally,
 672          * the file will be a new temp file, which should be adequate.
 673          *
 674          * @param array $params Operation parameters
 675          * $params include:
 676          *   - srcs        : ordered source storage paths (e.g. chunk1, chunk2, ...)
 677          *   - dst         : file system path to 0-byte temp file
 678          *   - parallelize : try to do operations in parallel when possible
 679          * @return Status
 680          */
 681         abstract public function concatenate( array $params );
 682
 683         /**
 684          * Prepare a storage directory for usage.
 685          * This will create any required containers and parent directories.
 686          * Backends using key/value stores only need to create the container.
 687          *
 688          * The 'noAccess' and 'noListing' parameters works the same as in secure(),
 689          * except they are only applied *if* the directory/container had to be created.
 690          * These flags should always be set for directories that have private files.
 691          * However, setting them is not guaranteed to actually do anything.
 692          * Additional server configuration may be needed to achieve the desired effect.
 693          *
 694          * @param array $params
 695          * $params include:
 696          *   - dir            : storage directory
 697          *   - noAccess       : try to deny file access (since 1.20)
 698          *   - noListing      : try to deny file listing (since 1.20)
 699          *   - bypassReadOnly : allow writes in read-only mode (since 1.20)
 700          * @return Status
 701          */
 702         final public function prepare( array $params ) {
 703                 if ( empty( $params['bypassReadOnly'] ) && $this->isReadOnly() ) {
 704                         return Status::newFatal( 'backend-fail-readonly', $this->name, $this->readOnly );
 705                 }
 706                 $scope = $this->getScopedPHPBehaviorForOps(); // try to ignore client aborts
 707                 return $this->doPrepare( $params );
 708         }
 709
 710         /**
 711          * @see FileBackend::prepare()
 712          */
 713         abstract protected function doPrepare( array $params );
 714
 715         /**
 716          * Take measures to block web access to a storage directory and
 717          * the container it belongs to. FS backends might add .htaccess
 718          * files whereas key/value store backends might revoke container
 719          * access to the storage user representing end-users in web requests.
 720          *
 721          * This is not guaranteed to actually make files or listings publically hidden.
 722          * Additional server configuration may be needed to achieve the desired effect.
 723          *
 724          * @param array $params
 725          * $params include:
 726          *   - dir            : storage directory
 727          *   - noAccess       : try to deny file access
 728          *   - noListing      : try to deny file listing
 729          *   - bypassReadOnly : allow writes in read-only mode (since 1.20)
 730          * @return Status
 731          */
 732         final public function secure( array $params ) {
 733                 if ( empty( $params['bypassReadOnly'] ) && $this->isReadOnly() ) {
 734                         return Status::newFatal( 'backend-fail-readonly', $this->name, $this->readOnly );
 735                 }
 736                 $scope = $this->getScopedPHPBehaviorForOps(); // try to ignore client aborts
 737                 return $this->doSecure( $params );
 738         }
 739
 740         /**
 741          * @see FileBackend::secure()
 742          */
 743         abstract protected function doSecure( array $params );
 744
 745         /**
 746          * Remove measures to block web access to a storage directory and
 747          * the container it belongs to. FS backends might remove .htaccess
 748          * files whereas key/value store backends might grant container
 749          * access to the storage user representing end-users in web requests.
 750          * This essentially can undo the result of secure() calls.
 751          *
 752          * This is not guaranteed to actually make files or listings publically viewable.
 753          * Additional server configuration may be needed to achieve the desired effect.
 754          *
 755          * @param array $params
 756          * $params include:
 757          *   - dir            : storage directory
 758          *   - access         : try to allow file access
 759          *   - listing        : try to allow file listing
 760          *   - bypassReadOnly : allow writes in read-only mode (since 1.20)
 761          * @return Status
 762          * @since 1.20
 763          */
 764         final public function publish( array $params ) {
 765                 if ( empty( $params['bypassReadOnly'] ) && $this->isReadOnly() ) {
 766                         return Status::newFatal( 'backend-fail-readonly', $this->name, $this->readOnly );
 767                 }
 768                 $scope = $this->getScopedPHPBehaviorForOps(); // try to ignore client aborts
 769                 return $this->doPublish( $params );
 770         }
 771
 772         /**
 773          * @see FileBackend::publish()
 774          */
 775         abstract protected function doPublish( array $params );
 776
 777         /**
 778          * Delete a storage directory if it is empty.
 779          * Backends using key/value stores may do nothing unless the directory
 780          * is that of an empty container, in which case it will be deleted.
 781          *
 782          * @param array $params
 783          * $params include:
 784          *   - dir            : storage directory
 785          *   - recursive      : recursively delete empty subdirectories first (since 1.20)
 786          *   - bypassReadOnly : allow writes in read-only mode (since 1.20)
 787          * @return Status
 788          */
 789         final public function clean( array $params ) {
 790                 if ( empty( $params['bypassReadOnly'] ) && $this->isReadOnly() ) {
 791                         return Status::newFatal( 'backend-fail-readonly', $this->name, $this->readOnly );
 792                 }
 793                 $scope = $this->getScopedPHPBehaviorForOps(); // try to ignore client aborts
 794                 return $this->doClean( $params );
 795         }
 796
 797         /**
 798          * @see FileBackend::clean()
 799          */
 800         abstract protected function doClean( array $params );
 801
 802         /**
 803          * Enter file operation scope.
 804          * This just makes PHP ignore user aborts/disconnects until the return
 805          * value leaves scope. This returns null and does nothing in CLI mode.
 806          *
 807          * @return ScopedCallback|null
 808          */
 809         final protected function getScopedPHPBehaviorForOps() {
 810                 if ( php_sapi_name() != 'cli' ) { // http://bugs.php.net/bug.php?id=47540
 811                         $old = ignore_user_abort( true ); // avoid half-finished operations
 812                         return new ScopedCallback( function() use ( $old ) {
 813                                 ignore_user_abort( $old );
 814                         } );
 815                 }
 816                 return null;
 817         }
 818
 819         /**
 820          * Check if a file exists at a storage path in the backend.
 821          * This returns false if only a directory exists at the path.
 822          *
 823          * @param array $params
 824          * $params include:
 825          *   - src    : source storage path
 826          *   - latest : use the latest available data
 827          * @return bool|null Returns null on failure
 828          */
 829         abstract public function fileExists( array $params );
 830
 831         /**
 832          * Get the last-modified timestamp of the file at a storage path.
 833          *
 834          * @param array $params
 835          * $params include:
 836          *   - src    : source storage path
 837          *   - latest : use the latest available data
 838          * @return string|bool TS_MW timestamp or false on failure
 839          */
 840         abstract public function getFileTimestamp( array $params );
 841
 842         /**
 843          * Get the contents of a file at a storage path in the backend.
 844          * This should be avoided for potentially large files.
 845          *
 846          * @param array $params
 847          * $params include:
 848          *   - src    : source storage path
 849          *   - latest : use the latest available data
 850          * @return string|bool Returns false on failure
 851          */
 852         final public function getFileContents( array $params ) {
 853                 $contents = $this->getFileContentsMulti(
 854                         array( 'srcs' => array( $params['src'] ) ) + $params );
 855
 856                 return $contents[$params['src']];
 857         }
 858
 859         /**
 860          * Like getFileContents() except it takes an array of storage paths
 861          * and returns a map of storage paths to strings (or null on failure).
 862          * The map keys (paths) are in the same order as the provided list of paths.
 863          *
 864          * @see FileBackend::getFileContents()
 865          *
 866          * @param array $params
 867          * $params include:
 868          *   - srcs        : list of source storage paths
 869          *   - latest      : use the latest available data
 870          *   - parallelize : try to do operations in parallel when possible
 871          * @return Array Map of (path name => string or false on failure)
 872          * @since 1.20
 873          */
 874         abstract public function getFileContentsMulti( array $params );
 875
 876         /**
 877          * Get the size (bytes) of a file at a storage path in the backend.
 878          *
 879          * @param array $params
 880          * $params include:
 881          *   - src    : source storage path
 882          *   - latest : use the latest available data
 883          * @return integer|bool Returns false on failure
 884          */
 885         abstract public function getFileSize( array $params );
 886
 887         /**
 888          * Get quick information about a file at a storage path in the backend.
 889          * If the file does not exist, then this returns false.
 890          * Otherwise, the result is an associative array that includes:
 891          *   - mtime  : the last-modified timestamp (TS_MW)
 892          *   - size   : the file size (bytes)
 893          * Additional values may be included for internal use only.
 894          *
 895          * @param array $params
 896          * $params include:
 897          *   - src    : source storage path
 898          *   - latest : use the latest available data
 899          * @return Array|bool|null Returns null on failure
 900          */
 901         abstract public function getFileStat( array $params );
 902
 903         /**
 904          * Get a SHA-1 hash of the file at a storage path in the backend.
 905          *
 906          * @param array $params
 907          * $params include:
 908          *   - src    : source storage path
 909          *   - latest : use the latest available data
 910          * @return string|bool Hash string or false on failure
 911          */
 912         abstract public function getFileSha1Base36( array $params );
 913
 914         /**
 915          * Get the properties of the file at a storage path in the backend.
 916          * This gives the result of FSFile::getProps() on a local copy of the file.
 917          *
 918          * @param array $params
 919          * $params include:
 920          *   - src    : source storage path
 921          *   - latest : use the latest available data
 922          * @return Array Returns FSFile::placeholderProps() on failure
 923          */
 924         abstract public function getFileProps( array $params );
 925
 926         /**
 927          * Stream the file at a storage path in the backend.
 928          * If the file does not exists, an HTTP 404 error will be given.
 929          * Appropriate HTTP headers (Status, Content-Type, Content-Length)
 930          * will be sent if streaming began, while none will be sent otherwise.
 931          * Implementations should flush the output buffer before sending data.
 932          *
 933          * @param array $params
 934          * $params include:
 935          *   - src     : source storage path
 936          *   - headers : list of additional HTTP headers to send on success
 937          *   - latest  : use the latest available data
 938          * @return Status
 939          */
 940         abstract public function streamFile( array $params );
 941
 942         /**
 943          * Returns a file system file, identical to the file at a storage path.
 944          * The file returned is either:
 945          *   - a) A local copy of the file at a storage path in the backend.
 946          *        The temporary copy will have the same extension as the source.
 947          *   - b) An original of the file at a storage path in the backend.
 948          * Temporary files may be purged when the file object falls out of scope.
 949          *
 950          * Write operations should *never* be done on this file as some backends
 951          * may do internal tracking or may be instances of FileBackendMultiWrite.
 952          * In that later case, there are copies of the file that must stay in sync.
 953          * Additionally, further calls to this function may return the same file.
 954          *
 955          * @param array $params
 956          * $params include:
 957          *   - src    : source storage path
 958          *   - latest : use the latest available data
 959          * @return FSFile|null Returns null on failure
 960          */
 961         final public function getLocalReference( array $params ) {
 962                 $fsFiles = $this->getLocalReferenceMulti(
 963                         array( 'srcs' => array( $params['src'] ) ) + $params );
 964
 965                 return $fsFiles[$params['src']];
 966         }
 967
 968         /**
 969          * Like getLocalReference() except it takes an array of storage paths
 970          * and returns a map of storage paths to FSFile objects (or null on failure).
 971          * The map keys (paths) are in the same order as the provided list of paths.
 972          *
 973          * @see FileBackend::getLocalReference()
 974          *
 975          * @param array $params
 976          * $params include:
 977          *   - srcs        : list of source storage paths
 978          *   - latest      : use the latest available data
 979          *   - parallelize : try to do operations in parallel when possible
 980          * @return Array Map of (path name => FSFile or null on failure)
 981          * @since 1.20
 982          */
 983         abstract public function getLocalReferenceMulti( array $params );
 984
 985         /**
 986          * Get a local copy on disk of the file at a storage path in the backend.
 987          * The temporary copy will have the same file extension as the source.
 988          * Temporary files may be purged when the file object falls out of scope.
 989          *
 990          * @param array $params
 991          * $params include:
 992          *   - src    : source storage path
 993          *   - latest : use the latest available data
 994          * @return TempFSFile|null Returns null on failure
 995          */
 996         final public function getLocalCopy( array $params ) {
 997                 $tmpFiles = $this->getLocalCopyMulti(
 998                         array( 'srcs' => array( $params['src'] ) ) + $params );
 999
1000                 return $tmpFiles[$params['src']];
1001         }
1002
1003         /**
1004          * Like getLocalCopy() except it takes an array of storage paths and
1005          * returns a map of storage paths to TempFSFile objects (or null on failure).
1006          * The map keys (paths) are in the same order as the provided list of paths.
1007          *
1008          * @see FileBackend::getLocalCopy()
1009          *
1010          * @param array $params
1011          * $params include:
1012          *   - srcs        : list of source storage paths
1013          *   - latest      : use the latest available data
1014          *   - parallelize : try to do operations in parallel when possible
1015          * @return Array Map of (path name => TempFSFile or null on failure)
1016          * @since 1.20
1017          */
1018         abstract public function getLocalCopyMulti( array $params );
1019
1020         /**
1021          * Return an HTTP URL to a given file that requires no authentication to use.
1022          * The URL may be pre-authenticated (via some token in the URL) and temporary.
1023          * This will return null if the backend cannot make an HTTP URL for the file.
1024          *
1025          * This is useful for key/value stores when using scripts that seek around
1026          * large files and those scripts (and the backend) support HTTP Range headers.
1027          * Otherwise, one would need to use getLocalReference(), which involves loading
1028          * the entire file on to local disk.
1029          *
1030          * @param array $params
1031          * $params include:
1032          *   - src : source storage path
1033          *   - ttl : lifetime (seconds) if pre-authenticated; default is 1 day
1034          * @return string|null
1035          * @since 1.21
1036          */
1037         abstract public function getFileHttpUrl( array $params );
1038
1039         /**
1040          * Check if a directory exists at a given storage path.
1041          * Backends using key/value stores will check if the path is a
1042          * virtual directory, meaning there are files under the given directory.
1043          *
1044          * Storage backends with eventual consistency might return stale data.
1045          *
1046          * @param array $params
1047          * $params include:
1048          *   - dir : storage directory
1049          * @return bool|null Returns null on failure
1050          * @since 1.20
1051          */
1052         abstract public function directoryExists( array $params );
1053
1054         /**
1055          * Get an iterator to list *all* directories under a storage directory.
1056          * If the directory is of the form "mwstore://backend/container",
1057          * then all directories in the container will be listed.
1058          * If the directory is of form "mwstore://backend/container/dir",
1059          * then all directories directly under that directory will be listed.
1060          * Results will be storage directories relative to the given directory.
1061          *
1062          * Storage backends with eventual consistency might return stale data.
1063          *
1064          * Failures during iteration can result in FileBackendError exceptions (since 1.22).
1065          *
1066          * @param array $params
1067          * $params include:
1068          *   - dir     : storage directory
1069          *   - topOnly : only return direct child dirs of the directory
1070          * @return Traversable|Array|null Returns null on failure
1071          * @since 1.20
1072          */
1073         abstract public function getDirectoryList( array $params );
1074
1075         /**
1076          * Same as FileBackend::getDirectoryList() except only lists
1077          * directories that are immediately under the given directory.
1078          *
1079          * Storage backends with eventual consistency might return stale data.
1080          *
1081          * Failures during iteration can result in FileBackendError exceptions (since 1.22).
1082          *
1083          * @param array $params
1084          * $params include:
1085          *   - dir : storage directory
1086          * @return Traversable|Array|null Returns null on failure
1087          * @since 1.20
1088          */
1089         final public function getTopDirectoryList( array $params ) {
1090                 return $this->getDirectoryList( array( 'topOnly' => true ) + $params );
1091         }
1092
1093         /**
1094          * Get an iterator to list *all* stored files under a storage directory.
1095          * If the directory is of the form "mwstore://backend/container",
1096          * then all files in the container will be listed.
1097          * If the directory is of form "mwstore://backend/container/dir",
1098          * then all files under that directory will be listed.
1099          * Results will be storage paths relative to the given directory.
1100          *
1101          * Storage backends with eventual consistency might return stale data.
1102          *
1103          * Failures during iteration can result in FileBackendError exceptions (since 1.22).
1104          *
1105          * @param array $params
1106          * $params include:
1107          *   - dir        : storage directory
1108          *   - topOnly    : only return direct child files of the directory (since 1.20)
1109          *   - adviseStat : set to true if stat requests will be made on the files (since 1.22)
1110          * @return Traversable|Array|null Returns null on failure
1111          */
1112         abstract public function getFileList( array $params );
1113
1114         /**
1115          * Same as FileBackend::getFileList() except only lists
1116          * files that are immediately under the given directory.
1117          *
1118          * Storage backends with eventual consistency might return stale data.
1119          *
1120          * Failures during iteration can result in FileBackendError exceptions (since 1.22).
1121          *
1122          * @param array $params
1123          * $params include:
1124          *   - dir        : storage directory
1125          *   - adviseStat : set to true if stat requests will be made on the files (since 1.22)
1126          * @return Traversable|Array|null Returns null on failure
1127          * @since 1.20
1128          */
1129         final public function getTopFileList( array $params ) {
1130                 return $this->getFileList( array( 'topOnly' => true ) + $params );
1131         }
1132
1133         /**
1134          * Preload persistent file stat and property cache into in-process cache.
1135          * This should be used when stat calls will be made on a known list of a many files.
1136          *
1137          * @param array $paths Storage paths
1138          * @return void
1139          */
1140         public function preloadCache( array $paths ) {}
1141
1142         /**
1143          * Invalidate any in-process file stat and property cache.
1144          * If $paths is given, then only the cache for those files will be cleared.
1145          *
1146          * @param array $paths Storage paths (optional)
1147          * @return void
1148          */
1149         public function clearCache( array $paths = null ) {}
1150
1151         /**
1152          * Lock the files at the given storage paths in the backend.
1153          * This will either lock all the files or none (on failure).
1154          *
1155          * Callers should consider using getScopedFileLocks() instead.
1156          *
1157          * @param array $paths Storage paths
1158          * @param integer $type LockManager::LOCK_* constant
1159          * @return Status
1160          */
1161         final public function lockFiles( array $paths, $type ) {
1162                 $paths = array_map( 'FileBackend::normalizeStoragePath', $paths );
1163                 return $this->lockManager->lock( $paths, $type );
1164         }
1165
1166         /**
1167          * Unlock the files at the given storage paths in the backend.
1168          *
1169          * @param array $paths Storage paths
1170          * @param integer $type LockManager::LOCK_* constant
1171          * @return Status
1172          */
1173         final public function unlockFiles( array $paths, $type ) {
1174                 $paths = array_map( 'FileBackend::normalizeStoragePath', $paths );
1175                 return $this->lockManager->unlock( $paths, $type );
1176         }
1177
1178         /**
1179          * Lock the files at the given storage paths in the backend.
1180          * This will either lock all the files or none (on failure).
1181          * On failure, the status object will be updated with errors.
1182          *
1183          * Once the return value goes out scope, the locks will be released and
1184          * the status updated. Unlock fatals will not change the status "OK" value.
1185          *
1186          * @param array $paths Storage paths
1187          * @param integer $type LockManager::LOCK_* constant
1188          * @param Status $status Status to update on lock/unlock
1189          * @return ScopedLock|null Returns null on failure
1190          */
1191         final public function getScopedFileLocks( array $paths, $type, Status $status ) {
1192                 if ( $type === 'mixed' ) {
1193                         foreach ( $paths as &$typePaths ) {
1194                                 $typePaths = array_map( 'FileBackend::normalizeStoragePath', $typePaths );
1195                         }
1196                 } else {
1197                         $paths = array_map( 'FileBackend::normalizeStoragePath', $paths );
1198                 }
1199                 return ScopedLock::factory( $this->lockManager, $paths, $type, $status );
1200         }
1201
1202         /**
1203          * Get an array of scoped locks needed for a batch of file operations.
1204          *
1205          * Normally, FileBackend::doOperations() handles locking, unless
1206          * the 'nonLocking' param is passed in. This function is useful if you
1207          * want the files to be locked for a broader scope than just when the
1208          * files are changing. For example, if you need to update DB metadata,
1209          * you may want to keep the files locked until finished.
1210          *
1211          * @see FileBackend::doOperations()
1212          *
1213          * @param array $ops List of file operations to FileBackend::doOperations()
1214          * @param Status $status Status to update on lock/unlock
1215          * @return Array List of ScopedFileLocks or null values
1216          * @since 1.20
1217          */
1218         abstract public function getScopedLocksForOps( array $ops, Status $status );
1219
1220         /**
1221          * Get the root storage path of this backend.
1222          * All container paths are "subdirectories" of this path.
1223          *
1224          * @return string Storage path
1225          * @since 1.20
1226          */
1227         final public function getRootStoragePath() {
1228                 return "mwstore://{$this->name}";
1229         }
1230
1231         /**
1232          * Get the storage path for the given container for this backend
1233          *
1234          * @param string $container Container name
1235          * @return string Storage path
1236          * @since 1.21
1237          */
1238         final public function getContainerStoragePath( $container ) {
1239                 return $this->getRootStoragePath() . "/{$container}";
1240         }
1241
1242         /**
1243          * Get the file journal object for this backend
1244          *
1245          * @return FileJournal
1246          */
1247         final public function getJournal() {
1248                 return $this->fileJournal;
1249         }
1250
1251         /**
1252          * Check if a given path is a "mwstore://" path.
1253          * This does not do any further validation or any existence checks.
1254          *
1255          * @param string $path
1256          * @return bool
1257          */
1258         final public static function isStoragePath( $path ) {
1259                 return ( strpos( $path, 'mwstore://' ) === 0 );
1260         }
1261
1262         /**
1263          * Split a storage path into a backend name, a container name,
1264          * and a relative file path. The relative path may be the empty string.
1265          * This does not do any path normalization or traversal checks.
1266          *
1267          * @param string $storagePath
1268          * @return Array (backend, container, rel object) or (null, null, null)
1269          */
1270         final public static function splitStoragePath( $storagePath ) {
1271                 if ( self::isStoragePath( $storagePath ) ) {
1272                         // Remove the "mwstore://" prefix and split the path
1273                         $parts = explode( '/', substr( $storagePath, 10 ), 3 );
1274                         if ( count( $parts ) >= 2 && $parts[0] != '' && $parts[1] != '' ) {
1275                                 if ( count( $parts ) == 3 ) {
1276                                         return $parts; // e.g. "backend/container/path"
1277                                 } else {
1278                                         return array( $parts[0], $parts[1], '' ); // e.g. "backend/container"
1279                                 }
1280                         }
1281                 }
1282                 return array( null, null, null );
1283         }
1284
1285         /**
1286          * Normalize a storage path by cleaning up directory separators.
1287          * Returns null if the path is not of the format of a valid storage path.
1288          *
1289          * @param string $storagePath
1290          * @return string|null
1291          */
1292         final public static function normalizeStoragePath( $storagePath ) {
1293                 list( $backend, $container, $relPath ) = self::splitStoragePath( $storagePath );
1294                 if ( $relPath !== null ) { // must be for this backend
1295                         $relPath = self::normalizeContainerPath( $relPath );
1296                         if ( $relPath !== null ) {
1297                                 return ( $relPath != '' )
1298                                         ? "mwstore://{$backend}/{$container}/{$relPath}"
1299                                         : "mwstore://{$backend}/{$container}";
1300                         }
1301                 }
1302                 return null;
1303         }
1304
1305         /**
1306          * Get the parent storage directory of a storage path.
1307          * This returns a path like "mwstore://backend/container",
1308          * "mwstore://backend/container/...", or null if there is no parent.
1309          *
1310          * @param string $storagePath
1311          * @return string|null
1312          */
1313         final public static function parentStoragePath( $storagePath ) {
1314                 $storagePath = dirname( $storagePath );
1315                 list( , , $rel ) = self::splitStoragePath( $storagePath );
1316                 return ( $rel === null ) ? null : $storagePath;
1317         }
1318
1319         /**
1320          * Get the final extension from a storage or FS path
1321          *
1322          * @param string $path
1323          * @return string
1324          */
1325         final public static function extensionFromPath( $path ) {
1326                 $i = strrpos( $path, '.' );
1327                 return strtolower( $i ? substr( $path, $i + 1 ) : '' );
1328         }
1329
1330         /**
1331          * Check if a relative path has no directory traversals
1332          *
1333          * @param string $path
1334          * @return bool
1335          * @since 1.20
1336          */
1337         final public static function isPathTraversalFree( $path ) {
1338                 return ( self::normalizeContainerPath( $path ) !== null );
1339         }
1340
1341         /**
1342          * Build a Content-Disposition header value per RFC 6266.
1343          *
1344          * @param string $type One of (attachment, inline)
1345          * @param string $filename Suggested file name (should not contain slashes)
1346          * @throws MWException
1347          * @return string
1348          * @since 1.20
1349          */
1350         final public static function makeContentDisposition( $type, $filename = '' ) {
1351                 $parts = array();
1352
1353                 $type = strtolower( $type );
1354                 if ( !in_array( $type, array( 'inline', 'attachment' ) ) ) {
1355                         throw new MWException( "Invalid Content-Disposition type '$type'." );
1356                 }
1357                 $parts[] = $type;
1358
1359                 if ( strlen( $filename ) ) {
1360                         $parts[] = "filename*=UTF-8''" . rawurlencode( basename( $filename ) );
1361                 }
1362
1363                 return implode( ';', $parts );
1364         }
1365
1366         /**
1367          * Validate and normalize a relative storage path.
1368          * Null is returned if the path involves directory traversal.
1369          * Traversal is insecure for FS backends and broken for others.
1370          *
1371          * This uses the same traversal protection as Title::secureAndSplit().
1372          *
1373          * @param string $path Storage path relative to a container
1374          * @return string|null
1375          */
1376         final protected static function normalizeContainerPath( $path ) {
1377                 // Normalize directory separators
1378                 $path = strtr( $path, '\\', '/' );
1379                 // Collapse any consecutive directory separators
1380                 $path = preg_replace( '![/]{2,}!', '/', $path );
1381                 // Remove any leading directory separator
1382                 $path = ltrim( $path, '/' );
1383                 // Use the same traversal protection as Title::secureAndSplit()
1384                 if ( strpos( $path, '.' ) !== false ) {
1385                         if (
1386                                 $path === '.' ||
1387                                 $path === '..' ||
1388                                 strpos( $path, './' ) === 0 ||
1389                                 strpos( $path, '../' ) === 0 ||
1390                                 strpos( $path, '/./' ) !== false ||
1391                                 strpos( $path, '/../' ) !== false
1392                         ) {
1393                                 return null;
1394                         }
1395                 }
1396                 return $path;
1397         }
1398 }
1399
1400 /**
1401  * @ingroup FileBackend
1402  * @since 1.22
1403  */
1404 class FileBackendError extends MWException {}