Migrate session.xq query execution pipeline to REST API

[joewiz]

Open Question: session.xq migration

The legacy module migration has removed most modules/*.xq files, but session.xq is fundamentally different from the others and warrants discussion before migrating.

Current Architecture

session.xq is not a standalone endpoint — it's a view in eXist-db's URL-rewrite pipeline:

1. POST execute — controller sends the user's query to XQueryServlet for evaluation, then pipes the results as a request attribute to session.xq, which stores them in the HTTP session and returns <result hits="N" elapsed="T"/>
2. GET results/N — controller forwards to session.xq with a num parameter, which retrieves item N from the session and returns an HTML <div> with badges, copy buttons, and syntax highlighting

The frontend (eXide.js) expects:

• XML <result> or <error> elements from execute
• HTML fragments from results/N, rendered directly into the DOM

API Replacement (already written)

modules/api/query.xqm already provides JSON equivalents:

• POST /api/query — executes via util:eval(), returns { id, count, elapsed, items[] }
• GET /api/query/{id}/results?start=N&count=M — paginated JSON result retrieval

Key Differences & Concerns

Aspect	session.xq (current)	query.xqm (API)
Execution	XQueryServlet (full context)	util:eval()
Error handling	XQueryServlet <error> elements, including null-description edge case	try/catch with structured JSON errors
Result rendering	Server-side HTML (<div> with badges, match highlights)	Client-side rendering from JSON strings
Match highlights	util:expand($item, "highlight-matches=both")	Not yet implemented
Serialization modes	html5, xhtml, xhtml5, json, text, xml, adaptive, microxml — non-XML modes bypass session and render directly in iframe	All modes serialize to JSON string items
Module load path	Set via xquery.module-load-path request attribute in controller	Passed as base parameter to util:eval()

Questions

1. XQueryServlet vs util:eval() — Are there meaningful behavioral differences? XQueryServlet sets up a full execution context via the URL rewrite chain. Does util:eval() with a base parameter provide equivalent module resolution?

2. Match highlighting — util:expand() with highlight-matches=both is used in session.xq for full-text search result highlighting. Should this be added to query.xqm, or handled client-side?

3. Non-XML serialization modes — Currently, non-standard output modes (html5, xhtml, etc.) bypass the session entirely and render raw output in an iframe. The API approach serializes everything to JSON strings. Is there a use case where raw iframe rendering is important?

4. Migration scope — Moving to the API requires rewriting the frontend result rendering (currently receives HTML, would need to build DOM from JSON). Is this worth doing now, or should session.xq remain as-is until a larger editor refactor?

Related

• PR Manual UI review: consistency and functionality fixes #12 (ui-review-polish) — current migration work
• Tracking issue eXide overhaul: PR chain #15 — eXide overhaul PR chain

[joewiz]

Additional: debuger.xq and git.xq frontend references

While the controller now returns 410 Gone for debuger.xq and git.xq, the frontend JS still has fetch calls to them:

• src/debuger.js:55 — fetch("modules/debuger.xq", ...)
• src/eXide.js:1459 — var gitUrl = "modules/git.xq"

These calls will fail silently against the 410 response. Options:

1. Disable frontend code paths — show "not available" instead of fetching
2. Remove debuger.js entirely — the debugger was never functional in modern eXist-db
3. Leave as-is — the 410 is sufficient, and the dead code can be cleaned up in a future pass

Full remaining legacy module inventory

Module	Status	Notes
session.xq	Active	Query execution pipeline — see discussion above
view.xq	Active	Injects server config (allowExecution, allowGuest, context) into index.html — must stay
debuger.xq	Disabled	Controller returns 410; src/debuger.js still calls it
git.xq	Disabled	Controller returns 410; src/eXide.js still calls it