graphiti-rails 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0546b042d2d512c700094de8be871f95f65488ae003c508ce522bb881dfccb2e
+  data.tar.gz: 75dc08fb8add0c1a1eb6ef63c927ff83fdba84eb8cfa9d3b08197db4ee3dbae8
+SHA512:
+  metadata.gz: e5d4a756cc7bd379e962830b1ff7171fdabae707799a2961e3df8d96746643a6061fe7b6cb1151aea0228fc1a34f42197e11c188a40976cbc0a6982ae09769c5
+  data.tar.gz: cce0b7aff8cc4301068c6c1e367abb094cc1bed28d7a5203736b4f9cf747082a73fd54438ec15d1e45cdc8e79b7a3a1f1ca9b42a933706e1612ba0c12120f701

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+No releases means no changes...

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2019 Peter Wagenet
+
+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,72 @@
+# Graphiti::Rails
+
+Graphiti::Rails provides robust Rails integration for Graphiti, following standard Rails conventions.
+
+## Usage
+Out of the box, Graphiti::Rails requires no configuration!
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'graphiti-rails'
+```
+
+### Additional Setup
+
+#### Debug Exception Format
+
+If you're already running Rails in [API-only mode](https://guides.rubyonrails.org/api_app.html#changing-an-existing-application), there's no additional setup. Otherwise, we recommend the following in `config/application.rb`:
+
+```ruby
+config.debug_exception_response_format = :api
+```
+
+This will cause the [`ActionDispatch::DebugExceptions`][debug-exceptions] middleware to generate debug information in the requested content-type instead of as HTML only. In turn, this allows graphti-rails to generate more specific error messages for JSON API requests.
+
+#### Handled Exception Formats
+
+Since Rails doesn't correctly format exceptions for JSON:API requests, graphiti-rails intercepts these requests for proper rendering. If you'd like to use the GraphitiError handlers for other response types as well, you can add them in `config/application.rb`:
+
+```ruby
+config.graphiti.handled_exception_formats += [:xml]
+```
+
+## Features
+
+### Exception Handling
+By default, Rails does a few things to handle exceptions. We integrate into this handling to ensure behavior as close to the Rails defaults while still adding important conventions and additional information provide by Graphiti.
+
+#### `rescue_from`
+
+At the highest level, is [`rescue_from`][rescue-from] which allows you to handle an error at the controller level. This bypasses all default error handling in Rails, leaving it up to the developer to account for all scenarios. In the future, we would like to provide some APIs for default handling in these cases.
+
+#### `ActionDispatch::DebugExceptions`
+
+Next is [`ActionDispatch::DebugExceptions`][debug-exceptions]. This middleware logs exceptions and renders debugging information for local requests. We hook in here to log information in a proper format for JSON:API.
+
+#### `ActionDispatch::ShowExceptions`
+
+Last is [`ActionDispatch::ShowExceptions`][show-exceptions]. This middleware rescues any exception returned by the application and calls an exceptions app that will wrap it in a format for the end user. We wrap the exceptions app to ensure that JSON:API errors are always rendered in the standard format.
+
+### Context Wrapping
+We wrap all requests in a Graphiti context pointing to the current controller instance. If you'd like to use a different context, overwrite the `graphiti_context` method in your controller.
+
+For more information about Graphiti context, see the [Graphiti docs][context].
+
+### Debugging
+We also provide hooks for Graphiti's built-in debugger. For more information see the [Graphiti docs][debugger].
+
+## Contributing
+We'd love to have your help improving graphiti-rails. To chat with the team and other users, join the `#rails` channel on [Slack][slack].
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+
+[debug-exceptions]: https://api.rubyonrails.org/classes/ActionDispatch/DebugExceptions.html
+[context]: https://www.graphiti.dev/guides/concepts/resources#context
+[debugger]: https://www.graphiti.dev/guides/concepts/debugging#debugger
+[rescue-from]: https://api.rubyonrails.org/classes/ActiveSupport/Rescuable/ClassMethods.html#method-i-rescue_from
+[show-exceptions]: https://api.rubyonrails.org/classes/ActionDispatch/ShowExceptions.html
+[slack]: https://join.slack.com/t/graphiti-api/shared_invite/enQtMjkyMTA3MDgxNTQzLWVkMDM3NTlmNTIwODY2YWFkMGNiNzUzZGMzOTY3YmNmZjBhYzIyZWZlZTk4YmI1YTI0Y2M0OTZmZGYwN2QxZjg

