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