graphql-stitching 1.4.3 → 1.5.0

data/examples/subscriptions/config/initializers/inflections.rb

@@ -0,0 +1,16 @@
+# Be sure to restart your server when you modify this file.
+
+# Add new inflection rules using the following format. Inflections
+# are locale specific, and you may define rules for as many different
+# locales as you wish. All of these examples are active by default:
+# ActiveSupport::Inflector.inflections(:en) do |inflect|
+#   inflect.plural /^(ox)$/i, "\\1en"
+#   inflect.singular /^(ox)en/i, "\\1"
+#   inflect.irregular "person", "people"
+#   inflect.uncountable %w( fish sheep )
+# end
+
+# These inflection rules are supported but not enabled by default:
+# ActiveSupport::Inflector.inflections(:en) do |inflect|
+#   inflect.acronym "RESTful"
+# end

data/examples/subscriptions/config/initializers/permissions_policy.rb

@@ -0,0 +1,13 @@
+# Be sure to restart your server when you modify this file.
+
+# Define an application-wide HTTP permissions policy. For further
+# information see: https://developers.google.com/web/updates/2018/06/feature-policy
+
+# Rails.application.config.permissions_policy do |policy|
+#   policy.camera      :none
+#   policy.gyroscope   :none
+#   policy.microphone  :none
+#   policy.usb         :none
+#   policy.fullscreen  :self
+#   policy.payment     :self, "https://secure.example.com"
+# end

data/examples/subscriptions/config/locales/en.yml

@@ -0,0 +1,31 @@
+# Files in the config/locales directory are used for internationalization and
+# are automatically loaded by Rails. If you want to use locales other than
+# English, add the necessary files in this directory.
+#
+# To use the locales, use `I18n.t`:
+#
+#     I18n.t "hello"
+#
+# In views, this is aliased to just `t`:
+#
+#     <%= t("hello") %>
+#
+# To use a different locale, set it with `I18n.locale`:
+#
+#     I18n.locale = :es
+#
+# This would use the information in config/locales/es.yml.
+#
+# To learn more about the API, please read the Rails Internationalization guide
+# at https://guides.rubyonrails.org/i18n.html.
+#
+# Be aware that YAML interprets the following case-insensitive strings as
+# booleans: `true`, `false`, `on`, `off`, `yes`, `no`. Therefore, these strings
+# must be quoted to be interpreted as strings. For example:
+#
+#     en:
+#       "yes": yup
+#       enabled: "ON"
+
+en:
+  hello: "Hello world"

data/examples/subscriptions/config/master.key

@@ -0,0 +1 @@
+b7cc7c63ca7597ff3f5fc4a6cb27b65d

data/examples/subscriptions/config/puma.rb

@@ -0,0 +1,35 @@
+# This configuration file will be evaluated by Puma. The top-level methods that
+# are invoked here are part of Puma's configuration DSL. For more information
+# about methods provided by the DSL, see https://puma.io/puma/Puma/DSL.html.
+
+# Puma can serve each request in a thread from an internal thread pool.
+# The `threads` method setting takes two numbers: a minimum and maximum.
+# Any libraries that use thread pools should be configured to match
+# the maximum value specified for Puma. Default is set to 5 threads for minimum
+# and maximum; this matches the default thread size of Active Record.
+max_threads_count = ENV.fetch("RAILS_MAX_THREADS") { 5 }
+min_threads_count = ENV.fetch("RAILS_MIN_THREADS") { max_threads_count }
+threads min_threads_count, max_threads_count
+
+# Specifies that the worker count should equal the number of processors in production.
+if ENV["RAILS_ENV"] == "production"
+  require "concurrent-ruby"
+  worker_count = Integer(ENV.fetch("WEB_CONCURRENCY") { Concurrent.physical_processor_count })
+  workers worker_count if worker_count > 1
+end
+
+# Specifies the `worker_timeout` threshold that Puma will use to wait before
+# terminating a worker in development environments.
+worker_timeout 3600 if ENV.fetch("RAILS_ENV", "development") == "development"
+
+# Specifies the `port` that Puma will listen on to receive requests; default is 3000.
+port ENV.fetch("PORT") { 3000 }
+
+# Specifies the `environment` that Puma will run in.
+environment ENV.fetch("RAILS_ENV") { "development" }
+
+# Specifies the `pidfile` that Puma will use.
+pidfile ENV.fetch("PIDFILE") { "tmp/pids/server.pid" }
+
+# Allow puma to be restarted by `bin/rails restart` command.
+plugin :tmp_restart

