qube_rails 0.2.0

data/app/controllers/concerns/qube_rails/run_authorization.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module QubeRails
+  # Finding the run a request names (params[:id]) and asking config.authorize_question whether the
+  # signed-in user may act on it, for the question routes and the start retry. The run's id comes
+  # from the URL, so this is what keeps one customer's users off another's runs.
+  module RunAuthorization
+    private
+
+    # [run, operation class, record] when the run, its operation and its record are there and
+    # authorize_question says true; else nil, and a refusal is logged. Only true lets it through:
+    # a truthy record, or a forgotten return, doesn't. A refusal answers as a run that doesn't
+    # exist does (404), so a user can't tell another customer's run is there.
+    def authorized_run(action)
+      run = QubeRails::Run.find_by(id: params[:id])
+      operation = run && QubeRails.config.operation_class(run.operation)
+      record = operation && operation.record_for(run)
+      return nil unless record
+
+      unless QubeRails.config.authorize_question.call(self, record, run) == true
+        QubeRails.logger.warn("QuBe Sync: refused #{action} for run #{run.id}: config.authorize_question said no")
+        return nil
+      end
+
+      [run, operation, record]
+    end
+
+    # Back to the page, with message (a Symbol is an I18n key under qube_rails, a String the
+    # sentence itself) in the flash for the engine's partials to show (qube_rails/_question and
+    # _run_status). The forms post through Turbo in most apps, which
+    # shows nothing for a plain-text 409 or 422, so a failed answer or retry says why this way.
+    def back_with_error(message)
+      flash[:qube_rails_error] = message.is_a?(Symbol) ? QubeRails.t(message) : message
+      redirect_back fallback_location: "/", status: :see_other
+    end
+  end
+end

