Module.php

Go to the documentation of this file.

<?php
 
namespace MediaWiki\Rest\Module;
 
use LogicException;
use MediaWiki\HookContainer\HookContainer;
use MediaWiki\Profiler\ProfilingContext;
use MediaWiki\Rest\BasicAccess\BasicAuthorizerInterface;
use MediaWiki\Rest\CorsUtils;
use MediaWiki\Rest\Handler;
use MediaWiki\Rest\Hook\HookRunner;
use MediaWiki\Rest\HttpException;
use MediaWiki\Rest\LocalizedHttpException;
use MediaWiki\Rest\PathTemplateMatcher\ModuleConfigurationException;
use MediaWiki\Rest\Reporter\ErrorReporter;
use MediaWiki\Rest\RequestInterface;
use MediaWiki\Rest\ResponseException;
use MediaWiki\Rest\ResponseFactory;
use MediaWiki\Rest\ResponseInterface;
use MediaWiki\Rest\Router;
use MediaWiki\Rest\Validator\Validator;
use Throwable;
use Wikimedia\Message\MessageValue;
use Wikimedia\ObjectFactory\ObjectFactory;
use Wikimedia\Stats\StatsFactory;
use Wikimedia\Timestamp\ConvertibleTimestamp;
 
abstract class Module {
 
    public const CACHE_CONFIG_HASH_KEY = 'CONFIG-HASH';
 
    private Router $router;
    protected string $pathPrefix;
    protected ResponseFactory $responseFactory;
    private BasicAuthorizerInterface $basicAuth;
    private ObjectFactory $objectFactory;
    private Validator $restValidator;
    private ErrorReporter $errorReporter;
    private HookContainer $hookContainer;
 
    private StatsFactory $stats;
    private ?CorsUtils $cors = null;
    private ?HookRunner $hookRunner = null;
 
    public function __construct(
        Router $router,
        string $pathPrefix,
        ResponseFactory $responseFactory,
        BasicAuthorizerInterface $basicAuth,
        ObjectFactory $objectFactory,
        Validator $restValidator,
        ErrorReporter $errorReporter,
        HookContainer $hookContainer
    ) {
        $this->router = $router;
        $this->pathPrefix = $pathPrefix;
        $this->responseFactory = $responseFactory;
        $this->basicAuth = $basicAuth;
        $this->objectFactory = $objectFactory;
        $this->restValidator = $restValidator;
        $this->errorReporter = $errorReporter;
        $this->hookContainer = $hookContainer;
 
        $this->stats = StatsFactory::newNull();
    }
 
    public function getPathPrefix(): string {
        return $this->pathPrefix;
    }
 
    abstract public function getCacheData(): array;
 
    abstract public function initFromCacheData( array $cacheData ): bool;
 
    public function getHandlerForPath(
        string $path,
        RequestInterface $request,
        bool $initForExecute = false
    ): Handler {
        $requestMethod = strtoupper( $request->getMethod() );
 
        $match = $this->findHandlerMatch( $path, $requestMethod );
 
        if ( !$match['found'] && $requestMethod === 'HEAD' ) {
            // For a HEAD request, execute the GET handler instead if one exists.
            $match = $this->findHandlerMatch( $path, 'GET' );
        }
 
        if ( !$match['found'] ) {
            $this->throwNoMatch(
                $path,
                $request->getMethod(),
                $match['methods'] ?? []
            );
        }
 
        if ( isset( $match['handler'] ) ) {
            $handler = $match['handler'];
        } elseif ( isset( $match['spec'] ) ) {
            $handler = $this->instantiateHandlerObject( $match['spec'] );
        } else {
            throw new LogicException(
                'Match does not specify a handler instance or object spec.'
            );
        }
 
        // For backwards compatibility only. Handlers should get the path by
        // calling getPath(), not from the config array.
        $config = $match['config'] ?? [];
        $config['path'] ??= $match['path'];
 
        $openApiSpec = $match['openApiSpec'] ?? [];
 
        // Provide context about the module
        $handler->initContext( $this, $match['path'], $config, $openApiSpec );
 
        // Inject services and state from the router
        $this->getRouter()->prepareHandler( $handler );
 
        if ( $initForExecute ) {
            // Use rawurldecode so a "+" in path params is not interpreted as a space character.
            $pathParams = array_map( 'rawurldecode', $match['params'] ?? [] );
            $request->setPathParams( $pathParams );
 
            $handler->initForExecute( $request );
        }
 
        return $handler;
    }
 
    public function getRouter(): Router {
        return $this->router;
    }
 
    abstract protected function findHandlerMatch(
        string $path,
        string $requestMethod
    ): array;
 
