Document internal surfaces and the PHP Cypher query path

docs/extending/extending.md

@@ -190,6 +190,31 @@ you to remove pages that are already gone from your store.
 Examples: [`src/RedHerbSidebarHook.php`](https://github.com/ProfessionalWiki/NeoWiki/blob/master/tests/RedHerb/src/RedHerbSidebarHook.php)
 and [`src/Specials/SpecialRedHerbSubjectFinder.php`](https://github.com/ProfessionalWiki/NeoWiki/blob/master/tests/RedHerb/src/Specials/SpecialRedHerbSubjectFinder.php).
 
+### Running Cypher queries
+
+To run a read-only Cypher query from PHP, use `NeoWikiExtension::getInstance()->newCypherQueryService()`.
+It rejects write queries and enforces the timeout and row cap you pass as limits; resolve the values
+configured in [`$wgNeoWikiQueryLimits`](../api/query-api.md) with `Neo4jQueryLimits::forUser()` (users
+with `apihighlimits` get the higher tier):
+
+```php
+$result = NeoWikiExtension::getInstance()->newCypherQueryService()->execute( new Neo4jQueryRequest(
+	cypher: 'MATCH (s:Subject:Person) WHERE s.`Birth year` > $minYear RETURN s.name AS name',
+	parameters: [ 'minYear' => 2000 ],
+	limits: Neo4jQueryLimits::forUser( $this->getUser() ),
+) );
+```
+
+`execute()` returns a `Neo4jQueryResult` (columns, rows, truncation flag) and throws a `QueryException`
+subclass on failure; `newCypherQueryService()` itself throws a `LogicException` on a wiki with no graph
+backend configured.
+
+The `User` in `forUser()` only sizes the limits: how heavy a single query may be, not whether the user may
+query at all or how often. When running user-supplied queries, check the `neowiki-query` right and rate
+limit yourself, as the [Query API](../api/query-api.md) endpoint does.
+
+Example: [`src/Specials/SpecialRedHerbContentPageCount.php`](https://github.com/ProfessionalWiki/NeoWiki/blob/master/tests/RedHerb/src/Specials/SpecialRedHerbContentPageCount.php).
+
 ## Frontend extension points (JS/Vue)
 
 NeoWiki's frontend is built with TypeScript and Vue. Extensions consume it as plain JavaScript and need no build step.
@@ -377,3 +402,51 @@ These extension points are designed or partially present but not yet open to ext
 - **A published TypeScript types package.** TypeScript authors get types today by pointing their `tsconfig` at
   NeoWiki's source (see "Authoring in TypeScript" and [ADR 24](../adr/024-frontend-extension-mechanism.md)). A
   published, versioned package is deferred until a consumer needs types without a NeoWiki checkout.
+
+## Internal surfaces
+
+Everything on this page is alpha, but the surfaces below are internal even by that standard: they are
+implementation details that happen to be reachable, and they can change in any release without notice.
+
+### NeoWiki's rendered HTML
+
+The `.ext-neowiki-view` placeholder elements and `data-mw-neowiki-*` attributes are the private contract
+between NeoWiki's backend and its frontend for mounting Views. They are not an integration surface: do not
+select these elements, read Subject IDs out of them, restyle their internals, or remove and replace them
+with your own rendering. Their structure can change in any release.
+
+To control where and how a Subject renders:
+
+- To place a Subject rendering in page content, use the
+  [`{{#view}}` parser function](../authoring/parser-functions.md), optionally with a Layout to control which
+  properties are shown.
+- To render Subjects in your own visual format, register a custom View Type
+  (see [Registering a View Type frontend](#registering-a-view-type-frontend)).
+- For fully custom UI outside the View system, fetch the data through the [REST API](../api/rest-api.md) or
+  the [public JS API](#using-neowikis-public-js-api) and render your own components, mounted as described in
+  [Mounting standalone Vue features](#mounting-standalone-vue-features).
+
+### The internal Neo4j client
+
+`NeoWikiExtension::getInstance()->getNeo4jClient()` and `getReadOnlyNeo4jClient()` return the Laudis client
+NeoWiki itself uses. Neo4j access is treated as an implementation detail of NeoWiki's persistence layer
+([ADR 13](../adr/013-restrict-neo4j-access.md)). Nothing stops an extension from querying through the raw
+client, but compare what the documented query interfaces
+([`{{#cypher_raw}}`](../authoring/parser-functions.md), [`nw.query`](../authoring/lua-api.md), the
+[Query API](../api/query-api.md), and the [PHP query service](#running-cypher-queries)) provide over it:
+
+- **Read-only enforcement.** The query interfaces reject write queries (keyword check plus `EXPLAIN`);
+  with the raw client, a bug in calling code can corrupt the graph projection, which is what ADR 13
+  exists to prevent.
+- **Resource limits.** The query interfaces apply a configured timeout and row cap; the raw client runs
+  unbounded queries.
+- **Result handling.** The query interfaces return normalized rows and columns; the raw client returns
+  Laudis driver types that you convert yourself.
+- **Churn exposure.** The query interfaces are documented contracts (alpha, like everything on this page);
+  the client accessors are internal wiring that can change or disappear in any release.
+
+Writing to the graph directly deserves particular caution: the graph is a projection of wiki content that
+NeoWiki rewrites at will. Saving a page re-projects that page's nodes, and the `RebuildGraphDatabases`
+maintenance script rebuilds the projection from scratch, so anything a third party writes into the graph
+can be overwritten, orphaned, or deleted at any time. To contribute data to the graph durably, use
+[Page Property Providers](#page-property-providers), which NeoWiki re-runs on every save and rebuild.

tests/RedHerb/README.md

@@ -24,6 +24,8 @@ extension point to the file that demonstrates it.
   [`src/RedHerbFrontendModulesHook.php`](src/RedHerbFrontendModulesHook.php).
 - **Reading NeoWiki data / authorization** — [`src/RedHerbSidebarHook.php`](src/RedHerbSidebarHook.php) and
   [`src/Specials/SpecialRedHerbSubjectFinder.php`](src/Specials/SpecialRedHerbSubjectFinder.php).
+- **Running Cypher queries (PHP query service)** —
+  [`src/Specials/SpecialRedHerbContentPageCount.php`](src/Specials/SpecialRedHerbContentPageCount.php).
 
 ### Frontend (JS/Vue)
 

tests/RedHerb/extension.json

@@ -47,6 +47,9 @@
 	"SpecialPages": {
 		"RedHerbSubjectFinder": {
 			"class": "ProfessionalWiki\\RedHerb\\Specials\\SpecialRedHerbSubjectFinder"
+		},
+		"RedHerbContentPageCount": {
+			"class": "ProfessionalWiki\\RedHerb\\Specials\\SpecialRedHerbContentPageCount"
 		}
 	},
 

tests/RedHerb/i18n/_Aliases.php

@@ -4,4 +4,5 @@
 
 $specialPageAliases['en'] = [
 	'RedHerbSubjectFinder' => [ 'RedHerbSubjectFinder' ],
+	'RedHerbContentPageCount' => [ 'RedHerbContentPageCount' ],
 ];

tests/RedHerb/i18n/en.json

@@ -6,6 +6,9 @@
 	"redherb-sidebar-create-child-company": "Create child Company",
 	"redherb-sidebar-subject-finder": "Find a subject",
 	"redherb-special-subject-finder": "RedHerb subject finder",
+	"redherb-special-content-page-count": "RedHerb content page count",
+	"redherb-content-page-count": "Content namespace pages tracked in the graph: $1",
+	"redherb-content-page-count-error": "Could not count content namespace pages tracked in the graph.",
 	"redherb-subject-finder-schema-label": "Schema",
 	"redherb-subject-finder-schema-placeholder": "Enter a schema name",
 	"redherb-subject-finder-pick-subject": "Pick a subject",

tests/RedHerb/i18n/qqq.json

@@ -6,6 +6,9 @@
 	"redherb-sidebar-create-child-company": "Text of the sidebar link that opens a dialog for creating a child Subject with the Company schema.",
 	"redherb-sidebar-subject-finder": "Text of the sidebar link that opens the RedHerb subject finder.",
 	"redherb-special-subject-finder": "Title shown on Special:RedHerbSubjectFinder.",
+	"redherb-special-content-page-count": "Title shown on Special:RedHerbContentPageCount.",
+	"redherb-content-page-count": "Result shown on Special:RedHerbContentPageCount, reporting how many content-namespace pages NeoWiki tracks in the graph. $1 is the count.",
+	"redherb-content-page-count-error": "Error shown on Special:RedHerbContentPageCount when the Cypher query fails.",
 	"redherb-subject-finder-schema-label": "Label of the schema name input on Special:RedHerbSubjectFinder.\n{{Identical|Schema}}",
 	"redherb-subject-finder-schema-placeholder": "Placeholder text inside the schema name input on Special:RedHerbSubjectFinder.",
 	"redherb-subject-finder-pick-subject": "Label of the subject lookup on Special:RedHerbSubjectFinder.",

tests/RedHerb/src/Specials/SpecialRedHerbContentPageCount.php

@@ -0,0 +1,46 @@
+<?php
+
+declare( strict_types = 1 );
+
+namespace ProfessionalWiki\RedHerb\Specials;
+
+use Exception;
+use MediaWiki\Message\Message;
+use MediaWiki\SpecialPage\SpecialPage;
+use ProfessionalWiki\NeoWiki\GraphDatabasePlugins\Neo4j\Application\Neo4jQueryLimits;
+use ProfessionalWiki\NeoWiki\GraphDatabasePlugins\Neo4j\Application\Neo4jQueryRequest;
+use ProfessionalWiki\NeoWiki\NeoWikiExtension;
+
+class SpecialRedHerbContentPageCount extends SpecialPage {
+
+	public function __construct() {
+		parent::__construct( 'RedHerbContentPageCount' );
+	}
+
+	/**
+	 * @param ?string $subPage
+	 */
+	public function execute( $subPage ): void {
+		parent::execute( $subPage );
+
+		$out = $this->getOutput();
+
+		try {
+			$result = NeoWikiExtension::getInstance()->newCypherQueryService()->execute( new Neo4jQueryRequest(
+				cypher: 'MATCH (page:Page) WHERE page.namespaceId = $namespaceId RETURN count(page) AS pageCount',
+				parameters: [ 'namespaceId' => NS_MAIN ],
+				limits: Neo4jQueryLimits::forUser( $this->getUser() ),
+			) );
+		} catch ( Exception ) {
+			$out->addWikiMsg( 'redherb-content-page-count-error' );
+			return;
+		}
+
+		$out->addWikiMsg( 'redherb-content-page-count', $result->rows[0]['pageCount'] );
+	}
+
+	public function getDescription(): Message {
+		return $this->msg( 'redherb-special-content-page-count' );
+	}
+
+}

tests/phpunit/RedHerb/SpecialRedHerbContentPageCountTest.php

@@ -0,0 +1,52 @@
+<?php
+
+declare( strict_types = 1 );
+
+namespace ProfessionalWiki\NeoWiki\Tests\RedHerb;
+
+use MediaWiki\Context\DerivativeContext;
+use MediaWiki\Context\RequestContext;
+use MediaWiki\Output\OutputPage;
+use MediaWiki\Title\Title;
+use ProfessionalWiki\NeoWiki\Tests\Data\TestSubject;
+use ProfessionalWiki\NeoWiki\Tests\NeoWikiIntegrationTestCase;
+use ProfessionalWiki\RedHerb\Specials\SpecialRedHerbContentPageCount;
+
+/**
+ * @covers \ProfessionalWiki\RedHerb\Specials\SpecialRedHerbContentPageCount
+ * @group Database
+ */
+class SpecialRedHerbContentPageCountTest extends NeoWikiIntegrationTestCase {
+
+	protected function setUp(): void {
+		parent::setUp();
+		$this->setUpNeo4j();
+		$this->createSchema( TestSubject::DEFAULT_SCHEMA_ID );
+		$this->markPageTableAsUsed();
+	}
+
+	public function testCountsOnlyContentNamespacePagesTrackedInTheGraph(): void {
+		$this->createPageWithSubjects( 'RedHerb content page one', TestSubject::build( id: 'sRedHerbCP11111' ) );
+		$this->createPageWithSubjects( 'RedHerb content page two', TestSubject::build( id: 'sRedHerbCP22222' ) );
+		$this->createPageWithSubjects( 'Help:RedHerb help page', TestSubject::build( id: 'sRedHerbHP33333' ) );
+
+		$this->assertStringContainsString(
+			'Content namespace pages tracked in the graph: 2',
+			$this->executeContentPageCount()
+		);
+	}
+
+	private function executeContentPageCount(): string {
+		$context = new DerivativeContext( RequestContext::getMain() );
+		$context->setTitle( Title::makeTitle( NS_SPECIAL, 'RedHerbContentPageCount' ) );
+		$output = new OutputPage( $context );
+		$context->setOutput( $output );
+
+		$page = new SpecialRedHerbContentPageCount();
+		$page->setContext( $context );
+		$page->execute( null );
+
+		return $output->getHTML();
+	}
+
+}