ApiMain.php

Go to the documentation of this file.

<?php
class ApiMain extends ApiBase {

        const API_DEFAULT_FORMAT = 'xmlfm';

        private static $Modules = array(
                'login' => 'ApiLogin',
                'logout' => 'ApiLogout',
                'query' => 'ApiQuery',
                'expandtemplates' => 'ApiExpandTemplates',
                'parse' => 'ApiParse',
                'opensearch' => 'ApiOpenSearch',
                'feedcontributions' => 'ApiFeedContributions',
                'feedwatchlist' => 'ApiFeedWatchlist',
                'help' => 'ApiHelp',
                'paraminfo' => 'ApiParamInfo',
                'rsd' => 'ApiRsd',
                'compare' => 'ApiComparePages',
                'tokens' => 'ApiTokens',

                // Write modules
                'purge' => 'ApiPurge',
                'setnotificationtimestamp' => 'ApiSetNotificationTimestamp',
                'rollback' => 'ApiRollback',
                'delete' => 'ApiDelete',
                'undelete' => 'ApiUndelete',
                'protect' => 'ApiProtect',
                'block' => 'ApiBlock',
                'unblock' => 'ApiUnblock',
                'move' => 'ApiMove',
                'edit' => 'ApiEditPage',
                'upload' => 'ApiUpload',
                'filerevert' => 'ApiFileRevert',
                'emailuser' => 'ApiEmailUser',
                'watch' => 'ApiWatch',
                'patrol' => 'ApiPatrol',
                'import' => 'ApiImport',
                'userrights' => 'ApiUserrights',
                'options' => 'ApiOptions',
        );

        private static $Formats = array(
                'json' => 'ApiFormatJson',
                'jsonfm' => 'ApiFormatJson',
                'php' => 'ApiFormatPhp',
                'phpfm' => 'ApiFormatPhp',
                'wddx' => 'ApiFormatWddx',
                'wddxfm' => 'ApiFormatWddx',
                'xml' => 'ApiFormatXml',
                'xmlfm' => 'ApiFormatXml',
                'yaml' => 'ApiFormatYaml',
                'yamlfm' => 'ApiFormatYaml',
                'rawfm' => 'ApiFormatJson',
                'txt' => 'ApiFormatTxt',
                'txtfm' => 'ApiFormatTxt',
                'dbg' => 'ApiFormatDbg',
                'dbgfm' => 'ApiFormatDbg',
                'dump' => 'ApiFormatDump',
                'dumpfm' => 'ApiFormatDump',
                'none' => 'ApiFormatNone',
        );

        private static $mRights = array(
                'writeapi' => array(
                        'msg' => 'Use of the write API',
                        'params' => array()
                ),
                'apihighlimits' => array(
                        'msg' => 'Use higher limits in API queries (Slow queries: $1 results; Fast queries: $2 results). The limits for slow queries also apply to multivalue parameters.',
                        'params' => array( ApiBase::LIMIT_SML2, ApiBase::LIMIT_BIG2 )
                )
        );

        private $mPrinter;

        private $mModules, $mModuleNames, $mFormats, $mFormatNames;
        private $mResult, $mAction, $mShowVersions, $mEnableWrite;
        private $mInternalMode, $mSquidMaxage, $mModule;

        private $mCacheMode = 'private';
        private $mCacheControl = array();
        private $mParamsUsed = array();

        public function __construct( $context = null, $enableWrite = false ) {
                if ( $context === null ) {
                        $context = RequestContext::getMain();
                } elseif ( $context instanceof WebRequest ) {
                        // BC for pre-1.19
                        $request = $context;
                        $context = RequestContext::getMain();
                }
                // We set a derivative context so we can change stuff later
                $this->setContext( new DerivativeContext( $context ) );

                if ( isset( $request ) ) {
                        $this->getContext()->setRequest( $request );
                }

                $this->mInternalMode = ( $this->getRequest() instanceof FauxRequest );

                // Special handling for the main module: $parent === $this
                parent::__construct( $this, $this->mInternalMode ? 'main_int' : 'main' );

                if ( !$this->mInternalMode ) {
                        // Impose module restrictions.
                        // If the current user cannot read,
                        // Remove all modules other than login
                        global $wgUser;

                        if ( $this->getVal( 'callback' ) !== null ) {
                                // JSON callback allows cross-site reads.
                                // For safety, strip user credentials.
                                wfDebug( "API: stripping user credentials for JSON callback\n" );
                                $wgUser = new User();
                                $this->getContext()->setUser( $wgUser );
                        }
                }

                global $wgAPIModules; // extension modules
                $this->mModules = $wgAPIModules + self::$Modules;

                $this->mModuleNames = array_keys( $this->mModules );
                $this->mFormats = self::$Formats;
                $this->mFormatNames = array_keys( $this->mFormats );

                $this->mResult = new ApiResult( $this );
                $this->mShowVersions = false;
                $this->mEnableWrite = $enableWrite;

                $this->mSquidMaxage = - 1; // flag for executeActionWithErrorHandling()
                $this->mCommit = false;
        }

