Handler.php

Go to the documentation of this file.

<?php
 
namespace MediaWiki\Rest;
 
use DateTime;
use MediaWiki\Debug\MWDebug;
use MediaWiki\HookContainer\HookContainer;
use MediaWiki\HookContainer\HookRunner;
use MediaWiki\Permissions\Authority;
use MediaWiki\Rest\Module\Module;
use MediaWiki\Rest\Validator\BodyValidator;
use MediaWiki\Rest\Validator\NullBodyValidator;
use MediaWiki\Rest\Validator\Validator;
use MediaWiki\Session\Session;
use UtfNormal\Validator as UtfNormalValidator;
use Wikimedia\Assert\Assert;
use Wikimedia\Message\MessageValue;
use Wikimedia\ParamValidator\ParamValidator;
 
abstract class Handler {
 
    public const KNOWN_PARAM_SOURCES = Validator::KNOWN_PARAM_SOURCES;
 
    public const PARAM_SOURCE = Validator::PARAM_SOURCE;
 
    public const PARAM_DESCRIPTION = Validator::PARAM_DESCRIPTION;
 
    public const PARAM_EXAMPLE = Validator::PARAM_EXAMPLE;
 
    public const OPENAPI_DESCRIPTION_KEY = 'description';
 
    private const MISSING_BODY_EXAMPLE = 'missing_example';
 
    private ?Module $module = null;
    private ?RequestInterface $request = null;
    private ?Authority $authority = null;
    private string $path;
    private array $config;
    private array $openApiSpec;
    private ?ResponseFactory $responseFactory = null;
    private ?array $validatedParams = null;
 
    private $validatedBody;
    private ?ConditionalHeaderUtil $conditionalHeaderUtil = null;
    private HookContainer $hookContainer;
    private ?Session $session = null;
    private HookRunner $hookRunner;
 
    final public function initContext(
        Module $module,
        string $path,
        array $routeConfig,
        array $openApiSpec = []
    ) {
        Assert::precondition(
            $this->authority === null,
            'initContext() must be called before initServices()'
        );
 
        $this->module = $module;
        $this->path = $path;
        $this->config = $routeConfig;
        $this->openApiSpec = $openApiSpec;
    }
 
    final public function initServices(
        Authority $authority, HookContainer $hookContainer
    ) {
        // Warn if a subclass overrides getBodyValidator()
        MWDebug::detectDeprecatedOverride(
            $this,
            __CLASS__,
            'getBodyValidator',
            '1.43'
        );
 
        Assert::precondition(
            $this->module !== null,
            'initServices() must not be called before initContext()'
        );
        Assert::precondition(
            $this->session === null,
            'initServices() must be called before initSession()'
        );
 
        $this->authority = $authority;
        $this->hookContainer = $hookContainer;
        $this->hookRunner = new HookRunner( $hookContainer );
    }
 
    final public function initSession( Session $session ) {
        Assert::precondition(
            $this->authority !== null,
            'initSession() must not be called before initContext()'
        );
        Assert::precondition(
            $this->request === null,
            'initSession() must be called before initForExecute()'
        );
 
        $this->session = $session;
    }
 
    final public function initForExecute(
        RequestInterface $request,
        ResponseFactory $responseFactory
    ) {
        Assert::precondition(
            $this->session !== null,
            'initForExecute() must not be called before initSession()'
        );
 
        if ( $request->getParsedBody() === null ) {
            $this->processRequestBody( $request );
        }
 
        $this->request = $request;
        $this->responseFactory = $responseFactory;
 
        $this->postInitSetup();
    }
 