data/examples/subscriptions/config/routes.rb

@@ -0,0 +1,8 @@
+Rails.application.routes.draw do
+  mount ActionCable.server, at: "/cable"
+
+  post "/graphql", to: "graphql#execute"
+  get  "/graphql/event", to: "graphql#event"
+  
+  root "graphql#client"
+end

data/examples/subscriptions/config/storage.yml

@@ -0,0 +1,34 @@
+test:
+  service: Disk
+  root: <%= Rails.root.join("tmp/storage") %>
+
+local:
+  service: Disk
+  root: <%= Rails.root.join("storage") %>
+
+# Use bin/rails credentials:edit to set the AWS secrets (as aws:access_key_id|secret_access_key)
+# amazon:
+#   service: S3
+#   access_key_id: <%= Rails.application.credentials.dig(:aws, :access_key_id) %>
+#   secret_access_key: <%= Rails.application.credentials.dig(:aws, :secret_access_key) %>
+#   region: us-east-1
+#   bucket: your_own_bucket-<%= Rails.env %>
+
+# Remember not to checkin your GCS keyfile to a repository
+# google:
+#   service: GCS
+#   project: your_project
+#   credentials: <%= Rails.root.join("path/to/gcs.keyfile") %>
+#   bucket: your_own_bucket-<%= Rails.env %>
+
+# Use bin/rails credentials:edit to set the Azure Storage secret (as azure_storage:storage_access_key)
+# microsoft:
+#   service: AzureStorage
+#   storage_account_name: your_account_name
+#   storage_access_key: <%= Rails.application.credentials.dig(:azure_storage, :storage_access_key) %>
+#   container: your_container_name-<%= Rails.env %>
+
+# mirror:
+#   service: Mirror
+#   primary: local
+#   mirrors: [ amazon, google, microsoft ]

data/examples/subscriptions/config.ru

@@ -0,0 +1,6 @@
+# This file is used by Rack-based servers to start the application.
+
+require_relative "config/environment"
+
+run Rails.application
+Rails.application.load_server

data/examples/subscriptions/db/seeds.rb

@@ -0,0 +1,9 @@
+# This file should ensure the existence of records required to run the application in every environment (production,
+# development, test). The code here should be idempotent so that it can be executed at any point in every environment.
+# The data can then be loaded with the bin/rails db:seed command (or created alongside the database with db:setup).
+#
+# Example:
+#
+#   ["Action", "Comedy", "Drama", "Horror"].each do |genre_name|
+#     MovieGenre.find_or_create_by!(name: genre_name)
+#   end

data/examples/subscriptions/public/404.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>The page you were looking for doesn't exist (404)</title>
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+</head>
+
+<body class="rails-default-error-page">
+  <div class="dialog">
+    <div>
+      <h1>The page you were looking for doesn't exist.</h1>
+      <p>You may have mistyped the address or the page may have moved.</p>
+    </div>
+    <p>If you are the application owner check the logs for more information.</p>
+  </div>
+</body>
+</html>

data/examples/subscriptions/public/422.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>The change you wanted was rejected (422)</title>
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+</head>
+
+<body class="rails-default-error-page">
+  <div class="dialog">
+    <div>
+      <h1>The change you wanted was rejected.</h1>
+      <p>Maybe you tried to change something you didn't have access to.</p>
+    </div>
+    <p>If you are the application owner check the logs for more information.</p>
+  </div>
+</body>
+</html>

data/examples/subscriptions/public/500.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>We're sorry, but something went wrong (500)</title>
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+</head>
+
+<body class="rails-default-error-page">
+  <div class="dialog">
+    <div>
+      <h1>We're sorry, but something went wrong.</h1>
+    </div>
+    <p>If you are the application owner check the logs for more information.</p>
+  </div>
+</body>
+</html>

data/examples/subscriptions/public/robots.txt