data/Rakefile

@@ -0,0 +1,20 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'yard'
+require 'rspec/core/rake_task'
+require 'bundler/gem_tasks'
+
+YARD::Rake::YardocTask.new
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = "--order random"
+end
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+task default: :spec

data/lib/generators/graphiti/api_test_generator.rb

@@ -0,0 +1,70 @@
+require_relative "generator_mixin"
+
+module Graphiti
+  class ApiTestGenerator < ::Rails::Generators::Base
+    include GeneratorMixin
+
+    source_root File.expand_path("../templates", __FILE__)
+
+    argument :resource, type: :string
+    class_option :actions,
+      type: :array,
+      default: nil,
+      aliases: ["--actions", "-a"],
+      desc: 'Array of controller actions, e.g. "index show destroy"'
+
+    desc "Generates rspec request specs at spec/api"
+    def generate
+      generate_api_specs
+    end
+
+    private
+
+    def var
+      dir.singularize
+    end
+
+    def dir
+      @resource.gsub("Resource", "").underscore.pluralize
+    end
+
+    def generate_api_specs
+      if actions?("index")
+        to = File.join("spec", ApplicationResource.endpoint_namespace, dir, "index_spec.rb")
+        template("index_request_spec.rb.erb", to)
+      end
+
+      if actions?("show")
+        to = File.join("spec", ApplicationResource.endpoint_namespace, dir, "show_spec.rb")
+        template("show_request_spec.rb.erb", to)
+      end
+
+      if actions?("create")
+        to = File.join("spec", ApplicationResource.endpoint_namespace, dir, "create_spec.rb")
+        template("create_request_spec.rb.erb", to)
+      end
+
+      if actions?("update")
+        to = File.join("spec", ApplicationResource.endpoint_namespace, dir, "update_spec.rb")
+        template("update_request_spec.rb.erb", to)
+      end
+
+      if actions?("destroy")
+        to = File.join("spec", ApplicationResource.endpoint_namespace, dir, "destroy_spec.rb")
+        template("destroy_request_spec.rb.erb", to)
+      end
+    end
+
+    def resource_class
+      @resource.constantize
+    end
+
+    def type
+      resource_class.type
+    end
+
+    def model_class
+      resource_class.model
+    end
+  end
+end

data/lib/generators/graphiti/generator_mixin.rb

@@ -0,0 +1,45 @@
+module Graphiti
+  module GeneratorMixin
+    def prompt(header: nil, description: nil, default: nil)
+      say(set_color("\n#{header}", :magenta, :bold)) if header
+      say("\n#{description}") if description
+      answer = ask(set_color("\n(default: #{default}):", :magenta, :bold))
+      answer = default if answer.blank? && default != "nil"
+      say(set_color("\nGot it!\n", :white, :bold))
+      answer
+    end
+
+    def api_namespace
+      @api_namespace ||= begin
+        ns = graphiti_config["namespace"]
+
+        if ns.blank?
+          ns = prompt \
+            header: "What is your API namespace?",
+            description: "This will be used as a route prefix, e.g. if you want the route '/books_api/v1/authors' your namespace would be '/books_api/v1'",
+            default: "/api/v1"
+          update_config!("namespace" => ns)
+        end
+
+        ns
+      end
+    end
+
+    def actions
+      @options["actions"] || %w[index show create update destroy]
+    end
+
+    def actions?(*methods)
+      methods.any? { |m| actions.include?(m) }
+    end
+
+    def graphiti_config
+      File.exist?(".graphiticfg.yml") ? YAML.load_file(".graphiticfg.yml") : {}
+    end
+
+    def update_config!(attrs)
+      config = graphiti_config.merge(attrs)
+      File.open(".graphiticfg.yml", "w") { |f| f.write(config.to_yaml) }
+    end
+  end
+end