    private function processRequestBody( RequestInterface $request ) {
        // fail if the request method is in NO_BODY_METHODS but has body
        $requestMethod = $request->getMethod();
        if ( in_array( $requestMethod, RequestInterface::NO_BODY_METHODS ) ) {
            // check if the request has a body
            if ( $request->hasBody() ) {
                // NOTE: Don't throw, see T359509.
                // TODO: Ignore only empty bodies, log a warning or fail if
                //       there is actual content.
                return;
            }
        }
 
        // fail if the request method expects a body but has no body
        if ( in_array( $requestMethod, RequestInterface::BODY_METHODS ) ) {
            // check if it has no body
            if ( !$request->hasBody() ) {
                throw new LocalizedHttpException(
                    new MessageValue(
                        "rest-request-body-expected",
                        [ $requestMethod ]
                    ),
                    400
                );
            }
        }
 
        // call parsedbody
        if ( $request->hasBody() ) {
            $parsedBody = $this->parseBodyData( $request );
            // Set the parsed body data on the request object
            $request->setParsedBody( $parsedBody );
        }
    }
 
    public function getPath(): string {
        return $this->path;
    }
 
    public function getRoutePath(): string {
        $prefix = $this->getModulePathPrefix();
        if ( $prefix !== '' ) {
            $prefix = "/$prefix";
        }
 
        return $prefix . $this->path;
    }
 
    public function getSupportedPathParams(): array {
        preg_match_all( '/\{(.*?)\}/', $this->path, $matches, PREG_PATTERN_ORDER );
 
        return $matches[1] ?? [];
    }
 
    protected function getRouter(): Router {
        return $this->module->getRouter();
    }
 
    protected function getModule(): Module {
        Assert::precondition(
            $this->module !== null,
            'initContext() must be called before getModule()'
        );
 
        return $this->module;
    }
 
    protected function getModulePathPrefix(): string {
        // @todo Use an injected module path prefix string (T411521)
        return $this->module->getPathPrefix();
    }
 
    protected function getRouteUrl( $pathParams = [], $queryParams = [] ): string {
        $path = $this->getRoutePath();
        // @todo: use a narrower route interface to the URL instead of Router (T411521)
        return $this->getRouter()->getRouteUrl( $path, $pathParams, $queryParams );
    }
 
    protected function urlEncodeTitle( $title ) {
        $title = str_replace( ' ', '_', $title );
        $title = urlencode( $title );
 
        // %3B_a_%40_b_%24_c_%21_d_%2A_e_%28_f_%29_g_%2C_h_~_i_%3A
        $replace = [ '%3B', '%40', '%24', '%21', '%2A', '%28', '%29', '%2C', '%7E', '%3A' ];
        $with = [ ';', '@', '$', '!', '*', '(', ')', ',', '~', ':' ];
 
        return str_replace( $replace, $with, $title );
    }
 
    public function getRequest(): RequestInterface {
        if ( !$this->request ) {
            throw new \RuntimeException( 'initForExecute() must be called before getRequest()' );
        }
        return $this->request;
    }
 
    public function getAuthority(): Authority {
        if ( !$this->authority ) {
            throw new \RuntimeException( 'initServices() must be called before getAuthority()' );
        }
        return $this->authority;
    }
 
    public function getConfig(): array {
        return $this->config;
    }
 
    public function getHttpMethod(): string {
        return strtolower( $this->config['method'] ?? '' );
    }
 
    public function getResponseFactory(): ResponseFactory {
        Assert::precondition(
            $this->responseFactory !== null,
            'getResponseFactory() must not be called before initForExecute()'
        );
        return $this->responseFactory;
    }
 
    public function getSession(): Session {
        return $this->session;
    }
 
    protected function isDeprecated(): bool {
        return isset( $this->getModule()->getModuleDescription()['info']['deprecationSettings'] ) ||
            isset( $this->openApiSpec['deprecationSettings'] );
    }
 
    protected function getDeprecatedDate(): ?int {
        return $this->getModule()->getDeprecatedDate()
            ?? $this->openApiSpec['deprecationSettings']['since']
            ?? null;
    }
 