@@ -0,0 +1 @@
+# See https://www.robotstxt.org/robotstxt.html for documentation on how to use the robots.txt file

data/lib/graphql/stitching/client.rb

@@ -4,20 +4,27 @@ require "json"
 
 module GraphQL
   module Stitching
+    # Client is an out-of-the-box helper that assembles all 
+    # stitching components into a workflow that executes requests.
     class Client
       class ClientError < StitchingError; end
 
+      # @return [Supergraph] composed supergraph that services incoming requests.
       attr_reader :supergraph
 
+      # Builds a new client instance. Either `supergraph` or `locations` configuration is required.
+      # @param supergraph [Supergraph] optional, a pre-composed supergraph that bypasses composer setup.
+      # @param locations [Hash<Symbol, Hash<Symbol, untyped>>] optional, composer configurations for each graph location.
+      # @param composer [Composer] optional, a pre-configured composer instance for use with `locations` configuration.
       def initialize(locations: nil, supergraph: nil, composer: nil)
         @supergraph = if locations && supergraph
           raise ClientError, "Cannot provide both locations and a supergraph."
-        elsif supergraph && !supergraph.is_a?(GraphQL::Stitching::Supergraph)
+        elsif supergraph && !supergraph.is_a?(Supergraph)
           raise ClientError, "Provided supergraph must be a GraphQL::Stitching::Supergraph instance."
         elsif supergraph
           supergraph
         else
-          composer ||= GraphQL::Stitching::Composer.new
+          composer ||= Composer.new
           composer.perform(locations)
         end
 
@@ -26,10 +33,10 @@ module GraphQL
         @on_error = nil
       end
 
