Replace term matchkey with pool.

[jakub-id]

Retain API compatibility and deprecate old endpoints.

[Copilot]

Pull request overview

This PR renames the “matchkey” concept to “pool” across the Reservoir server, introducing new /reservoir/config/pools APIs while keeping the existing /reservoir/config/matchkeys endpoints and matchkeyid parameter as deprecated compatibility aliases.

Changes:

• Added first-class pool configuration APIs (/reservoir/config/pools) and a new poolId query parameter, while retaining legacy matchkeys routes/parameters as deprecated aliases.
• Refactored server code and entities from MatchKeyConfig → PoolConfig, and updated clustering/ingest code paths to use poolId naming.
• Updated tests and operational/user documentation to prefer the new pool terminology and endpoints.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
server/src/test/java/com/indexdata/reservoir/server/MainVerticleTest.java	Updates integration tests to use /config/pools + poolId and adds coverage for deprecated matchkeys aliases.
server/src/test/java/com/indexdata/reservoir/server/entity/PoolConfigTest.java	Renames/updates unit tests to use PoolConfig.
server/src/main/resources/openapi/schemas/poolStats.json	Adds schema for pool stats responses.
server/src/main/resources/openapi/schemas/pools.yaml	Adds schema for pool collection responses.
server/src/main/resources/openapi/schemas/pool.yaml	Adds schema for an individual pool configuration.
server/src/main/resources/openapi/schemas/matchKeyStats.json	Updates deprecated matchkeys stats schema description.
server/src/main/resources/openapi/schemas/matchKeys.yaml	Updates deprecated matchkeys collection schema descriptions to reflect pool compatibility.
server/src/main/resources/openapi/schemas/matchKey.yaml	Updates deprecated matchKey schema naming/description to reflect pool compatibility.
server/src/main/resources/openapi/reservoir.yaml	Introduces /config/pools paths and marks matchkeys paths as deprecated aliases; updates clusters/touch docs for poolId.
server/src/main/resources/openapi/parameters/poolId.yaml	Adds poolId query parameter definition.
server/src/main/resources/openapi/parameters/matchkeyid.yaml	Marks matchkeyid deprecated and no longer required.
server/src/main/java/com/indexdata/reservoir/server/Storage.java	Refactors storage layer to PoolConfig naming while keeping underlying table name for compatibility.
server/src/main/java/com/indexdata/reservoir/server/SruService.java	Refactors SRU-related config handling to use PoolConfig.
server/src/main/java/com/indexdata/reservoir/server/ReservoirService.java	Adds pool endpoints/handlers and compatibility routing for legacy matchkeys endpoints; updates cluster selection to use poolId aliasing.
server/src/main/java/com/indexdata/reservoir/server/OaiService.java	Switches OAI “set” resolution to pool config selection.
server/src/main/java/com/indexdata/reservoir/server/MatcherResult.java	Renames match key identifier field to poolId.
server/src/main/java/com/indexdata/reservoir/server/IngestMatcher.java	Renames match key identifier field to poolId.
server/src/main/java/com/indexdata/reservoir/server/entity/PoolConfig.java	Renames entity class and updates validation/messages to pool terminology.
server/src/main/java/com/indexdata/reservoir/server/CqlFields.java	Adds POOL_ID CQL field and repoints config-related fields to the pool-config table constant.
README.md	Updates examples and documents deprecated alias support.
docs/ops/obtain-example-records.md	Updates operational examples from matchkeyid to poolId and wording.
docs/ops/miscellaneous.md	Updates operational notes/examples to pool endpoints and terminology.
docs/ops/configure.md	Updates configuration guide to matchers/pools terminology and endpoints.
descriptors/ModuleDescriptor-template.json	Adds new permissions/handlers for pool config endpoints and re-labels deprecated matchkeys permissions.

Suppressed comments (2)

server/src/main/resources/openapi/schemas/pools.yaml:13

• In OpenAPI 3.0, a $ref cannot be combined with sibling keys like type/description. To keep a local description, wrap the reference in allOf.

  resultInfo:
    description: Common result set information
    type: object
    $ref: resultInfo.json

server/src/main/resources/openapi/schemas/poolStats.json:28

• Because /stats responses don’t include totalRecords, requiring it makes this schema fail validation for that endpoint. If both initialize and stats share this schema, required should be loosened (or expressed with anyOf) so either totalRecords or recordsTotal is acceptable.

  "required": [
    "totalRecords"
  ],

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated no new comments.

Suppressed comments (5)

server/src/main/resources/openapi/schemas/pools.yaml:9

