3 * Temporary storage for uploaded files.
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
24 * UploadStash is intended to accomplish a few things:
25 * - Enable applications to temporarily stash files without publishing them to
27 * - Several parts of MediaWiki do this in similar ways: UploadBase,
28 * UploadWizard, and FirefoggChunkedExtension.
29 * And there are several that reimplement stashing from scratch, in
30 * idiosyncratic ways. The idea is to unify them all here.
31 * Mostly all of them are the same except for storing some custom fields,
32 * which we subsume into the data array.
33 * - Enable applications to find said files later, as long as the db table or
34 * temp files haven't been purged.
35 * - Enable the uploading user (and *ONLY* the uploading user) to access said
36 * files, and thumbnails of said files, via a URL. We accomplish this using
37 * a database table, with ownership checking as you might expect. See
38 * SpecialUploadStash, which implements a web interface to some files stored
41 * UploadStash right now is *mostly* intended to show you one user's slice of
42 * the entire stash. The user parameter is only optional because there are few
43 * cases where we clean out the stash from an automated script. In the future we
44 * might refactor this.
46 * UploadStash represents the entire stash of temporary files.
47 * UploadStashFile is a filestore for the actual physical disk files.
48 * UploadFromStash extends UploadBase, and represents a single stashed file as
49 * it is moved from the stash to the regular file repository
54 // Format of the key for files -- has to be suitable as a filename itself (e.g. ab12cd34ef.jpg)
55 const KEY_FORMAT_REGEX
= '/^[\w\-\.]+\.\w*$/';
56 const MAX_US_PROPS_SIZE
= 65535;
59 * repository that this uses to store temp files
60 * public because we sometimes need to get a LocalFile within the same repo.
66 // array of initialized repo objects
67 protected $files = [];
69 // cache of the file metadata that's stored in the database
70 protected $fileMetadata = [];
73 protected $fileProps = [];
76 protected $user, $userId, $isLoggedIn;
79 * Represents a temporary filestore, with metadata in the database.
80 * Designed to be compatible with the session stashing code in UploadBase
81 * (should replace it eventually).
83 * @param FileRepo $repo
84 * @param User|null $user
86 public function __construct( FileRepo
$repo, $user = null ) {
87 // this might change based on wiki's configuration.
90 // if a user was passed, use it. otherwise, attempt to use the global.
91 // this keeps FileRepo from breaking when it creates an UploadStash object
93 $this->user
= $user ?
: $wgUser;
95 if ( is_object( $this->user
) ) {
96 $this->userId
= $this->user
->getId();
97 $this->isLoggedIn
= $this->user
->isLoggedIn();
102 * Get a file and its metadata from the stash.
103 * The noAuth param is a bit janky but is required for automated scripts
104 * which clean out the stash.
106 * @param string $key Key under which file information is stored
107 * @param bool $noAuth (optional) Don't check authentication. Used by maintenance scripts.
108 * @throws UploadStashFileNotFoundException
109 * @throws UploadStashNotLoggedInException
110 * @throws UploadStashWrongOwnerException
111 * @throws UploadStashBadPathException
112 * @return UploadStashFile
114 public function getFile( $key, $noAuth = false ) {
115 if ( !preg_match( self
::KEY_FORMAT_REGEX
, $key ) ) {
116 throw new UploadStashBadPathException(
117 wfMessage( 'uploadstash-bad-path-bad-format', $key )
121 if ( !$noAuth && !$this->isLoggedIn
) {
122 throw new UploadStashNotLoggedInException(
123 wfMessage( 'uploadstash-not-logged-in' )
127 if ( !isset( $this->fileMetadata
[$key] ) ) {
128 if ( !$this->fetchFileMetadata( $key ) ) {
129 // If nothing was received, it's likely due to replication lag.
130 // Check the master to see if the record is there.
131 $this->fetchFileMetadata( $key, DB_MASTER
);
134 if ( !isset( $this->fileMetadata
[$key] ) ) {
135 throw new UploadStashFileNotFoundException(
136 wfMessage( 'uploadstash-file-not-found', $key )
140 // create $this->files[$key]
141 $this->initFile( $key );
144 if ( strlen( $this->fileMetadata
[$key]['us_props'] ) ) {
145 $this->fileProps
[$key] = unserialize( $this->fileMetadata
[$key]['us_props'] );
146 } else { // b/c for rows with no us_props
147 wfDebug( __METHOD__
. " fetched props for $key from file\n" );
148 $path = $this->fileMetadata
[$key]['us_path'];
149 $this->fileProps
[$key] = $this->repo
->getFileProps( $path );
153 if ( !$this->files
[$key]->exists() ) {
154 wfDebug( __METHOD__
. " tried to get file at $key, but it doesn't exist\n" );
155 // @todo Is this not an UploadStashFileNotFoundException case?
156 throw new UploadStashBadPathException(
157 wfMessage( 'uploadstash-bad-path' )
161 if ( !$noAuth && $this->fileMetadata
[$key]['us_user'] != $this->userId
) {
162 throw new UploadStashWrongOwnerException(
163 wfMessage( 'uploadstash-wrong-owner', $key )
167 return $this->files
[$key];
171 * Getter for file metadata.
173 * @param string $key Key under which file information is stored
176 public function getMetadata( $key ) {
177 $this->getFile( $key );
179 return $this->fileMetadata
[$key];
183 * Getter for fileProps
185 * @param string $key Key under which file information is stored
188 public function getFileProps( $key ) {
189 $this->getFile( $key );
191 return $this->fileProps
[$key];
195 * Stash a file in a temp directory and record that we did this in the
196 * database, along with other metadata.
198 * @param string $path Path to file you want stashed
199 * @param string|null $sourceType The type of upload that generated this file
200 * (currently, I believe, 'file' or null)
201 * @throws UploadStashBadPathException
202 * @throws UploadStashFileException
203 * @throws UploadStashNotLoggedInException
204 * @return UploadStashFile|null File, or null on failure
206 public function stashFile( $path, $sourceType = null ) {
207 if ( !is_file( $path ) ) {
208 wfDebug( __METHOD__
. " tried to stash file at '$path', but it doesn't exist\n" );
209 throw new UploadStashBadPathException(
210 wfMessage( 'uploadstash-bad-path' )
214 $mwProps = new MWFileProps( MediaWiki\MediaWikiServices
::getInstance()->getMimeAnalyzer() );
215 $fileProps = $mwProps->getPropsFromPath( $path, true );
216 wfDebug( __METHOD__
. " stashing file at '$path'\n" );
218 // we will be initializing from some tmpnam files that don't have extensions.
219 // most of MediaWiki assumes all uploaded files have good extensions. So, we fix this.
220 $extension = self
::getExtensionForPath( $path );
221 if ( !preg_match( "/\\.\\Q$extension\\E$/", $path ) ) {
222 $pathWithGoodExtension = "$path.$extension";
224 $pathWithGoodExtension = $path;
227 // If no key was supplied, make one. a mysql insertid would be totally
228 // reasonable here, except that for historical reasons, the key is this
229 // random thing instead. At least it's not guessable.
230 // Some things that when combined will make a suitably unique key.
231 // see: http://www.jwz.org/doc/mid.html
232 list( $usec, $sec ) = explode( ' ', microtime() );
233 $usec = substr( $usec, 2 );
234 $key = Wikimedia\base_convert
( $sec . $usec, 10, 36 ) . '.' .
235 Wikimedia\base_convert
( mt_rand(), 10, 36 ) . '.' .
236 $this->userId
. '.' .
239 $this->fileProps
[$key] = $fileProps;
241 if ( !preg_match( self
::KEY_FORMAT_REGEX
, $key ) ) {
242 throw new UploadStashBadPathException(
243 wfMessage( 'uploadstash-bad-path-bad-format', $key )
247 wfDebug( __METHOD__
. " key for '$path': $key\n" );
249 // if not already in a temporary area, put it there
250 $storeStatus = $this->repo
->storeTemp( basename( $pathWithGoodExtension ), $path );
252 if ( !$storeStatus->isOK() ) {
253 // It is a convention in MediaWiki to only return one error per API
254 // exception, even if multiple errors are available. We use reset()
255 // to pick the "first" thing that was wrong, preferring errors to
256 // warnings. This is a bit lame, as we may have more info in the
257 // $storeStatus and we're throwing it away, but to fix it means
258 // redesigning API errors significantly.
259 // $storeStatus->value just contains the virtual URL (if anything)
260 // which is probably useless to the caller.
261 $error = $storeStatus->getErrorsArray();
262 $error = reset( $error );
263 if ( !count( $error ) ) {
264 $error = $storeStatus->getWarningsArray();
265 $error = reset( $error );
266 if ( !count( $error ) ) {
267 $error = [ 'unknown', 'no error recorded' ];
270 // At this point, $error should contain the single "most important"
271 // error, plus any parameters.
272 $errorMsg = array_shift( $error );
273 throw new UploadStashFileException( wfMessage( $errorMsg, $error ) );
275 $stashPath = $storeStatus->value
;
277 // fetch the current user ID
278 if ( !$this->isLoggedIn
) {
279 throw new UploadStashNotLoggedInException(
280 wfMessage( 'uploadstash-not-logged-in' )
284 // insert the file metadata into the db.
285 wfDebug( __METHOD__
. " inserting $stashPath under $key\n" );
286 $dbw = $this->repo
->getMasterDB();
288 $serializedFileProps = serialize( $fileProps );
289 if ( strlen( $serializedFileProps ) > self
::MAX_US_PROPS_SIZE
) {
290 // Database is going to truncate this and make the field invalid.
291 // Prioritize important metadata over file handler metadata.
292 // File handler should be prepared to regenerate invalid metadata if needed.
293 $fileProps['metadata'] = false;
294 $serializedFileProps = serialize( $fileProps );
297 $this->fileMetadata
[$key] = [
298 'us_user' => $this->userId
,
300 'us_orig_path' => $path,
301 'us_path' => $stashPath, // virtual URL
302 'us_props' => $dbw->encodeBlob( $serializedFileProps ),
303 'us_size' => $fileProps['size'],
304 'us_sha1' => $fileProps['sha1'],
305 'us_mime' => $fileProps['mime'],
306 'us_media_type' => $fileProps['media_type'],
307 'us_image_width' => $fileProps['width'],
308 'us_image_height' => $fileProps['height'],
309 'us_image_bits' => $fileProps['bits'],
310 'us_source_type' => $sourceType,
311 'us_timestamp' => $dbw->timestamp(),
312 'us_status' => 'finished'
317 $this->fileMetadata
[$key],
321 // store the insertid in the class variable so immediate retrieval
322 // (possibly laggy) isn't necessary.
323 $this->fileMetadata
[$key]['us_id'] = $dbw->insertId();
325 # create the UploadStashFile object for this file.
326 $this->initFile( $key );
328 return $this->getFile( $key );
332 * Remove all files from the stash.
333 * Does not clean up files in the repo, just the record of them.
335 * @throws UploadStashNotLoggedInException
336 * @return bool Success
338 public function clear() {
339 if ( !$this->isLoggedIn
) {
340 throw new UploadStashNotLoggedInException(
341 wfMessage( 'uploadstash-not-logged-in' )
345 wfDebug( __METHOD__
. ' clearing all rows for user ' . $this->userId
. "\n" );
346 $dbw = $this->repo
->getMasterDB();
349 [ 'us_user' => $this->userId
],
355 $this->fileMetadata
= [];
361 * Remove a particular file from the stash. Also removes it from the repo.
364 * @throws UploadStashNoSuchKeyException|UploadStashNotLoggedInException
365 * @throws UploadStashWrongOwnerException
366 * @return bool Success
368 public function removeFile( $key ) {
369 if ( !$this->isLoggedIn
) {
370 throw new UploadStashNotLoggedInException(
371 wfMessage( 'uploadstash-not-logged-in' )
375 $dbw = $this->repo
->getMasterDB();
377 // this is a cheap query. it runs on the master so that this function
378 // still works when there's lag. It won't be called all that often.
379 $row = $dbw->selectRow(
382 [ 'us_key' => $key ],
387 throw new UploadStashNoSuchKeyException(
388 wfMessage( 'uploadstash-no-such-key', $key )
392 if ( $row->us_user
!= $this->userId
) {
393 throw new UploadStashWrongOwnerException(
394 wfMessage( 'uploadstash-wrong-owner', $key )
398 return $this->removeFileNoAuth( $key );
402 * Remove a file (see removeFile), but doesn't check ownership first.
405 * @return bool Success
407 public function removeFileNoAuth( $key ) {
408 wfDebug( __METHOD__
. " clearing row $key\n" );
410 // Ensure we have the UploadStashFile loaded for this key
411 $this->getFile( $key, true );
413 $dbw = $this->repo
->getMasterDB();
417 [ 'us_key' => $key ],
421 /** @todo Look into UnregisteredLocalFile and find out why the rv here is
422 * sometimes wrong (false when file was removed). For now, ignore.
424 $this->files
[$key]->remove();
426 unset( $this->files
[$key] );
427 unset( $this->fileMetadata
[$key] );
433 * List all files in the stash.
435 * @throws UploadStashNotLoggedInException
438 public function listFiles() {
439 if ( !$this->isLoggedIn
) {
440 throw new UploadStashNotLoggedInException(
441 wfMessage( 'uploadstash-not-logged-in' )
445 $dbr = $this->repo
->getReplicaDB();
449 [ 'us_user' => $this->userId
],
453 if ( !is_object( $res ) ||
$res->numRows() == 0 ) {
458 // finish the read before starting writes.
460 foreach ( $res as $row ) {
461 array_push( $keys, $row->us_key
);
468 * Find or guess extension -- ensuring that our extension matches our MIME type.
469 * Since these files are constructed from php tempnames they may not start off
471 * XXX this is somewhat redundant with the checks that ApiUpload.php does with incoming
472 * uploads versus the desired filename. Maybe we can get that passed to us...
473 * @param string $path
474 * @throws UploadStashFileException
477 public static function getExtensionForPath( $path ) {
478 global $wgFileBlacklist;
479 // Does this have an extension?
480 $n = strrpos( $path, '.' );
482 if ( $n !== false ) {
483 $extension = $n ?
substr( $path, $n +
1 ) : '';
485 // If not, assume that it should be related to the MIME type of the original file.
486 $magic = MediaWiki\MediaWikiServices
::getInstance()->getMimeAnalyzer();
487 $mimeType = $magic->guessMimeType( $path );
488 $extensions = explode( ' ', $magic->getExtensionsForType( $mimeType ) );
489 if ( count( $extensions ) ) {
490 $extension = $extensions[0];
494 if ( is_null( $extension ) ) {
495 throw new UploadStashFileException(
496 wfMessage( 'uploadstash-no-extension' )
500 $extension = File
::normalizeExtension( $extension );
501 if ( in_array( $extension, $wgFileBlacklist ) ) {
502 // The file should already be checked for being evil.
503 // However, if somehow we got here, we definitely
504 // don't want to give it an extension of .php and
505 // put it in a web accesible directory.
513 * Helper function: do the actual database query to fetch file metadata.
516 * @param int $readFromDB Constant (default: DB_REPLICA)
519 protected function fetchFileMetadata( $key, $readFromDB = DB_REPLICA
) {
520 // populate $fileMetadata[$key]
522 if ( $readFromDB === DB_MASTER
) {
523 // sometimes reading from the master is necessary, if there's replication lag.
524 $dbr = $this->repo
->getMasterDB();
526 $dbr = $this->repo
->getReplicaDB();
529 $row = $dbr->selectRow(
532 'us_user', 'us_key', 'us_orig_path', 'us_path', 'us_props',
533 'us_size', 'us_sha1', 'us_mime', 'us_media_type',
534 'us_image_width', 'us_image_height', 'us_image_bits',
535 'us_source_type', 'us_timestamp', 'us_status',
537 [ 'us_key' => $key ],
541 if ( !is_object( $row ) ) {
542 // key wasn't present in the database. this will happen sometimes.
546 $this->fileMetadata
[$key] = (array)$row;
547 $this->fileMetadata
[$key]['us_props'] = $dbr->decodeBlob( $row->us_props
);
553 * Helper function: Initialize the UploadStashFile for a given file.
555 * @param string $key Key under which to store the object
556 * @throws UploadStashZeroLengthFileException
559 protected function initFile( $key ) {
560 $file = new UploadStashFile( $this->repo
, $this->fileMetadata
[$key]['us_path'], $key );
561 if ( $file->getSize() === 0 ) {
562 throw new UploadStashZeroLengthFileException(
563 wfMessage( 'uploadstash-zero-length' )
566 $this->files
[$key] = $file;