Rongsong Shen
d26ff8870d
The buglog was one 27K-line JSON file whose fields covered only symptom,
root cause and fix, as free text: 2% of entries named the code version a
bug was found on, 12% the build profile, 36% a way to reproduce, and 58% of
the file was OpenWolf hook auto-detections ("Missing guard clause",
"Function not marked async" on .md files).
- .claude/skills/buglog/bug-record.md: the record standard. Eight
sections (Summary as the title, Description, Environment, Reproduction;
Root cause, Fix, Verification, References once fixed), each with the
content it must contain -- e.g. Environment needs the OS, the libc the
failing binary loads (from its ELF interpreter: glibc 2.42 in the nix
shell vs 2.40 on the host), toolchain, build profile and commit.
- .wolf/bugs/<id>.md: 500 records migrated from buglog.json; every field
verified to round-trip. They carry legacy: true and an explicit "not
recorded" where the old log had no such field; component derived from
file paths, severity from keywords (else unknown), fix_commits from
hashes in status_note/fix that git resolves (91 of 463 fixed).
- .wolf/buglog-archive.json: the 710 hook auto-detections, verbatim.
- .wolf/buglog.json is now an index generated from the records, keeping
the fields OpenWolf's hooks and `openwolf bug search` read.
- scripts/buglog.py rewritten: new (template + Environment collected from
the machine and --binary), check, status (refuses a status the record
doesn't support; fixed needs Root cause, Fix, Verification and
--commit hashes git resolves), note, recur, set, show, list, triage,
env, index. 29 unittest cases in scripts/tests/test_buglog.py.
- scripts/git-hooks/pre-commit runs `check --staged`: incomplete staged
records, a legacy record hand-changed to fixed without the fix-time
sections, a new record claiming legacy: true, or a stale index refuse
the commit.
- scripts/gitea-sync.py reads the records: issue body = the record's
sections plus linked fix commits (origin remote, GITEA_COMMIT_REPO to
override), and a body hash so an issue's text is refreshed when the
record changes.
- bug-1866 rewritten to the full standard as the worked example.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
38 lines
9.5 KiB
Markdown
38 lines
9.5 KiB
Markdown
---
|
|
id: "bug-1435"
|
|
status: "fixed"
|
|
status_updated: "2026-09-24"
|
|
status_note: ""
|
|
component: "controller"
|
|
severity: "unknown"
|
|
timestamp: "2026-07-12T04:45:15Z"
|
|
last_seen: "2026-09-19T09:00:00Z"
|
|
occurrences: 1
|
|
files: ["src/controller/ha.c (raft_state_t entry points)", "src/controller/ha.h (new raft_lock field)", "src/controller/cluster.c (raft_on_vote_request/raft_on_pre_vote_request call sites)"]
|
|
tags: ["ha", "raft", "raft-drive-async", "data-race", "raft_state_t", "vote-reply", "election", "verify_no_loss", "xce-test-ha", "E_XCE_STANDBY", "concurrency", "peer_ctrl_dispatch_to_pool"]
|
|
related: ["bug-608", "bug-1197", "bug-1198", "bug-1417", "bug-652", "bug-1282"]
|
|
legacy: true
|
|
---
|
|
|
|
# bug-1435: 40-round sequential /xce-test-ha FAIL at round 36/40: verify_no_loss reported 0/111 jobs confirmed…
|
|
|
|
## Description
|
|
40-round sequential /xce-test-ha FAIL at round 36/40: verify_no_loss reported 0/111 jobs confirmed after 3 attempts; xce_joblist client call returned E_XCE_STANDBY (10014) against freshly-elected primary ctrl-1 (term=41) moments after wait-primary succeeded on the same session
|
|
|
|
## Environment
|
|
_Not recorded (migrated from buglog.json)._
|
|
|
|
## Reproduction
|
|
_Not recorded (migrated from buglog.json)._
|
|
|
|
## Root cause
|
|
ROOT-CAUSED (2026-07-12, static analysis + full call-graph trace, not live-reproduced under a debugger due to timing rarity -- see confidence note in fix). ha_dispatch_gate's CTRL_STANDBY branch is the ONLY production site that can return -XCE_ERR_STANDBY for a GET/joblist request (confirmed by exhaustive read of ha.c:3699-3865); under CTRL_PRIMARY, OPCode_get is unconditionally allowed regardless of quorum/fence state. So the answering node's ha->role was genuinely CTRL_STANDBY at the moment ha_dispatch_gate ran -- this was NOT a client-side discovery/retry-budget problem (ruled out: XCECLI_FAILOVER_CALL's retry loop -- src/lib/client_failover.c -- correctly retries E_XCE_STANDBY up to max_retries=20 with zero backoff via XCE_FO_RETRY_NOW, and its final surfaced rc staying exactly -E_XCE_STANDBY on budget exhaustion is the DOCUMENTED behavior for a RETRY_NOW-classified cause, not a symptom of a broken retry loop). The MISSING INFO 'xcecli failover: attempt N' log lines (zero matches across the whole 40-round run) are explained by the fact that libxce's wait-primary REPL command (cmd_wait_primary, testsuite/test.c) does its OWN silent primary-discovery/redirect-follow loop (xcecli_ctrlstatus_primary) that never calls the shared xcecli_retry_next/INFO-logging path -- once wait-primary hands off a live, correctly-connected-to-primary ctx, subsequent ops normally succeed on attempt 0 with nothing to log; this is a red herring, not a clue to a client bug. The REAL mechanism is a genuine, unsynchronized DATA RACE in raft_state_t (the embedded Raft consensus struct, ha->raft): raft_on_vote_reply/raft_on_vote_request/raft_on_pre_vote_reply/raft_on_pre_vote_request/raft_begin_pre_vote/raft_start_election/raft_check_and_start_election/raft_on_election_timeout/raft_on_higher_term_observed all read+mutate raft_state_t's PLAIN (non-atomic) fields (term, role, votes_granted, replies_received, election_decided, vote_replies[], pre_vote_* tally) with ZERO locking -- the raft library (src/lib/raft/raft.c) is written assuming a single-threaded/serialized caller (the classic Raft single-event-loop model). But the raft-drive-async feature (peer_ctrl_dispatch_to_pool in ha.c, default ON via g_drive_async_peerctrl_dispatch_enabled=1) dispatches each peer-control message (including RequestVoteReply from each individual voter) as an independent VTASK_LIVENESS vtask onto the shared vtaskmgr pool; peer_ctrl_dispatch_to_pool's own per-endpoint serialization (bind_vtask) only orders messages arriving on the SAME endpoint -- it does NOT serialize messages from DIFFERENT peers' endpoints against each other. So two vote replies from two different voters (e.g. ctrl-2 grants, ctrl-3 grants or denies) for the SAME election CAN be processed concurrently on two different pool worker threads, both calling raft_on_vote_reply(&ha->raft, ...) on the shared struct with no lock. Traced exact race for the observed symptom: worker A processes voter1's grant, reaches quorum (votes_granted=2>=2), sets election_decided=1, fires on_become_leader -> raft_cb_become_leader -> ha->role=CTRL_PRIMARY (term=41, matching ctrl-1's own logs exactly). Worker B, running concurrently (no synchronization), processes voter2's reply and -- racing on the unprotected votes_granted/replies_received/election_decided reads -- can independently satisfy raft_on_vote_reply's Step 6 'all replied, no quorum' branch (replies_received==n_peers-1 && votes_granted<quorum, read before worker A's increment is visible to it) and fire on_become_follower -> raft_cb_become_follower -> ha->role=CTRL_STANDBY for the SAME term, an instant after promotion, with no further election and no fresh log line calling out a 'demotion' that anyone was specifically looking for. Every subsequent client GET request then correctly, faithfully hits ha_dispatch_gate's CTRL_STANDBY branch and is rejected with -XCE_ERR_STANDBY -- explaining why the failure PERSISTED across all retries/attempts across multiple seconds (nothing else ever corrects role back to PRIMARY once flipped -- no bug, no external trigger, it just stays CTRL_STANDBY). This also explains why the bug needed ~36 rounds to surface once: it requires two vote replies to genuinely overlap in processing time on two different pool workers, a narrow, load/scheduling-dependent timing window. Verified raft-drive-async is on by default (g_drive_async_peerctrl_dispatch_enabled=1) and confirmed via full call-graph trace that raft_cb_become_leader/raft_cb_become_follower (the synchronously-fired callbacks) never themselves call back into another raft_* entry point (no re-entrancy via the callbacks), and that no existing ha->lock-held critical section ever calls into a raft_* function (so lock-order is always raft_lock-then-ha->lock, never reversed -- no ABBA risk versus the two pre-existing lock-order bugs in this exact area, bug-652 and bug-1282). CONFIDENCE: HIGH on mechanism (every piece of evidence in the original investigation -- ctrl-1's own healthy term=41 promotion log, zero ASAN errors, commit_advanced continuing for seconds after, the missing xcecli-failover logs, every retry returning the SAME E_XCE_STANDBY class -- is fully and specifically explained by this race, with no residual unexplained facts), but NOT live-reproduced under a debugger/instrumented build in this session (the race is timing-rare, needed ~36 rounds to surface once in the original soak) -- this is a well-evidenced, fully-traced static diagnosis, not a confirmed-via-repro one.
|
|
|
|
## Fix
|
|
Added a new dedicated ha_state_t field `raft_lock` (pthread_mutex_t, PTHREAD_MUTEX_RECURSIVE -- src/controller/ha.h) serializing every mutating/reading entry point into raft_state_t on the election/vote path: raft_on_vote_reply (ha.c vote_reply_dispatch), raft_on_vote_request + raft_on_pre_vote_request (cluster.c, inbound vote RPCs), raft_on_pre_vote_reply + raft_begin_pre_vote (ha.c pre-vote dispatch), raft_start_election + raft_check_and_start_election x3 call sites (ha.c election-start paths, inline and vtask-dispatched), raft_on_election_timeout (ha.c delaymgr callback), and raft_on_higher_term_observed x2 (ha.c heartbeat-reply and WAL-NACK term-discovery paths). Initialized/destroyed in ha_init/ha_fini. Deliberately RECURSIVE (not a plain mutex): raft_on_pre_vote_reply's WON branch and raft_begin_pre_vote's single-node-win branch synchronously call ha_enter_real_election -> ha_start_election_async -> raft_start_election on the SAME thread within the same call chain (a legitimate same-thread nesting, not a race) -- a plain non-recursive mutex would self-deadlock on that path exactly like the precedent bug-652 (ha->lock self-deadlock from synchronous re-entry). Deliberately scoped to the ELECTION/VOTE path only, NOT the AE/commit-replication path (raft_log_append, raft_on_append_entries_request/reply, raft_advance_commit) -- ha_primary_log_append/raft_log_append is reachable from concurrent client-write vtasks with no visible lock either, which may be a SEPARATE, analogous concurrency gap, but touching the write/durability path carries much higher regression risk and wasn't the demonstrated mechanism for this specific symptom; flagging it as a follow-up investigation, not silently ignoring it. Verified no lock-order regression: no existing ha->lock-held critical section calls into any raft_* function (grepped and read all 9 ha->lock call sites), so raft_lock is always acquired before, never after, ha->lock -- consistent single order, no ABBA (cf. bug-1282, bug-652). Build: nix develop ./src -- bash src/tools/xce-build.sh controller -- clean compile, zero new warnings (3 pre-existing unrelated warnings in ha.c/cluster.c confirmed via git diff hunk-range check to be outside every edited region), controller_unit_test meson suite Ok:1 Fail:0 in 32.38s with no hang/timeout (a hang would have surfaced a recursive-mutex misuse or missed ha_init path, per the bug-1224/bug-1429 precedent of dispatch-related test hangs in this exact area -- none occurred). NOT live-reproduced/soak-validated in this session (explicitly deferred by the user to a separate follow-up 40-round /xce-test-ha run) -- this is a well-evidenced, carefully-scoped static fix for a data race, not a repro-confirmed one; flagged honestly as best-effort-but-high-confidence rather than 100%-certain.
|
|
|
|
## Verification
|
|
_Not recorded (migrated from buglog.json)._
|
|
|
|
## References
|
|
- Related: bug-608, bug-1197, bug-1198, bug-1417, bug-652, bug-1282
|