graphql_backed 0.1.0

data/lib/graphql_backed/operation.rb

@@ -0,0 +1,248 @@
+# typed: strict
+# frozen_string_literal: true
+
+module GraphQLBacked
+  # A GraphQL query or mutation with a single root field (subscriptions aren't supported).
+  # It includes each Resource by spreading its class name:
+  #
+  #     class GetUser < GraphQLBacked::Operation
+  #       graphql <<~GRAPHQL
+  #         query GetUser($id: ID!) {
+  #           user(id: $id) { ...Resources::User }
+  #         }
+  #       GRAPHQL
+  #     end
+  #
+  # When .graphql is called, the string is parsed and flattened: each `...Resources::User` is replaced with
+  # a valid GraphQL fragment name and the fragment of each referenced Resource is appended, transitively.
+  # .query_string returns the flattened GraphQL.
+  # It's validated against a schema when it's added to a Service, which also runs it.
+  #
+  # An operation can describe itself for the people or agents who'll call it (for example, as an MCP tool, see GraphQLBacked::MCP):
+  #
+  #     class ArchiveUser < GraphQLBacked::Operation
+  #       description "Archive a user by ID"
+  #       destructive false # default: true for mutations, false for queries
+  #       idempotent true   # default: false for mutations, true for queries
+  #       open_world false  # default: true
+  #
+  #       graphql <<~GRAPHQL
+  #         mutation ArchiveUser($id: ID!) {
+  #           archiveUser(id: $id) { ...Resources::User }
+  #         }
+  #       GRAPHQL
+  #     end
+  #
+  # It can also configure the method and path that it's served at over HTTP (see GraphQLBacked::REST):
+  #
+  #     class GetUser < GraphQLBacked::Operation
+  #       route :get, "/users/:id" # default: `GET /GetUser` for queries, `POST /GetUser` for mutations
+  #       # ...
+  #     end
+  class Operation
+    class << self
+      # Assign the GraphQL document for this operation, then flatten it.
+      #
+      #: (String graphql_string) -> void
+      def graphql(graphql_string)
+        document, resources = ResourceReferences.parse(graphql_string, owner: self)
+        operations = document.definitions.grep(GraphQL::Language::Nodes::OperationDefinition)
+        operation = operations.first
+        if operations.size != 1 || operation.nil?
+          raise InvalidDocumentError, "#{name}: an Operation must contain exactly one query or mutation"
+        end
+        if operation.operation_type == "subscription"
+          raise InvalidDocumentError, "#{name}: subscriptions aren't supported, an Operation must be a query or mutation"
+        end
+        root_field = operation.selections.first
+        if operation.selections.size != 1 || !root_field.is_a?(GraphQL::Language::Nodes::Field)
+          raise InvalidDocumentError, "#{name}: an Operation must select exactly one root field"
+        end
+
+        resources = resources.dup
+        # Appending while iterating visits each resource once, so cycles end here; they're reported when a Service validates the document
+        resources.each { |resource| resources.concat(resource.resources - resources) }
+        document = document.merge(definitions: document.definitions + resources.map(&:fragment_definition))
+
+        @document = document #: GraphQL::Language::Nodes::Document?
+        @fragments = document.definitions.grep(GraphQL::Language::Nodes::FragmentDefinition).to_h { |f| [f.name, f] } #: Hash[String, GraphQL::Language::Nodes::FragmentDefinition]?
+        @definition = operation #: GraphQL::Language::Nodes::OperationDefinition?
+        @query_string = document.to_query_string #: String?
+        @operation_type = (operation.operation_type || "query").to_sym #: Symbol?
+        @root_field_name = root_field.name #: String?
+        @resources = resources #: Array[singleton(Resource)]?
+      end
+
+      # Get or set a description of what this operation does, for the people or agents who'll call it:
+      #
+      #     class GetUser < GraphQLBacked::Operation
+      #       description "Look up a user by ID"
+      #       # ...
+      #     end
+      #
+      #: (?String? new_description) -> String?
+      def description(new_description = nil)
+        if new_description
+          @description = new_description #: String?
+        end
+        @description
+      end
+
+      # The name which identifies this operation within a Service: the class name without its namespaces.
+      #
+      #     Operations::GetUser.public_name # => "GetUser"
+      #
+      #: -> String
+      def public_name
+        class_name = name || raise(Error, "Anonymous Operation classes aren't supported, assign it to a constant")
+        class_name.split("::").last #: as !nil
+      end
+
+      # The flattened GraphQL string: this operation, followed by the fragments of its resources.
+      #
+      #: -> String
+      def query_string
+        @query_string || raise(Error, "#{name} has no GraphQL document, add one with `graphql \"...\"`")
+      end
+
+      # The parsed form of .query_string, including resources' fragments. A Service validates and executes this;
+      # to inspect the operation, use .definition.
+      #
+      #: -> GraphQL::Language::Nodes::Document
+      def document
+        query_string
+        @document #: as !nil
+      end
+
+      # The query or mutation in .document, for inspecting its name, variables and selections.
+      #
+      #: -> GraphQL::Language::Nodes::OperationDefinition
+      def definition
+        query_string
+        @definition #: as !nil
+      end
+
+      # Every fragment that .definition may spread, by name: those written in this operation's GraphQL
+      # and those of its .resources (named by Resource.fragment_name).
+      #
+      #: -> Hash[String, GraphQL::Language::Nodes::FragmentDefinition]
+      def fragments
+        query_string
+        @fragments #: as !nil
+      end
+
+      # `:query` or `:mutation`
+      #
+      #: -> Symbol
+      def operation_type
+        query_string
+        @operation_type #: as !nil
+      end
+
+      #: -> bool
+      def query?
+        operation_type == :query
+      end
+
+      #: -> bool
+      def mutation?
+        operation_type == :mutation
+      end
+
+      # Configure whether this operation may delete or overwrite data. See .destructive?
+      #
+      #: (bool new_value) -> void
+      def destructive(new_value)
+        @destructive = new_value #: bool?
+      end
+
+      # Whether this operation may delete or overwrite data, as opposed to only adding to it.
+      # Unless configured with .destructive, mutations are assumed to be destructive and queries aren't.
+      #
+      #: -> bool
+      def destructive?
+        @destructive.nil? ? mutation? : @destructive
+      end
+
+      # Configure whether repeating this operation with the same input has no further effect. See .idempotent?
+      #
+      #: (bool new_value) -> void
+      def idempotent(new_value)
+        @idempotent = new_value #: bool?
+      end
+
+      # Whether repeating this operation with the same input has no further effect.
+      # Unless configured with .idempotent, queries are assumed to be idempotent and mutations aren't.
+      #
+      #: -> bool
+      def idempotent?
+        @idempotent.nil? ? query? : @idempotent
+      end
+
+      # Configure whether this operation interacts with things outside of your system. See .open_world?
+      #
+      #: (bool new_value) -> void
+      def open_world(new_value)
+        @open_world = new_value #: bool?
+      end
+
+      # Whether this operation interacts with an open set of things outside of your system (for example, the web),
+      # as opposed to only your system's own data. True unless configured with .open_world.
+      #
+      #: -> bool
+      def open_world?
+        @open_world.nil? ? true : @open_world
+      end
+
+      # Configure how this operation is served over HTTP by Service.rest_app (see GraphQLBacked::REST):
+      #
+      #     route :get, "/users/:id"
+      #
+      # `http_method` is `:get`, `:post`, `:put`, `:patch` or `:delete`. Each `:name` in `path` is passed
+      # as the variable `$name`.
+      #
+      #: (Symbol http_method, String path) -> void
+      def route(http_method, path)
+        if !REST::HTTP_METHODS.include?(http_method)
+          raise ArgumentError, "#{name}: expected one of #{REST::HTTP_METHODS.map(&:inspect).join(", ")}, but got #{http_method.inspect}"
+        end
+        if !path.start_with?("/")
+          raise ArgumentError, "#{name}: a path must start with \"/\", but got #{path.inspect}"
+        end
+        @http_method = http_method #: Symbol?
+        @path = path #: String?
+      end
+
+      # The HTTP method which this operation is served with. Unless configured with .route,
+      # queries are `:get` and mutations are `:post`.
+      #
+      #: -> Symbol
+      def http_method
+        @http_method || (query? ? :get : :post)
+      end
+
+      # The path which this operation is served at. Unless configured with .route, it's `/` followed by .public_name.
+      #
+      #: -> String
+      def path
+        @path || "/#{public_name}"
+      end
+
+      # The name of the single root field selected by this operation.
+      #
+      #: -> String
+      def root_field_name
+        query_string
+        @root_field_name #: as !nil
+      end
+
+      # Every Resource included in this operation, directly or through another resource.
+      #
+      #: -> Array[singleton(Resource)]
+      def resources
+        query_string
+        @resources #: as !nil
+      end
+    end
+  end
+end

