graphql-stitching 1.1.1 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9cdcb3361e391ba9b6dd78aa38c308c08ddb6fde2720d15208e8dfb96c3006ea
-  data.tar.gz: 9f64b024bda3987d1c523cf52b49f0ca2dfd688ac4c89bbf18de30c88c098156
+  metadata.gz: 4cb8c0d3b16cda5db8b82d0d0f9eba93a4537c3faa584b1b301dc84b34b5fd0e
+  data.tar.gz: 83f4b436479307ac8575f718ace5a82288024a6e5741f786151e55920d7ef61f
 SHA512:
-  metadata.gz: b51bcfeaa20e9cdea6c2d4b4e472e8c23e13ec8af36e1b23852603d0329045af064e3ae738467a0823be0c9f545105acba001b708c207eb7f08d51ebf0791e1f
-  data.tar.gz: c529e74c88fc7193d7823d8c92a488b3e459b5ba9f88e8d62355ae2bd5e9eb0ed2b0d6f7fd14b6b8ed13ab1bb53a93bc5da49dcecd5deb92ee180fa70604c80b
+  metadata.gz: e247e539e223a1fbefcd398c1aeb3940fa91320b81c45caeaa21b3ddca50631ffb6ddbd3963cde07f11609cbaacc1f814a167fefebab8f888979afe929bcb93f
+  data.tar.gz: 66de3bacb73749bd90b4d8e7ade4bf35cc144e0ae60b3ff1c81a5f548b20d74e204454b6727875984da293b4b3853aa9bf6215283666f2b037a7dc148e8aa64b

data/.yardopts

@@ -0,0 +1,5 @@
+--no-private
+--markup=markdown
+--readme=readme.md
+--title='GraphQL Stitching Ruby API Documentation'
+'lib/**/*.rb' - '*.md'

data/Gemfile

@@ -3,9 +3,6 @@
 source 'https://rubygems.org'
 gemspec
 
-gem 'rack'
-gem 'rackup'
-gem 'foreman'
 gem 'pry'
 gem 'pry-byebug'
 gem 'warning'

data/README.md

@@ -10,6 +10,7 @@ GraphQL stitching composes a single schema from multiple underlying GraphQL reso
 - Shared objects, fields, enums, and inputs across locations.
 - Combining local and remote schemas.
 - Type merging via arbitrary queries or federation `_entities` protocol.
