3 namespace MediaWiki\Rest
;
7 use Wikimedia\Message\MessageValue
;
8 use MediaWiki\Rest\BasicAccess\BasicAuthorizerInterface
;
9 use MediaWiki\Rest\PathTemplateMatcher\PathMatcher
;
10 use MediaWiki\Rest\Validator\Validator
;
11 use Wikimedia\ObjectFactory
;
14 * The REST router is responsible for gathering handler configuration, matching
15 * an input path and HTTP method against the defined routes, and constructing
16 * and executing the relevant handler for a request.
25 /** @var array|null */
26 private $routesFromFiles;
28 /** @var int[]|null */
29 private $routeFileTimestamps;
34 /** @var \BagOStuff */
37 /** @var PathMatcher[]|null Path matchers by method */
40 /** @var string|null */
43 /** @var ResponseFactory */
44 private $responseFactory;
46 /** @var BasicAuthorizerInterface */
49 /** @var ObjectFactory */
50 private $objectFactory;
53 private $restValidator;
56 * @param string[] $routeFiles List of names of JSON files containing routes
57 * @param array $extraRoutes Extension route array
58 * @param string $rootPath The base URL path
59 * @param BagOStuff $cacheBag A cache in which to store the matcher trees
60 * @param ResponseFactory $responseFactory
61 * @param BasicAuthorizerInterface $basicAuth
62 * @param ObjectFactory $objectFactory
63 * @param Validator $restValidator
65 public function __construct( $routeFiles, $extraRoutes, $rootPath,
66 BagOStuff
$cacheBag, ResponseFactory
$responseFactory,
67 BasicAuthorizerInterface
$basicAuth, ObjectFactory
$objectFactory,
68 Validator
$restValidator
70 $this->routeFiles
= $routeFiles;
71 $this->extraRoutes
= $extraRoutes;
72 $this->rootPath
= $rootPath;
73 $this->cacheBag
= $cacheBag;
74 $this->responseFactory
= $responseFactory;
75 $this->basicAuth
= $basicAuth;
76 $this->objectFactory
= $objectFactory;
77 $this->restValidator
= $restValidator;
81 * Get the cache data, or false if it is missing or invalid
85 private function fetchCacheData() {
86 $cacheData = $this->cacheBag
->get( $this->getCacheKey() );
87 if ( $cacheData && $cacheData['CONFIG-HASH'] === $this->getConfigHash() ) {
88 unset( $cacheData['CONFIG-HASH'] );
96 * @return string The cache key
98 private function getCacheKey() {
99 return $this->cacheBag
->makeKey( __CLASS__
, '1' );
103 * Get a config version hash for cache invalidation
107 private function getConfigHash() {
108 if ( $this->configHash
=== null ) {
109 $this->configHash
= md5( json_encode( [
111 $this->getRouteFileTimestamps()
114 return $this->configHash
;
118 * Load the defined JSON files and return the merged routes
122 private function getRoutesFromFiles() {
123 if ( $this->routesFromFiles
=== null ) {
124 $this->routeFileTimestamps
= [];
125 foreach ( $this->routeFiles
as $fileName ) {
126 $this->routeFileTimestamps
[$fileName] = filemtime( $fileName );
127 $routes = json_decode( file_get_contents( $fileName ), true );
128 if ( $this->routesFromFiles
=== null ) {
129 $this->routesFromFiles
= $routes;
131 $this->routesFromFiles
= array_merge( $this->routesFromFiles
, $routes );
135 return $this->routesFromFiles
;
139 * Get an array of last modification times of the defined route files.
141 * @return int[] Last modification times
143 private function getRouteFileTimestamps() {
144 if ( $this->routeFileTimestamps
=== null ) {
145 $this->routeFileTimestamps
= [];
146 foreach ( $this->routeFiles
as $fileName ) {
147 $this->routeFileTimestamps
[$fileName] = filemtime( $fileName );
150 return $this->routeFileTimestamps
;
154 * Get an iterator for all defined routes, including loading the routes from
157 * @return AppendIterator
159 private function getAllRoutes() {
160 $iterator = new AppendIterator
;
161 $iterator->append( new \
ArrayIterator( $this->getRoutesFromFiles() ) );
162 $iterator->append( new \
ArrayIterator( $this->extraRoutes
) );
167 * Get an array of PathMatcher objects indexed by HTTP method
169 * @return PathMatcher[]
171 private function getMatchers() {
172 if ( $this->matchers
=== null ) {
173 $cacheData = $this->fetchCacheData();
176 foreach ( $cacheData as $method => $data ) {
177 $matchers[$method] = PathMatcher
::newFromCache( $data );
180 foreach ( $this->getAllRoutes() as $spec ) {
181 $methods = $spec['method'] ??
[ 'GET' ];
182 if ( !is_array( $methods ) ) {
183 $methods = [ $methods ];
185 foreach ( $methods as $method ) {
186 if ( !isset( $matchers[$method] ) ) {
187 $matchers[$method] = new PathMatcher
;
189 $matchers[$method]->add( $spec['path'], $spec );
193 $cacheData = [ 'CONFIG-HASH' => $this->getConfigHash() ];
194 foreach ( $matchers as $method => $matcher ) {
195 $cacheData[$method] = $matcher->getCacheData();
197 $this->cacheBag
->set( $this->getCacheKey(), $cacheData );
199 $this->matchers
= $matchers;
201 return $this->matchers
;
205 * Remove the path prefix $this->rootPath. Return the part of the path with the
206 * prefix removed, or false if the prefix did not match.
208 * @param string $path
209 * @return false|string
211 private function getRelativePath( $path ) {
212 if ( strlen( $this->rootPath
) > strlen( $path ) ||
213 substr_compare( $path, $this->rootPath
, 0, strlen( $this->rootPath
) ) !== 0
217 return substr( $path, strlen( $this->rootPath
) );
221 * Find the handler for a request and execute it
223 * @param RequestInterface $request
224 * @return ResponseInterface
226 public function execute( RequestInterface
$request ) {
227 $path = $request->getUri()->getPath();
228 $relPath = $this->getRelativePath( $path );
229 if ( $relPath === false ) {
230 return $this->responseFactory
->createLocalizedHttpError( 404,
231 ( new MessageValue( 'rest-prefix-mismatch' ) )
232 ->plaintextParams( $path, $this->rootPath
)
236 $requestMethod = $request->getMethod();
237 $matchers = $this->getMatchers();
238 $matcher = $matchers[$requestMethod] ??
null;
239 $match = $matcher ?
$matcher->match( $relPath ) : null;
241 // For a HEAD request, execute the GET handler instead if one exists.
242 // The webserver will discard the body.
243 if ( !$match && $requestMethod === 'HEAD' && isset( $matchers['GET'] ) ) {
244 $match = $matchers['GET']->match( $relPath );
248 // Check for 405 wrong method
250 foreach ( $matchers as $allowedMethod => $allowedMatcher ) {
251 if ( $allowedMethod === $requestMethod ) {
254 if ( $allowedMatcher->match( $relPath ) ) {
255 $allowed[] = $allowedMethod;
259 $response = $this->responseFactory
->createLocalizedHttpError( 405,
260 ( new MessageValue( 'rest-wrong-method' ) )
261 ->textParams( $requestMethod )
262 ->commaListParams( $allowed )
263 ->numParams( count( $allowed ) )
265 $response->setHeader( 'Allow', $allowed );
268 // Did not match with any other method, must be 404
269 return $this->responseFactory
->createLocalizedHttpError( 404,
270 ( new MessageValue( 'rest-no-match' ) )
271 ->plaintextParams( $relPath )
276 $request->setPathParams( array_map( 'rawurldecode', $match['params'] ) );
277 $spec = $match['userData'];
278 $objectFactorySpec = array_intersect_key( $spec,
279 [ 'factory' => true, 'class' => true, 'args' => true, 'services' => true ] );
280 /** @var $handler Handler (annotation for PHPStorm) */
281 $handler = $this->objectFactory
->createObject( $objectFactorySpec );
282 $handler->init( $this, $request, $spec, $this->responseFactory
);
285 return $this->executeHandler( $handler );
286 } catch ( HttpException
$e ) {
287 return $this->responseFactory
->createFromException( $e );
292 * Execute a fully-constructed handler
294 * @param Handler $handler
295 * @return ResponseInterface
297 private function executeHandler( $handler ): ResponseInterface
{
298 // @phan-suppress-next-line PhanAccessMethodInternal
299 $authResult = $this->basicAuth
->authorize( $handler->getRequest(), $handler );
301 return $this->responseFactory
->createHttpError( 403, [ 'error' => $authResult ] );
304 $handler->validate( $this->restValidator
);
306 $response = $handler->execute();
307 if ( !( $response instanceof ResponseInterface
) ) {
308 $response = $this->responseFactory
->createFromReturnValue( $response );