data/lib/graphql_backed/resource.rb

@@ -0,0 +1,71 @@
+# typed: strict
+# frozen_string_literal: true
+
+module GraphQLBacked
+  # A reusable selection on a GraphQL Object, Interface or Union type, written as a fragment:
+  #
+  #     class Resources::User < GraphQLBacked::Resource
+  #       graphql <<~GRAPHQL
+  #         fragment on User {
+  #           id
+  #           name
+  #           organization { ...Resources::Organization }
+  #         }
+  #       GRAPHQL
+  #     end
+  #
+  # Operations (and other Resources) include it by spreading its class name: `...Resources::User`.
+  #
+  # The fragment must not have a name; in flattened operations it's named after the class (see .fragment_name).
+  # A resource must be defined (or autoloadable) before it's referenced.
+  # Resources are only parsed when defined. They're validated against a schema as part of each Operation that uses them, when it's added to a Service.
+  class Resource
+    class << self
+      # Assign the GraphQL fragment for this resource.
+      #
+      #: (String graphql_string) -> void
+      def graphql(graphql_string)
+        document, resources = ResourceReferences.parse(graphql_string, owner: self)
+        definition = document.definitions.first
+        if document.definitions.size != 1 || !definition.is_a?(GraphQL::Language::Nodes::FragmentDefinition)
+          raise InvalidDocumentError, "#{name}: a Resource must contain exactly one fragment definition"
+        end
+        if definition.name
+          raise InvalidDocumentError, "#{name}: a Resource's fragment must not be named, use `fragment on #{definition.type.name} { ... }` instead of `fragment #{definition.name} on ...`"
+        end
+        @type_name = definition.type.name #: String?
+        @fragment_definition = definition.merge(name: fragment_name) #: GraphQL::Language::Nodes::FragmentDefinition?
+        @resources = resources #: Array[singleton(Resource)]?
+      end
+
+      # The name of the GraphQL type that this resource's fragment applies to.
+      #
+      #: -> String
+      def type_name
+        @type_name || raise(Error, "#{name} has no GraphQL fragment, add one with `graphql \"...\"`")
+      end
+
+      # The name given to this resource's fragment in flattened operations, eg `Resources__User`.
+      #
+      #: -> String
+      def fragment_name
+        (name || raise(Error, "Anonymous Resource classes aren't supported, assign it to a constant")).gsub("::", "__")
+      end
+
+      # This resource's fragment, named .fragment_name, with references to other resources replaced by their fragment names.
+      #
+      #: -> GraphQL::Language::Nodes::FragmentDefinition
+      def fragment_definition
+        @fragment_definition || raise(Error, "#{name} has no GraphQL fragment, add one with `graphql \"...\"`")
+      end
+
+      # Other resources directly referenced by this one.
+      #
+      #: -> Array[singleton(Resource)]
+      def resources
+        fragment_definition
+        @resources #: as !nil
+      end
+    end
+  end
+end

