enhance rollback query with range support

Merged
AJ
4mo ago
+608-173

Why

When a merge fails partway through, everything it already wrote to the default branch has to be reversed — the bulk graph merge and any schema-migration collateral. The existing rollback couldn't fully do that: it matched edges at one exact timestamp and restored metadata only for a node-UUID list held in memory on the DiffMerger instance. That made it blind to migration collateral for post-migration failures, a silent no-op when the merge crashed before the UUID discovery step, and unusable out-of-process — a restarted worker has no UUID list, so the upcoming infrahub recover could never share it.

Goal: one rollback mechanism, keyed only on (destination branch, merge_started_at), that reverses every write of the merge window uniformly and restores vertex updated_at/updated_by metadata from its snapshots — usable identically by the in-process failure path today and by out-of-process recovery in the next PR.

Why this is safe: the write-block shipped in the detection PR closes the default branch to client writes for the whole merge window, so everything stamped on the destination branch at-or-after merge_started_at is provably the merge's own work. The range rollback is that invariant applied in reverse. (This PR also tightens the invariant: the write-protection key is now published before the merge timestamp is stamped, so a write that slips in ahead of the block can never fall inside the rollback range.)

Non-goals (follow-ups):

  • recovery entry points — MergeFailureIdentifier.recover() and the infrahub recover CLI.
  • range indexes on edge from/to + node updated_at.
  • Schema migrations co-writing previous_updated_at/by.

This is the rollback core of IFC-2566 (reset the app to its pre-merge state). It does not close IFC-2566. That still requires the operator-facing recovery command.

What changed

Behavioral changes (what you'll observe differently):

  • A failed merge now rolls back everything with a timestamp on or after the time of the merge. All of the changes during a merge should have included the same timestamp, but using a >= range ensures that nothing is missed, such as changes from asynchronous tasks run during the merge.
  • The destination branch's schema_changed_at/schema_hash are restored literally to their pre-merge values on rollback. Previously they were recomputed, which stamped schema_changed_at with the rollback time. The same bug is fixed in SchemaUpdateCoordinator's failure path.
  • The rollback is idempotent and needs no in-memory state, so a re-run (or a post-restart recovery run) is safe.

Internals:

  • RollbackQuery rewritten: per-edge-type subqueries over all 8 DatabaseEdgeTypes (relationship indexes are per-type; a label-less match uses none), with an explicit RollbackScope — AT_TIMESTAMP for unified-timestamp callers whose branch is not write-blocked (other writers' later writes must survive), SINCE_TIMESTAMP for the merge window. restore_metadata is validated to the default/global branches only — vertex metadata properties exist nowhere else.
  • The metadata restore selects the vertices adjacent to reverted edges plus the owner Node one hop up via HAS_ATTRIBUTE/IS_RELATED (a value change reverts edges only on the Attribute vertex, while the merge metadata bump also stamps the owning Node), filtered by updated_at inside the window.
  • DiffMerger.rollback(merge_started_at) runs the range query with no UUID list; the UUID-scoped rollback, its _affected_node_uuids instance state, and GraphMerger.rollback() are deleted. A _merge_started guard keeps routine pre-write failures (unresolved conflicts, constraint violations) from paying for a full range scan.
  • MergeRollbackHandler gets its collaborators by constructor injection (both branches, the diff merger, the schema manager) and receives the captured pre-merge state as a frozen PreMergeState.
  • The orchestrator publishes the write-block key first, then stamps merge_at, then captures PreMergeState.

What stayed the same: the healthy-merge happy path; no database migration; the coordinator's rollback semantics on user branches (rebase, branch schema loads).

Suggested review order

  1. backend/infrahub/core/query/rollback.py — the range query itself: scope modes, per-edge-type phases, orphan cleanup, metadata-restore phase.
  2. backend/infrahub/core/diff/merger/merger.py — the new rollback entry and the removal of the UUID instance state.
  3. backend/infrahub/core/merge/ (rollback_handler.py, orchestrator.py, builder.py, graph_merger.py) — the unified in-process path, PreMergeState, and the key-before-timestamp reorder.
  4. backend/infrahub/core/schema/update_coordinator.py — exact-timestamp scope + literal hash/changed-at restore.
  5. Tests — backend/tests/component/core/diff/query/test_rollback.py (new), backend/tests/integration/diff/test_merge_rollback.py (extended), mechanical keyword updates across the merge component tests.

Impact & rollout

  • Backward compatibility: purely internal — no schema, API, enum, or config change; no migration.
  • Performance: the range query runs only on merge-failure/recovery paths. Real performance testing will come later. Depending on how it goes, changes to the query or indexes on certain properties might be required.
  • ⚠️ Known gap until IFC-2716: schema migrations bump vertex updated_at/by without writing previous_* snapshots, so migration-collateral vertices of a failed merge restore to an empty value rather than their true pre-merge metadata. The structural revert is complete either way; the metadata co-write lands with IFC-2716.
  • Deployment notes: safe to deploy; behavior changes only manifest when a merge fails.

Checklist

  • Tests added/updated
  • Changelog entry — intentionally omitted; folded into the infrahub recover PR's changelog once the operator-facing command lands
  • External docs — n/a (no user-facing surface changed)
  • Internal .md docs updated (dev/specs/ifc-2437-merge-failure-recovery/* task tracking)
  • I have reviewed AI generated content

Summary by cubic

Adds a range-based rollback with timestamp scopes and optional metadata restore, and unifies merge rollback to use it. Improves merge failure recovery for IFC-2566 and correctly restores branch schema_hash and schema_changed_at.

  • New Features

    • Rewrote RollbackQuery with RollbackScope.AT_TIMESTAMP and RollbackScope.SINCE_TIMESTAMP, per-edge-type phases, and orphan cleanup.
    • Optional updated_at/by restore driven by edges + owning Node, allowed only on default/global branches; idempotent and validated.
    • DiffMerger.rollback(merge_started_at) runs a SINCE range with metadata restore; orchestrator publishes the merge write-block before stamping merge_at and cleans it up if setup fails.
  • Refactors

    • Unified in-process merge rollback onto DiffMerger.rollback(merge_started_at); removed GraphMerger.rollback and the UUID-scoped paths.
    • MergeRollbackHandler now restores the destination schema content and literally resets schema_hash/schema_changed_at via PreMergeState; reopens the source branch and clears the write block.
    • SchemaUpdateCoordinator keeps exact-timestamp rollback (no metadata restore) and now restores schema_hash/schema_changed_at literally on failure.