        public function isInternalMode() {
                return $this->mInternalMode;
        }

        public function getResult() {
                return $this->mResult;
        }

        public function getModule() {
                return $this->mModule;
        }

        public function getPrinter() {
                return $this->mPrinter;
        }

        public function setCacheMaxAge( $maxage ) {
                $this->setCacheControl( array(
                        'max-age' => $maxage,
                        's-maxage' => $maxage
                ) );
        }

        public function setCacheMode( $mode ) {
                if ( !in_array( $mode, array( 'private', 'public', 'anon-public-user-private' ) ) ) {
                        wfDebug( __METHOD__ . ": unrecognised cache mode \"$mode\"\n" );
                        // Ignore for forwards-compatibility
                        return;
                }

                if ( !in_array( 'read', User::getGroupPermissions( array( '*' ) ), true ) ) {
                        // Private wiki, only private headers
                        if ( $mode !== 'private' ) {
                                wfDebug( __METHOD__ . ": ignoring request for $mode cache mode, private wiki\n" );
                                return;
                        }
                }

                wfDebug( __METHOD__ . ": setting cache mode $mode\n" );
                $this->mCacheMode = $mode;
        }

        public function setCachePrivate() {
                wfDeprecated( __METHOD__, '1.17' );
                $this->setCacheMode( 'private' );
        }

        public function setCacheControl( $directives ) {
                $this->mCacheControl = $directives + $this->mCacheControl;
        }

        public function setVaryCookie() {
                wfDeprecated( __METHOD__, '1.17' );
                $this->setCacheMode( 'anon-public-user-private' );
        }

        public function createPrinterByName( $format ) {
                if ( !isset( $this->mFormats[$format] ) ) {
                        $this->dieUsage( "Unrecognized format: {$format}", 'unknown_format' );
                }
                return new $this->mFormats[$format] ( $this, $format );
        }

        public function execute() {
                $this->profileIn();
                if ( $this->mInternalMode ) {
                        $this->executeAction();
                } else {
                        $this->executeActionWithErrorHandling();
                }

                $this->profileOut();
        }

        protected function executeActionWithErrorHandling() {
                // Verify the CORS header before executing the action
                if ( !$this->handleCORS() ) {
                        // handleCORS() has sent a 403, abort
                        return;
                }

                // In case an error occurs during data output,
                // clear the output buffer and print just the error information
                ob_start();

                $t = microtime( true );
                try {
                        $this->executeAction();
                } catch ( Exception $e ) {
                        // Allow extra cleanup and logging
                        wfRunHooks( 'ApiMain::onException', array( $this, $e ) );

                        // Log it
                        if ( !( $e instanceof UsageException ) ) {
                                global $wgLogExceptionBacktrace;
                                if ( $wgLogExceptionBacktrace ) {
                                        wfDebugLog( 'exception', $e->getLogMessage() . "\n" . $e->getTraceAsString() . "\n" );
                                } else {
                                        wfDebugLog( 'exception', $e->getLogMessage() );
                                }
                        }

                        // Handle any kind of exception by outputing properly formatted error message.
                        // If this fails, an unhandled exception should be thrown so that global error
                        // handler will process and log it.

                        $errCode = $this->substituteResultWithError( $e );

                        // Error results should not be cached
                        $this->setCacheMode( 'private' );

                        $response = $this->getRequest()->response();
                        $headerStr = 'MediaWiki-API-Error: ' . $errCode;
                        if ( $e->getCode() === 0 ) {
                                $response->header( $headerStr );
                        } else {
                                $response->header( $headerStr, true, $e->getCode() );
                        }

                        // Reset and print just the error message
                        ob_clean();

                        // If the error occurred during printing, do a printer->profileOut()
                        $this->mPrinter->safeProfileOut();
                        $this->printResult( true );
                }

                // Log the request whether or not there was an error
                $this->logRequest( microtime( true ) - $t);

                // Send cache headers after any code which might generate an error, to
                // avoid sending public cache headers for errors.
                $this->sendCacheHeaders();

                if ( $this->mPrinter->getIsHtml() && !$this->mPrinter->isDisabled() ) {
                        echo wfReportTime();
                }

                ob_end_flush();
        }

