openreceive-rails 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3709b7ea572da6d1a0a259c84f95ea3f5e41ec1fc7dc9dd067a8a77951bd0691
+  data.tar.gz: 0c42db53e3d8dff9c5796ebc53b15c87b02286c627250be6a2741327d3082403
+SHA512:
+  metadata.gz: '0930dafa248e3f22fbc2297fac22a8d14b09ed407c49c08f01cd5de48cb7213f49370644233a74efd45782432a1629a12439a312c4c074f1a9401dcc8ccda51d'
+  data.tar.gz: 2990f0db5d68c3b8a0fa4c1bace12eb7708f1961894d6bd444cdd593f259aead0249b28ba127e2cc246903ec4517c6f8944ae3a7cde14d4bf58ea6dd7fa65e1f

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.2.1 - 2026-08-24
+
+The Ruby gems release in lockstep with the npm workspace version. The full
+release narrative lives in the repository-root
+[CHANGELOG](https://github.com/openreceive/openreceive/blob/master/CHANGELOG.md);
+entries here are scoped to this gem.
+
+- Packaging only: `npm run release:gem:build` now names the built `.gem` with
+  the version RubyGems actually mints, so prerelease versions build and push.
+
+## 0.1.1 - 2026-08-18
+
+- First packaged release of `openreceive-rails`: the mountable engine, the
+  engine-owned `OpenReceivePayment` model and reconciliation, and the
+  `openreceive:install` generator.
+- `config.price_provider` defaults to the built-in live price feed, and swap
+  providers auto-build from `LSC_URI_PRIMARY`/`LSC_URI_BACKUP` — matching the
+  Node engine's `createOpenReceive` defaults.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenReceive contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,52 @@
+# openreceive-rails
+
+Mountable receive-only OpenReceive engine. The engine owns the
+`OpenReceivePayment` attempt model (statuses `pending`, `settled`, `expired`,
+`failed`, `attention`), its per-reference commit locking, settlement write-once, and
+the reconciliation state machine. The install generator mounts the routes and
+emits the initializer plus one migration creating both engine tables
+(`openreceive_payments` and the `openreceive_meta` reconcile gate):
+
+```sh
+bin/rails generate openreceive:install
+bin/rails db:migrate
+```
+
+The generated migration supports PostgreSQL, SQLite, and MySQL, and seeds the
+shared `schema_version`; on its first database touch the engine refuses to
+operate a database whose stored schema version is newer than the gem.
+
+The quickstart host contract is `config.authorize`, `config.amount_for` (the
+trusted price for a reference, or `nil` for a 404), and `config.on_paid` (run
+inside the settlement transaction, only for the first settled attempt for a reference). The generated
+initializer starts with the `OpenReceive::LOGGING_ON_PAID` placeholder, which
+only logs settlements — the engine warns every time your application boots
+until it is replaced.
+Hosts with a custom repository may instead configure `resolve_checkout` and
+`on_checkout_created` together as the advanced escape hatch. In production the
+engine builds the service (and its wallet preflight) eagerly when your
+application boots, so a missing `NWC_URI` or a spend-capable wallet stops the
+deploy instead of surfacing as checkout-time 500s.
+
+Settlement runs on the request path by default: every engine route runs one
+opportunistic reconcile pass, serialized across all Puma workers by that
+durable `openreceive_meta` gate (`config.opportunistic_reconcile` disables or
+tunes it). The optional
+`bin/rails openreceive:notifications` worker listens for wallet notifications
+and reconciles periodically; `OpenReceive::ReconcileJob` and
+`bin/rails openreceive:reconcile` remain one-shot primitives. Closure of an
+unpaid attempt requires a successful wallet scan at or after expiry plus the
+shared grace window — a local clock alone never closes a row.
+
+The engine inherits the host's `protect_from_forgery`: render `csrf_meta_tags`
+and the checkout client sends `X-CSRF-Token` from it. Independently of that,
+the shared handler refuses non-JSON bodies (415) and `Sec-Fetch-Site:
+cross-site` requests (403) before `authorize` runs.
+
+Because the engine cannot see fulfillment that happens outside it,
+`config.on_paid` must be idempotent if any other path can also fulfill an
+order — the generated initializer shows the guarded transition. The receive-only wallet URI loads from `ENV["NWC_URI"]`; your
+application refuses to start when the connection advertises spend methods unless
+`config.allow_spend_capable_wallet` or `OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC`
+overrides it. Keep ordinary settings such as `config.price_currencies` in
+`config/initializers/openreceive.rb`.

data/app/controllers/openreceive/application_controller.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module OpenReceive
+  # Base controller for the engine. It inherits DYNAMICALLY from the configured
+  # `config.parent_controller` (default "ActionController::Base"; a host sets "ApplicationController")
+  # so the engine automatically gets the host's authentication and current_user.
+  #
+  # Set `parent_controller` in a normal initializer — not `after_initialize`. Production
+  # eager-loads this class before after_initialize runs, so a late parent_controller change
+  # is ignored and the default ActionController::Base CSRF `:exception` strategy remains.
+  #
+  # Every action is a thin adapter: it converts the Rails request into the inputs the shared
+  # OpenReceive::Server::RequestHandler needs, delegates, and renders the returned
+  # [status, headers, body] triple. Controllers and the Rack app therefore cannot drift — the
+  # routing/authorize/error semantics live in one place (the server gem's RequestHandler).
+  class ApplicationController < OpenReceive.config.parent_controller.constantize
+    # The host's forgery protection is inherited, not skipped: whatever
+    # `protect_from_forgery` the parent controller configures applies to the
+    # engine's routes exactly as it applies to the host's own. The shipped
+    # browser client sends `X-CSRF-Token` from `<meta name="csrf-token">`
+    # whenever the page renders `csrf_meta_tags`, so a Rails host needs no
+    # extra wiring; API-only parents (ActionController::API) have no forgery
+    # protection, and the shared handler's JSON-only + same-site gates cover
+    # them. A failed check answers with the shared 403 error contract instead
+    # of the opaque 500 the StandardError rescue below would produce.
+
+    # Any PAYMENT call is a settlement trigger (mirrors the JS handler's
+    # dispatch): after the route matched and before its own work, run one
+    # durably gated reconcile pass. maybe_reconcile! never raises; a failed
+    # scan must not fail this request. payments/check consumes this pass
+    # result — exactly one gate claim per request. Host-only routes never
+    # auto-run this; hosts call OpenReceive.maybe_reconcile! from their own
+    # code instead.
+    #
+    # Unauthenticated GET /rates is deliberately EXEMPT (RatesController skips
+    # this filter, matching the JS handler's early return for route.kind
+    # "rates"): crawlers and health checks must not consume the wallet-scan
+    # budget.
+    around_action :openreceive_opportunistic_reconcile
+
+    # Any exception the thin adapter layer itself raises (body cap, render)
+    # still answers with the shared error contract instead of the host's HTML
+    # error page — the same last-resort rescue as Server::RackApp#call. The
+    # handler's error_response redacts unexpected exceptions and reports them
+    # through Rails.error before the opaque 500 goes on the wire.
+    rescue_from StandardError do |error|
+      openreceive_respond(openreceive_handler.error_response(error, openreceive_request_id))
+    end
+
+    rescue_from ActionController::InvalidAuthenticityToken do
+      forbidden = Server::ForbiddenError.new("Invalid or missing CSRF token.")
+      openreceive_respond(openreceive_handler.error_response(forbidden, openreceive_request_id))
+    end
+
+    private
+
+    def openreceive_opportunistic_reconcile
+      # The body cap runs FIRST, matching the JS handler's dispatch order: an
+      # anonymous oversized POST is refused without a database read, without
+      # claiming the reconcile gate, and without triggering a wallet scan. The
+      # read is memoized, so the action reuses it.
+      openreceive_raw_body
+      @openreceive_reconcile_pass = OpenReceive.maybe_reconcile!
+      yield
+    end
+
+    # The memoized shared request handler (Service + configured host callbacks).
+    def openreceive_handler
+      OpenReceive.config.request_handler
+    end
+
+    # Always server-generated (matches RackApp and JS): client-supplied
+    # X-Request-Id values are unvalidated content and are never reflected.
+    def openreceive_request_id
+      "req_#{SecureRandom.uuid}"
+    end
+
+    # The raw JSON request body string (Server::RequestHandler parses it so the parse/error semantics
+    # match the Rack app exactly rather than relying on Rails' params coercion). Capped pre-auth,
+    # mirroring RackApp#read_body and the JS readJsonBody: an over-declared Content-Length is
+    # rejected before any read, and the read itself stops one byte past the cap so a chunked body
+    # can never stream unbounded input into memory.
+    def openreceive_raw_body
+      return @openreceive_raw_body if defined?(@openreceive_raw_body)
+
+      @openreceive_raw_body = openreceive_read_raw_body
+    end
+
+    def openreceive_read_raw_body
+      max_bytes = Server::RequestHandler::MAX_BODY_BYTES
+      raise Server::PayloadTooLargeError if request.get_header("CONTENT_LENGTH").to_i > max_bytes
+
+      body = request.body
+      return "" if body.nil?
+
+      raw = body.respond_to?(:read) ? body.read(max_bytes + 1).to_s : body.to_s
+      body.rewind if body.respond_to?(:rewind)
+      raise Server::PayloadTooLargeError if raw.bytesize > max_bytes
+
+      raw
+    end
+
+    # Render a [status, headers, body] triple with a byte-equal JSON body. `render body:` with an
+    # explicit content_type avoids Rails appending a charset, keeping the wire body identical to the
+    # Rack app; the JSON is generated exactly as RackApp generates it. Every non-Content-Type header
+    # from the shared handler is copied onto the Rails response verbatim.
+    def openreceive_respond(result)
+      status, headers, body = result
+      headers.each do |key, value|
+        next if key.casecmp("content-type").zero?
+
+        response.set_header(key, value)
+      end
+      render body: JSON.generate(body), content_type: "application/json", status: status
+    end
+  end
+end

data/app/controllers/openreceive/checkouts_controller.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module OpenReceive
+  class CheckoutsController < ApplicationController
+    def prepare
+      openreceive_respond(openreceive_handler.prepare_checkout(
+        raw_body: openreceive_raw_body,
+        request: request,
+        request_id: openreceive_request_id
+      ))
+    end
+
+    def create
+      openreceive_respond(openreceive_handler.create_checkout(
+        raw_body: openreceive_raw_body,
+        request: request,
+        request_id: openreceive_request_id
+      ))
+    end
+  end
+end

data/app/controllers/openreceive/payments_controller.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module OpenReceive
+  class PaymentsController < ApplicationController
+    def check
+      openreceive_respond(openreceive_handler.check_payment(
+        raw_body: openreceive_raw_body,
+        request: request,
+        request_id: openreceive_request_id,
+        **openreceive_check_pass_arguments
+      ))
+    end
+
+    private
+
+    # Engine mode serves payments/check from the around_action's gated pass
+    # (winner) or the engine-owned row (gate_busy / disabled) — never a second
+    # per-invoice wallet walk. Advanced mode (custom repository) has no
+    # engine-owned rows: it keeps the handler's legacy per-invoice behavior.
+    def openreceive_check_pass_arguments
+      return {} if OpenReceive.config.advanced_hooks?
+
+      {
+        reconcile_pass: @openreceive_reconcile_pass || { "reason" => "disabled" },
+        attempt_status: lambda do |payment_hash|
+          payment = OpenReceivePayment.find_by(payment_hash: payment_hash.to_s.downcase)
+          next nil if payment.nil?
+
+          {
+            "status" => payment.status,
+            "paid_at" => payment.paid_at&.to_i
+          }.compact
+        end
+      }
+    end
+  end
+end

data/app/controllers/openreceive/rates_controller.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module OpenReceive
+  class RatesController < ApplicationController
+    # Unauthenticated and payment-free: a crawler or health check hitting
+    # /rates must not consume the NWC scan budget. The JS handler returns
+    # before its opportunistic pass for the same route.
+    skip_around_action :openreceive_opportunistic_reconcile
+
+    def index
+      openreceive_respond(openreceive_handler.read_rates(
+        query_string: request.query_string,
+        request: request,
+        request_id: openreceive_request_id
+      ))
+    end
+  end
+end

data/app/controllers/openreceive/swaps_controller.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module OpenReceive
+  class SwapsController < ApplicationController
+    def quote
+      respond_with(:quote_swap)
+    end
+
+    def create
+      respond_with(:create_swap)
+    end
+
+    def status
+      respond_with(:get_swap)
+    end
+
+    def refund
+      respond_with(:refund_swap)
+    end
+
+    private
+
+    def respond_with(method)
+      openreceive_respond(openreceive_handler.public_send(
+        method,
+        raw_body: openreceive_raw_body,
+        request: request,
+        request_id: openreceive_request_id
+      ))
+    end
+  end
+end

data/app/jobs/openreceive/reconcile_job.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OpenReceive
+  # One reconciliation pass, wrapped for the host's ActiveJob backend. Schedule
+  # it with the host's recurring-job system (for example a solid_queue
+  # config/recurring.yml entry, sidekiq-cron, or clockwork); OpenReceive ships
+  # no scheduler of its own.
+  class ReconcileJob < ActiveJob::Base
+    queue_as :default
+
+    def perform
+      OpenReceive.reconcile!
+    end
+  end
+end

data/app/models/open_receive_meta.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+# Engine-owned key/value/rev rows in the host database (the install generator
+# emits the openreceive_meta table next to openreceive_payments). It holds the
+# durable reconcile gate every Puma worker and process on this database shares,
+# so rapid OpenReceive calls collapse to one real wallet scan per interval, and
+# the installed schema-version marker the engine refuses to run past. Mirrors
+# the JS SQL repository's claimReconcileGate and assertSupportedSchema.
+class OpenReceiveMeta < ActiveRecord::Base
+  self.table_name = "openreceive_meta"
+  self.primary_key = "key"
+
+  RECONCILE_GATE_KEY = "transaction_scan_gate"
+  SCHEMA_VERSION_KEY = "schema_version"
+  CAS_RETRIES = 6
+  # Tolerance when reading a timestamp another worker wrote. Beyond it a claim
+  # stamped in the future is a backwards clock step, not a fresh claim: without
+  # this clamp the gate would read as busy until wall-clock time caught up.
+  META_CLOCK_SKEW_SECONDS = 60
+
+  # One probe per process, on the engine's first database touch: a database
+  # written by a NEWER library must not be operated by this one (columns or
+  # state transitions it does not know about). An unreadable or absent marker
+  # means "not versioned" — the pre-versioned migrations could not seed a row —
+  # and is not a refusal. Mirrors the JS repository's assertSupportedSchema.
+  def self.assert_supported_schema!
+    @schema_version_checked ||= begin
+      stored = stored_schema_version
+      if !stored.nil? && stored > OpenReceive::Server::PAYMENTS_SCHEMA_VERSION
+        raise OpenReceive::ConfigurationError,
+              "openreceive_meta reports openreceive schema version #{stored}, newer than this " \
+              "library's #{OpenReceive::Server::PAYMENTS_SCHEMA_VERSION}. Upgrade openreceive-rails " \
+              "before serving this database."
+      end
+      true
+    end
+  end
+
+  # Optimistic compare-and-set: INSERT-if-absent at rev 0, or
+  # UPDATE ... WHERE rev = expected. Returns true when this caller's write won.
+  def self.cas(key, value, expected_rev)
+    if expected_rev.nil?
+      begin
+        create!(key: key, value: value, rev: 0)
+        true
+      rescue ActiveRecord::RecordNotUnique
+        false
+      end
+    else
+      where(key: key, rev: expected_rev).update_all(value: value, rev: expected_rev + 1) == 1
+    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:)
+    assert_supported_schema!
+    claim = JSON.generate("claimed_at" => Integer(now), "token" => SecureRandom.uuid)
+    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
+    end
+    false
+  end
+
+  def self.stored_schema_version
+    value = where(key: SCHEMA_VERSION_KEY).pick(:value)
+    return nil if value.nil?
+
+    Integer(value.to_s, 10, exception: false)
+  rescue ActiveRecord::ActiveRecordError
+    nil
+  end
+
+  # True when `timestamp` is within `window_seconds` of `now`. A stamp far in
+  # the future is a clock that stepped backwards, not a fresh claim: clamping
+  # it to stale keeps a rewound clock from parking the gate busy until
+  # wall-clock time catches up. Mirrors the JS isFreshTimestamp.
+  def self.fresh_timestamp?(now, timestamp, window_seconds)
+    age = now - timestamp
+    return false if age < -META_CLOCK_SKEW_SECONDS
+
+    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
+end