includes/api/ApiMain.php

   1 <?php
   2 /**
   3  *
   4  *
   5  * Created on Sep 4, 2006
   6  *
   7  * Copyright © 2006 Yuri Astrakhan "<Firstname><Lastname>@gmail.com"
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License along
  20  * with this program; if not, write to the Free Software Foundation, Inc.,
  21  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  22  * http://www.gnu.org/copyleft/gpl.html
  23  *
  24  * @file
  25  * @defgroup API API
  26  */
  27
  28 /**
  29  * This is the main API class, used for both external and internal processing.
  30  * When executed, it will create the requested formatter object,
  31  * instantiate and execute an object associated with the needed action,
  32  * and use formatter to print results.
  33  * In case of an exception, an error message will be printed using the same formatter.
  34  *
  35  * To use API from another application, run it using FauxRequest object, in which
  36  * case any internal exceptions will not be handled but passed up to the caller.
  37  * After successful execution, use getResult() for the resulting data.
  38  *
  39  * @ingroup API
  40  */
  41 class ApiMain extends ApiBase {
  42         /**
  43          * When no format parameter is given, this format will be used
  44          */
  45         const API_DEFAULT_FORMAT = 'jsonfm';
  46
  47         /**
  48          * List of available modules: action name => module class
  49          */
  50         private static $Modules = array(
  51                 'login' => 'ApiLogin',
  52                 'logout' => 'ApiLogout',
  53                 'createaccount' => 'ApiCreateAccount',
  54                 'query' => 'ApiQuery',
  55                 'expandtemplates' => 'ApiExpandTemplates',
  56                 'parse' => 'ApiParse',
  57                 'stashedit' => 'ApiStashEdit',
  58                 'opensearch' => 'ApiOpenSearch',
  59                 'feedcontributions' => 'ApiFeedContributions',
  60                 'feedrecentchanges' => 'ApiFeedRecentChanges',
  61                 'feedwatchlist' => 'ApiFeedWatchlist',
  62                 'help' => 'ApiHelp',
  63                 'paraminfo' => 'ApiParamInfo',
  64                 'rsd' => 'ApiRsd',
  65                 'compare' => 'ApiComparePages',
  66                 'tokens' => 'ApiTokens',
  67                 'checktoken' => 'ApiCheckToken',
  68
  69                 // Write modules
  70                 'purge' => 'ApiPurge',
  71                 'setnotificationtimestamp' => 'ApiSetNotificationTimestamp',
  72                 'rollback' => 'ApiRollback',
  73                 'delete' => 'ApiDelete',
  74                 'undelete' => 'ApiUndelete',
  75                 'protect' => 'ApiProtect',
  76                 'block' => 'ApiBlock',
  77                 'unblock' => 'ApiUnblock',
  78                 'move' => 'ApiMove',
  79                 'edit' => 'ApiEditPage',
  80                 'upload' => 'ApiUpload',
  81                 'filerevert' => 'ApiFileRevert',
  82                 'emailuser' => 'ApiEmailUser',
  83                 'watch' => 'ApiWatch',
  84                 'patrol' => 'ApiPatrol',
  85                 'import' => 'ApiImport',
  86                 'clearhasmsg' => 'ApiClearHasMsg',
  87                 'userrights' => 'ApiUserrights',
  88                 'options' => 'ApiOptions',
  89                 'imagerotate' => 'ApiImageRotate',
  90                 'revisiondelete' => 'ApiRevisionDelete',
  91                 'managetags' => 'ApiManageTags',
  92                 'tag' => 'ApiTag',
  93         );
  94
  95         /**
  96          * List of available formats: format name => format class
  97          */
  98         private static $Formats = array(
  99                 'json' => 'ApiFormatJson',
 100                 'jsonfm' => 'ApiFormatJson',
 101                 'php' => 'ApiFormatPhp',
 102                 'phpfm' => 'ApiFormatPhp',
 103                 'xml' => 'ApiFormatXml',
 104                 'xmlfm' => 'ApiFormatXml',
 105                 'rawfm' => 'ApiFormatJson',
 106                 'none' => 'ApiFormatNone',
 107         );
 108
 109         // @codingStandardsIgnoreStart String contenation on "msg" not allowed to break long line
 110         /**
 111          * List of user roles that are specifically relevant to the API.
 112          * array( 'right' => array ( 'msg'    => 'Some message with a $1',
 113          *                           'params' => array ( $someVarToSubst ) ),
 114          *                          );
 115          */
 116         private static $mRights = array(
 117                 'writeapi' => array(
 118                         'msg' => 'right-writeapi',
 119                         'params' => array()
 120                 ),
 121                 'apihighlimits' => array(
 122                         'msg' => 'api-help-right-apihighlimits',
 123                         'params' => array( ApiBase::LIMIT_SML2, ApiBase::LIMIT_BIG2 )
 124                 )
 125         );
 126         // @codingStandardsIgnoreEnd
 127
 128         /**
 129          * @var ApiFormatBase
 130          */
 131         private $mPrinter;
 132
 133         private $mModuleMgr, $mResult, $mErrorFormatter, $mContinuationManager;
 134         private $mAction;
 135         private $mEnableWrite;
 136         private $mInternalMode, $mSquidMaxage, $mModule;
 137
 138         private $mCacheMode = 'private';
 139         private $mCacheControl = array();
 140         private $mParamsUsed = array();
 141
 142         /**
 143          * Constructs an instance of ApiMain that utilizes the module and format specified by $request.
 144          *
 145          * @param IContextSource|WebRequest $context If this is an instance of
 146          *    FauxRequest, errors are thrown and no printing occurs
 147          * @param bool $enableWrite Should be set to true if the api may modify data
 148          */
 149         public function __construct( $context = null, $enableWrite = false ) {
 150                 if ( $context === null ) {
 151                         $context = RequestContext::getMain();
 152                 } elseif ( $context instanceof WebRequest ) {
 153                         // BC for pre-1.19
 154                         $request = $context;
 155                         $context = RequestContext::getMain();
 156                 }
 157                 // We set a derivative context so we can change stuff later
 158                 $this->setContext( new DerivativeContext( $context ) );
 159
 160                 if ( isset( $request ) ) {
 161                         $this->getContext()->setRequest( $request );
 162                 }
 163
 164                 $this->mInternalMode = ( $this->getRequest() instanceof FauxRequest );
 165
 166                 // Special handling for the main module: $parent === $this
 167                 parent::__construct( $this, $this->mInternalMode ? 'main_int' : 'main' );
 168
 169                 if ( !$this->mInternalMode ) {
 170                         // Impose module restrictions.
 171                         // If the current user cannot read,
 172                         // Remove all modules other than login
 173                         global $wgUser;
 174
 175                         if ( $this->lacksSameOriginSecurity() ) {
 176                                 // If we're in a mode that breaks the same-origin policy, strip
 177                                 // user credentials for security.
 178                                 wfDebug( "API: stripping user credentials when the same-origin policy is not applied\n" );
 179                                 $wgUser = new User();
 180                                 $this->getContext()->setUser( $wgUser );
 181                         }
 182                 }
 183
 184                 $uselang = $this->getParameter( 'uselang' );
 185                 if ( $uselang === 'user' ) {
 186                         // Assume the parent context is going to return the user language
 187                         // for uselang=user (see T85635).
 188                 } else {
 189                         if ( $uselang === 'content' ) {
 190                                 global $wgContLang;
 191                                 $uselang = $wgContLang->getCode();
 192                         }
 193                         $code = RequestContext::sanitizeLangCode( $uselang );
 194                         $this->getContext()->setLanguage( $code );
 195                         if ( !$this->mInternalMode ) {
 196                                 global $wgLang;
 197                                 $wgLang = $this->getContext()->getLanguage();
 198                                 RequestContext::getMain()->setLanguage( $wgLang );
 199                         }
 200                 }
 201
 202                 $config = $this->getConfig();
 203                 $this->mModuleMgr = new ApiModuleManager( $this );
 204                 $this->mModuleMgr->addModules( self::$Modules, 'action' );
 205                 $this->mModuleMgr->addModules( $config->get( 'APIModules' ), 'action' );
 206                 $this->mModuleMgr->addModules( self::$Formats, 'format' );
 207                 $this->mModuleMgr->addModules( $config->get( 'APIFormatModules' ), 'format' );
 208
 209                 Hooks::run( 'ApiMain::moduleManager', array( $this->mModuleMgr ) );
 210
 211                 $this->mResult = new ApiResult( $this->getConfig()->get( 'APIMaxResultSize' ) );
 212                 $this->mErrorFormatter = new ApiErrorFormatter_BackCompat( $this->mResult );
 213                 $this->mResult->setErrorFormatter( $this->mErrorFormatter );
 214                 $this->mResult->setMainForContinuation( $this );
 215                 $this->mContinuationManager = null;
 216                 $this->mEnableWrite = $enableWrite;
 217
 218                 $this->mSquidMaxage = -1; // flag for executeActionWithErrorHandling()
 219                 $this->mCommit = false;
 220         }
 221
 222         /**
 223          * Return true if the API was started by other PHP code using FauxRequest
 224          * @return bool
 225          */
 226         public function isInternalMode() {
 227                 return $this->mInternalMode;
 228         }
 229
 230         /**
 231          * Get the ApiResult object associated with current request
 232          *
 233          * @return ApiResult
 234          */
 235         public function getResult() {
 236                 return $this->mResult;
 237         }
 238
 239         /**
 240          * Get the ApiErrorFormatter object associated with current request
 241          * @return ApiErrorFormatter
 242          */
 243         public function getErrorFormatter() {
 244                 return $this->mErrorFormatter;
 245         }
 246
 247         /**
 248          * Get the continuation manager
 249          * @return ApiContinuationManager|null
 250          */
 251         public function getContinuationManager() {
 252                 return $this->mContinuationManager;
 253         }
 254
 255         /**
 256          * Set the continuation manager
 257          * @param ApiContinuationManager|null
 258          */
 259         public function setContinuationManager( $manager ) {
 260                 if ( $manager !== null ) {
 261                         if ( !$manager instanceof ApiContinuationManager ) {
 262                                 throw new InvalidArgumentException( __METHOD__ . ': Was passed ' .
 263                                         is_object( $manager ) ? get_class( $manager ) : gettype( $manager )
 264                                 );
 265                         }
 266                         if ( $this->mContinuationManager !== null ) {
 267                                 throw new UnexpectedValueException(
 268                                         __METHOD__ . ': tried to set manager from ' . $manager->getSource() .
 269                                         ' when a manager is already set from ' . $this->mContinuationManager->getSource()
 270                                 );
 271                         }
 272                 }
 273                 $this->mContinuationManager = $manager;
 274         }
 275
 276         /**
 277          * Get the API module object. Only works after executeAction()
 278          *
 279          * @return ApiBase
 280          */
 281         public function getModule() {
 282                 return $this->mModule;
 283         }
 284
 285         /**
 286          * Get the result formatter object. Only works after setupExecuteAction()
 287          *
 288          * @return ApiFormatBase
 289          */
 290         public function getPrinter() {
 291                 return $this->mPrinter;
 292         }
 293
 294         /**
 295          * Set how long the response should be cached.
 296          *
 297          * @param int $maxage
 298          */
 299         public function setCacheMaxAge( $maxage ) {
 300                 $this->setCacheControl( array(
 301                         'max-age' => $maxage,
 302                         's-maxage' => $maxage
 303                 ) );
 304         }
 305
 306         /**
 307          * Set the type of caching headers which will be sent.
 308          *
 309          * @param string $mode One of:
 310          *    - 'public':     Cache this object in public caches, if the maxage or smaxage
 311          *         parameter is set, or if setCacheMaxAge() was called. If a maximum age is
 312          *         not provided by any of these means, the object will be private.
 313          *    - 'private':    Cache this object only in private client-side caches.
 314          *    - 'anon-public-user-private': Make this object cacheable for logged-out
 315          *         users, but private for logged-in users. IMPORTANT: If this is set, it must be
 316          *         set consistently for a given URL, it cannot be set differently depending on
 317          *         things like the contents of the database, or whether the user is logged in.
 318          *
 319          *  If the wiki does not allow anonymous users to read it, the mode set here
 320          *  will be ignored, and private caching headers will always be sent. In other words,
 321          *  the "public" mode is equivalent to saying that the data sent is as public as a page
 322          *  view.
 323          *
 324          *  For user-dependent data, the private mode should generally be used. The
 325          *  anon-public-user-private mode should only be used where there is a particularly
 326          *  good performance reason for caching the anonymous response, but where the
 327          *  response to logged-in users may differ, or may contain private data.
 328          *
 329          *  If this function is never called, then the default will be the private mode.
 330          */
 331         public function setCacheMode( $mode ) {
 332                 if ( !in_array( $mode, array( 'private', 'public', 'anon-public-user-private' ) ) ) {
 333                         wfDebug( __METHOD__ . ": unrecognised cache mode \"$mode\"\n" );
 334
 335                         // Ignore for forwards-compatibility
 336                         return;
 337                 }
 338
 339                 if ( !User::isEveryoneAllowed( 'read' ) ) {
 340                         // Private wiki, only private headers
 341                         if ( $mode !== 'private' ) {
 342                                 wfDebug( __METHOD__ . ": ignoring request for $mode cache mode, private wiki\n" );
 343
 344                                 return;
 345                         }
 346                 }
 347
 348                 if ( $mode === 'public' && $this->getParameter( 'uselang' ) === 'user' ) {
 349                         // User language is used for i18n, so we don't want to publicly
 350                         // cache. Anons are ok, because if they have non-default language
 351                         // then there's an appropriate Vary header set by whatever set
 352                         // their non-default language.
 353                         wfDebug( __METHOD__ . ": downgrading cache mode 'public' to " .
 354                                 "'anon-public-user-private' due to uselang=user\n" );
 355                         $mode = 'anon-public-user-private';
 356                 }
 357
 358                 wfDebug( __METHOD__ . ": setting cache mode $mode\n" );
 359                 $this->mCacheMode = $mode;
 360         }
 361
 362         /**
 363          * Set directives (key/value pairs) for the Cache-Control header.
 364          * Boolean values will be formatted as such, by including or omitting
 365          * without an equals sign.
 366          *
 367          * Cache control values set here will only be used if the cache mode is not
 368          * private, see setCacheMode().
 369          *
 370          * @param array $directives
 371          */
 372         public function setCacheControl( $directives ) {
 373                 $this->mCacheControl = $directives + $this->mCacheControl;
 374         }
 375
 376         /**
 377          * Create an instance of an output formatter by its name
 378          *
 379          * @param string $format
 380          *
 381          * @return ApiFormatBase
 382          */
 383         public function createPrinterByName( $format ) {
 384                 $printer = $this->mModuleMgr->getModule( $format, 'format' );
 385                 if ( $printer === null ) {
 386                         $this->dieUsage( "Unrecognized format: {$format}", 'unknown_format' );
 387                 }
 388
 389                 return $printer;
 390         }
 391
 392         /**
 393          * Execute api request. Any errors will be handled if the API was called by the remote client.
 394          */
 395         public function execute() {
 396                 if ( $this->mInternalMode ) {
 397                         $this->executeAction();
 398                 } else {
 399                         $this->executeActionWithErrorHandling();
 400                 }
 401         }
 402
 403         /**
 404          * Execute an action, and in case of an error, erase whatever partial results
 405          * have been accumulated, and replace it with an error message and a help screen.
 406          */
 407         protected function executeActionWithErrorHandling() {
 408                 // Verify the CORS header before executing the action
 409                 if ( !$this->handleCORS() ) {
 410                         // handleCORS() has sent a 403, abort
 411                         return;
 412                 }
 413
 414                 // Exit here if the request method was OPTIONS
 415                 // (assume there will be a followup GET or POST)
 416                 if ( $this->getRequest()->getMethod() === 'OPTIONS' ) {
 417                         return;
 418                 }
 419
 420                 // In case an error occurs during data output,
 421                 // clear the output buffer and print just the error information
 422                 $obLevel = ob_get_level();
 423                 ob_start();
 424
 425                 $t = microtime( true );
 426                 try {
 427                         $this->executeAction();
 428                         $isError = false;
 429                 } catch ( Exception $e ) {
 430                         $this->handleException( $e );
 431                         $isError = true;
 432                 }
 433
 434                 // Log the request whether or not there was an error
 435                 $this->logRequest( microtime( true ) - $t );
 436
 437                 // Commit DBs and send any related cookies and headers
 438                 MediaWiki::preOutputCommit( $this->getContext() );
 439
 440                 // Send cache headers after any code which might generate an error, to
 441                 // avoid sending public cache headers for errors.
 442                 $this->sendCacheHeaders( $isError );
 443
 444                 // Executing the action might have already messed with the output
 445                 // buffers.
 446                 while ( ob_get_level() > $obLevel ) {
 447                         ob_end_flush();
 448                 }
 449         }
 450
 451         /**
 452          * Handle an exception as an API response
 453          *
 454          * @since 1.23
 455          * @param Exception $e
 456          */
 457         protected function handleException( Exception $e ) {
 458                 // Bug 63145: Rollback any open database transactions
 459                 if ( !( $e instanceof UsageException ) ) {
 460                         // UsageExceptions are intentional, so don't rollback if that's the case
 461                         try {
 462                                 MWExceptionHandler::rollbackMasterChangesAndLog( $e );
 463                         } catch ( DBError $e2 ) {
 464                                 // Rollback threw an exception too. Log it, but don't interrupt
 465                                 // our regularly scheduled exception handling.
 466                                 MWExceptionHandler::logException( $e2 );
 467                         }
 468                 }
 469
 470                 // Allow extra cleanup and logging
 471                 Hooks::run( 'ApiMain::onException', array( $this, $e ) );
 472
 473                 // Log it
 474                 if ( !( $e instanceof UsageException ) ) {
 475                         MWExceptionHandler::logException( $e );
 476                 }
 477
 478                 // Handle any kind of exception by outputting properly formatted error message.
 479                 // If this fails, an unhandled exception should be thrown so that global error
 480                 // handler will process and log it.
 481
 482                 $errCode = $this->substituteResultWithError( $e );
 483
 484                 // Error results should not be cached
 485                 $this->setCacheMode( 'private' );
 486
 487                 $response = $this->getRequest()->response();
 488                 $headerStr = 'MediaWiki-API-Error: ' . $errCode;
 489                 if ( $e->getCode() === 0 ) {
 490                         $response->header( $headerStr );
 491                 } else {
 492                         $response->header( $headerStr, true, $e->getCode() );
 493                 }
 494
 495                 // Reset and print just the error message
 496                 ob_clean();
 497
 498                 // Printer may not be initialized if the extractRequestParams() fails for the main module
 499                 $this->createErrorPrinter();
 500
 501                 try {
 502                         $this->printResult( true );
 503                 } catch ( UsageException $ex ) {
 504                         // The error printer itself is failing. Try suppressing its request
 505                         // parameters and redo.
 506                         $this->setWarning(
 507                                 'Error printer failed (will retry without params): ' . $ex->getMessage()
 508                         );
 509                         $this->mPrinter = null;
 510                         $this->createErrorPrinter();
 511                         $this->mPrinter->forceDefaultParams();
 512                         $this->printResult( true );
 513                 }
 514         }
 515
 516         /**
 517          * Handle an exception from the ApiBeforeMain hook.
 518          *
 519          * This tries to print the exception as an API response, to be more
 520          * friendly to clients. If it fails, it will rethrow the exception.
 521          *
 522          * @since 1.23
 523          * @param Exception $e
 524          * @throws Exception
 525          */
 526         public static function handleApiBeforeMainException( Exception $e ) {
 527                 ob_start();
 528
 529                 try {
 530                         $main = new self( RequestContext::getMain(), false );
 531                         $main->handleException( $e );
 532                 } catch ( Exception $e2 ) {
 533                         // Nope, even that didn't work. Punt.
 534                         throw $e;
 535                 }
 536
 537                 // Log the request and reset cache headers
 538                 $main->logRequest( 0 );
 539                 $main->sendCacheHeaders( true );
 540
 541                 ob_end_flush();
 542         }
 543
 544         /**
 545          * Check the &origin= query parameter against the Origin: HTTP header and respond appropriately.
 546          *
 547          * If no origin parameter is present, nothing happens.
 548          * If an origin parameter is present but doesn't match the Origin header, a 403 status code
 549          * is set and false is returned.
 550          * If the parameter and the header do match, the header is checked against $wgCrossSiteAJAXdomains
 551          * and $wgCrossSiteAJAXdomainExceptions, and if the origin qualifies, the appropriate CORS
 552          * headers are set.
 553          * http://www.w3.org/TR/cors/#resource-requests
 554          * http://www.w3.org/TR/cors/#resource-preflight-requests
 555          *
 556          * @return bool False if the caller should abort (403 case), true otherwise (all other cases)
 557          */
 558         protected function handleCORS() {
 559                 $originParam = $this->getParameter( 'origin' ); // defaults to null
 560                 if ( $originParam === null ) {
 561                         // No origin parameter, nothing to do
 562                         return true;
 563                 }
 564
 565                 $request = $this->getRequest();
 566                 $response = $request->response();
 567
 568                 // Origin: header is a space-separated list of origins, check all of them
 569                 $originHeader = $request->getHeader( 'Origin' );
 570                 if ( $originHeader === false ) {
 571                         $origins = array();
 572                 } else {
 573                         $originHeader = trim( $originHeader );
 574                         $origins = preg_split( '/\s+/', $originHeader );
 575                 }
 576
 577                 if ( !in_array( $originParam, $origins ) ) {
 578                         // origin parameter set but incorrect
 579                         // Send a 403 response
 580                         $response->statusHeader( 403 );
 581                         $response->header( 'Cache-Control: no-cache' );
 582                         echo "'origin' parameter does not match Origin header\n";
 583
 584                         return false;
 585                 }
 586
 587                 $config = $this->getConfig();
 588                 $matchOrigin = count( $origins ) === 1 && self::matchOrigin(
 589                         $originParam,
 590                         $config->get( 'CrossSiteAJAXdomains' ),
 591                         $config->get( 'CrossSiteAJAXdomainExceptions' )
 592                 );
 593
 594                 if ( $matchOrigin ) {
 595                         $requestedMethod = $request->getHeader( 'Access-Control-Request-Method' );
 596                         $preflight = $request->getMethod() === 'OPTIONS' && $requestedMethod !== false;
 597                         if ( $preflight ) {
 598                                 // This is a CORS preflight request
 599                                 if ( $requestedMethod !== 'POST' && $requestedMethod !== 'GET' ) {
 600                                         // If method is not a case-sensitive match, do not set any additional headers and terminate.
 601                                         return true;
 602                                 }
 603                                 // We allow the actual request to send the following headers
 604                                 $requestedHeaders = $request->getHeader( 'Access-Control-Request-Headers' );
 605                                 if ( $requestedHeaders !== false ) {
 606                                         if ( !self::matchRequestedHeaders( $requestedHeaders ) ) {
 607                                                 return true;
 608                                         }
 609                                         $response->header( 'Access-Control-Allow-Headers: ' . $requestedHeaders );
 610                                 }
 611
 612                                 // We only allow the actual request to be GET or POST
 613                                 $response->header( 'Access-Control-Allow-Methods: POST, GET' );
 614                         }
 615
 616                         $response->header( "Access-Control-Allow-Origin: $originHeader" );
 617                         $response->header( 'Access-Control-Allow-Credentials: true' );
 618                         // http://www.w3.org/TR/resource-timing/#timing-allow-origin
 619                         $response->header( "Timing-Allow-Origin: $originHeader" );
 620
 621                         if ( !$preflight ) {
 622                                 $response->header(
 623                                         'Access-Control-Expose-Headers: MediaWiki-API-Error, Retry-After, X-Database-Lag'
 624                                 );
 625                         }
 626                 }
 627
 628                 $this->getOutput()->addVaryHeader( 'Origin' );
 629                 return true;
 630         }
 631
 632         /**
 633          * Attempt to match an Origin header against a set of rules and a set of exceptions
 634          * @param string $value Origin header
 635          * @param array $rules Set of wildcard rules
 636          * @param array $exceptions Set of wildcard rules
 637          * @return bool True if $value matches a rule in $rules and doesn't match
 638          *    any rules in $exceptions, false otherwise
 639          */
 640         protected static function matchOrigin( $value, $rules, $exceptions ) {
 641                 foreach ( $rules as $rule ) {
 642                         if ( preg_match( self::wildcardToRegex( $rule ), $value ) ) {
 643                                 // Rule matches, check exceptions
 644                                 foreach ( $exceptions as $exc ) {
 645                                         if ( preg_match( self::wildcardToRegex( $exc ), $value ) ) {
 646                                                 return false;
 647                                         }
 648                                 }
 649
 650                                 return true;
 651                         }
 652                 }
 653
 654                 return false;
 655         }
 656
 657         /**
 658          * Attempt to validate the value of Access-Control-Request-Headers against a list
 659          * of headers that we allow the follow up request to send.
 660          *
 661          * @param string $requestedHeaders Comma seperated list of HTTP headers
 662          * @return bool True if all requested headers are in the list of allowed headers
 663          */
 664         protected static function matchRequestedHeaders( $requestedHeaders ) {
 665                 if ( trim( $requestedHeaders ) === '' ) {
 666                         return true;
 667                 }
 668                 $requestedHeaders = explode( ',', $requestedHeaders );
 669                 $allowedAuthorHeaders = array_flip( array(
 670                         /* simple headers (see spec) */
 671                         'accept',
 672                         'accept-language',
 673                         'content-language',
 674                         'content-type',
 675                         /* non-authorable headers in XHR, which are however requested by some UAs */
 676                         'accept-encoding',
 677                         'dnt',
 678                         'origin',
 679                         /* MediaWiki whitelist */
 680                         'api-user-agent',
 681                 ) );
 682                 foreach ( $requestedHeaders as $rHeader ) {
 683                         $rHeader = strtolower( trim( $rHeader ) );
 684                         if ( !isset( $allowedAuthorHeaders[$rHeader] ) ) {
 685                                 wfDebugLog( 'api', 'CORS preflight failed on requested header: ' . $rHeader );
 686                                 return false;
 687                         }
 688                 }
 689                 return true;
 690         }
 691
 692         /**
 693          * Helper function to convert wildcard string into a regex
 694          * '*' => '.*?'
 695          * '?' => '.'
 696          *
 697          * @param string $wildcard String with wildcards
 698          * @return string Regular expression
 699          */
 700         protected static function wildcardToRegex( $wildcard ) {
 701                 $wildcard = preg_quote( $wildcard, '/' );
 702                 $wildcard = str_replace(
 703                         array( '\*', '\?' ),
 704                         array( '.*?', '.' ),
 705                         $wildcard
 706                 );
 707
 708                 return "/^https?:\/\/$wildcard$/";
 709         }
 710
 711         /**
 712          * Send caching headers
 713          * @param boolean $isError Whether an error response is being output
 714          * @since 1.26 added $isError parameter
 715          */
 716         protected function sendCacheHeaders( $isError ) {
 717                 $response = $this->getRequest()->response();
 718                 $out = $this->getOutput();
 719
 720                 $config = $this->getConfig();
 721
 722                 if ( $config->get( 'VaryOnXFP' ) ) {
 723                         $out->addVaryHeader( 'X-Forwarded-Proto' );
 724                 }
 725
 726                 if ( !$isError && $this->mModule &&
 727                         ( $this->getRequest()->getMethod() === 'GET' || $this->getRequest()->getMethod() === 'HEAD' )
 728                 ) {
 729                         $etag = $this->mModule->getConditionalRequestData( 'etag' );
 730                         if ( $etag !== null ) {
 731                                 $response->header( "ETag: $etag" );
 732                         }
 733                         $lastMod = $this->mModule->getConditionalRequestData( 'last-modified' );
 734                         if ( $lastMod !== null ) {
 735                                 $response->header( 'Last-Modified: ' . wfTimestamp( TS_RFC2822, $lastMod ) );
 736                         }
 737                 }
 738
 739                 // The logic should be:
 740                 // $this->mCacheControl['max-age'] is set?
 741                 //    Use it, the module knows better than our guess.
 742                 // !$this->mModule || $this->mModule->isWriteMode(), and mCacheMode is private?
 743                 //    Use 0 because we can guess caching is probably the wrong thing to do.
 744                 // Use $this->getParameter( 'maxage' ), which already defaults to 0.
 745                 $maxage = 0;
 746                 if ( isset( $this->mCacheControl['max-age'] ) ) {
 747                         $maxage = $this->mCacheControl['max-age'];
 748                 } elseif ( ( $this->mModule && !$this->mModule->isWriteMode() ) ||
 749                         $this->mCacheMode !== 'private'
 750                 ) {
 751                         $maxage = $this->getParameter( 'maxage' );
 752                 }
 753                 $privateCache = 'private, must-revalidate, max-age=' . $maxage;
 754
 755                 if ( $this->mCacheMode == 'private' ) {
 756                         $response->header( "Cache-Control: $privateCache" );
 757                         return;
 758                 }
 759
 760                 $useKeyHeader = $config->get( 'UseKeyHeader' );
 761                 if ( $this->mCacheMode == 'anon-public-user-private' ) {
 762                         $out->addVaryHeader( 'Cookie' );
 763                         $response->header( $out->getVaryHeader() );
 764                         if ( $useKeyHeader ) {
 765                                 $response->header( $out->getKeyHeader() );
 766                                 if ( $out->haveCacheVaryCookies() ) {
 767                                         // Logged in, mark this request private
 768                                         $response->header( "Cache-Control: $privateCache" );
 769                                         return;
 770                                 }
 771                                 // Logged out, send normal public headers below
 772                         } elseif ( session_id() != '' ) {
 773                                 // Logged in or otherwise has session (e.g. anonymous users who have edited)
 774                                 // Mark request private
 775                                 $response->header( "Cache-Control: $privateCache" );
 776
 777                                 return;
 778                         } // else no Key and anonymous, send public headers below
 779                 }
 780
 781                 // Send public headers
 782                 $response->header( $out->getVaryHeader() );
 783                 if ( $useKeyHeader ) {
 784                         $response->header( $out->getKeyHeader() );
 785                 }
 786
 787                 // If nobody called setCacheMaxAge(), use the (s)maxage parameters
 788                 if ( !isset( $this->mCacheControl['s-maxage'] ) ) {
 789                         $this->mCacheControl['s-maxage'] = $this->getParameter( 'smaxage' );
 790                 }
 791                 if ( !isset( $this->mCacheControl['max-age'] ) ) {
 792                         $this->mCacheControl['max-age'] = $this->getParameter( 'maxage' );
 793                 }
 794
 795                 if ( !$this->mCacheControl['s-maxage'] && !$this->mCacheControl['max-age'] ) {
 796                         // Public cache not requested
 797                         // Sending a Vary header in this case is harmless, and protects us
 798                         // against conditional calls of setCacheMaxAge().
 799                         $response->header( "Cache-Control: $privateCache" );
 800
 801                         return;
 802                 }
 803
 804                 $this->mCacheControl['public'] = true;
 805
 806                 // Send an Expires header
 807                 $maxAge = min( $this->mCacheControl['s-maxage'], $this->mCacheControl['max-age'] );
 808                 $expiryUnixTime = ( $maxAge == 0 ? 1 : time() + $maxAge );
 809                 $response->header( 'Expires: ' . wfTimestamp( TS_RFC2822, $expiryUnixTime ) );
 810
 811                 // Construct the Cache-Control header
 812                 $ccHeader = '';
 813                 $separator = '';
 814                 foreach ( $this->mCacheControl as $name => $value ) {
 815                         if ( is_bool( $value ) ) {
 816                                 if ( $value ) {
 817                                         $ccHeader .= $separator . $name;
 818                                         $separator = ', ';
 819                                 }
 820                         } else {
 821                                 $ccHeader .= $separator . "$name=$value";
 822                                 $separator = ', ';
 823                         }
 824                 }
 825
 826                 $response->header( "Cache-Control: $ccHeader" );
 827         }
 828
 829         /**
 830          * Create the printer for error output
 831          */
 832         private function createErrorPrinter() {
 833                 if ( !isset( $this->mPrinter ) ) {
 834                         $value = $this->getRequest()->getVal( 'format', self::API_DEFAULT_FORMAT );
 835                         if ( !$this->mModuleMgr->isDefined( $value, 'format' ) ) {
 836                                 $value = self::API_DEFAULT_FORMAT;
 837                         }
 838                         $this->mPrinter = $this->createPrinterByName( $value );
 839                 }
 840
 841                 // Printer may not be able to handle errors. This is particularly
 842                 // likely if the module returns something for getCustomPrinter().
 843                 if ( !$this->mPrinter->canPrintErrors() ) {
 844                         $this->mPrinter = $this->createPrinterByName( self::API_DEFAULT_FORMAT );
 845                 }
 846         }
 847
 848         /**
 849          * Replace the result data with the information about an exception.
 850          * Returns the error code
 851          * @param Exception $e
 852          * @return string
 853          */
 854         protected function substituteResultWithError( $e ) {
 855                 $result = $this->getResult();
 856                 $config = $this->getConfig();
 857
 858                 if ( $e instanceof UsageException ) {
 859                         // User entered incorrect parameters - generate error response
 860                         $errMessage = $e->getMessageArray();
 861                         $link = wfExpandUrl( wfScript( 'api' ) );
 862                         ApiResult::setContentValue( $errMessage, 'docref', "See $link for API usage" );
 863                 } else {
 864                         // Something is seriously wrong
 865                         if ( ( $e instanceof DBQueryError ) && !$config->get( 'ShowSQLErrors' ) ) {
 866                                 $info = 'Database query error';
 867                         } else {
 868                                 $info = "Exception Caught: {$e->getMessage()}";
 869                         }
 870
 871                         $errMessage = array(
 872                                 'code' => 'internal_api_error_' . get_class( $e ),
 873                                 'info' => '[' . MWExceptionHandler::getLogId( $e ) . '] ' . $info,
 874                         );
 875                         if ( $config->get( 'ShowExceptionDetails' ) ) {
 876                                 ApiResult::setContentValue(
 877                                         $errMessage,
 878                                         'trace',
 879                                         MWExceptionHandler::getRedactedTraceAsString( $e )
 880                                 );
 881                         }
 882                 }
 883
 884                 // Remember all the warnings to re-add them later
 885                 $warnings = $result->getResultData( array( 'warnings' ) );
 886
 887                 $result->reset();
 888                 // Re-add the id
 889                 $requestid = $this->getParameter( 'requestid' );
 890                 if ( !is_null( $requestid ) ) {
 891                         $result->addValue( null, 'requestid', $requestid, ApiResult::NO_SIZE_CHECK );
 892                 }
 893                 if ( $config->get( 'ShowHostnames' ) ) {
 894                         // servedby is especially useful when debugging errors
 895                         $result->addValue( null, 'servedby', wfHostname(), ApiResult::NO_SIZE_CHECK );
 896                 }
 897                 if ( $warnings !== null ) {
 898                         $result->addValue( null, 'warnings', $warnings, ApiResult::NO_SIZE_CHECK );
 899                 }
 900
 901                 $result->addValue( null, 'error', $errMessage, ApiResult::NO_SIZE_CHECK );
 902
 903                 return $errMessage['code'];
 904         }
 905
 906         /**
 907          * Set up for the execution.
 908          * @return array
 909          */
 910         protected function setupExecuteAction() {
 911                 // First add the id to the top element
 912                 $result = $this->getResult();
 913                 $requestid = $this->getParameter( 'requestid' );
 914                 if ( !is_null( $requestid ) ) {
 915                         $result->addValue( null, 'requestid', $requestid );
 916                 }
 917
 918                 if ( $this->getConfig()->get( 'ShowHostnames' ) ) {
 919                         $servedby = $this->getParameter( 'servedby' );
 920                         if ( $servedby ) {
 921                                 $result->addValue( null, 'servedby', wfHostName() );
 922                         }
 923                 }
 924
 925                 if ( $this->getParameter( 'curtimestamp' ) ) {
 926                         $result->addValue( null, 'curtimestamp', wfTimestamp( TS_ISO_8601, time() ),
 927                                 ApiResult::NO_SIZE_CHECK );
 928                 }
 929
 930                 $params = $this->extractRequestParams();
 931
 932                 $this->mAction = $params['action'];
 933
 934                 if ( !is_string( $this->mAction ) ) {
 935                         $this->dieUsage( 'The API requires a valid action parameter', 'unknown_action' );
 936                 }
 937
 938                 return $params;
 939         }
 940
 941         /**
 942          * Set up the module for response
 943          * @return ApiBase The module that will handle this action
 944          * @throws MWException
 945          * @throws UsageException
 946          */
 947         protected function setupModule() {
 948                 // Instantiate the module requested by the user
 949                 $module = $this->mModuleMgr->getModule( $this->mAction, 'action' );
 950                 if ( $module === null ) {
 951                         $this->dieUsage( 'The API requires a valid action parameter', 'unknown_action' );
 952                 }
 953                 $moduleParams = $module->extractRequestParams();
 954
 955                 // Check token, if necessary
 956                 if ( $module->needsToken() === true ) {
 957                         throw new MWException(
 958                                 "Module '{$module->getModuleName()}' must be updated for the new token handling. " .
 959                                 "See documentation for ApiBase::needsToken for details."
 960                         );
 961                 }
 962                 if ( $module->needsToken() ) {
 963                         if ( !$module->mustBePosted() ) {
 964                                 throw new MWException(
 965                                         "Module '{$module->getModuleName()}' must require POST to use tokens."
 966                                 );
 967                         }
 968
 969                         if ( !isset( $moduleParams['token'] ) ) {
 970                                 $this->dieUsageMsg( array( 'missingparam', 'token' ) );
 971                         }
 972
 973                         if ( !$this->getConfig()->get( 'DebugAPI' ) &&
 974                                 array_key_exists(
 975                                         $module->encodeParamName( 'token' ),
 976                                         $this->getRequest()->getQueryValues()
 977                                 )
 978                         ) {
 979                                 $this->dieUsage(
 980                                         "The '{$module->encodeParamName( 'token' )}' parameter was " .
 981                                                 'found in the query string, but must be in the POST body',
 982                                         'mustposttoken'
 983                                 );
 984                         }
 985
 986                         if ( !$module->validateToken( $moduleParams['token'], $moduleParams ) ) {
 987                                 $this->dieUsageMsg( 'sessionfailure' );
 988                         }
 989                 }
 990
 991                 return $module;
 992         }
 993
 994         /**
 995          * Check the max lag if necessary
 996          * @param ApiBase $module Api module being used
 997          * @param array $params Array an array containing the request parameters.
 998          * @return bool True on success, false should exit immediately
 999          */
1000         protected function checkMaxLag( $module, $params ) {
1001                 if ( $module->shouldCheckMaxlag() && isset( $params['maxlag'] ) ) {
1002                         $maxLag = $params['maxlag'];
1003                         list( $host, $lag ) = wfGetLB()->getMaxLag();
1004                         if ( $lag > $maxLag ) {
1005                                 $response = $this->getRequest()->response();
1006
1007                                 $response->header( 'Retry-After: ' . max( intval( $maxLag ), 5 ) );
1008                                 $response->header( 'X-Database-Lag: ' . intval( $lag ) );
1009
1010                                 if ( $this->getConfig()->get( 'ShowHostnames' ) ) {
1011                                         $this->dieUsage( "Waiting for $host: $lag seconds lagged", 'maxlag' );
1012                                 }
1013
1014                                 $this->dieUsage( "Waiting for a database server: $lag seconds lagged", 'maxlag' );
1015                         }
1016                 }
1017
1018                 return true;
1019         }
1020
1021         /**
1022          * Check selected RFC 7232 precondition headers
1023          *
1024          * RFC 7232 envisions a particular model where you send your request to "a
1025          * resource", and for write requests that you can read "the resource" by
1026          * changing the method to GET. When the API receives a GET request, it
1027          * works out even though "the resource" from RFC 7232's perspective might
1028          * be many resources from MediaWiki's perspective. But it totally fails for
1029          * a POST, since what HTTP sees as "the resource" is probably just
1030          * "/api.php" with all the interesting bits in the body.
1031          *
1032          * Therefore, we only support RFC 7232 precondition headers for GET (and
1033          * HEAD). That means we don't need to bother with If-Match and
1034          * If-Unmodified-Since since they only apply to modification requests.
1035          *
1036          * And since we don't support Range, If-Range is ignored too.
1037          *
1038          * @since 1.26
1039          * @param ApiBase $module Api module being used
1040          * @return bool True on success, false should exit immediately
1041          */
1042         protected function checkConditionalRequestHeaders( $module ) {
1043                 if ( $this->mInternalMode ) {
1044                         // No headers to check in internal mode
1045                         return true;
1046                 }
1047
1048                 if ( $this->getRequest()->getMethod() !== 'GET' && $this->getRequest()->getMethod() !== 'HEAD' ) {
1049                         // Don't check POSTs
1050                         return true;
1051                 }
1052
1053                 $return304 = false;
1054
1055                 $ifNoneMatch = array_diff(
1056                         $this->getRequest()->getHeader( 'If-None-Match', WebRequest::GETHEADER_LIST ) ?: array(),
1057                         array( '' )
1058                 );
1059                 if ( $ifNoneMatch ) {
1060                         if ( $ifNoneMatch === array( '*' ) ) {
1061                                 // API responses always "exist"
1062                                 $etag = '*';
1063                         } else {
1064                                 $etag = $module->getConditionalRequestData( 'etag' );
1065                         }
1066                 }
1067                 if ( $ifNoneMatch && $etag !== null ) {
1068                         $test = substr( $etag, 0, 2 ) === 'W/' ? substr( $etag, 2 ) : $etag;
1069                         $match = array_map( function ( $s ) {
1070                                 return substr( $s, 0, 2 ) === 'W/' ? substr( $s, 2 ) : $s;
1071                         }, $ifNoneMatch );
1072                         $return304 = in_array( $test, $match, true );
1073                 } else {
1074                         $value = trim( $this->getRequest()->getHeader( 'If-Modified-Since' ) );
1075
1076                         // Some old browsers sends sizes after the date, like this:
1077                         //  Wed, 20 Aug 2003 06:51:19 GMT; length=5202
1078                         // Ignore that.
1079                         $i = strpos( $value, ';' );
1080                         if ( $i !== false ) {
1081                                 $value = trim( substr( $value, 0, $i ) );
1082                         }
1083
1084                         if ( $value !== '' ) {
1085                                 try {
1086                                         $ts = new MWTimestamp( $value );
1087                                         if (
1088                                                 // RFC 7231 IMF-fixdate
1089                                                 $ts->getTimestamp( TS_RFC2822 ) === $value ||
1090                                                 // RFC 850
1091                                                 $ts->format( 'l, d-M-y H:i:s' ) . ' GMT' === $value ||
1092                                                 // asctime (with and without space-padded day)
1093                                                 $ts->format( 'D M j H:i:s Y' ) === $value ||
1094                                                 $ts->format( 'D M  j H:i:s Y' ) === $value
1095                                         ) {
1096                                                 $lastMod = $module->getConditionalRequestData( 'last-modified' );
1097                                                 if ( $lastMod !== null ) {
1098                                                         // Mix in some MediaWiki modification times
1099                                                         $modifiedTimes = array(
1100                                                                 'page' => $lastMod,
1101                                                                 'user' => $this->getUser()->getTouched(),
1102                                                                 'epoch' => $this->getConfig()->get( 'CacheEpoch' ),
1103                                                         );
1104                                                         if ( $this->getConfig()->get( 'UseSquid' ) ) {
1105                                                                 // T46570: the core page itself may not change, but resources might
1106                                                                 $modifiedTimes['sepoch'] = wfTimestamp(
1107                                                                         TS_MW, time() - $this->getConfig()->get( 'SquidMaxage' )
1108                                                                 );
1109                                                         }
1110                                                         Hooks::run( 'OutputPageCheckLastModified', array( &$modifiedTimes ) );
1111                                                         $lastMod = max( $modifiedTimes );
1112                                                         $return304 = wfTimestamp( TS_MW, $lastMod ) <= $ts->getTimestamp( TS_MW );
1113                                                 }
1114                                         }
1115                                 } catch ( TimestampException $e ) {
1116                                         // Invalid timestamp, ignore it
1117                                 }
1118                         }
1119                 }
1120
1121                 if ( $return304 ) {
1122                         $this->getRequest()->response()->statusHeader( 304 );
1123
1124                         // Avoid outputting the compressed representation of a zero-length body
1125                         MediaWiki\suppressWarnings();
1126                         ini_set( 'zlib.output_compression', 0 );
1127                         MediaWiki\restoreWarnings();
1128                         wfClearOutputBuffers();
1129
1130                         return false;
1131                 }
1132
1133                 return true;
1134         }
1135
1136         /**
1137          * Check for sufficient permissions to execute
1138          * @param ApiBase $module An Api module
1139          */
1140         protected function checkExecutePermissions( $module ) {
1141                 $user = $this->getUser();
1142                 if ( $module->isReadMode() && !User::isEveryoneAllowed( 'read' ) &&
1143                         !$user->isAllowed( 'read' )
1144                 ) {
1145                         $this->dieUsageMsg( 'readrequired' );
1146                 }
1147
1148                 if ( $module->isWriteMode() ) {
1149                         if ( !$this->mEnableWrite ) {
1150                                 $this->dieUsageMsg( 'writedisabled' );
1151                         } elseif ( !$user->isAllowed( 'writeapi' ) ) {
1152                                 $this->dieUsageMsg( 'writerequired' );
1153                         } elseif ( $this->getRequest()->getHeader( 'Promise-Non-Write-API-Action' ) ) {
1154                                 $this->dieUsage(
1155                                         "Promise-Non-Write-API-Action HTTP header cannot be sent to write API modules",
1156                                         'promised-nonwrite-api'
1157                                 );
1158                         }
1159
1160                         $this->checkReadOnly( $module );
1161                 }
1162
1163                 // Allow extensions to stop execution for arbitrary reasons.
1164                 $message = false;
1165                 if ( !Hooks::run( 'ApiCheckCanExecute', array( $module, $user, &$message ) ) ) {
1166                         $this->dieUsageMsg( $message );
1167                 }
1168         }
1169
1170         /**
1171          * Check if the DB is read-only for this user
1172          * @param ApiBase $module An Api module
1173          */
1174         protected function checkReadOnly( $module ) {
1175                 if ( wfReadOnly() ) {
1176                         $this->dieReadOnly();
1177                 }
1178
1179                 if ( $module->isWriteMode()
1180                         && in_array( 'bot', $this->getUser()->getGroups() )
1181                         && wfGetLB()->getServerCount() > 1
1182                 ) {
1183                         // Figure out how many servers have passed the lag threshold
1184                         $numLagged = 0;
1185                         $lagLimit = $this->getConfig()->get( 'APIMaxLagThreshold' );
1186                         foreach ( wfGetLB()->getLagTimes() as $lag ) {
1187                                 if ( $lag > $lagLimit ) {
1188                                         ++$numLagged;
1189                                 }
1190                         }
1191                         // If a majority of slaves are too lagged then disallow writes
1192                         $slaveCount = wfGetLB()->getServerCount() - 1;
1193                         if ( $numLagged >= ceil( $slaveCount / 2 ) ) {
1194                                 $parsed = $this->parseMsg( array( 'readonlytext' ) );
1195                                 $this->dieUsage(
1196                                         $parsed['info'],
1197                                         $parsed['code'],
1198                                         /* http error */
1199                                         0,
1200                                         array( 'readonlyreason' => "Waiting for $numLagged lagged database(s)" )
1201                                 );
1202                         }
1203                 }
1204         }
1205
1206         /**
1207          * Check asserts of the user's rights
1208          * @param array $params
1209          */
1210         protected function checkAsserts( $params ) {
1211                 if ( isset( $params['assert'] ) ) {
1212                         $user = $this->getUser();
1213                         switch ( $params['assert'] ) {
1214                                 case 'user':
1215                                         if ( $user->isAnon() ) {
1216                                                 $this->dieUsage( 'Assertion that the user is logged in failed', 'assertuserfailed' );
1217                                         }
1218                                         break;
1219                                 case 'bot':
1220                                         if ( !$user->isAllowed( 'bot' ) ) {
1221                                                 $this->dieUsage( 'Assertion that the user has the bot right failed', 'assertbotfailed' );
1222                                         }
1223                                         break;
1224                         }
1225                 }
1226         }
1227
1228         /**
1229          * Check POST for external response and setup result printer
1230          * @param ApiBase $module An Api module
1231          * @param array $params An array with the request parameters
1232          */
1233         protected function setupExternalResponse( $module, $params ) {
1234                 if ( !$this->getRequest()->wasPosted() && $module->mustBePosted() ) {
1235                         // Module requires POST. GET request might still be allowed
1236                         // if $wgDebugApi is true, otherwise fail.
1237                         $this->dieUsageMsgOrDebug( array( 'mustbeposted', $this->mAction ) );
1238                 }
1239
1240                 // See if custom printer is used
1241                 $this->mPrinter = $module->getCustomPrinter();
1242                 if ( is_null( $this->mPrinter ) ) {
1243                         // Create an appropriate printer
1244                         $this->mPrinter = $this->createPrinterByName( $params['format'] );
1245                 }
1246         }
1247
1248         /**
1249          * Execute the actual module, without any error handling
1250          */
1251         protected function executeAction() {
1252                 $params = $this->setupExecuteAction();
1253                 $module = $this->setupModule();
1254                 $this->mModule = $module;
1255
1256                 $this->setRequestExpectations( $module );
1257
1258                 $this->checkExecutePermissions( $module );
1259
1260                 if ( !$this->checkMaxLag( $module, $params ) ) {
1261                         return;
1262                 }
1263
1264                 if ( !$this->checkConditionalRequestHeaders( $module ) ) {
1265                         return;
1266                 }
1267
1268                 if ( !$this->mInternalMode ) {
1269                         $this->setupExternalResponse( $module, $params );
1270                 }
1271
1272                 $this->checkAsserts( $params );
1273
1274                 // Execute
1275                 $module->execute();
1276                 Hooks::run( 'APIAfterExecute', array( &$module ) );
1277
1278                 $this->reportUnusedParams();
1279
1280                 if ( !$this->mInternalMode ) {
1281                         // append Debug information
1282                         MWDebug::appendDebugInfoToApiResult( $this->getContext(), $this->getResult() );
1283
1284                         // Print result data
1285                         $this->printResult( false );
1286                 }
1287         }
1288
1289         /**
1290          * Set database connection, query, and write expectations given this module request
1291          * @param ApiBase $module
1292          */
1293         protected function setRequestExpectations( ApiBase $module ) {
1294                 $limits = $this->getConfig()->get( 'TrxProfilerLimits' );
1295                 $trxProfiler = Profiler::instance()->getTransactionProfiler();
1296                 if ( $this->getRequest()->wasPosted() ) {
1297                         if ( $module->isWriteMode() ) {
1298                                 $trxProfiler->setExpectations( $limits['POST'], __METHOD__ );
1299                         } else {
1300                                 $trxProfiler->setExpectations( $limits['POST-nonwrite'], __METHOD__ );
1301                         }
1302                 } else {
1303                         $trxProfiler->setExpectations( $limits['GET'], __METHOD__ );
1304                 }
1305         }
1306
1307         /**
1308          * Log the preceding request
1309          * @param float $time Time in seconds
1310          */
1311         protected function logRequest( $time ) {
1312                 $request = $this->getRequest();
1313                 $logCtx = array(
1314                         'dt' => date( 'c' ),
1315                         'client_ip' => $request->getIP(),
1316                         'user_agent' => $this->getUserAgent(),
1317                         'wiki' => wfWikiID(),
1318                         'time_backend_ms' => round( $time * 1000 ),
1319                         'params' => array(),
1320                 );
1321
1322                 // Construct space separated message for 'api' log channel
1323                 $msg = "API {$request->getMethod()} " .
1324                         wfUrlencode( str_replace( ' ', '_', $this->getUser()->getName() ) ) .
1325                         " {$logCtx['client_ip']} " .
1326                         "T={$logCtx['time_backend_ms']}ms";
1327
1328                 foreach ( $this->getParamsUsed() as $name ) {
1329                         $value = $request->getVal( $name );
1330                         if ( $value === null ) {
1331                                 continue;
1332                         }
1333
1334                         if ( strlen( $value ) > 256 ) {
1335                                 $value = substr( $value, 0, 256 );
1336                                 $encValue = $this->encodeRequestLogValue( $value ) . '[...]';
1337                         } else {
1338                                 $encValue = $this->encodeRequestLogValue( $value );
1339                         }
1340
1341                         $logCtx['params'][$name] = $value;
1342                         $msg .= " {$name}={$encValue}";
1343                 }
1344
1345                 wfDebugLog( 'api', $msg, 'private' );
1346                 // ApiRequest channel is for structured data consumers
1347                 wfDebugLog( 'ApiRequest', '', 'private', $logCtx );
1348         }
1349
1350         /**
1351          * Encode a value in a format suitable for a space-separated log line.
1352          * @param string $s
1353          * @return string
1354          */
1355         protected function encodeRequestLogValue( $s ) {
1356                 static $table;
1357                 if ( !$table ) {
1358                         $chars = ';@$!*(),/:';
1359                         $numChars = strlen( $chars );
1360                         for ( $i = 0; $i < $numChars; $i++ ) {
1361                                 $table[rawurlencode( $chars[$i] )] = $chars[$i];
1362                         }
1363                 }
1364
1365                 return strtr( rawurlencode( $s ), $table );
1366         }
1367
1368         /**
1369          * Get the request parameters used in the course of the preceding execute() request
1370          * @return array
1371          */
1372         protected function getParamsUsed() {
1373                 return array_keys( $this->mParamsUsed );
1374         }
1375
1376         /**
1377          * Get a request value, and register the fact that it was used, for logging.
1378          * @param string $name
1379          * @param mixed $default
1380          * @return mixed
1381          */
1382         public function getVal( $name, $default = null ) {
1383                 $this->mParamsUsed[$name] = true;
1384
1385                 $ret = $this->getRequest()->getVal( $name );
1386                 if ( $ret === null ) {
1387                         if ( $this->getRequest()->getArray( $name ) !== null ) {
1388                                 // See bug 10262 for why we don't just join( '|', ... ) the
1389                                 // array.
1390                                 $this->setWarning(
1391                                         "Parameter '$name' uses unsupported PHP array syntax"
1392                                 );
1393                         }
1394                         $ret = $default;
1395                 }
1396                 return $ret;
1397         }
1398
1399         /**
1400          * Get a boolean request value, and register the fact that the parameter
1401          * was used, for logging.
1402          * @param string $name
1403          * @return bool
1404          */
1405         public function getCheck( $name ) {
1406                 return $this->getVal( $name, null ) !== null;
1407         }
1408
1409         /**
1410          * Get a request upload, and register the fact that it was used, for logging.
1411          *
1412          * @since 1.21
1413          * @param string $name Parameter name
1414          * @return WebRequestUpload
1415          */
1416         public function getUpload( $name ) {
1417                 $this->mParamsUsed[$name] = true;
1418
1419                 return $this->getRequest()->getUpload( $name );
1420         }
1421
1422         /**
1423          * Report unused parameters, so the client gets a hint in case it gave us parameters we don't know,
1424          * for example in case of spelling mistakes or a missing 'g' prefix for generators.
1425          */
1426         protected function reportUnusedParams() {
1427                 $paramsUsed = $this->getParamsUsed();
1428                 $allParams = $this->getRequest()->getValueNames();
1429
1430                 if ( !$this->mInternalMode ) {
1431                         // Printer has not yet executed; don't warn that its parameters are unused
1432                         $printerParams = array_map(
1433                                 array( $this->mPrinter, 'encodeParamName' ),
1434                                 array_keys( $this->mPrinter->getFinalParams() ?: array() )
1435                         );
1436                         $unusedParams = array_diff( $allParams, $paramsUsed, $printerParams );
1437                 } else {
1438                         $unusedParams = array_diff( $allParams, $paramsUsed );
1439                 }
1440
1441                 if ( count( $unusedParams ) ) {
1442                         $s = count( $unusedParams ) > 1 ? 's' : '';
1443                         $this->setWarning( "Unrecognized parameter$s: '" . implode( $unusedParams, "', '" ) . "'" );
1444                 }
1445         }
1446
1447         /**
1448          * Print results using the current printer
1449          *
1450          * @param bool $isError
1451          */
1452         protected function printResult( $isError ) {
1453                 if ( $this->getConfig()->get( 'DebugAPI' ) !== false ) {
1454                         $this->setWarning( 'SECURITY WARNING: $wgDebugAPI is enabled' );
1455                 }
1456
1457                 $printer = $this->mPrinter;
1458                 $printer->initPrinter( false );
1459                 $printer->execute();
1460                 $printer->closePrinter();
1461         }
1462
1463         /**
1464          * @return bool
1465          */
1466         public function isReadMode() {
1467                 return false;
1468         }
1469
1470         /**
1471          * See ApiBase for description.
1472          *
1473          * @return array
1474          */
1475         public function getAllowedParams() {
1476                 return array(
1477                         'action' => array(
1478                                 ApiBase::PARAM_DFLT => 'help',
1479                                 ApiBase::PARAM_TYPE => 'submodule',
1480                         ),
1481                         'format' => array(
1482                                 ApiBase::PARAM_DFLT => ApiMain::API_DEFAULT_FORMAT,
1483                                 ApiBase::PARAM_TYPE => 'submodule',
1484                         ),
1485                         'maxlag' => array(
1486                                 ApiBase::PARAM_TYPE => 'integer'
1487                         ),
1488                         'smaxage' => array(
1489                                 ApiBase::PARAM_TYPE => 'integer',
1490                                 ApiBase::PARAM_DFLT => 0
1491                         ),
1492                         'maxage' => array(
1493                                 ApiBase::PARAM_TYPE => 'integer',
1494                                 ApiBase::PARAM_DFLT => 0
1495                         ),
1496                         'assert' => array(
1497                                 ApiBase::PARAM_TYPE => array( 'user', 'bot' )
1498                         ),
1499                         'requestid' => null,
1500                         'servedby' => false,
1501                         'curtimestamp' => false,
1502                         'origin' => null,
1503                         'uselang' => array(
1504                                 ApiBase::PARAM_DFLT => 'user',
1505                         ),
1506                 );
1507         }
1508
1509         /** @see ApiBase::getExamplesMessages() */
1510         protected function getExamplesMessages() {
1511                 return array(
1512                         'action=help'
1513                                 => 'apihelp-help-example-main',
1514                         'action=help&recursivesubmodules=1'
1515                                 => 'apihelp-help-example-recursive',
1516                 );
1517         }
1518
1519         public function modifyHelp( array &$help, array $options, array &$tocData ) {
1520                 // Wish PHP had an "array_insert_before". Instead, we have to manually
1521                 // reindex the array to get 'permissions' in the right place.
1522                 $oldHelp = $help;
1523                 $help = array();
1524                 foreach ( $oldHelp as $k => $v ) {
1525                         if ( $k === 'submodules' ) {
1526                                 $help['permissions'] = '';
1527                         }
1528                         $help[$k] = $v;
1529                 }
1530                 $help['datatypes'] = '';
1531                 $help['credits'] = '';
1532
1533                 // Fill 'permissions'
1534                 $help['permissions'] .= Html::openElement( 'div',
1535                         array( 'class' => 'apihelp-block apihelp-permissions' ) );
1536                 $m = $this->msg( 'api-help-permissions' );
1537                 if ( !$m->isDisabled() ) {
1538                         $help['permissions'] .= Html::rawElement( 'div', array( 'class' => 'apihelp-block-head' ),
1539                                 $m->numParams( count( self::$mRights ) )->parse()
1540                         );
1541                 }
1542                 $help['permissions'] .= Html::openElement( 'dl' );
1543                 foreach ( self::$mRights as $right => $rightMsg ) {
1544                         $help['permissions'] .= Html::element( 'dt', null, $right );
1545
1546                         $rightMsg = $this->msg( $rightMsg['msg'], $rightMsg['params'] )->parse();
1547                         $help['permissions'] .= Html::rawElement( 'dd', null, $rightMsg );
1548
1549                         $groups = array_map( function ( $group ) {
1550                                 return $group == '*' ? 'all' : $group;
1551                         }, User::getGroupsWithPermission( $right ) );
1552
1553                         $help['permissions'] .= Html::rawElement( 'dd', null,
1554                                 $this->msg( 'api-help-permissions-granted-to' )
1555                                         ->numParams( count( $groups ) )
1556                                         ->params( $this->getLanguage()->commaList( $groups ) )
1557                                         ->parse()
1558                         );
1559                 }
1560                 $help['permissions'] .= Html::closeElement( 'dl' );
1561                 $help['permissions'] .= Html::closeElement( 'div' );
1562
1563                 // Fill 'datatypes' and 'credits', if applicable
1564                 if ( empty( $options['nolead'] ) ) {
1565                         $level = $options['headerlevel'];
1566                         $tocnumber = &$options['tocnumber'];
1567
1568                         $header = $this->msg( 'api-help-datatypes-header' )->parse();
1569                         $help['datatypes'] .= Html::rawElement( 'h' . min( 6, $level ),
1570                                 array( 'id' => 'main/datatypes', 'class' => 'apihelp-header' ),
1571                                 Html::element( 'span', array( 'id' => Sanitizer::escapeId( 'main/datatypes' ) ) ) .
1572                                 $header
1573                         );
1574                         $help['datatypes'] .= $this->msg( 'api-help-datatypes' )->parseAsBlock();
1575                         if ( !isset( $tocData['main/datatypes'] ) ) {
1576                                 $tocnumber[$level]++;
1577                                 $tocData['main/datatypes'] = array(
1578                                         'toclevel' => count( $tocnumber ),
1579                                         'level' => $level,
1580                                         'anchor' => 'main/datatypes',
1581                                         'line' => $header,
1582                                         'number' => join( '.', $tocnumber ),
1583                                         'index' => false,
1584                                 );
1585                         }
1586
1587                         $header = $this->msg( 'api-credits-header' )->parse();
1588                         $help['credits'] .= Html::rawElement( 'h' . min( 6, $level ),
1589                                 array( 'id' => 'main/credits', 'class' => 'apihelp-header' ),
1590                                 Html::element( 'span', array( 'id' => Sanitizer::escapeId( 'main/credits' ) ) ) .
1591                                 $header
1592                         );
1593                         $help['credits'] .= $this->msg( 'api-credits' )->useDatabase( false )->parseAsBlock();
1594                         if ( !isset( $tocData['main/credits'] ) ) {
1595                                 $tocnumber[$level]++;
1596                                 $tocData['main/credits'] = array(
1597                                         'toclevel' => count( $tocnumber ),
1598                                         'level' => $level,
1599                                         'anchor' => 'main/credits',
1600                                         'line' => $header,
1601                                         'number' => join( '.', $tocnumber ),
1602                                         'index' => false,
1603                                 );
1604                         }
1605                 }
1606         }
1607
1608         private $mCanApiHighLimits = null;
1609
1610         /**
1611          * Check whether the current user is allowed to use high limits
1612          * @return bool
1613          */
1614         public function canApiHighLimits() {
1615                 if ( !isset( $this->mCanApiHighLimits ) ) {
1616                         $this->mCanApiHighLimits = $this->getUser()->isAllowed( 'apihighlimits' );
1617                 }
1618
1619                 return $this->mCanApiHighLimits;
1620         }
1621
1622         /**
1623          * Overrides to return this instance's module manager.
1624          * @return ApiModuleManager
1625          */
1626         public function getModuleManager() {
1627                 return $this->mModuleMgr;
1628         }
1629
1630         /**
1631          * Fetches the user agent used for this request
1632          *
1633          * The value will be the combination of the 'Api-User-Agent' header (if
1634          * any) and the standard User-Agent header (if any).
1635          *
1636          * @return string
1637          */
1638         public function getUserAgent() {
1639                 return trim(
1640                         $this->getRequest()->getHeader( 'Api-user-agent' ) . ' ' .
1641                         $this->getRequest()->getHeader( 'User-agent' )
1642                 );
1643         }
1644
1645         /************************************************************************//**
1646          * @name   Deprecated
1647          * @{
1648          */
1649
1650         /**
1651          * Sets whether the pretty-printer should format *bold* and $italics$
1652          *
1653          * @deprecated since 1.25
1654          * @param bool $help
1655          */
1656         public function setHelp( $help = true ) {
1657                 wfDeprecated( __METHOD__, '1.25' );
1658                 $this->mPrinter->setHelp( $help );
1659         }
1660
1661         /**
1662          * Override the parent to generate help messages for all available modules.
1663          *
1664          * @deprecated since 1.25
1665          * @return string
1666          */
1667         public function makeHelpMsg() {
1668                 wfDeprecated( __METHOD__, '1.25' );
1669
1670                 $this->setHelp();
1671                 $cacheHelpTimeout = $this->getConfig()->get( 'APICacheHelpTimeout' );
1672
1673                 return ObjectCache::getMainWANInstance()->getWithSetCallback(
1674                         wfMemcKey(
1675                                 'apihelp',
1676                                 $this->getModuleName(),
1677                                 str_replace( ' ', '_', SpecialVersion::getVersion( 'nodb' ) )
1678                         ),
1679                         $cacheHelpTimeout > 0 ? $cacheHelpTimeout : WANObjectCache::TTL_UNCACHEABLE,
1680                         array( $this, 'reallyMakeHelpMsg' )
1681                 );
1682         }
1683
1684         /**
1685          * @deprecated since 1.25
1686          * @return mixed|string
1687          */
1688         public function reallyMakeHelpMsg() {
1689                 wfDeprecated( __METHOD__, '1.25' );
1690                 $this->setHelp();
1691
1692                 // Use parent to make default message for the main module
1693                 $msg = parent::makeHelpMsg();
1694
1695                 $astriks = str_repeat( '*** ', 14 );
1696                 $msg .= "\n\n$astriks Modules  $astriks\n\n";
1697
1698                 foreach ( $this->mModuleMgr->getNames( 'action' ) as $name ) {
1699                         $module = $this->mModuleMgr->getModule( $name );
1700                         $msg .= self::makeHelpMsgHeader( $module, 'action' );
1701
1702                         $msg2 = $module->makeHelpMsg();
1703                         if ( $msg2 !== false ) {
1704                                 $msg .= $msg2;
1705                         }
1706                         $msg .= "\n";
1707                 }
1708
1709                 $msg .= "\n$astriks Permissions $astriks\n\n";
1710                 foreach ( self::$mRights as $right => $rightMsg ) {
1711                         $rightsMsg = $this->msg( $rightMsg['msg'], $rightMsg['params'] )
1712                                 ->useDatabase( false )
1713                                 ->inLanguage( 'en' )
1714                                 ->text();
1715                         $groups = User::getGroupsWithPermission( $right );
1716                         $msg .= "* " . $right . " *\n  $rightsMsg" .
1717                                 "\nGranted to:\n  " . str_replace( '*', 'all', implode( ', ', $groups ) ) . "\n\n";
1718                 }
1719
1720                 $msg .= "\n$astriks Formats  $astriks\n\n";
1721                 foreach ( $this->mModuleMgr->getNames( 'format' ) as $name ) {
1722                         $module = $this->mModuleMgr->getModule( $name );
1723                         $msg .= self::makeHelpMsgHeader( $module, 'format' );
1724                         $msg2 = $module->makeHelpMsg();
1725                         if ( $msg2 !== false ) {
1726                                 $msg .= $msg2;
1727                         }
1728                         $msg .= "\n";
1729                 }
1730
1731                 $credits = $this->msg( 'api-credits' )->useDatabase( 'false' )->inLanguage( 'en' )->text();
1732                 $credits = str_replace( "\n", "\n   ", $credits );
1733                 $msg .= "\n*** Credits: ***\n   $credits\n";
1734
1735                 return $msg;
1736         }
1737
1738         /**
1739          * @deprecated since 1.25
1740          * @param ApiBase $module
1741          * @param string $paramName What type of request is this? e.g. action,
1742          *    query, list, prop, meta, format
1743          * @return string
1744          */
1745         public static function makeHelpMsgHeader( $module, $paramName ) {
1746                 wfDeprecated( __METHOD__, '1.25' );
1747                 $modulePrefix = $module->getModulePrefix();
1748                 if ( strval( $modulePrefix ) !== '' ) {
1749                         $modulePrefix = "($modulePrefix) ";
1750                 }
1751
1752                 return "* $paramName={$module->getModuleName()} $modulePrefix*";
1753         }
1754
1755         /**
1756          * Check whether the user wants us to show version information in the API help
1757          * @return bool
1758          * @deprecated since 1.21, always returns false
1759          */
1760         public function getShowVersions() {
1761                 wfDeprecated( __METHOD__, '1.21' );
1762
1763                 return false;
1764         }
1765
1766         /**
1767          * Add or overwrite a module in this ApiMain instance. Intended for use by extending
1768          * classes who wish to add their own modules to their lexicon or override the
1769          * behavior of inherent ones.
1770          *
1771          * @deprecated since 1.21, Use getModuleManager()->addModule() instead.
1772          * @param string $name The identifier for this module.
1773          * @param ApiBase $class The class where this module is implemented.
1774          */
1775         protected function addModule( $name, $class ) {
1776                 $this->getModuleManager()->addModule( $name, 'action', $class );
1777         }
1778
1779         /**
1780          * Add or overwrite an output format for this ApiMain. Intended for use by extending
1781          * classes who wish to add to or modify current formatters.
1782          *
1783          * @deprecated since 1.21, Use getModuleManager()->addModule() instead.
1784          * @param string $name The identifier for this format.
1785          * @param ApiFormatBase $class The class implementing this format.
1786          */
1787         protected function addFormat( $name, $class ) {
1788                 $this->getModuleManager()->addModule( $name, 'format', $class );
1789         }
1790
1791         /**
1792          * Returns the list of supported formats in form ( 'format' => 'ClassName' )
1793          *
1794          * @since 1.18
1795          * @deprecated since 1.21, Use getModuleManager()'s methods instead.
1796          * @return array
1797          */
1798         public function getFormats() {
1799                 return $this->getModuleManager()->getNamesWithClasses( 'format' );
1800         }
1801
1802         /**@}*/
1803
1804 }
1805
1806 /**
1807  * This exception will be thrown when dieUsage is called to stop module execution.
1808  *
1809  * @ingroup API
1810  */
1811 class UsageException extends MWException {
1812
1813         private $mCodestr;
1814
1815         /**
1816          * @var null|array
1817          */
1818         private $mExtraData;
1819
1820         /**
1821          * @param string $message
1822          * @param string $codestr
1823          * @param int $code
1824          * @param array|null $extradata
1825          */
1826         public function __construct( $message, $codestr, $code = 0, $extradata = null ) {
1827                 parent::__construct( $message, $code );
1828                 $this->mCodestr = $codestr;
1829                 $this->mExtraData = $extradata;
1830         }
1831
1832         /**
1833          * @return string
1834          */
1835         public function getCodeString() {
1836                 return $this->mCodestr;
1837         }
1838
1839         /**
1840          * @return array
1841          */
1842         public function getMessageArray() {
1843                 $result = array(
1844                         'code' => $this->mCodestr,
1845                         'info' => $this->getMessage()
1846                 );
1847                 if ( is_array( $this->mExtraData ) ) {
1848                         $result = array_merge( $result, $this->mExtraData );
1849                 }
1850
1851                 return $result;
1852         }
1853
1854         /**
1855          * @return string
1856          */
1857         public function __toString() {
1858                 return "{$this->getCodeString()}: {$this->getMessage()}";
1859         }
1860 }
1861
1862 /**
1863  * For really cool vim folding this needs to be at the end:
1864  * vim: foldmarker=@{,@} foldmethod=marker
1865  */