        protected function handleCORS() {
                global $wgCrossSiteAJAXdomains, $wgCrossSiteAJAXdomainExceptions;

                $originParam = $this->getParameter( 'origin' ); // defaults to null
                if ( $originParam === null ) {
                        // No origin parameter, nothing to do
                        return true;
                }

                $request = $this->getRequest();
                $response = $request->response();
                // Origin: header is a space-separated list of origins, check all of them
                $originHeader = $request->getHeader( 'Origin' );
                if ( $originHeader === false ) {
                        $origins = array();
                } else {
                        $origins = explode( ' ', $originHeader );
                }
                if ( !in_array( $originParam, $origins ) ) {
                        // origin parameter set but incorrect
                        // Send a 403 response
                        $message = HttpStatus::getMessage( 403 );
                        $response->header( "HTTP/1.1 403 $message", true, 403 );
                        $response->header( 'Cache-Control: no-cache' );
                        echo "'origin' parameter does not match Origin header\n";
                        return false;
                }
                if ( self::matchOrigin( $originParam, $wgCrossSiteAJAXdomains, $wgCrossSiteAJAXdomainExceptions ) ) {
                        $response->header( "Access-Control-Allow-Origin: $originParam" );
                        $response->header( 'Access-Control-Allow-Credentials: true' );
                        $this->getOutput()->addVaryHeader( 'Origin' );
                }
                return true;
        }

        protected static function matchOrigin( $value, $rules, $exceptions ) {
                foreach ( $rules as $rule ) {
                        if ( preg_match( self::wildcardToRegex( $rule ), $value ) ) {
                                // Rule matches, check exceptions
                                foreach ( $exceptions as $exc ) {
                                        if ( preg_match( self::wildcardToRegex( $exc ), $value ) ) {
                                                return false;
                                        }
                                }
                                return true;
                        }
                }
                return false;
        }

        protected static function wildcardToRegex( $wildcard ) {
                $wildcard = preg_quote( $wildcard, '/' );
                $wildcard = str_replace(
                        array( '\*', '\?' ),
                        array( '.*?', '.' ),
                        $wildcard
                );
                return "/https?:\/\/$wildcard/";
        }

        protected function sendCacheHeaders() {
                global $wgUseXVO, $wgVaryOnXFP;
                $response = $this->getRequest()->response();
                $out = $this->getOutput();

                if ( $wgVaryOnXFP ) {
                        $out->addVaryHeader( 'X-Forwarded-Proto' );
                }

                if ( $this->mCacheMode == 'private' ) {
                        $response->header( 'Cache-Control: private' );
                        return;
                }

                if ( $this->mCacheMode == 'anon-public-user-private' ) {
                        $out->addVaryHeader( 'Cookie' );
                        $response->header( $out->getVaryHeader() );
                        if ( $wgUseXVO ) {
                                $response->header( $out->getXVO() );
                                if ( $out->haveCacheVaryCookies() ) {
                                        // Logged in, mark this request private
                                        $response->header( 'Cache-Control: private' );
                                        return;
                                }
                                // Logged out, send normal public headers below
                        } elseif ( session_id() != '' ) {
                                // Logged in or otherwise has session (e.g. anonymous users who have edited)
                                // Mark request private
                                $response->header( 'Cache-Control: private' );
                                return;
                        } // else no XVO and anonymous, send public headers below
                }

                // Send public headers
                $response->header( $out->getVaryHeader() );
                if ( $wgUseXVO ) {
                        $response->header( $out->getXVO() );
                }

                // If nobody called setCacheMaxAge(), use the (s)maxage parameters
                if ( !isset( $this->mCacheControl['s-maxage'] ) ) {
                        $this->mCacheControl['s-maxage'] = $this->getParameter( 'smaxage' );
                }
                if ( !isset( $this->mCacheControl['max-age'] ) ) {
                        $this->mCacheControl['max-age'] = $this->getParameter( 'maxage' );
                }

                if ( !$this->mCacheControl['s-maxage'] && !$this->mCacheControl['max-age'] ) {
                        // Public cache not requested
                        // Sending a Vary header in this case is harmless, and protects us
                        // against conditional calls of setCacheMaxAge().
                        $response->header( 'Cache-Control: private' );
                        return;
                }

                $this->mCacheControl['public'] = true;

                // Send an Expires header
                $maxAge = min( $this->mCacheControl['s-maxage'], $this->mCacheControl['max-age'] );
                $expiryUnixTime = ( $maxAge == 0 ? 1 : time() + $maxAge );
                $response->header( 'Expires: ' . wfTimestamp( TS_RFC2822, $expiryUnixTime ) );

                // Construct the Cache-Control header
                $ccHeader = '';
                $separator = '';
                foreach ( $this->mCacheControl as $name => $value ) {
                        if ( is_bool( $value ) ) {
                                if ( $value ) {
                                        $ccHeader .= $separator . $name;
                                        $separator = ', ';
                                }
                        } else {
                                $ccHeader .= $separator . "$name=$value";
                                $separator = ', ';
                        }
                }

                $response->header( "Cache-Control: $ccHeader" );
        }

