nexus_cqrs 0.3.0 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4e6e4a145007fe8658503e9745e3be716436749d9bea2c714bca1d47b1ea4ab
-  data.tar.gz: aedbcb7c36185faf7d546e3ea5c268cba6642d0880a0a2c2cdf612e761f5096c
+  metadata.gz: 2ad110fb96498636aa174c3d45aa7783177fb7e5a2475e828f6e694adf392b46
+  data.tar.gz: 35fd22cd65fd520c91c93629b365f4573fbc0787158212b12dd3fb1241e0da43
 SHA512:
-  metadata.gz: 83c240bd9f056d0d82e5437f52c45527be6092e83f6356c765bfa127153d8d5c5c660437598707fb470879606ede7c9fc1a28f11e42355401b177c29b37e7c45
-  data.tar.gz: 0dab29f1d52e3f4110cfb948ffbe425c342f682c01f1945ceced2385aa022201e84c7025b1cc7eb633110029efdf4e7b5e0366baf2b7466183a164a040df5ff3
+  metadata.gz: faee92b66ddcd2cdcd70fb315f444c2f226ff194ff528eb5c4e3f0a654c5e274e7715df987883b7a0512cbf0245a84824dd24829aa879277424c675435ea5169
+  data.tar.gz: 172b58d34c2da223e41e933fd0df3b379450d0d9ec0ce89095e6581ff894006224614cb62455d7d5223a376988413f3e6d7a98e28d1d502ad58b349c3a075fa8

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
@@ -10,3 +11,4 @@ gem 'rspec'
 gem "generator_spec"
 gem 'thread_safe'
 gem 'ibsciss-middleware'
+gem 'request_store'

data/Gemfile.lock

@@ -1,107 +1,117 @@
 PATH
   remote: .
   specs:
-    nexus_cqrs (0.3.0)
+    nexus_cqrs (0.1.0)
       generator_spec
       ibsciss-middleware
+      pundit
+      request_store
+      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)
+    request_store (1.5.0)
+      rack (>= 1.4)
+    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
@@ -110,6 +120,7 @@ DEPENDENCIES
   generator_spec
   ibsciss-middleware
   nexus_cqrs!
+  request_store
   rspec
   rubocop
   rubocop-shopify (~> 1.0.4)

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/templates/register_cqrs_handlers.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 Rails.configuration.to_prepare do
-
   middleware_stack = Middleware::Builder.new do |b|
-    b.use(NexusCqrsAuth::AuthMiddleware)
   end
 
   command_bus = NexusCqrs::CommandBus.new(middleware: middleware_stack)

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,121 @@
+# 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?
+
+          # get all permissions for this entity. NOTE: This will be cached per-request.
+          permissions = cached_permissions(permission_model)
+
+          # if there are no permissions for this entity and user, return false
+          return false if permissions[entity_id].nil?
+
+          # if the permission key is in the user's permissions for this entity, return true
+          return true if permissions[entity_id].include?(permission_key)
+        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_on_entity(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
+
+      # Retrieves a list of permissions assigned to a user for ANY entity ID
+      #
+      # @param [ApplicationRecord] permission_model Permission model
+      # @return [Hash] Returns a hash representing each entity and the user's permissions
+      # @example Get a list of permissions
+      #   permissions.for_user(CollectionPermissions) #=>
+      #     {
+      #       1 => ["collection:discard"],
+      #       2 => ["collection:discard"],
+      #       3 => ["collection:discard", "collection:edit"],
+      #       4 => ["collection:discard"],
+      #     }
+      def for_user(permission_model)
+        return {} if @user_id.nil?
+
+        permissions = {}
+
+        # retrieve entity-specific permissions from DB and map to hash
+        permission_model.where(user_id: @user_id).each do |p|
+          if permissions[p.entity_id].nil?
+            permissions[p.entity_id] = [p.permission]
+          else
+            permissions[p.entity_id] << p.permission
+          end
+        end
+
+        permissions
+      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
+
+      # Retrieve all the permissions for this user for a specific model and cache it for this request (as all calls to
+      # a PermissionProvider in the same request will all have the same permissions, this saves on many SQL calls)
+      #
+      # @param [ApplicationRecord] permission_model Permission model
+      # @see PermissionProvider#for_user
+      def cached_permissions(permission_model)
+        ::RequestStore.store[:permissions] ||= for_user(permission_model)
+      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,5 +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,6 +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,27 +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,11 +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,5 +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,6 +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

@@ -3,6 +3,11 @@ 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)
@@ -12,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
@@ -37,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,39 +1,49 @@
 # frozen_string_literal: true
+
 module NexusCqrs
   class CommandExecutor
     # @param [NexusCqrs::CommandBus] command_bus
     def initialize(command_bus)
       @bus = command_bus
+      @logger = logger
     end
 
-    def autoregister(base_class, dir = 'app/domain/commands', ignore_strings = ['.rb', 'app/domain/'])
+    # Get logger instance depending on runtime environment.
+    def logger
+      defined?(Rails) && defined?(Rails.logger) ? Rails.logger : Logger.new(STDOUT)
+    end
 
-      # Iterate over the director passed and find all ruby files, removing unwanted parts of the string.
-      Dir["#{dir}/*.rb"].each do |file|
-        ignore_strings.each { |i|
-          file.slice!(i)
-        }
-        begin
-          # Constantize class name to constant to force rails to autoload this class
+    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
-          puts "WARN: Tried to autoregister #{file.camelize} but class could not be found"
+          @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 => e
-          Rails.logger.error "WARN: A command/query called `#{c}` tried to autoregister `#{handler_name}` but the class was not found"
+        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
-          Rails.logger.error "WARN: A command/query called `#{c}` tried to autoregister `#{handler_name}` but the class did not have a `call` method"
+          @logger.warn { "Command `#{c}` tried to autoregister `#{handler_name}` but `call` method did not exist" }
         end
       end
     end
@@ -45,16 +55,24 @@ module NexusCqrs
       @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?
 
@@ -62,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,21 +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,4 +1,5 @@
 # frozen_string_literal: true
 module NexusCqrs
-  VERSION = '0.3.0'
+  # Leave this as 0.4.3 in order for CI process to replace with the tagged version.
+  VERSION = '0.4.3'
 end

data/lib/nexus_cqrs.rb

@@ -1,6 +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,7 @@ 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')
+  spec.add_dependency('request_store')
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nexus_cqrs
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.3
 platform: ruby
 authors:
 - Dean Lovett
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-11-11 00:00:00.000000000 Z
+date: 2021-11-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: generator_spec
@@ -52,6 +52,48 @@ 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'
+- !ruby/object:Gem::Dependency
+  name: request_store
+  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 +121,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 +154,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.31
+rubygems_version: 3.2.32
 signing_key: 
 specification_version: 4
 summary: Core package for the nexus cqrs gem