HarperFast / HarperFast/harper-pro
Re-scope the mid-log txnlog tear cluster test to the quarantine semantics (currently skipped)
- Dominant language
- JavaScript
- Stars
- 3
- Forks
- 0
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 80
Description
`integrationTests/cluster/txnlogTearReplication.test.mjs` asserts that replication **resyncs past** a
mid-log transaction-log tear and delivers every acknowledged row behind it. That is no longer the
intended behavior, so the suite is skipped and the coverage is gone until it is rewritten.
## Why the premise changed
HarperFast/harper#2087 reversed the recovery approach on the owner's decision. Resyncing past a break
skips one frame, and replay groups every equal-version entry into one source transaction — so a break
inside such a group would commit the surviving subset of a transaction that never committed that way
at the source. The policy is fail-stop/quarantine instead: stop at the break, discard the transaction
it truncated, and report it. Boundary-safe recovery waits until the engine can resume at a proven
transaction boundary.
That PR names this test directly: *"harper-pro#670 proves mid-log recovery end-to-end … #670's premise
no longer holds and needs re-scoping to the quarantine semantics."*
## Why it surfaced now
The suite gated itself on the engine exporting `CorruptFrameError`. `@harperfast/rocksdb-js` 2.7.1 did
not export it, so the suite silently skipped and `main` was green. The 2.8.0 bump (harper-pro
`b15fceb4`, "feat: Sync Core", 2026-08-31) exports it, so the suite began running against a core that
had already decided not to recover — and failed on every `main` run since, on all three Node versions,
with `B is missing the last row written after the tear (r59); it holds 39/60 rows`.
## What to do
Rewrite the oracle against the quarantine semantics: a mid-log break is **contained and reported**, not
recovered. The receiver stops at the break rather than silently reporting itself current, and the break
is surfaced. The signals worth asserting land with #2087 — the mid-log `error` (distinct from the
`warn` a torn tail gets) and the `getCorruptFrameReports()` registry — so this is best done with or
right after that PR rather than against today's core, where the only observable is a generic `warn`.
Worth keeping in scope while rewriting:
- The suite is the only place a genuinely damaged log on disk is read by a real replication stream;
the unit tests on both fix PRs drive synthetic iterators and hand-built buffers.
- The *readable* tear shape (#669) is still out of scope — framing recovery cannot help there.
- Nothing here stops a tear being created; that is HarperFast/rocksdb-js#748.
## Current state
Skipped with a reason (`pending re-scope to quarantine semantics (harper#2087)`), keeping the
`HARPER_TXNLOG_TEAR_FORCE=1` override for anyone reproducing what a torn log does today.
Refs HarperFast/harper#2087, HarperFast/harper#2063, HarperFast/harper#2016, #669, #670
Contributor guide
Research direction
Start with integrationTests/cluster/txnlogTearReplication.test.mjs and read HarperFast/harper#2087 to understand the quarantine semantics. Use HARPER_TXNLOG_TEAR_FORCE=1 and the existing cluster test setup to reproduce the current behavior. Done means the test asserts that a mid-log break stops and is reported through the mid-log error and getCorruptFrameReports(), rather than silently recovering or reporting the receiver current.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, nodejs
- Domain
- databases, distributed-systems, testing
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100