qube_rails 0.2.0

data/lib/qube_rails/configuration.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+module QubeRails
+  # A setting the app hasn't written yet, raised the first time it's needed.
+  class NotConfigured < StandardError; end
+
+  # The only place qube_rails reads your app from: QubeRails.configure in
+  # config/initializers/qube_rails.rb (`rails g qube_rails:install` writes one). A setting your
+  # app hasn't written raises QubeRails::NotConfigured, naming that file, the first time it's
+  # needed, so nothing silently passes.
+  class Configuration
+    FILE = "config/initializers/qube_rails.rb"
+    DEFAULT_BASE_URL = "https://qubesync.com"
+
+    attr_writer :base_url, :api_key, :webhook_secret, :webhook_url, :queue, :parent_controller
+
+    def initialize
+      @operations = nil
+      @connection_events = nil
+      @current_account = nil
+      @authorize_question = nil
+      @enqueue = nil
+      @dedupe = nil
+      @queue = nil
+      @job_attempts = nil
+      @prune_runs_after = nil
+      @connection_type = nil
+      @parent_controller = nil
+      @api_key = nil
+      @base_url = nil
+      @webhook_secret = nil
+      @webhook_url = nil
+      @ui_classes = {}.freeze
+      @storyboard = nil
+    end
+
+    # The pieces of the engine's screens config.ui_classes can add classes to.
+    UI_PIECES = %i[
+      question message details choice choice_detail choice_description field label input select checkbox
+      button button_secondary search search_results search_result status summary detail error
+      rows row row_header segmented segment row_fields use_for_all stall
+      picks pick pick_detail pick_action reason button_ghost choice_footer choice_divider
+    ].freeze
+
+    # Your CSS framework's classes for the engine's screens, by piece, added beside each element's
+    # qube- classes (a String, or an Array of them):
+    #   config.ui_classes = { button: "btn btn-primary", input: "form-control", select: "form-select" }
+    # A piece not in UI_PIECES raises, naming them.
+    def ui_classes=(map)
+      raise ArgumentError, "ui_classes is a Hash of piece => CSS classes, in #{FILE}" unless map.respond_to?(:each_pair)
+
+      list = {}
+      map.each_pair do |piece, classes|
+        key = piece.to_s.to_sym
+        unless UI_PIECES.include?(key)
+          raise ArgumentError, "ui_classes has no piece #{piece.inspect}: it takes #{UI_PIECES.join(", ")}, in #{FILE}"
+        end
+
+        list[key] = Array(classes).flatten.map(&:to_s).reject(&:empty?).join(" ").freeze
+      end
+      @ui_classes = list.freeze
+    end
+
+    attr_reader :ui_classes
+
+    # Whether GET qube/storyboard shows every screen with sample data. Default: in development.
+    def storyboard
+      return @storyboard unless @storyboard.nil?
+
+      defined?(Rails) && Rails.respond_to?(:env) ? Rails.env.development? : false
+    end
+
+    def storyboard=(value)
+      raise ArgumentError, "storyboard is true or false, in #{FILE}" unless [true, false].include?(value)
+
+      @storyboard = value
+    end
+
+    # Each operation, and each plain request (QubeRails::Request), by its slug (the SLUG its row
+    # keeps, in qube_runs.operation or qube_requests.operation), as class *names*:
+    #   config.operations = { "create_invoice" => "QuickbooksDesktop::CreateInvoice" }
+    # Names, not classes, so code reloading in development finds the class again each time. A
+    # fixed list, so a class is never looked up from anything a request says.
+    def operations=(map)
+      unless map.respond_to?(:each_pair)
+        raise ArgumentError, "operations is a Hash of slug => class name, in #{FILE}"
+      end
+
+      list = {}
+      map.each_pair do |slug, name|
+        list[slug.to_s] = name.is_a?(Module) ? name.name : name.to_s
+      end
+      @operations = list.freeze
+    end
+
+    def operations
+      @operations || not_configured(:operations, "the operations by slug, as class names")
+    end
+
+    # Your class for a connection's own events (a QubeRails::ConnectionEvents), by name:
+    #   config.connection_events = "QuickbooksDesktop::ConnectionEvents"
+    def connection_events=(name)
+      @connection_events = name.is_a?(Module) ? name.name : name && name.to_s
+    end
+
+    def connection_events
+      @connection_events || not_configured(:connection_events, "your ConnectionEvents class's name")
+    end
+
+    def connection_events_class
+      constantize(connection_events)
+    end
+
+    # The operation class for a slug, or nil when none of your operations has it.
+    def operation_class(slug)
+      name = operations[slug.to_s]
+      name && constantize(name)
+    end
+
+    # The signed-in customer's account, called with the controller handling the request (so your
+    # current_user and other helpers are there):
+    #   config.current_account = ->(controller) { controller.current_user.account }
+    # It owns the connections onboarding makes (QubeRails::Connection#owner), and only its own can
+    # be sent back through setup; nil answers 401.
+    def current_account=(callable)
+      @current_account = callable!(:current_account, callable)
+    end
+
+    def current_account
+      @current_account || not_configured(:current_account,
+                                         "->(controller) { the signed-in customer's account }")
+    end
+
+    # Whether the signed-in user may answer or search the question a run asks about record. The
+    # run (a QubeRails::Run) carries its operation and its connection, whose owner is the account
+    # that connected it. Only true allows; anything else is refused (404, as for a missing run)
+    # and logged. The run's id comes from the URL, so this is what keeps one customer's users off
+    # another's runs.
+    #
+    # The default allows the signed-in account (current_account) when it owns the run's
+    # connection. Set your own to check more (that the user may see the record), or less (staff
+    # who act across accounts):
+    #   config.authorize_question = ->(controller, record, run) {
+    #     run.connection.owner == controller.current_user.account && controller.current_user.can_edit?(record)
+    #   }
+    def authorize_question=(callable)
+      @authorize_question = callable!(:authorize_question, callable)
+    end
+
+    def authorize_question
+      @authorize_question || method(:owner_answers)
+    end
+
+    # Hands a verified delivery, { kind:, id:, body: } (kind "run", "connection" or "request", id the row's),
+    # to a queue. The default puts it on ActiveJob (QubeRails::WebhookJob, on the queue setting).
+    # Your own queue's worker calls QubeRails.run(kind, id, body).
+    def enqueue=(callable)
+      @enqueue = callable!(:enqueue, callable)
+    end
+
+    def enqueue
+      @enqueue || method(:enqueue_on_active_job)
+    end
+
+    # How many times QubeRails::WebhookJob runs a delivery before it gives up (retry_on, with a
+    # growing wait), read when the job class loads. Default 10.
+    def job_attempts
+      @job_attempts || 10
+    end
+
+    def job_attempts=(attempts)
+      unless attempts.is_a?(Integer) && attempts >= 1
+        raise ArgumentError, "job_attempts is a whole number of 1 or more, in #{FILE}"
+      end
+
+      @job_attempts = attempts
+    end
+
+    # The ActiveJob queue QubeRails::WebhookJob runs on.
+    def queue
+      @queue || :default
+    end
+
+    # The type onboarding creates connections as: "realtime" (the default; workflows need it) or
+    # "standard".
+    def connection_type
+      @connection_type || "realtime"
+    end
+
+    def connection_type=(type)
+      unless %w[realtime standard].include?(type.to_s)
+        raise ArgumentError, "connection_type is 'realtime' or 'standard', in #{FILE}"
+      end
+
+      @connection_type = type.to_s
+    end
+
+    # How long ended runs are kept before QubeRails::PruneRunsJob deletes them (nil: never).
+    attr_reader :prune_runs_after
+
+    def prune_runs_after=(duration)
+      unless duration.nil? || (duration.respond_to?(:to_i) && duration.to_i >= 1.day.to_i)
+        raise ArgumentError, "prune_runs_after is nil or a duration of a day or more, in #{FILE}"
+      end
+
+      @prune_runs_after = duration
+    end
+
+    # Where the notification delivery ids each run has taken are kept, so a redelivery runs its
+    # handler once. The default is the engine's qube_notifications table
+    # (QubeRails::DatabaseDedupe), written in the same transaction as the handler. Another store
+    # answers once(run, delivery_id) { } (running the block unless it's taken), or seen?(key) and
+    # remember(key), as QubeRails::CacheDedupe (Rails.cache, not transactional) does.
+    def dedupe=(store)
+      unless dedupe_store?(store)
+        raise ArgumentError, "dedupe needs once(run, delivery_id) { }, or seen?(key) and remember(key), in #{FILE}"
+      end
+
+      @dedupe = store
+    end
+
+    def dedupe
+      @dedupe ||= DatabaseDedupe.new
+    end
+
+    # The controller onboarding and the question routes inherit, by name, so your sign-in and
+    # CSRF protection apply to them.
+    def parent_controller
+      @parent_controller || "ApplicationController"
+    end
+
+    # QUBE_API_KEY, which `qube env --write .env` writes.
+    def api_key
+      @api_key || env("QUBE_API_KEY") || env_not_set(:api_key, "QUBE_API_KEY")
+    end
+
+    # QUBE_URL, or https://qubesync.com.
+    def base_url
+      @base_url || env("QUBE_URL") || DEFAULT_BASE_URL
+    end
+
+    # QUBE_WEBHOOK_SECRET, or a list of secrets while one rotates.
+    def webhook_secret
+      @webhook_secret || env("QUBE_WEBHOOK_SECRET") ||
+        env_not_set(:webhook_secret, "QUBE_WEBHOOK_SECRET")
+    end
+
+    # QUBE_WEBHOOK_URL, the base of each run's and each connection's webhook URL: `qube listen
+    # --write-env .env` writes it in development, and in production it's your app's
+    # /webhooks/qube.
+    def webhook_url
+      url = @webhook_url || env("QUBE_WEBHOOK_URL") ||
+            env_not_set(:webhook_url, "QUBE_WEBHOOK_URL")
+      url.to_s.chomp("/")
+    end
+
+    # Never the API key or a webhook secret.
+    def inspect
+      "#<#{self.class.name} base_url=#{base_url.inspect} operations=#{@operations.inspect} " \
+        "connection_events=#{@connection_events.inspect} api_key=#{secret_state(@api_key, "QUBE_API_KEY")} " \
+        "webhook_secret=#{secret_state(@webhook_secret, "QUBE_WEBHOOK_SECRET")}>"
+    end
+    alias to_s inspect
+
+    private
+
+    # Answers once(run, delivery_id) { }, or seen?(key) and remember(key).
+    def dedupe_store?(store)
+      store.respond_to?(:once) || (store.respond_to?(:seen?) && store.respond_to?(:remember))
+    end
+
+    # The default authorize_question: the signed-in account owns the run's connection. Compared
+    # by type and id, as the connection keeps them, so a nil or unsaved account never matches.
+    def owner_answers(controller, _record, run)
+      account = current_account.call(controller)
+      return false if account.nil? || account.id.nil?
+      return false if account.respond_to?(:persisted?) && !account.persisted?
+
+      klass = account.class
+      type = klass.respond_to?(:base_class) ? klass.base_class.name : klass.name
+      connection = run.connection
+      type == connection.owner_type && account.id.to_s == connection.owner_id.to_s
+    end
+
+    def enqueue_on_active_job(delivery)
+      QubeRails::WebhookJob.perform_later(delivery[:kind], delivery[:id], delivery[:body])
+    end
+
+    def constantize(name)
+      name.to_s.constantize
+    end
+
+    def env(name)
+      value = ENV[name]
+      value unless value.nil? || value.strip.empty?
+    end
+
+    def callable!(setting, callable)
+      return nil if callable.nil?
+      return callable if callable.respond_to?(:call)
+
+      raise ArgumentError, "#{setting} must respond to call, in #{FILE}"
+    end
+
+    def secret_state(value, env_name)
+      value || env(env_name) ? "[hidden]" : "nil"
+    end
+
+    def not_configured(setting, what)
+      raise NotConfigured, "QuBe Sync: #{setting} isn't set yet. Set config.#{setting} (#{what}) " \
+                           "in QubeRails.configure, in #{FILE}."
+    end
+
+    def env_not_set(setting, env_name)
+      raise NotConfigured, "QuBe Sync: #{setting} isn't set yet. Set #{env_name} in the " \
+                           "environment, or config.#{setting} in QubeRails.configure, in #{FILE}."
+    end
+  end
+end

