From 1585c62b0de5befc0c8fdeac4ddbcf318c12bee8 Mon Sep 17 00:00:00 2001 From: Viliam Simko Date: Wed, 4 Nov 2026 16:35:32 +0100 Subject: [PATCH 1/3] docs: prioritize accepted API gap verification --- docs/roadmap.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/roadmap.md b/docs/roadmap.md index 85cbd52..eb663fc 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -29,7 +29,8 @@ The scope is balanced: cover major Solr API areas and production readiness witho | Work | Tracking | | --- | --- | -| Classify residual documented API gaps as focused follow-up work, deferred scope, or explicit non-goals | [#256](https://github.com/vsimko/node-solr-lambda/issues/256) | +| Verify Solr 10.1 Export `includeStoredFields` behavior and record exact version evidence | [#258](https://github.com/vsimko/node-solr-lambda/issues/258) | +| Verify isolated ReplicationHandler abort/async lifecycle semantics, or explicitly retain unverified status | [#259](https://github.com/vsimko/node-solr-lambda/issues/259) | ### P1 — SolrCloud operation evidence @@ -43,7 +44,7 @@ v4.0 stable publication remains a separate release-owner decision and must not b ## Dependencies and execution -- #255 is the documentation baseline for #256; keep operation status grounded in exact tests and pinned versions. +- #255 established the documentation baseline. The #256 gap triage is delivered by this roadmap/API-coverage update; accepted follow-ups are #258 and #259. Keep operation status grounded in exact tests and pinned versions. - #232 is independent of the documentation cleanup, but its results must be reflected in the Collections action matrix and API inventory before any compatibility claim changes. - #110 remains separate from feature implementation and depends on final documentation, release-candidate CI, external npm/GitHub trusted-publishing configuration, and release-owner approval. - Every implementation PR updates relevant API docs, compatibility evidence, and `api-inventory.json`; do not infer runtime support from type or serialization tests. From e2a403cb6e9a337081e086c1481423b830c4db7b Mon Sep 17 00:00:00 2001 From: Viliam Simko Date: Wed, 4 Nov 2026 16:35:35 +0100 Subject: [PATCH 2/3] docs: classify deferred API gaps and non-goals --- docs/api-coverage.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/api-coverage.md b/docs/api-coverage.md index 1cbc150..9d25080 100644 --- a/docs/api-coverage.md +++ b/docs/api-coverage.md @@ -32,6 +32,31 @@ A generic request method does not mean that every endpoint has a typed wrapper, | Export | `export()`, `exportStream()`; exported `SolrExportParams`, `SolrExportSort`, and `SolrExportFieldType` | Export requests require typed `fl` and `sort` parameters, support repeated filter queries, structured or raw sort expressions, batch sizing, JSON/JavaBin writers, and an explicit custom-parameter escape hatch. The raw Response preserves backpressure-aware streaming; `exportStream()` exposes its byte body directly. Sort fields must be single-valued docValues fields (int, long, float, double, or string); field lists additionally support date and boolean and may be multi-valued. Solr 10.1 `includeStoredFields` support is exposed but requires version-specific verification. Existing raw Export response tests pass on pinned Solr 8.11.4/9.11.0/10.1.0; typed parameter serialization and streamed chunk consumption have unit coverage. See [Export docs](export.md) and Issues #92–#94. | | Advanced / Raw | `requestRaw(path, options)` with typed method/query/header/body/control options and a raw Fetch `Response` | Relative paths and same-origin absolute URLs use the shared transport. Cross-origin URLs, embedded credentials, and URL fragments are rejected before Fetch, preventing configured credentials from being sent to unrelated hosts. Generic request()/requestRaw() transport behavior has unit coverage only; arbitrary custom endpoint behavior remains unverified until endpoint-specific integration tests exist. See [raw requests](raw-requests.md) and Issue #98. | +## Deferred work and explicit scope boundaries + +The following gaps were reviewed for the TypeScript-first, balanced product scope. They are not implicit implementation commitments. + +### Accepted, focused verification work + +- **Export `includeStoredFields`** — Solr 10.1 behavior needs an isolated runtime assertion; tracked by [#258](https://github.com/vsimko/node-solr-lambda/issues/258). Existing Export streaming tests do not certify this option. +- **ReplicationHandler abort/async lifecycle** — one-shot `fetchindex` and follower read-back are verified, but abort/polling semantics are not; tracked by [#259](https://github.com/vsimko/node-solr-lambda/issues/259). + +### Deferred pending a concrete consumer requirement + +- **Solr-version-specific error payload variants** — error envelopes preserve unknown fields and expose the typed common shape. Add version-specific models only when a concrete incompatible payload is identified and can be tested. +- **Advanced authentication (for example OAuth or mTLS)** — deployment-specific credential acquisition and certificate lifecycle are outside the built-in Basic/Bearer transport contract. The custom Fetch/headers extension points remain available. +- **Retry telemetry** — retry policy is opt-in; logging/metrics integration belongs to caller observability policy. The transport deliberately avoids logging credentials or server-controlled bodies. +- **Additional validation adapters and operation-specific schema examples** — the generic schema interface and optional Zod peer cover the supported extension contract. Add another adapter only for a demonstrated ecosystem demand. +- **Runtime verification of Core Admin `RENAME`, `SWAP`, `MERGEINDEXES`, `SPLIT`, `REQUESTSTATUS`, and `REQUESTRECOVERY`** — these operations have isolated/destructive or operational side effects and remain type/serialization-covered only until a safe, deterministic disposable environment is justified. +- **Collections `MODIFYCOLLECTION`, `ADDROLE`, and `REMOVEROLE` runtime verification** — these mutate cluster-wide policy/configuration and are not run against shared CI state. SPLITSHARD/MIGRATE have the separate opt-in gate in [#232](https://github.com/vsimko/node-solr-lambda/issues/232). + +### Intentional non-goals + +- **Plugin-specific Schema similarity mutation and plugin-specific Metrics/Auth schemas** — arbitrary plugin contracts are not part of the closed typed surface. Common stable fields remain typed and extension points preserve unknown/custom fields. +- **Solr 10 V2 routes where the client explicitly implements V1 contracts** — V2 is a distinct API surface, not a silent compatibility extension. Add it only as a separately scoped feature with its own types and tests. + +These decisions do not change the compatibility matrix: unverified operations remain unverified until exact runtime evidence exists. + ## Request controls Typed client methods support per-request cancellation and timeout controls. Caller cancellation throws `SolrAbortError`; a configured timeout throws `SolrTimeoutError`. The timeout remains active while JSON response bodies are read and while raw `requestRaw()` or export response streams are consumed. See [error handling](errors.md). From bd2dff2ea532680a5cc2dac4c60853fbc181e70b Mon Sep 17 00:00:00 2001 From: Viliam Simko Date: Wed, 4 Nov 2026 16:35:38 +0100 Subject: [PATCH 3/3] docs: clarify unverified operation boundaries --- docs/compatibility.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/compatibility.md b/docs/compatibility.md index 9bf47d8..fab35b7 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -11,6 +11,10 @@ This page records the current client compatibility policy. It separates document Documentation evidence does not prove that every patch release behaves in the same way. +## Interpreting unverified operations + +An exposed action or parameter is not runtime-certified merely because it has a TypeScript model or serialization test. The API coverage page records the current triage of deferred and intentionally out-of-scope gaps. In particular, destructive Core Admin actions and cluster-wide Collections policy mutations remain unverified until isolated runtime evidence is added; SPLITSHARD/MIGRATE require the opt-in workflow in [#232](https://github.com/vsimko/node-solr-lambda/issues/232). Export `includeStoredFields` and ReplicationHandler abort/async lifecycle have focused verification issues [#258](https://github.com/vsimko/node-solr-lambda/issues/258) and [#259](https://github.com/vsimko/node-solr-lambda/issues/259). + ## Reference baselines | Solr line | Documentation baseline | Documentation |