oxidizer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ed6b93890738ae60feb4c4d579bb291eda9086fe768b8adb5487a124f7629539
+  data.tar.gz: 46efbd146e216d26325c1fb5024781cce988599b192035a8ad53bb4f00acf508
+SHA512:
+  metadata.gz: cfb69290fbeb108ed02fbabbed97370d3a4fca008a27be406421ba7fb85305896cdb8b22ef926d0ae298d7c6d0eb988e45ba170496ab08a57a936800b066fb75
+  data.tar.gz: 5de271eb48c4ef95ed18e353270d3359b1e12ef1e5c1a0b7a85dce8efe66f16a2b86689a1b6202a1a0fab039f313d11a2c92be30d865ddaf46f3c786db5b16d4

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2022 Brad Gessler
+
+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,103 @@
+# Oxidizer
+
+Rails controllers require a lot of boilerplate for non-trivial Rails applications. Oxidizer resources a lot of the boilerplate and spaghetti code typically seen in Rails controllers by:
+
+1. Moves authorization out of controller methods and callbacks and into policy objects via Pundit.
+2. Encourage the use of more, but smaller, controllers to handle various interactions with ActiveRecord objects and other Resources.
+3. Utiliziers PORO and inheritance for making controller code less verbose, as opposed to a DSL approach, which can be difficult to extend and obscufates how Rails controllers work.
+4. Encourages keeping business logic out of ActiveRecord objects **and** controllers by utilizing Resource objects.
+
+Putting that all together, a typical Oxidizer controller that handles CRUD actions for a blog comment feature would look like this:
+
+```ruby
+# Example Oxidizer controller for comments in a blog post.
+class CommentsController < Oxidizer::NestedResourcesController
+  protected
+    def self.resource
+      Comment
+    end
+
+    def self.parent_resource
+      Post
+    end
+
+    def assign_attributes
+      @comment.user = current_user
+      @comment.blog = @post
+    end
+
+    def permitted_params
+      [:post_id, :body]
+    end
+end
+```
+
+Since there's no DSLs, its easy to extend Oxidizer controllers to implement any type of behavior you need.
+
+## Installation
+
+Add to your Rails application Gemfile by executing:
+
+```bash
+bundle add "oxidizer"
+```
+
+Then run:
+
+```bash
+# TODO: Not implemented yet
+rails generate oxidizer:install
+```
+
+This will create the folders and files needed to get going with Oxidizer.
+
+```txt
+# TODO: Not implemented yet
+app/controllers/application_resources_controller.rb
+```
+
+## Concepts
+
+Oxidizer makes it easy to build RESTful Rails applications that follow the CRUD controller pattern and shallow routes.
+
+## Controller types
+
+There's a few types of controllers you'll want to use:
+
+### ResourcesController
+
+The most common type of controller is a resources controller. Its very much like a vanilla RESTful Rails controller where `index` is the collection of resources and `new`, `create`, `show`, `edit`, `update`, and `destroy` operate on the singular resource.
+
+For example, a blog web application might have a `Posts` Resources controller.
+
+### ResourceController
+
+Similar to above, but does not have an `index` action. Singular resources are commonly used in web applications for managing the current users profile and associated resources.
+
+For example, a blog web application might have a `Session` Resource controller that the user can create when they login and destroy when they log out.
+
+### NestedResources
+
+Nested resources are designed to be scoped within a `Resources`. They have `new`, `create`, and `index` actions, but do not have the remaining actions. The remaining CRUD actions for a nested resource should be `Resources` controller.
+
+For example, a blog's `Post` resources might have many `Comment` resources per post. The creation of the comment is within the context of the `Post` resource. After the `Comment` resource is created, the `Post` should be persisted in the `Comment` (probably as `comments.post_id`) if it needs to be accessible after its persisted.
+
+It's possible to have the other CRUD actions in a nested resource, but its discourage since nesting controller scopes can be difficult to maintain as dependencies and business logic change. Best to keep themn flat.
+
+### NestedResource
+
+A nested resources is similar to the nested resources, but is singular. For example, a `Post` may have an `Author` resource at `posts/:id/author`. The singular nested resource supports the full range of CRUD actions, but does not have `index`.
+
+### NestedWeakResource
+
+A nested weak resource is on where the underlying resource is the same as the parent resource.
+
+For example, a `Post` may require a confirmation screen before its deleted available at `posts/:id/delete_confirmation/new`. The user would press the `Confirm deletion` button on that screen which would `POST` to `/posts/:id/delete_confirmation` and destroy the object.
+
+## Contributing
+
+Open issues with reproducable steps.
+
+## 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,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/controllers/oxidizer/nested_resource_controller.rb