    protected function throwNoMatch( string $path, string $method, array $allowed ): never {
        // Check for CORS Preflight. This response will *not* allow the request unless
        // an Access-Control-Allow-Origin header is added to this response.
        if ( $this->cors && $method === 'OPTIONS' && $allowed ) {
            // IDEA: Create a CorsHandler, which getHandlerForPath can return in this case.
            $response = $this->cors->createPreflightResponse( $allowed );
            throw new ResponseException( $response );
        }
 
        if ( $allowed ) {
            // There are allowed methods for this patch, so reply with Method Not Allowed.
            $response = $this->responseFactory->createLocalizedHttpError( 405,
                ( new MessageValue( 'rest-wrong-method' ) )
                    ->textParams( $method )
                    ->commaListParams( $allowed )
                    ->numParams( count( $allowed ) )
            );
            $response->setHeader( 'Allow', $allowed );
            throw new ResponseException( $response );
        } else {
            // There are no allowed methods for this path, so the path was not found at all.
            $msg = ( new MessageValue( 'rest-no-match' ) )
                ->plaintextParams( $path );
            throw new LocalizedHttpException( $msg, 404 );
        }
    }
 
    private function runRestCheckCanExecuteHook(
        Handler $handler,
        string $path,
        RequestInterface $request
    ): void {
        $this->hookRunner ??= new HookRunner( $this->hookContainer );
        $error = null;
        $canExecute = $this->hookRunner->onRestCheckCanExecute( $this, $handler, $path, $request, $error );
        if ( $canExecute !== ( $error === null ) ) {
            throw new LogicException(
                'Hook RestCheckCanExecute returned ' . ( $canExecute ? 'true' : 'false' )
                    . ' but ' . ( $error ? 'did' : 'did not' ) . ' set an error'
            );
        } elseif ( $error instanceof HttpException ) {
            throw $error;
        } elseif ( $error ) {
            throw new LogicException(
                'RestCheckCanExecute must set a HttpException when returning false, '
                    . 'but got ' . get_class( $error )
            );
        }
    }
 
    public function execute( string $path, RequestInterface $request ): ResponseInterface {
        $handler = null;
        $startTime = ConvertibleTimestamp::hrtime();
 
        try {
            $handler = $this->getHandlerForPath( $path, $request, true );
            $this->runRestCheckCanExecuteHook( $handler, $path, $request );
            $response = $this->executeHandler( $handler );
        } catch ( HttpException $e ) {
            $extraData = [];
            if ( $this->router->isRestbaseCompatEnabled( $request )
                && $e instanceof LocalizedHttpException
            ) {
                $extraData = $this->router->getRestbaseCompatErrorData( $request, $e );
            }
            $response = $this->responseFactory->createFromException( $e, $extraData );
        } catch ( Throwable $e ) {
            // Note that $handler is allowed to be null here.
            $this->errorReporter->reportError( $e, $handler, $request );
            $response = $this->responseFactory->createFromException( $e );
        }
 
        $this->recordMetrics( $handler, $request, $response, $startTime );
 
        return $response;
    }
 
    private function recordMetrics(
        ?Handler $handler,
        RequestInterface $request,
        ResponseInterface $response,
        float $startTime
    ) {
        $latency = ConvertibleTimestamp::hrtime() - $startTime;
 
        // NOTE: The "/" prefix is for consistency with old logs. It's rather ugly.
        $pathForMetrics = $this->getPathPrefix();
 
        if ( $pathForMetrics !== '' ) {
            $pathForMetrics = '/' . $pathForMetrics;
        }
 
        $pathForMetrics .= $handler ? $handler->getPath() : '/UNKNOWN';
 
        // Replace any characters that may have a special meaning in the metrics DB.
        $pathForMetrics = strtr( $pathForMetrics, '{}:/.', '---__' );
 
        $statusCode = $response->getStatusCode();
        $requestMethod = $request->getMethod();
        if ( $statusCode >= 400 ) {
            // count how often we return which error code
            $this->stats->getCounter( 'rest_api_errors_total' )
                ->setLabel( 'path', $pathForMetrics )
                ->setLabel( 'method', $requestMethod )
                ->setLabel( 'status', "$statusCode" )
                ->increment();
        } else {
            // measure how long it takes to generate a response
            $this->stats->getTiming( 'rest_api_latency_seconds' )
                ->setLabel( 'path', $pathForMetrics )
                ->setLabel( 'method', $requestMethod )
                ->setLabel( 'status', "$statusCode" )
                ->observeNanoseconds( $latency );
        }
 
        // New unified metrics for the API
        // Only record those if there's a handler
        if ( !$handler ) {
            return;
        }
        $moduleDescription = $this->getModuleDescription();
 
        $metricsLabels = [
            'api_module' => $moduleDescription['moduleId'],
            // as a starting point, we'll use the Handler class name for the endpoint
            'api_endpoint' => $handler::class,
            'path' => $pathForMetrics,
            'method' => $requestMethod,
            'status' => "$statusCode",
        ];
 
        $approvedLabels = [
            'api_module',
            'api_endpoint',
            'path',
            'method',
            'status',
        ];
 
        // Hit metrics
        $metricHitStats = $this->stats->getCounter( 'rest_api_modules_hit_total' )
            ->setLabel( 'api_type', 'REST_API' );
        // Iterate over the approved labels and set the labels for the metric
        foreach ( $approvedLabels as $label ) {
            // Set a fallback value for empty strings
            $value = (
                array_key_exists( $label, $metricsLabels ) &&
                is_string( $metricsLabels[$label] ) &&
                trim( $metricsLabels[$label] ) !== ''
            ) ? $metricsLabels[$label] : 'EMPTY_VALUE';
 
            $metricHitStats->setLabel( $label, $value );
        }
        $metricHitStats->increment();
 
        // Latency metrics
        $metricLatencyStats = $this->stats->getTiming( 'rest_api_modules_latency' )
            ->setLabel( 'api_type', 'REST_API' );
        // Iterate over the approved labels and set the labels for the metric
        foreach ( $approvedLabels as $label ) {
            // Set a fallback value for empty strings
            $value = (
                array_key_exists( $label, $metricsLabels ) &&
                is_string( $metricsLabels[$label] ) &&
                trim( $metricsLabels[$label] ) !== ''
            ) ? $metricsLabels[$label] : 'EMPTY_VALUE';
 
            $metricLatencyStats->setLabel( $label, $value );
        }
        $metricLatencyStats->observeNanoseconds( $latency );
    }
 