data/app/controllers/qube_rails/connections_controller.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module QubeRails
+  # Connects a customer's QuickBooks Desktop. QuBe Sync hosts the setup and walks them through
+  # the Web Connector, on the computer where QuickBooks is installed, and tells the connection
+  # how it went by webhook (QubeRails::ConnectionEvents, then your config.connection_events
+  # class): connection.connected, or connection.setup_cancelled.
+  #
+  # An account can have any number of connections (a company file each), so each is its own row
+  # (QubeRails::Connection), owned by the signed-in account (config.current_account). Behind
+  # your sign-in, as your ApplicationController (config.parent_controller) is.
+  class ConnectionsController < QubeRails.config.parent_controller.constantize
+    # POST /quickbooks/connections, from a "Connect QuickBooks Desktop" button, with an optional
+    # name. Best clicked on the computer where QuickBooks is installed. It sends the account's
+    # newest connection that has never connected (pending, or its setup cancelled) back through
+    # setup, so clicking Connect again doesn't pile up connections; it makes a new one when the
+    # account has none, or with new=1 (a "Connect another company file" button). A new row is
+    # written first, so the connection's webhook URL names it; if QuBe Sync doesn't answer, the
+    # row is left without a qube_id and the next click picks it up. Until connection.connected
+    # comes, show it as waiting for QuickBooks: the setup doesn't come back here.
+    #
+    # With simulated=1, outside production, it connects a simulated QuickBooks company file
+    # instead, for testing with no Windows computer: a new row whose QuBe Sync connection is
+    # connected as it's made, so connection.connected comes at once, and back to the page the
+    # button was on rather than to setup.
+    def create
+      account = signed_in_account
+      return head(:unauthorized) unless account
+      return connect_simulated(account) if simulated_requested?
+
+      connection = QubeRails::Connection.owned_by(account).never_connected.first unless params[:new].to_s == "1"
+      return send_to_setup(connection) if connection
+
+      send_to_setup(QubeRails::Connection.create!(owner: account, name: connection_name, status: "pending"),
+                    fresh: true)
+    end
+
+    # POST /quickbooks/connections/:id/onboarding: sends one of the signed-in account's
+    # connections back through setup (a new company file, a Web Connector set up again), with its
+    # webhook URL brought up to date. Another account's connection answers 404.
+    def onboarding
+      account = signed_in_account
+      return head(:unauthorized) unless account
+
+      connection = QubeRails::Connection.owned_by(account).find_by(id: params[:id])
+      return head(:not_found) unless connection
+
+      send_to_setup(connection)
+    end
+
+    # What the page says when it can't, as I18n keys under qube_rails (config/locales/en.yml).
+    RUNS_GOING = :"errors.still_syncing"
+    NO_ANSWER = :"errors.disconnect_unreachable"
+
+    # DELETE /quickbooks/connections/:id: disconnects one of the signed-in account's
+    # connections. QuBe Sync deletes its connection (the Web Connector stops syncing that
+    # company file), then the row goes, with its runs and its QuickBooks links. Refused while a
+    # run hasn't ended. Another account's connection answers 404.
+    def destroy
+      account = signed_in_account
+      return head(:unauthorized) unless account
+
+      connection = QubeRails::Connection.owned_by(account).find_by(id: params[:id])
+      return head(:not_found) unless connection
+      return back_with_error(RUNS_GOING) if work_going?(connection)
+
+      delete_on_qube(connection)
+      connection.disconnect!
+      redirect_back fallback_location: "/", status: :see_other
+    rescue *QubeRails::Backend::NETWORK_ERRORS
+      back_with_error(NO_ANSWER)
+    end
+
+    private
+
+    def work_going?(connection)
+      connection.runs.where.not(state: QubeRails::Run::ENDED_STATES).exists? ||
+        connection.queued_requests.where(ended_at: nil).exists?
+    end
+
+    # Already gone there (404) is gone.
+    def delete_on_qube(connection)
+      return if connection.qube_id.to_s.empty?
+
+      QubeRails.client.delete_connection(connection.qube_id)
+    rescue QubeRails::Backend::APIError => e
+      raise unless e.status == 404
+    end
+
+    # The engine's partials show the message once.
+    def back_with_error(key)
+      flash[:qube_rails_error] = QubeRails.t(key)
+      redirect_back fallback_location: "/", status: :see_other
+    end
+
+    def signed_in_account
+      account = QubeRails.config.current_account.call(self)
+      unless account
+        QubeRails.logger.warn("QuBe Sync: refused a connect: config.current_account found no signed-in account")
+      end
+      account
+    end
+
+    def simulated_requested?
+      params[:simulated].to_s == "1"
+    end
+
+    # Never in production: a customer's user can't make a connection to a fake company file.
+    def connect_simulated(account)
+      return head(:not_found) if Rails.env.production?
+
+      connection = QubeRails::Connection.create!(owner: account, name: connection_name, status: "pending")
+      made = QubeRails.client.create_connection(webhook_url: connection.webhook_url, name: connection.name,
+                                                type: "simulated")
+      connection.update!(qube_id: made["id"])
+      redirect_back fallback_location: "/", status: :see_other
+    end
+
+    def connection_name
+      name = params[:name].to_s.strip
+      name.empty? ? nil : name[0, 255]
+    end
+
+    # fresh: a row this request wrote, which no earlier create can have been made for.
+    def send_to_setup(connection, fresh: false)
+      # An earlier create that landed before its id was saved: that connection, not a second one.
+      connection.adopt_qube_connection if !fresh && connection.qube_id.to_s.empty?
+      if connection.qube_id
+        QubeRails.client.update_connection(connection.qube_id, webhook_url: connection.webhook_url)
+        made = QubeRails.client.regenerate_onboarding(connection.qube_id)
+      else
+        made = QubeRails.client.create_connection(webhook_url: connection.webhook_url, name: connection.name,
+                                                  type: QubeRails.config.connection_type)
+        connection.update!(qube_id: made["id"])
+      end
+
+      # 303, so the browser follows the POST with a GET.
+      redirect_to made.dig("links", "onboarding"), allow_other_host: true, status: :see_other
+    end
+  end
+end