    public function validate( Validator $restValidator ) {
        $allParamSettings = array_merge( $this->getParamSettings(), $this->getHeaderParamSettings() );
        $this->validatedParams = $restValidator->validateParams( $allParamSettings );
 
        $bodyType = $this->request->getBodyType();
        $legacyBodyValidator = $bodyType === null ? null
            : $this->getBodyValidator( $bodyType );
 
        if ( $legacyBodyValidator && !$legacyBodyValidator instanceof NullBodyValidator ) {
            $this->validatedBody = $restValidator->validateBody( $this->getRequest(), $this );
        } else {
            // Allow type coercion if the request body is form data.
            // For JSON requests, insist on proper types.
            $enforceTypes = !in_array(
                $this->request->getBodyType(),
                RequestInterface::FORM_DATA_CONTENT_TYPES
            );
 
            $this->validatedBody = $restValidator->validateBodyParams(
                $this->getBodyParamSettings(),
                $enforceTypes
            );
 
            // If there is a body, check if it contains extra fields.
            if ( $this->getRequest()->hasBody() ) {
                $this->detectExtraneousBodyFields( $restValidator );
            }
        }
 
        $this->postValidationSetup();
    }
 
    public function applyDeprecationHeader( ResponseInterface $response ) {
        $dd = $this->getDeprecatedDate();
        if ( $dd !== null && !$response->getHeaderLine( 'Deprecation' ) ) {
            $response->setHeader( ResponseHeaders::DEPRECATION, '@' . $dd );
        }
    }
 
    protected function detectExtraneousBodyFields( Validator $restValidator ) {
        $parsedBody = $this->getRequest()->getParsedBody();
 
        if ( !$parsedBody ) {
            // nothing to do
            return;
        }
 
        $restValidator->detectExtraneousBodyFields(
            $this->getBodyParamSettings(),
            $parsedBody
        );
    }
 
    public function checkSession() {
        if ( !$this->session->getProvider()->safeAgainstCsrf() ) {
            if ( $this->requireSafeAgainstCsrf() ) {
                throw new LocalizedHttpException(
                    new MessageValue( 'rest-requires-safe-against-csrf' ),
                    400
                );
            }
        } elseif ( !empty( $this->validatedBody['token'] ) ) {
            throw new LocalizedHttpException(
                new MessageValue( 'rest-extraneous-csrf-token' ),
                400
            );
        }
    }
 
    protected function getJsonLocalizer(): JsonLocalizer {
        Assert::precondition(
            $this->module !== null,
            'getJsonLocalizer() must not be called before initContext()'
        );
 
        return $this->module->getJsonLocalizer();
    }
 
    protected function getConditionalHeaderUtil() {
        if ( $this->conditionalHeaderUtil === null ) {
            $this->conditionalHeaderUtil = new ConditionalHeaderUtil;
 
            // NOTE: It would be nicer to have Handler implement a
            // ConditionalHeaderValues interface that defines methods that
            // ConditionalHeaderUtil can call. But the relevant methods already
            // exist in Handler as protected and stable to override.
            // We can't make them public without breaking all subclasses that
            // override them. So we pass closures for now.
            $this->conditionalHeaderUtil->setValidators(
                $this->getETag( ... ),
                $this->getLastModified( ... ),
                $this->hasRepresentation( ... )
            );
        }
        return $this->conditionalHeaderUtil;
    }
 
    public function checkPreconditions() {
        $status = $this->getConditionalHeaderUtil()->checkPreconditions( $this->getRequest() );
        if ( $status ) {
            $response = $this->getResponseFactory()->create();
            $response->setStatus( $status );
            $this->applyConditionalResponseHeaders( $response );
            return $response;
        }
 
        return null;
    }
 
    public function applyConditionalResponseHeaders( ResponseInterface $response ) {
        $method = $this->getRequest()->getMethod();
        if ( $method === 'GET' || $method === 'HEAD' ) {
            $this->getConditionalHeaderUtil()->applyResponseHeaders( $response );
        }
    }
 
