openreceive-rails 0.4.10 → 0.4.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 624dd853dd3e316cd20bacb9a6c8f669ddb61558c6540d05da6000cc71d3efd2
-  data.tar.gz: b2acac5e32343925c1d6974cb7ee1451f4ea34335aec82921feebe05c33b90e8
+  metadata.gz: c17784f21721177e139d27349d7fa0367f2e6f90cce005e5dd61906ac5fae96a
+  data.tar.gz: f285c9fb57805628956740699f078115672f1485916784fbc2e4b6d8738b1578
 SHA512:
-  metadata.gz: 86971442440a6ce6dc19c7f884ebac554e0a28999976ad6761b3843fbe1dee6daa9bb03087863e14f651d644140be222dace9e84df6b37de823af5b4151c71a0
-  data.tar.gz: 1cf150cc363e76166a216f830a550a42d4615f0c99f287f9e9d69dc537fd60754e1fc26e3a1558a584b33056c88a49ccfe23d420ab565fdb4b4a14c65f3cfbeb
+  metadata.gz: 16634ea35e356230c34b4da9ecf58bc8c089835d1b919692e41ddda40ef127fbddc23e5aa3090ba62835f90ba23b393d562a9006df015cbb5a84c2c16ec0ee35
+  data.tar.gz: 5d70f67f044bfa1003fb963da3e3e8ffe620f27517662d8fd1199ae0972906c7fcc1172196b8b8704d9c4354485700e2732dcf7d99ea818772cb19999a045296

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.4.13 - 2026-10-01
+
+Reconciliation no longer livelocks on a slow wallet. A wallet-history page
+still in flight at the scan deadline (`Timeout` in the nwc-ruby adapter) failed
+the whole pass and dropped its resume offset, so a long walk restarted at
+offset 0 on every pass and logged `reconciliation failed (will retry):
+OpenReceive::Server::WalletFailureError: execution expired` forever. A cut page
+now ends the slice and keeps the completed pages' progress. A first page cut
+before the wallet answers still fails the pass. Host-clock attempts (legacy
+rows without `created_at_source`) get their own full-history cohort instead of
+widening the window of every wallet-timed attempt pending with them. The gate
+floor rises from 2 s to 3 s (`OpenReceive::MIN_RECONCILE_INTERVAL_SECONDS`).
+
+## 0.4.12 - 2026-10-01
+
+Release in lockstep with the 0.4.12 checkout fixes. The Rails Buy a Button
+demo's checkout now returns to the method grid on every "Switch payment
+method" click. No Rails engine API change.
+
+## 0.4.11 - 2026-09-21
+
+Reconciliation progress is durable and bounded. A capped wallet walk now
+stores its window — attempt identities, page offset, view and page
+fingerprint — in `OpenReceive::ReconcileScan`, so the next request or worker
+resumes where the last one stopped instead of restarting the history, and a
+resumed scan is never treated as proof that a payment is absent. Scans carry
+a deadline into the wallet request, and fulfillment commits in the same
+transaction as settlement.
+
+The default repository maps an unexpected persistence failure to
+`HostPersistenceError` (retryable 503, payer instructions withheld) rather
+than letting it surface as an unrelated error.
+
 ## 0.4.10 - 2026-09-16
 
 Release alongside the packaged checkout fix that shows one amount to send

data/README.md

@@ -98,3 +98,36 @@ overrides it. Keep ordinary settings such as `config.price_currencies` in
 - Changelog: [CHANGELOG.md](CHANGELOG.md)
 
 MIT license.
