patient_http-solid_queue 1.2.0 → 1.3.0

data/VERSION

@@ -1 +1 @@
-1.2.0
+1.3.0

data/lib/generators/patient_http/solid_queue/install_generator.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/migration"
+require "rails/generators/active_record"
+
+module PatientHttp
+  module SolidQueue
+    # Installs the crash recovery migration and a commented initializer.
+    #
+    # The migration must run on the database that Solid Queue uses. The
+    # generator finds that database in `config/database.yml` and copies the
+    # migration to its migrations path, so a multi-database application needs
+    # no extra arguments. To name the database explicitly, pass `--database`.
+    #
+    # @example
+    #   bin/rails generate patient_http:solid_queue:install
+    class InstallGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      # The gem's migration. The generator copies this file so that the
+      # generator and the engine's `install:migrations` task use one schema.
+      MIGRATION_SOURCE = File.expand_path(
+        "../../../../db/migrate/20260216000000_create_patient_http_solid_queue_tables.rb",
+        __dir__
+      )
+
+      desc "Copies the patient_http-solid_queue migration and creates a commented initializer."
+
+      class_option :database,
+        type: :string,
+        default: nil,
+        desc: "Name of the database Solid Queue uses (detected from config/database.yml when omitted)"
+
+      class_option :skip_initializer,
+        type: :boolean,
+        default: false,
+        desc: "Skip creating config/initializers/patient_http.rb"
+
+      class << self
+        # Returns the timestamp prefix for the new migration.
+        #
+        # @param dirname [String] The directory that the migration is copied to.
+        # @return [String] The timestamp prefix.
+        def next_migration_number(dirname)
+          ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+        end
+      end
+
+      # Copies the migration to the Solid Queue database's migrations path.
+      # Skips the copy if any migrations path already has a migration for the
+      # tables.
+      #
+      # @return [void]
+      def copy_migration
+        existing = existing_migrations.first
+        if existing
+          say_status(:skip, "#{relative_to_original_destination_root(existing)} already creates the tables", :yellow)
+          return
+        end
+
+        migration_template(
+          MIGRATION_SOURCE,
+          File.join(migration_directory, "create_patient_http_solid_queue_tables.rb")
+        )
+      end
+
+      # Creates `config/initializers/patient_http.rb`, unless
+      # `--skip-initializer` is set.
+      #
+      # @return [void]
+      def create_initializer
+        return if options[:skip_initializer]
+
+        template("initializer.rb", "config/initializers/patient_http.rb")
+      end
+
+      # Prints the migrate command and a usage example.
+      #
+      # @return [void]
+      def show_next_steps
+        say("")
+        say("patient_http-solid_queue is installed.", :green)
+        say("")
+        say("Run the migration to create the crash-recovery tables:")
+        say("")
+        say("  bin/rails #{migrate_task}")
+        say("")
+        if other_database_env
+          say("The #{database_config.name} database is configured only for #{other_database_env}.", :yellow)
+          say("Run the migration where #{other_database_env} is deployed, for example as part of a deploy.", :yellow)
+          say("")
+        end
+        say("Nothing else is required: the request handler is registered when the gem")
+        say("loads and the processor starts and stops with your Solid Queue workers.")
+        say("")
+        say("Make a request from anywhere in your application:")
+        say("")
+        say("  PatientHttp.get(url, callback: MyCallback, callback_args: {id: 1})")
+        say("")
+      end
+
+      private
+
+      # Returns the migrations path of the database that Solid Queue uses. For
+      # single-database applications, falls back to `db/migrate`.
+      #
+      # @return [String] The migrations path.
+      def migration_directory
+        @migration_directory ||= begin
+          path = Array(database_config&.migrations_paths).first
+          path || "db/migrate"
+        end
+      end
+
+      # Returns the configuration of the database that Solid Queue uses.
+      #
+      # The generator checks the following, in order:
+      #
+      # 1. The database named by `--database`.
+      # 2. The database that Solid Queue connects to in the current environment
+      #    (`config.solid_queue.connects_to`).
+      # 3. The primary database, if the current environment runs Solid Queue
+      #    without `connects_to`.
+      # 4. A database named `queue`, which is the Rails default for Solid Queue,
+      #    then any database whose name contains `queue`.
+      # 5. The primary database.
+      #
+      # Databases in the current environment are checked first, then databases
+      # in the other environments. Solid Queue often has its own database only
+      # in production, so running the generator in development still finds it.
+      #
+      # @return [ActiveRecord::DatabaseConfigurations::DatabaseConfig, nil] The
+      #   database configuration, or `nil` if `config/database.yml` can't be
+      #   read.
+      # @raise [Rails::Generators::Error] If `--database` names a database that
+      #   isn't configured, or `config/database.yml` can't be read to find it.
+      def database_config
+        return @database_config if defined?(@database_config)
+
+        configs = database_configs
+        @database_config = if options[:database]
+          named = configs&.find { |config| config.name == options[:database] }
+          unless named
+            raise ::Rails::Generators::Error.new(
+              "No #{options[:database].inspect} database is configured in config/database.yml."
+            )
+          end
+          named
+        elsif configs
+          primary = configs.find { |config| config.env_name == ::Rails.env && config.name == "primary" }
+          connected_name = solid_queue_database_name
+          connected = configs.find { |config| config.env_name == ::Rails.env && config.name == connected_name } if connected_name
+
+          if connected
+            connected
+          elsif connected_name.nil? && solid_queue_adapter?
+            primary
+          else
+            configs.find { |config| config.name == "queue" } ||
+              configs.find { |config| config.name.to_s.include?("queue") } ||
+              primary
+          end
+        end
+      end
+
+      # Returns the name of the database that Solid Queue connects to in the
+      # current environment.
+      #
+      # @return [String, nil] The database name, or `nil` if Solid Queue doesn't
+      #   set `connects_to` with a writing database.
+      def solid_queue_database_name
+        return nil unless defined?(::SolidQueue) && ::SolidQueue.respond_to?(:connects_to)
+
+        connects_to = ::SolidQueue.connects_to
+        return nil unless connects_to.is_a?(Hash)
+
+        connects_to.dig(:database, :writing)&.to_s
+      end
+
+      # Returns whether Active Job uses Solid Queue in the current environment.
+      #
+      # @return [Boolean] `true` if the Active Job queue adapter is Solid Queue.
+      def solid_queue_adapter?
+        ::ActiveJob::Base.queue_adapter_name.to_s == "solid_queue"
+      end
+
+      # Returns the database configurations from `config/database.yml`, with
+      # the current environment's configurations first.
+      #
+      # @return [Array<ActiveRecord::DatabaseConfigurations::DatabaseConfig>, nil]
+      #   The database configurations, or `nil` if `config/database.yml` can't
+      #   be read.
+      def database_configs
+        return @database_configs if defined?(@database_configs)
+
+        @database_configs = begin
+          all_configs = ::ActiveRecord::Base.configurations.configs_for
+          current_env_configs = all_configs.select { |config| config.env_name == ::Rails.env }
+          current_env_configs + (all_configs - current_env_configs)
+        rescue => e
+          # Without a readable database configuration, fall back to db/migrate
+          # and let the developer move the file if it landed in the wrong place.
+          say("Could not read config/database.yml (#{e.class}); using db/migrate.", :yellow)
+          nil
+        end
+      end
+
+      # Returns the Rake task that runs the migration on the detected database.
+      #
+      # @return [String] The task name.
+      def migrate_task
+        name = database_config&.name
+        return "db:migrate" if name.nil? || name == "primary"
+
+        "db:migrate:#{name}"
+      end
+
+      # Returns the environment of the detected database if it isn't the
+      # current environment.
+      #
+      # @return [String, nil] The environment name, or `nil` if the database is
+      #   in the current environment or wasn't detected.
+      def other_database_env
+        env_name = database_config&.env_name
+        env_name unless env_name.nil? || env_name == ::Rails.env
+      end
+
+      # Returns the paths of migrations that already create this gem's tables.
+      # Checks the migrations paths of every configured database and
+      # `db/migrate`, and matches copies made by the engine's
+      # `install:migrations` task and copies under the gem's earlier migration
+      # name.
+      #
+      # @return [Array<String>] The migration paths.
+      def existing_migrations
+        directories = [migration_directory, "db/migrate"]
+        directories += Array(database_configs).flat_map { |config| Array(config.migrations_paths) }
+        pattern = "[0-9]*_create_{patient_http_solid_queue,solid_queue_async_http}_tables*.rb"
+        directories.uniq.flat_map do |directory|
+          Dir.glob(File.join(destination_root, directory, pattern))
+        end
+      end
+    end
+  end
+end

