Skip to content

Repository navigation

api-coverage.md

Latest commit

 

History

History
103 lines (73 loc) · 24.9 KB

api-coverage.md

File metadata and controls

103 lines (73 loc) · 24.9 KB
Raw

Solr API coverage

See the public API reference for the package-root client methods and exported API groups. The documentation consistency check verifies the reference against the source declarations and package entry points.

See the Solr endpoint inventory for the explicit typed-client boundary, deferred endpoint families, and official Solr reference sources.

The Solr V2 API strategy records the V1/V2 route map and version boundaries. The client now exposes a low-level, explicit client.v2 namespace over the shared transport; operation-specific V2 wrappers and runtime certification remain separate follow-up work.

See Client architecture for module boundaries, type-model guidelines, and shared request conventions. The roadmap tracks priorities and links to implementation issues.

See the machine-readable API inventory for each operation, request path, type coverage, unit-test status, and per-version integration status. The Collections action coverage matrix maps each exposed Collections action to its input type, response contract, tests, and pinned Solr evidence.

The testing and quality strategy defines the required evidence for each test layer, API-to-test traceability, failure-mode coverage, coverage reporting, and flaky-test policy.

A generic request method does not mean that every endpoint has a typed wrapper, useful IDE autocomplete, or tested version support. For supported features, the primary public API should expose named TypeScript properties and nested models that IDEs can complete and validate. Custom parameters remain available through an explicit escape hatch.

