Router.php

Go to the documentation of this file.

<?php
 
namespace MediaWiki\Rest;
 
use MediaWiki\Config\ServiceOptions;
use MediaWiki\HookContainer\HookContainer;
use MediaWiki\MainConfigNames;
use MediaWiki\MainConfigSchema;
use MediaWiki\Permissions\Authority;
use MediaWiki\Rest\BasicAccess\BasicAuthorizerInterface;
use MediaWiki\Rest\Module\ExtraRoutesModule;
use MediaWiki\Rest\Module\Module;
use MediaWiki\Rest\Module\SpecBasedModule;
use MediaWiki\Rest\PathTemplateMatcher\ModuleConfigurationException;
use MediaWiki\Rest\Reporter\ErrorReporter;
use MediaWiki\Rest\Validator\Validator;
use MediaWiki\Session\Session;
use Throwable;
use Wikimedia\Http\HttpStatus;
use Wikimedia\Message\MessageValue;
use Wikimedia\ObjectCache\BagOStuff;
use Wikimedia\ObjectFactory\ObjectFactory;
use Wikimedia\Stats\StatsFactory;
 
class Router {
    private const PREFIX_PATTERN = '!^/([-_.\w]+(?:/v\d+)?)(/.*)$!';
 
    private $routeFiles;
 
    private $extraRoutes;
 
    private $moduleMap = null;
 
    private $modules = [];
 
    private $moduleFileTimestamps = null;
 
    private $baseUrl;
 
    private $privateBaseUrl;
 
    private $rootPath;
 
    private $scriptPath;
 
    private $configHash = null;
 
    private $cors;
 
    private BagOStuff $cacheBag;
    private ResponseFactory $responseFactory;
    private BasicAuthorizerInterface $basicAuth;
    private Authority $authority;
    private ObjectFactory $objectFactory;
    private Validator $restValidator;
    private ErrorReporter $errorReporter;
    private HookContainer $hookContainer;
    private Session $session;
 
    private $stats = null;
 
    public const CONSTRUCTOR_OPTIONS = [
        MainConfigNames::CanonicalServer,
        MainConfigNames::InternalServer,
        MainConfigNames::RestPath,
        MainConfigNames::ScriptPath,
    ];
 
    public function __construct(
        array $routeFiles,
        array $extraRoutes,
        ServiceOptions $options,
        BagOStuff $cacheBag,
        ResponseFactory $responseFactory,
        BasicAuthorizerInterface $basicAuth,
        Authority $authority,
        ObjectFactory $objectFactory,
        Validator $restValidator,
        ErrorReporter $errorReporter,
        HookContainer $hookContainer,
        Session $session
    ) {
        $options->assertRequiredOptions( self::CONSTRUCTOR_OPTIONS );
 
        $this->routeFiles = $routeFiles;
        $this->extraRoutes = $extraRoutes;
        $this->baseUrl = $options->get( MainConfigNames::CanonicalServer );
        $this->privateBaseUrl = $options->get( MainConfigNames::InternalServer );
        $this->rootPath = $options->get( MainConfigNames::RestPath );
        $this->scriptPath = $options->get( MainConfigNames::ScriptPath );
        $this->cacheBag = $cacheBag;
        $this->responseFactory = $responseFactory;
        $this->basicAuth = $basicAuth;
        $this->authority = $authority;
        $this->objectFactory = $objectFactory;
        $this->restValidator = $restValidator;
        $this->errorReporter = $errorReporter;
        $this->hookContainer = $hookContainer;
        $this->session = $session;
    }
 
    private function getRelativePath( $path ) {
        $allowed = [
            $this->rootPath,
            MainConfigSchema::getDefaultRestPath( $this->scriptPath )
        ];
 
        foreach ( $allowed as $prefix ) {
            if ( str_starts_with( $path, $prefix ) ) {
                return substr( $path, strlen( $prefix ) );
            }
        }
 
        return false;
    }
 