        protected function substituteResultWithError( $e ) {
                global $wgShowHostnames;

                $result = $this->getResult();
                // Printer may not be initialized if the extractRequestParams() fails for the main module
                if ( !isset ( $this->mPrinter ) ) {
                        // The printer has not been created yet. Try to manually get formatter value.
                        $value = $this->getRequest()->getVal( 'format', self::API_DEFAULT_FORMAT );
                        if ( !in_array( $value, $this->mFormatNames ) ) {
                                $value = self::API_DEFAULT_FORMAT;
                        }

                        $this->mPrinter = $this->createPrinterByName( $value );
                        if ( $this->mPrinter->getNeedsRawData() ) {
                                $result->setRawMode();
                        }
                }

                if ( $e instanceof UsageException ) {
                        // User entered incorrect parameters - print usage screen
                        $errMessage = $e->getMessageArray();

                        // Only print the help message when this is for the developer, not runtime
                        if ( $this->mPrinter->getWantsHelp() || $this->mAction == 'help' ) {
                                ApiResult::setContent( $errMessage, $this->makeHelpMsg() );
                        }

                } else {
                        global $wgShowSQLErrors, $wgShowExceptionDetails;
                        // Something is seriously wrong
                        if ( ( $e instanceof DBQueryError ) && !$wgShowSQLErrors ) {
                                $info = 'Database query error';
                        } else {
                                $info = "Exception Caught: {$e->getMessage()}";
                        }

                        $errMessage = array(
                                'code' => 'internal_api_error_' . get_class( $e ),
                                'info' => $info,
                        );
                        ApiResult::setContent( $errMessage, $wgShowExceptionDetails ? "\n\n{$e->getTraceAsString()}\n\n" : '' );
                }

                $result->reset();
                $result->disableSizeCheck();
                // Re-add the id
                $requestid = $this->getParameter( 'requestid' );
                if ( !is_null( $requestid ) ) {
                        $result->addValue( null, 'requestid', $requestid );
                }

                if ( $wgShowHostnames ) {
                        // servedby is especially useful when debugging errors
                        $result->addValue( null, 'servedby', wfHostName() );
                }

                $result->addValue( null, 'error', $errMessage );

                return $errMessage['code'];
        }

        protected function setupExecuteAction() {
                global $wgShowHostnames;

                // First add the id to the top element
                $result = $this->getResult();
                $requestid = $this->getParameter( 'requestid' );
                if ( !is_null( $requestid ) ) {
                        $result->addValue( null, 'requestid', $requestid );
                }

                if ( $wgShowHostnames ) {
                        $servedby = $this->getParameter( 'servedby' );
                        if ( $servedby ) {
                                $result->addValue( null, 'servedby', wfHostName() );
                        }
                }

                $params = $this->extractRequestParams();

                $this->mShowVersions = $params['version'];
                $this->mAction = $params['action'];

                if ( !is_string( $this->mAction ) ) {
                        $this->dieUsage( 'The API requires a valid action parameter', 'unknown_action' );
                }

                return $params;
        }

