nexus_cqrs 0.2.2 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24bafc3e27cbf1ef65d1e507bdb2798b67283c92c64b274bbf8818cfffa9618a
-  data.tar.gz: e653d3e7b76bc2173a780cf6128974afaecaba8278c0f39e56527ae442395cff
+  metadata.gz: 967dfb16241304d1d0f2233b23e3410b87abff47ec4a916569101a53e4b963c5
+  data.tar.gz: d528d7da45c96cae5fe8a403116e3f9c8abc83c2842dbd165dfa5c3267a81e1d
 SHA512:
-  metadata.gz: 38a848d5da2a2a61116f1bb2f04df2fae1c0cb368e6482854e0f7896a9bfcd0b2baab39e58c223c2b1f5a1a0c62bc028c0dddf1d2daccebc7268010e9506559c
-  data.tar.gz: 6f7b0c32343f39b5b3eb61b9c4afb5cc338bbce81eeb5d998b0d0e1293fe1fa35984264f86ed8fbc8d1a0a29106602566a0ee00096951b4d54fc63ddb3d9f3d7
+  metadata.gz: 1f407d669371be6e3fd4f9ad4e55f92678b6fc82825b1dba6f5bf4a1dabb070c79005bdf37a114dd2461f6b99d7213daf777894d04f3337daf4a8255a74fa2f6
+  data.tar.gz: 6d31c90bff990bd92f7aeb9ffcf289d1fe47bb5fd987d47f14fb12e7a7d9baa0571f731a466dff569999976a370c7028a6380c8f4423a5798ecc1063f8847029

data/.gitignore

@@ -9,3 +9,8 @@
 /.gem
 /spec/lib/tmp
 *.gem
+
+results/rubocop.html
+
+# Ignore IDE configuration
+nexus_cqrs.iml

data/.rubocop.yml

@@ -3,9 +3,14 @@ inherit_gem:
 
 AllCops:
   Exclude:
-    - 'lib/generators/nexus_cqrs/templates/**/*.rb'
+    - db/schema.rb
+    - db/seeds.rb
+    - db/migrate/*.rb
+    - config/initializers/devise.rb
+    - spec/**/*
+
+Style/Documentation:
+  Enabled: false
 
 Style/GlobalVars:
   Enabled: false
-Style/FrozenStringLiteralComment:
-  Enabled: false

data/Gemfile

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in cqrs-core.gemspec

data/Gemfile.lock

@@ -4,104 +4,111 @@ PATH
     nexus_cqrs (0.1.0)
       generator_spec
       ibsciss-middleware
+      pundit
+      strings-case
       thread_safe
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actionpack (6.0.3.2)
-      actionview (= 6.0.3.2)
-      activesupport (= 6.0.3.2)
-      rack (~> 2.0, >= 2.0.8)
+    actionpack (6.1.4.1)
+      actionview (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+      rack (~> 2.0, >= 2.0.9)
       rack-test (>= 0.6.3)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.0, >= 1.2.0)
-    actionview (6.0.3.2)
-      activesupport (= 6.0.3.2)
+    actionview (6.1.4.1)
+      activesupport (= 6.1.4.1)
       builder (~> 3.1)
       erubi (~> 1.4)
       rails-dom-testing (~> 2.0)
       rails-html-sanitizer (~> 1.1, >= 1.2.0)
-    activesupport (6.0.3.2)
+    activesupport (6.1.4.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 0.7, < 2)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
-      zeitwerk (~> 2.2, >= 2.2.2)
-    ast (2.4.1)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    ast (2.4.2)
     builder (3.2.4)
-    concurrent-ruby (1.1.7)
+    concurrent-ruby (1.1.9)
     crass (1.0.6)
     diff-lcs (1.4.4)
-    erubi (1.9.0)
+    erubi (1.10.0)
     generator_spec (0.9.4)
       activesupport (>= 3.0.0)
       railties (>= 3.0.0)
-    i18n (1.8.5)
+    i18n (1.8.11)
       concurrent-ruby (~> 1.0)
     ibsciss-middleware (0.4.2)
-    loofah (2.6.0)
+    loofah (2.12.0)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
     method_source (1.0.0)
-    mini_portile2 (2.4.0)
-    minitest (5.14.1)
-    nokogiri (1.10.10)
-      mini_portile2 (~> 2.4.0)
-    parallel (1.19.2)
-    parser (2.7.1.4)
+    mini_portile2 (2.6.1)
+    minitest (5.14.4)
+    nokogiri (1.12.5)
+      mini_portile2 (~> 2.6.1)
+      racc (~> 1.4)
+    parallel (1.21.0)
+    parser (3.0.2.0)
       ast (~> 2.4.1)
+    pundit (2.1.1)
+      activesupport (>= 3.0.0)
+    racc (1.6.0)
     rack (2.2.3)
     rack-test (1.1.0)
       rack (>= 1.0, < 3)
     rails-dom-testing (2.0.3)
       activesupport (>= 4.2.0)
       nokogiri (>= 1.6)
