graphql-stitching 1.4.3 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a72adc399f618790fc1aefe1b6dca07709d45f10cc2936f5c3978d75b5d3f8c2
-  data.tar.gz: d45d7b73045755a750d6d4334e00e30f33c5124f83c849c24669c98f7912ca92
+  metadata.gz: 7b71b1d9e65a84356466a0ff822e177ef5faccce1e2a0cbd91d930b06ea50923
+  data.tar.gz: 8c73c1bcc78d23ea3b0c3f09da2659d84b7877000ccba86f79fa9f83f5801c60
 SHA512:
-  metadata.gz: 5302083cb9047ad77aa5e6276d02e3bdac8256ef328edb8c72b9248efbb279c48bb3e34b8e220f131d3efa541fdaa1b682fe4622501900defe797217cbc365c8
-  data.tar.gz: 4e238de4607764406ac52634daafc293c1b5fe672457106ff1070e77bc4d52cdc1ace02ce46ca4cacbcde7648d8a4f2bb8cc0321157dfb3c85c3ec40d5f82e43
+  metadata.gz: 0e46b25856e61dc033ba0e2640d30133463c550af0071ac0e8bb3836b2fa8f4d0690018359b5b3b086861a907b5c66ea55eece9d4bfebe85296e723aedd96415
+  data.tar.gz: 79180fc8944adde3ee0abf79a6fefa3487724cfbf9fb55e00adf29aa42d637c1c53331aad34a0c9c32ed7e3120fdaa6dd26fba9644df86b0feb774a84a8876b2

data/.gitignore

@@ -21,6 +21,10 @@ Gemfile.lock
 .ruby-version
 .DS_Store
 
