diff --git a/docs/api-coverage.md b/docs/api-coverage.md index 5bc6354..1cbc150 100644 --- a/docs/api-coverage.md +++ b/docs/api-coverage.md @@ -20,14 +20,14 @@ A generic request method does not mean that every endpoint has a typed wrapper, | Standard Query | `query()`, `queryJson()`; typed query, filter, fields, sort, parser, cursorMark, and response-writer options; compile-only documentation examples and negative typo/parser checks run in the Node.js type-test matrix; `SolrJsonQueryRequest` and recursive terms/query/range JSON Facet API models with nested metrics and domain changes; generic `SolrResponse` and `SolrQueryResponse` response models with typed document metadata, classic facets, caller-shaped JSON facets, highlighting, grouping, stats, and debug sections; typed classic field/query/numeric-and-date-range facet options with per-field overrides and range methods; typed highlighting options for fields, snippets, fragments, alternate fields, phrase/multi-term highlighting, encoders, tags, and per-field overrides; typed Result Grouping field/function/query options and grouped responses; typed Collapsing Query Parser and Expand component options/responses; typed Stats Component field/local options, facets, percentiles, cardinality, and nested response statistics; typed MoreLikeThis Search Component field selection, term/document thresholds, limits, and per-document similar-result responses; tagged filter models and query helpers; typed geofilt/bbox filters and geodist helpers; typed debug component selection, structured/plain explain response models, and explainOther query support | JSON Request API round-trip, nested JSON facets, highlighting, grouping, stats, MoreLikeThis, and cursorMark pagination have representative integration coverage on pinned Solr 8.11.4/9.11.0/10.1.0. Geospatial behavior is integration-tested on pinned Solr 8.11.4, 9.11.0, and 10.1.0: geofilt and bbox assert expected inclusion/exclusion using a disposable LatLonPointSpatialField, and geodist sorting asserts nearest-to-farthest document order. See Issues #44–#59 and umbrella Issue #121. | | Update / Documents | `add()`, `update()`, `atomicUpdate()`, `updateCommands()`, `delete()`, `commit()`, `softCommit()`, `optimize()`, `rollback()`; documentation examples compile in the Node.js type-test matrix | Single JSON documents use `/update/json/docs`, arrays use `/update`, and typed command objects use `/update/json` via `updateCommands()`. `SolrJsonUpdateCommands` models add/delete/commit/optimize/rollback. Typed JSON updateCommands add/commit, delete-by-ID/query, optimize, and rollback variants have integration tests with persisted-state assertions on pinned Solr 8.11.4/9.11.0/10.1.0. Named `SolrUpdateOptions`, `SolrDeleteOptions`, `SolrCommitOptions`, `SolrSoftCommitOptions`, and `SolrOptimizeOptions` expose overwrite, commitWithin, SolrCloud `_route_`, hard/soft commit, expungeDeletes, openSearcher, waitSearcher, and optimize maxSegments. `commitWithin` hard/soft behavior remains Solr-configuration-dependent; optimize's `openSearcher` runtime effect is not independently verified. `atomicUpdate()` adds field-specific modifier types for set/add/add-distinct/remove/removeregex/inc; unit, consumer type, and integration tests cover the supported shapes. Add, full-document update, atomic update, delete-by-ID, typed JSON updateCommands add+commit with persisted-document read-back, delete-by-query with persisted-state verification, hard/soft commit, optimize, and rollback have integration coverage on pinned Solr 8.11.4/9.11.0/10.1.0. The add/update `route` and `commitWithin` options have SolrCloud runtime coverage on pinned Solr 8.11.4/9.11.0/10.1.0: an implicit-router test proves shard selection using shard-scoped queries, and a bounded no-manual-commit poll verifies `commitWithin` search visibility with the pinned `_default` configset. The test does not assert hard versus soft commit because that is server-configuration-dependent; delete-option route/commitWithin remain runtime-unverified. Atomic updates have integration coverage on all three pinned versions. `SolrUpdateResponse` is the default success response type for Update Handler methods; output validation is keyed by operation, and `SolrHttpError.errorResponse` exposes typed error envelopes. Add/update response headers are asserted on Solr 8.11.4/9.11.0/10.1.0; version-specific error payload variants are not exhaustively certified. See Issues #42, #60–#67. | | Schema | `schema(command)` with typed add/replace/delete operations for fields, field types, and dynamic fields; add/delete copy-field rules; typed analyzer/tokenizer/filter and mutation response models; typed schema read responses | All field, field-type, dynamic-field, and copy-field operations plus full schema/name/version/uniqueKey/similarity reads are tested against Solr 8.11.4/9.11.0/10.1.0. Copy-field replacement is delete + add because Solr has no native replace-copy-field command. Similarity plugin mutation remains type/serialization-covered only. Client implements V1 Schema API, not Solr 10 V2 routes. Schema changes may require reindexing; SolrCloud replica propagation can be asynchronous. See Issues #68–#72 and #121. | -| Config | `config(command)`, `getConfig()`, and `getConfigOverlay()`; typed POST commands plus typed GET effective-config and overlay responses; cross-version `SolrConfigPropertyName` and property-specific `SolrConfigPropertyValues`; `SolrConfigRequestHandlerParams` for common request defaults/appends/invariants; distinct effective read models for request handlers, search components, response writers, init params, and listeners; query caches, update-handler commit settings, and request-dispatcher parser settings | Request-handler defaults type common query parameters (including rows, start, q/fq/fl, sort, wt, echoParams and time limits) while preserving open Solr parameters. Response-writer content negotiation and listener events have named fields; search-component and plugin-specific settings remain open and use `customOptions` where flattened command options are needed. An isolated temporary request handler is added, read back through GET `/config`, and removed in integration tests on pinned Solr 8.11.4/9.11.0/10.1.0; GET effective-config/overlay and command serialization have unit/type coverage. Version-specific common properties remain outside the shared property-name union. See Issues #73–#76, #121, and #228. | +| Config | `config(command)`, `getConfig()`, and `getConfigOverlay()`; typed POST commands plus typed GET effective-config and overlay responses; cross-version `SolrConfigPropertyName` and property-specific `SolrConfigPropertyValues`; `SolrConfigRequestHandlerParams` for common request defaults/appends/invariants; distinct effective read models for request handlers, search components, response writers, init params, and listeners; query caches, update-handler commit settings, and request-dispatcher parser settings | Request-handler defaults type common query parameters (including rows, start, q/fq/fl, sort, wt, echoParams and time limits) while preserving open Solr parameters. Response-writer content negotiation and listener events have named fields; search-component and plugin-specific settings remain open and use `customOptions` where flattened command options are needed. An isolated temporary request handler is added, read back through GET `/config`, and removed in integration tests on pinned Solr 8.11.4/9.11.0/10.1.0; Config API property set/unset is read back through GET `/config/overlay` with cleanup assertions on all three pinned versions. Version-specific common properties remain outside the shared property-name union. See Issues #73–#76, #121, and #228. | | Core Admin | `coreAdmin(action, params)` with `CoreAdminParams` action-specific models for STATUS, CREATE, RELOAD, UNLOAD, RENAME, SWAP, MERGEINDEXES, and SPLIT; `CoreAdminStatusResponse` for STATUS and `CoreAdminCommandResponse` as the default non-STATUS response envelope | STATUS models per-core paths/config metadata, optional index statistics, initialization failures, and unknown fields. Other actions default to a named extensible response-header envelope; callers may supply a more specific generic. Unit/type fixtures cover minimal and detailed STATUS payloads plus CREATE/RELOAD response inference. Isolated CREATE, STATUS, RELOAD, and fixture-cleanup UNLOAD are integration-tested on Solr 8.11.4/9.11.0/10.1.0; remaining actions retain serialization/type coverage only and are not claimed as runtime-certified. See [Core Admin evidence](administration.md#core-admin-status-response) and Issue #229. -| Collections | `collections(action, params)` with action-specific `CollectionAdminParams` and `CollectionAdminResponse` conditional response contracts | `LIST` uses `SolrCollectionListResponse`; collection lifecycle/policy, replica, and role actions use named extensible response envelopes; alias, cluster, shard, backup/restore, and async actions retain their named response models. Runtime evidence remains partial, not blanket certification of every action: exact Solr 8.11.4/9.11.0/10.1.0 evidence is listed in the [per-action Collections matrix](collections-api-coverage.md). `MODIFYCOLLECTION`, `SPLITSHARD`, `MIGRATE`, `ADDROLE`, and `REMOVEROLE` remain runtime-unverified. See [backup and restore docs](backup-restore.md), [Collections action matrix](collections-api-coverage.md), and Issues #80–#85, #121, and #230. | +| Collections | `collections(action, params)` with action-specific `CollectionAdminParams` and `CollectionAdminResponse` conditional response contracts | `LIST` uses `SolrCollectionListResponse`; collection lifecycle/policy, replica, and role actions use named extensible response envelopes; alias, cluster, shard, backup/restore, and async actions retain their named response models. Runtime evidence remains partial, not blanket certification of every action: `RELOAD` and the other tested actions are verified on pinned Solr 8.11.4/9.11.0/10.1.0 versions as listed in the [per-action Collections matrix](collections-api-coverage.md). `MODIFYCOLLECTION`, `SPLITSHARD`, `MIGRATE`, `ADDROLE`, and `REMOVEROLE` remain runtime-unverified. See [backup and restore docs](backup-restore.md), [Collections action matrix](collections-api-coverage.md), and Issues #80–#85, #121, and #230. | | Security | `security(area, command)` | Security-enabled standalone matrix covers anonymous 401 responses for both authentication and authorization, authenticated reads, authentication property mutation/read-back, and malformed JSON rejection on Solr 8.11.4/9.11.0/10.1.0. Unit tests verify Basic/Bearer credentials and Authorization headers are not exposed through client HTTP errors. See Issues #86–#88. | | System | `systemInfo()`, `systemProperties()`, `systemThreads()`, `systemLogging()` | System info, non-empty JVM/process properties, a non-empty thread dump, and logger metadata are exercised on pinned Solr 8.11.4/9.11.0/10.1.0. Optional fields remain version-dependent; response models preserve unknown fields. See Issues #89 and #91. | | Metrics | `metrics()` with typed group/registry/prefix/regex filters; exported `SolrMetricsJsonResponse`, `SolrMetricsRegistry`, and open `SolrMetricValue`; JSON/Prometheus response union | JVM response-format coverage remains distinct (observed JSON on Solr 8/9 and Prometheus exposition on 10.1). A `node` group integration check runs on all pinned versions, asserting a non-empty JSON registry on Solr 8/9 and Prometheus samples on 10.1; registry, prefix, and regex filters are asserted against JSON responses on Solr 8/9 (Solr 10.1 supports Prometheus/OpenMetrics, not the JSON writer). Consumer fixtures verify the extensible registry/value envelope; plugin-specific metrics remain open and unenumerated. See Issues #90, #91, and #236. | | Backup and restore | `replication("backup" | "restore" | "restorestatus" | "deletebackup")`, `collections("BACKUP" | "RESTORE" | "LISTBACKUP" | "DELETEBACKUP" | "REQUESTSTATUS" | "DELETESTATUS")` | Typed core and SolrCloud backup/restore parameters and response models, including async status polling. Full core restore and SolrCloud collection backup/restore cycles are integration-tested on Solr 8.11.4/9.11.0/10.1.0 using local filesystem repositories and shared SolrCloud storage. See [backup and restore docs](backup-restore.md). | -| Replication | `replication(command, params)`, `replicationFile(params)`; exported command-specific parameter and response models | V1 ReplicationHandler commands for index version, details, file list, leader/follower control (fetchindex/abortfetch across Solr 8/9/10), core backup/restore/status/delete, and raw file-content streaming. Integration coverage includes core backup/restore cycles on Solr 8.11.4/9.11.0/10.1.0. A disposable two-core leader/follower fetch/read-back check is implemented but remains pending runtime verification until its pinned-version CI jobs pass; it uses `fetchindex`/`abortfetch` across Solr 8/9/10. Abort and polling lifecycle behavior remains unit-only. See Issue #95 and [replication docs](replication.md). | +| Replication | `replication(command, params)`, `replicationFile(params)`; exported command-specific parameter and response models | V1 ReplicationHandler commands for index version, details, file list, leader/follower control (fetchindex/abortfetch across Solr 8/9/10), core backup/restore/status/delete, and raw file-content streaming. Integration coverage includes core backup/restore cycles on Solr 8.11.4/9.11.0/10.1.0. A disposable two-core leader/follower fetch using `fetchindex` and follower query read-back passed the full standalone/security matrix on Solr 8.11.4 / 9.11.0 / 10.1.0 (CI #640). Abort and polling lifecycle behavior remains unit-only. See Issue #95 and [replication docs](replication.md). | | Streaming Expressions | `stream()` | Sends `expr` with `wt=json` and parses the complete JSON response through the shared transport. It is not an incremental tuple-stream parser: no chunk-boundary protocol or memory-bound/backpressure guarantee is claimed. SolrCloud search is integration-tested on pinned Solr 8.11.4/9.11.0/10.1.0; unit tests cover JSON parsing, caller cancellation during body consumption, and cleanup after body-stream errors. See [Streaming Expressions](streaming.md) and Issue #93. | | 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. | diff --git a/docs/api-inventory.json b/docs/api-inventory.json index a255a0b..def9bb1 100644 --- a/docs/api-inventory.json +++ b/docs/api-inventory.json @@ -224,17 +224,18 @@ "methodImplemented": true, "typeCoverage": "partial", "unitTests": "present", - "integrationTests": "not-run", + "integrationTests": "tested", "versions": { - "8": "unverified", - "9": "unverified", - "10": "unverified" + "8": "tested", + "9": "tested", + "10": "tested" }, "documentation": "docs/config.md", "testFiles": [ - "test/config.test.ts" + "test/integration/solr-config-components.test.ts", + "test/integration/solr-config-operations.test.ts" ], - "notes": "Reads the effective configuration through GET /config. The method has dedicated request serialization and integration evidence." + "notes": "GET /config reads back an isolated request handler after add and update, and confirms its removal after delete on pinned Solr 8.11.4, 9.11.0, and 10.1.0. The effective configuration response is asserted, not merely the HTTP status." }, { "id": "config.getOverlay", @@ -245,17 +246,17 @@ "methodImplemented": true, "typeCoverage": "partial", "unitTests": "present", - "integrationTests": "not-run", + "integrationTests": "tested", "versions": { - "8": "unverified", - "9": "unverified", - "10": "unverified" + "8": "tested", + "9": "tested", + "10": "tested" }, "documentation": "docs/config.md", "testFiles": [ - "test/config.test.ts" + "test/integration/solr-config-operations.test.ts" ], - "notes": "Reads the persisted Config API overlay through GET /config/overlay. Kept separate from getConfig because the endpoint and semantics differ." + "notes": "GET /config/overlay reads back Config API property mutations and verifies unset cleanup on pinned Solr 8.11.4, 9.11.0, and 10.1.0. This is persisted overlay state, distinct from effective GET /config." }, { "id": "metrics.api", @@ -402,7 +403,7 @@ "test/backup-restore-api-types.ts", "test/integration/solr-core-backup-restore.test.ts" ], - "notes": "Typed V1 ReplicationHandler commands for enablereplication, disablereplication, indexversion, fetchindex, abortfetch, snappull, abort, enablepoll, disablepoll, details, filelist, backup, restore, restorestatus, and deletebackup; replicationFile() returns raw filecontent streams. Live integration coverage on Solr 8.11.4, 9.11.0, and 10.1.0 covers indexversion, details, filelist, filecontent, leader enable/disable, and a disposable two-core leader/follower fetch with follower query read-back is implemented but remains pending runtime verification until the pinned-version CI jobs pass. The integration job supplies SOLR_VERSION so the test uses fetchindex on Solr 10 and snappull on Solr 8/9. abortfetch/abort, enablepoll, and disablepoll retain unit serialization coverage only; an in-progress abort lifecycle is not certified. Core-level backup, restore, restorestatus, and deletebackup are integration-tested on all three pinned versions. Filelist uses the generation returned by newer Solr indexversion responses and falls back to the legacy indexversion parameter when that field is absent. Additional operation evidence: Core-level ReplicationHandler backup, restore, restorestatus, and deletebackup are typed. Backup defaults to the core dataDir; restore status is polled with restorestatus. Full backup/restore/read-back/delete cycle is integration-tested on Solr 8.11.4, 9.11.0, and 10.1.0. Custom filesystem locations must be permitted by server allowPaths." + "notes": "Typed V1 ReplicationHandler commands for enablereplication, disablereplication, indexversion, fetchindex, abortfetch, snappull, abort, enablepoll, disablepoll, details, filelist, backup, restore, restorestatus, and deletebackup; replicationFile() returns raw filecontent streams. Live integration coverage on Solr 8.11.4, 9.11.0, and 10.1.0 covers indexversion, details, filelist, filecontent, leader enable/disable, and a disposable two-core leader/follower fetch using fetchindex with follower query read-back passed the full standalone/security matrix on Solr 8.11.4, 9.11.0, and 10.1.0 (CI #640). abortfetch/abort, enablepoll, and disablepoll retain unit serialization coverage only; an in-progress abort lifecycle is not certified. Core-level backup, restore, restorestatus, and deletebackup are integration-tested on all three pinned versions. Filelist uses the generation returned by newer Solr indexversion responses and falls back to the legacy indexversion parameter when that field is absent. Additional operation evidence: Core-level ReplicationHandler backup, restore, restorestatus, and deletebackup are typed. Backup defaults to the core dataDir; restore status is polled with restorestatus. Full backup/restore/read-back/delete cycle is integration-tested on Solr 8.11.4, 9.11.0, and 10.1.0. Custom filesystem locations must be permitted by server allowPaths." }, { "id": "replication.file", @@ -413,18 +414,18 @@ "methodImplemented": true, "typeCoverage": "partial", "unitTests": "present", - "integrationTests": "not-run", + "integrationTests": "tested", "documentation": "docs/replication.md", "versions": { - "8": "unverified", - "9": "unverified", - "10": "unverified" + "8": "tested", + "9": "tested", + "10": "tested" }, "testFiles": [ "test/replication.test.ts", "test/integration/solr-replication.test.ts" ], - "notes": "Returns raw replication file content as a Response stream; distinct from command-based replication operations." + "notes": "Returns raw replication file content as a Response stream; integration coverage requests a listed leader index file and verifies a successful non-empty binary response on pinned Solr 8.11.4, 9.11.0, and 10.1.0." }, { "id": "transport.request", diff --git a/docs/collections-api-coverage.md b/docs/collections-api-coverage.md index fa27607..5700795 100644 --- a/docs/collections-api-coverage.md +++ b/docs/collections-api-coverage.md @@ -23,7 +23,8 @@ This matrix is deliberately action-specific. The public client infers a named re | `ADDREPLICAPROP` | `AddReplicaPropertyParams` | `SolrCollectionReplicaResponse` | Serialization and compile fixtures | Adds replica property; all three pinned versions | | `DELETEREPLICAPROP` | `DeleteReplicaPropertyParams` | `SolrCollectionReplicaResponse` | Serialization and compile fixtures | Removes replica property; all three pinned versions | | `CREATESHARD` | `CreateShardParams` | `SolrCollectionShardOperationResponse` | Exact serialization and consumer type fixture | Creates a shard on a disposable implicit collection and reads it through CLUSTERSTATUS; all three pinned versions | -| `DELETESHARD` | `DeleteShardParams` | `SolrCollectionShardOperationResponse` | Exact serialization and consumer type fixture | Deletes only the shard created by the test and verifies absence; all three pinned versions |\n| `MIGRATE` | `MigrateCollectionParams` (`collection`, V1 `split.key`, V1 `target.collection`, optional `forward.timeout`, `async`) | `SolrCollectionShardOperationResponse` | Exact serialization and consumer type fixture | Opt-in only: disposable compositeId source/empty target; async completion plus target document read-back. Not yet executed against pinned versions; remains runtime-unverified | +| `DELETESHARD` | `DeleteShardParams` | `SolrCollectionShardOperationResponse` | Exact serialization and consumer type fixture | Deletes only the shard created by the test and verifies absence; all three pinned versions | +| `MIGRATE` | `MigrateCollectionParams` (`collection`, V1 `split.key`, V1 `target.collection`, optional `forward.timeout`, `async`) | `SolrCollectionShardOperationResponse` | Exact serialization and consumer type fixture | Opt-in only: disposable compositeId source/empty target; async completion plus target document read-back. Not yet executed against pinned versions; remains runtime-unverified | | `SPLITSHARD` | `SplitShardParams` (`shard` or V1 `split.key`; `ranges`, `numSubShards`, `splitMethod`, `async`) | `SolrCollectionShardOperationResponse` | Exact serialization and consumer type fixture | Opt-in only: disposable one-shard compositeId collection; async completion, active child-shard state, and document read-back. Not yet executed against pinned versions; remains runtime-unverified | | `ADDROLE` | `CollectionRoleParams` | `SolrCollectionRoleResponse` | Exact serialization and consumer type fixture | Not integration-tested: changes cluster-wide node role assignment; requires a dedicated isolated cluster policy fixture | | `REMOVEROLE` | `CollectionRoleParams` | `SolrCollectionRoleResponse` | Exact serialization and consumer type fixture | Not integration-tested: changes cluster-wide node role assignment; requires a dedicated isolated cluster policy fixture | diff --git a/docs/compatibility.md b/docs/compatibility.md index b604ca9..9bf47d8 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -5,7 +5,8 @@ This page records the current client compatibility policy. It separates document ## Status terms - **Documented** means the endpoint or feature appears in the official reference guide for the listed Solr documentation baseline. -- **Tested** means the exact behavior named in the runtime-test column passed against the pinned Docker image for that Solr line; it does not certify other parameters or actions.\n- **Unverified** means this repository has not run an integration test for that operation against that Solr server version. +- **Tested** means the exact behavior named in the runtime-test column passed against the pinned Docker image for that Solr line; it does not certify other parameters or actions. +- **Unverified** means this repository has not run an integration test for that operation against that Solr server version. - **Not covered** means the current typed client does not provide a dedicated method for that endpoint. Documentation evidence does not prove that every patch release behaves in the same way. @@ -30,15 +31,18 @@ The 8.11, 9.11, and 10.1 guides describe the API families below. The Replica Man | `commit()`, `softCommit()`, `optimize()`, `rollback()` — update commands | Documented | Documented | Documented | Tested: hard commit, soft commit, rollback, and optimize preserving committed documents on pinned 8.11.4 / 9.11.0 / 10.1.0 images. `expungeDeletes` and `openSearcher=false` commit behavior are tested; optimize-specific `openSearcher` runtime effect remains unverified | | `ping()` — `/admin/ping` | Documented | Documented | Documented | Tested: ping returns OK on pinned 8.11.4 / 9.11.0 / 10.1.0 images | | `schema()` — `/schema` | Documented | Documented | Documented | Tested: add-field and GET /{core}/schema/fields read-back on pinned 8.11.4 / 9.11.0 / 10.1.0 images | -| `config()` — `/config` | Documented | Documented | Documented | Tested: set-user-property and GET /config/overlay userProps read-back on pinned 8.11.4 / 9.11.0 / 10.1.0 images (CI #166) | +| `config()` / `getConfig()` / `getConfigOverlay()` — `/config`, `/config/overlay` | Documented | Documented | Documented | Tested: isolated request-handler add/read/update/delete and GET /config read-back; Config API property set/unset and GET /config/overlay read-back on pinned 8.11.4 / 9.11.0 / 10.1.0 images | | `coreAdmin()` — `/solr/admin/cores` | Documented | Documented | Documented | Tested: CREATE, STATUS, RELOAD, and fixture UNLOAD cleanup on pinned 8.11.4 / 9.11.0 / 10.1.0 images | -| `collections()` — `/solr/admin/collections` | Documented | Documented | Documented | Partial, per action: CREATE/LIST/DELETE; CREATEALIAS/LISTALIASES/DELETEALIAS; CLUSTERSTATUS; CREATESHARD/DELETESHARD; ADDREPLICA/DELETEREPLICA; ADDREPLICAPROP/DELETEREPLICAPROP; BALANCESHARDUNIQUE; MOVEREPLICA/REBALANCELEADERS; BACKUP/LISTBACKUP/RESTORE/DELETEBACKUP; REQUESTSTATUS/DELETESTATUS are tested on pinned 8.11.4 / 9.11.0 / 10.1.0. RELOAD, MODIFYCOLLECTION, SPLITSHARD, MIGRATE, ADDROLE, and REMOVEROLE remain unverified. See [per-action Collections coverage](collections-api-coverage.md). | -| `systemInfo()` — `/solr/admin/info/system` | Documented | Documented | Documented | Tested: non-empty server metadata and at least one stable system section on pinned 8.11.4 / 9.11.0 / 10.1.0 images. Optional sections remain version/runtime-dependent |\n| `systemProperties()` — `/solr/admin/info/properties` | Documented | Documented | Documented | Tested: non-empty JVM/process properties on pinned 8.11.4 / 9.11.0 / 10.1.0 images |\n| `systemThreads()` — `/solr/admin/info/threads` | Documented | Documented | Documented | Tested: non-empty JVM thread dump on pinned 8.11.4 / 9.11.0 / 10.1.0 images |\n| `systemLogging()` — `/solr/admin/info/logging` | Documented | Documented | Documented | Tested: logger levels, loggers, or watcher metadata on pinned 8.11.4 / 9.11.0 / 10.1.0 images | +| `collections()` — `/solr/admin/collections` | Documented | Documented | Documented | Partial, per action: CREATE/LIST/DELETE; CREATEALIAS/LISTALIASES/DELETEALIAS; CLUSTERSTATUS; CREATESHARD/DELETESHARD; ADDREPLICA/DELETEREPLICA; ADDREPLICAPROP/DELETEREPLICAPROP; BALANCESHARDUNIQUE; MOVEREPLICA/REBALANCELEADERS; BACKUP/LISTBACKUP/RESTORE/DELETEBACKUP; REQUESTSTATUS/DELETESTATUS are tested on pinned 8.11.4 / 9.11.0 / 10.1.0. MODIFYCOLLECTION, SPLITSHARD, MIGRATE, ADDROLE, and REMOVEROLE remain unverified. RELOAD is tested on all three pinned versions. See [per-action Collections coverage](collections-api-coverage.md). | +| `systemInfo()` — `/solr/admin/info/system` | Documented | Documented | Documented | Tested: non-empty server metadata and at least one stable system section on pinned 8.11.4 / 9.11.0 / 10.1.0 images. Optional sections remain version/runtime-dependent | +| `systemProperties()` — `/solr/admin/info/properties` | Documented | Documented | Documented | Tested: non-empty JVM/process properties on pinned 8.11.4 / 9.11.0 / 10.1.0 images | +| `systemThreads()` — `/solr/admin/info/threads` | Documented | Documented | Documented | Tested: non-empty JVM thread dump on pinned 8.11.4 / 9.11.0 / 10.1.0 images | +| `systemLogging()` — `/solr/admin/info/logging` | Documented | Documented | Documented | Tested: logger levels, loggers, or watcher metadata on pinned 8.11.4 / 9.11.0 / 10.1.0 images | | `metrics()` — `/solr/admin/metrics` | Documented | Documented | Documented | Tested: non-empty JVM registry/metric entries for JSON or a Prometheus metric declaration/sample on pinned 8.11.4 / 9.11.0 / 10.1.0; observed JSON on Solr 8/9 and Prometheus text on Solr 10.1 | | `security()` — authentication and authorization handlers | Documented | Documented | Documented | Tested: authenticated BasicAuth/RuleBasedAuthorization reads, anonymous 401 on both handlers, authentication `set-property` read-back, and malformed JSON rejection on pinned 8.11.4 / 9.11.0 / 10.1.0 images. Unit tests verify Basic/Bearer credentials are not exposed by client HTTP errors | | `stream()` — `/stream` | Documented | Documented | Documented | Tested: Streaming Expressions search against a disposable SolrCloud collection on pinned 8.11.4 / 9.11.0 / 10.1.0 images (CI #145) | | `export()` — `/export` | Documented | Documented | Documented | Tested: raw response with docValues sort field on pinned 8.11.4 / 9.11.0 / 10.1.0 images | -| `replication()` / `replicationFile()` — `/solr/{core}/replication` | Documented | Documented | Documented | Tested: indexversion, details, filelist (generation on newer versions / legacy indexversion on older versions), streamed filecontent, enablereplication/disablereplication, core backup, restorestatus, restore, and deletebackup on pinned 8.11.4 / 9.11.0 / 10.1.0 images. A disposable two-core leader/follower fetch with follower query read-back is covered by the regular standalone/security integration matrix; runtime verification remains pending until those CI jobs pass on each pinned version. It uses snappull on Solr 8/9 and fetchindex on Solr 10. Abort and polling lifecycle behavior remains unit-only | +| `replication()` / `replicationFile()` — `/solr/{core}/replication` | Documented | Documented | Documented | Tested: indexversion, details, filelist (generation on newer versions / legacy indexversion on older versions), streamed filecontent, enablereplication/disablereplication, core backup, restorestatus, restore, and deletebackup on pinned 8.11.4 / 9.11.0 / 10.1.0 images. A disposable two-core leader/follower fetch using `fetchindex` with follower query read-back passed the full standalone/security matrix on Solr 8.11.4 / 9.11.0 / 10.1.0 (CI #640). `abortfetch`, `enablepoll`, and `disablepoll` retain unit serialization coverage only; cancellation of an in-progress transfer and polling lifecycle behavior remain unverified | | Core and collection backup/restore | `replication("backup" | "restore" | "restorestatus" | "deletebackup")`, `collections("BACKUP" | "RESTORE" | "LISTBACKUP" | "DELETEBACKUP" | "REQUESTSTATUS" | "DELETESTATUS")` | Documented | Documented | Documented | Tested: full core backup/restore/read-back and SolrCloud collection backup/list/restore/read-back/delete with asynchronous status polling on pinned 8.11.4 / 9.11.0 / 10.1.0 images using local filesystem repositories and shared SolrCloud storage | | `request()` / `requestRaw()` — generic caller-defined transport | Depends on the selected endpoint | Depends on the selected endpoint | Depends on the selected endpoint | Generic transport behavior has unit tests only; no endpoint-independent live Solr integration claim is made. Each custom endpoint remains unverified until tested individually | diff --git a/docs/endpoint-inventory.md b/docs/endpoint-inventory.md index 7c40c31..788a80f 100644 --- a/docs/endpoint-inventory.md +++ b/docs/endpoint-inventory.md @@ -19,7 +19,7 @@ This inventory defines the boundary of the typed client API after review against | Metrics API `/solr/admin/metrics` | `metrics()` | Typed response models; JSON metrics on Solr 8/9 and Prometheus exposition text on Solr 10.1 are documented. | | Streaming Expressions `/stream` | `stream()` | Expression request support and JSON response parsing; tested against SolrCloud on all three pinned versions. | | Export handler `/export` | `export()`, `exportStream()` | Typed export parameters and raw backpressure-aware response/byte-stream access; docValues sort-field flow tested on all three pinned versions. | -| ReplicationHandler V1 `/solr/{core}/replication` | `replication()`, `replicationFile()` | Typed commands include indexversion, details, filelist, fetch/poll/enable/disable/abort, backup, restore, restorestatus, and deletebackup (using fetchindex/abortfetch across the pinned Solr 8/9/10 versions), plus raw file-content streaming. Core backup/restore cycles are integration-tested on all three pinned versions. A complete leader/follower fetch cycle is not yet certified. | +| ReplicationHandler V1 `/solr/{core}/replication` | `replication()`, `replicationFile()` | Typed commands include indexversion, details, filelist, fetch/poll/enable/disable/abort, backup, restore, restorestatus, and deletebackup (using fetchindex/abortfetch across the pinned Solr 8/9/10 versions), plus raw file-content streaming. Core backup/restore cycles are integration-tested on all three pinned versions. A disposable two-core leader/follower fetch with follower query read-back passed the pinned Solr 8.11.4, 9.11.0, and 10.1.0 matrix (CI #640); live-transfer abort and polling lifecycle remain unverified. | | Generic/custom request handlers | `request()`, `requestRaw()` | Escape hatches for custom paths and parameters. These do not imply typed support or integration certification for arbitrary endpoints. | ## Explicitly deferred or excluded endpoint families diff --git a/docs/replication.md b/docs/replication.md index 68632b4..e97fd3f 100644 --- a/docs/replication.md +++ b/docs/replication.md @@ -59,7 +59,7 @@ await client.replication("enablepoll"); await client.replication("abortfetch"); ``` -`fetchindex`/`abortfetch` are the canonical fetch and cancellation commands across the pinned Solr 8.11.4, 9.11.0, and 10.1.0 versions. `leaderUrl` is the leader core URL without the `/replication` suffix; Solr appends the handler path when fetching files. For Basic authentication between the follower and its leader, configure the ReplicationHandler's server-side follower settings; do not put credentials into URLs or query parameters. +`fetchindex`/`abortfetch` are the canonical fetch and cancellation commands across the pinned Solr 8.11.4, 9.11.0, and 10.1.0 versions. `leaderUrl` is the leader core URL without the `/replication` suffix; Solr appends the handler path when fetching files. For Basic authentication between the follower and its leader, configure the ReplicationHandler's server-side follower settings and pass `httpBasicAuthUser` / `httpBasicAuthPassword` as `customParams` on the `fetchindex` request when the server requires them. Do not put credentials into URLs or log them. ## Control a leader @@ -103,7 +103,7 @@ Supported directory types are `file` (Lucene index files), `cf` (configuration f - The client currently exposes the V1 handler path. Solr 10.1 also documents V2 equivalents for selected file and index-version operations; no dedicated V2 wrapper is provided. - The handler may not be configured for user-managed leader/follower replication on every core. The server must have the appropriate ReplicationHandler configuration before control commands can be used. -- A regular standalone/security integration test creates disposable leader and follower cores, commits a unique leader document, triggers `fetchindex` on Solr 8/9/10 with the fully qualified leader handler URL, and verifies that the document becomes searchable on the follower. Treat this behavior as pending runtime verification until the pinned Solr 8.11.4, 9.11.0, and 10.1.0 CI jobs pass. The test does not cover polling or abort of an in-progress transfer. +- A regular standalone/security integration test creates disposable leader and follower cores, commits a unique leader document, triggers `fetchindex` on Solr 8/9/10 with the fully qualified leader handler URL, and verifies that the document becomes searchable on the follower. This behavior passed the pinned Solr 8.11.4, 9.11.0, and 10.1.0 standalone/security CI matrix (run #640). The test does not cover polling or abort of an in-progress transfer. - `abortfetch` on Solr 8/9/10, plus `enablepoll`/`disablepoll`, have request-serialization unit coverage; cancellation of a live transfer remains unverified. The disposable-core fixture unloads both cores in its `finally` cleanup. If a CI job is cancelled or the fetch does not settle, the ephemeral Solr container is discarded rather than reusing the cores. See the [Solr 8.11](https://solr.apache.org/__root/docs.solr.apache.org/guide/8_11/deployment-guide/user-managed-index-replication.html), [Solr 9.11](https://solr.apache.org/guide/solr/9_11/deployment-guide/user-managed-index-replication.html), and [Solr 10.1](https://solr.apache.org/guide/solr/10_1/deployment-guide/user-managed-index-replication.html) guides for server configuration and command semantics. diff --git a/docs/roadmap.md b/docs/roadmap.md index ce71cfe..85cbd52 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,96 +1,79 @@ # Development roadmap -This roadmap tracks the single active development line on master. Work is delivered through short-lived branches and pull requests targeting master; there is no permanent version-specific development branch. +This roadmap tracks the single active development line on `master`. Work is delivered through short-lived branches and pull requests targeting `master`; there is no permanent version-specific development branch. ## Product direction **node-solr-lambda is a modern, lightweight, TypeScript-first Apache Solr client whose public API makes Solr parameters discoverable through IDE autocomplete.** -TypeScript IntelliSense is a product requirement: - Supported Solr options use named exported interfaces, literal/discriminated unions, and nested models where useful. -- IDE completion exposes valid parameters and value shapes; type checking catches misspellings. - Query and response generics let consumers type their own Solr documents. - Less common and newly introduced Solr features remain accessible through explicit custom-parameter/raw-request escape hatches. - Version-specific behavior is documented rather than hidden behind broad types. -The scope is balanced: cover major Solr API areas and production readiness without attempting to wrap every historical or plugin-specific endpoint. Keep the native Fetch transport, small dependency footprint, and direct mapping to Solr APIs. Feature work is not blocked on the v4.0 stable release. +The scope is balanced: cover major Solr API areas and production readiness without attempting to wrap every historical or plugin-specific endpoint. Feature work is not blocked on the v4.0 stable release. ## Current baseline -- Package manager: npm; use npm ci and commit package-lock.json. +- Package manager: npm; use `npm ci` and commit `package-lock.json`. - Runtime targets: Node.js 20, 22, and 24. - Transport: Node.js Fetch API; optional runtime validation: Zod. - Target Solr lines: 8.x, 9.x, and 10.x. -- Pinned integration images: Solr 8.11.4, 9.11.0, and 10.1.0. Compatibility is operation-specific; a green matrix does not certify every action. See compatibility.md and api-inventory.json. +- Pinned integration images: Solr 8.11.4, 9.11.0, and 10.1.0. Compatibility is operation-specific; a green matrix does not certify every action. See [compatibility](compatibility.md) and [api-inventory.json](api-inventory.json). - Package metadata identifies the current package line as 4.0.0-beta.0; this does not imply a separate development branch. -- master is the only active development line. Historical branches are audit evidence only and are not valid bases for new work. +- `master` is the only active development line. ## Active priorities -### P0 — Roadmap and public-contract hygiene +### P0 — Documentation and API-contract consistency | Work | Tracking | | --- | --- | -| Reconcile active priorities with current issue status and operation-level API evidence | [#239](https://github.com/vsimko/node-solr-lambda/issues/239) | -| Keep the machine-readable inventory, endpoint inventory, API coverage, and public method declarations aligned as follow-up work lands | Track in each API issue; use the API inventory as the operation-level source of truth | +| 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) | -### P1 — Core typed API quality and evidence +### P1 — SolrCloud operation evidence | Work | Tracking | | --- | --- | -| Complete Config component-specific option models and safe behavior evidence | [#228](https://github.com/vsimko/node-solr-lambda/issues/228) | -| Add action-specific CoreAdmin response models and per-operation evidence | [#229](https://github.com/vsimko/node-solr-lambda/issues/229) | -| Add named response contracts for Collections actions beyond backup/restore | [#230](https://github.com/vsimko/node-solr-lambda/issues/230) | -| Close Collections RELOAD, MODIFYCOLLECTION, ADDROLE, and REMOVEROLE request/type/test gaps | [#231](https://github.com/vsimko/node-solr-lambda/issues/231) | - -### P2 — Solr behavior verification and advanced API contracts - -| Work | Tracking | -| --- | --- | -| Verify geospatial query helpers against the pinned Solr matrix | [#233](https://github.com/vsimko/node-solr-lambda/issues/233) | -| Verify SolrCloud _route_ and commitWithin runtime semantics | [#234](https://github.com/vsimko/node-solr-lambda/issues/234) | -| Expand live coverage for JSON update command variants beyond add + commit | [#235](https://github.com/vsimko/node-solr-lambda/issues/235) | -| Broaden Metrics fixtures and filter evidence beyond the JVM registry | [#236](https://github.com/vsimko/node-solr-lambda/issues/236) | -| Define typed Streaming Expressions tuple/error response contracts without claiming incremental streaming | [#237](https://github.com/vsimko/node-solr-lambda/issues/237) | -| Verify the ReplicationHandler leader/follower fetch lifecycle | [#238](https://github.com/vsimko/node-solr-lambda/issues/238) | -| Add opt-in isolated verification for SPLITSHARD and MIGRATE; retain explicit non-certification if safe automation is impractical | [#232](https://github.com/vsimko/node-solr-lambda/issues/232) | +| Execute the opt-in, loopback-only SPLITSHARD and MIGRATE verification workflow for each pinned Solr version; retain non-certification until evidence exists | [#232](https://github.com/vsimko/node-solr-lambda/issues/232) | ### Separate release gate -v4.0 stable publication remains a separate release-owner decision and must not block feature development. Complete the exact release-candidate CI matrix, release notes/migration summary, npm trusted-publisher configuration and provenance verification, and clean npm consumer smoke test before publication. Tracking: [#110](https://github.com/vsimko/node-solr-lambda/issues/110). The repository's release process describes the OIDC workflow, but the actual npm trusted-publisher/account settings must still be verified externally. +v4.0 stable publication remains a separate release-owner decision and must not block feature development. Complete the exact release-candidate CI matrix, release notes/migration summary, npm trusted-publisher configuration and provenance verification, and clean npm consumer smoke test before publication. Tracking: [#110](https://github.com/vsimko/node-solr-lambda/issues/110). Do not create a stable tag or publish without explicit release-owner approval. -## Parallel execution and dependencies +## Dependencies and execution -- Config (#228) and CoreAdmin (#229) can proceed independently. -- Collections response contracts (#230) and the remaining action evidence (#231) can proceed in parallel, coordinating shared action/type definitions. -- Query/update verification (#233–#235), Metrics (#236), Streaming Expressions (#237), and Replication (#238) are independent workstreams after shared test conventions are agreed. -- SPLITSHARD/MIGRATE verification (#232) is opt-in and must never run against shared or user-owned Solr clusters. -- Every PR updates relevant API docs, compatibility evidence, and api-inventory.json; do not infer runtime support from type or serialization tests. +- #255 is the documentation baseline for #256; 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. ## Completed foundation and historical work Closed issues are retained as historical evidence, not active priorities: - Mainline/branch strategy and historical branch audit: [#122](https://github.com/vsimko/node-solr-lambda/issues/122). -- Query API and consumer-facing TypeScript foundation: [#44–#59](https://github.com/vsimko/node-solr-lambda/issues/44). Remaining geospatial runtime verification is tracked separately in #233. -- Update API and response handling: [#60–#67](https://github.com/vsimko/node-solr-lambda/issues/60). Remaining _route_, commitWithin, and JSON command runtime evidence is tracked in #234 and #235. +- Query API and consumer-facing TypeScript foundation: [#44–#59](https://github.com/vsimko/node-solr-lambda/issues/44). +- Update API and response handling: [#60–#67](https://github.com/vsimko/node-solr-lambda/issues/60); remaining runtime semantics are tracked only when still open. - Schema API: [#68–#72](https://github.com/vsimko/node-solr-lambda/issues/68). -- Config command/read/overlay implementation: [#73–#76](https://github.com/vsimko/node-solr-lambda/issues/73); component-specific options follow-up is #228. -- CoreAdmin and Collections initial implementation: [#77–#85](https://github.com/vsimko/node-solr-lambda/issues/77); focused response/evidence follow-ups are #229–#232. -- Security, System, Metrics, Streaming Expressions, and Export foundations: [#86–#94](https://github.com/vsimko/node-solr-lambda/issues/86). Current remaining Metrics and Streaming Expressions gaps are #236 and #237. -- Replication, backup/restore, raw-request, URL serialization, retry, and authentication foundations are implemented; the leader/follower fetch lifecycle follow-up is #238. -- Packaging, public API review, operation inventory, and endpoint/roadmap audit issues #104, #108, #184, and #185 are closed. Their completion does not imply blanket endpoint certification. +- Config command/read/overlay implementation: [#73–#76](https://github.com/vsimko/node-solr-lambda/issues/73); component-specific options work is historical unless reopened. +- CoreAdmin and Collections implementation: [#77–#85](https://github.com/vsimko/node-solr-lambda/issues/77). +- Security, System, Metrics, Streaming Expressions, and Export foundations: [#86–#94](https://github.com/vsimko/node-solr-lambda/issues/86). +- Packaging, public API review, and operation inventory foundations: #104, #108, #184, and #185. +- Feature and evidence follow-ups #228–#231 and #233–#238 are completed and merged. #238 (ReplicationHandler one-shot leader/follower fetch and read-back) was completed by merged PR #253. +- The post-#253 documentation reconciliation is delivered by PR #257 (#255); it is not a continuing roadmap priority once merged. +- PR #253 also added the isolated opt-in SolrCloud test harness for SPLITSHARD/MIGRATE. Those actions remain unverified until the manual workflow has actually passed. ## Workflow 1. Select an open issue describing one coherent change. -2. Create a short-lived branch from current master. +2. Create a short-lived branch from current `master`. 3. Implement with unit tests, consumer type tests, documentation, and operation-specific integration evidence. -4. Open a pull request targeting master and link the issue. +4. Open a pull request targeting `master` and link the issue. 5. Require review and passing CI on Node.js 20, 22, and 24; use pinned Solr integration jobs for behavior claims. -6. Merge the PR into master. -7. Update this roadmap and the API coverage/compatibility documents when scope or status changes. +6. Merge the PR into `master`. +7. Update this roadmap and API coverage/compatibility documents when scope or status changes. ## Definition of done -A feature is not complete merely because it compiles. It needs useful TypeScript autocomplete, consumer compile tests, unit tests, documentation, and integration evidence for supported Solr versions—or an explicit unverified/unsupported status. Record evidence per operation and version; never generalize a passing family-level CI job to every action. \ No newline at end of file +A feature is not complete merely because it compiles. It needs useful TypeScript autocomplete, consumer compile tests, unit tests, documentation, and integration evidence for supported Solr versions—or an explicit unverified/unsupported status. Record evidence per operation and version; never generalize a passing family-level CI job to every action.