[ISSUE #9173]♻️Complete mapped-file lifecycle finalization

[mxsm]

Which Issue(s) This PR Fixes(Closes)

• Fixes [Refactor♻️] Complete mapped-file lifecycle consumer convergence and final acceptance #9173

Brief Description

• Complete the remaining mapped-file lifecycle consumer convergence and enable explicit Store destruction only after ordinary shutdown.
• Keep the activation boundary simple and fail-closed: explicit default-off configuration, retained exclusive Store-root lease, complete replay/reconciliation, and qualified platform support. No signatures, private keys, activation tokens, timestamps, force flags, or bypass path are introduced.
• Route Store-destroy retirement through the durable intent, registry, single-CAS queue handoff, namespace, and completion pipeline while preserving normal-shutdown segments for restart.
• Reopen reconciled segments through retained-root, handle-relative, no-follow platform APIs with exact physical-key and length validation.
• Migrate the store inspection reader away from direct mapped-file ownership and restore the checked-in lifecycle fixture corpus required by the frozen format tests.

How Did You Test This Change?

• cargo fmt --all -- --check on WSL2 Ubuntu 24.04: passed.
• cargo clippy --workspace --no-deps --all-targets --all-features -- -D warnings: passed.
• cargo test -p rocketmq-store-local --lib mapped_file::retirement -- --test-threads=1: 303 passed.
• cargo test -p rocketmq-store --lib wave_b_ -- --test-threads=1: 8 passed.
• Linux focused Store-destroy admission and shutdown-to-explicit-destroy tests: 2 passed in an isolated target.
• Full affected-package Windows and Linux test/Clippy matrices, strict-provenance Miri, runtime ownership audit, and the store_recovery_record fuzz target passed.
• mapped_write_lease benchmark completed 10/10 cases with a stable source snapshot; 4/10 cases were within the M0 3% observation line and 7/10 within the pre-optimization line. Remaining deviations are recorded as performance debt rather than treated as a hard safety gate.

Summary by CodeRabbit

• New Features
  • Added graceful store destruction that safely retires stored data and reports completion status.
  • Store shutdown now drains pending retirement work before final destruction.
  • Durable message data is preserved across ordinary shutdown and can be replayed after restart.
• Bug Fixes
  • Improved validation when opening stored segments, detecting invalid, altered, truncated, or mismatched files.
  • Hardened content inspection against malformed or incomplete records.
• Lifecycle
  • Destruction is now state-aware, retryable, and idempotent.

[rocketmq-rust-bot]

🔊@mxsm 🚀Thanks for your contribution🎉！

💡CodeRabbit(AI) will review your code first🔥！

Note

🚨The code review suggestions from CodeRabbit are to be used as a reference only, and the PR submitter can decide whether to make changes based on their own judgment. Ultimately, the project management personnel will conduct the final code review💥.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: c6a46810-c189-43ba-8dd5-aa5d83bc6ae5

📥 Commits

Reviewing files that changed from the base of the PR and between 47ed46c and c08fbac.

📒 Files selected for processing (22)

• rocketmq-store-local/src/mapped_file/retirement/activation.rs
• rocketmq-store-local/src/mapped_file/retirement/fixture_corpus/build/edges.rs
• rocketmq-store-local/src/mapped_file/retirement/fixture_corpus/build/frontiers.rs
• rocketmq-store-local/src/mapped_file/retirement/fixture_corpus/build/samples.rs
• rocketmq-store-local/src/mapped_file/retirement/platform.rs
• rocketmq-store-local/src/mapped_file/retirement/platform/linux.rs
• rocketmq-store-local/src/mapped_file/retirement/platform/windows.rs
• rocketmq-store-local/src/mapped_file/retirement/registry/queue_slot.rs
• rocketmq-store-local/src/mapped_file/retirement/service.rs
• rocketmq-store-local/src/mapped_file/retirement/service/creation.rs
• rocketmq-store-local/src/mapped_file/retirement/service/tests.rs
• rocketmq-store-local/src/mapped_file/retirement/state/reconciliation.rs
• rocketmq-store/src/base/backend_ops.rs
• rocketmq-store/src/consume_queue/mapped_file_queue.rs
• rocketmq-store/src/message_store.rs
• rocketmq-store/src/message_store/local_file_message_store.rs
• rocketmq-store/src/message_store/local_file_message_store/lifecycle.rs
• rocketmq-store/src/message_store/local_file_message_store/mapped_file_retirement_service.rs
• rocketmq-store/src/message_store/rocksdb_message_store.rs
• rocketmq-store/tests/mapped_file_retirement_service.rs
• rocketmq-store/tests/message_store/local_file_message_store/unit.rs
• rocketmq-tools/rocketmq-store-inspect/src/content_show.rs

---

Walkthrough

The PR adds platform-specific active-segment verification, extensive retirement fixtures, runtime queue-generation tracking, asynchronous graceful destruction, lifecycle tests, and buffered commit-log inspection.

Changes

Mapped-file retirement lifecycle

Layer / File(s)	Summary
Verified active-segment staging rocketmq-store-local/src/mapped_file/retirement/activation.rs, rocketmq-store-local/src/mapped_file/retirement/platform*, rocketmq-store-local/src/mapped_file/retirement/state/reconciliation.rs	Staging reopens claimed segments through platform-specific namespace and physical-identity checks, then replaces retained file handles.
Retirement fixture corpus rocketmq-store-local/src/mapped_file/retirement/fixture_corpus/build/*	Deterministic samples and edge and frontier fixtures cover ledger, acknowledgement, snapshot, marker, recovery, and tail-repair cases.
Admission and generation tracking rocketmq-store-local/src/mapped_file/retirement/registry/queue_slot.rs, rocketmq-store-local/src/mapped_file/retirement/service*, rocketmq-store/src/consume_queue/mapped_file_queue.rs	Runtime admission uses lifecycle states, tracks queue generations, submits store-destroy retirements, and reports backlog and completion state.
Graceful destruction API and lifecycle rocketmq-store/src/base/backend_ops.rs, rocketmq-store/src/message_store*, rocketmq-store/tests/message_store/local_file_message_store/unit.rs	Backends expose asynchronous graceful destruction. Managed stores drain retirement work before marking durable data destroyed. Tests cover shutdown, restart, retry, idempotency, and legacy behavior.

Store inspection reader

Layer / File(s)	Summary
Validated sequential record reading rocketmq-tools/rocketmq-store-inspect/src/content_show.rs	Inspection reads commit-log records with File and BufReader, validates lengths, and decodes complete records.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related issues

• mxsm/rocketmq-rust#9143 — Covers the mapped-file retirement, namespace verification, lifecycle runtime, and durable destruction work extended by this PR.

Possibly related PRs

• mxsm/rocketmq-rust#9172 — Directly extends the same lifecycle with active-segment staging, queue tracking, and graceful destruction.
• mxsm/rocketmq-rust#9175 — Directly overlaps the added retirement fixture modules.
• mxsm/rocketmq-rust#9142 — Provides related generation-owned file handling used by verified segment reopening.

Suggested labels: refactor♻️, approved, auto merge, AI review first

Suggested reviewers: rocketmq-rust-bot

Poem

A rabbit checks each segment tight,
With verified paths by day and night.
Queues retire, then stores rest,
Durable cleanup passes the test.
“Hop!” says the hare, “the files are right.”

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch mxsm/issue-9173-mapped-file-lifecycle-finalization

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}