data/lib/qube_rails/connection_events.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module QubeRails
+  # A connection's own events, which QuBe Sync POSTs to the connection's webhook URL,
+  # QUBE_WEBHOOK_URL/connections/<connection id>, set when onboarding makes it. The webhook job
+  # applies each to the connection row (status, stall_reason, revision) and then hands it to
+  # your class (a subclass of this, named by config.connection_events), which sees the
+  # connection and its owner:
+  #   connection.connected        the Web Connector checked in: QuickBooks is connected
+  #   connection.setup_cancelled  they chose "Cancel setup" on the setup page
+  #   connection.stalled          requests are stuck; see stall_reason
+  #   connection.resumed          after a stall, they're being taken again
+  #
+  # The setup ends on the QuickBooks computer, which usually isn't signed in to your app, so
+  # nothing comes back to it there: connection.connected, signed by QuBe Sync, is how your app
+  # knows. connection.status already says so when your handler runs.
+  class ConnectionEvents
+    # The status each event leaves the connection in.
+    STATUS = {
+      "connection.connected" => "connected",
+      "connection.setup_cancelled" => "setup_cancelled",
+      "connection.stalled" => "stalled",
+      "connection.resumed" => "connected"
+    }.freeze
+
+    attr_reader :connection
+
+    def initialize(connection)
+      @connection = connection
+    end
+
+    # The account (or whatever your app's customer is) that connected it.
+    def owner
+      connection.owner
+    end
+
+    # One of the connection's webhooks, from the webhook job, as the qube_sync gem parsed it (a
+    # ConnectionEvent). Deliveries come at least once and, from a queue with more than one
+    # worker, in any order:
+    # - an event whose connection isn't this row's qube_id (a signed body posted to another
+    #   connection's URL) is logged and skipped;
+    # - any other is applied only when its revision is newer than the last one applied, so a
+    #   retried connection.stalled that comes after its connection.resumed is skipped.
+    # It holds the connection row's lock while it does, so two workers never apply its events at
+    # once, and what your handler writes is saved with the revision or not at all.
+    #
+    # A row with no qube_id yet can't be checked: its id is adopted from QuBe Sync when one of the
+    # app's connections there has this row's webhook URL (a create that landed but whose id
+    # wasn't saved yet), and otherwise QubeRails::NotReady is raised, so the queue retries it.
+    def handle(event)
+      if connection.qube_id.to_s.empty?
+        connection.adopt_qube_connection
+        if connection.qube_id.to_s.empty?
+          raise NotReady, "QuBe Sync: connection #{connection.id} has no qube_id yet; #{event.event} waits for it"
+        end
+      end
+
+      applied = connection.with_lock { apply(event) }
+      refresh_pages if applied && (event.stalled? || event.resumed?)
+    end
+
+    # What your app does with each: until you fill them in, each logs.
+
+    # QuickBooks is connected: show the connection as connected, and start syncing.
+    def connected(event)
+      log_event(event)
+    end
+
+    # They cancelled the setup: offer Connect QuickBooks Desktop again.
+    def setup_cancelled(event)
+      log_event(event)
+    end
+
+    # Your requests are waiting and QuickBooks hasn't been reached. Show the customer, and tell
+    # them what the event's stall_reason (and connection.stall_reason) says:
+    # - "not_checking_in": the Web Connector isn't calling in. Turn on the QuickBooks computer,
+    #   and check the Web Connector runs.
+    # - "quickbooks_unavailable": it is calling in and can't reach QuickBooks. Open QuickBooks
+    #   with the company file.
+    # A stall can send this again with a new reason (the computer was turned on, and QuickBooks
+    # isn't open yet): show the newest. resumed clears it.
+    def stalled(event)
+      log_event(event)
+    end
+
+    # Clear what stalled showed, whichever its reason.
+    def resumed(event)
+      log_event(event)
+    end
+
+    # The account disconnected it (DELETE quickbooks/connections/:id): delete your rows that
+    # point at it. Runs in the transaction that deletes it, before its runs and links go.
+    def disconnected; end
+
+    private
+
+    # Only a connection event carries a connection: any other event posted to this URL is
+    # skipped as not its connection.
+    def apply(event)
+      connection_id = event.type == "connection" ? event.connection_id : nil
+      unless this_connection?(connection_id)
+        QubeRails.logger.warn("QuBe Sync: connection #{connection.id} skipped #{event.event} for " \
+                              "#{connection_id.inspect}: not this connection")
+        return false
+      end
+
+      # Applied already, or older than what was.
+      return false unless event.newer_than?(connection.revision)
+
+      status = STATUS[event.event]
+      if status
+        connection.status = status
+        connection.stall_reason = event.stalled? ? event.stall_reason : nil
+      end
+      connection.revision = event.revision
+
+      if event.connected?
+        connected(event)
+      elsif event.setup_cancelled?
+        setup_cancelled(event)
+      elsif event.stalled?
+        stalled(event)
+      elsif event.resumed?
+        resumed(event)
+      else
+        log_event(event)
+      end
+      connection.save!
+      true
+    end
+
+    # At most this many records' pages are told to refresh when the connection stalls or resumes.
+    REFRESH_LIMIT = 200
+
+    # A stall or a resume changes what the run status says on the pages of the records with a run
+    # still going on this connection: tell them to refresh, after the change is committed (by the
+    # connection's runs index, at most REFRESH_LIMIT records).
+    def refresh_pages
+      return unless QubeRails.refresh_broadcasts?
+
+      going = connection.runs.where.not(state: Run::ENDED_STATES).distinct.limit(REFRESH_LIMIT)
+                        .pluck(:record_type, :record_id)
+      going.each do |type, id|
+        model = type.safe_constantize
+        record = model.respond_to?(:find_by) ? model.find_by(model.primary_key => id) : nil
+        QubeRails.broadcast_refresh(record) if record
+      end
+    rescue StandardError => e
+      QubeRails.logger.warn("QuBe Sync: couldn't tell connection #{connection.id}'s pages to refresh (#{e.class})")
+    end
+
+    # All a handler does until you fill it in.
+    def log_event(event)
+      line = "QuBe Sync: connection #{connection.id}: #{event["event"]} (revision #{event["revision"]})"
+      if event["event"] == "connection.stalled"
+        QubeRails.logger.warn(line)
+      else
+        QubeRails.logger.info(line)
+      end
+    end
+
+    # The event is about this connection: its connection_id is the one QuBe Sync made it.
+    def this_connection?(connection_id)
+      !connection_id.nil? && connection_id == connection.qube_id
+    end
+  end
+end

