Document and test ActiveRecord::Promise usage

rmosolgo · rmosolgo · commit 9ce5ba096ca1 · 2024-01-09T14:50:40.000-05:00
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -44,17 +44,17 @@ jobs:
         include:
           - gemfile: Gemfile
             ruby: 3.2
-          - gemfile: gemfiles/rails_5.2.gemfile
-            ruby: 2.7
           # Rails 6.1 is tested with Postgresql below
           - gemfile: gemfiles/rails_7.0.gemfile
             ruby: 3.1
           - gemfile: gemfiles/rails_master.gemfile
             ruby: 3.1
           - gemfile: gemfiles/rails_7.0.gemfile
             ruby: 3.2
+          - gemfile: gemfiles/rails_7.1.gemfile
+            ruby: 3.3
           - gemfile: gemfiles/rails_master.gemfile
-            ruby: 3.2
+            ruby: 3.3
     runs-on: ubuntu-latest
     steps:
     - run: echo BUNDLE_GEMFILE=${{ matrix.gemfile }} > $GITHUB_ENV
diff --git a/gemfiles/rails_7.0.gemfile b/gemfiles/rails_7.0.gemfile
@@ -6,7 +6,7 @@ gem "bootsnap"
 gem "ruby-prof", platform: :ruby
 gem "pry"
 gem "pry-stack_explorer", platform: :ruby
-gem "rails", "~> 7.0", require: "rails/all"
+gem "rails", "~> 7.0.0", require: "rails/all"
 gem "sqlite3", "~> 1.4", platform: :ruby
 gem "activerecord-jdbcsqlite3-adapter", platform: :jruby
 gem "sequel"
diff --git a/gemfiles/rails_7.1.gemfile b/gemfiles/rails_7.1.gemfile
@@ -6,9 +6,12 @@ gem "bootsnap"
 gem "ruby-prof", platform: :ruby
 gem "pry"
 gem "pry-stack_explorer", platform: :ruby
-gem "rails", "~> 5.2.0", require: "rails/all"
+gem "rails", "~> 7.1.0", require: "rails/all"
 gem "sqlite3", "~> 1.4", platform: :ruby
+gem "pg", platform: :ruby
 gem "activerecord-jdbcsqlite3-adapter", platform: :jruby
 gem "sequel"
+gem "evt"
+gem "async"
 
 gemspec path: "../"
diff --git a/guides/dataloader/async_dataloader.md b/guides/dataloader/async_dataloader.md
@@ -2,7 +2,7 @@
 layout: guide
 search: true
 section: Dataloader
-title: Parallel Data Loading for GraphQL
+title: Async Source Execution
 desc: Using AsyncDataloader to fetch external data in parallel
 index: 5
 ---
@@ -26,6 +26,8 @@ Now, {{ "GraphQL::Dataloader::AsyncDataloader" | api_doc }} will create `Async::
 
 For a demonstration of this behavior, see: [https://github.com/rmosolgo/rails-graphql-async-demo](https://github.com/rmosolgo/rails-graphql-async-demo)
 
+_You can also implement {% internal_link "manual parallelism", "/dataloader/parallelism" %} using `dataloader.yield`._
+
 ## Rails
 
 For Rails, you'll need **Rails 7.1**, which properly supports fiber-based concurrency, and you'll also want to configure Rails to use Fibers for isolation:
@@ -36,3 +38,7 @@ class Application < Rails::Application
   config.active_support.isolation_level = :fiber
 end
 ```
+
+## Other Options
+
+You can also manually implement parallelism with Dataloader. See the {% internal_link "Dataloader Parallelism", "/dataloader/parallelism" } guide for details.
diff --git a/guides/dataloader/overview.md b/guides/dataloader/overview.md
@@ -131,3 +131,10 @@ end
 ## Data Sources
 
 To implement batch-loading data sources, see the {% internal_link "Sources guide", "/dataloader/sources" %}.
