RouteFileModule.php

Go to the documentation of this file.

<?php
 
namespace MediaWiki\Rest\Module;
 
use AppendIterator;
use ArrayIterator;
use Iterator;
use LogicException;
use MediaWiki\Rest\BasicAccess\BasicAuthorizerInterface;
use MediaWiki\Rest\Handler\RedirectHandler;
use MediaWiki\Rest\PathTemplateMatcher\ModuleConfigurationException;
use MediaWiki\Rest\PathTemplateMatcher\PathMatcher;
use MediaWiki\Rest\Reporter\ErrorReporter;
use MediaWiki\Rest\ResponseFactory;
use MediaWiki\Rest\RouteDefinitionException;
use MediaWiki\Rest\Router;
use MediaWiki\Rest\Validator\Validator;
use Wikimedia\ObjectFactory\ObjectFactory;
 
class RouteFileModule extends Module {
 
    private array $routeFiles;
 
    private array $extraRoutes;
 
    private ?array $routesFromFiles = null;
 
    private ?array $routeFileTimestamps = null;
 
    private ?string $configHash = null;
 
    private ?array $matchers = null;
 
    public function __construct(
        array $routeFiles,
        array $extraRoutes,
        Router $router,
        string $pathPrefix,
        ResponseFactory $responseFactory,
        BasicAuthorizerInterface $basicAuth,
        ObjectFactory $objectFactory,
        Validator $restValidator,
        ErrorReporter $errorReporter
    ) {
        parent::__construct(
            $router,
            $pathPrefix,
            $responseFactory,
            $basicAuth,
            $objectFactory,
            $restValidator,
            $errorReporter
        );
        $this->routeFiles = $routeFiles;
        $this->extraRoutes = $extraRoutes;
    }
 
    public function getCacheData(): array {
        $cacheData = [];
 
        foreach ( $this->getMatchers() as $method => $matcher ) {
            $cacheData[$method] = $matcher->getCacheData();
        }
 
        $cacheData[self::CACHE_CONFIG_HASH_KEY] = $this->getConfigHash();
        return $cacheData;
    }
 
    public function initFromCacheData( array $cacheData ): bool {
        if ( $cacheData[self::CACHE_CONFIG_HASH_KEY] !== $this->getConfigHash() ) {
            return false;
        }
 
        unset( $cacheData[self::CACHE_CONFIG_HASH_KEY] );
        $this->matchers = [];
 
        foreach ( $cacheData as $method => $data ) {
            $this->matchers[$method] = PathMatcher::newFromCache( $data );
        }
 
        return true;
    }
 
    private function getConfigHash(): string {
        if ( $this->configHash === null ) {
            $this->configHash = md5( json_encode( [
                'version' => 5,
                'extraRoutes' => $this->extraRoutes,
                'fileTimestamps' => $this->getRouteFileTimestamps()
            ] ) );
        }
        return $this->configHash;
    }
 
    private function getRoutesFromFiles(): array {
        if ( $this->routesFromFiles !== null ) {
            return $this->routesFromFiles;
        }
 
        $this->routesFromFiles = [];
        $this->routeFileTimestamps = [];
        foreach ( $this->routeFiles as $fileName ) {
            $this->routeFileTimestamps[$fileName] = filemtime( $fileName );
 
            $routes = $this->loadRoutes( $fileName );
 
            $this->routesFromFiles = array_merge( $this->routesFromFiles, $routes );
        }
 
        return $this->routesFromFiles;
    }
 
    private function loadRoutes( string $fileName ) {
        $spec = $this->loadJsonFile( $fileName );
 
        if ( isset( $spec['routes'] ) ) {
            if ( !isset( $spec['module'] ) ) {
                throw new ModuleConfigurationException(
                    "Missing module name in $fileName"
                );
            }
 
            if ( $spec['module'] !== $this->pathPrefix ) {
                // The Router gave us a route file that doesn't match the module name.
                // This is a programming error, the Router should get this right.
                throw new LogicException(
                    "Module name mismatch in $fileName: " .
                    "expected {$this->pathPrefix} but got {$spec['module']}."
                );
            }
 
            // intermediate format with meta-data
            $routes = $spec['routes'];
        } else {
            // old, flat format
            $routes = $spec;
        }
 
        return $routes;
    }
 
    private function getRouteFileTimestamps(): array {
        if ( $this->routeFileTimestamps === null ) {
            $this->routeFileTimestamps = [];
            foreach ( $this->routeFiles as $fileName ) {
                $this->routeFileTimestamps[$fileName] = filemtime( $fileName );
            }
        }
        return $this->routeFileTimestamps;
    }
 
    public function getDefinedPaths(): array {
        $paths = [];
        foreach ( $this->getAllRoutes() as $spec ) {
            $key = $spec['path'];
 
            $methods = isset( $spec['method'] ) ? (array)$spec['method'] : [ 'GET' ];
 
            $paths[$key] = array_merge( $paths[$key] ?? [], $methods );
        }
 
        return $paths;
    }
 
    private function getAllRoutes() {
        $iterator = new AppendIterator;
        $iterator->append( new ArrayIterator( $this->getRoutesFromFiles() ) );
        $iterator->append( new ArrayIterator( $this->extraRoutes ) );
        return $iterator;
    }
 
    private function getMatchers() {
        if ( $this->matchers === null ) {
            $routeDefs = $this->getAllRoutes();
 
            $matchers = [];
 
            foreach ( $routeDefs as $spec ) {
                $methods = $spec['method'] ?? [ 'GET' ];
                if ( !is_array( $methods ) ) {
                    $methods = [ $methods ];
                }
                foreach ( $methods as $method ) {
                    if ( !isset( $matchers[$method] ) ) {
                        $matchers[$method] = new PathMatcher;
                    }
                    $matchers[$method]->add( $spec['path'], $spec );
                }
            }
            $this->matchers = $matchers;
        }
 
        return $this->matchers;
    }
 
    public function findHandlerMatch(
        string $path,
        string $requestMethod
    ): array {
        $matchers = $this->getMatchers();
        $matcher = $matchers[$requestMethod] ?? null;
        $match = $matcher ? $matcher->match( $path ) : null;
 
        if ( !$match ) {
            // Return allowed methods, to support CORS and 405 responses.
            return [
                'found' => false,
                'methods' => $this->getAllowedMethods( $path ),
            ];
        } else {
            $spec = $match['userData'];
 
            if ( !isset( $spec['class'] ) && !isset( $spec['factory'] ) ) {
                // Inject well known handler class for shorthand definition
                if ( isset( $spec['redirect'] ) ) {
                    $spec['class'] = RedirectHandler::class;
                } else {
                    throw new RouteDefinitionException(
                        'Route handler definition must specify "class" or ' .
                        '"factory" or "redirect"'
                    );
                }
            }
 
            return [
                'found' => true,
                'spec' => $spec,
                'params' => $match['params'] ?? [],
                'config' => $spec,
                'path' => $spec['path'],
            ];
        }
    }
 
    public function getAllowedMethods( string $relPath ): array {
        $allowed = [];
        foreach ( $this->getMatchers() as $allowedMethod => $allowedMatcher ) {
            if ( $allowedMatcher->match( $relPath ) ) {
                $allowed[] = $allowedMethod;
            }
        }
 
        return array_unique(
            in_array( 'GET', $allowed ) ? array_merge( [ 'HEAD' ], $allowed ) : $allowed
        );
    }
 
}