data/lib/graphql_backed/resource_references.rb

@@ -0,0 +1,64 @@
+# typed: strict
+# frozen_string_literal: true
+
+module GraphQLBacked
+  # Replaces references to Resource classes in GraphQL strings with valid GraphQL.
+  #
+  # A reference is a fragment spread whose name is a Ruby constant, eg `...Resources::User`.
+  # It's replaced by a spread of that resource's Resource.fragment_name, eg `...Resources__User`.
+  module ResourceReferences # :nodoc:
+    # Strings and comments are matched first so that anything which looks like a reference inside them is left alone
+    PATTERN = /""".*?"""|"(?:\\.|[^"\\\n])*"|\#[^\n]*|(?<spread>\.\.\.\s*)(?<const_path>[A-Z]\w*(?:::[A-Z]\w*)*)/m #: Regexp
+
+    LOCAL_FRAGMENT = /\bfragment\s+(?!on\b)(\w+)/ #: Regexp
+
+    # Returns valid GraphQL for `graphql_string`, and the Resource classes it referenced.
+    #
+    #: (String graphql_string, owner: (singleton(Operation) | singleton(Resource))) -> [String, Array[singleton(Resource)]]
+    def self.replace(graphql_string, owner:)
+      resources = [] #: Array[singleton(Resource)]
+      local_fragment_names = graphql_string.scan(LOCAL_FRAGMENT).flatten
+      replaced_string = graphql_string.gsub(PATTERN) do |match|
+        const_path = $~[:const_path] #: as String?
+        # A spread of a fragment defined in the same string wins, like a local variable would
+        next match if const_path.nil? || local_fragment_names.include?(const_path)
+        resource = lookup(const_path, owner)
+        if resource
+          resources << resource unless resources.include?(resource)
+          "#{$~[:spread]}#{resource.fragment_name}"
+        elsif const_path.include?("::")
+          raise InvalidDocumentError, "#{owner.name}: `...#{const_path}` doesn't name a GraphQLBacked::Resource"
+        else
+          match # GraphQL validation will report this if there's no such fragment
+        end
+      end
+      [replaced_string, resources]
+    end
+
+    # Like .replace, but also parses the result.
+    #
+    #: (String graphql_string, owner: (singleton(Operation) | singleton(Resource))) -> [GraphQL::Language::Nodes::Document, Array[singleton(Resource)]]
+    def self.parse(graphql_string, owner:)
+      replaced_string, resources = replace(graphql_string, owner: owner)
+      [GraphQL.parse(replaced_string), resources]
+    rescue GraphQL::ParseError => err
+      raise InvalidDocumentError, "#{owner.name}: #{err.message}"
+    end
+
+    # Resolve `const_path` (eg `Resources::User`) to a Resource class,
+    # searching the namespaces enclosing `owner` first, like Ruby's own constant lookup.
+    #
+    #: (String const_path, (singleton(Operation) | singleton(Resource)) owner) -> singleton(Resource)?
+    def self.lookup(const_path, owner)
+      namespaces = owner.name.to_s.split("::")
+      namespaces.pop
+      namespaces.length.downto(0) do |depth|
+        candidate = [*namespaces.first(depth), const_path].join("::")
+        next unless Object.const_defined?(candidate)
+        const = Object.const_get(candidate)
+        return const if const.is_a?(Class) && const < Resource
+      end
+      nil
+    end
+  end
+end