• In OpenAPI schemas, $ref should not be combined with sibling keywords like type under the same schema object (many tooling implementations ignore siblings). Here the items schema mixes type: object and $ref.

    items:
      type: object
      $ref: pool.yaml

server/src/main/java/com/indexdata/reservoir/server/ReservoirService.java:220

• The new clusters API accepts poolId, with legacy fallback to matchkeyid. When neither is provided, the 400 message currently says matchkeyid, which is misleading for new clients.

      failHandler(400, ctx, "Missing required query parameter: matchkeyid");

server/src/main/java/com/indexdata/reservoir/server/entity/PoolConfig.java:67

• PoolConfig currently allows matcher to be omitted (it only requires id). This means clients can create/update a pool that will later fail at ingest/initialize time (Storage.createIngestMatcher returns a failed Future when matcher is missing). Consider rejecting configs without matcher up front.
  server/src/main/resources/openapi/schemas/pool.yaml:38
• If matcher is required (the server fails when it is missing), the OpenAPI schema should reflect that so clients can validate requests locally.

required:
  - id

server/src/main/resources/openapi/schemas/pools.yaml:13

• In OpenAPI schemas, $ref should not be combined with sibling keywords like type under the same schema object. The resultInfo schema mixes type: object and $ref.

  resultInfo:
    description: Common result set information
    type: object
    $ref: resultInfo.json

[Copilot]

Pull request overview

Copilot reviewed 25 out of 25 changed files in this pull request and generated no new comments.

Suppressed comments (2)

server/src/main/java/com/indexdata/reservoir/server/ReservoirService.java:220

• The clusters endpoint now prefers the poolId query parameter, but the 400 error message still refers only to the deprecated matchkeyid. This is confusing for new clients and inconsistent with the OpenAPI docs that introduce poolId. Consider mentioning both parameters (with poolId as the preferred name).

      failHandler(400, ctx, "Missing required query parameter: matchkeyid");

server/src/test/java/com/indexdata/reservoir/server/MainVerticleTest.java:1369

• This test is named testPoolIdMissing, but it currently asserts the legacy error text mentioning only matchkeyid. If the API is moving toward poolId as the primary parameter, updating the assertion to look for poolId (and optionally still allow mentioning matchkeyid) will keep the test aligned with the new contract.

  public void testPoolIdMissing() {
    RestAssured.given()
        .header(XOkapiHeaders.TENANT, TENANT_1)
        .header("Content-Type", "application/json")

[Copilot]

Pull request overview

Copilot reviewed 36 out of 36 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 36 out of 36 changed files in this pull request and generated no new comments.

Suppressed comments (5)

server/src/main/java/com/indexdata/reservoir/server/Storage.java:929

• tx.commit() is asynchronous; completing the promise immediately can return the connection to the pool before the transaction is actually committed (and any commit failure is silently ignored). Await the commit result before completing the promise.

          stream.endHandler(end -> {
            tx.commit();
            promise.complete(totalRecords.get());
          });

server/src/main/java/com/indexdata/reservoir/server/Storage.java:934

• On stream failure, the code commits the transaction and doesn't await the async result. This can persist partial updates and still report a failure. Roll back on errors and wait for rollback/commit completion before resolving the promise.

          stream.exceptionHandler(e -> {
            log.error(e.getMessage(), e);
            tx.commit();
            promise.fail(e);
          });

server/src/main/resources/openapi/reservoir.yaml:617

• The API requires a pool selector (poolId or deprecated matchkeyid), but the OpenAPI description doesn’t state that at least one must be provided. This can confuse clients because both parameters are marked required: false.

      description: >
        Get clusters in a pool selected by poolId. The deprecated matchkeyid parameter is also
        accepted. Query is CQL with the following fields supported:
        matchValue, clusterId, globalId, localId, sourceId, sourceVersion.

server/src/main/java/com/indexdata/reservoir/server/Storage.java:399

• PoolConfig#getMatcherInvocations() throws when matcher is null/invalid. Because poolConfigFromRow doesn’t call validate(), a bad DB row will throw here synchronously and bypass the intended Future failure path. Catch the exception and return a failed Future so callers get a controlled error instead of an uncaught exception.

    ingestMatcher.poolId = poolConfig.getId();
    String[] matcherInvocations = poolConfig.getMatcherInvocations();
    if (matcherInvocations.length > 0) {

server/src/main/resources/openapi/parameters/poolId.yaml:4

• poolId is effectively required unless the deprecated matchkeyid is supplied; consider documenting that constraint in the parameter description to match runtime behavior.

in: query
name: poolId
description: Pool identifier
required: false

[dcrossleyau]

Thanks for also doing such a good job with the various documentation.