data/lib/generators/patient_http/solid_queue/templates/initializer.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+# Configuration for patient_http running on Solid Queue.
+#
+# Every option below is optional. Each is shown with its default value or with
+# an example value. The gem works with no configuration at all: requiring it
+# registers the request handler, and the async processor starts and stops with
+# your Solid Queue workers.
+#
+# Make requests from anywhere in your application:
+#
+#   PatientHttp.get("https://api.example.com/users/1",
+#     callback: FetchUserCallback,
+#     callback_args: {user_id: 1})
+#
+# Full reference: https://github.com/bdurand/patient_http-solid_queue#configuration
+
+PatientHttp.configure do |config|
+  # --- HTTP behavior -------------------------------------------------------
+
+  # Maximum concurrent HTTP requests per processor. Each named processor below
+  # has its own limit and uses this value unless it sets max_connections.
+  # config.max_connections = 256
+
+  # Default request timeout in seconds. Raise it for slow APIs; LLM APIs can
+  # take minutes.
+  # config.request_timeout = 60
+
+  # Cap sockets opened against any single host so one host cannot consume every
+  # file descriptor. Unlimited by default.
+  # config.max_connections_per_host = 32
+
+  # Maximum response body size in bytes. Larger responses raise
+  # PatientHttp::ResponseTooLargeError.
+  # config.max_response_size = 1024 * 1024
+
+  # Treat 4xx and 5xx responses as errors (routing them to the callback's
+  # on_error) instead of delivering them to on_complete.
+  # config.raise_error_responses = false
+
+  # User-Agent sent with every request.
+  # config.user_agent = "MyApp/1.0"
+
+  # --- Sending sensitive values -------------------------------------------
+
+  # Requests are serialized into the queue before they run. Register secrets by
+  # name and reference them with PatientHttp.secret(:api_token) when building a
+  # request; only the name is written to the queue, and the value is resolved
+  # in the processor at send time.
+  #
+  # config.register_secret(:api_token) { ENV["API_TOKEN"] }
+
+  # Encrypt request and response payloads in the queue. Pass an array of keys
+  # to rotate: the first encrypts, all of them decrypt.
+  #
+  # config.encryption_key = Rails.application.credentials.patient_http_key
+
+  # --- Large payloads ------------------------------------------------------
+
+  # Payloads over the threshold are written to a payload store instead of being
+  # passed through the queue. Register a store to turn this on.
+  #
+  # config.register_payload_store(:database, adapter: :active_record)
+  # config.payload_store_threshold = 64 * 1024
+
+  # --- Workload isolation --------------------------------------------------
+
+  # Named processors run independently, each with its own capacity and
+  # timeouts, so a burst of one kind of work cannot starve another. Route a
+  # request with PatientHttp.get(url, callback: Cb, processor: :llm).
+  #
+  # config.processor(:llm, max_connections: 200, request_timeout: 120)
+  # config.processor(:webhooks, max_connections: 64, request_timeout: 10)
+
+  # --- Solid Queue specifics -----------------------------------------------
+
+  # Queue used for this gem's request and callback jobs.
+  # config.queue_name = "patient_http"
+
+  # Graceful shutdown budget in seconds. Defaults to Solid Queue's own shutdown
+  # timeout minus two seconds, and must stay below it.
+  # config.shutdown_timeout = 23
+
+  # Called when Active Job discards a callback job.
+  # config.on_retries_exhausted { |error| Sentry.capture_message(error.message) }
+end
+
+# Callback jobs are not retried by default. Uncomment to retry them before they
+# are discarded.
+#
+# PatientHttp::SolidQueue::CallbackJob.retry_on StandardError,
+#   wait: :polynomially_longer, attempts: 5
+
+# Hooks for metrics. Both can be registered more than once.
+#
+# PatientHttp::SolidQueue.after_completion do |response|
+#   StatsD.timing("patient_http.duration", response.duration * 1000)
+# end
+#
+# PatientHttp::SolidQueue.after_error do |error|
+#   StatsD.increment("patient_http.error")
+# end