    public function applyCacheControl( ResponseInterface $response ) {
        // NOTE: keep this consistent with the logic in OutputPage::sendCacheControl
 
        // If the response sets cookies, it must not be cached in proxies.
        // If there's an active cookie-based session (logged-in user or anonymous user with
        // session-scoped cookies), it is not safe to cache either, as the session manager may set
        // cookies in the response, or the response itself may vary on user-specific variables,
        // for example on private wikis where the 'read' permission is restricted. (T264631)
        if ( $response->getHeaderLine( 'Set-Cookie' ) || $this->getSession()->isPersistent() ) {
            $response->setHeader( ResponseHeaders::CACHE_CONTROL, 'private,must-revalidate,s-maxage=0' );
        }
 
        if ( !$response->getHeaderLine( ResponseHeaders::CACHE_CONTROL ) ) {
            $rqMethod = $this->getRequest()->getMethod();
            if ( $rqMethod !== 'GET' && $rqMethod !== 'HEAD' ) {
                // Responses to requests other than GET or HEAD should not be cacheable by default.
                $response->setHeader( ResponseHeaders::CACHE_CONTROL, 'private,no-cache,s-maxage=0' );
            }
        }
    }
 
    public function getParamSettings() {
        return [];
    }
 
    public function getHeaderParamSettings() {
        return [];
    }
 
    public function getBodyParamSettings(): array {
        return [];
    }
 
    public function getOpenApiSpec( string $method ): array {
        $parameters = [];
 
        $supportedPathParams = array_flip( $this->getSupportedPathParams() );
 
        foreach ( $this->getParamSettings() as $name => $setting ) {
            $source = $setting[ Validator::PARAM_SOURCE ] ?? '';
 
            if ( $source !== 'query' && $source !== 'path' ) {
                continue;
            }
 
            if ( $source === 'path' && !isset( $supportedPathParams[$name] ) ) {
                // Skip optional path param not used in the current path
                continue;
            }
 
            $setting[ Validator::PARAM_DESCRIPTION ] = $this->getJsonLocalizer()->localizeValue(
                $setting, Validator::PARAM_DESCRIPTION,
            );
 
            if (
                isset( $setting[ Validator::PARAM_EXAMPLE ] ) &&
                $setting[ Validator::PARAM_EXAMPLE ] instanceof MessageValue
            ) {
                $setting[ Validator::PARAM_EXAMPLE ] = $this->getJsonLocalizer()->localizeValue(
                    $setting, Validator::PARAM_EXAMPLE,
                );
            }
 
            $param = Validator::getParameterSpec( $name, $setting );
 
            $parameters[] = $param;
        }
 
        foreach ( $this->getHeaderParamSettings() as $name => $setting ) {
            $source = $setting[ Validator::PARAM_SOURCE ] ?? '';
 
            if ( $source !== 'header' ) {
                continue;
            }
 
            $setting[ Validator::PARAM_DESCRIPTION ] = $this->getJsonLocalizer()->localizeValue(
                $setting, Validator::PARAM_DESCRIPTION,
            );
 
            if (
                isset( $setting[ Validator::PARAM_EXAMPLE ] ) &&
                $setting[ Validator::PARAM_EXAMPLE ] instanceof MessageValue
            ) {
                $setting[ Validator::PARAM_EXAMPLE ] = $this->getJsonLocalizer()->localizeValue(
                    $setting, Validator::PARAM_EXAMPLE,
                );
            }
 
            $param = Validator::getParameterSpec( $name, $setting );
 
            $parameters[] = $param;
        }
 
        $spec = [
            'parameters' => $parameters,
            'responses' => $this->generateResponseSpec( $method ),
        ];
 
        if ( !in_array( $method, RequestInterface::NO_BODY_METHODS ) ) {
            $requestBody = $this->getRequestSpec( $method );
            if ( $requestBody ) {
                $spec['requestBody'] = $requestBody;
            }
        }
 
        // TODO: Allow additional information about parameters and responses to
        //       be provided in the route definition.
        $spec += $this->openApiSpec;
 
        if ( $this->isDeprecated() ) {
            $spec['deprecated'] = true;
            unset( $spec['deprecationSettings'] );
        }
 
        return $spec;
    }
 