        protected function setupModule() {
                // Instantiate the module requested by the user
                $module = new $this->mModules[$this->mAction] ( $this, $this->mAction );
                $this->mModule = $module;

                $moduleParams = $module->extractRequestParams();

                // Die if token required, but not provided (unless there is a gettoken parameter)
                if ( isset( $moduleParams['gettoken'] ) ) {
                        $gettoken = $moduleParams['gettoken'];
                } else {
                        $gettoken = false;
                }

                $salt = $module->getTokenSalt();
                if ( $salt !== false && !$gettoken ) {
                        if ( !isset( $moduleParams['token'] ) ) {
                                $this->dieUsageMsg( array( 'missingparam', 'token' ) );
                        } else {
                                if ( !$this->getUser()->matchEditToken( $moduleParams['token'], $salt, $this->getContext()->getRequest() ) ) {
                                        $this->dieUsageMsg( 'sessionfailure' );
                                }
                        }
                }
                return $module;
        }

        protected function checkMaxLag( $module, $params ) {
                if ( $module->shouldCheckMaxlag() && isset( $params['maxlag'] ) ) {
                        // Check for maxlag
                        global $wgShowHostnames;
                        $maxLag = $params['maxlag'];
                        list( $host, $lag ) = wfGetLB()->getMaxLag();
                        if ( $lag > $maxLag ) {
                                $response = $this->getRequest()->response();

                                $response->header( 'Retry-After: ' . max( intval( $maxLag ), 5 ) );
                                $response->header( 'X-Database-Lag: ' . intval( $lag ) );

                                if ( $wgShowHostnames ) {
                                        $this->dieUsage( "Waiting for $host: $lag seconds lagged", 'maxlag' );
                                } else {
                                        $this->dieUsage( "Waiting for a database server: $lag seconds lagged", 'maxlag' );
                                }
                                return false;
                        }
                }
                return true;
        }

        protected function checkExecutePermissions( $module ) {
                $user = $this->getUser();
                if ( $module->isReadMode() && !in_array( 'read', User::getGroupPermissions( array( '*' ) ), true ) &&
                        !$user->isAllowed( 'read' ) )
                {
                        $this->dieUsageMsg( 'readrequired' );
                }
                if ( $module->isWriteMode() ) {
                        if ( !$this->mEnableWrite ) {
                                $this->dieUsageMsg( 'writedisabled' );
                        }
                        if ( !$user->isAllowed( 'writeapi' ) ) {
                                $this->dieUsageMsg( 'writerequired' );
                        }
                        if ( wfReadOnly() ) {
                                $this->dieReadOnly();
                        }
                }

                // Allow extensions to stop execution for arbitrary reasons.
                $message = false;
                if( !wfRunHooks( 'ApiCheckCanExecute', array( $module, $user, &$message ) ) ) {
                        $this->dieUsageMsg( $message );
                }
        }

        protected function setupExternalResponse( $module, $params ) {
                // Ignore mustBePosted() for internal calls
                if ( $module->mustBePosted() && !$this->getRequest()->wasPosted() ) {
                        $this->dieUsageMsg( array( 'mustbeposted', $this->mAction ) );
                }

                // See if custom printer is used
                $this->mPrinter = $module->getCustomPrinter();
                if ( is_null( $this->mPrinter ) ) {
                        // Create an appropriate printer
                        $this->mPrinter = $this->createPrinterByName( $params['format'] );
                }

                if ( $this->mPrinter->getNeedsRawData() ) {
                        $this->getResult()->setRawMode();
                }
        }

        protected function executeAction() {
                $params = $this->setupExecuteAction();
                $module = $this->setupModule();

                $this->checkExecutePermissions( $module );

                if ( !$this->checkMaxLag( $module, $params ) ) {
                        return;
                }

                if ( !$this->mInternalMode ) {
                        $this->setupExternalResponse( $module, $params );
                }

                // Execute
                $module->profileIn();
                $module->execute();
                wfRunHooks( 'APIAfterExecute', array( &$module ) );
                $module->profileOut();

                if ( !$this->mInternalMode ) {
                        // Report unused params
                        $this->reportUnusedParams();

                        //append Debug information
                        MWDebug::appendDebugInfoToApiResult( $this->getContext(), $this->getResult() );

                        // Print result data
                        $this->printResult( false );
                }
        }