data/lib/generators/graphiti/install_generator.rb

@@ -0,0 +1,80 @@
+require_relative "generator_mixin"
+
+module Graphiti
+  class InstallGenerator < ::Rails::Generators::Base
+    include GeneratorMixin
+
+    source_root File.expand_path("templates", __dir__)
+
+    class_option :'omit-comments',
+      type: :boolean,
+      default: false,
+      aliases: ["-c"],
+      desc: "Generate without documentation comments"
+
+    desc "This generator boostraps graphiti"
+    def install
+      to = File.join("app/resources", "application_resource.rb")
+      template("application_resource.rb.erb", to)
+
+      inject_into_file "app/controllers/application_controller.rb", after: "class ApplicationController < ActionController::API\n" do
+        app_controller_code
+      end
+
+      inject_into_file "app/controllers/application_controller.rb", after: "class ApplicationController < ActionController::Base\n" do
+        app_controller_code
+      end
+
+      inject_into_file "config/application.rb", after: "Rails::Application\n" do
+        <<-'RUBY'
+    # In order for Graphiti to generate links, you need to set the routes host.
+    # When not explicitly set, via the HOST env var, this will fall back to
+    # the rails server settings.
+    # Rails::Server is not defined in console or rake tasks, so this will only
+    # use those defaults when they are available.
+    routes.default_url_options[:host] = ENV.fetch('HOST') do
+      if defined?(Rails::Server)
+        argv_options = Rails::Server::Options.new.parse!(ARGV)
+        "http://#{argv_options[:Host]}:#{argv_options[:Port]}"
+      end
+    end
+        RUBY
+      end
+
+      inject_into_file "spec/rails_helper.rb", after: /RSpec.configure.+^end$/m do
+        "\n\nGraphitiSpecHelpers::RSpec.schema!"
+      end
+
+      insert_into_file "config/routes.rb", after: "Rails.application.routes.draw do\n" do
+        if defined?(VandalUi)
+          <<-STR
+  scope path: ApplicationResource.endpoint_namespace, defaults: { format: :jsonapi } do
+    mount VandalUi::Engine, at: '/vandal'
+    # your routes go here
+  end
+          STR
+        else
+          <<-STR
+  scope path: ApplicationResource.endpoint_namespace, defaults: { format: :jsonapi } do
+    # your routes go here
+  end
+          STR
+        end
+      end
+    end
+
+    private
+
+    def omit_comments?
+      @options["omit-comments"]
+    end
+
+    def app_controller_code
+      str = ""
+      if defined?(::Responders)
+        str << "  include Graphiti::Rails::Responders\n"
+      end
+      str
+    end
+  end
+end

data/lib/generators/graphiti/resource_generator.rb