+examples/subscriptions/log/*
+examples/subscriptions/tmp/*
+examples/subscriptions/storage/*
+
 ## Specific to RubyMotion:
 .dat*
 .repl_history

data/README.md

@@ -5,16 +5,17 @@ GraphQL stitching composes a single schema from multiple underlying GraphQL reso
 ![Stitched graph](./docs/images/stitching.png)
 
 **Supports:**
+- All operation types: query, mutation, and subscription.
 - Merged object and abstract types.
-- Multiple and composite keys per merged type.
 - Shared objects, fields, enums, and inputs across locations.
+- Multiple and composite type keys.
 - Combining local and remote schemas.
 - File uploads via [multipart form spec](https://github.com/jaydenseric/graphql-multipart-request-spec).
 - Tested with all minor versions of `graphql-ruby`.
 
 **NOT Supported:**
 - Computed fields (ie: federation-style `@requires`).
-- Subscriptions, defer/stream.
+- Defer/stream.
 
 This Ruby implementation is a sibling to [GraphQL Tools](https://the-guild.dev/graphql/stitching) (JS) and [Bramble](https://movio.github.io/bramble/) (Go), and its capabilities fall somewhere in between them. GraphQL stitching is similar in concept to [Apollo Federation](https://www.apollographql.com/docs/federation/), though more generic. The opportunity here is for a Ruby application to stitch its local schemas together or onto remote sources without requiring an additional proxy service running in another language. If your goal is to build a purely high-throughput federated reverse proxy, consider not using Ruby.
 
@@ -445,6 +446,7 @@ The [Executor](./docs/executor.md) component builds atop the Ruby fiber-based im
 - [Modeling foreign keys for stitching](./docs/mechanics.md##modeling-foreign-keys-for-stitching)
 - [Deploying a stitched schema](./docs/mechanics.md#deploying-a-stitched-schema)
 - [Schema composition merge patterns](./docs/composer.md#merge-patterns)
+- [Subscriptions tutorial](./docs/subscriptions.md)
 - [Field selection routing](./docs/mechanics.md#field-selection-routing)
 - [Root selection routing](./docs/mechanics.md#root-selection-routing)
 - [Stitched errors](./docs/mechanics.md#stitched-errors)

data/docs/README.md

@@ -15,4 +15,5 @@ Major components include:
 Additional topics:
 
 - [Stitching mechanics](./mechanics.md) - more about building for stitching and how it operates.
+- [Subscriptions](./subscriptions.md) - explore how to stitch realtime event subscriptions.
 - [Federation entities](./federation_entities.md) - more about Apollo Federation compatibility.

data/docs/composer.md

@@ -1,6 +1,6 @@
 ## GraphQL::Stitching::Composer
 
-A `Composer` receives many individual `GraphQL:Schema` instances for various graph locations and _composes_ them into a combined [`Supergraph`](./supergraph.md) that is validated for integrity.
+A `Composer` receives many individual `GraphQL::Schema` instances representing various graph locations and _composes_ them into one combined [`Supergraph`](./supergraph.md) that is validated for integrity.
 
 ### Configuring composition
 

data/docs/subscriptions.md

@@ -0,0 +1,208 @@
+## Stitching subscriptions
+
+Stitching is an interesting prospect for subscriptions because socket-based interactions can be isolated to their own schema/server with very little implementation beyond resolving entity keys. Then, entity data can be stitched onto subscription payloads from other locations.
+
+### Composing a subscriptions schema
+
+For simplicity, subscription resolvers should exist together in a single schema (multiple schemas with subscriptions probably aren't worth the confusion). This subscriptions schema may provide basic entity types that will merge with other locations. For example, here's a bare-bones subscriptions schema:
+
+```ruby
+class SubscriptionSchema < GraphQL::Schema
+  class Post < GraphQL::Schema::Object
+    field :id, ID, null: false
+  end
+
+  class Comment < GraphQL::Schema::Object
+    field :id, ID, null: false
+  end
+
+  class CommentAddedToPost < GraphQL::Schema::Subscription
+    argument :post_id, ID, required: true
+    field :post, Post, null: false
+    field :comment, Comment, null: true
+
+    def subscribe(post_id:)
+      { post: { id: post_id }, comment: nil }
+    end
+
+    def update(post_id:)
+      { post: { id: post_id }, comment: object }
+    end
+  end
+
+  class SubscriptionType < GraphQL::Schema::Object
+    field :comment_added_to_post, subscription: CommentAddedToPost
+  end
+
+  use GraphQL::Subscriptions::ActionCableSubscriptions
+  subscription SubscriptionType
+end
+```
+
+The above subscriptions schema can compose with other locations, such as the following that provides full entity types:
+
+```ruby
+class EntitiesSchema < GraphQL::Schema
+  class StitchingResolver < GraphQL::Schema::Directive
+    graphql_name "stitch"
+    locations FIELD_DEFINITION
+    argument :key, String, required: true
+    argument :arguments, String, required: false
+    repeatable true
+  end
+
+  class Comment < GraphQL::Schema::Object
+    field :id, ID, null: false
+    field :message, String, null: false
+  end
+
+  class Post < GraphQL::Schema::Object
+    field :id, ID, null: false
+    field :title, String, null: false
+    field :comments, [Comment, null: false], null: false
+  end
+
+  class QueryType < GraphQL::Schema::Object
+    field :posts, [Post, null: true] do
+      directive StitchingResolver, key: "id"
+      argument :ids, [ID], required: true
+    end
+
+    def posts(ids:)
+      records_by_id = Post.where(id: ids).index_by(&:id)
+      ids.map { |id| records_by_id[id] }
+    end
+
+    field :comments, [Comment, null: true] do
+      directive StitchingResolver, key: "id"
+      argument :ids, [ID], required: true
+    end
+
+    def comments(ids:)
+      records_by_id = Comment.where(id: ids).index_by(&:id)
+      ids.map { |id| records_by_id[id] }
+    end
+  end
+
+  query QueryType
+end
+```
+
+These schemas can be composed as normal into a stitching client. The subscriptions schema must be locally-executable while other entity schema(s) may be served from anywhere:
+
+```ruby
+StitchedSchema = GraphQL::Stitching::Client.new(locations: {
+  subscriptions: {
+    schema: SubscriptionSchema, # << locally executable!
+  },
+  entities: {
+    schema: GraphQL::Schema.from_definition(entities_schema_sdl),
+    executable: GraphQL::Stitching::HttpExecutable.new("http://localhost:3001"),
+  },
+})
+```
+
+### Serving stitched subscriptions
+
+Once you've stitched a schema with subscriptions, it gets called as part of three workflows:
+
+1. Controller - handles normal query and mutation requests recieved via HTTP.
+2. Channel - handles subscription-create requests recieved through a socket connection.
+3. Plugin – handles subscription-update events pushed to the socket connection.
+
+#### Controller
+
+A controller will recieve basic query and mutation requests sent over HTTP, including introspection requests. Fulfill these using the stitched schema client.
+
+```ruby
+class GraphqlController < ApplicationController
+  skip_before_action :verify_authenticity_token
+  layout false
+
+  def execute
+    result = StitchedSchema.execute(
+      params[:query],
+      context: {}, 
+      variables: params[:variables],
+      operation_name: params[:operationName],
+    )
+
+    render json: result
+  end
+end
+```
+
+#### Channel
+
+A channel handles subscription requests initiated via websocket connection. This mostly follows the [GraphQL Ruby documentation example](https://graphql-ruby.org/api-doc/2.3.9/GraphQL/Subscriptions/ActionCableSubscriptions), except that `execute` uses the stitched schema client while `unsubscribed` uses the subscriptions subschema directly:
+
+```ruby
+class GraphqlChannel < ApplicationCable::Channel
+  def subscribed
+    @subscription_ids = []
+  end
+
+  def execute(params)
+    result = StitchedSchema.execute(
+      params["query"],
+      context: { channel: self },
+      variables: params["variables"],
+      operation_name: params["operationName"]
+    )
+
+    payload = {
+      result: result.to_h,
+      more: result.subscription?,
+    }
+
+    if result.context[:subscription_id]
+      @subscription_ids << result.context[:subscription_id]
+    end
+
+    transmit(payload)
+  end
+
+  def unsubscribed
+    @subscription_ids.each { |sid|
+      # Go directly through the subscriptions subschema 
+      # when managing/triggering subscriptions:
+      SubscriptionSchema.subscriptions.delete_subscription(sid)
+    }
+  end
+end
+```
+
+What happens behind the scenes here is that stitching filters the `execute` request down to just subscription selections, and passes those through to the subscriptions subschema where they register an event binding. The subscriber response gets stitched while passing back up through the stitching client.
+
+#### Plugin
+
+Lastly, update events trigger with the filtered subscriptions selection, so must get stitched before transmitting. The stitching client adds an update handler into request context for this purpose. A small patch to the subscriptions plugin class can call this handler on update event payloads before transmitting them:
+
+```ruby
+class StitchedActionCableSubscriptions < GraphQL::Subscriptions::ActionCableSubscriptions
+  def execute_update(subscription_id, event, object)
+    super(subscription_id, event, object).tap do |result|
+      result.context[:stitch_subscription_update]&.call(result)
+    end
+  end
+end
+
+class SubscriptionSchema < GraphQL::Schema
+  # switch the plugin on the subscriptions schema to use the patched class... 
+  use StitchedActionCableSubscriptions
+end
+```
+
+### Triggering subscriptions
+
+Subscription update events are triggered as normal directly through the subscriptions subschema:
+
+```ruby
+class Comment < ApplicationRecord
+  after_create :trigger_subscriptions
+  
+  def trigger_subscriptions
+    SubscriptionsSchema.subscriptions.trigger(:comment_added_to_post, { post_id: post_id }, self)
+  end
+end
+```

data/examples/subscriptions/.gitattributes

@@ -0,0 +1,9 @@
+# See https://git-scm.com/docs/gitattributes for more about git attribute files.
+
+# Mark the database schema as having been generated.
+db/schema.rb linguist-generated
+
+# Mark any vendored files as having been vendored.
+vendor/* linguist-vendored
+config/credentials/*.yml.enc diff=rails_credentials
+config/credentials.yml.enc diff=rails_credentials

data/examples/subscriptions/.gitignore

@@ -0,0 +1,35 @@
+# See https://help.github.com/articles/ignoring-files for more about ignoring files.
+#
+# If you find yourself ignoring temporary files generated by your text editor
+# or operating system, you probably want to add a global ignore instead:
+#   git config --global core.excludesfile '~/.gitignore_global'
+
+# Ignore bundler config.
+/.bundle
+
+# Ignore all environment files (except templates).
+/.env*
+!/.env*.erb
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp/*
+!/log/.keep
+!/tmp/.keep
+
+# Ignore pidfiles, but keep the directory.
+/tmp/pids/*
+!/tmp/pids/
+!/tmp/pids/.keep
+
+# Ignore storage (uploaded files in development and any SQLite databases).
+/storage/*
+!/storage/.keep
+/tmp/storage/*
+!/tmp/storage/
+!/tmp/storage/.keep
+
+/public/assets
+
+# Ignore master key for decrypting credentials and more.
+/config/master.key

data/examples/subscriptions/Gemfile

@@ -0,0 +1,65 @@
+source "https://rubygems.org"
+
+ruby "3.1.1"
+
+# Bundle edge Rails instead: gem "rails", github: "rails/rails", branch: "main"
+gem "rails", "~> 7.1.3", ">= 7.1.3.4"
+
+# Use sqlite3 as the database for Active Record
+gem "sqlite3", "~> 1.4"
+
+# Use the Puma web server [https://github.com/puma/puma]
+gem "puma", ">= 5.0"
+
+# Use JavaScript with ESM import maps [https://github.com/rails/importmap-rails]
+gem "importmap-rails"
+
+# Hotwire's SPA-like page accelerator [https://turbo.hotwired.dev]
+gem "turbo-rails"
+
+# Hotwire's modest JavaScript framework [https://stimulus.hotwired.dev]
+gem "stimulus-rails"
+
+# Build JSON APIs with ease [https://github.com/rails/jbuilder]
+gem "jbuilder"
+
+# Use Redis adapter to run Action Cable in production
+gem "redis", ">= 4.0.1"
+
+# Use Kredis to get higher-level data types in Redis [https://github.com/rails/kredis]
+# gem "kredis"
+
+# Use Active Model has_secure_password [https://guides.rubyonrails.org/active_model_basics.html#securepassword]
+# gem "bcrypt", "~> 3.1.7"
+
+# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
+gem "tzinfo-data", platforms: %i[ mswin mswin64 mingw x64_mingw jruby ]
+
+# Reduces boot times through caching; required in config/boot.rb
+gem "bootsnap", require: false
+
+gem "graphql", "~> 2.3.0"
+
+group :development, :test do
+  # See https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
+  gem "debug", platforms: %i[ mri mswin mswin64 mingw x64_mingw ]
+end
+
+group :development do
+  # Use console on exceptions pages [https://github.com/rails/web-console]
+  gem "web-console"
+
+  # Add speed badges [https://github.com/MiniProfiler/rack-mini-profiler]
+  # gem "rack-mini-profiler"
+
+  # Speed up commands on slow machines / big apps [https://github.com/rails/spring]
+  # gem "spring"
+
+  gem "error_highlight", ">= 0.4.0", platforms: [:ruby]
+end
+
+group :test do
+  # Use system testing [https://guides.rubyonrails.org/testing.html#system-testing]
+  gem "capybara"
+  gem "selenium-webdriver"
+end

data/examples/subscriptions/README.md

@@ -0,0 +1,38 @@
+# Subscriptions example
+
+This example demonstrates stitching subscriptions in a small Rails application. No database required, just bundle-install and try running it:
+
+```shell
+cd examples/subscriptions
+bundle install
+bin/rails s
+```
+
+Then visit the GraphiQL client running at [`http://localhost:3000`](http://localhost:3000) and try subscribing:
+
+```graphql
+subscription SubscribeToComments {
+  commentAddedToPost(postId: "1") {
+    post { 
+      id 
+      title
+      comments {
+        id
+        message
+      }
+    }
+    comment { 
+      id
+      message
+    }
+  }
+}
+```
+
+Upon running that subscription, you'll recieve an initial payload for the subscribe event that stitches post data from another schema. Now try triggering events by hitting this URL in another browser window:
+
+```
+http://localhost:3000/graphql/event
+```
+
+Each refresh of the above URL will add a comment and trigger a subscription event. Assuming you're subscribed, you should see comment activity appear in the GraphiQL output. Again, these update events are stitched to enrich the basic subscription payload with additional data from another schema.

data/examples/subscriptions/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require_relative "config/application"
+
+Rails.application.load_tasks

data/examples/subscriptions/app/channels/graphql_channel.rb

@@ -0,0 +1,50 @@
+class GraphqlChannel < ActionCable::Channel::Base
+  def subscribed
+    @subscription_ids = []
+  end
+
+  def execute(data)
+    result = StitchedSchema.execute(
+      data["query"],
+      context: { channel: self },
+      variables: ensure_hash(data["variables"]),
+      operation_name: data["operationName"],
+    )
+
+    payload = {
+      result: result.to_h,
+      more: result.subscription?,
+    }
+
+    if result.context[:subscription_id]
+      @subscription_ids << result.context[:subscription_id]
+    end
+
+    transmit(payload)
+  end
+
+  def unsubscribed
+    @subscription_ids.each { |sid|
+      SubscriptionsSchema.subscriptions.delete_subscription(sid)
+    }
+  end
+
+  private
+
+  def ensure_hash(ambiguous_param)
+    case ambiguous_param
+    when String
+      if ambiguous_param.present?
+        ensure_hash(JSON.parse(ambiguous_param))
+      else
+        {}
+      end
+    when Hash, ActionController::Parameters
+      ambiguous_param
+    when nil
+      {}
+    else
+      raise ArgumentError, "Unexpected parameter: #{ambiguous_param}"
+    end
+  end
+end

data/examples/subscriptions/app/controllers/graphql_controller.rb

@@ -0,0 +1,44 @@
+class GraphqlController < ActionController::Base
+  skip_before_action :verify_authenticity_token
+  layout false
+
+  def client
+  end
+
+  def execute
+    result = StitchedSchema.execute(
+      params[:query],
+      variables: ensure_hash(params[:variables]), 
+      context: {}, 
+      operation_name: params[:operationName],
+    )
+
+    render json: result
+  end
+
+  COMMENTS = ["Great", "Meh", "Terrible"].freeze
+
+  def event
+    comment = Repository.add_comment("1", COMMENTS.sample)
+    render json: comment
+  end
+
+  private
+
+  def ensure_hash(ambiguous_param)
+    case ambiguous_param
+    when String
+      if ambiguous_param.present?
+        ensure_hash(JSON.parse(ambiguous_param))
+      else
+        {}
+      end
+    when Hash, ActionController::Parameters
+      ambiguous_param
+    when nil
+      {}
+    else
+      raise ArgumentError, "Unexpected parameter: #{ambiguous_param}"
+    end
+  end
+end

data/examples/subscriptions/app/graphql/entities_schema.rb

@@ -0,0 +1,42 @@
+class EntitiesSchema < GraphQL::Schema
+  class StitchingResolver < GraphQL::Schema::Directive
+    graphql_name "stitch"
+    locations FIELD_DEFINITION
+    argument :key, String, required: true
+    argument :arguments, String, required: false
+    repeatable true
+  end
+
+  class Comment < GraphQL::Schema::Object
+    field :id, ID, null: false
+    field :message, String, null: false
+  end
+
+  class Post < GraphQL::Schema::Object
+    field :id, ID, null: false
+    field :title, String, null: false
+    field :comments, [Comment, null: false], null: false
+  end
+
+  class QueryType < GraphQL::Schema::Object
+    field :posts, [Post, null: true] do
+      directive StitchingResolver, key: "id"
+      argument :ids, [ID], required: true
+    end
+
+    def posts(ids:)
+      ids.map { Repository.post(_1) }
+    end
+
+    field :comments, [Comment, null: true] do
+      directive StitchingResolver, key: "id"
+      argument :ids, [ID], required: true
+    end
+
+    def comments(ids:)
+      ids.map { Repository.comment(_1) }
+    end
+  end
+
+  query QueryType
+end

data/examples/subscriptions/app/graphql/stitched_schema.rb

@@ -0,0 +1,10 @@
+require_relative "../../../../lib/graphql/stitching"
+
+StitchedSchema = GraphQL::Stitching::Client.new(locations: {
+  entities: {
+    schema: EntitiesSchema,
+  },
+  subscriptions: {
+    schema: SubscriptionsSchema,
+  },
+})

data/examples/subscriptions/app/graphql/subscriptions_schema.rb

@@ -0,0 +1,54 @@
+class SubscriptionsSchema < GraphQL::Schema
+  class StitchedActionCableSubscriptions < GraphQL::Subscriptions::ActionCableSubscriptions
+    def execute_update(subscription_id, event, object)
+      super(subscription_id, event, object).tap do |result|
+        result.context[:stitch_subscription_update]&.call(result)
+      end
+    end
+  end
+
+  class Post < GraphQL::Schema::Object
+    field :id, ID, null: false
+  end
+
+  class Comment < GraphQL::Schema::Object
+    field :id, ID, null: false
+  end
+
+  class CommentAddedToPost < GraphQL::Schema::Subscription
+    argument :post_id, ID, required: true
+    field :post, Post, null: false
+    field :comment, Comment, null: true
+
+    def subscribe(post_id:)
+      {
+        post: { id: post_id },
+        comment: nil,
+      }
+    end
+
+    def update(post_id:)
+      {
+        post: { id: post_id },
+        comment: object,
+      }
+    end
+  end
+
+  class SubscriptionType < GraphQL::Schema::Object
+    field :comment_added_to_post, subscription: CommentAddedToPost
+  end
+
+  class QueryType < GraphQL::Schema::Object
+    field :ping, String
+
+    def ping
+      "PONG"
+    end
+  end
+
+  use StitchedActionCableSubscriptions
+
+  subscription SubscriptionType
+  query QueryType
+end

data/examples/subscriptions/app/models/repository.rb

@@ -0,0 +1,39 @@
+class Repository
+  POSTS = {}
+  COMMENTS = {}
+
+  class << self
+    def post(id)
+      POSTS.fetch(id)
+    end
+
+    def comment(id)
+      COMMENTS.fetch(id)
+    end
+
+    def add_post(title, id = Time.zone.now.to_i.to_s)
+      post = {
+        id: id,
+        title: title,
+        comments: [],
+      }
+      POSTS[post[:id]] = post
+      post
+    end
+
+    def add_comment(post_id, message)
+      comment = {
+        id: Time.zone.now.to_i.to_s,
+        message: message,
+      }
+      parent = post(post_id)
+      parent[:comments] << comment
+      COMMENTS[comment[:id]] = comment
+      
+      SubscriptionsSchema.subscriptions.trigger(:comment_added_to_post, { post_id: parent[:id] }, comment)
+      comment
+    end
+  end
+end
+
+Repository.add_post("How to walk, talk, and chew gum", "1")