feat(db): consolidate resource content onto a binary-safe /api/db/resource

[joewiz]

[This PR was co-authored with Claude Code. -Joe]

Summary

Consolidates all resource-content transport onto a single, binary-safe /api/db/resource, and retires the JSON-envelope shape. The /api/db/resource endpoint, in the /api/db family, is identical in form to its siblings (collection/move/copy/properties/sync). This design supersedes the path-in-URL binary endpoints (#38, #56) and folds in the latest serialization work (#48), extending it to the full parameter vocabulary.

This is the outcome of a design review (with @line-o on #38 and #56, and in coordination with eXide, dashboard-next, and existdb-oxygen-plugin): the path-in-URL /api/resource/{path} broke the query-param convention of the /api/db family (it dangled under "default" in Swagger and doubled db in the URL), and the JSON envelope wasn't relied on by any client. A review of the clients confirmed they could drop it.

Rebased onto current develop — the decoded-UTF-8 names and db-core work it was originally stacked behind have since merged, so the diff here is the consolidation itself.

The consolidated contract

GET /api/db/resource?path=/db/… — returns the resource's raw content:

• binary → bytes streamed as-is; XML/text → serialized from the stored node tree.
• Content-Type = the stored mime type.
• Serialization parameters (XML/text): the full W3C set (method, indent, omit-xml-declaration, encoding, media-type, item-separator, standalone, …) plus eXist's extensions (expand-xincludes, highlight-matches, add-exist-id, process-xsl-pi, jsonp, insert-final-newline). Omitted params fall through to the conf.xml defaults — defaults are a fallback, never a ceiling.
• download=true → Content-Disposition: attachment.

PUT /api/db/resource?path=/db/…[&mime=…] — stores a raw request body (binary-safe):

• the stored mime comes from the optional &mime query param, else it is inferred from the resource name; pass mime=application/octet-stream to force raw-byte storage of content that would otherwise be parsed. The request's own Content-Type is transport only (HTTP clients send unpredictable defaults, so &mime keeps it deterministic).
• 201 Created (new) / 200 OK (overwrite), body { "path": "<canonical decoded path>" } so the caller can reconcile any server-side name normalization.

DELETE /api/db/resource?path=/db/… — unchanged.

Removed

• The JSON-envelope GET/PUT shape (content-as-a-string-field).
• meta=full and the X-Resource-* metadata headers.
• The separate /api/resource/{path} and /api/db/resource/{path} path-in-URL endpoints.
• runPath from every response (db-core get-resource and store); dbc:get-run-path deleted.

Note: runPath is derivable client-side and documented in the README:

function runPath(dbPath) {
  return dbPath.startsWith('/db/apps/')
    ? '/exist/apps/' + dbPath.slice('/db/apps/'.length)
    : '/exist/rest' + dbPath;
}

Metadata

• Metadata stays at GET /api/db/properties?path= — clients fetch it separately (a review of the clients confirmed this is preferred; content reads need only mime + binary-ness, derivable from Content-Type).

Encoding

The endpoint speaks decoded UTF-8 on the wire (eXist-db/exist#6463): a client sends and receives café.xml, never caf%C3%A9.xml. The ?path= form aligns better with this than path-in-URL did — a single query token roaster decodes cleanly, with no per-segment encoding ambiguity. db-core's to-stored/to-display/resolve-stored map to/from the canonical stored form (and stay read-compatible with legacy full-encoded names). Known Phase-1 limitation: literal % in a name is ambiguous (eXist-db/exist#6463), to be made bijective later.

Serialization params — no eXist-core dependency

The eXist-specific serialization params (notably expand-xincludes) are emitted as exist:-namespaced children of output:serialization-parameters (the http://exist.sourceforge.net/NS/exist namespace), which eXist already honors — so they work on any eXist, with no dependency on eXist-db/exist#6447. expand-xincludes=no on read (the data-loss-safe round-trip of <xi:include> documents) is reachable everywhere.

Testing

• Cypress (db.cy.js): raw GET round-trip (binary bytes intact, XQuery source not executed), serialization params (W3C + eXist extensions, including a real expand-xincludes case), raw PUT create/overwrite with canonical-path echo, DELETE, decoded-UTF-8 name round-trips, non-/db 400. Full suite green (200/200) against a clean existdb/existdb:latest container using CI's install → restart → cypress run sequence.
• Store path: dbc:store decodes the raw octet-stream body to text for XML-class targets before handing it to xmldb:store, so an XML mime never receives a binary value (which errored on some builds and blocked the request on others); non-XML content is stored byte-for-byte.

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics -107 complexity · -2 duplication

Metric	Results
Complexity	-107
Duplication	-2

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[line-o]

A much wanted change to the API for sure.
Let's work on the implementation details.

[joewiz]

[This response was prompted by Joe, drafted by Claude Code, and reviewed by Joe.]

Thanks @line-o — both addressed.

db:get-resource indentation (ca9e6b1). Split into three private helpers, each taking over one former nesting level: db:resolve-and-stream (resolve + 404), db:stream-content (mime, download header, binary-vs-serialize branch), and db:stream-serialized (serialize + the clean-400 on a bad param). The top function is now just the empty-path guard delegating into the chain, and each step reads top to bottom.

Colon instead of a dot on the wire (08d5b8e). Switched the eXist serializer extensions from an exist. prefix to exist: — ?exist:expand-xincludes=no — so the wire name matches the actual exist: serialization namespace. The original dot was a hedge against colons confusing OpenAPI/SDK codegen, but colons are valid in query-parameter and OpenAPI parameter names, and a generator has to sanitize either form to a legal identifier anyway, so the hedge bought nothing. Verified end to end against a clean existdb/existdb:latest: exist:expand-xincludes=no preserves <xi:include> verbatim, =yes expands it, and the full db.cy.js suite is green (76/76).

[line-o]

Much appreciated!