+
+### Reconciliation upgrades and operator recovery
+
+Explicit jobs, the notifications worker, notification fallback and mounted routes
+share the durable lease/CAS gate and bounded scheduler. Disabling
+`opportunistic_reconcile` disables request triggers only. Stop old application and
+worker processes before deploying this scheduler contract, then start the updated
+processes together. Resumed history slices discover positive wallet finality but
+never prove absence; unpaid dense histories stay pending until a fresh complete
+covering scan fits the budget. Deposit countdown/reuse expiry remains separate
+from the saved Lightning invoice's settlement deadline.
+
+`OpenReceivePayment.maintenance_candidates(after: cursor, limit: 100)` is a
+read-only report with `candidates`, `next_cursor` and `scanned`. An operator can
+review a selected candidate and call
+`OpenReceivePayment.requeue_reviewed_attempt!(candidate, decision_id: "ticket-42")`.
+The model checks the unchanged row under its reference lock, records the decision
+in `openreceive_meta`, and requeues it without granting fulfillment. The ordinary
+gated reconciler must still discover wallet finality. Settled rows remain
+immutable, and genuine sibling payments never grant a second entitlement.
+Candidates distinguish early swap-deadline closure from ordinary operator
+attention; reports contain no swap credentials. Follow the
+[coordinated upgrade guide](https://github.com/OpenReceive/openreceive/blob/master/docs/guides/payment-safety-upgrade.md).
+
+MySQL repository operations require an outermost transaction; wrapping them in
+an ambient ActiveRecord transaction is rejected before taking the named lock.
+
+Fulfillment database writes and a host outbox belong in `on_paid`; a callback can
+run again after rollback. External jobs need their own durable idempotency.
+Storage-free `openreceive-server` handlers can call `on_paid` on every settled
+poll, so advanced hosts own the conditional write/outbox. A raw create hook
+refusal returns 409 with instructions withheld; repository infrastructure failures
+remain retryable 503.

data/app/models/open_receive_meta.rb

@@ -68,29 +68,58 @@ class OpenReceiveMeta < ActiveRecord::Base
     end
   end
 
-  # Claim the durable global reconcile gate. Returns true when this caller may
-  # run a wallet scan now; false (gate_busy) when another worker scanned within
-  # interval_seconds. The winner is identified by reading back its own token —
-  # the portable equivalent of an affected-row count, matching the JS
-  # claimReconcileGate. A failed scan leaves claimed_at in place on purpose —
-  # the next interval retries without a stampede.
-  def self.claim_reconcile_gate(now:, interval_seconds:)
+  # The durable global scan gate returns a token/scheduler claim or nil.
+  # Checkpoints require that token and an unexpired lease; failed scans retain
+  # the interval and pre-scan queue so another worker can retry fairly.
+  def self.claim_reconcile_gate(now:, interval_seconds:, lease_seconds: 10)
     assert_supported_schema!
-    claim = JSON.generate("claimed_at" => Integer(now), "token" => SecureRandom.uuid)
+    now = Integer(now)
     CAS_RETRIES.times do
       row = find_by(key: RECONCILE_GATE_KEY)
-      if row.nil?
-        cas(RECONCILE_GATE_KEY, claim, nil)
-      else
-        claimed_at = parse_claimed_at(row.value)
-        if claimed_at && fresh_timestamp?(Integer(now), claimed_at, Integer(interval_seconds))
-          return false
-        end
-        cas(RECONCILE_GATE_KEY, claim, row.rev)
-      end
-      return true if where(key: RECONCILE_GATE_KEY).pick(:value) == claim
+      current = parse_gate(row&.value)
+      claimed = current["claimed_at"]
+      return nil if claimed && fresh_timestamp?(now, claimed, interval_seconds)
+      return nil if current.fetch("lease_until", 0) > now && current.fetch("claimed_at", 0) <= now + 60
+
+      gate = {
+        "version" => 1, "claimed_at" => now, "token" => SecureRandom.uuid,
+        "lease_until" => now + lease_seconds, "interval_seconds" => interval_seconds,
+        "scheduler" => current.fetch("scheduler", { "cursor" => nil, "windows" => [] })
+      }
+      next unless cas(RECONCILE_GATE_KEY, JSON.generate(gate), row&.rev)
+
+      return { "token" => gate.fetch("token"), "scheduler" => gate.fetch("scheduler") }
     end
-    false
+    nil
+  end
+
+  def self.checkpoint_reconcile_gate(claim, scheduler, now:, release: false)
+    assert_supported_schema!
+    row = find_by(key: RECONCILE_GATE_KEY)
+    return false if row.nil?
+
+    gate = parse_gate(row.value)
+    return false unless gate["token"] == claim.fetch("token") && gate.fetch("lease_until", 0) > now
+
+    windows = scheduler.fetch("windows")
+    raise ArgumentError, "Reconciliation checkpoint exceeded bounded cohorts" if windows.length > 2 || windows.any? { |w| w.fetch("attempts").length > 200 }
+
+    gate["scheduler"] = scheduler
+    gate["lease_until"] = 0 if release
+    encoded = JSON.generate(gate)
+    raise ArgumentError, "Reconciliation checkpoint exceeded 128 KiB" if encoded.bytesize > 128 * 1024
+
+    cas(RECONCILE_GATE_KEY, encoded, row.rev)
+  end
+
+  def self.parse_gate(value)
+    gate = value.nil? ? {} : JSON.parse(value.to_s)
+    gate = {} unless gate.is_a?(Hash)
+    raise OpenReceive::ConfigurationError, "Unsupported reconciliation checkpoint version; upgrade OpenReceive." if gate.fetch("version", 0) > 1
+
+    gate["version"] == 1 ? gate : { "scheduler" => { "cursor" => nil, "windows" => [] } }
+  rescue JSON::ParserError
+    { "scheduler" => { "cursor" => nil, "windows" => [] } }
   end
 
   def self.stored_schema_version
@@ -113,13 +142,5 @@ class OpenReceiveMeta < ActiveRecord::Base
     age < window_seconds
   end
 
-  def self.parse_claimed_at(value)
-    parsed = JSON.parse(value.to_s)
-    claimed_at = parsed["claimed_at"]
-    claimed_at.is_a?(Numeric) ? Integer(claimed_at) : nil
-  rescue JSON::ParserError
-    nil
-  end
-
-  private_class_method :stored_schema_version, :fresh_timestamp?, :parse_claimed_at
+  private_class_method :stored_schema_version, :fresh_timestamp?
 end

data/app/models/open_receive_payment.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "digest"
+require "time"
 
 # Engine-owned payment attempts. The table lives in the host application's
 # database (the install generator emits the migration), but the schema, locking,
@@ -88,6 +89,10 @@ class OpenReceivePayment < ActiveRecord::Base
   # COMMIT — releasing inside the transaction would leave a window where a
   # second worker could commit against state this one has already read.
   def self.with_mysql_reference_lock(key)
+    if connection.transaction_open?
+      raise RuntimeError, "OpenReceive MySQL reference operations require an outermost transaction; ambient transactions cannot retain the connection-scoped reference lock."
+    end
+
     name = "openreceive:#{Digest::SHA256.hexdigest(key)[0, 40]}"
     acquired = connection.select_value(
       sanitize_sql_array(["SELECT GET_LOCK(?, ?)", name, MYSQL_LOCK_TIMEOUT_SECONDS])
@@ -218,7 +223,7 @@ class OpenReceivePayment < ActiveRecord::Base
 
     with_reference_lock(payment.reference) do
       payment.reload
-      return payment if payment.status == "settled"
+      return payment unless payment.status == "pending"
 
       first_for_order = !where(reference: payment.reference).settled.exists?
       payment.update!(
@@ -240,11 +245,16 @@ class OpenReceivePayment < ActiveRecord::Base
       raise ArgumentError, "invalid reconciliation status: #{status_text}"
     end
 
-    where(payment_hash: payment_hash.to_s.downcase, status: "pending").update_all(
-      status: status_text,
-      status_reason: reason,
-      updated_at: Time.at(Integer(observed_at)).utc
-    )
+    payment = find_by(payment_hash: payment_hash.to_s.downcase)
+    return if payment.nil?
+
+    with_reference_lock(payment.reference) do
+      where(payment_hash: payment.payment_hash, status: "pending").update_all(
+        status: status_text,
+        status_reason: reason,
+        updated_at: Time.at(Integer(observed_at)).utc
+      )
+    end
   end
 
   # Pending attempts for the reconciler's next wallet scan — oldest first, one
@@ -252,19 +262,103 @@ class OpenReceivePayment < ActiveRecord::Base
   # closest to their closure deadline are always covered, and a backlog drains
   # over several passes instead of widening one wallet scan window without
   # bound. Terminal rows never return.
-  def self.reconcilable_attempts
+  def self.reconcilable_attempts(after: nil, limit: OpenReceive::Server::RECONCILE_BATCH_SIZE)
     OpenReceiveMeta.assert_supported_schema!
-    pending.order(created_at: :asc)
-           .limit(OpenReceive::Server::RECONCILE_BATCH_SIZE)
-           .pluck(:payment_hash, :created_at, :expires_at).map do |hash, created_at, expires_at|
+    query = pending.order(created_at: :asc, payment_hash: :asc)
+    if after
+      created = Time.at(after.fetch("created_at")).utc
+      query = query.where("created_at > ? OR (created_at = ? AND payment_hash > ?)", created, created, after.fetch("payment_hash"))
+    end
+    query.limit([limit, OpenReceive::Server::RECONCILE_BATCH_SIZE].min)
+         .pluck(:payment_hash, :created_at, :checkout_data).map do |hash, created_at, checkout|
       {
-        "payment_hash" => hash,
-        "created_at" => created_at.to_i,
-        "expires_at" => expires_at.to_i
+        "payment_hash" => hash, "created_at" => created_at.to_i,
+        "expires_at" => settlement_expires_at(checkout, hash),
+        "created_at_source" => checkout["created_at_source"] || checkout[:created_at_source] || "host"
       }
     end
   end
 
+  # Same reconciliation DTO for authenticated by-hash notification lookup.
+  def self.find_pending_attempt(payment_hash)
+    OpenReceiveMeta.assert_supported_schema!
+    row = pending.where(payment_hash: payment_hash.to_s.downcase).pick(:payment_hash, :created_at, :checkout_data)
+    return nil if row.nil?
+
+    hash, created_at, checkout = row
+    {
+      "payment_hash" => hash, "created_at" => created_at.to_i,
+      "expires_at" => settlement_expires_at(checkout, hash),
+      "created_at_source" => checkout["created_at_source"] || checkout[:created_at_source] || "host"
+    }
+  end
+
+  # Saved Lightning deadline, independent of the payer's deposit countdown.
+  def self.settlement_expires_at(checkout, payment_hash)
+    value = checkout[:expires_at] || checkout["expires_at"] || checkout[:expiresAt] || checkout["expiresAt"]
+    raise ArgumentError unless value.is_a?(Integer) || (value.is_a?(String) && value.match?(/\A[0-9]+\z/))
+
+    expiry = Integer(value)
+    raise ArgumentError if expiry <= 0
+
+    expiry
+  rescue TypeError, ArgumentError, NoMethodError
+    raise RuntimeError, "Corrupt checkout_data wallet expiry on openreceive payment attempt #{payment_hash}."
+  end
+
+  # Host-invoked dry-run report. Normal routes never read terminal repair candidates.
+  def self.maintenance_candidates(after: nil, limit: 100)
+    OpenReceiveMeta.assert_supported_schema!
+    limit = [[limit, 1].max, 1000].min
+    query = where(status: %w[attention expired])
+    if after
+      stamp = Time.iso8601(after.fetch("updated_at"))
+      query = query.where("updated_at > ? OR (updated_at = ? AND payment_hash > ?)", stamp, stamp, after.fetch("payment_hash"))
+    end
+    rows = query.order(:updated_at, :payment_hash).limit(limit).to_a
+    cursor = rows.length == limit ? { "updated_at" => rows.last.updated_at.utc.iso8601(6), "payment_hash" => rows.last.payment_hash } : nil
+    { "candidates" => rows.filter_map { |row| repair_candidate(row) }, "next_cursor" => cursor, "scanned" => rows.length }
+  end
+
+  def self.requeue_reviewed_attempt!(candidate, decision_id:)
+    OpenReceiveMeta.assert_supported_schema!
+    unless /\A[A-Za-z0-9._:-]{1,120}\z/.match?(decision_id.to_s)
+      raise ArgumentError, "decision_id must be a nonsecret operator ticket identifier."
+    end
+    payment = find_by(payment_hash: candidate.fetch("payment_hash"))
+    return false if payment.nil?
+
+    with_reference_lock(payment.reference) do
+      payment.reload
+      return false unless repair_candidate(payment) == candidate
+
+      audit_key = "repair:#{payment.payment_hash}:#{decision_id}"
+      return false if OpenReceiveMeta.exists?(key: audit_key)
+
+      audit = candidate.merge("decision_id" => decision_id, "requeued_at" => Time.now.to_i)
+      OpenReceiveMeta.create!(key: audit_key, value: JSON.generate(audit), rev: 0)
+      payment.update!(status: "pending", status_reason: "operator_requeued")
+      true
+    end
+  end
+
+  def self.repair_candidate(row)
+    return nil unless %w[attention expired].include?(row.status)
+
+    wallet_expiry = settlement_expires_at(row.checkout_data, row.payment_hash)
+    reason = row.status == "attention" ? "operator_attention" : nil
+    if row.swap_data.present? && %w[not_found_after_expiry no_finality_after_expiry unsettled_after_expiry].include?(row.status_reason) &&
+       wallet_expiry > row.expires_at.to_i && row.updated_at.to_i >= row.expires_at.to_i + 900 && row.updated_at.to_i < wallet_expiry + 900
+      reason = "early_deposit_deadline_closure"
+    end
+    return nil if reason.nil?
+
+    { "reference" => row.reference, "payment_hash" => row.payment_hash,
+      "status" => row.status, "status_reason" => row.status_reason,
+      "updated_at" => row.updated_at.utc.iso8601(6), "instruction_expires_at" => row.expires_at.to_i,
+      "wallet_expires_at" => wallet_expiry, "reason" => reason }
+  end
+
   def self.reusable?(payment, now = Time.current)
     payment.expires_at.to_i - now.to_i > REUSE_BUFFER_SECONDS
   end

data/lib/generators/openreceive/install/templates/initializer.rb

@@ -90,7 +90,7 @@ OpenReceive.configure do |config|
 
   # Settlement discovery is opportunistic by default: every engine request
   # first runs one reconcile pass through the durable openreceive_meta gate
-  # (shared by all Puma workers; min 2s between real wallet scans), so pending
+  # (shared by all Puma workers; min 3s between real wallet scans), so pending
   # attempts settle or close on any later OpenReceive call — no scheduled job
   # required. Set false only if a dedicated worker owns scanning.
   # config.opportunistic_reconcile = false

data/lib/openreceive/configuration.rb

@@ -81,7 +81,7 @@ module OpenReceive
       # durably gated reconcile pass when attempts are pending, so abandoned
       # checkouts settle on any later OpenReceive call with no scheduled job.
       # The openreceive_meta gate row is shared by every Puma worker/process on
-      # the host database (min 2s between real wallet scans, stretched by
+      # the host database (min 3s between real wallet scans, stretched by
       # invoice age). Set false to disable (e.g. when the optional
       # `bin/rails openreceive:notifications` worker owns scanning), or a Hash
       # with min_interval_seconds to tune.
@@ -359,6 +359,8 @@ module OpenReceive
           # 409 CONFLICT. Leaving AttemptConflict unwrapped lets request_handler
           # #commit treat it as infrastructure failure (retryable 503 persist).
           raise OpenReceive::Server::ConflictError, e.message
+        rescue StandardError
+          raise OpenReceive::Server::HostPersistenceError
         end
       end
     end

data/lib/openreceive/generated/fulfillment_note.rb

@@ -13,13 +13,22 @@ module OpenReceive
       "",
       "WHAT OPENRECEIVE GUARANTEES",
       "",
-      "Across every settlement path OpenReceive itself owns (wallet notifications,",
-      "the opportunistic reconcile pass, an explicit reconcile job), the settlement",
-      "hook runs AT MOST ONCE per reference. The library serializes on its own",
-      "`{{table}}` rows, decides the winner there, and runs your hook",
-      "inside that same transaction. A second payment to a second invoice for the",
-      "same order is still recorded - with `status_reason = 'duplicate_settlement'`",
-      "- but never fulfills a second time. You do not need to add a lock for this.",
+      "Repository-backed settlement paths (wallet notifications, gated reconciliation,",
+      "and explicit jobs) commit fulfillment for only the first settled attempt per",
+      "reference. The library locks its `{{table}}` rows, decides the winner,",
+      "and awaits your hook inside the same database transaction. A failure rolls",
+      "back payment and host writes together; the hook can run again on a retry.",
+      "A genuine second payment is still recorded with",
+      "`status_reason = 'duplicate_settlement'`, without another fulfillment.",
+      "",
+      "Write an entitlement or an outbox job through the supplied transaction. Email,",
+      "shipping APIs, and other external effects cannot commit atomically with it;",
+      "your outbox worker must use durable idempotency for external delivery.",
+      "A best-effort after-paid callback may be lost after commit and is not an outbox.",
+      "",
+      "Raw storage-free handlers do not provide this transaction: their on_paid hook",
+      "may run on every settled poll. Those hosts own the durable conditional write",
+      "or outbox themselves; process-local deduplication does not replace it.",
       "",
       "That makes the reference the unit of fulfillment: give every payable order",
       "its own reference, created before checkout, kept across retries, and never",
@@ -51,7 +60,7 @@ module OpenReceive
       "conditional UPDATE, take a row lock for the duration instead:",
       "",
       "  SELECT * FROM orders WHERE id = :reference FOR UPDATE;  -- postgres/mysql",
-      "  -- ...check state, ship, write the new state, all before COMMIT.",
+      "  -- ...check state, grant entitlement/enqueue work, all before COMMIT.",
       "",
       "Run either one inside the transaction OpenReceive hands your settlement",
       "hook, so the order transition and the payment record commit together.",

data/lib/openreceive/rails/version.rb

@@ -5,6 +5,6 @@ module OpenReceive
   # top-level `::Rails` framework constant — engine code always references the framework as
   # `::Rails` to avoid shadowing.
   module Rails
-    VERSION = "0.4.10"
+    VERSION = "0.4.13"
   end
 end