    protected function getRequestSpec( string $method ): ?array {
        $mediaTypes = [];
 
        foreach ( $this->getSupportedRequestTypes() as $type ) {
            $schema = $this->getRequestBodySchema( $type );
 
            if ( $schema ) {
                $schema = $this->getJsonLocalizer()->localizeJson( $schema );
                $mediaTypes[$type] = [ 'schema' => $schema ];
                $example = $this->getRequestBodyExample( $type );
                if ( $example ) {
                    $mediaTypes[$type]['example'] = $example;
                }
            }
        }
 
        if ( !$mediaTypes ) {
            return null;
        }
 
        $spec = [
            // TODO: some DELETE handlers may require a body that contains a token
            // FIXME: check if there are required body params!
            'required' => in_array( $method, RequestInterface::BODY_METHODS ),
            'content' => $mediaTypes,
        ];
 
        $description = $this->getRequestBodyDescription();
        if ( $description ) {
            $spec['description'] = $this->getJsonLocalizer()->localizeValue(
                [ self::OPENAPI_DESCRIPTION_KEY => $description ],
                self::OPENAPI_DESCRIPTION_KEY
            );
        }
 
        return $spec;
    }
 
    public function getRequestBodyDescription(): MessageValue|string|null {
        return null;
    }
 
    public function getRequestBodyExample( string $mediaType ): ?array {
        if ( $mediaType !== RequestInterface::JSON_CONTENT_TYPE ) {
            return null;
        }
 
        $allowedSources = $this->getParamSourcesForRequestType( $mediaType );
        $example = [];
 
        foreach ( $this->getBodyParamSettings() as $name => $settings ) {
            $source = $settings[ Validator::PARAM_SOURCE ] ?? '';
            if ( !in_array( $source, $allowedSources, true ) ) {
                continue;
            }
 
            if ( !array_key_exists( Validator::PARAM_EXAMPLE, $settings ) ) {
                $example[$name] = self::MISSING_BODY_EXAMPLE;
            } elseif ( $settings[ Validator::PARAM_EXAMPLE ] instanceof MessageValue ) {
                $example[$name] = $this->getJsonLocalizer()->localizeValue(
                    $settings, Validator::PARAM_EXAMPLE
                );
            } else {
                $example[$name] = $settings[ Validator::PARAM_EXAMPLE ];
            }
        }
 
        return $example ?: null;
    }
 
    private function getParamSourcesForRequestType( string $mediaType ): array {
        if (
            $mediaType === RequestInterface::FORM_URLENCODED_CONTENT_TYPE ||
            $mediaType === RequestInterface::MULTIPART_FORM_DATA_CONTENT_TYPE
        ) {
            return [ 'body', 'post' ];
        }
 
        return [ 'body' ];
    }
 
    protected function getRequestBodySchema( string $mediaType ): array {
        $allowedSources = $this->getParamSourcesForRequestType( $mediaType );
 
        $paramSettings = $this->getBodyParamSettings();
 
        $properties = [];
        $required = [];
 
        foreach ( $paramSettings as $name => $settings ) {
            $source = $settings[ Validator::PARAM_SOURCE ] ?? '';
            $isRequired = $settings[ ParamValidator::PARAM_REQUIRED ] ?? false;
 
            if ( !in_array( $source, $allowedSources ) ) {
                // TODO: post parameters also work as body parameters...
                continue;
            }
 
            if (
                isset( $settings[ Validator::PARAM_EXAMPLE ] ) &&
                $settings[ Validator::PARAM_EXAMPLE ] instanceof MessageValue
            ) {
                $settings[ Validator::PARAM_EXAMPLE ] = $this->getJsonLocalizer()->localizeValue(
                    $settings, Validator::PARAM_EXAMPLE,
                );
            }
 
            $properties[$name] = Validator::getParameterSchema( $settings );
            $properties[$name][self::OPENAPI_DESCRIPTION_KEY] =
                $this->getJsonLocalizer()->localizeValue( $settings, Validator::PARAM_DESCRIPTION )
                ?? "$name parameter";
 
            if ( $isRequired ) {
                $required[] = $name;
            }
        }
 
        if ( !$properties ) {
            return [];
        }
 
        $schema = [
            'type' => 'object',
            'properties' => $properties,
        ];
 
        if ( $required ) {
            $schema['required'] = $required;
        }
 
        return $schema;
    }
 