+- File uploads via [multipart form spec](https://github.com/jaydenseric/graphql-multipart-request-spec).
 
 **NOT Supported:**
 - Computed fields (ie: federation-style `@requires`).
@@ -80,6 +81,7 @@ While the `Client` constructor is an easy quick start, the library also has seve
 - [Request](./docs/request.md) - prepares a requested GraphQL document and variables for stitching.
 - [Planner](./docs/planner.md) - builds a cacheable query plan for a request document.
 - [Executor](./docs/executor.md) - executes a query plan with given request variables.
+- [HttpExecutable](./docs/http_executable.md) - proxies requests to remotes with multipart file upload support.
 
 ## Merged types
 
@@ -360,11 +362,11 @@ It's perfectly fine to mix and match schemas that implement an `_entities` query
 
 ## Executables
 
-An executable resource performs location-specific GraphQL requests. Executables may be `GraphQL::Schema` classes, or any object that responds to `.call(location, source, variables, context)` and returns a raw GraphQL response:
+An executable resource performs location-specific GraphQL requests. Executables may be `GraphQL::Schema` classes, or any object that responds to `.call(request, source, variables)` and returns a raw GraphQL response:
 
 ```ruby
 class MyExecutable
-  def call(location, source, variables, context)
+  def call(request, source, variables)
     # process a GraphQL request...
     return {
       "data" => { ... },
@@ -392,12 +394,12 @@ supergraph = GraphQL::Stitching::Composer.new.perform({
   },
   fourth: {
     schema: FourthSchema,
-    executable: ->(loc, query, vars, ctx) { ... },
+    executable: ->(req, query, vars) { ... },
   },
 })
 ```
 
-The `GraphQL::Stitching::HttpExecutable` class is provided as a simple executable wrapper around `Net::HTTP.post`. You should build your own executables to leverage your existing libraries and to add instrumentation. Note that you must manually assign all executables to a `Supergraph` when rehydrating it from cache ([see docs](./docs/supergraph.md)).
+The `GraphQL::Stitching::HttpExecutable` class is provided as a simple executable wrapper around `Net::HTTP.post` with [file upload](./docs/http_executable.md#graphql-file-uploads) support. You should build your own executables to leverage your existing libraries and to add instrumentation. Note that you must manually assign all executables to a `Supergraph` when rehydrating it from cache ([see docs](./docs/supergraph.md)).
 
 ## Batching
 
@@ -431,36 +433,12 @@ The [Executor](./docs/executor.md) component builds atop the Ruby fiber-based im
 - [Stitched errors](./docs/mechanics.md#stitched-errors)
 - [Null results](./docs/mechanics.md#null-results)
 
-## Example
+## Examples
 
-This repo includes a working example of several stitched schemas running across small Rack servers. Try running it:
+This repo includes working examples of stitched schemas running across small Rack servers. Clone the repo, `cd` into each example and try running it following its README instructions.
 
-```shell
-bundle install
-foreman start
-```
-
-Then visit the gateway service at `http://localhost:3000` and try this query:
-
-```graphql
-query {
-  storefront(id: "1") {
-    id
-    products {
-      upc
-      name
-      price
-      manufacturer {
-        name
-        address
-        products { upc name }
-      }
-    }
-  }
-}
-```
-
-The above query collects data from all locations, two of which are remote schemas and the third a local schema. The combined graph schema is also stitched in to provide introspection capabilities.
+- [Merged types](./examples/merged_types)
+- [File uploads](./examples/file_uploads)
 
 ## Tests
 

data/docs/README.md

@@ -12,6 +12,7 @@ Major components include:
 - [Request](./request.md) - prepares a requested GraphQL document and variables for stitching.
 - [Planner](./planner.md) - builds a cacheable query plan for a request document.
 - [Executor](./executor.md) - executes a query plan with given request variables.
+- [HttpExecutable](./http_executable.md) - proxies requests to remotes with multipart file upload support.
 
 Additional topics:
 

data/docs/client.md

@@ -60,11 +60,11 @@ The client provides cache hooks to enable caching query plans across requests. W
 
 ```ruby
 client.on_cache_read do |request|
-  $redis.get(request.digest) # << 3P code
+  $cache.get(request.digest) # << 3P code
 end
 
 client.on_cache_write do |request, payload|
-  $redis.set(request.digest, payload) # << 3P code
+  $cache.set(request.digest, payload) # << 3P code
 end
 ```
 

data/docs/composer.md

@@ -90,7 +90,7 @@ Location settings have top-level keys that specify arbitrary location names, eac
 
 - **`schema:`** _required_, provides a `GraphQL::Schema` class for the location. This may be a class-based schema that inherits from `GraphQL::Schema`, or built from SDL (Schema Definition Language) string using `GraphQL::Schema.from_definition` and mapped to a remote location. The provided schema is only used for type reference and does not require any real data resolvers (unless it is also used as the location's executable, see below).
 
-- **`executable:`** _optional_, provides an executable resource to be called when delegating a request to this location. Executables are `GraphQL::Schema` classes or any object with a `.call(location, source, variables, context)` method that returns a GraphQL response. Omitting the executable option will use the location's provided `schema` as the executable resource.
+- **`executable:`** _optional_, provides an executable resource to be called when delegating a request to this location. Executables are `GraphQL::Schema` classes or any object with a `.call(request, source, variables)` method that returns a GraphQL response. Omitting the executable option will use the location's provided `schema` as the executable resource.
 
 - **`stitch:`** _optional_, an array of configs used to dynamically apply `@stitch` directives to select root fields prior to composing. This is useful when you can't easily render stitching directives into a location's source schema.
 

data/docs/executor.md

@@ -13,22 +13,18 @@ query = <<~GRAPHQL
 GRAPHQL
 
 request = GraphQL::Stitching::Request.new(
+  supergraph,
   query,
   variables: { "id" => "123" },
   operation_name: "MyQuery",
   context: { ... },
 )
 
-plan = GraphQL::Stitching::Planner.new(
-  supergraph: supergraph,
-  request: request,
-).perform
+# Via Request:
+result = request.execute
 
-result = GraphQL::Stitching::Executor.new(
-  supergraph: supergraph,
-  request: request,
-  plan: plan,
-).perform
+# Via Executor:
+result = GraphQL::Stitching::Executor.new(request).perform
 ```
 
 ### Raw results
@@ -36,12 +32,9 @@ result = GraphQL::Stitching::Executor.new(
 By default, execution results are always returned with document shaping (stitching additions removed, missing fields added, null bubbling applied). You may access the raw execution result by calling the `perform` method with a `raw: true` argument:
 
 ```ruby
-# get the raw result without shaping
-raw_result = GraphQL::Stitching::Executor.new(
-  supergraph: supergraph,
-  request: request,
-  plan: plan,
-).perform(raw: true)
+# get the raw result without shaping using either form:
+raw_result = request.execute(raw: true)
+raw_result = GraphQL::Stitching::Executor.new(request).perform(raw: true)
 ```
 
 The raw result will contain many irregularities from the stitching process, however may be insightful when debugging inconsistencies in results:

data/docs/http_executable.md

@@ -0,0 +1,51 @@
+## GraphQL::Stitching::HttpExecutable
+
+A `HttpExecutable` provides an out-of-the-box convenience for sending HTTP post requests to a remote location, or a base class for your own implementation with [GraphQL multipart uploads](https://github.com/jaydenseric/graphql-multipart-request-spec).
+
+```ruby
+exe = GraphQL::Stitching::HttpExecutable.new(
+  url: "http://localhost:3001",
+  headers: {
+    "Authorization" => "..."
+  }
+)
+```
+
+### GraphQL file uploads
+
+The [GraphQL Upload Spec](https://github.com/jaydenseric/graphql-multipart-request-spec) defines a multipart form structure for submitting GraphQL requests with file upload attachments. It's possible to pass these requests through stitched schemas using the following:
+
+#### 1. Input file uploads as Tempfile variables
+
+```ruby
+client.execute(
+  "mutation($file: Upload) { upload(file: $file) }",
+  variables: { "file" => Tempfile.new(...) }
+)
+```
+
+File uploads must enter the stitched schema as standard GraphQL variables with `Tempfile` values. The simplest way to recieve this input is to install [apollo_upload_server](https://github.com/jetruby/apollo_upload_server-ruby) into your stitching app's middleware so that multipart form submissions automatically unpack into standard variables.
+
+#### 2. Enable `HttpExecutable.upload_types`
+
+```ruby
+client = GraphQL::Stitching::Client.new(locations: {
+  alpha: {
+    schema: GraphQL::Schema.from_definition(...),
+    executable: GraphQL::Stitching::HttpExecutable.new(
+      url: "http://localhost:3000",
+      upload_types: ["Upload"], # << extract `Upload` scalars into multipart forms
+    ),
+  },
+  bravo: {
+    schema: GraphQL::Schema.from_definition(...),
+    executable: GraphQL::Stitching::HttpExecutable.new(
+      url: "http://localhost:3001"
+    ),
+  },
+})
+```
+
+A location's `HttpExecutable` can then re-package `Tempfile` variables into multipart forms before sending them upstream. This is enabled with an `upload_types` parameter that specifies which scalar names require form extraction. Enabling `upload_types` does add some additional subgraph request processing, so it should only be enabled for locations that will actually recieve file uploads.
+
+The upstream location will recieve a multipart form submission from stitching that can again be unpacked using [apollo_upload_server](https://github.com/jetruby/apollo_upload_server-ruby) or similar.

data/docs/planner.md

@@ -13,15 +13,17 @@ document = <<~GRAPHQL
 GRAPHQL
 
 request = GraphQL::Stitching::Request.new(
+  supergraph,
   document,
   variables: { "id" => "1" },
   operation_name: "MyQuery",
 ).prepare!
 
-plan = GraphQL::Stitching::Planner.new(
-  supergraph: supergraph,
-  request: request,
-).perform
+# Via Request:
+plan = request.plan
+
+# Via Planner:
+plan = GraphQL::Stitching::Planner.new(request).perform
 ```
 
 ### Caching
@@ -29,18 +31,14 @@ plan = GraphQL::Stitching::Planner.new(
 Plans are designed to be cacheable. This is very useful for redundant GraphQL documents (commonly sent by frontend clients) where there's no sense in planning every request individually. It's far more efficient to generate a plan once and cache it, then simply retreive the plan and execute it for future requests.
 
 ```ruby
-cached_plan = $redis.get(request.digest)
+cached_plan = $cache.get(request.digest)
 
-plan = if cached_plan
-  GraphQL::Stitching::Plan.from_json(JSON.parse(cached_plan))
+if cached_plan
+  plan = GraphQL::Stitching::Plan.from_json(JSON.parse(cached_plan))
+  request.plan(plan)
 else
-  plan = GraphQL::Stitching::Planner.new(
-    supergraph: supergraph,
-    request: request,
-  ).perform
-
-  $redis.set(request.digest, JSON.generate(plan.as_json))
-  plan
+  plan = request.plan
+  $cache.set(request.digest, JSON.generate(plan.as_json))
 end
 
 # execute the plan...

data/docs/request.md

@@ -5,6 +5,7 @@ A `Request` contains a parsed GraphQL document and variables, and handles the lo
 ```ruby
 source = "query FetchMovie($id: ID!) { movie(id:$id) { id genre } }"
 request = GraphQL::Stitching::Request.new(
+  supergraph,
   source,
   variables: { "id" => "1" },
   operation_name: "FetchMovie",
@@ -42,6 +43,7 @@ document = <<~GRAPHQL
 GRAPHQL
 
 request = GraphQL::Stitching::Request.new(
+  supergraph,
   document,
   variables: { "id" => "1" },
   operation_name: "FetchMovie",

data/docs/supergraph.md

@@ -10,7 +10,7 @@ A Supergraph is designed to be composed, cached, and restored. Calling `to_defin
 supergraph_sdl = supergraph.to_definition
 
 # stash this composed schema in a cache...
-$redis.set("cached_supergraph_sdl", supergraph_sdl)
+$cache.set("cached_supergraph_sdl", supergraph_sdl)
 
 # or, write the composed schema as a file into your repo...
 File.write("supergraph/schema.graphql", supergraph_sdl)
@@ -19,7 +19,7 @@ File.write("supergraph/schema.graphql", supergraph_sdl)
 To restore a Supergraph, call `from_definition` providing the cached SDL string and a hash of executables keyed by their location names:
 
 ```ruby
-supergraph_sdl = $redis.get("cached_supergraph_sdl")
+supergraph_sdl = $cache.get("cached_supergraph_sdl")
 
 supergraph = GraphQL::Stitching::Supergraph.from_definition(
   supergraph_sdl,

data/examples/file_uploads/Gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'rack'
+gem 'rackup'
+gem 'foreman'
+gem 'graphql'
+gem 'apollo_upload_server', '2.1'

data/examples/file_uploads/Procfile

@@ -0,0 +1,2 @@
+gateway: bundle exec ruby gateway.rb
+remote: bundle exec ruby remote.rb

data/examples/file_uploads/README.md

@@ -0,0 +1,37 @@
+# File uploads example
+
+This example demonstrates uploading files via the [GraphQL Upload spec](https://github.com/jaydenseric/graphql-multipart-request-spec).
+
+Try running it:
+
+```shell
+cd examples/file_uploads
+bundle install
+foreman start
+```
+
+This example is headless, but you can verify the stitched schema is running by querying a field from each graph location:
+
+```shell
+curl -X POST http://localhost:3000 \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"{ gateway remote }"}'
+```
+
+Now try submitting a multipart form upload with a file attachment, per the [spec](https://github.com/jaydenseric/graphql-multipart-request-spec?tab=readme-ov-file#curl-request). The response will echo the uploaded file contents:
+
+```shell
+curl http://localhost:3000 \
+  -H 'Content-Type: multipart/form-data' \
+  -F operations='{ "query": "mutation ($file: Upload!) { gateway upload(file: $file) }", "variables": { "file": null } }' \
+  -F map='{ "0": ["variables.file"] }' \
+  -F 0=@file.txt
+```
+
+This workflow has:
+
+1. Submitted a multipart form to the stitched gateway.
+2. The gateway server unpacked the request using [apollo_upload_server](https://github.com/jetruby/apollo_upload_server-ruby).
+3. Stitching delegated the `upload` field to its appropraite subgraph location.
+4. `HttpExecutable` has re-encoded the subgraph request into a multipart form.
+5. The subgraph location has recieved, unpacked, and resolved the uploaded file.

data/examples/file_uploads/file.txt

@@ -0,0 +1 @@
+Hello World!

data/examples/file_uploads/gateway.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'rackup'
+require 'json'
+require 'graphql'
+require_relative '../../lib/graphql/stitching'
+require_relative './helpers'
+
+class StitchedApp
+  def initialize
+    @client = GraphQL::Stitching::Client.new(locations: {
+      gateway: {
+        schema: GatewaySchema,
+      },
+      remote: {
+        schema: RemoteSchema,
+        executable: GraphQL::Stitching::HttpExecutable.new(
+          url: "http://localhost:3001",
+          upload_types: ["Upload"]
+        ),
+      },
+    })
+  end
+
+  def call(env)
+    params = apollo_upload_server_middleware_params(env)
+    result = @client.execute(
+      query: params["query"],
+      variables: params["variables"],
+      operation_name: params["operationName"],
+    )
+
+    [200, {"content-type" => "application/json"}, [JSON.generate(result)]]
+  end
+end
+
+Rackup::Handler.default.run(StitchedApp.new, :Port => 3000)

data/examples/file_uploads/helpers.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'action_dispatch'
+require 'apollo_upload_server/graphql_data_builder'
+require 'apollo_upload_server/upload'
+
+# ApolloUploadServer middleware only modifies Rails request params;
+# for simple Rack apps we need to extract the behavior.
+def apollo_upload_server_middleware_params(env)
+  req = ActionDispatch::Request.new(env)
+  if env['CONTENT_TYPE'].to_s.include?('multipart/form-data')
+    ApolloUploadServer::GraphQLDataBuilder.new(strict_mode: true).call(req.params)
+  else
+    req.params
+  end
+end
+
+# Gateway local schema
+class GatewaySchema < GraphQL::Schema
+  class Query < GraphQL::Schema::Object
+    field :gateway, Boolean, null: false
+
+    def gateway
+      true
+    end
+  end
+
+  class Mutation < GraphQL::Schema::Object
+    field :gateway, Boolean, null: false
+
+    def gateway
+      true
+    end
+  end
+
+  query Query
+  mutation Mutation
+end
+
+# Remote local schema, with file upload
+class RemoteSchema < GraphQL::Schema
+  class Query < GraphQL::Schema::Object
+    field :remote, Boolean, null: false
+
+    def remote
+      true
+    end
+  end
+
+  class Mutation < GraphQL::Schema::Object
+    field :upload, String, null: true do
+      argument :file, ApolloUploadServer::Upload, required: true
+    end
+
+    def upload(file:)
+      file.read
+    end
+  end
+
+  query Query
+  mutation Mutation
+end

data/examples/file_uploads/remote.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'rackup'
+require 'json'
+require 'graphql'
+require_relative './helpers'
+
+class RemoteApp
+  def call(env)
+    params = apollo_upload_server_middleware_params(env)
+    result = RemoteSchema.execute(
+      query: params["query"],
+      variables: params["variables"],
+      operation_name: params["operationName"],
+    )
+
+    [200, {"content-type" => "application/json"}, [JSON.generate(result)]]
+  end
+end
+
+Rackup::Handler.default.run(RemoteApp.new, :Port => 3001)

data/examples/merged_types/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'rack'
+gem 'rackup'
+gem 'foreman'
+gem 'graphql'

data/examples/merged_types/Procfile

@@ -0,0 +1,3 @@
+gateway: bundle exec ruby gateway.rb
+remote1: bundle exec ruby remote1.rb
+remote2: bundle exec ruby remote2.rb

data/examples/merged_types/README.md

@@ -0,0 +1,33 @@
+# Merged types example
+
+This example demonstrates several stitched schemas running across small Rack servers with types merged across locations. The main "gateway" location stitches its local schema onto two remote endpoints.
+
+Try running it:
+
+```shell
+cd examples/merged_types
+bundle install
+foreman start
+```
+
+Then visit the gateway service at [`http://localhost:3000`](http://localhost:3000) and try this query:
+
+```graphql
+query {
+  storefront(id: "1") {
+    id
+    products {
+      upc
+      name
+      price
+      manufacturer {
+        name
+        address
+        products { upc name }
+      }
+    }
+  }
+}
+```
+
+The above query collects data from all locations. You can also request introspections that resolve using the combined supergraph schema.

data/{example → examples/merged_types}/gateway.rb

@@ -2,10 +2,9 @@
 
 require 'rackup'
 require 'json'
-require 'byebug'
 require 'graphql'
-require 'graphql/stitching'
-require_relative '../test/schemas/example'
+require_relative '../../lib/graphql/stitching'
+require_relative '../../test/schemas/example'
 
 class StitchedApp
   def initialize
@@ -19,11 +18,11 @@ class StitchedApp
       },
       storefronts: {
         schema: Schemas::Example::Storefronts,
-        executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001/graphql"),
+        executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3001"),
       },
       manufacturers: {
         schema: Schemas::Example::Manufacturers,
-        executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3002/graphql"),
+        executable: GraphQL::Stitching::HttpExecutable.new(url: "http://localhost:3002"),
       }
     })
   end

data/examples/merged_types/remote1.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'rackup'
+require 'json'
+require 'graphql'
+require_relative '../../test/schemas/example'
+
+class FirstRemoteApp
+  def call(env)
+    req = Rack::Request.new(env)
+    params = JSON.parse(req.body.read)
+    result = Schemas::Example::Storefronts.execute(
+      query: params["query"],
+      variables: params["variables"],
+      operation_name: params["operationName"],
+    )
+
+    [200, {"content-type" => "application/json"}, [JSON.generate(result)]]
+  end
+end
+
+Rackup::Handler.default.run(FirstRemoteApp.new, :Port => 3001)

data/examples/merged_types/remote2.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'rackup'
+require 'json'
+require 'graphql'
+require_relative '../../test/schemas/example'
+
+class SecondRemoteApp
+  def call(env)
+    req = Rack::Request.new(env)
+    params = JSON.parse(req.body.read)
+    result = Schemas::Example::Manufacturers.execute(
+      query: params["query"],
+      variables: params["variables"],
+      operation_name: params["operationName"],
+    )
+
+    [200, {"content-type" => "application/json"}, [JSON.generate(result)]]
+  end
+end
+
+Rackup::Handler.default.run(SecondRemoteApp.new, :Port => 3002)