data/lib/qube_rails/database_dedupe.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module QubeRails
+  # The default dedupe setting: the notification delivery ids each run has taken, in
+  # qube_notifications. once runs inside the run row's lock and transaction (Operation#handle), so
+  # the row and the handler's writes commit together: a redelivery finds the row and is skipped,
+  # and a handler that raised rolls its row back with it, so the retry runs it again.
+  class DatabaseDedupe
+    # Runs the block unless run has taken delivery_id already.
+    def once(run, delivery_id)
+      notifications = QubeRails::Notification.where(run_id: run.id)
+      # Under the run row's lock no other worker inserts for this run, so this check is enough;
+      # the savepoint keeps a unique violation from a lock-free caller from aborting a
+      # PostgreSQL transaction.
+      return false if notifications.where(delivery_id: delivery_id.to_s).exists?
+
+      begin
+        QubeRails::Notification.transaction(requires_new: true) do
+          notifications.create!(delivery_id: delivery_id.to_s)
+        end
+      rescue ActiveRecord::RecordNotUnique
+        return false
+      end
+      yield
+      true
+    end
+  end
+end

data/lib/qube_rails/engine.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module QubeRails
+  # Mounted in your config/routes.rb with `mount QubeRails::Engine => "/"`, which adds, relative
+  # to where it's mounted:
+  #   POST quickbooks/connections                  a connection for the signed-in account
+  #   POST quickbooks/connections/:id/onboarding   one of its connections, through setup again
+  #   POST webhooks/qube/runs/:id                  a run's webhooks: no sign-in, no CSRF
+  #   POST webhooks/qube/connections/:id           a connection's webhooks: no sign-in, no CSRF
+  #   POST qube/questions/runs/:id                 an answer, behind your sign-in and CSRF
+  #   GET  qube/questions/runs/:id/search          a record field's matches, behind sign-in
+  #   POST qube/runs/:id/retry_start               an unconfirmed start sent again, likewise
+  #   GET  qube/storyboard(/:screen)               every screen with sample data (config.storyboard)
+  # Your views reach them through the qube_rails route proxy: qube_rails.connections_path,
+  # qube_rails.connection_onboarding_path(connection).
+  class Engine < ::Rails::Engine
+    isolate_namespace QubeRails
+
+    # qube_rails_assets and qube_classes, in every view of the app.
+    initializer "qube_rails.view_helpers" do
+      ActiveSupport.on_load(:action_view) { include QubeRails::ViewHelpers }
+    end
+
+    # Sprockets serves only what's listed; Propshaft serves every asset path and has no list.
+    initializer "qube_rails.assets" do |app|
+      assets = app.config.respond_to?(:assets) ? app.config.assets : nil
+      precompile = assets && assets.precompile
+      precompile.concat(%w[qube_rails/question.js qube_rails.css]) if precompile.is_a?(Array)
+    end
+  end
+end