-    rails-html-sanitizer (1.3.0)
+    rails-html-sanitizer (1.4.2)
       loofah (~> 2.3)
-    railties (6.0.3.2)
-      actionpack (= 6.0.3.2)
-      activesupport (= 6.0.3.2)
+    railties (6.1.4.1)
+      actionpack (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
       method_source
-      rake (>= 0.8.7)
-      thor (>= 0.20.3, < 2.0)
+      rake (>= 0.13)
+      thor (~> 1.0)
     rainbow (3.0.0)
-    rake (13.0.1)
-    regexp_parser (1.7.1)
-    rexml (3.2.4)
-    rspec (3.9.0)
-      rspec-core (~> 3.9.0)
-      rspec-expectations (~> 3.9.0)
-      rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.2)
-      rspec-support (~> 3.9.3)
-    rspec-expectations (3.9.2)
+    rake (13.0.6)
+    regexp_parser (2.1.1)
+    rexml (3.2.5)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.1)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-support (3.9.3)
-    rubocop (0.86.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.3)
+    rubocop (1.22.3)
       parallel (~> 1.10)
-      parser (>= 2.7.0.1)
+      parser (>= 3.0.0.0)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.7)
+      regexp_parser (>= 1.8, < 3.0)
       rexml
-      rubocop-ast (>= 0.0.3, < 1.0)
+      rubocop-ast (>= 1.12.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 2.0)
-    rubocop-ast (0.3.0)
-      parser (>= 2.7.1.4)
-    rubocop-shopify (1.0.4)
-      rubocop (>= 0.85, < 0.87)
-    ruby-progressbar (1.10.1)
-    thor (1.0.1)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.13.0)
+      parser (>= 3.0.1.1)
+    rubocop-shopify (1.0.7)
+      rubocop (~> 1.4)
+    ruby-progressbar (1.11.0)
+    strings-case (0.3.0)
+    thor (1.1.0)
     thread_safe (0.3.6)
-    tzinfo (1.2.7)
-      thread_safe (~> 0.1)
-    unicode-display_width (1.7.0)
-    zeitwerk (2.4.0)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.1.0)
+    zeitwerk (2.5.1)
 
 PLATFORMS
   ruby

data/README.md

@@ -1,8 +1,11 @@
-# Cqrs::Core
+# Nexus CQRS
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/cqrs/core`. To experiment with that code, run `bin/console` for an interactive prompt.
+Built by the NexusMods team for providing a universal way of organising CQRS logic (Command and Queries) and permission
+management. Used by most of NexusMod's rails applications.
 
-TODO: Delete this and the text above, and describe your gem
+The core concept of this gem is to provide a MessageBus that can invoked handlers registered to certain commands.
+This allows developers to separate business and application logic, whilst also seperating read operations from write
+operations (Queries and Commands).
 
 ## Installation
 
@@ -20,39 +23,119 @@ Or install it yourself as:
 
     $ gem install nexus_cqrs
 
-## Usage
+## Getting Started
 
-Generators can be used to aide in the creation of Commands and Queries:
+### Generators
+
+Generators can be used to aid in the creation of Commands and Queries:
 
     rails g nexus_cqrs:command CommandName
     rails g nexus_cqrs:query QueryName
 
-Once installed, a CommandBus is required to control the flow of Commands and/or Queries:
+Optionally, a command can be scaffolded with basic authorisation logic with `--permission`
+
+    rails g nexus_cqrs:command CommandName --permission
+    rails g nexus_cqrs:query QueryName --permission
+
+Once a command has been created, two new files will be created under `/app/domain/command` or `/app/domain/query`
+depending on which generator was used. An initializer will also be created - `register_cqrs_handlers.rb`
+
+### Command Bus and Executor
+
+In `register_cqrs_handlers.rb`, the command bus and executor will be created and used to register queries and commands:
+
+```ruby
+middleware_stack = Middleware::Builder.new do |b|
+  # Configure additional middleware for the CQRS stack here
+end
+
+command_bus = NexusCqrs::CommandBus.new(middleware: middleware_stack)
+query_bus = NexusCqrs::CommandBus.new(middleware: middleware_stack)
+
+$COMMAND_EXECUTOR = NexusCqrs::CommandExecutor.new(command_bus)
+$QUERY_EXECUTOR = NexusCqrs::CommandExecutor.new(query_bus)
+```
+
+*NOTE: By default, all classes extending `BaseCommand` and `BaseQuery` in the `app/domain` directory will be 
+registered automatically.* 
 
 ### Middleware
 
-Middleware can be created by extending the base middleware:
+Middleware can be created by extending the base middleware and injecting into the middleware stack:
 
 ```ruby
+# my_middleware.rb
 class MyMiddleware < NexusCqrs::BaseMiddleware
   def call(command)
     @next.call(command)
   end
 end