+
+## Parallelism
+
+You can run I/O operations in parallel with GraphQL::Dataloader. There are two approaches:
+
+- `AsyncDataloader` uses the `async` gem to automatically background I/O from `Dataloader::Source#fetch` calls. {% internal_link "Read More", "/dataloader/async_dataloader" %}
+- You can manually call `dataloader.yield` after starting work in the background. {% internal_link "Read More", "/dataloader/parallelism" %}
diff --git a/guides/dataloader/parallelism.md b/guides/dataloader/parallelism.md
@@ -0,0 +1,105 @@
+---
+layout: guide
+search: true
+section: Dataloader
+title: Manual Parallelism
+desc: Yield to Dataloader after starting work
+index: 7
+---
+
+You can coordinate with {{ "GraphQL::Dataloader" | api_doc }} to run tasks in the background. To do this, call `dataloader.yield` inside `Source#fetch` after kicking off your task. For example:
+
+```ruby
+def fetch(ids)
+  # somehow queue up a background query,
+  # see examples below
+  future_result = async_query_for(ids)
+  # return control to the dataloader
+  dataloader.yield
+  # dataloader will come back here
+  # after calling other sources,
+  # now wait for the value
+  future_result.value
+end
+```
+
+_Alternatively, you can use {% internal_link "AsyncDataloader", "/dataloader/async_dataloader" %} to automatically background I/O inside `Source#fetch` calls._
+
+## Example: Rails load_async
+
+You can use Rails's `load_async` method to load `ActiveRecord::Relation`s in the background. For example:
+
+```ruby
+class Sources::AsyncRelationSource < GraphQL::Dataloader::Source
+  def fetch(relations)
+    relations.each(&:load_async) # start loading them in the background
+    dataloader.yield # hand back to GraphQL::Dataloader
+    relations.each(&:load) # now, wait for the result, returning the now-loaded relation
+  end
+end
+```
+
+You could call that source from a GraphQL field method:
+
+```ruby
+field :direct_reports, [Person]
+
+def direct_reports
+  # prepare an ActiveRecord::Relation:
+  direct_reports = Person.where(manager: object)
+  # pass it off to the source:
+  dataloader
+    .with(Sources::AsyncRelationSource)
+    .load(direct_reports)
+end
+```
+
+## Example: Rails async calculations
+
+In a Dataloader source, you can run Rails async calculations in the background while other work continues. For example:
+
+```ruby
+class Sources::DirectReportsCount < GraphQL::Dataloader::Source
+  def fetch(users)
+    # Start the queries in the background:
+    promises = users.map { |u| u.direct_reports.async_count }
+    # Return to GraphQL::Dataloader:
+    dataloader.yield
+    # Now return the results, waiting if necessary:
+    promises.map(&:value)
+  end
+end
+```
+
+Which could be used in a GraphQL field:
+
+```ruby
+field :direct_reports_count, Int
+
+def direct_reports_count
+  dataloader.with(Sources::DirectReportsCount).load(object)
+end
+```
+
+## Example: Concurrent::Future
+
+You could use `concurrent-ruby` to put work in a background thread. For example, using `Concurrent::Future`:
+
+```ruby
+class Sources::ExternalDataSource < GraphQL::Dataloader::Source
+  def fetch(urls)
+    # Start some I/O-intensive work:
+    futures = urls.map do |url|
+      Concurrent::Future.execute {
+        # Somehow fetch and parse data:
+        get_remote_json(url)
+      }
+    end
+    # Yield back to GraphQL::Dataloader:
+    dataloader.yield
+    # Dataloader has done what it can,
+    # so now return the value, waiting if necessary:
+    futures.map(&:value)
+  end
+end
+```
diff --git a/guides/dataloader/sources.md b/guides/dataloader/sources.md
@@ -132,9 +132,7 @@ def fetch(keys)
 end
 ```
 
-For a more robust asynchronous task primitive, check out [`Concurrent::Future`](http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Future.html).
-
-Ruby 3.0 added built-in support for yielding Fibers that make I/O calls -- hopefully a future GraphQL-Ruby version will work with that!
+See the {% internal_link "parallelism guide", "/dataloader/parallelism" %} for details about this approach.
 
 ## Filling the Dataloader Cache
 
diff --git a/spec/graphql/pagination/active_record_relation_connection_spec.rb b/spec/graphql/pagination/active_record_relation_connection_spec.rb
@@ -3,9 +3,6 @@
 
 if testing_rails?
   describe GraphQL::Pagination::ActiveRecordRelationConnection do
-    class Food < ActiveRecord::Base
-    end
-
     if Food.count == 0 # Backwards-compat version of `.none?`
       ConnectionAssertions::NAMES.each { |n| Food.create!(name: n) }
     end
diff --git a/spec/integration/rails/graphql/dataloader_spec.rb b/spec/integration/rails/graphql/dataloader_spec.rb
@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+require "spec_helper"
+
+describe GraphQL::Dataloader do
+  if defined?(ActiveRecord::Promise) && ENV['DATABASE'] == 'POSTGRESQL' # Rails 7.1+
+    class RailsPromiseSchema < GraphQL::Schema
+      class LoadAsyncSource < GraphQL::Dataloader::Source
+        LOG = []
+        def fetch(relations)
+          relations.each do |rel|
+            LOG << Time.now
+            rel.load_async
+          end
+          dataloader.yield
+          relations.each do |rel|
+            rel.load
+            LOG << Time.now
+          end
+        end
+      end
+
+      class SleepSource < GraphQL::Dataloader::Source
+        def initialize(duration)
+          @duration = duration
+        end
+
+        def fetch(durations)
+          # puts  "[#{Time.now.to_f}] Starting #{durations}"
+          promise = ::Food.async_find_by_sql("SELECT pg_sleep(#{durations.first})")
+          # puts "[#{Time.now.to_f}] Yielding #{durations}"
+          dataloader.yield
+          # puts "[#{Time.now.to_f}] Finishing #{durations}"
+          promise.value
+          durations
+        end
+      end
+      class Query < GraphQL::Schema::Object
+        field :sleep, Float do
+          argument :duration, Float
+        end
+
+        def sleep(duration:)
+          dataloader.with(SleepSource, duration).load(duration)
+        end
+
+        field :things, Integer do
+          argument :first, Integer
+        end
+
+        def things(first:)
+          relation = Food
+            .where(name: "Zucchini")
+            .select("pg_sleep(0.3)")
+            .limit(first)
+          items = dataloader.with(LoadAsyncSource).load(relation)
+          items.size
+        end
+      end
+
+      query(Query)
+      use GraphQL::Dataloader
+    end
+
+    before do
+      Food.create!(name: "Zucchini")
+      RailsPromiseSchema::LoadAsyncSource::LOG.clear
+    end
+
+    after do
+      Food.find_by(name: "Zucchini").destroy
+    end
+
+    it "Supports async queries" do
+      assert ActiveRecord::Base.connection.async_enabled?, "ActiveRecord must support real async queries"
+    end
+
+    describe "using ActiveRecord::Promise for manual parallelism" do
+      it "runs queries in parallel" do
+        query_str = "
+        {
+          s1: sleep(duration: 0.1)
+          s2: sleep(duration: 0.2)
+          s3: sleep(duration: 0.3)
+        }"
+        t1 = Time.now
+        result = RailsPromiseSchema.execute(query_str)
+        t2 = Time.now
+        assert_equal({ "s1" => 0.1, "s2" => 0.2, "s3" => 0.3}, result["data"])
+        assert_in_delta 0.3, t2 - t1, 0.05, "Sleeps were in parallel"
+      end
+    end
+
+    describe "using load_async for parallelism" do
+      it "runs queries in parallel" do
+        query_str = "
+        {
+          t1: things(first: 5)
+          t2: things(first: 10)
+          t3: things(first: 100)
+        }"
+        t1 = Time.now
+        result = RailsPromiseSchema.execute(query_str)
+        t2 = Time.now
+
+        load_async_1, load_async_2, load_async_3, load_1, load_2, load_3 = RailsPromiseSchema::LoadAsyncSource::LOG
+        assert_in_delta load_async_1, load_async_2, 0.05, "load_async happened first"
+        assert_in_delta load_async_1, load_async_3, 0.05, "the third load_async happened right after"
+
+        assert_in_delta load_async_1, load_1, 0.35, "load came 0.3s after"
+        assert_in_delta load_1, load_2, 0.05, "the second load didn't have to wait because it was already done"
+        assert_in_delta load_1, load_3, 0.05, "the third load didn't have to wait because it was already done"
+
+        assert_equal({ "t1" => 1, "t2" => 1, "t3" => 1}, result["data"])
+        assert_in_delta 0.3, t2 - t1, 0.05, "Sleeps were in parallel"
+      end
+    end
+  end
+end
diff --git a/spec/support/active_record_setup.rb b/spec/support/active_record_setup.rb
@@ -3,6 +3,8 @@
   # Remove the old sqlite database
   `rm -f ./_test_.db`
 
+  ActiveRecord.async_query_executor ||= :global_thread_pool
+
   # platform helper
   def jruby?
     RUBY_ENGINE == 'jruby'
@@ -47,4 +49,7 @@ def jruby?
       t.column :name, :string
     end
   end
+
+  class Food < ActiveRecord::Base
+  end
 end
