diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e727c74 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,106 @@ +# AGENTS.md — Semantic External Query Lookup (SEQL) + +Guidance for agents and humans working in this repository. Review findings are +persisted in `REVIEW.md` (defect findings and simplification findings are kept +in separate sections there). + +## Project + +SEQL is a [Semantic MediaWiki](https://github.com/SemanticMediaWiki/SemanticMediaWiki) +extension that integrates `#ask`/`#show` query results from an external +MediaWiki wiki into a local wiki. PHP ≥ 8.1, MediaWiki ≥ 1.43, Semantic +MediaWiki ≥ 7.0 (see `extension.json` and `composer.json`). + +## Repository layout + +- `src/` — first-party code, PSR-4 namespace `SEQL\` (registered in + `extension.json` → `AutoloadNamespaces`). +- `tests/phpunit/Unit/`, `tests/phpunit/Integration/` — PHPUnit suites with + JSON fixtures under `tests/phpunit/Integration/ByHttpRequest/Fixtures/`. +- `i18n/` — MediaWiki message files; `en.json` and `qqq.json` must carry every + `seql-*` key (enforced by `I18nJsonFileIntegrityTest` plus translatewiki + practice). +- `build/` — git submodule (`docker-compose-ci`); initialize with + `git submodule update --init --remote` (the `Makefile` does this + automatically when `build/` is missing). Not first-party code. +- `docs/` — end-user configuration documentation. + +## Running tests, linters, and builds + +Prerequisites: a MediaWiki install with Semantic MediaWiki is required at +runtime; `composer phpunit` resolves the MediaWiki root from `MW_INSTALL_PATH` +(default `../..`). The test bootstrap (`tests/bootstrap.php`) hard-fails if the +SMW test autoloader is not present. + +All commands run through Composer scripts defined in `composer.json`: + +| Task | Command | +| --- | --- | +| Full test suite (analyze + phpunit) | `composer test` | +| Static analysis only (lint + phpcs + minus-x) | `composer analyze` | +| Unit tests only | `composer unit` | +| Integration tests only | `composer integration` | +| Tests with coverage | `composer test-coverage` | +| PHP parallel lint | `composer lint` | +| Code sniffer (MediaWiki standard) | `composer phpcs` | +| Auto-fix sniffer findings | `composer fix` | +| Executable-bit / shebang check | `composer minus-x` | + +CI (GitHub Actions, `.github/workflows/ci.yaml`) runs `make ci` / +`make ci-coverage`, which drives the `docker-compose-ci` submodule with the +versions declared in the `Makefile` (`MW_VERSION`, `PHP_VERSION`, `DB_TYPE`, +`DB_IMAGE`, `SMW_VERSION`). + +There is no separate build step; the extension is a Composer package +(`mediawiki/semantic-external-query-lookup`). + +## Coding conventions + +- Style is the **MediaWiki coding standard**, enforced by + `mediawiki/mediawiki-codesniffer` 48.0.0 via `.phpcs.xml`; tabs for + indentation, `aligned` spacing inside function calls as seen throughout + `src/`. +- Every class file carries the `@license GPL-2.0-or-later` docblock. +- Classes live in `src/` under `SEQL\`; test classes use + `SEQL\Tests\` / `SEQL\ByHttpRequest\Tests\` namespaces (note: the latter is + currently **not** matched by the PSR-4 mappings in `tests/bootstrap.php` — + see REVIEW.md). +- Configuration is declared in `extension.json` with the `seqlg` prefix + (`config_prefix`); code reads it as `$GLOBALS['seqlg…']`. +- User-facing strings are MediaWiki messages in `i18n/`, keys prefixed + `seql-`. +- Behavior changes ship with unit/integration tests and a RELEASE-NOTES entry. + +## Project rules + +1. **POSIX shell only.** Any shell script added to this repo must be strictly + POSIX (`#!/bin/sh`, `[ ]` tests, quoted variable expansions; `set -eux` for + setup scripts) and be verified with `shellcheck` and `dash -n` where + available. The repo currently contains **no** shell scripts (the Makefile + is not shell); this rule applies to any future ones. +2. **Validate installed versions.** Any installed tool, runtime, or + dependency whose version matters must be validated after installation: + compare installed vs. expected version and fail fast with a clear error on + mismatch. Today this is satisfied declaratively — `composer.json` requires + `php >=8.1.0` and `extension.json` requires MediaWiki ≥ 1.43 / SMW ≥ 7.0 + (checked by MediaWiki's extension registry) — keep it that way for any new + tooling. +3. **Funnel dependency installs through one declared place.** PHP dependencies + come exclusively from `composer.json`; CI toolchain versions come + exclusively from the `Makefile` variables passed to the + `docker-compose-ci` submodule. Do not add ad-hoc `install`/`require` + commands scattered in scripts or CI steps. + +## Known issues + +See `REVIEW.md` for the full, ordered list (defect findings and simplification +findings). The most significant ones at review time (2026-11-13): + +- `seqlgExternalQueryEnabledNamespaces` default `[]` **blocks** `source=` + queries in every namespace, contradicting the documented "keep empty to + allow every namespace" (`src/HookRegistry.php:93`, `extension.json`). +- All outbound HTTP requests disable TLS certificate/host verification + (`src/ByHttpRequest/QueryResultFetcher.php`). +- The remote-login flow uses the deprecated `action=login` API and stores its + cookie jar in a `static` shared across instances and endpoints. +- `.gitreview` names the wrong Gerrit project (`SemanticMetaTags`). diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md index 0e64145..e241b76 100644 --- a/RELEASE-NOTES.md +++ b/RELEASE-NOTES.md @@ -1,5 +1,20 @@ This file contains the RELEASE-NOTES of the Semantic External Query Lookup (a.k.a. SEQL) extension. +### 2.0.1 (not yet released) + +- Fixed `source=` queries failing silently: a transport failure or an + unparseable response from the external repository is now reported as a + query error (`seql-http-request-failed` / `seql-http-response-invalid`) + instead of rendering an empty result without any diagnostic +- A response that does not decode as JSON is no longer written to the + HTTP response cache, so a failed fetch is retried after the error is + fixed instead of being frozen for the cache lifetime +- Added a "Names must align" section to the configuration documentation + explaining that the `source=` value, the `$smwgQuerySources` key, and + the `$seqlgExternalRepositoryEndpoints` prefix must carry the same + name, and that a mismatch (or a later wholesale re-assignment of + `$smwgQuerySources`) silently falls back to the local store + ### 2.0.0 (2026-06-08) - Added support for Semantic MediaWiki 7.0 @@ -7,6 +22,9 @@ This file contains the RELEASE-NOTES of the Semantic External Query Lookup (a.k. - Raised the minimum requirement to Semantic MediaWiki 7.0 - Raised the minimum requirement to PHP 8.1 - Replaced the `mediawiki/http-request` dependency with MediaWiki core's `HttpRequestFactory` +- Removed the `InterwikiLoadPrefix` hook registration (deprecated since MediaWiki 1.36); + endpoints in `$seqlgExternalRepositoryEndpoints` are now exposed by decorating the + `InterwikiLookup` service via the `MediaWikiServices` hook ### 1.0.0 (2016-??-??) diff --git a/build b/build index 13d00b1..75c4ef2 160000 --- a/build +++ b/build @@ -1 +1 @@ -Subproject commit 13d00b11a7743cb6a524c6ed577b8dea3913a62c +Subproject commit 75c4ef2a81400c40039fec7f4433a4ae9b7d805b diff --git a/composer.json b/composer.json index 138b439..81454ba 100644 --- a/composer.json +++ b/composer.json @@ -29,7 +29,7 @@ "composer/installers": "^2|^1.0.1" }, "require-dev": { - "mediawiki/mediawiki-codesniffer": "48.0.0", + "mediawiki/mediawiki-codesniffer": ">=51.0.1", "mediawiki/minus-x": "1.1.3", "php-parallel-lint/php-console-highlighter": "1.0.0", "php-parallel-lint/php-parallel-lint": "1.4.0" diff --git a/docs/00-configurations.md b/docs/00-configurations.md index 3fd11cf..92c0143 100644 --- a/docs/00-configurations.md +++ b/docs/00-configurations.md @@ -23,6 +23,30 @@ $GLOBALS['seqlgExternalRepositoryEndpoints'] = array( ) ); ```` + +#### Names must align + +The `source=` value used in a `#ask`/`#show` query, the key in `$GLOBALS['smwgQuerySources']`, and the key in +`$GLOBALS['seqlgExternalRepositoryEndpoints']` (or the interwiki table) must carry **the same name**. In the examples +above that name is `mw-foo`; queries use `{{#ask: ... |source=mw-foo }}`. + +The failure modes of a mismatch are silent: + +- If `source=X` names no key in `$GLOBALS['smwgQuerySources']`, Semantic MediaWiki resets the source to its default and + runs the query against the **local** store without raising an error. The rendered output is an empty result whenever + the local wiki cannot answer the query, which is indistinguishable from a broken endpoint. +- If `X` names a query source but is not resolvable as an interwiki prefix, SEQL renders the + `seql-interwiki-prefix-is-missing` warning instead of results. + +When adding a source with `= array( ... )`, use the array-append operator (`$GLOBALS['smwgQuerySources']['mw-foo'] = ...`) +or merge with existing entries. A wholesale re-assignment in a settings file that is loaded **after** this registration +(for example a farm- or host-level configuration layered on top of `LocalSettings.php`) discards the query source +without any notice. + +A quick check for a suspected fallback: `{{#ask: ... |source=X |format=debug }}`. Debug queries are not supported by +external query sources, so a *normal local* debug pane is the signature of the local-store fallback; an error message +about debug queries confirms that the external source was selected. + ### Cache To help limit the amount of request made to an endpoint, SEQL provides: diff --git a/extension.json b/extension.json index b311e6b..ae8541a 100644 --- a/extension.json +++ b/extension.json @@ -20,6 +20,14 @@ "i18n" ] }, + "Hooks": { + "MediaWikiServices": "main" + }, + "HookHandlers": { + "main": { + "class": "SEQL\\MediaWikiServicesHandler" + } + }, "AutoloadNamespaces": { "SEQL\\": "src/" }, diff --git a/i18n/en.json b/i18n/en.json index 434d8ed..4ca1587 100644 --- a/i18n/en.json +++ b/i18n/en.json @@ -8,5 +8,7 @@ "seql-desc": "Allows to integrate query results from a remote [https://semantic-mediawiki.org Semantic MediaWiki] into a local wiki", "seql-name": "Semantic External Query Lookup", "seql-interwiki-prefix-is-missing": "The selected \"$1\" source is missing a matching interwiki prefix.", - "seql-debug-query-not-supported": "The display of results for a debug query is not supported when using an external query source." + "seql-debug-query-not-supported": "The display of results for a debug query is not supported when using an external query source.", + "seql-http-request-failed": "The request to the external repository at \"$1\" failed or could not be answered with a usable response.", + "seql-http-response-invalid": "The response from the external repository at \"$1\" could not be decoded." } diff --git a/i18n/qqq.json b/i18n/qqq.json index 284be15..b45d96a 100644 --- a/i18n/qqq.json +++ b/i18n/qqq.json @@ -9,5 +9,7 @@ "seql-desc": "{{desc|name=Semantic External Query Lookup|url=https://www.mediawiki.org/wiki/Extension:Semantic_External_Query_Lookup}}", "seql-name": "{{name}}", "seql-interwiki-prefix-is-missing": "This is an error message.\n\n* $1 holds the label of the configured query source.", - "seql-debug-query-not-supported": "This is an error message." + "seql-debug-query-not-supported": "This is an error message.", + "seql-http-request-failed": "This is an error message.\n\n* $1 holds the URL of the queried external repository endpoint.", + "seql-http-response-invalid": "This is an error message.\n\n* $1 holds the URL of the queried external repository endpoint." } diff --git a/src/ByHttpRequest/QueryResultFetcher.php b/src/ByHttpRequest/QueryResultFetcher.php index 928bb8a..cd70e69 100644 --- a/src/ByHttpRequest/QueryResultFetcher.php +++ b/src/ByHttpRequest/QueryResultFetcher.php @@ -202,9 +202,20 @@ public function fetchQueryResult( Query $query ) { $this->doAuthenticateRemoteWiki( $this->credentials ); } - [ $result, $isFromCache ] = $this->doMakeHttpRequestFor( $query ); + [ $result, $isFromCache, $failureReason ] = $this->doMakeHttpRequestFor( $query ); + + if ( $result === null ) { + // The response could not be fetched or decoded; make the failure + // visible instead of silently rendering an empty result. + $query->addErrors( [ wfMessage( + $failureReason === 'decode' ? 'seql-http-response-invalid' : 'seql-http-request-failed', + $this->httpRequestEndpoint + )->text() ] ); - if ( $result === [] || $result === false || $result === null ) { + return $this->queryResultFactory->newEmptyQueryResult( $query ); + } + + if ( $result === [] ) { return $this->queryResultFactory->newEmptyQueryResult( $query ); } @@ -270,12 +281,27 @@ private function doMakeHttpRequestFor( $query ) { $isFromCache = false; $response = $this->fetchHttpResponse( $url ); - if ( is_string( $response ) && $response !== '' ) { + // Only cache responses that at least decode as JSON so that a + // failed or corrupted fetch is retried on the next request + // instead of being served from the cache. + if ( is_string( $response ) && $response !== '' && is_array( json_decode( $response, true ) ) ) { $this->cache->set( $key, $response, $this->httpResponseCacheLifetime ); } } - return [ json_decode( $response ?? '', true ), $isFromCache ]; + if ( $response === false || $response === null || $response === '' ) { + // The response could not be fetched at all (transport failure) + return [ null, $isFromCache, 'request' ]; + } + + $result = json_decode( $response, true ); + + if ( !is_array( $result ) ) { + // The response was fetched but is no valid JSON + return [ null, $isFromCache, 'decode' ]; + } + + return [ $result, $isFromCache, '' ]; } private function fetchHttpResponse( $url ) { diff --git a/src/DynamicInterwikiPrefixLoader.php b/src/DynamicInterwikiPrefixLoader.php index 71fadd7..109c659 100644 --- a/src/DynamicInterwikiPrefixLoader.php +++ b/src/DynamicInterwikiPrefixLoader.php @@ -2,6 +2,8 @@ namespace SEQL; +use Interwiki; + /** * Allows to dynamically assign interwiki prefixes without having to * create an interwiki table entry. @@ -28,7 +30,7 @@ public function __construct( array $enabledExternalRepositoryEndpoints = [] ) { } /** - * @since 1.0 + * @since 2.0.1 * * @param string $prefix */ @@ -36,26 +38,54 @@ public function isEnabledPrefixForExternalRepository( $prefix ) { return isset( $this->enabledExternalRepositoryEndpoints[$prefix] ); } + /** + * @since 2.0.1 + * + * @param string $prefix + * + * @return Interwiki|null Interwiki instance for a known external + * repository endpoint or null when the prefix holds no such endpoint + */ + public function newInterwiki( $prefix ) { + if ( !$this->isEnabledPrefixForExternalRepository( $prefix ) ) { + return null; + } + + [ $iw_url, $iw_api, $iw_local ] = $this->enabledExternalRepositoryEndpoints[$prefix]; + + return new Interwiki( + $prefix, + $iw_url, + $iw_api, + $prefix, + $iw_local + ); + } + /** * @since 1.0 + * @deprecated since 2.0.1, use newInterwiki() instead. Kept for + * compatibility with the removed InterwikiLoadPrefix hook. * * @param string $prefix * @param array &$interwiki + * + * @return bool */ public function tryToLoadIwMapForExternalRepository( $prefix, &$interwiki ) { - if ( !$this->isEnabledPrefixForExternalRepository( $prefix ) ) { + $interwikiObject = $this->newInterwiki( $prefix ); + + if ( $interwikiObject === null ) { return true; } - [ $iw_url, $iw_api, $iw_local ] = $this->enabledExternalRepositoryEndpoints[$prefix]; - $interwiki = [ 'iw_prefix' => $prefix, - 'iw_url' => $iw_url, - 'iw_api' => $iw_api, - 'iw_wikiid' => $prefix, - 'iw_local' => $iw_local, - 'iw_trans' => false, + 'iw_url' => $interwikiObject->getURL(), + 'iw_api' => $interwikiObject->getAPI(), + 'iw_wikiid' => $interwikiObject->getWikiID(), + 'iw_local' => $interwikiObject->isLocal(), + 'iw_trans' => $interwikiObject->isTranscludable() ]; return false; diff --git a/src/HookRegistry.php b/src/HookRegistry.php index 88e29b0..958a93a 100644 --- a/src/HookRegistry.php +++ b/src/HookRegistry.php @@ -59,14 +59,6 @@ public function getHandlerFor( $name ) { } private function addCallbackHandlers( $options ) { - $dynamicInterwikiPrefixLoader = new DynamicInterwikiPrefixLoader( - $options['externalRepositoryEndpoints'] - ); - - $this->handlers['InterwikiLoadPrefix'] = static function ( $prefix, &$interwiki ) use( $dynamicInterwikiPrefixLoader ) { - return $dynamicInterwikiPrefixLoader->tryToLoadIwMapForExternalRepository( $prefix, $interwiki ); - }; - /** * Prevents ask parser function with "source" parameter defined from * being executed outside of allowed namespaces. This supports transclusion too. diff --git a/src/InterwikiLookupDecorator.php b/src/InterwikiLookupDecorator.php new file mode 100644 index 0000000..21df6bc --- /dev/null +++ b/src/InterwikiLookupDecorator.php @@ -0,0 +1,115 @@ +interwikiLookup = $interwikiLookup; + $this->dynamicInterwikiPrefixLoader = $dynamicInterwikiPrefixLoader; + $this->contentLanguage = $contentLanguage; + } + + /** + * @since 2.0.1 + * + * @param string|null $prefix + * + * @return bool + */ + public function isValidInterwiki( $prefix ) { + // Guarded like `ClassicInterwikiLookup` so that neither the content + // language nor the prefix loader are consulted with `null` or an + // empty prefix + if ( $prefix === null || $prefix === '' ) { + return $this->interwikiLookup->isValidInterwiki( $prefix ); + } + + if ( $this->dynamicInterwikiPrefixLoader->isEnabledPrefixForExternalRepository( $this->contentLanguage->lc( $prefix ) ) ) { + return true; + } + + return $this->interwikiLookup->isValidInterwiki( $prefix ); + } + + /** + * @since 2.0.1 + * + * @param string|null $prefix + * + * @return Interwiki|null|false + */ + public function fetch( $prefix ) { + if ( $prefix !== null && $prefix !== '' ) { + $interwiki = $this->dynamicInterwikiPrefixLoader->newInterwiki( $this->contentLanguage->lc( $prefix ) ); + + if ( $interwiki !== null ) { + return $interwiki; + } + } + + return $this->interwikiLookup->fetch( $prefix ); + } + + /** + * @since 2.0.1 + * + * @param bool|null $local + * + * @return array[] + */ + public function getAllPrefixes( $local = null ) { + return $this->interwikiLookup->getAllPrefixes( $local ); + } + + /** + * @since 2.0.1 + * + * @param string $prefix + */ + public function invalidateCache( $prefix ) { + $this->interwikiLookup->invalidateCache( $prefix ); + } + +} diff --git a/src/MediaWikiServicesHandler.php b/src/MediaWikiServicesHandler.php new file mode 100644 index 0000000..871b558 --- /dev/null +++ b/src/MediaWikiServicesHandler.php @@ -0,0 +1,44 @@ +addServiceManipulator( + 'InterwikiLookup', + static function ( $interwikiLookup, MediaWikiServices $serviceContainer ) { + $dynamicInterwikiPrefixLoader = new DynamicInterwikiPrefixLoader( + $GLOBALS['seqlgExternalRepositoryEndpoints'] ?? [] + ); + + return new InterwikiLookupDecorator( + $interwikiLookup, + $dynamicInterwikiPrefixLoader, + $serviceContainer->getContentLanguage() + ); + } + ); + } + +} diff --git a/src/Setup.php b/src/Setup.php index 2dd4b14..13ed239 100644 --- a/src/Setup.php +++ b/src/Setup.php @@ -17,15 +17,15 @@ public static function onExtensionFunction() { class_alias( ByHttpRequestQueryLookup::class, 'SMWExternalQueryLookup' ); // deprecated class_alias( ByHttpRequestQueryLookup::class, 'SMWExternalAskQueryLookup' ); - $options = [ - 'externalRepositoryEndpoints' => $GLOBALS['seqlgExternalRepositoryEndpoints'] - ]; - $hookRegistry = new HookRegistry( - $options + [] ); $hookRegistry->register(); + + // The InterwikiLookup decoration for `seqlgExternalRepositoryEndpoints` + // happens in `MediaWikiServicesHandler` via the `MediaWikiServices` hook + // (see extension.json), ahead of any service instantiation. } } diff --git a/tests/phpunit/Integration/ByHttpRequest/JsonParseOnFauxHttpResponseTest.php b/tests/phpunit/Integration/ByHttpRequest/JsonParseOnFauxHttpResponseTest.php index 457780a..3f2f4b6 100644 --- a/tests/phpunit/Integration/ByHttpRequest/JsonParseOnFauxHttpResponseTest.php +++ b/tests/phpunit/Integration/ByHttpRequest/JsonParseOnFauxHttpResponseTest.php @@ -2,9 +2,9 @@ namespace SEQL\Tests\Integration\ByHttpRequest; +use MediaWiki\MediaWikiServices; use SEQL\ByHttpRequest\JsonResponseParser; use SEQL\DataValueDeserializer; -use SEQL\HookRegistry; use SMW\DataItems\Property; use SMW\DataItems\WikiPage; use SMW\Tests\Utils\UtilityFactory; @@ -20,6 +20,8 @@ */ class JsonParseOnFauxHttpResponseTest extends \PHPUnit\Framework\TestCase { + private $oldExternalRepositoryEndpoints; + protected function setUp(): void { $externalRepositoryEndpoints = [ 'api-foo' => [ @@ -29,11 +31,37 @@ protected function setUp(): void { ] ]; - $hookRegistry = new HookRegistry( [ - 'externalRepositoryEndpoints' => $externalRepositoryEndpoints - ] ); + // The `api-foo` prefix is resolved by the InterwikiLookup decorator + // (registered via the `MediaWikiServices` hook), which reads the + // endpoints from the global when the decorator is instantiated. + // `Title::newFromText` consults the `TitleParser`/`_MediaWikiTitleCodec` + // services and those captured the `InterwikiLookup` at their own + // instantiation, therefore the whole chain has to be reset to make + // the endpoints above visible to title parsing. + $this->oldExternalRepositoryEndpoints = $GLOBALS['seqlgExternalRepositoryEndpoints'] ?? false; + $GLOBALS['seqlgExternalRepositoryEndpoints'] = $externalRepositoryEndpoints; + + $services = MediaWikiServices::getInstance(); + $services->resetServiceForTesting( 'InterwikiLookup' ); + $services->resetServiceForTesting( '_MediaWikiTitleCodec' ); + $services->resetServiceForTesting( 'TitleParser' ); + } + + protected function tearDown(): void { + if ( $this->oldExternalRepositoryEndpoints === false ) { + unset( $GLOBALS['seqlgExternalRepositoryEndpoints'] ); + } else { + $GLOBALS['seqlgExternalRepositoryEndpoints'] = $this->oldExternalRepositoryEndpoints; + } + + if ( MediaWikiServices::hasInstance() ) { + $services = MediaWikiServices::getInstance(); + $services->resetServiceForTesting( 'InterwikiLookup' ); + $services->resetServiceForTesting( '_MediaWikiTitleCodec' ); + $services->resetServiceForTesting( 'TitleParser' ); + } - $hookRegistry->register(); + parent::tearDown(); } /** diff --git a/tests/phpunit/Unit/ByHttpRequest/QueryResultFetcherTest.php b/tests/phpunit/Unit/ByHttpRequest/QueryResultFetcherTest.php index 08f4c88..96ab9b3 100644 --- a/tests/phpunit/Unit/ByHttpRequest/QueryResultFetcherTest.php +++ b/tests/phpunit/Unit/ByHttpRequest/QueryResultFetcherTest.php @@ -300,6 +300,171 @@ public function testHttpRequestToReturnWithError() { ); } + public function testTransportFailureAddsErrorInsteadOfSilentEmptyResult() { + $queryResultFactory = new QueryResultFactory( $this->store ); + + $printRequest = $this->getMockBuilder( '\SMW\Query\PrintRequest' ) + ->disableOriginalConstructor() + ->getMock(); + + $printRequest->expects( $this->any() ) + ->method( 'getSerialisation' ) + ->willReturn( '?ABC' ); + + $description = $this->getMockBuilder( '\SMW\Query\Language\Description' ) + ->disableOriginalConstructor() + ->getMock(); + + $description->expects( $this->any() ) + ->method( 'getPrintrequests' ) + ->willReturn( [ $printRequest ] ); + + $query = $this->getMockBuilder( '\SMW\Query\Query' ) + ->disableOriginalConstructor() + ->getMock(); + + $query->expects( $this->any() ) + ->method( 'getSortKeys' ) + ->willReturn( [] ); + + $query->expects( $this->any() ) + ->method( 'getExtraPrintouts' ) + ->willReturn( [ $printRequest ] ); + + $query->expects( $this->any() ) + ->method( 'getDescription' ) + ->willReturn( $description ); + + $errors = []; + + $query->expects( $this->once() ) + ->method( 'addErrors' ) + ->willReturnCallback( static function ( $e ) use ( &$errors ) { + $errors = $e; + } ); + + $this->httpRequest->expects( $this->any() ) + ->method( 'execute' ) + ->willReturn( Status::newFatal( 'http-bad-status', '503', 'Service Unavailable' ) ); + + $instance = new QueryResultFetcher( + $this->httpRequestFactory, + $this->cache, + $queryResultFactory, + $this->jsonResponseParser, + [] + ); + + $instance->setHttpRequestEndpoint( 'http://example.org/api.php' ); + $instance->setRepositoryTargetUrl( 'http://example.org/$1' ); + + $this->assertInstanceOf( + '\SMW\Query\QueryResult', + $instance->fetchQueryResult( $query ) + ); + + $this->assertCount( 1, $errors ); + $this->assertStringContainsString( 'http://example.org/api.php', $errors[0] ); + } + + public function testUndecodableResponseAddsErrorAndIsNotCached() { + $queryResultFactory = new QueryResultFactory( $this->store ); + $cache = new HashBagOStuff(); + + $printRequest = $this->getMockBuilder( '\SMW\Query\PrintRequest' ) + ->disableOriginalConstructor() + ->getMock(); + + $printRequest->expects( $this->any() ) + ->method( 'getSerialisation' ) + ->willReturn( '?ABC' ); + + $description = $this->getMockBuilder( '\SMW\Query\Language\Description' ) + ->disableOriginalConstructor() + ->getMock(); + + $description->expects( $this->any() ) + ->method( 'getPrintrequests' ) + ->willReturn( [ $printRequest ] ); + + $query = $this->getMockBuilder( '\SMW\Query\Query' ) + ->disableOriginalConstructor() + ->getMock(); + + $query->expects( $this->any() ) + ->method( 'getQueryString' ) + ->willReturn( '[[Category:City]]' ); + + $query->expects( $this->any() ) + ->method( 'getLimit' ) + ->willReturn( 10 ); + + $query->expects( $this->any() ) + ->method( 'getOffset' ) + ->willReturn( 0 ); + + $query->expects( $this->any() ) + ->method( 'getMainLabel' ) + ->willReturn( '' ); + + $query->expects( $this->any() ) + ->method( 'getSortKeys' ) + ->willReturn( [] ); + + $query->expects( $this->any() ) + ->method( 'getExtraPrintouts' ) + ->willReturn( [ $printRequest ] ); + + $query->expects( $this->any() ) + ->method( 'getDescription' ) + ->willReturn( $description ); + + $errors = []; + + $query->expects( $this->once() ) + ->method( 'addErrors' ) + ->willReturnCallback( static function ( $e ) use ( &$errors ) { + $errors = $e; + } ); + + // A HTML error page or similar: the transport succeeded but the + // body is no JSON + $this->httpRequest->expects( $this->any() ) + ->method( 'getContent' ) + ->willReturn( 'Blocked by crawler protection' ); + + $instance = new QueryResultFetcher( + $this->httpRequestFactory, + $cache, + $queryResultFactory, + $this->jsonResponseParser, + [] + ); + + $instance->setHttpRequestEndpoint( 'http://example.org/api.php' ); + $instance->setRepositoryTargetUrl( 'http://example.org/$1' ); + $instance->setHttpResponseCachePrefix( 'Foo' ); + $instance->setHttpResponseCacheLifetime( 42 ); + + $this->assertInstanceOf( + '\SMW\Query\QueryResult', + $instance->fetchQueryResult( $query ) + ); + + $this->assertCount( 1, $errors ); + $this->assertStringContainsString( 'http://example.org/api.php', $errors[0] ); + + // The garbage response must not have been written to the response + // cache, otherwise the error would be frozen for the cache lifetime + $url = 'http://example.org/api.php?action=ask&format=json&query=' . rawurlencode( + '[[Category:City]]|?ABC|limit=10|offset=0|mainlabel=' + ); + + $this->assertFalse( + $cache->get( $cache->makeKey( 'seql', 'Foo', md5( $url ) ) ) + ); + } + public function testHttpRequestToReturnWithValidJson() { $queryResultFactory = new QueryResultFactory( $this->store ); diff --git a/tests/phpunit/Unit/DynamicInterwikiPrefixLoaderTest.php b/tests/phpunit/Unit/DynamicInterwikiPrefixLoaderTest.php index d83e5e7..f08b374 100644 --- a/tests/phpunit/Unit/DynamicInterwikiPrefixLoaderTest.php +++ b/tests/phpunit/Unit/DynamicInterwikiPrefixLoaderTest.php @@ -24,6 +24,74 @@ public function testCanConstruct() { ); } + public function testIsEnabledPrefixForExternalRepository() { + $interwikiPrefixMap = [ + 'mw-foo' => [ + 'http://example.org:8080/mw-foo/index.php/$1', + 'http://example.org:8080/mw-foo/api.php', + true + ] + ]; + + $instance = new DynamicInterwikiPrefixLoader( $interwikiPrefixMap ); + + $this->assertTrue( + $instance->isEnabledPrefixForExternalRepository( 'mw-foo' ) + ); + + $this->assertFalse( + $instance->isEnabledPrefixForExternalRepository( 'mw-bar' ) + ); + } + + public function testNewInterwikiForExternalRepositoryMatch() { + $interwikiPrefixMap = [ + 'mw-foo' => [ + 'http://example.org:8080/mw-foo/index.php/$1', // corresponds to iw_url + 'http://example.org:8080/mw-foo/api.php', // corresponds to iw_api + true // corresponds to iw_local + ] + ]; + + $instance = new DynamicInterwikiPrefixLoader( $interwikiPrefixMap ); + + $interwiki = $instance->newInterwiki( 'mw-foo' ); + + $this->assertInstanceOf( + '\Interwiki', + $interwiki + ); + + $this->assertEquals( + 'http://example.org:8080/mw-foo/index.php/$1', + $interwiki->getURL() + ); + + $this->assertEquals( + 'http://example.org:8080/mw-foo/api.php', + $interwiki->getAPI() + ); + + $this->assertEquals( + 'mw-foo', + $interwiki->getWikiID() + ); + + $this->assertTrue( + $interwiki->isLocal() + ); + } + + public function testNewInterwikiForNoExternalRepositoryMatch() { + $interwikiPrefixMap = []; + + $instance = new DynamicInterwikiPrefixLoader( $interwikiPrefixMap ); + + $this->assertNull( + $instance->newInterwiki( 'mw-foo' ) + ); + } + public function testLoadIwMapForExternalRepositoryMatch() { $interwikiPrefixMap = [ 'mw-foo' => [ diff --git a/tests/phpunit/Unit/ExtensionJsonHookRegistrationTest.php b/tests/phpunit/Unit/ExtensionJsonHookRegistrationTest.php new file mode 100644 index 0000000..6ba5623 --- /dev/null +++ b/tests/phpunit/Unit/ExtensionJsonHookRegistrationTest.php @@ -0,0 +1,77 @@ += 1.41 (and + * current 1.43) fail during extension registration with + * `TypeError: Cannot access offset of type array on array` in + * `ExtensionProcessor.php` before any SEQL code runs. + * + * @covers \SEQL\MediaWikiServicesHandler + * @group semantic-external-query-lookup + * + * @license GPL-2.0-or-later + * @since 2.0.1 + */ +class ExtensionJsonHookRegistrationTest extends TestCase { + + private const EXTENSION_JSON_PATH = __DIR__ . '/../../../extension.json'; + + public function testExtensionJsonIsValid() { + $extensionJson = json_decode( file_get_contents( self::EXTENSION_JSON_PATH ), true ); + + $this->assertNotNull( + $extensionJson, + 'extension.json contains invalid JSON' + ); + } + + public function testMediaWikiServicesHookReferencesHookHandlersEntry() { + $extensionJson = json_decode( file_get_contents( self::EXTENSION_JSON_PATH ), true ); + + $this->assertArrayHasKey( + 'Hooks', + $extensionJson, + 'extension.json must register the MediaWikiServices hook' + ); + + $hook = $extensionJson['Hooks']['MediaWikiServices'] ?? null; + + $this->assertIsString( + $hook, + '`Hooks.MediaWikiServices` must be a string naming a `HookHandlers` entry; ' + . 'an inline `handler` object crashes MW\'s ExtensionProcessor' + ); + + $this->assertArrayHasKey( + 'HookHandlers', + $extensionJson + ); + + $handler = $extensionJson['HookHandlers'][$hook] ?? null; + + $this->assertIsArray( + $handler, + "`Hooks.MediaWikiServices` references missing `HookHandlers.$hook` entry" + ); + + $this->assertArrayHasKey( + 'class', + $handler + ); + + $this->assertTrue( + is_a( $handler['class'], 'MediaWiki\Hook\MediaWikiServicesHook', true ), + $handler['class'] . ' must implement MediaWikiServicesHook' + ); + } + +} diff --git a/tests/phpunit/Unit/HookRegistryTest.php b/tests/phpunit/Unit/HookRegistryTest.php index 3569531..bfe502e 100644 --- a/tests/phpunit/Unit/HookRegistryTest.php +++ b/tests/phpunit/Unit/HookRegistryTest.php @@ -2,6 +2,7 @@ namespace SEQL\Tests; +use PHPUnit\Framework\MockObject\MockObject; use SEQL\HookRegistry; /** @@ -16,50 +17,69 @@ class HookRegistryTest extends \PHPUnit\Framework\TestCase { public function testCanConstruct() { - $options = [ - 'externalRepositoryEndpoints' => [], - ]; - $this->assertInstanceOf( '\SEQL\HookRegistry', - new HookRegistry( $options ) + new HookRegistry( [] ) ); } public function testRegister() { - $options = [ - 'externalRepositoryEndpoints' => [], - ]; - $instance = new HookRegistry( - $options + [] ); $instance->register(); - $this->doTestRegisteredInterwikiLoadPrefixHandler( $instance ); + $this->doTestRegisteredSmwAskParserFunctionHandler( $instance ); + $this->doTestRegisteredSmwShowParserFunctionHandler( $instance ); } - public function doTestRegisteredInterwikiLoadPrefixHandler( $instance ) { - $handler = 'InterwikiLoadPrefix'; + public function doTestRegisteredSmwAskParserFunctionHandler( $instance ) { + $handler = 'smwAskParserFunction'; + + $this->assertTrue( + $instance->isRegistered( $handler ) + ); + + $override = false; + + $this->assertThatHookIsExcutable( + $instance->getHandlerFor( $handler ), + [ $this->newParserMock(), false, [], &$override ] + ); + } - $prefix = ''; - $interwiki = []; + public function doTestRegisteredSmwShowParserFunctionHandler( $instance ) { + $handler = 'smwShowParserFunction'; $this->assertTrue( $instance->isRegistered( $handler ) ); + $override = false; + $this->assertThatHookIsExcutable( $instance->getHandlerFor( $handler ), - [ $prefix, &$interwiki ] + [ $this->newParserMock(), false, [], &$override ] ); } + /** + * The `smwAskParserFunction`/`smwShowParserFunction` handlers communicate + * through the `$override` reference and return no value. + */ private function assertThatHookIsExcutable( \Closure $handler, $arguments ) { - $this->assertIsBool( + $this->assertNull( call_user_func_array( $handler, $arguments ) ); } + private function newParserMock(): MockObject { + $parser = $this->getMockBuilder( '\Parser' ) + ->disableOriginalConstructor() + ->getMock(); + + return $parser; + } + } diff --git a/tests/phpunit/Unit/InterwikiLookupDecoratorTest.php b/tests/phpunit/Unit/InterwikiLookupDecoratorTest.php new file mode 100644 index 0000000..e01080b --- /dev/null +++ b/tests/phpunit/Unit/InterwikiLookupDecoratorTest.php @@ -0,0 +1,209 @@ + [ + 'http://example.org:8080/mw-foo/index.php/$1', + 'http://example.org:8080/mw-foo/api.php', + true + ] + ]; + + public function testCanConstruct() { + $interwikiLookup = $this->createMock( '\MediaWiki\Interwiki\InterwikiLookup' ); + + $this->assertInstanceOf( + '\SEQL\InterwikiLookupDecorator', + new InterwikiLookupDecorator( + $interwikiLookup, + new DynamicInterwikiPrefixLoader( [] ), + $this->newContentLanguageMock() + ) + ); + } + + public function testFetchOnExternalRepositoryPrefix() { + $interwikiLookup = $this->createMock( '\MediaWiki\Interwiki\InterwikiLookup' ); + + $interwikiLookup->expects( $this->never() ) + ->method( 'fetch' ); + + $instance = new InterwikiLookupDecorator( + $interwikiLookup, + new DynamicInterwikiPrefixLoader( $this->interwikiPrefixMap ), + $this->newContentLanguageMock() + ); + + // Mirrors `ClassicInterwikiLookup::fetch()` resolving the prefix + // with the content language (case-insensitive match) + $interwiki = $instance->fetch( 'MW-FOO' ); + + $this->assertInstanceOf( + '\Interwiki', + $interwiki + ); + + $this->assertEquals( + 'http://example.org:8080/mw-foo/api.php', + $interwiki->getAPI() + ); + + $this->assertEquals( + 'http://example.org:8080/mw-foo/index.php/$1', + $interwiki->getURL() + ); + } + + public function testFetchOnNonExternalRepositoryPrefixIsDelegated() { + $interwiki = $this->createMock( '\Interwiki' ); + + $interwikiLookup = $this->createMock( '\MediaWiki\Interwiki\InterwikiLookup' ); + + $interwikiLookup->expects( $this->once() ) + ->method( 'fetch' ) + ->with( 'mw-bar' ) + ->willReturn( $interwiki ); + + $instance = new InterwikiLookupDecorator( + $interwikiLookup, + new DynamicInterwikiPrefixLoader( $this->interwikiPrefixMap ), + $this->newContentLanguageMock() + ); + + $this->assertSame( + $interwiki, + $instance->fetch( 'mw-bar' ) + ); + } + + public function testIsValidInterwikiOnExternalRepositoryPrefix() { + $interwikiLookup = $this->createMock( '\MediaWiki\Interwiki\InterwikiLookup' ); + + // Only the delegation for a non-external prefix is expected to hit + // the decorated InterwikiLookup + $interwikiLookup->expects( $this->once() ) + ->method( 'isValidInterwiki' ) + ->with( 'mw-bar' ) + ->willReturn( true ); + + $instance = new InterwikiLookupDecorator( + $interwikiLookup, + new DynamicInterwikiPrefixLoader( $this->interwikiPrefixMap ), + $this->newContentLanguageMock() + ); + + $this->assertTrue( + $instance->isValidInterwiki( 'mw-foo' ) + ); + + $this->assertTrue( + $instance->isValidInterwiki( 'mw-bar' ) + ); + } + + public function testGetAllPrefixesIsDelegated() { + $interwikiLookup = $this->createMock( '\MediaWiki\Interwiki\InterwikiLookup' ); + + $interwikiLookup->expects( $this->once() ) + ->method( 'getAllPrefixes' ) + ->with( null ) + ->willReturn( [] ); + + $instance = new InterwikiLookupDecorator( + $interwikiLookup, + new DynamicInterwikiPrefixLoader( $this->interwikiPrefixMap ), + $this->newContentLanguageMock() + ); + + $this->assertSame( + [], + $instance->getAllPrefixes() + ); + } + + public function testFetchAndIsValidInterwikiWithNullOrEmptyPrefixIssueNoWarning() { + $interwikiLookup = $this->createMock( '\MediaWiki\Interwiki\InterwikiLookup' ); + + $fetchArgs = []; + $interwikiLookup->method( 'fetch' ) + ->willReturnCallback( static function ( $prefix ) use ( &$fetchArgs ) { + $fetchArgs[] = $prefix; + return $prefix === null ? null : false; + } ); + + $isValidArgs = []; + $interwikiLookup->method( 'isValidInterwiki' ) + ->willReturnCallback( static function ( $prefix ) use ( &$isValidArgs ) { + $isValidArgs[] = $prefix; + return false; + } ); + + // Any PHP warning, deprecation, or notice (e.g. `strtolower( null )` + // on PHP 8.1+) fails the test + set_error_handler( static function ( $errno, $errstr ) { + throw new \ErrorException( $errstr ); + } ); + + try { + $instance = new InterwikiLookupDecorator( + $interwikiLookup, + new DynamicInterwikiPrefixLoader( $this->interwikiPrefixMap ), + $this->newContentLanguageMock() + ); + + $this->assertNull( $instance->fetch( null ) ); + $this->assertFalse( $instance->fetch( '' ) ); + $this->assertFalse( $instance->isValidInterwiki( null ) ); + $this->assertFalse( $instance->isValidInterwiki( '' ) ); + } finally { + restore_error_handler(); + } + + // Null/empty prefixes are delegated unaltered, never resolved against + // the content language or the external repository endpoints + $this->assertSame( [ null, '' ], $fetchArgs ); + $this->assertSame( [ null, '' ], $isValidArgs ); + } + + public function testInvalidateCacheIsDelegated() { + $interwikiLookup = $this->createMock( '\MediaWiki\Interwiki\InterwikiLookup' ); + + $interwikiLookup->expects( $this->once() ) + ->method( 'invalidateCache' ) + ->with( 'mw-bar' ); + + $instance = new InterwikiLookupDecorator( + $interwikiLookup, + new DynamicInterwikiPrefixLoader( $this->interwikiPrefixMap ), + $this->newContentLanguageMock() + ); + + $instance->invalidateCache( 'mw-bar' ); + } + + private function newContentLanguageMock(): Language { + $contentLanguage = $this->createMock( Language::class ); + + $contentLanguage->method( 'lc' ) + ->willReturnCallback( static function ( $str ) { + return strtolower( $str ); + } ); + + return $contentLanguage; + } + +}