@@ -0,0 +1,32 @@
+module Oxidizer
+  # Controller for nesting a singular resource within a parent resource. This
+  # should only be used for creating a new resource within the scope of the parent
+  # resource, or to redirect to the un-nested resource location if it exists.
+  class NestedResourceController < NestedResourcesController
+    def show
+      # Disabled for show because show will only redirect to either
+      # the new resource or to the existing resource, which both have
+      # authorizations of their own. I did this here and not as a `skip_after_filter`
+      # to add safety for a future engineer who might try to incorrectly override
+      # this action and render the resource. If that happened, authorization would
+      # be disabled for them, which wouldn't be great.
+      skip_authorization
+      redirect_to resource.present? ? existing_resource_url : new_resource_url
+    end
+
+    protected
+      def existing_resource_url
+        url_for resource
+      end
+
+      def new_resource_url
+        url_for action: :new
+      end
+
+      # A single nested resource should only have one resource under
+      # the scope of the parent resources.
+      def find_resource
+        resources.first
+      end
+  end
+end

data/app/controllers/oxidizer/nested_resources_controller.rb

@@ -0,0 +1,91 @@
+module Oxidizer
+  class NestedResourcesController < ResourcesController
+    before_action :assign_parent_resource_instance_variable
+    before_action :assign_resources_instance_variable, only: :index
+    before_action :authorize_parent_resource
+
+    helper_method :parent_resource
+
+    protected
+      def self.parent_resource
+        raise NotImplementedError, "NestedResourcesController.parent_resource must be an ActiveModel or ActiveRecord class"
+      end
+
+      def resources
+        @_resources ||= nested_resource_scope
+      end
+
+      # Use callbacks to share common setup or constraints between actions.
+      def assign_parent_resource_instance_variable
+        instance_variable_set("@#{parent_resource_name}", parent_resource)
+      end
+
+      def parent_resource
+        @_parent_resource ||= find_parent_resource
+      end
+
+      def find_parent_resource
+        self.class.parent_resource.find_resource params[parent_resource_id_param]
+      end
+
+      # Finds the account of the resource depending on the request type and
+      # the parent resource.
+      def find_account
+        if member_request?
+          resource.account
+        elsif parent_resource.is_a? Account
+          parent_resource
+        else
+          parent_resource.account
+        end
+      end
+
+      # If we're deep, we want to show only members that are scoped
+      # from within an index.
+      def nested_resource_scope
+        query = {}
+        query[parent_resource_foreign_key] = parent_resource
+        resource_scope.where(**query)
+      end
+
+      # Assumes the route key is the foreign key, which is usually the case.
+      # This can be overridden if its not the case or the `nested_resource_scope`
+      # can be over-ridden.
+      def parent_resource_id_param
+        parent_resource_foreign_key
+      end
+
+      # Key used to find the parent resource via ActiveRecord. Typically this is the primary key of the record,
+      # but it would be a different field if you don't want to expose users to primary keys.
+      def parent_active_record_id
+        :id
+      end
+
+      # If the user doesn't have `show?` priviledge on the parent resource,
+      # then its highly likely they won't be authorized to do anything with
+      # the child resource. This isn't 100% true, but I'm having a hard time
+      # thinking of a practical edge case.
+      def authorize_parent_resource
+        authorize parent_resource, :show?
+      end
+
+    private
+      def resource_params
+        # Optionally allow the resource params because nested resources usually
+        # allow a POST request with no params that create a resource.
+        if params.key? resource_name
+          params.require(resource_name).permit(permitted_params)
+        end
+      end
+
+      # Gets the resource name of the ActiveRecord model for use by
+      # instance methods in this controller.
+      def parent_resource_name
+        self.class.parent_resource.model_name.singular
+      end
+
+      def parent_resource_foreign_key
+        "#{parent_resource_name}_id".to_sym
+      end
+  end
+end

data/app/controllers/oxidizer/nested_weak_resource_controller.rb

