virgodb 0.4.8-x86_64-linux-gnu → 0.5.0-x86_64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d126a72fa57e28991c642bd995b952c81df1f024e51291f8a880f63913f5483
-  data.tar.gz: 48682c56e3f09417b8e241909edf65ae2519a07e0c62c27813aee63164c3bef1
+  metadata.gz: 9eeffeb389afab6ec06fbb371c526a2191c7422892a82d41d4c5890d70f136d7
+  data.tar.gz: c9410d12cb71225253f2610b01658181204dbfc71bdedf944d0e8824610fed93
 SHA512:
-  metadata.gz: 57912dbb519d7d1c62e13ff1db65b0394f2da3a1013caa6c906aa7ec4c09892d6d029d51deaba9de5a6a5f9217c867f90b6a9a427b971e0fc0a056f6d586a59b
-  data.tar.gz: e67f09ae131c4d5d35bbe3f505a79107a0136578b00345d109296b022911d3d4e6b2c843b894ac1916e85e70e5591fe16469743ddc1a8302c26892a356f49487
+  metadata.gz: e8536425d8f46324976627c7fef51a137dc7911d226ec4c9703d5db0935f1834217123b7f85d2f21b0392a1e463324b19d037aa384672b0af675311fb5c0f820
+  data.tar.gz: 394df85ea9b968c880ea7d81babdb8c4914afe65cc10f7e5ce137906a278bfa4fbbf814ef3d5095034e8dfdee53ec84b2f98e2515a9636d00adf7b44e38e9545

data/lib/virgodb/manifest_quiesce.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Virgodb
+  # Raised by `Virgodb.with_manifest_quiesced` when a table's maintenance
+  # lease is still held by someone else (real background maintenance, or a
+  # concurrent quiesce attempt) when `lease_wait_timeout` runs out.
+  class LeaseUnavailable < StandardError; end
+
+  class << self
+    # Claims EVERY `[manifest_path, table_name]` pair in `targets`'
+    # maintenance lease (the SAME mutual exclusion the real background
+    # maintenance thread already uses against itself across processes), so
+    # `holder` gets exclusive access to every manifest file involved for as
+    # long as the block runs, then releases every claimed lease afterward
+    # -- whether the block succeeds or raises.
+    #
+    # Takes a `[manifest_path, table_name]` pair per target, not one shared
+    # `manifest_path` plus a list of table names -- deliberately, even
+    # though every target sharing one physical file (this project's own
+    # real production topology) is the common case. A caller with tables
+    # split across separate manifest files (a topology this gem already
+    # supports -- see `Registry.override_manifest_path!`-style per-table
+    # overrides, real in this project's own test suite) needs each table's
+    # lease claimed against its OWN file, not all of them against
+    # whichever one happens to be listed first -- collapsing to one shared
+    # path would silently claim/release the wrong table's lease against
+    # the wrong file for every target after the first.
+    #
+    # Deliberately still per-table leases underneath, not a genuine
+    # single manifest-scoped lease: the real maintenance thread's own
+    # compaction/vacuum/integrity-check only ever checks the per-table
+    # lease, and a brand-new separate file-level lock nothing else looks at
+    # would protect nothing. Collapsing the underlying lease itself to
+    # one-per-file would also serialize every table's maintenance behind a
+    # single lock, regressing the deliberate "tables' maintenance runs
+    # independently" property `Manifest::try_claim_maintenance_lease`'s own
+    # doc comment describes.
+    #
+    # Waits up to `lease_wait_timeout` seconds (polling every
+    # `lease_poll_interval` seconds) for a lease real maintenance currently
+    # holds; raises `LeaseUnavailable` if one never frees up in time. The
+    # final `ensure` releases every table unconditionally, not just the
+    # ones this call actually reached before raising -- safe because
+    # `release_maintenance_lease` is a no-op on a lease this holder never
+    # held (see that method's own doc comment), so this needs no separate
+    # partial-rollback bookkeeping.
+    #
+    # `renewal_interval` (seconds, optional): if given, a background thread
+    # re-extends every claimed lease this often for as long as the block
+    # runs, instead of trusting the single fixed `lease_duration_secs`
+    # grant from the initial claim to always be enough -- needed for a
+    # caller whose actual work (e.g. a slow first-ever backup upload with
+    # no dedup baseline yet) could genuinely outlive one fixed grant and
+    # free real maintenance to start compacting/vacuuming mid-work. Uses a
+    # background `Thread` rather than checking elapsed time inline, since
+    # the caller's own slow work (e.g. a blocking shellout) has no natural
+    # checkpoint to interleave a renewal call into; `Thread#kill` in the
+    # `ensure` is deliberately not a graceful join -- a lease renewal is
+    # just an independent, atomic single-row update per table, nothing here
+    # has multi-step state a mid-flight kill could corrupt. Omit (the
+    # default) when the block's own work is guaranteed to finish well
+    # within `lease_duration_secs` on its own.
+    #
+    # Extracted here (not left to live per-host-app) because this exact
+    # "claim every table sharing a manifest, do work, release every table"
+    # dance has no host-app-specific content in it at all -- any embedder
+    # needing exclusive access to a shared manifest for an external
+    # operation (a backup tool, a manual admin task, anything else) needs
+    # the identical coordination, and every independent reimplementation of
+    # it is a real chance for the per-table lease and whatever whole-file
+    # operation it's meant to protect to drift out of sync (see this
+    # project's own README, the 2026-09 incremental_vacuum incident, for
+    # exactly that failure shape once).
+    def with_manifest_quiesced(targets:, holder:, lease_duration_secs:, lease_wait_timeout:, lease_poll_interval:, renewal_interval: nil)
+      holder = holder.to_s
+      targets.each { |manifest_path, table_name| claim_lease!(manifest_path, table_name, holder: holder, lease_duration_secs: lease_duration_secs, lease_wait_timeout: lease_wait_timeout, lease_poll_interval: lease_poll_interval) }
+
+      if renewal_interval
+        with_lease_renewal(targets, holder: holder, lease_duration_secs: lease_duration_secs, renewal_interval: renewal_interval) { yield }
+      else
+        yield
+      end
+    ensure
+      targets.each { |manifest_path, table_name| release_maintenance_lease(manifest_path, table_name, holder) }
+    end
+
+    private
+
+    def claim_lease!(manifest_path, table_name, holder:, lease_duration_secs:, lease_wait_timeout:, lease_poll_interval:)
+      deadline = Time.now + lease_wait_timeout
+      until claim_maintenance_lease(manifest_path, table_name, holder, lease_duration_secs)
+        if Time.now > deadline
+          raise LeaseUnavailable, "could not claim #{table_name}'s maintenance lease within #{lease_wait_timeout}s (still held by real maintenance)"
+        end
+
+        sleep lease_poll_interval
+      end
+    end
+
+    def with_lease_renewal(targets, holder:, lease_duration_secs:, renewal_interval:)
+      renewal_thread = Thread.new do
+        loop do
+          sleep renewal_interval
+          targets.each { |manifest_path, table_name| renew_maintenance_lease(manifest_path, table_name, holder, lease_duration_secs) }
+        end
+      end
+      yield
+    ensure
+      renewal_thread&.kill
+    end
+  end
+end