    private function splitPath( string $fullPath ): array {
        $pathWithModule = $this->getRelativePath( $fullPath );
 
        if ( $pathWithModule === false ) {
            throw new LocalizedHttpException(
                ( new MessageValue( 'rest-prefix-mismatch' ) )
                    ->plaintextParams( $fullPath, $this->rootPath ),
                404
            );
        }
 
        if ( preg_match( self::PREFIX_PATTERN, $pathWithModule, $matches ) ) {
            [ , $module, $pathUnderModule ] = $matches;
        } else {
            // No prefix found in the given path, assume prefix-less module.
            $module = '';
            $pathUnderModule = $pathWithModule;
        }
 
        if ( $module !== '' && !$this->getModuleInfo( $module ) ) {
            // Prefix doesn't match any module, try the prefix-less module...
            // TODO: At some point in the future, we'll want to warn and redirect...
            $module = '';
            $pathUnderModule = $pathWithModule;
        }
 
        return [ $module, $pathUnderModule ];
    }
 
    private function fetchCachedModuleMap(): ?array {
        $moduleMapCacheKey = $this->getModuleMapCacheKey();
        $cacheData = $this->cacheBag->get( $moduleMapCacheKey );
        if ( $cacheData && $cacheData[Module::CACHE_CONFIG_HASH_KEY] === $this->getModuleMapHash() ) {
            unset( $cacheData[Module::CACHE_CONFIG_HASH_KEY] );
            return $cacheData;
        } else {
            return null;
        }
    }
 
    private function fetchCachedModuleData( string $module ): ?array {
        $moduleDataCacheKey = $this->getModuleDataCacheKey( $module );
        $cacheData = $this->cacheBag->get( $moduleDataCacheKey );
        return $cacheData ?: null;
    }
 
    private function cacheModuleMap( array $map ) {
        $map[Module::CACHE_CONFIG_HASH_KEY] = $this->getModuleMapHash();
        $moduleMapCacheKey = $this->getModuleMapCacheKey();
        $this->cacheBag->set( $moduleMapCacheKey, $map );
    }
 
    private function cacheModuleData( string $module, array $map ) {
        $moduleDataCacheKey = $this->getModuleDataCacheKey( $module );
        $this->cacheBag->set( $moduleDataCacheKey, $map );
    }
 
    private function getModuleDataCacheKey( string $module ): string {
        if ( $module === '' ) {
            // Proper key for the prefix-less module.
            $module = '-';
        }
        return $this->cacheBag->makeKey( __CLASS__, 'module', $module );
    }
 
    private function getModuleMapCacheKey(): string {
        return $this->cacheBag->makeKey( __CLASS__, 'map', '1' );
    }
 
    private function getModuleMapHash(): string {
        if ( $this->configHash === null ) {
            $this->configHash = md5( json_encode( [
                $this->extraRoutes,
                $this->getModuleFileTimestamps()
            ] ) );
        }
        return $this->configHash;
    }
 
    private function buildModuleMap(): array {
        $modules = [];
        $noPrefixFiles = [];
        $id = ''; // should not be used, make Phan happy
 
        foreach ( $this->routeFiles as $file ) {
            // NOTE: we end up loading the file here (for the meta-data) as well
            // as in the Module object (for the routes). But since we have
            // caching on both levels, that shouldn't matter.
            $spec = Module::loadJsonFile( $file );
 
            if ( isset( $spec['mwapi'] ) || isset( $spec['moduleId'] ) || isset( $spec['routes'] ) ) {
                // OpenAPI 3, with some extras like the "module" field
                if ( !isset( $spec['moduleId'] ) ) {
                    throw new ModuleConfigurationException(
                        "Missing 'moduleId' field in $file"
                    );
                }
 
                $id = $spec['moduleId'];
 
                $moduleInfo = [
                    'class' => SpecBasedModule::class,
                    'pathPrefix' => $id,
                    'specFile' => $file
                ];
            } else {
                // Old-style route file containing a flat list of routes.
                $noPrefixFiles[] = $file;
                $moduleInfo = null;
            }
 
            if ( $moduleInfo ) {
                if ( isset( $modules[$id] ) ) {
                    $otherFiles = implode( ' and ', $modules[$id]['routeFiles'] );
                    throw new ModuleConfigurationException(
                        "Duplicate module $id in $file, also used in $otherFiles"
                    );
                }
 
                $modules[$id] = $moduleInfo;
            }
        }
 
        // The prefix-less module will be used when no prefix is matched.
        // It provides a mechanism to integrate extra routes and route files
        // registered by extensions.
        if ( $noPrefixFiles || $this->extraRoutes ) {
            $modules[''] = [
                'class' => ExtraRoutesModule::class,
                'pathPrefix' => '',
                'routeFiles' => $noPrefixFiles,
                'extraRoutes' => $this->extraRoutes,
            ];
        }
 
        return $modules;
    }
 