+
+# register_cqrs_handlers.rb
+middleware_stack = Middleware::Builder.new do |b|
+  b.use MyMiddleware
+end
+
+command_bus = Bus.new(middleware: middleware_stack)
 ```
 
-The above middleware will pass responsibility for execution to the next responder in the chain.
+The above middleware will pass responsibility for execution to the next responder in the chain and will be ran BEFORE 
+the handler is invoked for every message executed through the `CommandExecutor`
 
 For more information on writing middleware see: https://github.com/Ibsciss/ruby-middleware
 
-When creating a bus, middleware can be attached like so:
+### Metadata
+
+Commands/Queries can contain data, but data can also be injected into the message via metadata before the message is 
+executed:
 
 ```ruby
-middleware_stack = Middleware::Builder.new do |b|
-  b.use MyMiddleware
-end
+command.set_metadata(:current_user, user)
+execute(command)
+```
 
-command_bus = Bus.new(middleware: middleware_stack)
+### Authorisation
+
+There are various tools and helpers to aid with authorisation in this gem. Firstly, the system must be aware of the 
+user that is calling the command, this can be done by providing the current user and global permissions as metadata: 
+
+```ruby
+message.set_metadata(:current_user, current_user)
+message.set_metadata(:global_permissions, @access_token[:global_permissions])
+execute(message)
+```
+Once the metadata is set, the handler can than access the metadata - which in turn can invoke the `authorize` method:
+
+```ruby
+  class ModerateHandler < BaseCommandHandler
+    include NexusCqrs::Helpers
+
+    # @param [Commands::Moderate] command
+    def call(command)
+      mod = Mod.kept.find(command.mod_id)
+
+      authorize(command, mod)
+    ...
+```
+
+This will look up the correct Policy and automatically pass the metadata from the command, converting it into a 
+`UserContext` object:
+
+```ruby
+# Pull context variables from command
+user = message.metadata[:current_user]
+global_permissions = message.metadata[:global_permissions]
+
+# Instantiate new policy class, with context
+policy = policy_class.new(UserContext.new(user, global_permissions), record)
+```
+
+This will allow the policy class to access the `PermissionProvider` and retrieve any permission:
+
+```ruby
+def moderate?
+  permissions.has_permission?('mod:moderate', ModPermission, record.id)
+end
 ```
 
 ## Development
@@ -66,4 +149,4 @@ To contribute to this gem, simple pull the repository, run `bundle install` and
 
 ## Releasing
 
-The release process is tied to the git tags. Simply creating a new tag and pushing will trigger a new release to reubygems.
+The release process is tied to the git tags. Simply creating a new tag and pushing will trigger a new release to rubygems.

data/Rakefile

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require "bundler/gem_tasks"
 require 'bundler/gem_tasks'
 task(default: :spec)

data/bin/console

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'bundler/setup'
 require 'cqrs/core'

data/lib/generators/nexus_cqrs/USAGE

@@ -2,7 +2,7 @@ Description:
     Generates a new Query object, along with the QueryHandler
 
 Example:
-    rails generate cqrs:query GetUserById
+    rails generate cqrs:query GetUserById --permission
 
     This will create:
         app/domain/queries/get_user_by_id.rb

data/lib/generators/nexus_cqrs/command_generator.rb

@@ -1,30 +1,30 @@
+# frozen_string_literal: true
 require 'rails/generators/base'
 
 module NexusCqrs
   class CommandGenerator < Rails::Generators::NamedBase
     source_root File.expand_path('templates', __dir__)
+    class_option :permission, type: :string, default: nil
 
     def copy_command_file
       file_path = class_name.underscore
 
+      @permission = options['permission']
+
       template('command.rb', "app/domain/commands/#{file_path}.rb")
       template('command_handler.rb', "app/domain/commands/#{file_path}_handler.rb")
 
-      register_command(class_name)
+      register_command
     end
 
     private
 
-    def register_command(full_name)
+    def register_command
       handler_config = 'config/initializers/register_cqrs_handlers.rb'
 
       unless File.exist?('config/initializers/register_cqrs_handlers.rb')
         template('register_cqrs_handlers.rb', handler_config)
       end
-
-      code_to_inject = "$COMMAND_EXECUTOR.register_command(#{full_name}, #{full_name}Handler.new)\n"
-
-      inject_into_file(handler_config, code_to_inject, after: "# Register Commands\n")
     end
   end
 end

data/lib/generators/nexus_cqrs/query_generator.rb

@@ -1,30 +1,30 @@
+# frozen_string_literal: true
 require 'rails/generators/base'
 
 module NexusCqrs
   class QueryGenerator < Rails::Generators::NamedBase
     source_root File.expand_path('templates', __dir__)
+    class_option :permission, type: :string, default: nil
 
     def copy_query_file
       file_path = class_name.underscore
 
+      @permission = options['permission']
+
       template('query.rb', "app/domain/queries/#{file_path}.rb")
       template('query_handler.rb', "app/domain/queries/#{file_path}_handler.rb")
 
-      register_query(class_name)
+      register_query
     end
 
     private
 
-    def register_query(full_name)
+    def register_query
       handler_config = 'config/initializers/register_cqrs_handlers.rb'
 
       unless File.exist?('config/initializers/register_cqrs_handlers.rb')
         template('register_cqrs_handlers.rb', handler_config)
       end
-
-      code_to_inject = "$QUERY_EXECUTOR.register_command(#{full_name}, #{full_name}Handler.new)\n"
-
-      inject_into_file(handler_config, code_to_inject, after: "# Register Queries\n")
     end
   end
 end

data/lib/generators/nexus_cqrs/templates/command_handler.rb

@@ -1,9 +1,26 @@
+# frozen_string_literal: true
 module Commands
-  class <%= class_name %>Handler < NexusCqrs::BaseCommandHandler
+  # Command handler
+  class <%= class_name %>Handler < BaseCommandHandler
+    <% if @permission %>include NexusCqrs::Helpers<% end %>
 
-    # call is where the Command is executed
+    # @param [<%= class_name %>] command
     def call(command)
+      <% if @permission %>authorize(command, Model)<% end %>
 
+      domain_event(command)
     end
+
+    private
+
+      def domain_event(command)
+        NexusDomainEvents::Event.new(
+          message_name: :ENTITY_WAS_ACTIONED,
+          actor: command.metadata[:current_user].member_id,
+          payload: {
+            object_id: command.id,
+          }
+        )
+      end
   end
 end

data/lib/generators/nexus_cqrs/templates/query_handler.rb

@@ -1,9 +1,10 @@
 module Queries
   class <%= class_name %>Handler < NexusCqrs::BaseQueryHandler
+    <% if @permission %>include NexusCqrs::Helpers<% end %>
 
-    # call is where the Query is executed
+    # @param [<%= class_name %>] command
     def call(command)
-
+      <% if @permission %>authorize(command, Model)<% end %>
     end
   end
 end

data/lib/generators/nexus_cqrs/templates/register_cqrs_handlers.rb

@@ -1,9 +1,24 @@
-command_bus = NexusCqrs::CommandBus.new
-query_bus = NexusCqrs::CommandBus.new
+# frozen_string_literal: true
+Rails.configuration.to_prepare do
+  middleware_stack = Middleware::Builder.new do |b|
+  end
 
-$COMMAND_EXECUTOR = NexusCqrs::CommandExecutor.new command_bus
-$QUERY_EXECUTOR = NexusCqrs::CommandExecutor.new query_bus
+  command_bus = NexusCqrs::CommandBus.new(middleware: middleware_stack)
+  query_bus = NexusCqrs::CommandBus.new(middleware: middleware_stack)
 
-# Register Queries
+  $COMMAND_EXECUTOR = NexusCqrs::CommandExecutor.new(command_bus)
+  $QUERY_EXECUTOR = NexusCqrs::CommandExecutor.new(query_bus)
 
-# Register Commands
+  # Register Commands
+  $QUERY_EXECUTOR.configure_handlers do |executor|
+    # Manually registered queries should always go above the autoregister
+
+    executor.autoregister(NexusCqrs::BaseQuery, 'app/domain/queries')
+  end
+
+  $COMMAND_EXECUTOR.configure_handlers do |executor|
+    # Manually registered commands should always go above the autoregister
+
+    executor.autoregister(NexusCqrs::BaseCommand, 'app/domain/commands')
+  end
+end

data/lib/nexus_cqrs/auth/auth.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+require 'pundit'
+require 'strings-case'
+
+module NexusCqrs
+  # Concern used to provide authorisation abilities to handlers and other classes. Overrides pundit's `authorize` method
+  # and creates helpers for the permission_provider
+  module Auth
+    include Pundit
+
+    # Overrides pundit's `authorize` method, allowing the message to be passed
+    #
+    # @see Pundit#authorize
+    # @param [NexusCqrs::BaseMessage] message Message to authorise against
+    def authorize(message, record, query = nil, policy_class: nil)
+      # Populate the query from the command, or the params if it's being overriden
+      query ||= Strings::Case.snakecase(message.demodularised_class_name) + '?'
+
+      # Retreive the policy class object from the type of record we are passing in
+      policy_class ||= PolicyFinder.new(record).policy
+
+      # Pull context variables from command
+      user = message.metadata[:current_user]
+      global_permissions = message.metadata[:global_permissions]
+
+      # Instantiate new policy class, with context
+      policy = policy_class.new(UserContext.new(user, global_permissions), record)
+      raise NotAuthorizedError, query: query, record: record, policy: policy unless policy.public_send(query)
+
+      record.is_a?(Array) ? record.last : record
+    end
+
+    # Helper method for creating a permissions provider object from a query object. This allows certain permissions
+    # to be checked inside the command handler, as opposed to inside the policy
+    #
+    # @param [NexusCqrs::BaseMessage] message Create the PermissionProvider using the message metadata
+    # @return [PermissionProvider] A new instance of the permission provider
+    def permission_provider(message)
+      PermissionProvider.new(message.metadata[:current_user], message.metadata[:global_permissions])
+    end
+
+    def pundit_user
+      nil
+    end
+
+    def current_user
+      return super if defined?(super)
+
+      nil
+    end
+  end
+end

data/lib/nexus_cqrs/auth/ownable.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+module NexusCqrs
+  module Auth
+    # Concern used to integrate models to the permissions system. Including this module to a model will assume the
+    # model can be "owned" by a user. When the model is created, permissions will automatically be assigned to the user
+    # and permissions can be validated and "repaired" retroactively.
+    module Ownable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :granted_permissions, default: {}
+
+        # Default relationship to <class>_permissions
+        class_attribute :permissions_relation, default: top_ancestor_class.name.downcase + "_permissions"
+        class_attribute :owner_column, default: :user_id
+
+        before_create :assign_permissions
+
+        define_model_callbacks :create_permissions
+      end
+
+      module ClassMethods
+        # Gets the class that this module is included in
+        def top_ancestor_class
+          ancestors.first
+        end
+      end
+
+      def assign_permissions
+        # As we are doing this on before_create, we must "build" this association, as opposed to creating it. This
+        # ensures validation is passed before saving this parent Collection.
+        granted_permissions.each do |p|
+          unless permissions.where(permission: p, entity_id: id, user_id: owner_id).exists?
+            permissions.build(user_id: owner_id, permission: p)
+          end
+        end
+      end
+
+      def owner_id
+        send(owner_column)
+      end
+
+      def permissions
+        if respond_to?(permissions_relation)
+          return send(permissions_relation)
+        end
+
+        raise OwnableRelationshipNotSet, "Permissions relation not set.
+  Set it on your model with `self.permissions_relation = :xxx_permissions`, and ensure relationship has been created"
+      end
+    end
+
+    class OwnableRelationshipNotSet < StandardError
+    end
+  end
+end

data/lib/nexus_cqrs/auth/permission_provider.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+module NexusCqrs
+  module Auth
+    class PermissionProvider
+      def initialize(user_id, global_permissions)
+        @user_id = user_id
+        @global_permissions = parse_permissions_array(global_permissions)
+      end
+
+      # Returns true if the current user has the requested permission on the requested entity (if passed), or globally
+      #
+      # @param [String] permission_key Permission key to check against
+      # @param [ApplicationRecord] permission_model Permission model
+      # @param [Integer] entity_id ID of the entity
+      # @return [Boolean] Returns true if the current user has this permission on this entity
+      # @example Check for permission
+      #   permissions.has_permission?('collection:publish', CollectionPermissions, collection.id) #=> true
+      def has_permission?(permission_key, permission_model = nil, entity_id = nil)
+        return false if @user_id.nil?
+
+        return true if @global_permissions.include?(permission_key)
+
+        # check entity-specific permissions
+        unless permission_model.nil?
+          return true if permission_model.where(permission: permission_key, entity_id: entity_id,
+  user_id: @user_id.id).exists?
+        end
+
+        false
+      end
+
+      # Retrieves a list of permissions assigned to a user for a specific entity
+      #
+      # @param [ApplicationRecord] permission_model Permission model
+      # @param [Integer] entity_id ID of the entity
+      # @return [Array] Returns an array of hashes representing permission keys, along with their global status
+      # @example Get a list of permissions
+      #   permissions.for_user(CollectionPermissions, collection.id) #=>
+      #     [
+      #       {:global=>false, :key=>"collection:discard"},
+      #       {:global=>false, :key=>"collection:publish"},
+      #       {:global=>false, :key=>"collection:view_under_moderation"},
+      #       {:global=>false, :key=>"collection:set_status"}
+      #     ]
+      def for_user_on_entity(permission_model, entity_id)
+        return [] if @user_id.nil?
+
+        # retrieve entity-specific permissions from DB and map to hash
+        entity_permissions = permission_model.where(user_id: @user_id, entity_id: entity_id)
+          .map { |p| { global: false, key: p.permission } }
+
+        # Map global permissions to hash
+        global_permissions = @global_permissions.map { |p| { global: true, key: p } }
+
+        # Combine hashes and ensure global permissions take priority
+        (global_permissions + entity_permissions).uniq { |p| p[:key] }
+      end
+
+      private
+
+      def parse_permissions_array(permissions_array)
+        return [] if permissions_array.nil?
+
+        permissions = []
+
+        permissions_array.each do |entity, action_array|
+          action_array.each do |action|
+            permissions << entity + ":" + action
+          end
+        end
+
+        permissions
+      end
+    end
+  end
+end

data/lib/nexus_cqrs/auth/user_context.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+module NexusCqrs
+  module Auth
+    # Class used to provide additional context into pundit. This enables us to not only pass the user model, but also
+    # the global permissions for that user - as those are pulled from the user's request, not the model.
+    class UserContext
+      attr_reader :user, :global_permissions
+
+      def initialize(user, global_permissions)
+        @user = user
+        @global_permissions = global_permissions
+      end
+    end
+  end
+end

data/lib/nexus_cqrs/base_command.rb

@@ -1,4 +1,8 @@
+# frozen_string_literal: true
 module NexusCqrs
+  # Base class for all commands. Should declare value types for passing to handlers
+  #
+  # @since 0.1.0
   class BaseCommand < BaseMessage
   end
 end

data/lib/nexus_cqrs/base_command_handler.rb

@@ -1,5 +1,14 @@
+# frozen_string_literal: true
 module NexusCqrs
+  # Base class for all command handlers. Should always declare a `call` method for invoking the handler.
+  #
+  # @since 0.1.0
   class BaseCommandHandler
+    include NexusCqrs::Auth
+
+    # Method for invoking this handler - all command logic should be contained in this method.
+    #
+    # @param [NexusCqrs::BaseCommand] command Command to be executed by this handler
     def call(command)
     end
   end

data/lib/nexus_cqrs/base_message.rb

@@ -1,26 +1,52 @@
+# frozen_string_literal: true
 module NexusCqrs
+  # All messages passed through the message bus will extend this class. Commands and Queries are both extended types of
+  # `BaseMessage`. This is mainly used to store metadata for Commands/Queries (such as the user context), as well
+  # as helper methods for retrieving the policy method for this Command/Query/Message
+  #
+  # @since 0.1.0
   class BaseMessage
+    # Sets metadata on this message.
+    #
+    # @param [Symbol] key Metadata key
+    # @param [Object] value Metadata value
+    # @example Set the current user on a command/query
+    #   command.set_metadata(:current_user, user)
+    # @since 0.1.0
     def set_metadata(key, value)
       @metadata = {} unless @metadata
       @metadata[key.to_sym] = value
     end
 
+    # Getter for retrieving the metadata on this message
+    #
+    # @return [Hash] Any metadata attached to this message
+    # @since 0.1.0
     def metadata
       @metadata || {}
     end
 
-    def to_h
-      hash = instance_variables.each_with_object({}) do |var, acc|
-        acc[var.to_s[1..-1].to_sym] = instance_variable_get(var)
-      end
-      hash[:metadata] = @metadata || {}
-      hash
-    end
-
+    # Helper method for retrieving the name of the class used to define the auth policy for this message
+    #
+    # @example Get the policy_class on a `Commands::Mods::DeleteMod` command
+    #   command.policy_class #=> "DeleteModPolicy"
+    #
+    # @return [String] Name of the policy class
+    # @deprecated This used to be used to authorise policies before they hit the command bus - requiring a new policy
+    #   for every message. E.g. `DeleteModPolicy`, `UpdateModPolicy`, `CreateModPolicy` etc. It is now recommended to
+    #   simple call `authorise` within the handler as it is far more flexible
+    # @since 0.1.0
     def policy_class
       demodularised_class_name + 'Policy'
     end
 
+    # Helper method for retrieving the demodularised name of the class used to define the auth policy for this message
+    #
+    # @example Get the demodularised_class_name on a `Commands::Mods::DeleteMod` command
+    #   command.policy_class #=> "DeleteMod"
+    #
+    # @return [String] Name of the policy class
+    # @since 0.1.0
     def demodularised_class_name
       self.class.name.split('::').last
     end

data/lib/nexus_cqrs/base_middleware.rb

@@ -1,10 +1,17 @@
+# frozen_string_literal: true
 module NexusCqrs
+  # Base middleware class to allow custom middleware to be injected into the command bus
+  #
+  # @abstract
+  # @since 0.1.0
   class BaseMiddleware
     def initialize(next_)
       @next = next_
     end
 
-    # @param [BaseMessage] message
+    # Invoke middleware
+    #
+    # @param [BaseMessage] message Message object being passed to the bus
     def call(message)
     end
   end

data/lib/nexus_cqrs/base_query.rb

@@ -1,4 +1,8 @@
+# frozen_string_literal: true
 module NexusCqrs
+  # Base class for all queries. Should declare value types for passing to handlers
+  #
+  # @since 0.1.0
   class BaseQuery < BaseMessage
   end
 end

data/lib/nexus_cqrs/base_query_handler.rb

@@ -1,5 +1,14 @@
+# frozen_string_literal: true
 module NexusCqrs
+  # Base class for all query handlers. Should always declare a `call` method for invoking the handler.
+  #
+  # @since 0.1.0
   class BaseQueryHandler
+    include NexusCqrs::Auth
+
+    # Method for invoking this handler - all query logic should be contained in this method.
+    #
+    # @param [NexusCqrs::BaseQuery] query Query to be executed by this handler
     def call(query)
     end
   end

data/lib/nexus_cqrs/command_bus.rb

@@ -1,7 +1,13 @@
+# frozen_string_literal: true
 require 'thread_safe'
 require 'middleware'
 
 module NexusCqrs
+  # The command bus is responsible for registering and invoking the handlers. It stores a simple list of all registered
+  # commands, along with their handlers. When a message is passed to `call`, the middleware is triggered for the message
+  # then the handler is invoked.
+  #
+  # @since 0.1.0
   class CommandBus
     UnregisteredHandler = Class.new(StandardError)
     MultipleHandlers    = Class.new(StandardError)
@@ -11,23 +17,44 @@ module NexusCqrs
       @middleware = middleware || Middleware::Builder.new
     end
 
-    def register(klass, handler)
-      raise MultipleHandlers, "Multiple handlers not allowed for #{klass}" if handlers[klass]
+    # Registers a handler for a command.
+    #
+    # @param [NexusCqrs::BaseMessage] message Message to register a handler for
+    # @param [NexusCqrs::BaseCommandHandler] handler CommandHandler/QueryHandler to be invoked for this message
+    # @raise [MultipleHandlers] If the message already has a handler registered, an error will be raised
+    #
+    # @since 0.1.0
+    def register(message, handler)
+      raise MultipleHandlers, "Multiple handlers not allowed for #{message}" if handlers[message]
 
-      handlers[klass] = handler
+      handlers[message] = handler
     end
 
-    def call(command)
+    # Invokes a handler from a message
+    #
+    # @param [NexusCqrs::BaseMessage] message Message used to determine which handler to invoke
+    #
+    # @since 0.1.0
+    def call(message)
       runner = Middleware::Builder.new
       runner.use(@middleware)
-      runner.use(->(command_) { handler_for_command(command_).call(command_) })
-      runner.call(command)
+      runner.use(->(message_) { handler_for_command(message_).call(message_) })
+      runner.call(message)
     end
 
+    # Return a list of registered handlers
+    #
+    # @return [ThreadSafe::Cache] ThreadSafe::Cache object containing a list of all the registered handlers
+    #
+    # @since 0.1.0
     def registered_handlers
       handlers
     end
 
+    # Removes all registered handlers from the bus. This can be useful in tests - as we don't want state to persist
+    # across handlers
+    #
+    # @since 0.1.0
     def clear_handlers
       @handlers = ThreadSafe::Cache.new
     end
@@ -36,6 +63,9 @@ module NexusCqrs
 
     private
 
+    # Looks up the handler for a specific command
+    #
+    # @since 0.1.0
     def handler_for_command(command)
       unregistered_handler = proc { raise UnregisteredHandler, "Missing handler for #{command.class}" }
       handlers.fetch(command.class, &unregistered_handler)

data/lib/nexus_cqrs/command_executor.rb

@@ -1,20 +1,78 @@
+# frozen_string_literal: true
+
 module NexusCqrs
   class CommandExecutor
     # @param [NexusCqrs::CommandBus] command_bus
     def initialize(command_bus)
       @bus = command_bus
+      @logger = logger
+    end
+
+    # Get logger instance depending on runtime environment.
+    def logger
+      defined?(Rails) && defined?(Rails.logger) ? Rails.logger : Logger.new(STDOUT)
+    end
+
+    def autoregister(base_class, dir = 'app/domain/commands', ignore_strings = ['.rb', 'app/domain/'])
+      if defined?(Rails)
+        # Iterate over the directory passed and find all ruby files.
+        Dir["#{dir}/**/*.rb"].each do |file|
+          # Constantize class name to constant to force rails to autoload this class.
+          # Note that autoloading won't work when testing this gem standalone, but this does trigger the necessary
+          # loading when in a rails environment.
+          ignore_strings.each do |i|
+            file.slice!(i)
+          end
+          @logger.debug { "Attempting constantize of #{file}" }
+          file.camelize.constantize
+        rescue NameError => e
+          @logger.warn { "Failed autoregister #{file.camelize}, received NameError: #{e}" }
+        end
+      end
+
+      ObjectSpace.each_object(Class).select { |klass| klass < base_class }.each do |c|
+        @logger.debug { "Attempting auto registration of #{c}" }
+        handler_name = (c.to_s + "Handler")
+        begin
+          handler = handler_name.constantize.new
+        rescue NameError
+          @logger.warn { "Command `#{c}` tried to autoregister `#{handler_name}` but the class was not found" }
+          next
+        end
+
+        if handler.respond_to?(:call)
+          register_command(c, handler)
+        else
+          @logger.warn { "Command `#{c}` tried to autoregister `#{handler_name}` but `call` method did not exist" }
+        end
+      end
+    end
+
+    # Returns the bus used by this executor
+    #
+    # @return [NexusCqrs::CommandBus] command_bus
+    def command_bus
+      @bus
     end
 
