graphql_backed 0.1.0

data/lib/graphql_backed/rest/open_api.rb

@@ -0,0 +1,179 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+
+module GraphQLBacked
+  module REST
+    # Builds an OpenAPI document which describes a Service's REST app. See REST.openapi.
+    class OpenAPI # :nodoc:
+      VERSION = "3.1.0"
+
+      # Error responses are shaped like GraphQL responses. See App#call.
+      ERROR_CONTENT = {
+        "application/json" => {
+          "schema" => {
+            "type" => "object",
+            "properties" => {
+              "errors" => {
+                "type" => "array",
+                "items" => { "type" => "object", "properties" => { "message" => { "type" => "string" } }, "required" => ["message"] },
+              },
+            },
+            "required" => ["errors"],
+          },
+        },
+      }.freeze #: Hash[String, untyped]
+
+      RESPONSES = {
+        "BadRequest" => { "description" => "The request couldn't be parsed, or its variables weren't valid", "content" => ERROR_CONTENT },
+        "UnprocessableContent" => { "description" => "The operation ran, but it returned errors. `data` has the rest of its result.", "content" => ERROR_CONTENT },
+      }.freeze #: Hash[String, untyped]
+
+      #: (singleton(Service) service) -> void
+      def initialize(service)
+        @service = service
+        @scalars = service.scalar_json_schemas #: Hash[String, Hash[String, untyped]]
+        @schemas = {} #: Hash[String, untyped]
+      end
+
+      # `info` is merged into the document's `info`, and `document` into the document itself.
+      #
+      #: (info: Hash[untyped, untyped], document: Hash[untyped, untyped]) -> Hash[String, untyped]
+      def to_h(info:, document:)
+        paths = {} #: Hash[String, Hash[String, untyped]]
+        @service.rest_routes.each do |route|
+          path = route.path.split("/").map { |segment| segment.start_with?(":") ? "{#{segment.delete_prefix(":")}}" : segment }.join("/")
+          path = "/" if path.empty?
+          (paths[path] ||= {})[route.http_method.downcase] = operation(route)
+        end
+        result = {
+          "openapi" => VERSION,
+          "info" => { "title" => @service.name || "GraphQLBacked", "version" => "1.0.0" }.merge(JSON.parse(JSON.generate(info))),
+        } #: Hash[String, untyped]
+        result.merge!(JSON.parse(JSON.generate(document)))
+        result["paths"] = paths
+        result["components"] = { "schemas" => @schemas, "responses" => RESPONSES }
+        result
+      end
+
+      private
+
+      #: (App::Route route) -> Hash[String, untyped]
+      def operation(route)
+        operation_class = route.operation_class
+        input = components(operation_class, JSONSchema.input(@service.schema, operation_class, scalars: @scalars))
+        output = components(operation_class, JSONSchema.output(@service.schema, operation_class, scalars: @scalars))
+        required = input["required"] || [] #: Array[String]
+        has_body = !App::NO_BODY_METHODS.include?(route.http_method)
+
+        parameters = [] #: Array[Hash[String, untyped]]
+        body_properties = {} #: Hash[String, untyped]
+        input.fetch("properties").each do |name, json_schema|
+          if route.path_params.include?(name)
+            parameters << parameter(route, name, "path", true, json_schema)
+          elsif has_body
+            body_properties[name] = json_schema
+          else
+            parameters << parameter(route, name, "query", required.include?(name), json_schema)
+          end
+        end
+
+        result = { "operationId" => operation_class.public_name } #: Hash[String, untyped]
+        description = operation_class.description || root_field_description(operation_class)
+        result["description"] = description if description
+        result["parameters"] = parameters if parameters.any?
+        if body_properties.any?
+          body_schema = { "type" => "object", "properties" => body_properties } #: Hash[String, untyped]
+          body_required = required & body_properties.keys
+          body_schema["required"] = body_required if body_required.any?
+          result["requestBody"] = { "required" => body_required.any?, "content" => { "application/json" => { "schema" => body_schema } } }
+        end
+        result["responses"] = {
+          "200" => {
+            "description" => "The result of `#{operation_class.root_field_name}`",
+            "content" => { "application/json" => { "schema" => output.fetch("properties").fetch(route.response_key) } },
+          },
+          "400" => { "$ref" => "#/components/responses/BadRequest" },
+          "422" => { "$ref" => "#/components/responses/UnprocessableContent" },
+        }
+        result
+      end
+
+      #: (singleton(Operation) operation_class) -> String?
+      def root_field_description(operation_class)
+        root_type = @service.schema.root_type_for_operation(operation_class.operation_type.to_s)
+        root_type.get_field(operation_class.root_field_name)&.description
+      end
+
+      # `location` is `"path"` or `"query"`
+      #
+      #: (App::Route route, String name, String location, bool required, Hash[String, untyped] json_schema) -> Hash[String, untyped]
+      def parameter(route, name, location, required, json_schema)
+        result = { "name" => name, "in" => location, "required" => required } #: Hash[String, untyped]
+        description = json_schema["description"]
+        result["description"] = description if description
+        result["schema"] = json_schema.except("description")
+        if location == "query"
+          type = route.variable_types.fetch(name) #: untyped
+          type = type.of_type if type.non_null?
+          if type.list?
+            # Rack only makes a list from keys which end with `[]`
+            result["name"] = "#{name}[]"
+          elsif type.kind.input_object?
+            # eg `filter[role]=ADMIN`
+            result["style"] = "deepObject"
+            result["explode"] = true
+          end
+        end
+        result
+      end
+
+      # Moves the `$defs` of `json_schema` into this document's shared schemas, and returns `json_schema` referring to them there.
+      # Operations usually have the same definition for the same name (an input object or a Resource),
+      # but if they don't (eg, for different fragments with the same name), the later one is renamed after its operation.
+      #
+      #: (singleton(Operation) operation_class, Hash[String, untyped] json_schema) -> Hash[String, untyped]
+      def components(operation_class, json_schema)
+        defs = json_schema.delete("$defs") || {} #: Hash[String, untyped]
+        names = defs.to_h { |name, _definition| [name, name] } #: Hash[String, String]
+        renames = {} #: Hash[String, Integer]
+        # A definition depends on the names of those it refers to, so go around until no more are renamed
+        loop do
+          renamed = false #: bool
+          defs.each do |name, definition|
+            existing = @schemas[names.fetch(name)]
+            next if existing.nil? || existing == with_component_refs(definition, names)
+            count = renames.fetch(name, 0) + 1
+            renames[name] = count
+            names[name] = count == 1 ? "#{operation_class.public_name}_#{name}" : "#{operation_class.public_name}_#{name}_#{count}"
+            renamed = true
+          end
+          break if !renamed
+        end
+        defs.each { |name, definition| @schemas[names.fetch(name)] = with_component_refs(definition, names) }
+        with_component_refs(json_schema, names)
+      end
+
+      # A copy of `value` whose references to `$defs` point to this document's shared schemas instead
+      #
+      #: (untyped value, Hash[String, String] names) -> untyped
+      def with_component_refs(value, names)
+        case value
+        when Hash
+          value.to_h do |key, item|
+            if key == "$ref" && item.is_a?(String) && item.start_with?("#/$defs/")
+              [key, "#/components/schemas/#{names.fetch(item.delete_prefix("#/$defs/"))}"]
+            else
+              [key, with_component_refs(item, names)]
+            end
+          end
+        when Array
+          value.map { |item| with_component_refs(item, names) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/graphql_backed/rest.rb

@@ -0,0 +1,181 @@
+# typed: strict
+# frozen_string_literal: true
+
+module GraphQLBacked
+  # Serves a Service's queries and mutations as JSON over HTTP, and describes them with [OpenAPI](https://spec.openapis.org/oas/v3.1.0).
+  #
+  # - .app returns a Rack app. It needs the `rack` gem, which isn't a dependency of this one,
+  #   so add it to your app (`bundle add rack`); without it, .app raises MissingDependencyError.
+  # - .openapi returns an OpenAPI document which describes that app
+  #
+  # Each of them is also available from the service, as Service.rest_app and Service.openapi:
+  #
+  #     # config.ru
+  #     run MyService.rest_app
+  #
+  #     # or, in Rails' config/routes.rb
+  #     mount MyService.rest_app, at: "/api"
+  #
+  # ## Routes
+  #
+  # By default, queries are served at `GET /PublicName` and mutations at `POST /PublicName` (see Operation.public_name).
+  # An Operation can configure its own method and path with Operation.route:
+  #
+  #     class GetUser < GraphQLBacked::Operation
+  #       route :get, "/users/:id"
+  #       graphql <<~GRAPHQL
+  #         query GetUser($id: ID!) {
+  #           user(id: $id) { ...Resources::User }
+  #         }
+  #       GRAPHQL
+  #     end
+  #
+  #     # GET /users/1
+  #     # => 200 { "id": "1", "name": "..." }
+  #
+  # A service can't have two operations with the same method and path; .app raises Error if it does.
+  #
+  # ## Variables
+  #
+  # An operation's variables come from:
+  #
+  # - the query string, eg `?limit=5&ids[]=1&ids[]=2&filter[role]=ADMIN`
+  # - the request body, a JSON object (except for `GET` and `DELETE` requests)
+  # - the `:name` segments of its path, which must be variables of the operation
+  #
+  # When the same variable is given more than once, the path overrides the body, which overrides the query string.
+  # Values from the path and query string are strings, so they're converted for `Int`, `Float` and `Boolean` variables
+  # (including inside lists and input objects).
+  #
+  # ## Responses
+  #
+  # The response is the value of the operation's root field, as JSON.
+  #
+  # If the GraphQL response has `"errors"`, the response is the whole GraphQL response instead, with status 422,
+  # or 400 if the operation didn't run because its variables weren't valid.
+  #
+  # Other errors have the same shape (`{ "errors": [{ "message": "..." }] }`):
+  #
+  # - 404 when no operation matches the path
+  # - 405 when one does, but not for that method
+  # - 400 when the body or query string can't be parsed
+  #
+  # ## GraphQL context
+  #
+  # `context:` is the GraphQL context to execute with. To use a different one for each request,
+  # pass something that responds to `call`. It receives the `Rack::Request`:
+  #
+  #     MyService.rest_app(context: ->(request) { { current_user: User.from_token(request.get_header("HTTP_AUTHORIZATION")) } })
+  #
+  # ## Rails controllers
+  #
+  # To serve operations from a Rails controller instead (for example, to use the controller's authentication),
+  # route every request under a path to one action, and build an app for each request.
+  # `prefix:` is the part of the path which comes before operations' paths:
+  #
+  #     # config/routes.rb
+  #     match "/api/*path", to: "api#show", via: :all
+  #
+  #     # app/controllers/api_controller.rb
+  #     class ApiController < ApplicationController
+  #       def show
+  #         app = MyService.rest_app(context: { current_user: current_user }, prefix: "/api")
+  #         status, headers, body = app.call(request.env)
+  #         response.headers.merge!(headers)
+  #         render json: body.join, status: status
+  #       end
+  #     end
+  #
+  # Routes are built once per service, so building an app for each request is cheap.
+  # For `POST`, `PUT` and `PATCH` requests, the controller will need `skip_forgery_protection` (or `ActionController::API`).
+  #
+  # ## OpenAPI
+  #
+  # .openapi returns an OpenAPI 3.1 document as a Hash. To serve it at `/openapi.json`,
+  # pass `openapi: true` to .app, or the options for .openapi:
+  #
+  #     MyService.rest_app(openapi: { info: { title: "My API", version: "1.2.0" } })
+  #
+  # The service keeps the document (and its JSON) until its operations, scalars or the options change,
+  # so it isn't built again for each request, even when an app is built for each request.
+  # Service.openapi_json returns that JSON, to serve it some other way.
+  #
+  # When the app has a `prefix:`, it's the document's server URL, unless you pass `servers:`.
+  #
+  # For each operation:
+  #
+  # - its `operationId` is Operation.public_name
+  # - its description is Operation.description, or else the description of its root field in the schema
+  # - variables in its path are `path` parameters
+  # - its other variables are `query` parameters for `GET` and `DELETE` operations, or else properties of the JSON request body.
+  #   List parameters are named with `[]` (`ids[]=1&ids[]=2`) and input objects use the `deepObject` style (`filter[role]=ADMIN`).
+  #   Each one is described by the argument that it's passed to.
+  # - its `200` response is described by the selections of its root field, with the description of each field
+  # - input objects and Resources are shared in `components.schemas`, named after the input type or Resource.fragment_name
+  #   (eg `Resources__User`). If two operations define different fragments with the same name, the second
+  #   is named after its operation (eg `ListUsers_Friend`).
+  # - custom scalars are described by Service.scalar_json_schema
+  module REST
+    # The HTTP methods which Operation.route accepts
+    HTTP_METHODS = [:get, :post, :put, :patch, :delete].freeze #: Array[Symbol]
+
+    # A Rack app which serves the operations of `service`. See the sections above for how it handles requests.
+    #
+    # - `context` is the GraphQL context to execute with, or something that responds to `call`,
+    #   which receives the `Rack::Request` and returns the context for that request
+    # - `prefix` is the part of each request's path which comes before operations' paths, eg `"/api"`
+    # - `openapi` serves .openapi at `/openapi.json`. It's `true`, or a Hash of options for .openapi.
+    #
+    #     GraphQLBacked::REST.app(MyService, context: { current_user: user }, prefix: "/api", openapi: true)
+    #
+    #: (singleton(Service) service, ?context: untyped, ?prefix: String?, ?openapi: untyped) -> App
+    def self.app(service, context: {}, prefix: nil, openapi: nil)
+      App.new(service, context: context, prefix: prefix, openapi: openapi)
+    end
+
+    # An OpenAPI 3.1 document which describes the .app of `service`, as a Hash with String keys.
+    # See the "OpenAPI" section above for how operations are described.
+    #
+    # `info` is merged into the document's `info`. By default, its `title` is the service's name and its `version` is `1.0.0`.
+    # Other options are merged into the document itself:
+    #
+    #     GraphQLBacked::REST.openapi(MyService, info: { title: "My API", version: "1.2.0" }, servers: [{ url: "https://example.com/api" }])
+    #
+    # This builds a new document each time; Service.openapi keeps it until the service or the options change.
+    #
+    #: (singleton(Service) service, ?info: Hash[untyped, untyped], **untyped document) -> Hash[String, untyped]
+    def self.openapi(service, info: {}, **document)
+      OpenAPI.new(service).to_h(info: info, document: document)
+    end
+
+    # How each operation of `service` is matched to requests. This builds them each time;
+    # Service.rest_routes keeps them until the service changes.
+    #
+    #: (singleton(Service) service) -> Array[App::Route]
+    def self.routes(service) # :nodoc:
+      require_rack
+      routes = service.operations.map { |operation_class| App::Route.new(service, operation_class) }
+      routes.group_by { |route| [route.http_method, route.path] }.each do |(http_method, path), same_routes|
+        next if same_routes.size == 1
+        names = same_routes.map { |route| route.operation_class.name }.join(" and ")
+        raise Error, "#{service.name} has more than one operation for #{http_method} #{path}: #{names}"
+      end
+      routes
+    end
+
+    # `rack` isn't a dependency of this gem, so it's only required when REST features are first used.
+    #
+    #: -> void
+    def self.require_rack # :nodoc:
+      require "rack"
+    rescue LoadError => err
+      raise unless err.path == "rack"
+      raise MissingDependencyError, "GraphQLBacked's REST support requires the `rack` gem, add it to your app with `bundle add rack`"
+    end
+
+    private_class_method :require_rack
+  end
+end
+
+require "graphql_backed/rest/app"
+require "graphql_backed/rest/open_api"

data/lib/graphql_backed/service.rb

@@ -0,0 +1,253 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+
+module GraphQLBacked
+  # A set of Operations backed by one GraphQL schema:
+  #
+  #     class MyService < GraphQLBacked::Service
+  #       schema MySchema
+  #       operation GetUser
+  #       operation RenameUser
+  #     end
+  #
+  #     MyService.execute(GetUser, variables: { id: "1" })
+  #     # => { "data" => { "user" => { "id" => "1", "name" => "..." } } }
+  #
+  # Operations are identified by Operation.public_name, which must be unique within a service.
+  # Each operation is validated against .schema when it's added, raising InvalidDocumentError if it isn't valid.
+  # That's the only time it's validated: .execute runs it without validating it again, unless the service has `validate true`.
+  #
+  # A service can also serve its operations as Model Context Protocol tools (see GraphQLBacked::MCP)
+  # or as JSON over HTTP (see GraphQLBacked::REST).
+  class Service
+    class << self
+      # Get or set the schema that this service's operations are validated against and run by. Inherited by subclasses.
+      # Setting it validates the operations which this service already has (like the ones inherited from its superclass).
+      #
+      #: (?singleton(GraphQL::Schema)? new_schema) -> singleton(GraphQL::Schema)
+      def schema(new_schema = nil)
+        if new_schema
+          operations.each { |operation_class| validate_operation(operation_class, new_schema) }
+          @schema = new_schema #: singleton(GraphQL::Schema)?
+        end
+        @schema || parent_service&.schema || raise(Error, "#{name} has no schema, add one with `schema MySchema`")
+      end
+
+      # Configure whether .execute validates operations again, each time they're run:
+      #
+      #     validate true
+      #
+      # It's `false` by default, because operations were already validated when they were added. Turn it on when a document's validity
+      # depends on the request, for example when .schema hides some of its types or fields based on `context`. Inherited by subclasses.
+      #
+      #: (bool new_validate) -> void
+      def validate(new_validate)
+        @validate = new_validate #: bool?
+      end
+
+      # Whether .execute validates operations again, see .validate.
+      #
+      #: -> bool
+      def validate?
+        if @validate.nil?
+          parent_service&.validate? || false
+        else
+          @validate
+        end
+      end
+
+      # Add an operation to this service, validating its flattened document against .schema.
+      # Raises if the service already has a different operation with the same Operation.public_name.
+      #
+      #: (singleton(Operation) operation_class) -> void
+      def operation(operation_class)
+        validate_operation(operation_class, schema)
+        existing = find_operation(operation_class.public_name)
+        return if existing == operation_class
+        if existing
+          raise Error, "#{name} already has an operation named #{existing.public_name} (#{existing.name}), so #{operation_class.name} can't be added"
+        end
+        @own_operations ||= [] #: Array[singleton(Operation)]?
+        @own_operations << operation_class
+      end
+
+      # Describe one of .schema's custom scalars with JSON Schema, for frontends which describe their inputs and outputs that way (MCP tools and OpenAPI documents):
+      #
+      #     scalar_json_schema Types::Money, { "type" => "string", "pattern" => "^\\d+\\.\\d{2}$" }
+      #     scalar_json_schema Types::Percent, { "type" => "number", "minimum" => 0, "maximum" => 100 }
+      #
+      # `scalar_class` is the scalar's class, a subclass of `GraphQL::Schema::Scalar`. Inherited by subclasses.
+      #
+      # GraphQL-Ruby's own `ISO8601Date`, `ISO8601DateTime`, `ISO8601Duration` and `BigInt` are already described.
+      # Any other scalar which isn't configured here accepts any JSON value.
+      #
+      # Those defaults, and the ones for `String`, `ID`, `Int`, `Float` and `Boolean`, can be overridden by passing the built-in class:
+      #
+      #     scalar_json_schema GraphQL::Types::ID, { "type" => "string", "pattern" => "^\\d+$" }
+      #
+      # An override replaces the default altogether, for variables and for output alike: with this one,
+      # `ID` variables aren't accepted as integers anymore.
+      #
+      #: (singleton(GraphQL::Schema::Scalar) scalar_class, Hash[untyped, untyped] json_schema) -> void
+      def scalar_json_schema(scalar_class, json_schema)
+        scalar = scalar_class #: untyped
+        if !(scalar.is_a?(Class) && scalar < GraphQL::Schema::Scalar)
+          raise ArgumentError, "#{name}: expected a subclass of GraphQL::Schema::Scalar, but got #{scalar.inspect}"
+        end
+        @own_scalar_json_schemas ||= {} #: Hash[String, Hash[String, untyped]]?
+        # Round-tripping makes a copy with string keys
+        @own_scalar_json_schemas[scalar_class.graphql_name] = JSON.parse(JSON.generate(json_schema))
+      end
+
+      # The schemas configured with .scalar_json_schema, by scalar name, including those inherited from its superclass.
+      #
+      #: -> Hash[String, Hash[String, untyped]]
+      def scalar_json_schemas
+        (parent_service&.scalar_json_schemas || {}).merge(@own_scalar_json_schemas || {})
+      end
+
+      # Find one of this service's operations by its Operation.public_name.
+      #
+      #     MyService.find_operation("GetUser") # => GetUser
+      #
+      #: (String public_name) -> singleton(Operation)?
+      def find_operation(public_name)
+        operations.find { |operation_class| operation_class.public_name == public_name }
+      end
+
+      # The operations added to this service, including those inherited from its superclass.
+      #
+      #: -> Array[singleton(Operation)]
+      def operations
+        (parent_service&.operations || []) + (@own_operations || [])
+      end
+
+      # Run one of this service's operations and return the GraphQL response (with `"data"` and/or `"errors"`).
+      # This is the only place where GraphQL is executed.
+      #
+      #     MyService.execute(GetUser, variables: { id: "1" }, context: { current_user: current_user })
+      #     # => { "data" => { "user" => { "id" => "1", "name" => "..." } } }
+      #
+      #: (singleton(Operation) operation_class, ?variables: Hash[untyped, untyped], ?context: Hash[untyped, untyped]) -> Hash[String, untyped]
+      def execute(operation_class, variables: {}, context: {})
+        if !operations.include?(operation_class)
+          raise Error, "#{operation_class.name} isn't part of #{name}, add it with `operation #{operation_class.name}`"
+        end
+        # Passing the document saves GraphQL-Ruby from parsing the query string each time,
+        # and it was already validated when it was added to this service
+        schema.execute(document: operation_class.document, variables: variables, context: context, validate: validate?).to_h
+      end
+
+      # This service's operations as `MCP::Tool` classes, for the `mcp` gem. See MCP.tools.
+      #
+      # They're built once, then again whenever operations or scalars are added to this service (or its superclass).
+      #
+      #: -> Array[singleton(::MCP::Tool)]
+      def mcp_tools
+        current_config = [operations, scalar_json_schemas]
+        if @mcp_tools.nil? || @mcp_tools_config != current_config
+          @mcp_tools = MCP.tools(self) #: Array[singleton(::MCP::Tool)]?
+          @mcp_tools_config = current_config #: [Array[singleton(Operation)], Hash[String, Hash[String, untyped]]]?
+        end
+        @mcp_tools #: as !nil
+      end
+
+      # An `MCP::Server` with .mcp_tools. `context` is the GraphQL context which its tools execute with;
+      # other options are passed to `MCP::Server.new`. See MCP.server.
+      #
+      #     MyService.mcp_server(context: { current_user: user }, name: "my-api", version: "1.2.0")
+      #
+      #: (?context: Hash[untyped, untyped], **untyped server_options) -> ::MCP::Server
+      def mcp_server(context: {}, **server_options)
+        MCP.server(self, context: context, **server_options)
+      end
+
+      # A Streamable HTTP transport for .mcp_server, which is also a Rack app. See MCP.transport for its options.
+      #
+      #     # config.ru
+      #     run MyService.mcp_transport(allowed_hosts: ["api.example.com"])
+      #
+      #: (?context: Hash[untyped, untyped], ?server_options: Hash[Symbol, untyped], **untyped transport_options) -> ::MCP::Server::Transports::StreamableHTTPTransport
+      def mcp_transport(context: {}, server_options: {}, **transport_options)
+        MCP.transport(self, context: context, server_options: server_options, **transport_options)
+      end
+
+      # A Rack app which serves this service's operations as JSON over HTTP. See REST.app for its options.
+      #
+      #     # config.ru
+      #     run MyService.rest_app(context: { current_user: user }, prefix: "/api", openapi: true)
+      #
+      #: (?context: untyped, ?prefix: String?, ?openapi: untyped) -> REST::App
+      def rest_app(context: {}, prefix: nil, openapi: nil)
+        REST.app(self, context: context, prefix: prefix, openapi: openapi)
+      end
+
+      # An OpenAPI 3.1 document which describes .rest_app, as a Hash with String keys.
+      # `info` is merged into the document's `info`; other options are merged into the document. See REST.openapi.
+      #
+      #     MyService.openapi(info: { title: "My API", version: "1.2.0" }, servers: [{ url: "https://example.com/api" }])
+      #
+      # It's built once, then again whenever it's called with different options, or operations or scalars
+      # are added to this service (or its superclass). It's frozen, since it's shared between calls.
+      #
+      #: (?info: Hash[untyped, untyped], **untyped document) -> Hash[String, untyped]
+      def openapi(info: {}, **document)
+        current_config = [rest_routes, scalar_json_schemas, info, document]
+        if @openapi.nil? || @openapi_config != current_config
+          @openapi = deep_freeze(REST.openapi(self, info: info, **document)) #: Hash[String, untyped]?
+          @openapi_json = nil #: String?
+          @openapi_config = current_config #: Array[untyped]?
+        end
+        @openapi #: as !nil
+      end
+
+      # .openapi as a JSON string, for serving it. It takes the same options, and it's kept in the same way.
+      #
+      #: (?info: Hash[untyped, untyped], **untyped document) -> String
+      def openapi_json(info: {}, **document)
+        current_document = openapi(info: info, **document)
+        @openapi_json ||= JSON.generate(current_document).freeze
+      end
+
+      # How each operation is matched to requests by .rest_app. They're kept, so building an app for each request is cheap.
+      #
+      #: -> Array[REST::App::Route]
+      def rest_routes # :nodoc:
+        current_config = operations.map { |operation_class| [operation_class, operation_class.http_method, operation_class.path] }
+        # Build again if operations were added (here or in a superclass) or routed differently since last time
+        if @rest_routes.nil? || @rest_routes_config != current_config
+          @rest_routes = REST.routes(self) #: Array[REST::App::Route]?
+          @rest_routes_config = current_config #: Array[[singleton(Operation), Symbol, String]]?
+        end
+        @rest_routes #: as !nil
+      end
+
+      private
+
+      #: (singleton(Operation) operation_class, singleton(GraphQL::Schema) target_schema) -> void
+      def validate_operation(operation_class, target_schema)
+        errors = target_schema.validate(operation_class.document)
+        if errors.any?
+          raise InvalidDocumentError, "#{operation_class.name} isn't valid for #{name}: #{errors.map(&:message).join(", ")}"
+        end
+      end
+
+      #: (untyped value) -> untyped
+      def deep_freeze(value)
+        case value
+        when Hash then value.each_value { |item| deep_freeze(item) }
+        when Array then value.each { |item| deep_freeze(item) }
+        end
+        value.freeze
+      end
+
+      #: -> singleton(Service)?
+      def parent_service
+        parent = superclass
+        parent if parent.is_a?(Class) && parent < Service
+      end
+    end
+  end
+end

data/lib/graphql_backed/version.rb

@@ -0,0 +1,7 @@
+# typed: strict
+# frozen_string_literal: true
+
+# :startdoc:
+module GraphQLBacked
+  VERSION = "0.1.0" #: String
+end

data/lib/graphql_backed.rb

@@ -0,0 +1,32 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "graphql"
+require "graphql_backed/version"
+
+# Build APIs on top of existing GraphQL APIs:
+#
+# - a Resource is a reusable GraphQL fragment
+# - an Operation is a query or mutation which includes resources
+# - a Service is a set of operations backed by a schema. It runs them.
+# - MCP serves a service's operations as Model Context Protocol tools
+# - REST serves a service's operations as JSON over HTTP, and describes them with OpenAPI
+module GraphQLBacked
+  # Base class for errors raised by this library.
+  class Error < StandardError; end
+
+  # Raised when an Operation or Resource is defined with GraphQL that can't be parsed,
+  # doesn't have the required structure, or isn't valid for a Service's schema.
+  class InvalidDocumentError < Error; end
+
+  # Raised when a feature needs a gem which isn't a dependency of this one, and that gem isn't available.
+  class MissingDependencyError < Error; end
+end
+
+require "graphql_backed/resource_references"
+require "graphql_backed/resource"
+require "graphql_backed/operation"
+require "graphql_backed/json_schema"
+require "graphql_backed/mcp"
+require "graphql_backed/rest"
+require "graphql_backed/service"