data/app/controllers/qube_rails/questions_controller.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "json"
+
+module QubeRails
+  # Your user's answers to the questions a run asks, from the question partial
+  # (qube_rails/_question) on the record's page:
+  #   POST /qube/questions/runs/<run id>         a choice, with its fields
+  #   GET  /qube/questions/runs/<run id>/search  a record field's matches, as JSON
+  # Each finds the run, its operation (config.operations) and its record, as the webhooks do, and
+  # asks config.authorize_question(controller, record, run) before anything is sent: by default,
+  # whether the signed-in account owns the run's connection. The calls to QuBe Sync are made here, with
+  # the API key, so the browser only ever talks to your app.
+  #
+  # Behind your sign-in, as your ApplicationController (config.parent_controller) is. The answers
+  # come from forms, so they carry your CSRF token, as the partial writes it.
+  class QuestionsController < QubeRails.config.parent_controller.constantize
+    # What the page says when the answer wasn't sent, as an I18n key under qube_rails.
+    CHANGED = :"errors.question_changed"
+
+    include RunAuthorization
+
+    before_action :find_question
+
+    # Posts your user's choice, with what they filled in for its fields, to the question's
+    # links.decisions, and sends them back to the page; when it can't, back with why (the
+    # partial shows it). The question is forgotten once it's
+    # answered, or once QuBe Sync says it was answered or asked again since (a 409, or a 400 such
+    # as not_awaiting_input); the run's next webhook says what came of it.
+    def create
+      choices = Array(@question && @question["choices"])
+      choice = choices.find { |c| c["id"] == params[:choice] }
+      return back_with_error(CHANGED) unless choice && @links["decisions"]
+
+      QubeRails.client.answer(@links["decisions"], choice: choice["id"], data: answer_data(choice))
+      @operation.answered(@question["token"], taken: true)
+      redirect_back fallback_location: "/", status: :see_other
+    rescue Backend::APIError => e
+      raise unless [400, 409, 422].include?(e.status)
+      # A field QuBe Sync couldn't take: its errors.detail says which.
+      return back_with_error(refusal(e)) if e.status == 422
+
+      @operation.answered(@question["token"])
+      back_with_error(CHANGED)
+    end
+
+    # The matches for a record field, for what your user typed: [{value, label, detail}], at most
+    # 20, from the question's links.search, which a run sets while it asks with one. q of 2 to 100
+    # characters and a field name of at most 100 are asked about; anything else has no matches.
+    def search
+      q = params[:q].to_s.strip
+      field = params[:field].to_s
+      return render(json: [], status: :conflict) unless @links["search"]
+      return render(json: []) unless searchable?(q, field)
+
+      row = params[:row].to_s
+      row = nil if row.empty? || row.length > 200
+      render json: QubeRails.client.search(@links["search"], field: field, q: q, row: row)
+    rescue Backend::APIError => e
+      raise unless e.status.between?(400, 499)
+
+      render json: [], status: e.status # the question has changed (409), say
+    end
+
+    private
+
+    # What a search is asked about: q of 2 to 100 characters, a field name of 1 to 100.
+    # A rows field's answer: each row's filled columns, by row key. QuBe Sync drops a column the
+    # row's other answers say doesn't apply, and names any required one left out.
+    def rows_data(field, form)
+      form = form.respond_to?(:to_unsafe_h) ? form.to_unsafe_h : {}
+      field["rows"].to_a.each_with_object({}) do |row, rows|
+        given = form[row["key"]].is_a?(Hash) ? form[row["key"]] : {}
+        columns = field["columns"].to_a.select { |column| row["columns"].to_a.include?(column["name"]) }
+        rows[row["key"]] = columns.each_with_object({}) do |column, values|
+          text = given[column["name"]].to_s.strip
+          values[column["name"]] = column["type"] == "number" ? number(text) : text unless text.empty?
+        end
+      end
+    end
+
+    def searchable?(q, field)
+      q.length.between?(2, 100) && field.length.between?(1, 100)
+    end
+
+    def find_question
+      run, operation, record = authorized_run("an answer or search")
+      return refuse unless run
+
+      @operation = operation.new(record, run)
+      @question = run.open_question
+      @links = run.links || {}
+    end
+
+    def refuse
+      if action_name == "search"
+        render json: [], status: :not_found
+      else
+        head :not_found
+      end
+    end
+
+    # The choice's own fields from the form, each as its type: a checkbox true or false, a number
+    # as a number (or as typed, for QuBe Sync's 422 to name), and a blank one left out.
+    def answer_data(choice)
+      form = params.fetch(:data, {})
+      choice["fields"].to_a.each_with_object({}) do |field, data|
+        name = field["name"]
+        next data[name] = rows_data(field, form[name]) if field["type"] == "rows"
+
+        text = form[name].to_s.strip
+        if field["type"] == "boolean"
+          data[name] = text == "true"
+        elsif !text.empty?
+          data[name] = field["type"] == "number" ? number(text) : text
+        end
+      end
+    end
+
+    def number(text)
+      text.match?(/\A-?\d+\z/) ? text.to_i : Float(text, exception: false) || text
+    end
+
+    # What QuBe Sync said was wrong with an answer, in words (its errors.detail).
+    def refusal(error)
+      detail = JSON.parse(error.body.to_s).dig("errors", "detail")
+      detail ? QubeRails.t(:"errors.answer_refused_with", detail: detail) : QubeRails.t(:"errors.answer_refused")
+    rescue JSON::ParserError, TypeError, NoMethodError
+      QubeRails.t(:"errors.answer_refused")
+    end
+  end
+end