    protected function getResponseBodySchema( string $method ): ?array {
        $file = $this->getResponseBodySchemaFileName( $method );
        return $file ? Module::loadJsonFile( $file ) : null;
    }
 
    private function getResponseHeaderSchemas(): array {
        $responseHeaderSettings = [];
        foreach ( $this->getResponseHeaderSettings() as $headerName => $settings ) {
            // Set description field for localization
            $settings[ self::OPENAPI_DESCRIPTION_KEY  ] = new MessageValue( $settings[ 'messageKey' ] );
            // 'messageKey' field no longer required
            unset( $settings[ 'messageKey' ] );
            $settings[ self::OPENAPI_DESCRIPTION_KEY ] = $this->getJsonLocalizer()->localizeValue(
                $settings, self::OPENAPI_DESCRIPTION_KEY,
            );
            $responseHeaderSettings[ $headerName ] = [
                self::OPENAPI_DESCRIPTION_KEY => $settings[ self::OPENAPI_DESCRIPTION_KEY ],
                'schema' => $settings[ 'schema' ]
            ];
        }
        return $responseHeaderSettings;
    }
 
    public function getResponseHeaderSettings(): array {
        $responseHeaderSettings = [
            ResponseHeaders::CACHE_CONTROL => ResponseHeaders::RESPONSE_HEADER_DEFINITIONS[
                ResponseHeaders::CACHE_CONTROL
            ]
        ];
 
        if ( $this->isDeprecated() ) {
            $responseHeaderSettings[ ResponseHeaders::DEPRECATION ] = ResponseHeaders::RESPONSE_HEADER_DEFINITIONS[
                ResponseHeaders::DEPRECATION
            ];
        }
        return $responseHeaderSettings;
    }
 
    protected function getResponseBodySchemaFileName( string $method ): ?string {
        return null;
    }
 
    protected function getResponseBodyExampleFileName( string $method ): ?string {
        return null;
    }
 
    protected function getResponseBodyExample( string $method ): ?array {
        $file = $this->getResponseBodyExampleFileName( $method );
        return $file ? Module::loadJsonFile( $file ) : null;
    }
 
    protected function generateResponseSpec( string $method ): array {
        $ok = [ self::OPENAPI_DESCRIPTION_KEY => 'OK' ];
 
        $bodySchema = $this->getResponseBodySchema( $method );
 
        if ( $bodySchema ) {
            $bodySchema = $this->getJsonLocalizer()->localizeJson( $bodySchema );
            $ok['content']['application/json']['schema'] = $bodySchema;
        }
 
        $bodyExample = $this->getResponseBodyExample( $method );
        if ( $bodyExample !== null ) {
            $ok['content']['application/json']['example'] = $bodyExample;
        }
 
        $headersSpec = $this->getResponseHeaderSchemas();
        $ok['headers'] = $headersSpec;
 
        // XXX: we should add info about redirects
        return [
            '200' => $ok,
            'default' => [ '$ref' => '#/components/responses/GenericErrorResponse' ],
        ];
    }
 
    public function getBodyValidator( $contentType ) {
        // NOTE: When removing this method, also remove the BodyValidator interface and
        //       all classes implementing it!
        return new NullBodyValidator();
    }
 
    public function getValidatedParams() {
        if ( $this->validatedParams === null ) {
            throw new \RuntimeException( 'getValidatedParams() called before validate()' );
        }
        return $this->validatedParams;
    }
 
    public function getValidatedBody() {
        return $this->validatedBody;
    }
 
    public function getValidatedBodyArray(): array {
        return $this->validatedBody;
    }
 