data/lib/virgodb/table.rb

@@ -120,6 +120,18 @@ module Virgodb
       Virgodb.integrity_check(@manifest_path)
     end
 
+    # Writes a complete, consistent snapshot of the manifest to dest_path
+    # via VACUUM INTO, through virgodb's own connection -- same "don't use
+    # a second connection type against this shared file" reasoning as
+    # integrity_check above, just for backup tooling instead of health
+    # checks. Manifest-scoped, not table-scoped. See
+    # Manifest::snapshot_into's own doc comment (crates/manifest/src/lib.rs)
+    # for what VACUUM INTO itself guarantees and its one real caller
+    # constraint (refuses to overwrite an existing dest_path).
+    def snapshot(dest_path)
+      Virgodb.snapshot(@manifest_path, dest_path)
+    end
+
     # Claims this table's maintenance lease as `holder` for the next
     # `lease_duration_secs` seconds, locking out the real maintenance
     # thread (its own claim attempts fail against an unexpired lease the

data/lib/virgodb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Virgodb
-  VERSION = "0.4.8"
+  VERSION = "0.5.0"
 end

data/lib/virgodb.rb

@@ -5,3 +5,4 @@ require "virgodb/virgodb_ruby"
 require "virgodb/time_helpers"
 require "virgodb/rows"
 require "virgodb/table"
+require "virgodb/manifest_quiesce"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: virgodb
 version: !ruby/object:Gem::Version
-  version: 0.4.8
+  version: 0.5.0
 platform: x86_64-linux-gnu
 authors:
 - virgodb
@@ -21,6 +21,7 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - lib/virgodb.rb
+- lib/virgodb/manifest_quiesce.rb
 - lib/virgodb/rows.rb
 - lib/virgodb/table.rb
 - lib/virgodb/time_helpers.rb