-    # @param [NexusCqrs::BaseCommand] command
-    def execute(command)
-      @bus.call(command)
+    # Executes a specific handler on the bus, passing in the provided message (Query/Command)
+    #
+    # @param [NexusCqrs::BaseMessage] message
+    def execute(message)
+      @bus.call(message)
     end
 
+    # Helper method for registering a handler on the bus
+    #
+    # @see CommandBus#register
+    # @param [NexusCqrs::BaseMessage] message
     # @param [NexusCqrs::BaseCommandHandler] handler
-    def register_command(klass, handler)
-      @bus.register(klass, handler)
+    def register_command(message, handler)
+      @bus.register(message, handler)
     end
 
+    # Clears all handlers from the bus and invokes the block passed to `configure_handlers` to re-register all the
+    # handlers again. This can be useful in tests - as we don't want state to persist across handlers
     def reregister_handlers
       return if @register_handlers.nil?
 
@@ -22,6 +80,18 @@ module NexusCqrs
       @register_handlers.call(self)
     end
 
+    # Configuration method for allowing handlers to be registered in bulk
+    #
+    # @see CommandBus#register
+    # @param [Proc] block Block to execute to register handlers
+    # @example Registering all queries
+    #   executor.configure_handlers do |executor|
+    #     executor.autoregister(NexusCqrs::BaseQuery, 'app/domain/queries')
+    #   end
+    # @example Registering a query manually
+    #   executor.configure_handlers do |executor|
+    #     executor.register_command(NexusCqrs::BaseQuery, NexusCqrs::BaseQueryHandler)
+    #   end
     def configure_handlers(&block)
       @register_handlers = block
       @register_handlers.call(self)

