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',
        'createaccount' => 'ApiCreateAccount',
        'query' => 'ApiQuery',
        'expandtemplates' => 'ApiExpandTemplates',
        'parse' => 'ApiParse',
        'opensearch' => 'ApiOpenSearch',
        'feedcontributions' => 'ApiFeedContributions',
        'feedrecentchanges' => 'ApiFeedRecentChanges',
        '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',
        'imagerotate' => 'ApiImageRotate',
        'revisiondelete' => 'ApiRevisionDelete',
    );

    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',
    );

    // @codingStandardsIgnoreStart String contenation on "msg" not allowed to break long line
    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 )
        )
    );
    // @codingStandardsIgnoreEnd

    private $mPrinter;

    private $mModuleMgr, $mResult;
    private $mAction;
    private $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, $wgAPIFormatModules;
        $this->mModuleMgr = new ApiModuleManager( $this );
        $this->mModuleMgr->addModules( self::$Modules, 'action' );
        $this->mModuleMgr->addModules( $wgAPIModules, 'action' );
        $this->mModuleMgr->addModules( self::$Formats, 'format' );
        $this->mModuleMgr->addModules( $wgAPIFormatModules, 'format' );

        $this->mResult = new ApiResult( $this );
        $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 ( !User::isEveryoneAllowed( 'read' ) ) {
            // 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 setCacheControl( $directives ) {
        $this->mCacheControl = $directives + $this->mCacheControl;
    }

    public function createPrinterByName( $format ) {
        $printer = $this->mModuleMgr->getModule( $format, 'format' );
        if ( $printer === null ) {
            $this->dieUsage( "Unrecognized format: {$format}", 'unknown_format' );
        }

        return $printer;
    }

    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;
        }

        // Exit here if the request method was OPTIONS
        // (assume there will be a followup GET or POST)
        if ( $this->getRequest()->getMethod() === 'OPTIONS' ) {
            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 ) {
            $this->handleException( $e );
        }

        // 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 handleException( Exception $e ) {
        // Bug 63145: Rollback any open database transactions
        if ( !( $e instanceof UsageException ) ) {
            // UsageExceptions are intentional, so don't rollback if that's the case
            MWExceptionHandler::rollbackMasterChangesAndLog( $e );
        }

        // Allow extra cleanup and logging
        wfRunHooks( 'ApiMain::onException', array( $this, $e ) );

        // Log it
        if ( !( $e instanceof UsageException ) ) {
            MWExceptionHandler::logException( $e );
        }

        // Handle any kind of exception by outputting 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 );
    }

    public static function handleApiBeforeMainException( Exception $e ) {
        ob_start();

        try {
            $main = new self( RequestContext::getMain(), false );
            $main->handleException( $e );
        } catch ( Exception $e2 ) {
            // Nope, even that didn't work. Punt.
            throw $e;
        }

        // Log the request and reset cache headers
        $main->logRequest( 0 );
        $main->sendCacheHeaders();

        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;
        }

        $matchOrigin = self::matchOrigin(
            $originParam,
            $wgCrossSiteAJAXdomains,
            $wgCrossSiteAJAXdomainExceptions
        );

        if ( $matchOrigin ) {
            $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 ( !$this->mModuleMgr->isDefined( $value, 'format' ) ) {
                $value = self::API_DEFAULT_FORMAT;
            }

            $this->mPrinter = $this->createPrinterByName( $value );
        }

        // Printer may not be able to handle errors. This is particularly
        // likely if the module returns something for getCustomPrinter().
        if ( !$this->mPrinter->canPrintErrors() ) {
            $this->mPrinter->safeProfileOut();
            $this->mPrinter = $this->createPrinterByName( self::API_DEFAULT_FORMAT );
        }

        // Update raw mode flag for the selected printer.
        $result->setRawMode( $this->mPrinter->getNeedsRawData() );

        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" : ''
            );
        }

        // Remember all the warnings to re-add them later
        $oldResult = $result->getData();
        $warnings = isset( $oldResult['warnings'] ) ? $oldResult['warnings'] : null;

        $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() );
        }
        if ( $warnings !== null ) {
            $result->addValue( null, 'warnings', $warnings );
        }

        $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->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 = $this->mModuleMgr->getModule( $this->mAction, 'action' );
        if ( $module === null ) {
            $this->dieUsage( 'The API requires a valid action parameter', 'unknown_action' );
        }
        $moduleParams = $module->extractRequestParams();

        // Die if token required, but not provided
        $salt = $module->getTokenSalt();
        if ( $salt !== false ) {
            if ( !isset( $moduleParams['token'] ) ) {
                $this->dieUsageMsg( array( 'missingparam', 'token' ) );
            }

            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' );
                }

                $this->dieUsage( "Waiting for a database server: $lag seconds lagged", 'maxlag' );
            }
        }

        return true;
    }

    protected function checkExecutePermissions( $module ) {
        $user = $this->getUser();
        if ( $module->isReadMode() && !User::isEveryoneAllowed( 'read' ) &&
            !$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 checkAsserts( $params ) {
        if ( isset( $params['assert'] ) ) {
            $user = $this->getUser();
            switch ( $params['assert'] ) {
                case 'user':
                    if ( $user->isAnon() ) {
                        $this->dieUsage( 'Assertion that the user is logged in failed', 'assertuserfailed' );
                    }
                    break;
                case 'bot':
                    if ( !$user->isAllowed( 'bot' ) ) {
                        $this->dieUsage( 'Assertion that the user has the bot right failed', 'assertbotfailed' );
                    }
                    break;
            }
        }
    }

    protected function setupExternalResponse( $module, $params ) {
        if ( !$this->getRequest()->wasPosted() && $module->mustBePosted() ) {
            // Module requires POST. GET request might still be allowed
            // if $wgDebugApi is true, otherwise fail.
            $this->dieUsageMsgOrDebug( 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->mModule = $module;

        $this->checkExecutePermissions( $module );

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

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

        $this->checkAsserts( $params );

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

        $this->reportUnusedParams();

        if ( !$this->mInternalMode ) {
            //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, 'private' );
    }

    protected function encodeRequestLogValue( $s ) {
        static $table;
        if ( !$table ) {
            $chars = ';@$!*(),/:';
            $numChars = strlen( $chars );
            for ( $i = 0; $i < $numChars; $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 );
    }

    public function getUpload( $name ) {
        $this->mParamsUsed[$name] = true;

        return $this->getRequest()->getUpload( $name );
    }

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

        if ( !$this->mInternalMode ) {
            // Printer has not yet executed; don't warn that its parameters are unused
            $printerParams = array_map(
                array( $this->mPrinter, 'encodeParamName' ),
                array_keys( $this->mPrinter->getFinalParams() ?: array() )
            );
            $unusedParams = array_diff( $allParams, $paramsUsed, $printerParams );
        } else {
            $unusedParams = array_diff( $allParams, $paramsUsed );
        }

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

    protected function printResult( $isError ) {
        global $wgDebugAPI;
        if ( $wgDebugAPI !== false ) {
            $this->setWarning( 'SECURITY WARNING: $wgDebugAPI is enabled' );
        }

        $this->getResult()->cleanUpUTF8();
        $printer = $this->mPrinter;
        $printer->profileIn();

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

        $printer->initPrinter( $isHelp );

        $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->mModuleMgr->getNames( 'format' )
            ),
            'action' => array(
                ApiBase::PARAM_DFLT => 'help',
                ApiBase::PARAM_TYPE => $this->mModuleMgr->getNames( 'action' )
            ),
            '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
            ),
            'assert' => array(
                ApiBase::PARAM_TYPE => array( 'user', 'bot' )
            ),
            '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',
            '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, error code "maxlag" 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',
            'assert' => 'Verify the user is logged in if set to "user", or has the bot userright if "bot"',
            '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 be included in any pre-flight request, and',
                'therefore must be part of the request URI (not the POST body). 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' ),
            array( 'code' => 'assertuserfailed', 'info' => 'Assertion that the user is logged in failed' ),
            array(
                'code' => 'assertbotfailed',
                'info' => 'Assertion that the user has the bot right failed'
            ),
        ) );
    }

    protected function getCredits() {
        return array(
            'API developers:',
            '    Roan Kattouw (lead developer Sep 2007-2009)',
            '    Victor Vasiliev',
            '    Bryan Tong Minh',
            '    Sam Reed',
            '    Yuri Astrakhan (creator, lead developer Sep 2006-Sep 2007, 2012-present)',
            '',
            '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(),
            str_replace( ' ', '_', SpecialVersion::getVersion( 'nodb' ) ) );
        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 ( $this->mModuleMgr->getNames( 'action' ) as $name ) {
            $module = $this->mModuleMgr->getModule( $name );
            $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 ( $this->mModuleMgr->getNames( 'format' ) as $name ) {
            $module = $this->mModuleMgr->getModule( $name );
            $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() {
        wfDeprecated( __METHOD__, '1.21' );

        return false;
    }

    public function getModuleManager() {
        return $this->mModuleMgr;
    }

    protected function addModule( $name, $class ) {
        $this->getModuleManager()->addModule( $name, 'action', $class );
    }

    protected function addFormat( $name, $class ) {
        $this->getModuleManager()->addModule( $name, 'format', $class );
    }

    function getModules() {
        return $this->getModuleManager()->getNamesWithClasses( 'action' );
    }

    public function getFormats() {
        return $this->getModuleManager()->getNamesWithClasses( 'format' );
    }
}

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()}";
    }
}