        protected function logRequest( $time ) {
                $request = $this->getRequest();
                $milliseconds = $time === null ? '?' : round( $time * 1000 );
                $s = 'API' .
                        ' ' . $request->getMethod() .
                        ' ' . wfUrlencode( str_replace( ' ', '_', $this->getUser()->getName() ) ) .
                        ' ' . $request->getIP() .
                        ' T=' . $milliseconds .'ms';
                foreach ( $this->getParamsUsed() as $name ) {
                        $value = $request->getVal( $name );
                        if ( $value === null ) {
                                continue;
                        }
                        $s .= ' ' . $name . '=';
                        if ( strlen( $value ) > 256 ) {
                                $encValue = $this->encodeRequestLogValue( substr( $value, 0, 256 ) );
                                $s .= $encValue . '[...]';
                        } else {
                                $s .= $this->encodeRequestLogValue( $value );
                        }
                }
                $s .= "\n";
                wfDebugLog( 'api', $s, false );
        }

        protected function encodeRequestLogValue( $s ) {
                static $table;
                if ( !$table ) {
                        $chars = ';@$!*(),/:';
                        for ( $i = 0; $i < strlen( $chars ); $i++ ) {
                                $table[ rawurlencode( $chars[$i] ) ] = $chars[$i];
                        }
                }
                return strtr( rawurlencode( $s ), $table );
        }

        protected function getParamsUsed() {
                return array_keys( $this->mParamsUsed );
        }

        public function getVal( $name, $default = null ) {
                $this->mParamsUsed[$name] = true;
                return $this->getRequest()->getVal( $name, $default );
        }

        public function getCheck( $name ) {
                $this->mParamsUsed[$name] = true;
                return $this->getRequest()->getCheck( $name );
        }

        protected function reportUnusedParams() {
                $paramsUsed = $this->getParamsUsed();
                $allParams = $this->getRequest()->getValueNames();

                $unusedParams = array_diff( $allParams, $paramsUsed );
                if( count( $unusedParams ) ) {
                        $s = count( $unusedParams ) > 1 ? 's' : '';
                        $this->setWarning( "Unrecognized parameter$s: '" . implode( $unusedParams, "', '" ) . "'" );
                }
        }

        protected function printResult( $isError ) {
                $this->getResult()->cleanUpUTF8();
                $printer = $this->mPrinter;
                $printer->profileIn();

                $printer->setUnescapeAmps( ( $this->mAction == 'help' || $isError )
                                && $printer->getFormat() == 'XML' && $printer->getIsHtml() );

                $printer->initPrinter( $isError );

                $printer->execute();
                $printer->closePrinter();
                $printer->profileOut();
        }

        public function isReadMode() {
                return false;
        }

        public function getAllowedParams() {
                return array(
                        'format' => array(
                                ApiBase::PARAM_DFLT => ApiMain::API_DEFAULT_FORMAT,
                                ApiBase::PARAM_TYPE => $this->mFormatNames
                        ),
                        'action' => array(
                                ApiBase::PARAM_DFLT => 'help',
                                ApiBase::PARAM_TYPE => $this->mModuleNames
                        ),
                        'version' => false,
                        'maxlag'  => array(
                                ApiBase::PARAM_TYPE => 'integer'
                        ),
                        'smaxage' => array(
                                ApiBase::PARAM_TYPE => 'integer',
                                ApiBase::PARAM_DFLT => 0
                        ),
                        'maxage' => array(
                                ApiBase::PARAM_TYPE => 'integer',
                                ApiBase::PARAM_DFLT => 0
                        ),
                        'requestid' => null,
                        'servedby'  => false,
                        'origin' => null,
                );
        }