@@ -0,0 +1,33 @@
+module Oxidizer
+  # This controller is designed for a "Weak" resource entity, or the `parent_resource`
+  # is the same as the `resource`. This is useful if you want to have complex view logic
+  # in place to change a few parameters on a model.
+  class NestedWeakResourceController < NestedResourcesController
+    def self.resource
+      parent_resource
+    end
+
+    protected
+      # Prevents callbacks from superclasses from firing that `resources`, not `resource`
+      # routes fire. This is a non-obvios way to keep the inheritance on the simpler side.
+      # TODO: Can I infer a plural vs singular controller in a better way from params? I
+      # could look at action names, but those aren't great. Hmm.
+      def member_request?
+        true
+      end
+
+      def find_resource
+        parent_resource
+      end
+
+      # This is for the `account_layout` helper in all sub-classes.
+      def find_account
+        parent_resource.account
+      end
+
+      def assign_new_resource
+        # Do nothing; resource is already created, you're
+        # just doing something to it.
+      end
+  end
+end

data/app/controllers/oxidizer/resources_controller.rb

@@ -0,0 +1,253 @@
+module Oxidizer
+  class ResourcesController < ApplicationController
+    before_action :authenticate_user
+    before_action :assign_resource_instance_variable, if: :member_request?
+    before_action :authorize_resource, if: :member_request?
+    before_action :assign_resources_instance_variable, only: :index
+
+    helper_method \
+      :resource_name,
+      :resource_class,
+      :resource,
+      :resources,
+      :created_resource,
+      :updated_resource
+
+    # These are used to contain the serialized IDs for resources so they can
+    # be accessed from views on the other side of the action that's performed.
+    add_flash_types :created_resource, :updated_resource
+
+    def self.resource
+      raise NotImplementedError, "ResourcesController.resource must be an ActiveModel or ActiveRecord class"
+    end
+
+    def index
+    end
+
+    def show
+    end
+
+    def new
+      assign_new_resource
+      assign_attributes
+      authorize_resource
+    end
+
+    def edit
+    end
+
+    def create
+      self.resource = resource_class.new(resource_params)
+      assign_attributes
+      authorize_resource
+
+      respond_to do |format|
+        if resource.save
+          flash_created_resource
+          format.html { redirect_to create_redirect_url, notice: create_notice }
+          format.json { render :show, status: :created, location: resource }
+          create_success_formats format
+        else
+          format.html { render :new, status: :unprocessable_entity }
+          format.json { render json: resource.errors, status: :unprocessable_entity }
+        end
+      end
+    end
+
+    def update
+      resource.assign_attributes(resource_params)
+      assign_attributes
+      authorize_resource
+
+      respond_to do |format|
+        if resource.save
+          flash_updated_resource
+          format.html { redirect_to update_redirect_url, notice: update_notice }
+          format.json { render :show, status: :ok, location: resource }
+        else
+          format.html { render :edit, status: :unprocessable_entity }
+          format.json { render json: resource.errors, status: :unprocessable_entity }
+        end
+      end
+    end
+
+    def destroy
+      resource.destroy
+
+      respond_to do |format|
+        format.html { redirect_to destroy_redirect_url, notice: destroy_notice }
+        format.json { head :no_content }
+      end
+    end
+
+    protected
+      def member_request?
+        params.key? resource_id_param
+      end
+
+      def collection_request?
+        !member_request?
+      end
+
+      # Gets the resource name of the ActiveRecord model for use by
+      # instance methods in this controller.
+      def resource_name
+        resource_class.model_name.singular
+      end
+
+      def resources_name
+        resource_class.model_name.plural
+      end
+
+      def resource_class
+        self.class.resource
+      end
+
+      # Permitted params the resource controller allows
+      def permitted_params
+        []
+      end
+
+      # A scope used for collections scoped by Pundit auth.
+      def resource_scope
+        policy_scope.joins(:user)
+      end
+
+      # `policy_scope` is defined by Pundit.
+      def policy_scope(scope = resource_class)
+        super(scope)
+      end
+
+      # Sets instance variable for templates to match the model name. For
+      # example, `Account` model name would set the `@accounts` instance variable
+      # for template access.
+      def assign_resources_instance_variable
+        instance_variable_set("@#{resources_name}", resources)
+      end
+
+      # A hook that allows sub-classes to assign attributes to a model.
+      def assign_attributes
+        resource.user = current_user if resource.respond_to? :user=
+      end
+
+      # Redirect to this url after a resource is created
+      def create_redirect_url
+        resource
+      end
+
+      # Redirect to this url after a resource is updated
+      def update_redirect_url
+        resource
+      end
+
+      # Redirect to this url after a resource is destroyed
+      def destroy_redirect_url
+        resources_name.to_sym
+      end
+
+      # Key rails routing uses to find resource. Rails resources defaults to the `:id` value.
+      def resource_id_param
+        :id
+      end
+
+      # Use callbacks to share common setup or constraints between actions.
+      def assign_resource_instance_variable
+        instance_variable_set("@#{resource_name}", resource)
+      end
+
+      def resource
+        @_resource ||= find_resource
+      end
+
+      # Sometimes we need to set the resource to hack the controller from another method, such as the
+      # case of setting the instance variable to be an instance of a model.
+      def resource=(value)
+        @_resource = value
+        assign_resource_instance_variable
+      end
+
+      # Finds resource, which is called by `assign_resource` to assign it to the right variables.
+      def find_resource
+        resource_class.find_resource params[resource_id_param]
+      end
+
+      # Initializes a model for the `new` action.
+      def assign_new_resource
+        self.resource = resource_class.new
+      end
+
+      def resources
+        @_resources ||= resource_scope
+      end
+
+      # Additional formats can be specified for successful response creations
+      def create_success_formats(format)
+      end
+
+      # Authorizse resource with Pundit.
+      def authorize_resource(*args)
+        authorize resource, *args
+      end
+
+      # `flash[:notice]` message when a resource is successfully created
+      def create_notice
+        "#{notice_resource_name} created"
+      end
+
+      # `flash[:notice]` message when a resource is successfully updated
+      def update_notice
+        "#{notice_resource_name} updated"
+      end
+
+      # `flash[:notice]` message when a resource is successfully deleted
+      def destroy_notice
+        "#{notice_resource_name} deleted"
+      end
+
+      # What do you call the things that are created?
+      def notice_resource_name
+        resource_name.humanize.capitalize
+      end
+
+      # Get the current account of the resource, if possible.
+      def find_account
+        resource.account if member_request?
+      end
+
+    private
+      # Never trust parameters from the scary internet, only allow the white list through.
+      def resource_params
+        params.require(resource_name).permit(permitted_params)
+      end
+
+      # Assign global_id to resource that was just created. This is used in subsequent
+      # screens to display a link or information about the resource that was just created.
+      def flash_created_resource
+        flash[:created_resource] = resource_global_uri
+      end
+
+      # Resource that was created from the last action.
+      def created_resource
+        @created_resource ||= GlobalID::Locator.locate flash[:created_resource]
+      end
+
+      # Assign global_id to resource that was just created. This is used in subsequent
+      # screens to display a link or information about the resource that was just created.
+      def flash_updated_resource
+        flash[:updated_resource] = resource_global_uri
+      end
+
+      # Generates a GlobalID object that can be serialized into flash for the next action to
+      # pickup and find the object as an updated or created resource. The reason this check
+      # exists is because some resources are ApplicationModels (NOT Records) and don't have
+      # a way to find via ActiveRecord queries.
+      def resource_global_uri
+        resource.to_global_id.uri if resource.respond_to? :to_global_id
+      end
+
+      # Resource that was updated from the last action.
+      def updated_resource
+        @updated_resource ||= GlobalID::Locator.locate flash[:updated_resource]
+      end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,2 @@
+Rails.application.routes.draw do
+end

