quail-graphql 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f4a7270de975b06407fbe6b81ed40135a4c94e2816cc556dbd388fd5b673db12
+  data.tar.gz: 5deb33482ef22b0b18dc230fca7a8f90051f09ed81c09e88438d8ff5c19b9f3d
+SHA512:
+  metadata.gz: afa695056fd8c70acf472243252c5415c5c0a3b89e236499718ced6adfd8ba80a5ae7089fc105df615ba5208c2ef18598a548a98c8aa0d0fbcdc8d78451c5c94
+  data.tar.gz: 7ff9e3ed9a03729f13b64d40549fe1fcb9a4304a76a45db46426f41f42cb155598eb91a75f4778a1e5b6469c8adcb616c8adbe6abd99cb50572d3001d479a9b2

data/AGENTS.md

@@ -0,0 +1,19 @@
+# AGENTS.md
+
+This project provides machine-readable documentation for AI coding agents.
+
+## LLMs.txt Endpoints
+
+The following files are dynamically generated from the Quail documentation site root:
+
+- **llms.txt** Index of all documentation pages with links
+- **llms-full.txt** Full content of all pages in one file
+- **llms-small.txt** Condensed version
+
+## Usage
+
+Coding agents can fetch these URLs to get context about the Quail documentation:
+
+- `https://quail.taywils.me/llms.txt`
+- `https://quail.taywils.me/llms-full.txt`
+- `https://quail.taywils.me/llms-small.txt`

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Demetrious Wilson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,39 @@
+<div align="center">
+  <img src="./quail_logo_new.svg" alt="Quail Logo" width="320">
+
+  <strong>A Rails-first GraphQL library with a declarative, <a href="https://github.com/okuramasafumi/alba">Alba</a>-inspired DSL built on top of <a href="https://github.com/rmosolgo/graphql-ruby">graphql-ruby</a>.</strong>
+
+   [![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
+</div>
+
+> ⚠️ **This gem is under active development and has not been published to RubyGems. Please do not use in production.**
+
+## Installation
+
+Add Quail to your Gemfile:
+
+```Gemfile
+gem "quail", git: "https://github.com/taywils/quail.git", branch: "main"
+```
+
+## Quick Start
+
+```bash
+rails generate quail:install
+```
+
+## Documentation
+
+📖 **Full documentation:** [Quail Docs Website](https://quail.taywils.me/)
+
+📂 **Documentation source:** [quail-docs Github Repo](https://github.com/taywils/quail-docs)
+
+The docs site covers the resource DSL, mutations, queries, subscriptions, custom types, authentication wiring, and more.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at <https://github.com/taywils/quail>.
+
+## License
+
+Released under the [MIT License](./LICENSE.txt).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/generators/quail/channel_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Quail
+  module Generators
+    # Generates a customizable GraphQL ActionCable channel for subscriptions.
+    class ChannelGenerator < Rails::Generators::Base
+      desc "Generate a customizable GraphQL ActionCable channel"
+      source_root File.expand_path("templates", __dir__)
+
+      def create_channel
+        template "graphql_channel_custom.rb.tt", "app/channels/graphql_channel.rb"
+      end
+    end
+  end
+end

data/lib/generators/quail/install_generator.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Quail
+  module Generators
+    # Sets up Quail in a Rails app: schema, controller, channel, initializer, and directories.
+    class InstallGenerator < Rails::Generators::Base
+      desc "Set up Quail: schema, controller, route, initializer, and resource directory"
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :schema_name,
+                   type: :string,
+                   default: nil,
+                   desc: "Name for the schema class (default: AppSchema)"
+
+      class_option :skip_controller,
+                   type: :boolean,
+                   default: nil,
+                   desc: "Skip generating the GraphQL controller"
+
+      class_option :skip_channel,
+                   type: :boolean,
+                   default: false,
+                   desc: "Skip generating the ActionCable channel"
+
+      def create_graphql_directories
+        %w[resources mutations queries subscriptions types].each do |dir|
+          empty_directory "app/graphql/#{dir}"
+          create_file "app/graphql/#{dir}/.keep"
+        end
+      end
+
+      def create_schema
+        template "schema.rb.tt", "app/graphql/#{schema_name.underscore}.rb"
+      end
+
+      def create_controller
+        return if options[:skip_controller]
+
+        template "graphql_controller.rb.tt", "app/controllers/graphql_controller.rb"
+      end
+
+      def create_channel
+        return if options[:skip_channel]
+
+        template "graphql_channel.rb.tt", "app/channels/graphql_channel.rb"
+      end
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/quail.rb"
+      end
+
+      def add_route
+        return if options[:skip_controller]
+
+        route 'post "/graphql", to: "graphql#execute"'
+      end
+
+      private
+
+      def schema_name
+        options[:schema_name] || "AppSchema"
+      end
+
+      def app_name
+        if Rails.application.class.respond_to?(:module_parent_name)
+          Rails.application.class.module_parent_name
+        else
+          Rails.application.class.parent_name
+        end
+      end
+    end
+  end
+end

data/lib/generators/quail/resource_generator.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Quail
+  module Generators
+    # Generates a Quail resource file for a given ActiveRecord model.
+    class ResourceGenerator < Rails::Generators::NamedBase
+      desc "Generate a Quail resource for a model. Usage: rails g quail:resource Article"
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :attributes,
+                   type: :array,
+                   default: [],
+                   desc: "Attributes to expose (default: all columns)"
+
+      class_option :skip_mutations,
+                   type: :array,
+                   default: [],
+                   desc: "Mutations to skip: create update delete"
+
+      class_option :skip_queries,
+                   type: :array,
+                   default: [],
+                   desc: "Queries to skip: find list"
+
+      class_option :subscribe_on,
+                   type: :array,
+                   default: [],
+                   desc: "Events to subscribe on: create update delete"
+
+      def create_resource
+        template "resource.rb.tt", "app/graphql/resources/#{file_name}_resource.rb"
+      end
+
+      private
+
+      def model_class
+        class_name.constantize
+      rescue NameError
+        nil
+      end
+
+      def attribute_names
+        if options[:attributes].any?
+          options[:attributes].map(&:to_sym)
+        elsif model_class
+          model_class.column_names.map(&:to_sym)
+        else
+          [:id]
+        end
+      end
+
+      def association_lines
+        return [] unless model_class
+
+        model_class.reflect_on_all_associations.map do |association|
+          case association.macro
+          when :has_many    then "  has_many :#{association.name}"
+          when :has_one     then "  has_one :#{association.name}"
+          when :belongs_to  then "  belongs_to :#{association.name}"
+          end
+        end.compact
+      end
+
+      def writable_attribute_names
+        attribute_names.reject { |c| %i[id created_at updated_at].include?(c) }
+      end
+
+      def skip_mutations_list
+        options[:skip_mutations].map { |m| ":#{m}" }.join(", ")
+      end
+
+      def subscribe_on_list
+        options[:subscribe_on].map { |e| ":#{e}" }.join(", ")
+      end
+    end
+  end
+end

data/lib/generators/quail/templates/graphql_channel.rb.tt

@@ -0,0 +1,4 @@
+# Default Quail subscription channel.
+# For most apps, this just works out of the box.
+class GraphqlChannel < Quail::Channel
+end

data/lib/generators/quail/templates/graphql_channel_custom.rb.tt

@@ -0,0 +1,23 @@
+# Customizable GraphQL subscription channel.
+# Override context_for_subscription to inject your own auth context.
+class GraphqlChannel < Quail::Channel
+  private
+
+  # Add your auth context here. This is passed to every subscription query.
+  # Example:
+  #
+  # def context_for_subscription
+  #   {
+  #     channel: self,
+  #     current_user: find_verified_user
+  #   }
+  # end
+  #
+  # def find_verified_user
+  #   # Your auth logic - token-based, cookie-based, JWT, etc...
+  # end
+  #
+  def context_for_subscription
+    { channel: self }
+  end
+end

data/lib/generators/quail/templates/graphql_controller.rb.tt

@@ -0,0 +1,40 @@
+class GraphqlController < ApplicationController
+  # If accessing from outside this domain, nullify the session
+  # This allows for outside API access while preventing CSRF attacks,
+  # but you'll have to authenticate your user separately
+  # protect_from_forgery with: :null_session
+
+  def execute
+    result = <%= schema_name %>.execute(
+      params[:query],
+      variables: normalize_request_params(params[:variables]),
+      context: {
+        # Bring Your Own Auth - add your current_user here:
+        # current_user: current_user,
+      },
+      operation_name: params[:operationName]
+    )
+    render json: result
+  rescue StandardError => e
+    raise e unless Rails.env.development?
+    handle_error_in_development(e)
+  end
+
+  private
+
+  def normalize_request_params(request_params)
+    case request_params
+    when String then request_params.present? ? JSON.parse(request_params) : {}
+    when Hash then request_params
+    when ActionController::Parameters then request_params.to_unsafe_hash
+    when nil then {}
+    else raise ArgumentError, "Unexpected parameter: #{request_params}"
+    end
+  end
+
+  def handle_error_in_development(e)
+    logger.error e.message
+    logger.error e.backtrace.join("\n")
+    render json: { errors: [{ message: e.message, backtrace: e.backtrace }], data: {} }, status: 500
+  end
+end

data/lib/generators/quail/templates/initializer.rb.tt

@@ -0,0 +1,5 @@
+Rails.application.config.quail.schema_class = "<%= schema_name %>"
+
+# Uncomment to use custom base classes from your app:
+# Quail.base_object_class = Types::BaseObject
+# Quail.base_mutation_class = Mutations::BaseMutation

data/lib/generators/quail/templates/resource.rb.tt

@@ -0,0 +1,23 @@
+class <%= class_name %>Resource
+  include Quail::Resource
+<% if attribute_names.any? -%>
+
+  attributes <%= attribute_names.map { |a| ":#{a}" }.join(", ") %>
+<% end -%>
+<% if association_lines.any? -%>
+
+<%= association_lines.join("\n") %>
+<% end -%>
+<% if writable_attribute_names.any? -%>
+
+  writable_attributes <%= writable_attribute_names.map { |a| ":#{a}" }.join(", ") %>
+<% end -%>
+<% if options[:skip_mutations].any? -%>
+
+  skip_mutations <%= skip_mutations_list %>
+<% end -%>
+<% if options[:subscribe_on].any? -%>
+
+  subscribe_on <%= subscribe_on_list %>
+<% end -%>
+end

data/lib/generators/quail/templates/schema.rb.tt

@@ -0,0 +1,21 @@
+class <%= schema_name %> < GraphQL::Schema
+  Quail::SchemaBuilder.call(self)
+
+  # Limit the size of incoming queries:
+  max_query_string_tokens(5_000)
+
+  # Stop validating when it encounters this many errors:
+  validate_max_errors(100)
+
+  # Relay-style Object Identification:
+
+  # Return a string UUID for `object`
+  def self.id_from_object(object, type_definition, query_ctx)
+    object.to_gid_param
+  end
+
+  # Given a string UUID, find the object
+  def self.object_from_id(global_id, query_ctx)
+    GlobalID.find(global_id)
+  end
+end

data/lib/quail/channel.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Quail
+  # ActionCable channel for handling GraphQL subscriptions over WebSocket.
+  class Channel < ActionCable::Channel::Base
+    def subscribed
+      @subscription_ids = []
+      result = execute_query
+      track_subscription(result)
+      transmit(result: result.to_h, more: result.subscription?)
+    end
+
+    def unsubscribed
+      @subscription_ids&.each do |subscription_id|
+        schema_class.subscriptions.delete_subscription(subscription_id)
+      end
+    end
+
+    private
+
+    def execute_query
+      schema_class.execute(
+        params[:query],
+        context: context_for_subscription,
+        variables: ensure_hash(params[:variables]),
+        operation_name: params[:operation_name]
+      )
+    end
+
+    def track_subscription(result)
+      @subscription_ids << result.context[:subscription_id] if result.context[:subscription_id]
+    end
+
+    def context_for_subscription
+      { channel: self }
+    end
+
+    def schema_class
+      Rails.application.config.quail.schema_class
+    end
+
+    def ensure_hash(some_param)
+      case some_param
+      when String then some_param.present? ? JSON.parse(some_param) : {}
+      when Hash then some_param
+      when ActionController::Parameters then some_param.to_unsafe_hash
+      when nil then {}
+      else raise ArgumentError, "Unexpected parameter: #{some_param.class}"
+      end
+    end
+  end
+end

data/lib/quail/controller_helpers.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Quail
+  # Provides shared helper methods for GraphQL controllers,
+  # including request parameter normalization and development error handling.
+  module ControllerHelpers
+    extend ActiveSupport::Concern
+
+    private
+
+    def normalize_request_params(request_params)
+      case request_params
+      when String then request_params.present? ? JSON.parse(request_params) : {}
+      when Hash then request_params
+      when ActionController::Parameters then request_params.to_unsafe_hash
+      when nil then {}
+      else raise ArgumentError, "Unexpected parameter: #{request_params}"
+      end
+    end
+
+    def handle_error_in_development(error)
+      logger.error error.message
+      logger.error error.backtrace.join("\n")
+      render json: { errors: [{ message: error.message, backtrace: error.backtrace }], data: {} }, status: 500
+    end
+  end
+end

data/lib/quail/railtie.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Quail
+  # Rails integration for Quail: configures eager loading and schema resolution.
+  class Railtie < Rails::Railtie
+    config.quail = ActiveSupport::OrderedOptions.new
+    config.quail.schema_class = nil
+
+    initializer "quail.autoload_paths", before: :set_autoload_paths do |app|
+      # These subdirectories define top-level constants (e.g. UserResource, not Resources::UserResource)
+      # Note: types/ is excluded because custom types use the Types:: namespace by convention
+      %w[resources queries mutations subscriptions].each do |subdir|
+        path = Rails.root.join("app/graphql/#{subdir}").to_s
+        next unless Dir.exist?(path)
+
+        app.config.autoload_paths << path
+        app.config.eager_load_paths << path
+      end
+    end
+
+    # Tell Zeitwerk to ignore these subdirectories from the parent app/graphql/ root
+    # so they are only loaded as top-level autoload roots (no module namespace).
+    initializer "quail.zeitwerk_ignore", before: :setup_main_autoloader do
+      Rails.autoloaders.main.ignore(
+        Rails.root.join("app/graphql/resources"),
+        Rails.root.join("app/graphql/queries"),
+        Rails.root.join("app/graphql/mutations"),
+        Rails.root.join("app/graphql/subscriptions")
+      )
+    end
+
+    config.after_initialize do |app|
+      schema = app.config.quail.schema_class
+      app.config.quail.schema_class = schema.constantize if schema.is_a?(String)
+    end
+
+    rake_tasks do
+      load File.expand_path("tasks/quail.rake", __dir__)
+    end
+  end
+end

data/lib/quail/resource/dsl.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Quail
+  module Resource
+    # DSL for declaring attributes, associations, mutations, and subscriptions on a resource.
+    module DSL
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      # Class-level DSL methods mixed into resource classes.
+      module ClassMethods
+        def model(klass = nil)
+          if klass
+            @model_class = klass
+          else
+            @model ||= name.delete_suffix("Resource").constantize
+          end
+        end
+        alias model_class model
+
+        def attribute_definitions
+          @attribute_definitions ||= {}
+        end
+
+        def attributes(*names)
+          names.each { |name| attribute_definitions[name] = { type: :column } }
+        end
+
+        def attribute(name, type: nil, null: nil, &block)
+          attribute_definitions[name] = { type: :computed, graphql_type: type, null: null, block: block }
+        end
+
+        def association_definitions
+          @association_definitions ||= {}
+        end
+
+        def has_many(name, resource: nil, **options)
+          association_definitions[name] = { kind: :has_many, resource: resource, **options }
+        end
+
+        def has_one(name, resource: nil, **options)
+          association_definitions[name] = { kind: :has_one, resource: resource, **options }
+        end
+
+        def belongs_to(name, resource: nil, **options)
+          if options[:polymorphic]
+            validate_polymorphic_options!(options[:polymorphic])
+            options[:polymorphic_types] = options[:polymorphic][:types]
+            options[:union_name] = options[:polymorphic][:union_name] if options[:polymorphic][:union_name]
+            options[:polymorphic] = true
+          end
+          association_definitions[name] = { kind: :belongs_to, resource: resource, **options }
+        end
+
+        def skip_mutations(*actions)
+          @skipped_mutations = actions.map(&:to_sym)
+        end
+
+        def skipped_mutations
+          @skipped_mutations || []
+        end
+
+        def override_mutation(action, klass)
+          mutation_overrides[action.to_sym] = klass
+        end
+
+        def mutation_overrides
+          @mutation_overrides ||= {}
+        end
+
+        # Resolves mutation override values, constantizing strings lazily.
+        def resolved_mutation_overrides
+          mutation_overrides.transform_values do |klass|
+            klass.is_a?(String) ? klass.constantize : klass
+          end
+        end
+
+        def writable_attributes(*names)
+          if names.any?
+            @writable_attributes = names.map(&:to_sym)
+          else
+            @writable_attributes
+          end
+        end
+
+        def subscription_definitions
+          @subscription_definitions ||= {}
+        end
+
+        def subscribe_on(*events, scope: nil)
+          if scope && !scope.is_a?(Symbol) && !scope.is_a?(Hash)
+            raise ArgumentError, "subscribe_on scope: must be a Symbol or Hash { key: proc }, got #{scope.class}"
+          end
+
+          events.each { |event| subscription_definitions[event.to_sym] = { scope: scope } }
+        end
+
+        def skip_queries(*actions)
+          @skipped_queries = actions.map(&:to_sym)
+        end
+
+        def skipped_queries
+          @skipped_queries || []
+        end
+
+        private
+
+        def validate_polymorphic_options!(poly_opt)
+          unless poly_opt.is_a?(Hash) && poly_opt.key?(:types)
+            raise ArgumentError,
+                  "polymorphic requires a Hash with a :types key, e.g. polymorphic: { types: [FooResource] }"
+          end
+          return unless poly_opt[:types].empty?
+
+          raise ArgumentError, "polymorphic :types must contain at least one resource class or class name string"
+        end
+      end
+    end
+  end
+end

data/lib/quail/resource/mutation_builder/context.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Quail
+  module Resource
+    module MutationBuilder
+      # Holds the shared context needed by all mutation builders.
+      MutationContext = Struct.new(:resource_class) do
+        def model          = resource_class.model_class
+        def type_class     = resource_class.graphql_type
+        def underscore_name = model.name.underscore
+
+        def writable
+          resource_class.writable_attributes || MutationBuilder.default_writable(model,
+                                                                                 resource_class)
+        end
+
+        def subscriptions  = resource_class.subscription_definitions
+        def base           = Quail.base_mutation_class || GraphQL::Schema::RelayClassicMutation
+      end
+    end
+  end
+end