Crate krabka_restore

Expand description

Offline point-in-time restore of a krabka cluster.

krabka restore reads a KIP-405 tiered-storage archive from object storage and materializes a complete, bootable krabka data directory, replayed up to a bound and verified segment by segment as it rehydrates. The bound is an offset, a timestamp, or a set of exclude-record predicates, so an operator can recover an event-sourced system to the state it held just before a bad write. Recovery of that kind is a hand-built runbook everywhere else.

The tool runs when the cluster does not. It reads the archive through the object-store layer and formats the target through [krabka_format], and it does not depend on the broker.

§Stages

A restore runs five stages, and restore drives them in order:

Discover lists the archive and groups the keys into segments per topic partition.
Verify checks the framing and the CRC of every archived segment, and derives its true end offset and maximum timestamp.
Bound compiles the operator’s predicates and decides which batches and records survive.
Materialize formats the target log directory and writes the partition data.
Report renders what happened, as text or as JSON.

§Limits

A batch that the bound filters is re-encoded from the records that survive, so its bytes are not identical to the archived bytes. --exclude-key and --exclude-header match raw bytes and decode no payload. Without --rlmm-snapshot a segment the old cluster had marked for deletion is indistinguishable from a live one. Without --metadata-snapshot, topic configuration, ACLs, client quotas, SCRAM credentials, and finalized feature levels cannot be recovered.

§Errors and exit codes

The library returns RestoreError. Only run and the binary map one onto an exit code, so an embedding tool keeps the structured error. See EXIT_OK for the codes.

Structs§

ArchiveArgs: Where the archive is, and the restore inputs that sit beside it.
ArchiveInventory: Everything the scan found.
ArchiveObject: One artifact of one archived segment, as the scan found it.
ArchiveStore: A read handle on the archive, with the operator’s key prefix applied.
AuthenticationReport: Signed WORM evidence applied to the bytes consumed by restore.
Cli: The restore command line.
DisklessPartitionReport: Recovery boundary for one diskless partition.
DisklessRestoreReport: Diskless-WAL recovery outcome and its explicit limitations.
FormatTargetOutcome: The formatter outcome needed by the final restore report.
HeaderPattern: One --exclude-header pattern.
LeaderEpochStart: The offset a leader epoch starts at, from a leader-epoch checkpoint row.
MetadataRestoreReport: Cluster metadata recovered alongside the archived partition data.
OffsetBound: One --to-offset bound: the last offset the restore keeps in a partition.
OffsetRange: One --exclude-offset range, normalized to a half-open interval.
PartitionInventory: One partition of the archive.
PartitionRef: A topic partition an operator names in a bound.
PartitionReport: What the restore did for one partition.
Predicates: The compiled predicate set.
RestoreArgs: Arguments of an offline point-in-time restore.
RestoreReport: What the restore did, as a whole.
SegmentFacts: What verification established about one segment.
SegmentInventory: One archived segment and the artifacts the archive holds for it.
SegmentOutcome: What writing one segment into the target produced.
SkippedSegment: One segment the restore could not verify and did not write.
TargetArgs: The cluster the restore writes.
UnrecognizedKeys: The keys the scan could not attribute to a segment.
VerifiedSegment: A segment that passed verification, with the bytes that passed it.

Enums§

BatchDecision: What the bound decides about one archived batch.
RecordDecision: What the bound decides about one record inside a filtered batch.
ReportFormat: How RestoreReport::render writes the summary.
RestoreError: Every way a point-in-time restore stops.

Constants§

EXIT_ARCHIVE_UNREADABLE: See EXIT_OK.
EXIT_BAD_ARGUMENTS: See EXIT_OK.
EXIT_DIRTY_LOG_DIR: See EXIT_OK.
EXIT_INTEGRITY: See EXIT_OK.
EXIT_MATERIALIZE: See EXIT_OK.
EXIT_OK: Exit codes:
UNRECOGNIZED_SAMPLE_LIMIT: How many unattributable keys the scan keeps.

Functions§

format_target: Format the target log directory, seed it with the recovered topics, and return the cluster id it was formatted with.
inventory: Scan store and build the inventory of the partitions args selects.
object_store_config: Map the --archive-* flags onto an object-store configuration.
open_archive: Build the archive handle the --archive-* flags describe.
restore: Run a restore and return its report.
run: Run a restore and return the process exit code.
run_from_args: Run a restore from an argv-style iterator and return the process exit code.
seed_rlmm_snapshot: Seed the restored broker’s local RLMM cache while resetting its Kafka cursors for the new __remote_log_metadata topic.
verify_segment: Fetch and verify one segment.
verify_segment_authenticated: Fetch and verify one segment against signed WORM object claims.
write_segment: Write one verified segment into its target partition, under the bound.