        public function getParamDescription() {
                return array(
                        'format' => 'The format of the output',
                        'action' => 'What action you would like to perform. See below for module help',
                        'version' => 'When showing help, include version for each module',
                        'maxlag' => array(
                                'Maximum lag can be used when MediaWiki is installed on a database replicated cluster.',
                                'To save actions causing any more site replication lag, this parameter can make the client',
                                'wait until the replication lag is less than the specified value.',
                                'In case of a replag error, a HTTP 503 error is returned, with the message like',
                                '"Waiting for $host: $lag seconds lagged\n".',
                                'See https://www.mediawiki.org/wiki/Manual:Maxlag_parameter for more information',
                        ),
                        'smaxage' => 'Set the s-maxage header to this many seconds. Errors are never cached',
                        'maxage' => 'Set the max-age header to this many seconds. Errors are never cached',
                        'requestid' => 'Request ID to distinguish requests. This will just be output back to you',
                        'servedby' => 'Include the hostname that served the request in the results. Unconditionally shown on error',
                        'origin' => array(
                                'When accessing the API using a cross-domain AJAX request (CORS), set this to the originating domain.',
                                'This must match one of the origins in the Origin: header exactly, so it has to be set to something like http://en.wikipedia.org or https://meta.wikimedia.org .',
                                'If this parameter does not match the Origin: header, a 403 response will be returned.',
                                'If this parameter matches the Origin: header and the origin is whitelisted, an Access-Control-Allow-Origin header will be set.',
                        ),
                );
        }

        public function getDescription() {
                return array(
                        '',
                        '',
                        '**********************************************************************************************************',
                        '**                                                                                                      **',
                        '**                      This is an auto-generated MediaWiki API documentation page                      **',
                        '**                                                                                                      **',
                        '**                                     Documentation and Examples:                                      **',
                        '**                                  https://www.mediawiki.org/wiki/API                                  **',
                        '**                                                                                                      **',
                        '**********************************************************************************************************',
                        '',
                        'Status:                All features shown on this page should be working, but the API',
                        '                       is still in active development, and may change at any time.',
                        '                       Make sure to monitor our mailing list for any updates',
                        '',
                        'Erroneous requests:    When erroneous requests are sent to the API, a HTTP header will be sent',
                        '                       with the key "MediaWiki-API-Error" and then both the value of the',
                        '                       header and the error code sent back will be set to the same value',
                        '',
                        '                       In the case of an invalid action being passed, these will have a value',
                        '                       of "unknown_action"',
                        '',
                        '                       For more information see https://www.mediawiki.org/wiki/API:Errors_and_warnings',
                        '',
                        'Documentation:         https://www.mediawiki.org/wiki/API:Main_page',
                        'FAQ                    https://www.mediawiki.org/wiki/API:FAQ',
                        'Mailing list:          https://lists.wikimedia.org/mailman/listinfo/mediawiki-api',
                        'Api Announcements:     https://lists.wikimedia.org/mailman/listinfo/mediawiki-api-announce',
                        'Bugs & Requests:       https://bugzilla.wikimedia.org/buglist.cgi?component=API&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&order=bugs.delta_ts',
                        '',
                        '',
                        '',
                        '',
                        '',
                );
        }

        public function getPossibleErrors() {
                return array_merge( parent::getPossibleErrors(), array(
                        array( 'readonlytext' ),
                        array( 'code' => 'unknown_format', 'info' => 'Unrecognized format: format' ),
                        array( 'code' => 'unknown_action', 'info' => 'The API requires a valid action parameter' ),
                        array( 'code' => 'maxlag', 'info' => 'Waiting for host: x seconds lagged' ),
                        array( 'code' => 'maxlag', 'info' => 'Waiting for a database server: x seconds lagged' ),
                ) );
        }

        protected function getCredits() {
                return array(
                        'API developers:',
                        '    Roan Kattouw "<Firstname>.<Lastname>@gmail.com" (lead developer Sep 2007-present)',
                        '    Victor Vasiliev - vasilvv at gee mail dot com',
                        '    Bryan Tong Minh - bryan . tongminh @ gmail . com',
                        '    Sam Reed - sam @ reedyboy . net',
                        '    Yuri Astrakhan "<Firstname><Lastname>@gmail.com" (creator, lead developer Sep 2006-Sep 2007)',
                        '',
                        'Please send your comments, suggestions and questions to [email protected]',
                        'or file a bug report at https://bugzilla.wikimedia.org/'
                );
        }

        public function setHelp( $help = true ) {
                $this->mPrinter->setHelp( $help );
        }

        public function makeHelpMsg() {
                global $wgMemc, $wgAPICacheHelpTimeout;
                $this->setHelp();
                // Get help text from cache if present
                $key = wfMemcKey( 'apihelp', $this->getModuleName(),
                        SpecialVersion::getVersion( 'nodb' ) .
                        $this->getShowVersions() );
                if ( $wgAPICacheHelpTimeout > 0 ) {
                        $cached = $wgMemc->get( $key );
                        if ( $cached ) {
                                return $cached;
                        }
                }
                $retval = $this->reallyMakeHelpMsg();
                if ( $wgAPICacheHelpTimeout > 0 ) {
                        $wgMemc->set( $key, $retval, $wgAPICacheHelpTimeout );
                }
                return $retval;
        }

