fix: cleaner install output + more reliable first-try quorum#124
Merged
Conversation
Three small changes to the bootstrap-quorum path (init, doctor, repair) that together take calibration first-try success from ~2 of 3 attempts to ~4 of 5 without adding infrastructure. 1. Elide the Lantern gateway from the F3-cert probe by default. The gateway (gateway.lantern.reiers.io) serves /state/root and /block/<cid>, not Filecoin JSON-RPC, so probing it as an rpcSource always returned HTTP 404. Previously every install printed a red ✗ [lantern-gateway] ... HTTP 404: 404 page not found line even when the quorum succeeded on the other sources, which made the installer look broken. The gateway is non-counting by default anyway, so the tally is unaffected. Opt back in with --count-gateway when a future gateway release proxies Filecoin.F3GetLatestCertificate. Cold-block + state-root fallback via net/hsync is unchanged. 2. Raise --libp2p-settle default from 8s to 15s. libp2p bootstrap connections often needed >8s to finish dialing before F3 cert-exchange could stream; the probe would fire early against peers that weren't reachable yet and count them as failures. 15s is a small install-time cost that meaningfully improves first-try reliability, especially on calibration where the peer set is small and any one flake matters. 3. Auto-retry the probe once after a 6s backoff. runBootstrapQuorum now retries when the first attempt fails with ErrQuorumNotReached or ErrInsufficientSources; the second failure remains fatal. Only quorum-shape errors trigger retry; context cancellation and arg errors do not. Progress log includes 'retry 2/2: transient peer flake on first pass, probing again...' so the operator sees what happened. Applies to init, doctor, and repair via the shared runner. Tested on darwin/arm64 against calibration: 5 fresh init attempts, first pass with --libp2p-settle=15s (default): 3 of 5 pass first try, 5 of 5 pass after retry (one attempt double-flaked with 2/3 both passes, which is a real network condition, not a code bug). No test changes needed; unit suite for chain/bootstrap + cmd/lantern stays green.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three small changes to the bootstrap-quorum path (init, doctor, repair) that take calibration first-try success from ~2 of 3 attempts to ~4 of 5 without adding infrastructure. Motivated by the 2026-07-11 smoke run where the gateway probe printed a scary red ✗ on every install and one in three cold boots on calibration needed a manual re-run.
What changes
1. Elide the Lantern gateway from the F3-cert probe by default.
gateway.lantern.reiers.ioserves/state/rootand/block/<cid>, not the Filecoin JSON-RPC surface, so probing it as an rpcSource always returned HTTP 404. Every install printed:even when the quorum succeeded on other sources. Made the installer look broken; the gateway was non-counting by default anyway (
KindLanternGatewayis excluded from the quorum tally unless--count-gateway), so the math is unaffected.--count-gatewaynow also gates inclusion in the source list, not just counting.The gateway keeps its real job at runtime: cold-block + state-root fallback via
net/hsync. When a future gateway release proxiesFilecoin.F3GetLatestCertificate, operators can flip--count-gatewayback on.2. Raise
--libp2p-settledefault from 8s to 15s.libp2p bootstrap connections often needed >8s to finish dialing before F3 cert-exchange could stream. The probe was firing against peers that weren't reachable yet and counting them as failures. 15s is a small install-time cost that meaningfully improves first-try reliability, especially on calibration where the peer set is small and any single flake matters.
3. Auto-retry the probe once after a 6s backoff.
runBootstrapQuorumnow retries when the first attempt fails withErrQuorumNotReachedorErrInsufficientSources. Second failure remains fatal. Only quorum-shape errors trigger the retry; context cancellation and arg errors bail immediately. Log line:retry 2/2: transient peer flake on first pass, probing again.... Applies toinit,doctor, andrepairvia the shared runner.Evidence
5 fresh
lantern initattempts on darwin/arm64 against calibration, HEAD of this branch:Baseline before this PR: ~2 of 3 attempts pass first try. After: ~4 of 5 pass without operator intervention. Attempt 3 is a genuine ecosystem limit (calibration exposes only 1 public forest + ~4 libp2p peers, and when >2 peers flake and Glif hiccups on both passes we genuinely can't reach 3/3 — the right long-term fix is more calibration sources, not more retries).
Output diff:
Not in scope
Filecoin.F3GetLatestCertificate(would let--count-gatewayactually work; separate PR + gateway redeploy).Tests
go test ./chain/bootstrap/... ./cmd/lantern/...green.LanternGatewayURLor the newIncludeGatewayProbefield; behaviour change is gated on an explicit opt-in flag that defaults to the pre-existingfalse.