gearhead 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b2840550719a44e41f271d9dd420ac4c848f5a914214e1125ccae0db63f0e460
+  data.tar.gz: 4efb4442da94ebdd53b4d55d865866cdf516315906ed7df74c090f46b8071db0
+SHA512:
+  metadata.gz: 5c0c1f1fa96578021c7e52653f689442a35f840f5e883f69ac0fc0f1a07fcb8fdc7efbd9b9857a30ea457c59860cb38806678678d67c088a7b2d3c5dcac00e37
+  data.tar.gz: bdc1d6d0d3b5b93f8fbf7c727a80141720036960d3d162475e04b3ebbbdd29e79e5b0a2f74fe05550f06608fe0c797fc0744465e1a81ddcc4243a93c494c65f6

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2020 Josh
+
+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,220 @@
+# Gearhead test application
+
+Gearhead turns your database into a RESTful API. It's like if ActiveAdmin and Grape had a baby.
+
+## Installation
+
+Gearhead is a Rails engine, for now.
+
+```ruby
+gem 'gearhead'
+```
+
+## Setting up Gearhead
+
+After installing Gearhead, you need to run the generator.
+
+```
+rails g gearhead:install
+```
+
+which generates:
+
+```
+config/initializers/gearhead.rb
+app/gears/.keep
+```
+
+and modifies your routes:
+
+```ruby
+Gearbox.routes(self)
+```
+
+## Configuration
+
+You can change most of these on the Gear-level, but we have opinions.
+
+```ruby
+Gearhead.setup do |config|
+  # == Routing
+  #
+  # The endpoint in which to mount gearhead on.
+  # Default is "/gearhead" — must start with a slash, and have no trailing slash
+  # config.endpoint = "/api/v314"
+  #
+  # The default actions a Gear can respond to
+  # Default is [:index, :create, :show, :update, :destroy]
+  # config.actions = [:index, :show]
+  #
+
+  # == Querying
+  #
+  # The default scope of a Gear will be the default scope of the resource.
+  # Default is nil
+  # config.scope = :visible
+  #
+
+  # == Params
+  #
+  # Ignored params for creating/updating records
+  # Default is [:id, :created_at, :updated_at]
+  # config.ignored_params = [:id, :created_at, :updated_at]
+  #
+
+  # == Automount
+  #
+  # Change this to true if you want to automatically mount all your resources.
+  # config.automount.enabled = false
+  #
+  # Automatically mount most of your resources
+  # config.automount.resources = ['User', 'Post', 'Comment']
+  #
+  # Don't automatically mount these resources
+  # config.automount.excluded = ['User', 'Post']
+  #
+
+  # == Serialization
+  #
+  # Change the default serializer
+  # Currently supports FastJSONAPI (:fast_jsonapi) and ActiveModelSerializers (:active_model_serializers)
+  # Default is :fast_jsonapi
+  # config.serialization.adapter = :fast_jsonapi
+  #
+
+  # == Pagination
+  #
+  # Change the default paginator
+  # Currently supports :pagy and :will_paginate
+  # Default is :pagy
+  # config.pagination.adapter = :pagy
+  #
+
+  # == Controller
+  #
+  # Base class for the Gearhead controller
+  # Default is 'ApplicationController'
+  # config.base_controller = 'ApplicationController'
+  #
+end
+```
+
+## Exposing your data
+
+Gearhead does some metaprogramming to generate standard RESTful endpoints for your defined Rails models. They do this with Gears.
+
+A Gear is responsible for configuring the controller, including resource retrieval, serialization, and response.
+
+By default, Gearhead doesn't automatically mount all your resources. You can change this if you want in your initializer.
+
+To create a Gear, drop it in `/app/gears` and register it with `Gearhead.register Model, options`. Prefer a constant over a string.
+
+```ruby 
+Gearhead.register Post; end
+```
+
+will generate `/gearhead/posts` — or whatever `Model.model_name.route_key` is. Change the path:
+
+```ruby
+Gearhead.register Post, path: "postz"; end 
+```
+
+**A note about automount**: If you have automount enabled and call `/posts`, and you have explicitly defined this Gear,
+the defined Gear will take precedence. If you define a custom path such as `postz` and navigate to `/posts` with automount 
+enabled, the defined Gear will still take precedence.
+
+## Customizing Gears
+
+### Actions
+
+Change what CRUD actions the Gear can respond to:
+
+```ruby
+Gearhead.register Post do 
+  actions :index, :show
+  # or
+  actions except: [:create, :update, :delete]
+end
+``` 
+
+Want to expose `/gearhead/posts/favorites`?
+
+```ruby
+Gearhead.register Post do 
+  collection_action :favorites, via: :get do 
+    # do something
+  end
+end
+```
+
+Expose `GET /gearhead/posts/:id/report` and `POST /gearhead/posts/:id/report`:
+
+```ruby
+Gearhead.register Post do 
+  member_action :report, via: [:get, :post] do 
+    if request.get? 
+      resource.reports.all
+    elsif request.post? 
+      resource.reports.create!
+    end
+  end
+end
+```
+
+### Handling pagination 
+
+```ruby 
+Gearhead.register Post do 
+  per_page 5 
+  # or disable it 
+  pagination false 
+end
+```
+
+### Serializing your objects
+
+Just define what attributes you want exposed:
+
+```ruby 
+Gearhead.register Post do 
+  attributes :id, :name
+end
+```
+
+### Finding resources
+
+Change your finder:
+
+```ruby 
+Gearhead.register Post do 
+  finder do 
+    resource_class.find_by(token: params[:resource_id])
+  end
+end
+```
+
+### Permitting params
+
+Works just like the params you're used to:
+
+```ruby 
+Gearhead.register Post do 
+  permit_params :user_id, :content
+  # or do it for a certain subset of actions
+  permit_params :user_id, :content, only: :create 
+  permit_params :content, only: :update
+end
+```
+
+## TODO
+
+* Better param handling
+* Handling params for member actions and collection actions
+
+## Contributing
+
+Do things.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,32 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Gearhead'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/app/controllers/gearhead/application_controller.rb