data/app/controllers/qube_rails/runs_controller.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module QubeRails
+  # POST /qube/runs/<run id>/retry_start, from the run status partial's "Try sending again"
+  # button: sends a start QuBe Sync never confirmed (a run still "starting") again, with the same
+  # reference as its Idempotency-Key (QubeRails::Run#retry_start!), so a start that did land
+  # answers with its run rather than making another. Behind your sign-in and CSRF, as your
+  # ApplicationController (config.parent_controller) is, and config.authorize_question decides
+  # who may, as for answering the run's questions.
+  class RunsController < QubeRails.config.parent_controller.constantize
+    include RunAuthorization
+
+    # What the page says when it can't, as I18n keys under qube_rails (config/locales/en.yml).
+    NOT_STARTING = :"errors.not_starting"
+    NOT_QUIET = :"errors.not_quiet"
+    REDELIVERY_REFUSED = { 409 => :"errors.no_update_yet", 429 => :"errors.checked_just_now" }.freeze
+    NO_ANSWER = :"errors.unreachable"
+
+    def retry_start
+      run, = authorized_run("a start retry")
+      return head(:not_found) unless run
+      return back_with_error(NOT_STARTING) unless run.state == "starting"
+
+      begin
+        run.retry_start!
+      rescue Backend::APIError, *Backend::NETWORK_ERRORS => e
+        # Refused (the run is now failed) or no answer again (still unconfirmed): the status on
+        # the page says which.
+        QubeRails.logger.warn("QuBe Sync: run #{run.id}'s start retry didn't go through (#{e.class})")
+      end
+      redirect_back fallback_location: "/", status: :see_other
+    end
+
+    # POST /qube/runs/<run id>/redeliver, from the run status partial's "Check for updates"
+    # button on a run that looks stuck (QubeRails::Run#looks_stuck?): asks QuBe Sync to
+    # send the run's latest event again (its question, or how it ended) to the run's webhook URL,
+    # for a webhook this app missed. The event comes back through the webhook route as usual;
+    # one this app already applied is skipped by its revision.
+    def redeliver
+      run, = authorized_run("a redelivery")
+      return head(:not_found) unless run
+      return back_with_error(NOT_QUIET) unless run.looks_stuck?
+
+      QubeRails.client.redeliver_run(run.connection.qube_id, run.qube_run_id)
+      redirect_back fallback_location: "/", status: :see_other
+    rescue Backend::APIError => e
+      raise unless REDELIVERY_REFUSED.key?(e.status)
+
+      back_with_error(REDELIVERY_REFUSED.fetch(e.status))
+    rescue *Backend::NETWORK_ERRORS
+      back_with_error(NO_ANSWER)
+    end
+  end
+end

