SpecBasedModule.php

Go to the documentation of this file.

<?php
 
namespace MediaWiki\Rest\Module;
 
use MediaWiki\HookContainer\HookContainer;
use MediaWiki\Rest\BasicAccess\BasicAuthorizerInterface;
use MediaWiki\Rest\Handler\RedirectHandler;
use MediaWiki\Rest\JsonLocalizer;
use MediaWiki\Rest\PathTemplateMatcher\ModuleConfigurationException;
use MediaWiki\Rest\Reporter\ErrorReporter;
use MediaWiki\Rest\RouteDefinitionException;
use MediaWiki\Rest\Router;
use MediaWiki\Rest\Validator\Validator;
use Wikimedia\ObjectFactory\ObjectFactory;
 
class SpecBasedModule extends MatcherBasedModule {
 
    private ?array $moduleDef = null;
 
    private ?int $routeFileTimestamp = null;
 
    private ?string $configHash = null;
 
    public function __construct(
        private readonly string $definitionFile,
        Router $router,
        string $pathPrefix,
        JsonLocalizer $jsonLocalizer,
        BasicAuthorizerInterface $basicAuth,
        ObjectFactory $objectFactory,
        Validator $restValidator,
        ErrorReporter $errorReporter,
        HookContainer $hookContainer,
    ) {
        parent::__construct(
            $router,
            $pathPrefix,
            $jsonLocalizer,
            $basicAuth,
            $objectFactory,
            $restValidator,
            $errorReporter,
            $hookContainer
        );
    }
 
    protected function getConfigHash(): string {
        if ( $this->configHash === null ) {
            $this->configHash = md5( json_encode( [
                'class' => __CLASS__,
                'version' => 1,
                'fileTimestamps' => $this->getRouteFileTimestamp()
            ] ) );
        }
        return $this->configHash;
    }
 
    private function getModuleDefinition(): array {
        if ( $this->moduleDef !== null ) {
            return $this->moduleDef;
        }
 
        $this->routeFileTimestamp = filemtime( $this->definitionFile );
        $this->moduleDef = static::loadModuleDefinition(
            $this->definitionFile,
            $this->getJsonLocalizer()
        );
 
        return $this->moduleDef;
    }
 
    public static function loadModuleDefinition( string $file, JsonLocalizer $localizer ): array {
        $moduleDef = static::loadJsonFile( $file );
 
        // This does not guarantee the file is a valid flat route file, just that it appears
        // to be of that format. Files containing only an empty array are assumed to be valid
        // flat route files containing no routes rather than malformed module definition files.
        // Some development flat route files in extensions, such as Wikibase's routes.dev.json,
        // may exist as placeholders but intentionally contain no routes.
        if ( array_is_list( $moduleDef ) ) {
            throw new ModuleFormatException(
                $file . ' appears to be a flat route file, not a module definition file.'
            );
        }
 
        // The array_is_list() call above confuses phan. Force phan to consider $mwapi to be of
        // the type we expect. Also check its type ourselves in code at runtime, just to be sure.
        $mwapi = $moduleDef['mwapi'] ?? null;
        '@phan-var ?string $mwapi';
 
        if ( !is_string( $mwapi ) ) {
            throw new ModuleConfigurationException(
                'Missing or malformed mwapi version field in ' . $file
            );
        }
 
        // Require a supported version of mwapi
        if ( version_compare( $mwapi, '1.0.0', '<' ) ||
            version_compare( $mwapi, '1.2.999', '>' )
        ) {
            throw new ModuleConfigurationException(
                "Unsupported mwapi version {$mwapi} in "
                . $file
            );
        }
 
        return $localizer->localizeJson( $moduleDef );
    }
 
    private function getRouteFileTimestamp(): int {
        if ( $this->routeFileTimestamp === null ) {
            $this->routeFileTimestamp = filemtime( $this->definitionFile );
        }
        return $this->routeFileTimestamp;
    }
 
    public function getDefinedPaths(): array {
        $paths = [];
        $moduleDef = $this->getModuleDefinition();
 
        foreach ( $moduleDef['paths'] as $path => $pSpec ) {
            $paths[$path] = [];
            foreach ( $pSpec as $method => $opSpec ) {
                $paths[$path][] = strtoupper( $method );
            }
        }
 
        return $paths;
    }
 
    protected function initRoutes(): void {
        $moduleDef = $this->getModuleDefinition();
 
        // The structure is similar to OpenAPI, see docs/rest/mwapi.1.0.json
        foreach ( $moduleDef['paths'] as $path => $pathSpec ) {
            foreach ( $pathSpec as $method => $opSpec ) {
                $info = $this->makeRouteInfo( $path, $opSpec );
                $this->addRoute( $method, $path, $info );
            }
        }
    }
 
    private function makeRouteInfo( string $path, array $opSpec ): array {
        static $objectSpecKeys = [
            'class',
            'factory',
            'services',
            'optional_services',
            'args',
            'adapter', // for known adapter classes
        ];
 
        static $oasKeys = [
            'parameters',
            'responses',
            'summary',
            'description',
            'tags',
            'externalDocs',
            'deprecationSettings',
            'operationId',
        ];
 
        if ( isset( $opSpec['redirect'] ) ) {
            // Redirect shorthand
            $opSpec['handler'] = [
                'class' => RedirectHandler::class,
                'redirect' => $opSpec['redirect'],
            ];
            unset( $opSpec['redirect'] );
        }
 
        $handlerSpec = $opSpec['handler'] ?? null;
        if ( !$handlerSpec ) {
            throw new RouteDefinitionException( 'Missing handler spec' );
        }
 
        $info = [
            'spec' => array_intersect_key( $handlerSpec, array_flip( $objectSpecKeys ) ),
            'config' => array_diff_key( $handlerSpec, array_flip( $objectSpecKeys ) ),
            'openApiSpec' => array_intersect_key( $opSpec, array_flip( $oasKeys ) ),
            'path' => $path,
        ];
 
        return $info;
    }
 
    public function getOpenApiInfo() {
        $def = $this->getModuleDefinition();
        return $def['info'] ?? [];
    }
 
    public function getOpenApiExternalDocs(): array {
        $def = $this->getModuleDefinition();
        return $def['externalDocs'] ?? [];
    }
 
    public function getOpenApiTags(): array {
        $def = $this->getModuleDefinition();
        return $def['tags'] ?? [];
    }
 
}