-      def execute(query:, variables: nil, operation_name: nil, context: nil, validate: true)
-        request = GraphQL::Stitching::Request.new(
+      def execute(raw_query = nil, query: nil, variables: nil, operation_name: nil, context: nil, validate: true)
+        request = Request.new(
           @supergraph,
-          query,
+          raw_query || query, # << for parity with GraphQL Ruby Schema.execute
           operation_name: operation_name,
           variables: variables,
           context: context,
@@ -37,17 +44,17 @@ module GraphQL
 
         if validate
           validation_errors = request.validate
-          return error_result(validation_errors) if validation_errors.any?
+          return error_result(request, validation_errors) if validation_errors.any?
         end
 
         request.prepare!
         load_plan(request)
         request.execute
       rescue GraphQL::ParseError, GraphQL::ExecutionError => e
-        error_result([e])
+        error_result(request, [e])
       rescue StandardError => e
         custom_message = @on_error.call(request, e) if @on_error
-        error_result([{ "message" => custom_message || "An unexpected error occured." }])
+        error_result(request, [{ "message" => custom_message || "An unexpected error occured." }])
       end
 
       def on_cache_read(&block)
@@ -69,7 +76,7 @@ module GraphQL
 
       def load_plan(request)
         if @on_cache_read && plan_json = @on_cache_read.call(request)
-          plan = GraphQL::Stitching::Plan.from_json(JSON.parse(plan_json))
+          plan = Plan.from_json(JSON.parse(plan_json))
 
           # only use plans referencing current resolver versions
           if plan.ops.all? { |op| !op.resolver || @supergraph.resolvers_by_version[op.resolver] }
@@ -86,12 +93,12 @@ module GraphQL
         plan
       end
 
-      def error_result(errors)
+      def error_result(request, errors)
         public_errors = errors.map! do |e|
           e.is_a?(Hash) ? e : e.to_h
         end
 
-        { "errors" => public_errors }
+        GraphQL::Query::Result.new(query: request, values: { "errors" => public_errors })
       end
     end
   end

data/lib/graphql/stitching/composer/resolver_config.rb

@@ -38,7 +38,7 @@ module GraphQL::Stitching
               memo[field_path] << new(
                 key: key.to_definition,
                 type_name: entity_type.graphql_name,
-                arguments: "representations: { #{key_fields.join(", ")}, __typename: $.__typename }",
+                arguments: "representations: { #{key_fields.join(", ")}, #{TYPENAME}: $.#{TYPENAME} }",
               )
             end
           end

data/lib/graphql/stitching/composer/validate_resolvers.rb

@@ -5,10 +5,16 @@ module GraphQL::Stitching
     class ValidateResolvers < BaseValidator
 
       def perform(supergraph, composer)
+        root_types = [
+          supergraph.schema.query,
+          supergraph.schema.mutation,
+          supergraph.schema.subscription,
+        ].tap(&:compact!)
+        
         supergraph.schema.types.each do |type_name, type|
           # objects and interfaces that are not the root operation types
           next unless type.kind.object? || type.kind.interface?
-          next if supergraph.schema.query == type || supergraph.schema.mutation == type
+          next if root_types.include?(type)
           next if type.graphql_name.start_with?("__")
 
           # multiple subschemas implement the type

data/lib/graphql/stitching/composer.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
-require_relative "./composer/base_validator"
-require_relative "./composer/validate_interfaces"
-require_relative "./composer/validate_resolvers"
-require_relative "./composer/resolver_config"
+require_relative "composer/base_validator"
+require_relative "composer/validate_interfaces"
+require_relative "composer/validate_resolvers"
+require_relative "composer/resolver_config"
 
 module GraphQL
   module Stitching
+    # Composer receives many individual `GraphQL::Schema` instances 
+    # representing various graph locations and merges them into one 
+    # combined Supergraph that is validated for integrity.
     class Composer
       # @api private
       NO_DEFAULT_VALUE = begin
@@ -26,9 +29,9 @@ module GraphQL
       BASIC_ROOT_FIELD_LOCATION_SELECTOR = ->(locations, _info) { locations.last }
 
       # @api private
-      VALIDATORS = [
-        "ValidateInterfaces",
-        "ValidateResolvers",
+      COMPOSITION_VALIDATORS = [
+        ValidateInterfaces,
+        ValidateResolvers,
       ].freeze
 
       # @return [String] name of the Query type in the composed schema.
@@ -37,6 +40,9 @@ module GraphQL
       # @return [String] name of the Mutation type in the composed schema.
       attr_reader :mutation_name
 
+      # @return [String] name of the Subscription type in the composed schema.
+      attr_reader :subscription_name
+
       # @api private
       attr_reader :subgraph_types_by_name_and_location
 
@@ -46,6 +52,7 @@ module GraphQL
       def initialize(
         query_name: "Query",
         mutation_name: "Mutation",
+        subscription_name: "Subscription",
         description_merger: nil,
         deprecation_merger: nil,
         default_value_merger: nil,
@@ -54,23 +61,27 @@ module GraphQL
       )
         @query_name = query_name
         @mutation_name = mutation_name
+        @subscription_name = subscription_name
         @description_merger = description_merger || BASIC_VALUE_MERGER
         @deprecation_merger = deprecation_merger || BASIC_VALUE_MERGER
         @default_value_merger = default_value_merger || BASIC_VALUE_MERGER
         @directive_kwarg_merger = directive_kwarg_merger || BASIC_VALUE_MERGER
         @root_field_location_selector = root_field_location_selector || BASIC_ROOT_FIELD_LOCATION_SELECTOR
+        
+        @field_map = {}
+        @resolver_map = {}
         @resolver_configs = {}
-
-        @field_map = nil
-        @resolver_map = nil
-        @mapped_type_names = nil
+        @mapped_type_names = {}
         @subgraph_directives_by_name_and_location = nil
         @subgraph_types_by_name_and_location = nil
         @schema_directives = nil
       end
 
       def perform(locations_input)
-        reset!
+        if @subgraph_types_by_name_and_location
+          raise CompositionError, "Composer may only perform once per instance."
+        end
+
         schemas, executables = prepare_locations_input(locations_input)
 
         # "directive_name" => "location" => subgraph_directive
@@ -91,7 +102,6 @@ module GraphQL
         # "Typename" => "location" => subgraph_type
         @subgraph_types_by_name_and_location = schemas.each_with_object({}) do |(location, schema), memo|
           raise CompositionError, "Location keys must be strings" unless location.is_a?(String)
-          raise CompositionError, "The subscription operation is not supported." if schema.subscription
 
           introspection_types = schema.introspection_system.types.keys
           schema.types.each do |type_name, subgraph_type|
@@ -101,10 +111,13 @@ module GraphQL
               raise CompositionError, "Query name \"#{@query_name}\" is used by non-query type in #{location} schema."
             elsif type_name == @mutation_name && subgraph_type != schema.mutation
               raise CompositionError, "Mutation name \"#{@mutation_name}\" is used by non-mutation type in #{location} schema."
+            elsif type_name == @subscription_name && subgraph_type != schema.subscription
+              raise CompositionError, "Subscription name \"#{@subscription_name}\" is used by non-subscription type in #{location} schema."
             end
 
             type_name = @query_name if subgraph_type == schema.query
             type_name = @mutation_name if subgraph_type == schema.mutation
+            type_name = @subscription_name if subgraph_type == schema.subscription
             @mapped_type_names[subgraph_type.graphql_name] = type_name if subgraph_type.graphql_name != type_name
 
             memo[type_name] ||= {}
@@ -148,6 +161,7 @@ module GraphQL
           orphan_types(schema_types.values.select { |t| t.respond_to?(:kind) && t.kind.object? })
           query schema_types[builder.query_name]
           mutation schema_types[builder.mutation_name]
+          subscription schema_types[builder.subscription_name]
           directives builder.schema_directives.values
 
           own_orphan_types.clear
@@ -163,9 +177,8 @@ module GraphQL
           executables: executables,
         )
 
-        VALIDATORS.each do |validator|
-          klass = Object.const_get("GraphQL::Stitching::Composer::#{validator}")
-          klass.new.perform(supergraph, self)
+        COMPOSITION_VALIDATORS.each do |validator_class|
+          validator_class.new.perform(supergraph, self)
         end
 
         supergraph
@@ -588,7 +601,7 @@ module GraphQL
       # @!scope class
       # @!visibility private
       def select_root_field_locations(schema)
-        [schema.query, schema.mutation].tap(&:compact!).each do |root_type|
+        [schema.query, schema.mutation, schema.subscription].tap(&:compact!).each do |root_type|
           root_type.fields.each do |root_field_name, root_field|
             root_field_locations = @field_map[root_type.graphql_name][root_field_name]
             next unless root_field_locations.length > 1
@@ -660,16 +673,6 @@ module GraphQL
           memo[enum_name] << :write
         end
       end
-
-      private
-
-      def reset!
-        @field_map = {}
-        @resolver_map = {}
-        @mapped_type_names = {}
-        @subgraph_directives_by_name_and_location = nil
-        @schema_directives = nil
-      end
     end
   end
 end

data/lib/graphql/stitching/executor/shaper.rb

@@ -105,7 +105,7 @@ module GraphQL::Stitching
         is_root = parent_type == @root_type
 
         case node.name
-        when "__typename"
+        when TYPENAME
           yield(is_root)
           true
         when "__schema", "__type"

data/lib/graphql/stitching/executor.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
 require "json"
-require_relative "./executor/resolver_source"
-require_relative "./executor/root_source"
-require_relative "./executor/shaper"
+require_relative "executor/resolver_source"
+require_relative "executor/root_source"
+require_relative "executor/shaper"
 
 module GraphQL
   module Stitching
+    # Executor handles executing upon a planned request.
+    # All planned steps are initiated, their results merged,
+    # and loaded keys are collected for batching subsequent steps.
+    # Final execution results are then shaped to match the request selection.
     class Executor
       # @return [Request] the stitching request to execute.
       attr_reader :request
@@ -20,10 +24,14 @@ module GraphQL
       # @return [Integer] tally of queries performed while executing.
       attr_accessor :query_count
 
-      def initialize(request, nonblocking: false)
+      # Builds a new executor.
+      # @param request [Request] the stitching request to execute.
+      # @param nonblocking [Boolean] specifies if the dataloader should use async concurrency.
+      def initialize(request, data: {}, errors: [], after: 0, nonblocking: false)
         @request = request
-        @data = {}
-        @errors = []
+        @data = data
+        @errors = errors
+        @after = after
         @query_count = 0
         @exec_cycles = 0
         @dataloader = GraphQL::Dataloader.new(nonblocking: nonblocking)
@@ -40,13 +48,13 @@ module GraphQL
         if @errors.length > 0
           result["errors"] = @errors
         end
-
-        result
+        
+        GraphQL::Query::Result.new(query: @request, values: result)
       end
 
       private
 
-      def exec!(next_steps = [0])
+      def exec!(next_steps = [@after])
         if @exec_cycles > @request.plan.ops.length
           # sanity check... if we've exceeded queue size, then something went wrong.
           raise StitchingError, "Too many execution requests attempted."
@@ -58,8 +66,8 @@ module GraphQL
             .select { next_steps.include?(_1.after) }
             .group_by { [_1.location, _1.resolver.nil?] }
             .map do |(location, root_source), ops|
-              source_type = root_source ? RootSource : ResolverSource
-              @dataloader.with(source_type, self, location).request_all(ops)
+              source_class = root_source ? RootSource : ResolverSource
+              @dataloader.with(source_class, self, location).request_all(ops)
             end
 
           tasks.each(&method(:exec_task))

data/lib/graphql/stitching/http_executable.rb

@@ -6,6 +6,9 @@ require "json"
 
 module GraphQL
   module Stitching
+    # HttpExecutable provides an out-of-the-box convenience for sending 
+    # HTTP post requests to a remote location, or a base class 
+    # for other implementations with GraphQL multipart uploads.
     class HttpExecutable
       # Builds a new executable for proxying subgraph requests via HTTP.
       # @param url [String] the url of the remote location to proxy.

data/lib/graphql/stitching/plan.rb

@@ -2,7 +2,7 @@
 
 module GraphQL
   module Stitching
-    # Immutable (in theory) structures representing a query plan.
+    # Immutable-ish structures representing a query plan.
     # May serialize to/from JSON.
     class Plan
       Op = Struct.new(

data/lib/graphql/stitching/planner.rb

@@ -1,14 +1,13 @@
 # frozen_string_literal: true
 
-require_relative "./planner/step"
+require_relative "planner/step"
 
 module GraphQL
   module Stitching
+    # Planner partitions request selections by best-fit graph locations,
+    # and provides a query plan with sequential execution steps.
     class Planner
       SUPERGRAPH_LOCATIONS = [Supergraph::SUPERGRAPH_LOCATION].freeze
-      TYPENAME = "__typename"
-      QUERY_OP = "query"
-      MUTATION_OP = "mutation"
       ROOT_INDEX = 0
 
       def initialize(request)
@@ -126,6 +125,7 @@ module GraphQL
               parent_index: ROOT_INDEX,
               parent_type: parent_type,
               selections: selections,
+              operation_type: QUERY_OP,
             )
           end
 
@@ -154,6 +154,22 @@ module GraphQL
             ).index
           end
 
+        when SUBSCRIPTION_OP
+          parent_type = @supergraph.schema.subscription
+
+          each_field_in_scope(parent_type, @request.operation.selections) do |node|
+            raise StitchingError, "Too many root fields for subscription." unless @steps_by_entrypoint.empty?
+
+            locations = @supergraph.locations_by_type_and_field[parent_type.graphql_name][node.name] || SUPERGRAPH_LOCATIONS
+            add_step(
+              location: locations.first,
+              parent_index: ROOT_INDEX,
+              parent_type: parent_type,
+              selections: [node],
+              operation_type: SUBSCRIPTION_OP,
+            )
+          end
+
         else
           raise StitchingError, "Invalid operation type."
         end
@@ -281,7 +297,7 @@ module GraphQL
               parent_selections.push(*resolver.key.export_nodes) if resolver.key
               parent_selections.uniq! do |node|
                 export_node = node.is_a?(GraphQL::Language::Nodes::Field) && Resolver.export_key?(node.alias)
-                export_node ? node.alias : node
+                export_node ? node.alias : node.object_id
               end
 
               # E.2) Add a planner step for each new entrypoint location.

data/lib/graphql/stitching/{skip_include.rb → request/skip_include.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-module GraphQL
-  module Stitching
+module GraphQL::Stitching
+  class Request
     # Faster implementation of an AST visitor for prerendering
     # @skip and @include conditional directives into a document.
     # This avoids unnecessary planning steps, and prepares result shaping.