Add public Cypher query REST API + close #549

[alistair3149]

Fixes #549

Summary

• Adds POST /neowiki/v0/query/cypher — public read-only Cypher endpoint with stable JSON envelope (columns, rows, truncated, resultCount, durationMs) and stable errorType strings keyed to documented HTTP statuses.
• Funnels all three Cypher surfaces (REST, nw.query Lua, {{#cypher_raw}} parser fn) through a shared QueryService so validation, transaction timeout, result-row cap, and exception translation live in one place.
• Closes Add protection against expensive Cypher queries #549 (no transaction timeout, no LIMIT enforcement, no rate limiting on user-supplied Cypher) by applying the safety caps in QueryService and rate-limiting at the REST surface only (parser/Lua skip pingLimiter because their output is parser-cached).

Per-surface user controls:

• neowiki-query user right (default *) gates whether anyone can call the endpoint at all. Sysadmin lockdown: $wgGroupPermissions['*']['neowiki-query'] = false;
• Core's apihighlimits (default bot/sysop) lifts limits to the expensive tier (300s / 50,000 rows vs default 30s / 5,000 rows).
• $wgRateLimits['neowiki-query'] ships defaults: anon 10/min, user 60/min, bot 1000/min. Sysop/bureaucrat exempt via core noratelimit.
• $wgNeoWikiQueryLimits overrides per-query timeout and row cap per tier.

Architecture follows ADR 19 (no NeoWiki-specific query abstraction language; per-backend honesty). The future SPARQL endpoint will sit alongside as /neowiki/v0/query/sparql with its own service.

Files

• New: src/Application/Query/{QueryService,QueryRequest,QueryResult,QueryLimits,QueryResultNormalizer}.php + 7 typed exception classes
• New: src/EntryPoints/REST/QueryCypherApi.php
• New: docs/QueryApi.md (discovery flow, contract, Neo4j-side deployment recommendations)
• Refactored: CypherQueryRunner (Lua) and CypherRawParserFunction (parser fn) into thin adapters over QueryService
• Modified: extension.json (right, RateLimits, config, route), Neo4jQueryStore::runReadQuery() (timeout)
• Tests: 80+ new test methods across unit, integration, and end-to-end-against-real-Neo4j layers

Markup change

{{#cypher_raw}} output wrapping is now <div class="mw-neowiki-cypher-result"><pre>...</pre></div> (was <pre><code class="json">...</code></pre>). Anyone who styled the old markup will need to update selectors.

Test plan

• make phpunit filtered by each new test class (QueryServiceTest, QueryCypherApiTest, QueryLimitsTest, QueryResultNormalizerTest, QueryExceptionTest, Neo4jQueryStoreTimeoutTest, QueryCypherEndToEndTest) and the refactored ones (CypherQueryRunnerTest, CypherRawParserFunctionTest) — all green
• make cs clean
• OpenAPI spec drift test (ModuleSpecHandlerNeoWikiTest) still green; new route appears at /rest.php/specs/v0/module/-

Manual Browser Check

The parser-function markup change is visible to anyone using {{#cypher_raw}} on a wiki page.

1. Visit a page that uses {{#cypher_raw}} (the demo wiki has examples; if unsure, edit a sandbox page and add {{#cypher_raw: MATCH (p:Page) RETURN p.name LIMIT 5}}).
2. View source in browser devtools and confirm the rendered output is wrapped in <div class="mw-neowiki-cypher-result"><pre>...</pre></div>.
3. Confirm the JSON inside the <pre> is pretty-printed and HTML-escaped (no <script> execution from data values).

Manual API Check

The REST endpoint can be exercised directly via curl. Replace localhost:8484 with your dev wiki URL.

# Happy path — count pages
curl -sS -X POST http://localhost:8484/rest.php/neowiki/v0/query/cypher \
  -H 'Content-Type: application/json' \
  -d '{"cypher": "MATCH (n:Page) RETURN count(n) AS pages"}'
# Expect: 200 with {"columns":["pages"],"rows":[{"pages":N}],...}

# Empty query — error contract
curl -sS -w '\nHTTP %{http_code}\n' -X POST http://localhost:8484/rest.php/neowiki/v0/query/cypher \
  -H 'Content-Type: application/json' \
  -d '{"cypher": "   "}'
# Expect: 400 with {"errorType":"emptyQuery","message":"Query is empty."}

# Write query — rejected
curl -sS -w '\nHTTP %{http_code}\n' -X POST http://localhost:8484/rest.php/neowiki/v0/query/cypher \
  -H 'Content-Type: application/json' \
  -d '{"cypher": "CREATE (n:Test) RETURN n"}'
# Expect: 422 with {"errorType":"writeQueryRejected",...}

# Cypher syntax error — clean message, correct status
curl -sS -w '\nHTTP %{http_code}\n' -X POST http://localhost:8484/rest.php/neowiki/v0/query/cypher \
  -H 'Content-Type: application/json' \
  -d '{"cypher": "MATCH (n RETURN n"}'
# Expect: 400 with {"errorType":"cypherSyntaxError","message":"Invalid input 'RETURN'..."}

# Parameters work
curl -sS -X POST http://localhost:8484/rest.php/neowiki/v0/query/cypher \
  -H 'Content-Type: application/json' \
  -d '{"cypher": "RETURN $name AS hi", "parameters": {"name": "world"}}'
# Expect: 200 with {"rows":[{"hi":"world"}],...}

# OpenAPI spec exposes the route (requires $wgRestAPIAdditionalRouteFiles[] = 'includes/Rest/specs.v0.json';)
curl -sS http://localhost:8484/rest.php/specs/v0/module/- | python3 -c 'import json,sys; print(json.load(sys.stdin)["paths"]["/neowiki/v0/query/cypher"])'
# Expect: a JSON object describing the POST endpoint

Known gaps (deliberate)

• QueryCypherApiTest::testRateLimitedReturns429 is markTestIncomplete — pingLimiter is hard to trip in integration tests without lots of session setup; behavior is exercised by manual testing.
• Truncation happens after full normalization rather than slicing the CypherList first. Bounded by maxRows so the worst case is bounded; flagged in code review as a perf optimization to revisit if real workloads show a problem.

[alistair3149]

I picked a separate user rights for easier spam protections for wiki admins

[alistair3149]

Make the query limit more granular with timeout and max rows.

[JeroenDeDauw]

Has some organization/architecture issues. I'm investigating