data/app/controllers/qube_rails/storyboard_controller.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module QubeRails
+  # GET qube/storyboard (and qube/storyboard/<screen>): every screen the engine's partials show,
+  # from sample data (QubeRails::Storyboard), in your app's layout, so your CSS and
+  # config.ui_classes apply and each piece's override path is beside it. Only when
+  # config.storyboard is true (by default, in development), behind your sign-in as the other
+  # routes are. Its searches answer from the samples and its forms post to a no-op: nothing
+  # reaches QuBe Sync or the database.
+  class StoryboardController < QubeRails.config.parent_controller.constantize
+    NOTHING_SENT = "Storyboard: nothing was sent."
+
+    # Your layout's own route helpers (root_path) resolve as on your pages; the engine's are
+    # qube_rails.*.
+    include Rails.application.routes.url_helpers
+    helper Rails.application.routes.url_helpers
+
+    prepend_before_action :require_storyboard
+    before_action :find_screen, except: :index
+
+    def index
+      @screens = Storyboard.screens
+      render :show
+    end
+
+    def show
+      @screens = [@screen]
+    end
+
+    def search
+      render json: Storyboard.matches(@screen, params[:field], params[:q])
+    end
+
+    def answer
+      flash[:qube_rails_storyboard] = NOTHING_SENT
+      redirect_to qube_rails.storyboard_screen_path(@screen.key), status: :see_other
+    end
+
+    private
+
+    def require_storyboard
+      head :not_found unless QubeRails.config.storyboard == true
+    end
+
+    def find_screen
+      @screen = Storyboard.find(params[:screen])
+      head :not_found unless @screen
+    end
+  end
+end