data/lib/graphql_backed/rest/app.rb

@@ -0,0 +1,227 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+
+module GraphQLBacked
+  module REST
+    # A Rack app which serves a Service's operations as JSON over HTTP. Build one with REST.app or Service.rest_app.
+    class App
+      # Requests with these methods don't have variables in their bodies
+      NO_BODY_METHODS = ["GET", "DELETE"].freeze #: Array[String]
+
+      # Where the OpenAPI document is served, if the app was built with `openapi:`
+      OPENAPI_PATH = "/openapi.json"
+
+      JSON_HEADERS = { "content-type" => "application/json" }.freeze #: Hash[String, String]
+      private_constant :JSON_HEADERS
+
+      # Raised inside #call to respond with an error
+      class RequestError < Error # :nodoc:
+        #: Integer
+        attr_reader :status
+
+        #: (Integer status, String message) -> void
+        def initialize(status, message)
+          @status = status
+          super(message)
+        end
+      end
+
+      # One operation, and how requests are matched to it
+      class Route # :nodoc:
+        #: singleton(Operation)
+        attr_reader :operation_class
+
+        #: String
+        attr_reader :http_method
+
+        #: String
+        attr_reader :path
+
+        # The names of the variables in #path
+        #
+        #: Array[String]
+        attr_reader :path_params
+
+        # The GraphQL type of each of the operation's variables, by name
+        #
+        #: Hash[String, untyped]
+        attr_reader :variable_types
+
+        # The key of the root field's value in the `"data"` of a response
+        #
+        #: String
+        attr_reader :response_key
+
+        #: (singleton(Service) service, singleton(Operation) operation_class) -> void
+        def initialize(service, operation_class)
+          @operation_class = operation_class
+          @http_method = operation_class.http_method.to_s.upcase #: String
+          @path = operation_class.path #: String
+          root_field = operation_class.definition.selections.first #: untyped
+          @response_key = root_field.alias || root_field.name #: String
+          @variable_types = operation_class.definition.variables.to_h do |variable|
+            [variable.name, service.schema.type_from_ast(variable.type)]
+          end #: Hash[String, untyped]
+
+          @path_params = [] #: Array[String]
+          segments = @path.split("/").reject(&:empty?).map do |segment|
+            next Regexp.escape(segment) unless segment.start_with?(":")
+            name = segment.delete_prefix(":")
+            if !@variable_types.key?(name)
+              raise Error, "#{operation_class.name}'s path (#{@path}) has `:#{name}`, but the operation has no `$#{name}` variable"
+            end
+            @path_params << name
+            "(?<#{name}>[^/]+)"
+          end
+          @pattern = Regexp.new("\\A/#{segments.join("/")}/?\\z") #: Regexp
+        end
+
+        # The variables in `path`, if it matches this route
+        #
+        #: (String path) -> Hash[String, String]?
+        def match(path)
+          @pattern.match(path)&.named_captures&.transform_values { |value| ::Rack::Utils.unescape_path(value) }
+        end
+
+        # Values from the path and query string are strings, so convert them to what their variables expect.
+        # Anything which can't be converted is left for GraphQL to report.
+        #
+        #: (Hash[String, untyped] params) -> Hash[String, untyped]
+        def coerce(params)
+          params.to_h do |name, value|
+            type = @variable_types[name]
+            [name, type ? coerce_value(type, value) : value]
+          end
+        end
+
+        private
+
+        #: (untyped type, untyped value) -> untyped
+        def coerce_value(type, value)
+          if type.non_null?
+            coerce_value(type.of_type, value)
+          elsif type.list?
+            value.is_a?(Array) ? value.map { |item| coerce_value(type.of_type, item) } : coerce_value(type.of_type, value)
+          elsif type.kind.input_object? && value.is_a?(Hash)
+            arguments = type.arguments
+            value.to_h { |key, item| [key, arguments.key?(key) ? coerce_value(arguments[key].type, item) : item] }
+          elsif value.is_a?(String)
+            converted = case type.graphql_name
+            when "Int" then Integer(value, 10, exception: false)
+            when "Float" then Float(value, exception: false)
+            when "Boolean" then { "true" => true, "false" => false }[value]
+            end #: untyped
+            converted.nil? ? value : converted
+          else
+            value
+          end
+        end
+      end
+
+      # See REST.app for these options.
+      #
+      #: (singleton(Service) service, ?context: untyped, ?prefix: String?, ?openapi: untyped) -> void
+      def initialize(service, context: {}, prefix: nil, openapi: nil)
+        @openapi = openapi #: untyped
+        @service = service
+        @context = context #: untyped
+        @prefix = prefix&.delete_suffix("/") #: String?
+        @routes = service.rest_routes #: Array[Route]
+      end
+
+      # The method and path of each operation:
+      #
+      #     MyService.rest_app.routes # => [["GET", "/users/:id", GetUser], ["POST", "/RenameUser", RenameUser]]
+      #
+      #: -> Array[[String, String, singleton(Operation)]]
+      def routes
+        @routes.map { |route| [route.http_method, route.path, route.operation_class] }
+      end
+
+      # Handle a request and return a Rack response: `[status, headers, body]`.
+      # See REST for how requests are matched to operations and how responses are built.
+      #
+      #: (Hash[String, untyped] env) -> [Integer, Hash[String, String], Array[String]]
+      def call(env)
+        request = ::Rack::Request.new(env)
+        full_path = request.path_info
+        path = full_path
+        if @prefix && !@prefix.empty?
+          if path != @prefix && !path.start_with?("#{@prefix}/")
+            raise RequestError.new(404, "No operation for #{full_path}")
+          end
+          path = path.delete_prefix(@prefix)
+        end
+        matches = @routes.filter_map do |route|
+          path_params = route.match(path)
+          [route, path_params] if path_params
+        end
+        if matches.empty?
+          return [200, JSON_HEADERS.dup, [openapi_json]] if @openapi && path == OPENAPI_PATH && request.get?
+          raise RequestError.new(404, "No operation for #{full_path}")
+        end
+        route, path_params = matches.find { |(route, _path_params)| route.http_method == request.request_method }
+        if route.nil? || path_params.nil?
+          allow = matches.map { |(route, _path_params)| route.http_method }.uniq.join(", ")
+          return [405, JSON_HEADERS.merge("allow" => allow), [JSON.generate(error_body("#{request.request_method} isn't supported for #{full_path}"))]]
+        end
+
+        variables = route.coerce(query_params(request)).merge(body_params(request), route.coerce(path_params))
+        context = @context.respond_to?(:call) ? @context.call(request) : @context
+        response = @service.execute(route.operation_class, variables: variables, context: context)
+        if !response.key?("errors")
+          [200, JSON_HEADERS.dup, [JSON.generate(response.fetch("data")[route.response_key])]]
+        else
+          # Without `data`, the operation didn't run, because the variables weren't valid
+          [response.key?("data") ? 422 : 400, JSON_HEADERS.dup, [JSON.generate(response)]]
+        end
+      rescue RequestError => err
+        [err.status, JSON_HEADERS.dup, [JSON.generate(error_body(err.message))]]
+      end
+
+      private
+
+      #: (::Rack::Request request) -> Hash[String, untyped]
+      def query_params(request)
+        request.GET
+      rescue ::Rack::QueryParser::ParameterTypeError, ::Rack::QueryParser::InvalidParameterError, RangeError
+        raise RequestError.new(400, "The query string couldn't be parsed")
+      end
+
+      #: (::Rack::Request request) -> Hash[String, untyped]
+      def body_params(request)
+        return {} if NO_BODY_METHODS.include?(request.request_method)
+        input = request.body
+        return {} if input.nil?
+        # Something else may have read it already, like Rails when it parses params
+        input.rewind if input.respond_to?(:rewind)
+        body = input.read
+        return {} if body.nil? || body.empty?
+        params = JSON.parse(body)
+        raise RequestError.new(400, "The request body must be a JSON object") unless params.is_a?(Hash)
+        params
+      rescue JSON::ParserError
+        raise RequestError.new(400, "The request body isn't valid JSON")
+      end
+
+      # The service keeps it, so it isn't built again for each app or request
+      #
+      #: -> String
+      def openapi_json
+        options = @openapi.is_a?(Hash) ? @openapi : {}
+        # Operations' paths in the document don't include the prefix
+        options = { servers: [{ url: @prefix }] }.merge(options) if @prefix && !@prefix.empty?
+        @service.openapi_json(**options)
+      end
+
+      # Shaped like a GraphQL response, so that every error has the same structure
+      #
+      #: (String message) -> Hash[String, untyped]
+      def error_body(message)
+        { "errors" => [{ "message" => message }] }
+      end
+    end
+  end
+end