    private function getModuleFileTimestamps() {
        if ( $this->moduleFileTimestamps === null ) {
            $this->moduleFileTimestamps = [];
            foreach ( $this->routeFiles as $fileName ) {
                $this->moduleFileTimestamps[$fileName] = filemtime( $fileName );
            }
        }
        return $this->moduleFileTimestamps;
    }
 
    private function getModuleMap(): array {
        if ( !$this->moduleMap ) {
            $map = $this->fetchCachedModuleMap();
 
            if ( !$map ) {
                $map = $this->buildModuleMap();
                $this->cacheModuleMap( $map );
            }
 
            $this->moduleMap = $map;
        }
        return $this->moduleMap;
    }
 
    private function getModuleInfo( string $module ): ?array {
        $map = $this->getModuleMap();
        return $map[$module] ?? null;
    }
 
    public function getModuleIds(): array {
        return array_keys( $this->getModuleMap() );
    }
 
    public function getModuleForPath( string $fullPath ): ?Module {
        [ $moduleName, ] = $this->splitPath( $fullPath );
        return $this->getModule( $moduleName );
    }
 
    public function getModule( string $name ): ?Module {
        if ( isset( $this->modules[$name] ) ) {
            return $this->modules[$name];
        }
 
        $info = $this->getModuleInfo( $name );
 
        if ( !$info ) {
            return null;
        }
 
        $module = $this->instantiateModule( $info, $name );
 
        $cacheData = $this->fetchCachedModuleData( $name );
 
        if ( $cacheData !== null ) {
            $cacheOk = $module->initFromCacheData( $cacheData );
        } else {
            $cacheOk = false;
        }
 
        if ( !$cacheOk ) {
            $cacheData = $module->getCacheData();
            $this->cacheModuleData( $name, $cacheData );
        }
 
        if ( $this->cors ) {
            $module->setCors( $this->cors );
        }
 
        if ( $this->stats ) {
            $module->setStats( $this->stats );
        }
 
        $this->modules[$name] = $module;
        return $module;
    }
 
    public function getRoutePath(
        string $routeWithModulePrefix,
        array $pathParams = [],
        array $queryParams = []
    ): string {
        $routeWithModulePrefix = $this->substPathParams( $routeWithModulePrefix, $pathParams );
        $path = $this->rootPath . $routeWithModulePrefix;
        return wfAppendQuery( $path, $queryParams );
    }
 
    public function getRouteUrl(
        string $routeWithModulePrefix,
        array $pathParams = [],
        array $queryParams = []
    ): string {
        return $this->baseUrl . $this->getRoutePath( $routeWithModulePrefix, $pathParams, $queryParams );
    }
 
    public function getPrivateRouteUrl(
        string $routeWithModulePrefix,
        array $pathParams = [],
        array $queryParams = []
    ): string {
        return $this->privateBaseUrl . $this->getRoutePath( $routeWithModulePrefix, $pathParams, $queryParams );
    }
 
    protected function substPathParams( string $route, array $pathParams ): string {
        foreach ( $pathParams as $param => $value ) {
            // NOTE: we use rawurlencode here, since execute() uses rawurldecode().
            // Spaces in path params must be encoded to %20 (not +).
            // Slashes must be encoded as %2F.
            $route = str_replace( '{' . $param . '}', rawurlencode( (string)$value ), $route );
        }
        return $route;
    }
 