data/app/controllers/qube_rails/webhooks_controller.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module QubeRails
+  # Receives QuBe Sync's webhooks at POST /webhooks/qube/runs/<run id>, the URL each run was
+  # started with (QubeRails::Run#webhook_url), and at /webhooks/qube/connections/<connection id>,
+  # each connection's (QubeRails::Connection#webhook_url), and at /webhooks/qube/requests/<id>,
+  # each plain request's (QubeRails::QueuedRequest#webhook_url). It only verifies the delivery, checks
+  # the row is there and enqueues it (config.enqueue), so it answers well inside the 5 seconds
+  # QuBe Sync waits: the job does the rest.
+  #
+  # The verification is the qube_sync gem's: the signature over the raw body, with any v1
+  # matching in constant time, and a timestamp within 5 minutes either way. No sign-in and no
+  # CSRF token: the signature is what proves QuBe Sync sent it.
+  class WebhooksController < ActionController::API
+    # The largest body taken: a pull_changes page can be a few megabytes. Anything larger is
+    # answered 413 before it's read.
+    MAX_BODY_BYTES = 5 * 1024 * 1024
+
+    # Any content type: the body is only ever read raw, so Rails never parses it as params.
+    wrap_parameters false
+
+    def run_event
+      receive("run", QubeRails::Run)
+    end
+
+    def connection_event
+      receive("connection", QubeRails::Connection)
+    end
+
+    def request_event
+      receive("request", QubeRails::QueuedRequest)
+    end
+
+    private
+
+    def receive(kind, model)
+      return too_large if request.content_length.to_i > MAX_BODY_BYTES
+
+      body = request.raw_post.to_s
+      return too_large if body.bytesize > MAX_BODY_BYTES
+
+      Backend.verify(body, request.headers["X-Qube-Signature"], secrets: QubeRails.config.webhook_secret)
+      id = request.path_parameters[:id].to_s
+      # A row that isn't there (deleted, or a wrong webhook_url): QuBe Sync retries it, and shows
+      # it as a failed delivery.
+      return head(:not_found) unless model.where(id: id).exists?
+
+      # The signature covers the body, not the URL, so the id is only a pointer: the job checks
+      # the event's reference and connection id against the row.
+      # The body goes as text, which any queue can carry; the job parses it again. A 200 tells
+      # QuBe Sync it's taken and it won't send it again, so a queue that didn't take it answers
+      # 503 and QuBe Sync retries.
+      return head(:ok) if enqueued?(kind, id, body.dup.force_encoding(Encoding::UTF_8))
+
+      head :service_unavailable
+    rescue Backend::SignatureError => e
+      # Its reason (missing, malformed, stale or mismatch) is safe to log: never the secret, the
+      # signature or the body.
+      QubeRails.logger.warn("QuBe Sync: refused a webhook: #{e.reason} (#{request.path}): " \
+                            "#{SIGNATURE_HINTS[e.reason]}")
+      head :unauthorized
+    rescue Backend::ParseError => e
+      # Signed, but not a JSON object: nothing a job could take.
+      QubeRails.logger.warn("QuBe Sync: refused a webhook: #{e.message}")
+      head :bad_request
+    end
+
+    # false (ActiveJob 7.1+ when the adapter couldn't enqueue, or a callback stopped it) or an
+    # error from the enqueue is a delivery not taken. Logged without the body.
+    def enqueued?(kind, id, body)
+      result = QubeRails.config.enqueue.call(kind: kind, id: id, body: body)
+      return true unless result == false
+
+      QubeRails.logger.error("QuBe Sync: couldn't enqueue a webhook for #{kind} #{id}: the enqueue returned false; " \
+                             "answered 503 so QuBe Sync sends it again")
+      false
+    rescue StandardError => e
+      QubeRails.logger.error("QuBe Sync: couldn't enqueue a webhook for #{kind} #{id} (#{e.class}); " \
+                             "answered 503 so QuBe Sync sends it again")
+      false
+    end
+
+    # What to check for each reason a signature is refused, for the developer reading the log.
+    SIGNATURE_HINTS = {
+      mismatch: "it isn't signed with QUBE_WEBHOOK_SECRET (config.webhook_secret). Set that to this " \
+                "app's webhook secret, which `qube env --write .env` writes, and restart; QuBe Sync " \
+                "sends it again",
+      stale: "its signature's time is over 5 minutes from this server's clock. Check the clock",
+      missing: "it has no X-Qube-Signature header, so it isn't from QuBe Sync",
+      malformed: "its X-Qube-Signature header isn't t=<seconds>,v1=<hex>, so it isn't from QuBe Sync"
+    }.freeze
+    private_constant :SIGNATURE_HINTS
+
+    def too_large
+      QubeRails.logger.warn("QuBe Sync: refused a webhook: its body is over #{MAX_BODY_BYTES} bytes")
+      head 413
+    end
+  end
+end

data/app/jobs/qube_rails/prune_runs_job.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module QubeRails
+  # Deletes ended runs older than config.prune_runs_after (Run.prunable), with their
+  # notifications, and ended plain requests (QueuedRequest.prunable) with their deliveries. Links
+  # and sync marks stay. Does nothing until the setting is written.
+  class PruneRunsJob < ActiveJob::Base
+    queue_as { QubeRails.config.queue }
+
+    def perform
+      after = QubeRails.config.prune_runs_after
+      return unless after
+
+      QubeRails::Run.prunable(older_than: after).in_batches(of: 500).delete_all
+      QubeRails::QueuedRequest.prunable(older_than: after).in_batches(of: 500).delete_all
+    end
+  end
+end

