nexus_cqrs_auth 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12f88e69474120c6c77e39eb87c83087352ab327bbf3ccb31a25ea7a71ddd5af
-  data.tar.gz: 9a87ded659ce541ebd65d0089a01d739fa562c2ab3ff7836d555e62a4db6e90e
+  metadata.gz: d3d598f2e967a8b70e16c7eb5da21b63725fc986f04a83d1b5ea96f271117cad
+  data.tar.gz: edb9a9febb1aa1b97648ce83a471c81f05b90686dc735273a7a9d4f45cda30e0
 SHA512:
-  metadata.gz: c932a6ecd9cb000b4f1d70a3fff680a6abcbe4c86af7b1277faf04e3d44f50d453dbeacff310654055a026eecee01b2d0a68feef6225149258d00dd92f394404
-  data.tar.gz: 86134c0025b0134282495d4ea9823e3fb3b28914e35b5937d93ff1a5ab63a4a23f1a677bae3bdb9d4ddac4485066267f868478c94164a2870dab663cb17b7c9f
+  metadata.gz: 1be25f5a7a0f63f7a989df0332930ce51c340a5712d9288f5e60713e9c787bb7ed03c2903bb0b182528411dc97031ea5778705c84f88e580b07d9774f8ee1e8d
+  data.tar.gz: 1a4a782f0ffe7cc70c94fa57152f8277594d4e4b25abf372008773d37eb777ed25a0ecd17b74c627e2e9bac3f99ef81cc1efd7f24c50998a0991708c14fc674e

data/README.md

@@ -1 +1,145 @@
-nexus_cqrs_auth
+# nexus_cqrs_auth
+
+Authorisation for the Nexus CQRS pattern.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'nexus_cqrs_auth'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install nexus_cqrs_auth
+
+## Usage
+
+When setting up the message bus, attach the authorisation middleware to it:
+
+```ruby
+middleware_stack = Middleware::Builder.new do |b|
+  b.use NexusCqrsAuth::AuthMiddleware
+end
+
+bus = Bus.new(middleware: middleware_stack)
+```
+
+You will also need to set metadata on each message (command/query) before dispatching it to the bus:
+
+```ruby
+command.set_metadata(:current_user, user)
+execute(command)
+```
+
+How you set this data, and where you get the current user from is application specific.
+
+For example, a helper included in all GraphQL types could look like this:
+
+```ruby
+module GraphQlCqrsHelpers
+  def execute(command)
+    command_executor.execute(enrich_message(command))
+  end
+
+  def query(query)
+    query_executor.execute(enrich_message(query))
+  end
+
+  def command_executor
+    @command_executor ||= $COMMAND_EXECUTOR
+  end
+
+  def query_executor
+    @query_executor ||= $QUERY_EXECUTOR
+  end
+
+  private
+
+  def enrich_message(message)
+    message.set_metadata(:current_user, @context[:current_user])
+    message
+  end
+end
+```
+
+You can then write various policies to setup authorisation in CQRS flows.
+
+### Bus level policy
+
+Create a policy class in `app/policies/my_message_policy.rb`
+
+```ruby
+class MyMessagePolicy < ApplicationPolicy
+  def initialize(user, message)
+    @user = user
+    @query = message
+  end
+  
+  def authorise?
+    true
+  end
+end
+```
+
+The `authorise?` method will be called before the message handler. If `authorise?` returns false, execution of the bus
+will halt and a `Pundit::NotAuthorizedError` will be raised.
+
+### Record level policy
+
+You can write policies for records:
+
+```ruby
+class PostPolicy < ApplicationPolicy
+  def initialize(user, post)
+    @user = user
+    @post = post
+  end
+  
+  def publish_post?
+    true
+  end
+end
+```
+
+You can then authorise a particular `Post`s by calling the policy from a command handler:
+
+```ruby
+class PublishPostHandler < NexusCqrs::BaseCommandHandler
+  include NexusCqrsAuth
+
+  # @param [Commands::PublishPost] command
+  def call(command)
+    post = Post.find(command.post_id)
+    authorize(command, post)
+    post.is_published = true
+    post.save
+  end
+end
+```
+
+The `NexusCqrsAuth` module must be included in the handler.
+
+`authorize` should be called with the domain message (e.g. command) and the record. The policy for that record type
+(e.g. `PostPolicy`) will be called and the scope with the same name as the command (`PublishPost` -> `publish_post?`)
+will be called.
+
+If the scope returns false, then a `Pundit::NotAuthorizedError` will be raised.
+
+## Development
+
+To contribute to this gem, simple clone the repository, run `bundle install` and run tests:
+
+```shell script
+    bundle exec rspec
+    bundle exec rubocop
+```
+
+## Releasing
+
+The release process is tied to the git tags. Simply creating a new tag and pushing will trigger a new release to rubygems.

data/lib/nexus_cqrs_auth/middleware.rb

@@ -7,7 +7,9 @@ module NexusCqrsAuth
     include NexusCqrsAuth
 
     def call(message)
-      authorize(message, message, :authorise?)
+      if Pundit::PolicyFinder.new(message).policy
+        authorize(message, message, :authorise?)
+      end
       @next.call(message)
     end
   end

data/lib/nexus_cqrs_auth/version.rb

@@ -1,3 +1,3 @@
 module NexusCqrsAuth
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nexus_cqrs_auth
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Chris Harrison