data/lib/nexus_cqrs/helpers.rb

@@ -1,20 +1,36 @@
+# frozen_string_literal: true
 module NexusCqrs
+  # Simple module to inject execution methods into a class. Used to execute commands and queries from controllers and/or
+  # graphql resolvers.
   module Helpers
     # Executes a CQRS Command
+    #
+    # @param [NexusCqrs::BaseCommand] command Command to execute
+    # @example Execute a command
+    #     execute(DeleteMod.new(mod.id))
     def execute(command)
       command_executor.execute(command)
     end
 
     # Executes a CQRS Query
+    #
+    # @param [NexusCqrs::BaseQuery] query Query to execute
+    # @example Execute a query
+    #     execute(GetMod.new(mod.id))
     def query(query)
       query_executor.execute(query)
     end
 
-    # Provide access to the CQRS executor
+    # Provide access to the CQRS command executor
+    #
+    # @return [NexusCqrs::CommandExecutor] Returns the executor used for commands
     def command_executor
       @command_executor ||= $COMMAND_EXECUTOR
     end
 
+    # Provide access to the CQRS query executor
+    #
+    # @return [NexusCqrs::CommandExecutor] Returns the executor used for queries
     def query_executor
       @query_executor ||= $QUERY_EXECUTOR
     end

data/lib/nexus_cqrs/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
 module NexusCqrs