        public function reallyMakeHelpMsg() {
                $this->setHelp();

                // Use parent to make default message for the main module
                $msg = parent::makeHelpMsg();

                $astriks = str_repeat( '*** ', 14 );
                $msg .= "\n\n$astriks Modules  $astriks\n\n";
                foreach ( array_keys( $this->mModules ) as $moduleName ) {
                        $module = new $this->mModules[$moduleName] ( $this, $moduleName );
                        $msg .= self::makeHelpMsgHeader( $module, 'action' );
                        $msg2 = $module->makeHelpMsg();
                        if ( $msg2 !== false ) {
                                $msg .= $msg2;
                        }
                        $msg .= "\n";
                }

                $msg .= "\n$astriks Permissions $astriks\n\n";
                foreach ( self::$mRights as $right => $rightMsg ) {
                        $groups = User::getGroupsWithPermission( $right );
                        $msg .= "* " . $right . " *\n  " . wfMsgReplaceArgs( $rightMsg[ 'msg' ], $rightMsg[ 'params' ] ) .
                                                "\nGranted to:\n  " . str_replace( '*', 'all', implode( ', ', $groups ) ) . "\n\n";

                }

                $msg .= "\n$astriks Formats  $astriks\n\n";
                foreach ( array_keys( $this->mFormats ) as $formatName ) {
                        $module = $this->createPrinterByName( $formatName );
                        $msg .= self::makeHelpMsgHeader( $module, 'format' );
                        $msg2 = $module->makeHelpMsg();
                        if ( $msg2 !== false ) {
                                $msg .= $msg2;
                        }
                        $msg .= "\n";
                }

                $msg .= "\n*** Credits: ***\n   " . implode( "\n   ", $this->getCredits() ) . "\n";

                return $msg;
        }

        public static function makeHelpMsgHeader( $module, $paramName ) {
                $modulePrefix = $module->getModulePrefix();
                if ( strval( $modulePrefix ) !== '' ) {
                        $modulePrefix = "($modulePrefix) ";
                }

                return "* $paramName={$module->getModuleName()} $modulePrefix*";
        }

        private $mCanApiHighLimits = null;

        public function canApiHighLimits() {
                if ( !isset( $this->mCanApiHighLimits ) ) {
                        $this->mCanApiHighLimits = $this->getUser()->isAllowed( 'apihighlimits' );
                }

                return $this->mCanApiHighLimits;
        }

        public function getShowVersions() {
                return $this->mShowVersions;
        }

        public function getVersion() {
                $vers = array();
                $vers[] = 'MediaWiki: ' . SpecialVersion::getVersion() . "\n    https://svn.wikimedia.org/viewvc/mediawiki/trunk/phase3/";
                $vers[] = __CLASS__ . ': $Id$';
                $vers[] = ApiBase::getBaseVersion();
                $vers[] = ApiFormatBase::getBaseVersion();
                $vers[] = ApiQueryBase::getBaseVersion();
                return $vers;
        }

        protected function addModule( $mdlName, $mdlClass ) {
                $this->mModules[$mdlName] = $mdlClass;
        }

        protected function addFormat( $fmtName, $fmtClass ) {
                $this->mFormats[$fmtName] = $fmtClass;
        }

        function getModules() {
                return $this->mModules;
        }

        public function getFormats() {
                return $this->mFormats;
        }
}

class UsageException extends MWException {

        private $mCodestr;

        private $mExtraData;

        public function __construct( $message, $codestr, $code = 0, $extradata = null ) {
                parent::__construct( $message, $code );
                $this->mCodestr = $codestr;
                $this->mExtraData = $extradata;
        }

        public function getCodeString() {
                return $this->mCodestr;
        }

        public function getMessageArray() {
                $result = array(
                        'code' => $this->mCodestr,
                        'info' => $this->getMessage()
                );
                if ( is_array( $this->mExtraData ) ) {
                        $result = array_merge( $result, $this->mExtraData );
                }
                return $result;
        }

        public function __toString() {
                return "{$this->getCodeString()}: {$this->getMessage()}";
        }
}