data/lib/oxidizer/engine.rb

@@ -0,0 +1,4 @@
+module Oxidizer
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/oxidizer/version.rb

@@ -0,0 +1,3 @@
+module Oxidizer
+  VERSION = "0.1.0"
+end

data/lib/oxidizer.rb

@@ -0,0 +1,6 @@
+require "oxidizer/version"
+require "oxidizer/engine"
+
+module Oxidizer
+  # Your code goes here...
+end

data/lib/tasks/oxidizer_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :oxidizer do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: oxidizer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Brad Gessler
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-06-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.3
+description: Rapidly build Rails controllers.
+email:
+- bradgessler@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/config/resourcefully_manifest.js
+- app/controllers/oxidizer/nested_resource_controller.rb
+- app/controllers/oxidizer/nested_resources_controller.rb
+- app/controllers/oxidizer/nested_weak_resource_controller.rb
+- app/controllers/oxidizer/resources_controller.rb
+- config/routes.rb
+- lib/oxidizer.rb
+- lib/oxidizer/engine.rb
+- lib/oxidizer/version.rb
+- lib/tasks/oxidizer_tasks.rake
+homepage: https://github.com/rocketshipio/oxidizer
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/rocketshipio/oxidizer
+  source_code_uri: https://github.com/rocketshipio/oxidizer
+  changelog_uri: https://github.com/rocketshipio/oxidizer
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key:
+specification_version: 4
+summary: Rapidly build Rails controllers.
+test_files: []