@@ -0,0 +1,180 @@
+require_relative "generator_mixin"
+
+module Graphiti
+  class ResourceGenerator < ::Rails::Generators::NamedBase
+    include GeneratorMixin
+
+    source_root File.expand_path("../templates", __FILE__)
+
+    argument :attributes, type: :array, default: [], banner: "field[:type][:index] field[:type][:index]"
+
+    class_option :'omit-comments',
+      type: :boolean,
+      default: false,
+      aliases: ["--omit-comments", "-c"],
+      desc: "Generate without documentation comments"
+
+    class_option :actions,
+      type: :array,
+      default: nil,
+      aliases: ["--actions", "-a"],
+      desc: 'Array of controller actions to support, e.g. "index show destroy"'
+
+    class_option :'attributes-from',
+      banner: "Model",
+      type: :string,
+      aliases: ["--model", "-m"],
+      desc: "Specify to use attributes from a particular model"
+
+    desc "This generator creates a resource file at app/resources, as well as corresponding controller/specs/route/etc"
+    def generate_all
+      generate_model
+      generate_controller
+      generate_application_resource unless application_resource_defined?
+      generate_route
+      generate_resource
+      generate_resource_specs
+      generate_api_specs
+    end
+
+    private
+
+    class ModelAction
+      attr_reader :class_name
+      def initialize(class_name)
+        @class_name = class_name
+      end
+
+      def invoke!
+        unless class_name.safe_constantize
+          raise "You must define a #{class_name} model before generating the corresponding resource."
+        end
+      end
+
+      def revoke!
+        # Do nothing on destroy
+      end
+    end
+
+    def generate_model
+      action(ModelAction.new(class_name))
+    end
+
+    def omit_comments?
+      @options["omit-comments"]
+    end
+
+    def attributes_class
+      return @attributes_class if @attributes_class
+
+      case @options["attributes-from"]
+      # thor will set the value to the key if no value is specified
+      when "attributes-from"
+        klass = class_name
+      when :kind_of?, String
+        klass = @options["attributes-from"].classify
+      else
+        # return nil if attributes-from isn't set or has an invalid value
+        return
+      end
+      begin
+        @attributes_class = klass.safe_constantize
+      rescue NameError
+        raise NameError, "attributes-from #{klass.inspect} does not exist."
+      end
+    end
+
+    ##
+    # Generates a list of OpenStruct(:name, :type) objects that map to
+    # the +attributes_class+ columns.
+    ##
+    def default_attributes
+      unless attributes_class.is_a?(Class) && attributes_class <= ApplicationRecord
+        raise "Unable to set #{self} default_attributes from #{attributes_class}. #{attributes_class} must be a kind of ApplicationRecord"
+      end
+      if attributes_class.table_exists?
+        return attributes_class.columns.map do |c|
+          OpenStruct.new({name: c.name.to_sym, type: c.type})
+        end
+      else
+        raise "#{attributes_class} table must exist. Please run migrations."
+      end
+    end
+
+    def resource_attributes
+      # set a temporary variable because overriding attributes causes
+      # weird behavior when the generator is run. It will override
+      # everytime regardless of the conditional.
+      if !attributes_class.nil?
+        default_attributes
+      else
+        attributes
+      end
+    end
+
+    def responders?
+      defined?(::Responders)
+    end
+
+    def generate_controller
+      to = File.join("app/controllers", class_path, "#{file_name.pluralize}_controller.rb")
+      template("controller.rb.erb", to)
+    end
+
+    def generate_application_resource
+      to = File.join("app/resources", class_path, "application_resource.rb")
+      template("application_resource.rb.erb", to)
+      require "#{::Rails.root}/#{to}"
+    end
+
+    def application_resource_defined?
+      "ApplicationResource".safe_constantize.present?
+    end
+
+    def generate_route
+      # Rails 5.2 adds `plural_route_name`, fallback to `plural_table_name`
+      plural_name = try(:plural_route_name) || plural_table_name
+
+      code = "resources :#{plural_name}"
+      code << %(, only: [#{actions.map { |a| ":#{a}" }.join(", ")}]) if actions.length < 5
+      code << "\n"
+      inject_into_file "config/routes.rb", after: /ApplicationResource.*$\n/ do
+        indent(code, 4)
+      end
+    end
+
+    def generate_resource_specs
+      opts = {}
+      opts[:actions] = @options[:actions] if @options[:actions]
+      invoke "graphiti:resource_test", [resource_klass], opts
+    end
+
+    def generate_api_specs
+      opts = {}
+      opts[:actions] = @options[:actions] if @options[:actions]
+      invoke "graphiti:api_test", [resource_klass], opts
+    end
+
+    def generate_resource
+      to = File.join("app/resources", class_path, "#{file_name}_resource.rb")
+      template("resource.rb.erb", to)
+      require "#{::Rails.root}/#{to}" if create?
+    end
+
+    def create?
+      behavior == :invoke
+    end
+
+    def model_klass
+      class_name.safe_constantize
+    end
+
+    def resource_klass
+      "#{model_klass}Resource"
+    end
+
+    def type
+      model_klass.name.underscore.pluralize
+    end
+  end
+end