verify-store

Verifies the integrity of the store: its events, its event schemas, and its indexes.

Route: POST /api/v2/management/verify-store
Category: management
Authentication: required, with the API token
Answer: a stream of NDJSON

A verification checks that every event can be read and that the events form an unbroken chain of hashes, that every stored event schema compiles, is not too complex to validate against, and describes an object, and that every index is well-formed and holds what the events say it has to. What it finds is reported as findings, while an error means that the verification could not run to completion. Reads and writes go on while it runs: it checks the store as of the latest event at its start, and leaves what is written meanwhile to the next verification. Only where the latest event is damaged, or does not lie where its ID says, does it check the whole store at once, so that writes wait until it is done. Verifying Store Integrity explains when to run it and how to read its findings.

Request#

The route takes no body, and ignores one that is sent. To verify the store:

curl \
  -X POST \
  -H "authorization: Bearer secret" \
  http://localhost:3000/api/v2/management/verify-store

Answer#

The answer is a stream of items, one per line. Each finding is a finding item:

Type	Data	When
`finding`	`severity`, which is `error` for an inconsistency of the store and `warning` for a notice that does not necessarily indicate one, and `description`, which says what was found	Once the verification is done, for every inconsistency and every warning. Each check reports up to 100 inconsistencies, and where it found more, one further finding that says how many. Findings with the severity `error` come first, check by check, followed by the warnings.
`error`	`code`, `description`, and `details`	When the verification cannot run to completion, in place of any findings, see Errors.
`heartbeat`	empty	While nothing else is sent for a while, to keep the connection alive.
`end`	empty	Once, as the last item, when the stream ends cleanly.

Heartbeats and the end item work as on every stream of the API, see Streams. A store in which the verification finds nothing is answered with the end item alone, so treat only that as a clean result: a stream with an error item, or one that breaks off without its end, is a verification that did not finish.

For a store whose events file was changed on disk, the request above is answered with:

{"type":"finding","data":{"severity":"error","description":"structural verification of \"events\" failed: failed to validate file \"events/0.esdb\": file checksum does not match"}}
{"type":"end","data":{}}

Errors#

The verification reports these errors as an error item, followed by the end item:

indexes-rebuilding: The indexes are still being rebuilt after an upgrade, and would differ from the events only because they are not complete yet.
restore-in-progress: A restore is running when the verification starts. A verification that began before the restore waits until it is over instead.
store-failed: The store refuses reads for good, after a restore that could not empty it again.
file-unreadable: The verification cannot read a file of the store, for example because the disk returns an input/output error, and stops there without findings.
server-shutting-down: The server began to shut down after the verification had sent a heartbeat. Before that, the server answers with 503 instead.

Status Codes#

Before the stream begins, the server answers with a status code other than 200 where it cannot take the request at all, as described in Errors:

401: The API token is missing or wrong.
429: Too many requests were sent, or the client already holds 256 open streams, see Rate Limiting; the answer says when to try again.
500: The server failed unexpectedly before the stream began. Once it has begun, the stream breaks off without its end item instead.
503: The server is shutting down, or began to shut down before the stream began.