data/lib/patient_http/solid_queue/callback_job.rb

@@ -2,14 +2,15 @@
 
 module PatientHttp
   module SolidQueue
-    # Active Job that invokes callback services for HTTP request results.
+    # Active Job that passes HTTP request results to callback services.
     #
-    # Receives serialized Response or Error data and invokes the appropriate
-    # callback service method (+on_complete+ or +on_error+).
+    # The job receives serialized response or error data and calls the
+    # callback service's `on_complete` or `on_error` method.
     #
     # @api private
     class CallbackJob < ActiveJob::Base
-      # Clean up externally stored payloads when job exhausts all retries.
+      # Calls the `on_retries_exhausted` handler and deletes any externally
+      # stored payload when Active Job discards the job.
       after_discard do |job, _exception|
         data = job.arguments[0]
         result_type = job.arguments[1]
@@ -41,9 +42,15 @@ module PatientHttp
         end
       end
 
-      # @param data [Hash] Response or Error data (possibly a storage reference)
-      # @param result_type [String] "response" or "error" indicating the type of result
-      # @param callback_service_name [String] Fully qualified callback service class name
+      # Calls the callback service with the result.
+      #
+      # @param data [Hash] The serialized Response or Error, or a reference to
+      #   it in external storage. The data can be encrypted.
+      # @param result_type [String] The result type: `"response"` or `"error"`.
+      # @param callback_service_name [String] The fully qualified callback
+      #   service class name.
+      # @return [void]
+      # @raise [ArgumentError] If `result_type` isn't valid.
       def perform(data, result_type, callback_service_name)
         callback_service_class = PatientHttp::ClassHelper.resolve_class_name(callback_service_name)
         callback_service = callback_service_class.new