    abstract public function getDefinedPaths(): array;
 
    abstract public function getAllowedMethods( string $relPath ): array;
 
    protected function instantiateHandlerObject( array $spec ): Handler {
        $handler = $this->objectFactory->createObject(
            $spec,
            [ 'assertClass' => Handler::class ]
        );
 
        return $handler;
    }
 
    protected function executeHandler( Handler $handler ): ResponseInterface {
        ProfilingContext::singleton()->init( MW_ENTRY_POINT, $handler->getPath() );
        // Check for basic authorization, to avoid leaking data from private wikis
        $authResult = $this->basicAuth->authorize( $handler->getRequest(), $handler );
        if ( $authResult ) {
            return $this->responseFactory->createHttpError( 403, [ 'error' => $authResult ] );
        }
 
        // Check session (and session provider)
        $handler->checkSession();
 
        // Validate the parameters
        $handler->validate( $this->restValidator );
 
        // Check conditional request headers
        $earlyResponse = $handler->checkPreconditions();
        if ( $earlyResponse ) {
            return $earlyResponse;
        }
 
        // Run the main part of the handler
        $response = $handler->execute();
        if ( !( $response instanceof ResponseInterface ) ) {
            $response = $this->responseFactory->createFromReturnValue( $response );
        }
 
        // Deprecation header per RFC 9745
        $handler->applyDeprecationHeader( $response );
 
        // Set Last-Modified and ETag headers in the response if available
        $handler->applyConditionalResponseHeaders( $response );
 
        $handler->applyCacheControl( $response );
 
        return $response;
    }
 
    public function setCors( CorsUtils $cors ): self {
        $this->cors = $cors;
 
        return $this;
    }
 
    public function setStats( StatsFactory $stats ): self {
        $this->stats = $stats;
 
        return $this;
    }
 
    public static function loadJsonFile( string $fileName ): array {
        $json = file_get_contents( $fileName );
        if ( $json === false ) {
            throw new ModuleConfigurationException(
                "Failed to load file `$fileName`"
            );
        }
 
        $spec = json_decode( $json, true );
 
        if ( !is_array( $spec ) ) {
            throw new ModuleConfigurationException(
                "Failed to parse `$fileName` as a JSON object"
            );
        }
 
        return $spec;
    }
 
    public function getOpenApiInfo() {
        return [];
    }
 
    public function getModuleDescription(): array {
        // TODO: Include the designated audience (T366567).
        // Note that each module object is designated for only one audience,
        // even if the spec allows multiple.
        $moduleId = $this->getPathPrefix();
 
        // Fields from openApiSpec info to include.
        // Note that mwapi-1.1 and earlier are based on OAS 3.0, so they don't support the
        // "summary" property introduced in 3.1.
        $infoFields = [ 'version', 'title', 'description', 'deprecationSettings' ];
 
        return [
            'moduleId' => $moduleId,
            'info' => array_intersect_key(
                $this->getOpenApiInfo(),
                array_flip( $infoFields )
            ),
            'base' => $this->getRouter()->getRouteUrl(
                '/' . $moduleId
            ),
            'spec' => $this->getRouter()->getRouteUrl(
                '/specs/v0/module/{module}', // hard-coding this here isn't very pretty
                [ 'module' => $moduleId == '' ? '-' : $moduleId ]
            )
        ];
    }
}