Repair the registry from storage

POST/v1alpha1/admin/registry/actions/repairregistry.repair

Registers every synced generation that storage holds and the registry does not name. The repair operation only adds entries: it keeps existing entries as stored and never deletes an index, a generation, or storage data. If the registry is absent, the repair writes it fresh. If the registry is corrupt, the repair replaces it with one rebuilt from storage.

When "promoteNewest": true, each index created by the repair answers for its highest-numbered generation. Hand-named generations are not selected. Indexes that are already registered keep what they answer for. When omitted or false, created indexes answer for nothing until a generation is promoted.

Storage of a deleted index or generation, which the audit reports with removedAt, is skipped until the sweep removes it. Naming it in "restore" takes the removal mark off and registers it like any other unregistered storage, which is how a delete is taken back within the grace period.

The write is conditional and rebuilds on top of concurrent registry changes. The answering node applies the repaired registry immediately; other nodes pick it up within EXOFIND_INDEXES_REFRESH_INTERVAL.

Served by whichever node receives the request and never forwarded. Answers only in object storage mode.

Request

HTTP

POST /v1alpha1/admin/registry/actions/repair
Authorization: Bearer <key>
Content-Type: application/json

{
  "promoteNewest": true,
  "restore": [
    "books"
  ]
}

curl

curl -X POST "http://localhost:8080/v1alpha1/admin/registry/actions/repair" \
  -H "Authorization: Bearer $EXOFIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "promoteNewest": true,
  "restore": [
    "books"
  ]
}'

JavaScript

const apiKey = process.env.EXOFIND_API_KEY;

const response = await fetch("http://localhost:8080/v1alpha1/admin/registry/actions/repair", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "promoteNewest": true,
    "restore": [
      "books"
    ]
  })
});

const result = await response.json();

Java

String apiKey = System.getenv("EXOFIND_API_KEY");

String body = """
  {
    "promoteNewest": true,
    "restore": [
      "books"
    ]
  }
  """;

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("http://localhost:8080/v1alpha1/admin/registry/actions/repair"))
  .header("Authorization", "Bearer " + apiKey)
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString(body))
  .build();

HttpResponse<String> response = HttpClient.newHttpClient()
  .send(request, HttpResponse.BodyHandlers.ofString());

Go

apiKey := os.Getenv("EXOFIND_API_KEY")

body := strings.NewReader(`{
  "promoteNewest": true,
  "restore": [
    "books"
  ]
}`)

request, err := http.NewRequest("POST", "http://localhost:8080/v1alpha1/admin/registry/actions/repair", body)
if err != nil {
  log.Fatal(err)
}

request.Header.Set("Authorization", "Bearer "+apiKey)
request.Header.Set("Content-Type", "application/json")

response, err := http.DefaultClient.Do(request)

Response200

{
  "createdIndexes": [
    "products"
  ],
  "addedGenerations": [
    "products@2"
  ],
  "promoted": [
    "products@2"
  ],
  "restored": [
    "products"
  ]
}

Body

RegistryRepairRequestOptional

How a repair should treat the indexes it creates, and which deleted indexes or generations it should bring back. The entire body is optional.

promoteNewestboolean

When true, each index created by the repair answers for its highest-numbered generation. Hand-named generations are not selected. Indexes that are already registered keep what they answer for. When false, a created index answers for nothing until a generation is promoted.

Default

false

restorestring[]

Names of deleted indexes (books) or generations (books@2) whose storage the sweep has not removed yet, to bring back. The repair registers what each one holds like any other unregistered storage, then takes the removal mark off it. A name whose storage holds no synced generation keeps its mark, so the sweep still removes it. A name without a mark changes nothing. Deleted storage is never registered without being named here.

Example

[
  "books"
]

Responses

200

A summary of the changes made by the repair.

RegistryRepairResponse

Summary of the changes made by a repair. Every list empty means the registry already named everything storage holds, nothing was restored, and nothing was written.

createdIndexesstring[]

Index entries added to the registry, ordered by name.

addedGenerationsstring[]

Generations added to the registry, formatted as index@generation and ordered by name.

