graphql-stitching 1.4.3 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a72adc399f618790fc1aefe1b6dca07709d45f10cc2936f5c3978d75b5d3f8c2
-  data.tar.gz: d45d7b73045755a750d6d4334e00e30f33c5124f83c849c24669c98f7912ca92
+  metadata.gz: d8fb3561ddb47de2d07bdcdf32e940e1a151dff731081b2b4bffe09489809021
+  data.tar.gz: 9163e0d0e5116e232ee0594821d02568f85405c7fdc0f80e085e713d2e4d3a71
 SHA512:
-  metadata.gz: 5302083cb9047ad77aa5e6276d02e3bdac8256ef328edb8c72b9248efbb279c48bb3e34b8e220f131d3efa541fdaa1b682fe4622501900defe797217cbc365c8
-  data.tar.gz: 4e238de4607764406ac52634daafc293c1b5fe672457106ff1070e77bc4d52cdc1ace02ce46ca4cacbcde7648d8a4f2bb8cc0321157dfb3c85c3ec40d5f82e43
+  metadata.gz: 6823d661a3f812fbf11bbf14edf66f3da27a850399f909061c63d464d3be93777fe7f9c7158ea26cc0d1889aed04749d3ad10cd42c3ca76079604447ab66e3cc
+  data.tar.gz: 27dee9de11b90e960fb0c17d68129332ede38d237ef37ae1eca4cdca2c83696dec4b6c9f0283ee7f508c4f5076029afc81efa4b58d60e5b74411a6a368092947

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](./docs/subscriptions.md).
 - 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).
+- [File uploads](./docs/http_executable.md) via multipart forms.
 - 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.
 
@@ -34,7 +35,7 @@ require "graphql/stitching"
 
 ## Usage
 
-The quickest way to start is to use the provided [`Client`](./docs/client.md) component that wraps a stitched graph in an executable workflow (with optional query plan caching hooks):
+The [`Client`](./docs/client.md) component builds a stitched graph wrapped in an executable workflow (with optional query plan caching hooks):
 
 ```ruby
 movies_schema = <<~GRAPHQL
@@ -74,7 +75,7 @@ result = client.execute(
 
 Schemas provided in [location settings](./docs/composer.md#performing-composition) may be class-based schemas with local resolvers (locally-executable schemas), or schemas built from SDL strings (schema definition language parsed using `GraphQL::Schema.from_definition`) and mapped to remote locations via [executables](#executables).
 
-While the `Client` constructor is an easy quick start, the library also has several discrete components that can be assembled into custom workflows:
+While `Client` is sufficient for most usecases, the library offers several discrete components that can be assembled into tailored workflows:
 
 - [Composer](./docs/composer.md) - merges and validates many schemas into one supergraph.
 - [Supergraph](./docs/supergraph.md) - manages the combined schema, location routing maps, and executable resources. Can be exported, cached, and rehydrated.
@@ -87,7 +88,7 @@ While the `Client` constructor is an easy quick start, the library also has seve
 
 ![Merging types](./docs/images/merging.png)
 
-To facilitate this merging of types, stitching must know how to cross-reference and fetch each variant of a type from its source location using [resolver queries](#merged-type-resolver-queries). For those in an Apollo ecosystem, there's also _limited_ support for merging types though a [federation `_entities` protocol](./docs/federation_entities.md).
+To facilitate this merging of types, stitching must know how to cross-reference and fetch each variant of a type from its source location using [type resolver queries](#merged-type-resolver-queries). For those in an Apollo ecosystem, there's also _limited_ support for merging types though a [federation `_entities` protocol](./docs/federation_entities.md).
 
 ### Merged type resolver queries
 
@@ -248,7 +249,7 @@ type Query {
 }
 ```
 
-See [resolver arguments](./docs/resolver.md#arguments) for full documentation on shaping input.
+See [resolver arguments](./docs/type_resolver.md#arguments) for full documentation on shaping input.
 
 #### Composite type keys
 
@@ -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)
@@ -456,6 +458,7 @@ This repo includes working examples of stitched schemas running across small Rac
 
 - [Merged types](./examples/merged_types)
 - [File uploads](./examples/file_uploads)
+- [Subscriptions](./examples/subscriptions)
 
 ## Tests
 

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/client.md

@@ -68,6 +68,12 @@ client.on_cache_write do |request, payload|
 end
 ```
 
+All request digests use SHA2 by default. You can swap in [a faster algorithm](https://github.com/Shopify/blake3-rb) and/or add base scoping by reconfiguring the stitching library:
+
+```ruby
+GraphQL::Stitching.digest { |str| Digest::MD5.hexdigest("v2/#{str}") }
+```
+
 Note that inlined input data works against caching, so you should _avoid_ these input literals when possible:
 
 ```graphql

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 the 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 composed 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 out 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)
+    result = super(subscription_id, event, object)
+    result.context[:stitch_subscription_update]&.call(result)
+    result
+  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/docs/{resolver.md → type_resolver.md}

@@ -1,10 +1,10 @@
-## GraphQL::Stitching::Resolver
+## GraphQL::Stitching::TypeResolver
 
-A `Resolver` contains all information about a root query used by stitching to fetch location-specific variants of a merged type. Specifically, resolvers manage parsed keys and argument structures.
+A `TypeResolver` contains all information about a root query used by stitching to fetch location-specific variants of a merged type. Specifically, resolvers manage parsed keys and argument structures.
 
 ### Arguments
 
-Resolvers configure arguments through a template string of [GraphQL argument literal syntax](https://spec.graphql.org/October2021/#sec-Language.Arguments). This allows sending multiple arguments that intermix stitching keys with complex object shapes and other static values.
+Type resolvers configure arguments through a template string of [GraphQL argument literal syntax](https://spec.graphql.org/October2021/#sec-Language.Arguments). This allows sending multiple arguments that intermix stitching keys with complex object shapes and other static values.
 
 #### Key insertions
 

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,
+  },
+})