-  VERSION = '0.2.2'
+  # Leave this as 0.4.2 in order for CI process to replace with the tagged version.
+  VERSION = '0.4.2'
 end

data/lib/nexus_cqrs.rb

@@ -1,5 +1,10 @@
+# frozen_string_literal: true
 require 'nexus_cqrs/base_message'
 require 'nexus_cqrs/base_middleware'
+require 'nexus_cqrs/auth/auth'
+require 'nexus_cqrs/auth/user_context'
+require 'nexus_cqrs/auth/permission_provider'
+require 'nexus_cqrs/auth/ownable'
 require 'nexus_cqrs/base_command'
 require 'nexus_cqrs/base_command_handler'
 require 'nexus_cqrs/base_query'

data/nexus_cqrs.gemspec

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require_relative 'lib/nexus_cqrs/version'
 
 Gem::Specification.new do |spec|
@@ -20,4 +21,6 @@ Gem::Specification.new do |spec|
   spec.add_dependency('generator_spec')
   spec.add_dependency('thread_safe')
   spec.add_dependency('ibsciss-middleware')
+  spec.add_dependency('pundit')
+  spec.add_dependency('strings-case')
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nexus_cqrs
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.4.2
 platform: ruby
 authors:
 - Dean Lovett
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-08-25 00:00:00.000000000 Z
+date: 2021-11-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: generator_spec
@@ -52,6 +52,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: pundit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: strings-case
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - dean.lovett@nexusmods.com
@@ -79,6 +107,10 @@ files:
 - lib/generators/nexus_cqrs/templates/query_handler.rb
 - lib/generators/nexus_cqrs/templates/register_cqrs_handlers.rb
 - lib/nexus_cqrs.rb
+- lib/nexus_cqrs/auth/auth.rb
+- lib/nexus_cqrs/auth/ownable.rb
+- lib/nexus_cqrs/auth/permission_provider.rb
+- lib/nexus_cqrs/auth/user_context.rb
 - lib/nexus_cqrs/base_command.rb
 - lib/nexus_cqrs/base_command_handler.rb
 - lib/nexus_cqrs/base_message.rb
@@ -108,7 +140,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.26
+rubygems_version: 3.2.31
 signing_key: 
 specification_version: 4
 summary: Core package for the nexus cqrs gem