    public function execute( RequestInterface $request ): ResponseInterface {
        try {
            $fullPath = $request->getUri()->getPath();
            $response = $this->doExecute( $fullPath, $request );
        } catch ( HttpException $e ) {
            $extraData = [];
            if ( $this->isRestbaseCompatEnabled( $request )
                && $e instanceof LocalizedHttpException
            ) {
                $extraData = $this->getRestbaseCompatErrorData( $request, $e );
            }
            $response = $this->responseFactory->createFromException( $e, $extraData );
        } catch ( Throwable $e ) {
            $this->errorReporter->reportError( $e, null, $request );
            $response = $this->responseFactory->createFromException( $e );
        }
 
        // TODO: Only send the vary header for handlers that opt into
        //       restbase compat!
        $this->varyOnRestbaseCompat( $response );
 
        return $response;
    }
 
    private function doExecute( string $fullPath, RequestInterface $request ): ResponseInterface {
        [ $modulePrefix, $path ] = $this->splitPath( $fullPath );
 
        // If there is no path at all, redirect to "/".
        // That's the minimal path that can be routed.
        if ( $modulePrefix === '' && $path === '' ) {
            $target = $this->getRoutePath( '/' );
            return $this->responseFactory->createRedirect( $target, 308 );
        }
 
        $module = $this->getModule( $modulePrefix );
 
        if ( !$module ) {
            throw new LocalizedHttpException(
                MessageValue::new( 'rest-unknown-module' )->plaintextParams( $modulePrefix ),
                404,
                [ 'prefix' => $modulePrefix ]
            );
        }
 
        return $module->execute( $path, $request );
    }
 
    public function prepareHandler( Handler $handler ) {
        // Injecting services in the Router class means we don't have to inject
        // them into each Module.
        $handler->initServices(
            $this->authority,
            $this->responseFactory,
            $this->hookContainer
        );
 
        $handler->initSession( $this->session );
    }
 
    public function setCors( CorsUtils $cors ): self {
        $this->cors = $cors;
 
        return $this;
    }
 
    public function setStats( StatsFactory $stats ): self {
        $this->stats = $stats;
 
        return $this;
    }
 
    private function instantiateModule( array $info, string $name ): Module {
        if ( $info['class'] === SpecBasedModule::class ) {
            $module = new SpecBasedModule(
                $info['specFile'],
                $this,
                $info['pathPrefix'] ?? $name,
                $this->responseFactory,
                $this->basicAuth,
                $this->objectFactory,
                $this->restValidator,
                $this->errorReporter,
                $this->hookContainer
            );
        } else {
            $module = new ExtraRoutesModule(
                $info['routeFiles'] ?? [],
                $info['extraRoutes'] ?? [],
                $this,
                $this->responseFactory,
                $this->basicAuth,
                $this->objectFactory,
                $this->restValidator,
                $this->errorReporter,
                $this->hookContainer
            );
        }
 
        return $module;
    }
 
    public function isRestbaseCompatEnabled( RequestInterface $request ): bool {
        // See T374136
        return $request->getHeaderLine( 'x-restbase-compat' ) === 'true';
    }
 
    private function varyOnRestbaseCompat( ResponseInterface $response ) {
        // See T374136
        $response->addHeader( 'Vary', 'x-restbase-compat' );
    }
 
    public function getRestbaseCompatErrorData( RequestInterface $request, LocalizedHttpException $e ): array {
        $msg = $e->getMessageValue();
 
        // Match error fields emitted by the RESTBase endpoints.
        // EntryPoint::getTextFormatters() ensures 'en' is always available.
        return [
            'type' => "MediaWikiError/" .
                str_replace( ' ', '_', HttpStatus::getMessage( $e->getCode() ) ),
            'title' => $msg->getKey(),
            'method' => strtolower( $request->getMethod() ),
            'detail' => $this->responseFactory->getFormattedMessage( $msg, 'en' ),
            'uri' => (string)$request->getUri()
        ];
    }
}