promotedstring[]

Generations made live by the repair, formatted as index@generation and ordered by name.

restoredstring[]

Deleted indexes and generations whose removal mark the repair took off, as index or index@generation, in the order the request named them. What they hold appears in the other lists.

400

An entry of restore is not a valid index or generation name.

ErrorResponse

The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.

codestring

Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.

Example

"validation"

messagestring

Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.

Example

"Request contains 2 errors"

errorsErrorDetail[]

All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.

Example

{
  "code": "index:field:primary_key:multiple_unsupported",
  "message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
  "path": "id"
}

4 properties

codestring

The error code identifying this specific problem.

Example

"index:field:primary_key:multiple_unsupported"

messagestring

Human-readable description of this problem.

Example

"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"

pathstring

Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.

Example

"id"

argumentsmap of string

The values the message was rendered with, so a client can render a message of its own from the code.

1 property

<key>string

Error codes

index:name_invalid

An entry of `restore` is not a valid index or generation name.

401

The request carries no credential this node accepts. Absent, malformed, unknown and lapsed keys are all answered alike, so a refusal cannot be used to find out which keys exist. The response carries WWW-Authenticate: Bearer.

ErrorResponse

The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.

codestring

Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.

Example

"validation"

messagestring

Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.

Example

"Request contains 2 errors"

errorsErrorDetail[]

All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.

Example

{
  "code": "index:field:primary_key:multiple_unsupported",
  "message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
  "path": "id"
}

4 properties

codestring

The error code identifying this specific problem.

Example

"index:field:primary_key:multiple_unsupported"

messagestring

Human-readable description of this problem.

Example

"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"

pathstring

Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.

Example

"id"

argumentsmap of string

The values the message was rendered with, so a client can render a message of its own from the code.

1 property

<key>string

Error codes

auth:unauthenticated

The request carries no credential this node accepts.

403

The API key does not have the registry.repair permission.

ErrorResponse

The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.

codestring

Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.

Example

"validation"

messagestring

Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.

Example

"Request contains 2 errors"

errorsErrorDetail[]

All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.

Example

{
  "code": "index:field:primary_key:multiple_unsupported",
  "message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
  "path": "id"
}

4 properties

codestring

The error code identifying this specific problem.

Example

"index:field:primary_key:multiple_unsupported"

messagestring

Human-readable description of this problem.

Example

"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"

pathstring

Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.

Example

"id"

argumentsmap of string

The values the message was rendered with, so a client can render a message of its own from the code.

1 property

<key>string

Error codes

auth:forbidden

The key is accepted but does not hold the `registry.repair` permission.

409

The endpoint was called on a node configured with local storage, or writing the repaired registry failed. The registry remains unchanged.

ErrorResponse

The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.

codestring

Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.

Example

"validation"

messagestring

Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.

Example

"Request contains 2 errors"

errorsErrorDetail[]

All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.

Example

{
  "code": "index:field:primary_key:multiple_unsupported",
  "message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
  "path": "id"
}

4 properties

codestring

The error code identifying this specific problem.

Example

"index:field:primary_key:multiple_unsupported"

messagestring

Human-readable description of this problem.

Example

"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"

pathstring

Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.

Example

"id"

argumentsmap of string

The values the message was rendered with, so a client can render a message of its own from the code.

1 property

<key>string

Error codes

index:registry:audit_unavailable

The node stores indexes on local disk, where there is no shared registry to repair.

storage:conflict

The registry kept being written by other nodes. The registry is unchanged; send the request again.

storage:io_error

Registry storage answered with an error. The registry is unchanged; send the request again.

Authorization

Permission

registry.repair

Checked on

The deployment, not one index

Roles

admin

An API key sent as a bearer token, such as Authorization: Bearer exok_4ff6b760264c1918_ePQcdT1O9HSATZoXfDbT8hhHGsP9VpZH. A key carries grants that pair permissions with index patterns; the permission each endpoint needs is named beside it. Nodes running with EXOFIND_AUTH_MODE=none accept requests without a credential, and a node with EXOFIND_AUTH_ANONYMOUS_KEY set serves requests that carry none with the permissions of that key.