    public function parseBodyData( RequestInterface $request ): ?array {
        // Parse the body based on its content type
        $contentType = $request->getBodyType();
 
        // HACK: If the Handler uses a custom BodyValidator, the
        // getBodyValidator() is also responsible for checking whether
        // the content type is valid, and for parsing the body.
        // See T359149.
        // TODO: remove once no subclasses override getBodyValidator() anymore
        $bodyValidator = $this->getBodyValidator( $contentType ?? 'unknown/unknown' );
        if ( !$bodyValidator instanceof NullBodyValidator ) {
            // TODO: Trigger a deprecation warning.
            return null;
        }
 
        $supportedTypes = $this->getSupportedRequestTypes();
        if ( $contentType !== null && !in_array( $contentType, $supportedTypes ) ) {
            throw new LocalizedHttpException(
                new MessageValue( 'rest-unsupported-content-type', [ $contentType ] ),
                415
            );
        }
 
        // if it's supported and ends with "+json", we can probably parse it like a normal application/json request
        $contentType = str_ends_with( $contentType ?? '', '+json' )
            ? RequestInterface::JSON_CONTENT_TYPE
            : $contentType;
 
        switch ( $contentType ) {
            case RequestInterface::FORM_URLENCODED_CONTENT_TYPE:
            case RequestInterface::MULTIPART_FORM_DATA_CONTENT_TYPE:
                $params = $request->getPostParams();
                foreach ( $params as $key => $value ) {
                    $params[ $key ] = $this->recursiveUtfCleanup( $value );
                    // TODO: Warn if normalization was applied
                }
                return $params;
            case RequestInterface::JSON_CONTENT_TYPE:
                $jsonStream = $request->getBody();
                $jsonString = (string)$jsonStream;
                $normalizedJsonString = UtfNormalValidator::cleanUp( $jsonString );
                $parsedBody = json_decode( $normalizedJsonString, true );
                if ( !is_array( $parsedBody ) ) {
                    throw new LocalizedHttpException(
                        new MessageValue(
                            'rest-json-body-parse-error',
                            [ 'not a valid JSON object' ]
                        ),
                        400
                    );
                }
                // TODO: Warn if normalization was applied
                return $parsedBody;
            case null:
                // Specifying no Content-Type is fine if the body is empty
                if ( $request->getBody()->getSize() === 0 ) {
                    return null;
                }
            // no break, else fall through to the error below.
            default:
                throw new LocalizedHttpException(
                    new MessageValue( 'rest-unsupported-content-type', [ $contentType ?? '(null)' ] ),
                    415
                );
        }
    }
 
    private function recursiveUtfCleanup( $value ) {
        if ( is_string( $value ) ) {
            return UtfNormalValidator::cleanUp( $value );
        } elseif ( is_array( $value ) ) {
            foreach ( $value as $k => $v ) {
                $value[ $k ] = $this->recursiveUtfCleanup( $v );
                // TODO: Warn if normalization was applied
                // TODO: also normalize key
            }
 
            return $value;
        } else {
            return $value;
        }
    }
 
    public function getSupportedRequestTypes(): array {
        $types = [
            RequestInterface::JSON_CONTENT_TYPE
        ];
 
        // TODO: remove this once "post" parameters are no longer supported! T362850
        foreach ( $this->getParamSettings() as $settings ) {
            if ( ( $settings[self::PARAM_SOURCE] ?? null ) === 'post' ) {
                $types[] = RequestInterface::FORM_URLENCODED_CONTENT_TYPE;
                $types[] = RequestInterface::MULTIPART_FORM_DATA_CONTENT_TYPE;
                break;
            }
        }
 
        return $types;
    }
 
    protected function getHookContainer() {
        return $this->hookContainer;
    }
 
    protected function getHookRunner() {
        return $this->hookRunner;
    }
 
    protected function getLastModified() {
        return null;
    }
 
    protected function getETag() {
        return null;
    }
 
    protected function hasRepresentation() {
        return null;
    }
 
    public function needsReadAccess() {
        return true;
    }
 
    public function needsWriteAccess() {
        return true;
    }
 
    public function requireSafeAgainstCsrf() {
        return false;
    }
 
    protected function postInitSetup() {
    }
 
    protected function postValidationSetup() {
    }
 
    abstract public function execute();
}