data/app/jobs/qube_rails/refresh_job.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module QubeRails
+  # Tells a record's pages to refresh once more, a few seconds after an event changed its run
+  # (QubeRails.broadcast_refresh). A page still loading when the first refresh went out (the
+  # redirect after "Send to QuickBooks", when the simulator asks its question at once) had no
+  # subscription yet; by now it has, so a question that landed meanwhile still shows.
+  class RefreshJob < ActiveJob::Base
+    queue_as { QubeRails.config.queue }
+
+    # The record was deleted since: there's no page to refresh.
+    discard_on ActiveJob::DeserializationError
+
+    def perform(record)
+      QubeRails.broadcast_refresh_now(record)
+    end
+  end
+end

data/app/jobs/qube_rails/webhook_job.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module QubeRails
+  # Runs each verified QuBe Sync webhook on your ActiveJob queue (Sidekiq, Solid Queue,
+  # delayed_job, whichever your app uses), on config.queue: a run's event goes to its operation,
+  # with its record (QubeRails::Operation#handle), and a connection's to your connection_events
+  # class (QubeRails.run). It's config.enqueue's
+  # default; an app with another queue sets enqueue and calls QubeRails.run from its worker.
+  #
+  # QuBe Sync had its 2xx when the event was enqueued, so it won't send it again: a job that
+  # raises is retried here, config.job_attempts times in all (10 unless set) with a growing wait,
+  # since Solid Queue, GoodJob and :async don't retry a job that raises. When the attempts run
+  # out it logs an error and raises, so your adapter's own handling (Sidekiq's retries and dead
+  # set) sees it.
+  #
+  # With more than one worker, a run's events can run in any order, a later one first. handle
+  # applies a run event only when its revision is newer than the last applied, under the run row's
+  # lock, and takes a notification once, by its delivery_id.
+  #
+  # A workflow that sends notifications (pull_changes's pages) waits for each one's 2xx before it
+  # sends the next. The endpoint answers at once, so they come as fast as it answers, not after
+  # each is saved: see each operation's notification handler.
+  class WebhookJob < ActiveJob::Base
+    queue_as { QubeRails.config.queue }
+
+    # :polynomially_longer since Rails 7.1, which deprecates :exponentially_longer (the same wait).
+    BACKOFF = ActiveJob.gem_version >= Gem::Version.new("7.1") ? :polynomially_longer : :exponentially_longer
+
+    ATTEMPTS = QubeRails.config.job_attempts
+
+    retry_on StandardError, wait: BACKOFF, attempts: ATTEMPTS do |job, error|
+      kind, id = job.arguments
+      QubeRails.logger.error("QuBe Sync: gave up on a webhook for #{kind} #{id} after #{ATTEMPTS} " \
+                             "attempts: #{error.class}: #{error.message}")
+      raise error
+    end
+
+    # kind is "run", "connection" or "request", id the row's.
+    def perform(kind, id, body)
+      QubeRails.run(kind, id, body)
+    end
+  end
+end

data/app/models/qube_rails/application_record.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module QubeRails
+  # The base of the engine's models. Their tables are qube_connections, qube_runs,
+  # qube_notifications, qube_quickbooks_records, qube_sync_marks, qube_requests and
+  # qube_request_deliveries, from the engine's migrations
+  # (`bin/rails qube_rails:install:migrations`).
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+
+    # The type and id a polymorphic column keeps for record: its base class's name (as Rails
+    # writes it) and its id as a string, so an app's integer and UUID keys both fit.
+    def self.key_for(record)
+      [record.class.base_class.name, record.id.to_s]
+    end
+  end
+end