data/lib/qube_rails/json_coder.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+
+module QubeRails
+  # How the JSON in qube_runs (question, links) is kept: as JSON text in a plain text column, with
+  # this coder.
+  #
+  # Why text and not a json column: the engine has to run on PostgreSQL, MySQL and SQLite, from
+  # Rails 5.2 (vendored into older apps) to 8.1, and the native types disagree. PostgreSQL has
+  # json and jsonb, MySQL 5.7+ has json (MariaDB's is a longtext alias, so it comes back as a
+  # String), and SQLite has no json type at all before Rails 6 maps one; what each adapter hands
+  # back (a Hash, or a String to parse) differs by adapter and version. Nothing ever queries inside
+  # these columns, so text and one coder behave the same everywhere, and the value is always a
+  # Hash with String keys, or nil.
+  module JSONCoder
+    module_function
+
+    def dump(value)
+      value.nil? ? nil : JSON.generate(value)
+    end
+
+    def load(text)
+      return nil if text.nil? || text == ""
+      return text unless text.is_a?(String) # a json column read by its adapter already
+
+      JSON.parse(text)
+    end
+
+    # serialize(name, coder) until Rails 7.1, serialize(name, coder:) since: the positional form
+    # is deprecated in 7.1 and gone in 7.2.
+    def serialize(model, *names)
+      new_api = ActiveRecord.respond_to?(:gem_version) && ActiveRecord.gem_version >= Gem::Version.new("7.1")
+      names.each do |name|
+        if new_api
+          model.serialize(name, coder: self)
+        else
+          model.serialize(name, self)
+        end
+      end
+    end
+  end
+end