@@ -0,0 +1,5 @@
+module Gearhead
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+  end
+end

data/app/controllers/gearhead/gears_controller.rb

@@ -0,0 +1,98 @@
+# todo:
+if defined?(ActiveModelSerializers)
+  ActiveModelSerializers.config.serializer_lookup_enabled = false
+end
+
+module Gearhead
+  class GearsController < ::Gearhead.config.base_controller.constantize
+    before_action :find_gear!
+    before_action :ensure_action_enabled!, only: [:index, :create, :show, :update, :destroy]
+    before_action :find_resource!, except: [:index, :create, :collection_action]
+
+    def index
+      render json: Gearhead::Actions::Index.build(@gear, request), adapter: false
+    end
+
+    def create
+      @resource = Gearhead::Actions::Create.build(@gear, request)
+      if @resource.save
+        render json: @gear.serializer_class.new(@resource)
+      else
+        render json: { errors: @resource.errors }
+      end
+    end
+
+    def show
+      @resource = Gearhead::Actions::Show.build(@gear, request, resource: @resource)
+      render json: @gear.serializer_class.new(@resource)
+    end
+
+    def update
+      @resource = Gearhead::Actions::Update.build(@gear, request, resource: @resource)
+      if @resource.save
+        render json: @gear.serializer_class.new(@resource)
+      else
+        render json: { errors: @resource.errors }
+      end
+    end
+
+    def destroy
+      if @resource.destroy
+        render json: @gear.serializer_class.new(resource)
+      else
+        render json: { errors: resource.errors }
+      end
+    end
+
+    def member_action
+      action = @gear._gear_member_actions[params[:member_action].to_sym]
+      if action && action.verbs.include?(request.request_method.to_sym.downcase)
+        return render json: instance_exec(&action.block)
+      end
+    end
+
+    def collection_action
+      action = @gear._gear_collection_actions[params[:collection_action]]
+      if action && action.verbs.include?(request.request_method.to_sym.downcase)
+        return render json: instance_exec(&action.block)
+      end
+    end
+
+    private
+
+    def find_gear!
+      @gear = Gearhead.gear_for(request)
+      return @gear if @gear
+
+      if @gear.nil?
+        error!("Can't find or infer gear.", 404)
+      end
+      if @gear == false
+        error!("Gear already mounted somewhere else.", 500)
+      end
+    end
+
+    # remember that request method is from rack so GET/POST/etc.
+    def check_collection_actions!
+      action = @gear._gear_collection_actions[request.request_method][params[:resource_id].to_sym]
+      if action
+        return render json: instance_exec(&action)
+      end
+    end
+
+    def find_resource!
+      @resource = ::Gearhead::ResourceFinder.for(@gear, params)
+      error!("#{@gear.resource.name} not found for #{@gear._gear_param_key} #{params[:resource_id]}") if @resource.nil?
+    end
+
+    def ensure_action_enabled!
+      unless @gear.action_enabled?(action_name.to_sym)
+        error!("Action not allowed for #{@gear.resource.name}##{action_name}", 405)
+      end
+    end
+
+    def error!(msg, code = 400)
+      render json: Serializers::Lookup.for(:invalid_request).new(request, msg, code), serializer: nil
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,9 @@
+Gearhead::Engine.routes.draw do
+  scope module: :gearhead do
+    # resources :gears, path: ':resource_class', param: :resource_id do
+    #  member do
+    #    match ':member_action' => 'gears#member_action', via: :all
+    #  end
+    # end
+  end
+end

data/lib/gearhead.rb

@@ -0,0 +1,44 @@
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+module Gearhead
+  def self.gearbox
+    @gearbox ||= Gearbox.new
+  end
+
+  def self.routes(rails_router)
+    gearbox.routes(rails_router)
+  end
+
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  def self.setup
+    gearbox.setup!
+    yield config
+    gearbox.prepare!
+  end
+
+  def self.register(resource_class, options = {}, &block)
+    gear = Gear.new(resource_class, options)
+    gear.instance_exec(&block)
+    registry.register(gear)
+  end
+
+  def self.registry
+    @registry ||= Registry.new
+  end
+
+  def self.gear_for(request)
+    GearLookup.for(request)
+  end
+end
+
+# things that don't support autoloading
+
+require 'gearhead/engine'
+require 'pagy'
+require 'jsonapi/serializer'

data/lib/gearhead/actions/create.rb

@@ -0,0 +1,30 @@
+module Gearhead
+  module Actions
+    class Create
+      delegate_missing_to :@request
+
+      def self.build(gear, request)
+        new(gear, request).build
+      end
+
+      attr_reader :resource, :gear, :request
+      def initialize(gear, request)
+        @gear = gear
+        @request = request
+        @resource = new_resource
+      end
+
+      def build
+        params = ParamsBuilder.new(self).for(:create)
+        @resource.assign_attributes(params)
+        @resource
+      end
+
+      private
+
+      def new_resource
+        @gear.resource.new
+      end
+    end
+  end
+end