[BUG] KVRangeRestorer leaves the restore future uncompleted when startRestore() throws, permanently wedging the range
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 88/100
- Issue type
- Bug
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- java
- Domain
- backend, distributed-systems, testing-qa
Research direction
Start in base-kv/base-kv-store-server/src/main/java/org/apache/bifromq/basekv/store/range/KVRangeRestorer.java at restoreFrom(), then trace the startRestore() and messenger.send() failure paths. Add the regression test described in the issue: verify synchronous start failure completes the future exceptionally and that retrying the same snapshot starts a fresh session.
Written by the indexing model from the issue text.
Description
Environment
- BiFroMQ
4.0.0/main @ eef5e3af - Module:
base-kv/base-kv-store-server - File:
base-kv/base-kv-store-server/src/main/java/org/apache/bifromq/basekv/store/range/KVRangeRestorer.java(restoreFrom)
Summary
restoreFrom() wraps snapshot-install setup in try { ... } catch (Throwable t) { log.error(...) } and returns the session's doneFuture. If startRestore() (or the subsequent messenger.send()) throws synchronously, the future is never completed — and there is no timeout on this path (unlike the receiver-driven path, which has an idle timeout). Worse, the session stays cached in currentSession: a retry with the same snapshot from the same leader hits the reuse branch and returns the same dead future, so the range is permanently stuck — it never applies anything and never retries.
Snapshot install is mandatory on expansion/rebalance, so any transient synchronous failure here is a hard wedge.
Suggested fix
Complete the future exceptionally in the catch block; the caller observes the failure and a retry starts a fresh session:
} catch (Throwable t) {
log.error("Unexpected error", t);
onDone.completeExceptionally(new KVRangeStoreException("Snapshot restore failed to start", t));
}
Test
New regression test: startRestore throws → the future must be completed exceptionally, and a retry with the same snapshot must start a fresh session (not reuse the dead one). Fails on the unfixed code.
Production validation
A 6-node BifroMQ 4.0.0 cluster (standalone.sh, systemd, mTLS clientAuth=REQUIRE), fronted by a TCP load balancer with 6 backends. Live clients: 3 bridge replicas (MQTT5, $oshare subscribers) and 10 backend service instances (persistent sessions). RocksDB engine, default configuration otherwise.
The fix (plus other changes) was rolled across all six nodes one node at a time (wholesale lib/ replacement, then restart), with a per-node gate (service active, all four ports listening, cluster mesh re-established). Six of six nodes succeeded, zero rollbacks.
Post-deploy checks (all measured after the rollout):
| Check | Result |
|---|---|
| Cluster mesh (inter-node 8898/8899 connections, per node) | 408–417 established on every node |
| Live client connections (3 bridge replicas + 10 backend services over mTLS) | 13/13 reconnected and stable |
| Cross-node delivery end-to-end | publish on one node → bridge (connected elsewhere) consumed it → forwarded (counter 0 → 1) |
| Client-visible protocol smoke | connect / subscribe / publish with QoS 1 all CONNACK 0 / PUBACK 0 |
No wedged range (a range stuck in snapshot restore) was observed before or after the deployment; the fix closes the permanent-wedge path should a synchronous start failure ever occur.
- Dominant language
- Java
- Stars
- 805
- Forks
- 99
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 1
Getting set up
- Ships a Dockerfile or Docker Compose file
- No pull request template
- No contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from apache/bifromq
-
[BUG] TopicUtil.isValidTopicFilter accepts "$share/g/" — a shared subscription with an empty filter that can never matchPossibly taken @efegokdemir claimed this 33 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
-
[BUG] UTF8Util.isWellFormed inverts the surrogate-pair check: valid non-BMP characters are rejected, lone surrogates acceptedPossibly taken @efegokdemir claimed this 33 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
-
Inbound and outbound packet-size checks differ, so a QoS 1 message just under MaxUserPayloadBytes is accepted but never delivered (blocks a persistent subscriber)May be free again @abhiramaab claimed this 25 days ago, and no pull request is open. Open
Difficulty 4/5 3-5 days Newbie friendliness 55/100
-
Difficulty 4/5 3-5 days Newbie friendliness 48/100
-
[BUG] ManagedRequestPipeline.close() leaves in-flight request futures pending foreverPossibly taken @ImDanXie claimed this 32 days ago. Open
Difficulty 3/5 1-2 days Newbie friendliness 68/100
Similar issues
-
agent:working bug follow-up lane:auto
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Sanne/incus-spawn#1765 · 2 comments ·
Maintainers usually reply within 1 day
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
checkstyle/checkstyle#22260 · 2 comments ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
strimzi/strimzi-kafka-operator#13328 · 1 comment · 3 reactions ·
Maintainers usually reply within 1 day