API area Current public surface Remaining work
Solr V2 API client.v2.request<T>() and client.v2.requestRaw() provide an explicit generic V2 escape hatch. Existing CoreAdmin, Collections, Schema, and Config methods remain V1. Add operation-specific typed Core Admin and Collections V2 methods, version-specific request/response contracts, and runtime evidence. No automatic fallback. See Issues #332–#334.
Package exports ESM and CommonJS runtime entries; conditional TypeScript declarations for both module systems Older TypeScript resolution modes use the top-level declaration entry.
v3 to v4 migration Migration guide maps legacy client/configuration and helper patterns to the v4 factory, typed methods, Fetch transport, and error classes; compile-only checks reject legacy config keys and an end-to-end CRUD integration test verifies the replacement flow on Solr 8.11.4/9.11.0/10.1.0 Application-specific v3 query/configuration defaults still require a deliberate migration review.
Client transport Typed base URL, core/collection, Basic/Bearer auth headers, header precedence, client and per-request timeouts, AbortSignal controls, custom fetch, request defaults, opt-in retries, optional SolrJsonCodec for lossless JSON parsing/serialization, and same-origin raw requests with raw string bodies and streamed responses via requestRaw() Native JSON remains the default; exact 64-bit integer handling is opt-in through a caller-supplied codec. The built-in transport does not log requests or copy Authorization values into error properties; custom logging and server-controlled error bodies still require redaction. Advanced auth mechanisms and retry telemetry remain. XML is a generic raw-request escape hatch rather than a typed update API.
Errors SolrHttpError, SolrNetworkError, SolrTimeoutError, SolrAbortError, and SolrValidationError Solr-version-specific error payloads still need integration evidence.
Validation Optional input/output schema interface; optional Zod peer; async parsing; rejection and thrown-parser errors; disabled by default Additional schema adapters and operation-specific schema examples.
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<TDocument> and SolrQueryResponse<TDocument, TJsonFacet> 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 SpellCheck options for dictionaries, term suggestions/frequencies, collations, and collate parameter overrides; typed Suggester options for configured dictionary selection, lookup text/count, context filters, explicit build/reload controls, and dictionary/query-keyed suggestion responses; configured-handler integration tests for SpellCheck and Suggester passed on pinned Solr 8.11.4, 9.11.0, and 10.1.0 (CI run #42392182590); 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.
RealTime Get get() with mutually exclusive single-ID and multi-ID request contracts, generic document responses, field selection, filter queries, custom parameters, and shared request controls Unit serialization/validation and consumer type fixtures; integration read-after-write test verifies uncommitted single-ID and multi-ID retrieval before searcher visibility on pinned Solr 8.11.4, 9.11.0, and 10.1.0 (CI run #42392182590).
Update / Documents add(), addStream(), update(), atomicUpdate(), updateCommands(), delete(), commit(), softCommit(), optimize(), rollback(); addStream() consumes an AsyncIterable through a bounded Web ReadableStream and uses the shared transport; consumer type fixtures assert default/custom response generics and reject synchronous iterables and invalid option types 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<TDocument>() 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. addStream() has a deterministic 250-document count/order read-back integration test that passed on pinned Solr 8.11.4, 9.11.0, and 10.1.0 in CI run #42376175065, with all 30 Node.js/Solr matrix and documentation jobs successful. 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; 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<A> 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 and Issue #229.
Collections collections(action, params) with action-specific CollectionAdminParams<A> and CollectionAdminResponse<A> 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. MODIFYCOLLECTION, SPLITSHARD, MIGRATE, ADDROLE, and REMOVEROLE remain runtime-unverified. See backup and restore docs, Collections action matrix, 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"
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, core backup/restore/status/delete, and raw file-content streaming. Core backup/restore cycles are integration-tested on Solr 8.11.4/9.11.0/10.1.0. A disposable two-core leader/follower fetchindex with follower query read-back passed on all three pinned versions (CI #640). A bounded in-progress abortfetch test passes on Solr 9.11.0 and 10.1.0; Solr 8.11.4 remains explicitly unverified because CI did not expose an observable active-fetch state. enablepoll/disablepoll retain serialization-only coverage. See replication docs and closed verification Issue #259.
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 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=true is runtime-tested on 10.1.0 with stored-only field read-back; no support claim is made for Solr 8/9. 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 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 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 — verified on Solr 10.1.0 by PR #261 using stored-only field read-back. Solr 8/9 behavior remains unclaimed.
  • ReplicationHandler abort/async lifecycle — one-shot fetchindex and follower read-back are verified, but abort/polling semantics are not; tracked by #259.

Implemented feature/design work

  • RealTime Get (/get) — implemented in PR #271; the uncommitted single/multi-ID read-after-write integration test passed on pinned Solr 8.11.4/9.11.0/10.1.0 (CI run #42392182590).
  • SpellCheck — implemented as an optional standard-query component in PR #272; configured-handler integration coverage passed on all three pinned Solr versions (CI run #42392182590).
  • BigInt-safe JSON precision — implemented in PR #299 through an injectable SolrJsonCodec; native JSON remains the default, while callers can supply a lossless BigInt-aware codec.
  • Suggester — implemented in PR #298 as an optional query component; the disposable configured-handler integration test passed on pinned Solr 8.11.4/9.11.0/10.1.0 (CI run #42392182590).
  • Cross-client regression test audit — completed in PR #296; nested-document and Unicode read-back tests passed on all three pinned Solr versions in CI run #42392182590, while long-query and custom-handler behavior is covered by transport unit tests.
  • Streaming document ingestion — implemented and merged in #300, hardened in #317, and completed with tests/docs in #321 and #325; 250-document count/order read-back passed on all three pinned Solr versions.
  • Prepare-commit lifecycle — #294 first audits existing typed update commands, then decides whether a dedicated method is justified.

Deferred pending a concrete consumer requirement

  • Terms handler (/terms) — deferred pending a concrete consumer requirement; this is distinct from Suggester and SpellCheck. Generic request() remains available.
  • 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.

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.

Definition of done

An API feature is complete when it has:

  1. Named, exported request and response types that provide useful IDE autocomplete.
  2. Compile-time consumer examples, including typo/invalid-option checks where applicable.
  3. Unit tests for serialization, request path, and response typing.
  4. Documentation with realistic examples and version-specific notes.
  5. Integration tests for each target Solr major version, or an explicit unverified/unsupported status.
  6. A recorded compatibility result in compatibility.md.

Test every target endpoint against Solr 8.x, 9.x, and 10.x. Do not infer server support from a successful TypeScript build.

Cross-client regression coverage

The cross-client audit identified and added focused coverage without broadening the public API:

  • add() and query(): nested parent/child/grandchild document round-trip and exact Unicode/multi-valued field round-trip, in test/integration/solr-document-fidelity.test.ts.
  • query(): long query parameter preservation on GET, without implicit GET-to-POST switching, in test/transport-serialization.test.ts.
  • request(): custom handler path, repeated query parameters, and unknown/plugin-defined response fields in test/raw-request.test.ts.

The nested/Unicode integration tests are part of the normal standalone integration suite. Their source is added, but pinned Solr CI execution is still required before extending runtime compatibility evidence. Existing cursorMark, retry, cancellation, timeout, HTTP error, raw XML body, and SolrCloud shard-routing tests are retained rather than duplicated. See ADR 0003 and issue #297.