README.md in pragma-policy-2.0.0 vs README.md in pragma-policy-2.1.0
- old
+ new
@@ -1,16 +1,13 @@
# Pragma::Policy
-[](https://travis-ci.org/pragmarb/pragma-policy)
-[](https://gemnasium.com/github.com/pragmarb/pragma-policy)
-[](https://codeclimate.com/github/pragmarb/pragma-policy)
-[](https://coveralls.io/github/pragmarb/pragma-policy)
+[](https://travis-ci.org/pragmarb/pragma-policy)
+[](https://coveralls.io/github/pragmarb/pragma-policy?branch=master)
+[](https://codeclimate.com/github/pragmarb/pragma-policy/maintainability)
Policies provide fine-grained access control for your API resources.
-They are built on top of the [Pundit](https://github.com/elabs/pundit) gem.
-
## Installation
Add this line to your application's Gemfile:
```ruby
@@ -76,19 +73,19 @@
end
```
You are ready to use your policy!
-### Retrieving Records
+### Retrieving records
To retrieve all the records accessible by a user, use the `.accessible_by` class method:
```ruby
posts = API::V1::Article::Policy::Scope.new(user, Article.all).resolve
```
-### Authorizing Operations
+### Authorizing operations
To authorize an operation, first instantiate the policy, then use the predicate methods:
```ruby
policy = API::V1::Article::Policy.new(user, post)
@@ -99,9 +96,91 @@
syntax. `Pragma::Policy::NotAuthorizedError` is raised if the predicate method returns `false`:
```ruby
policy = API::V1::Article::Policy.new(user, post)
policy.update! # raises if the user cannot update the post
+```
+
+### Reusing Pundit policies
+
+If you already use [Pundit](https://github.com/varvet/pundit), there's no need to copy-paste
+policies for your API. You can use `Pragma::Policy::Pundit` to delegate to your existing policies
+and scopes:
+
+```ruby
+module API
+ module V1
+ module Article
+ class Policy < Pragma::Pundit::Policy
+ # This is optional: the inferred default would be ArticlePolicy.
+ self.pundit_klass = CustomArticlePolicy
+ end
+ end
+ end
+end
+```
+
+Note that you can still override specific methods if you want, and we'll keep delegating the rest
+to Pundit:
+
+```ruby
+module API
+ module V1
+ module Article
+ class Policy < Pragma::Pundit::Policy
+ def create?
+ # Your custom create policy here
+ end
+ end
+ end
+ end
+end
+```
+
+### Passing additional context
+
+If you want to pass additional context to the policy, just pass it instead of the user object.
+Pragma::Policy never uses your context in any way, so you can pass whatever you want:
+
+```ruby
+policy = API::V1::Article::Policy.new(OpenStruct.new(ip: request.remote_ip, user: user), post)
+policy.update!
+```
+
+In your policy, you can use `#context` as an alias for `#user` for convenience:
+
+```ruby
+module API
+ module V1
+ module Article
+ class Policy < Pragma::Pundit::Policy
+ def update?
+ record.author_id == context.user.id || context.ip == '127.0.0.1'
+ end
+ end
+ end
+ end
+end
+```
+
+If you are using [pragma-rails](https://github.com/pragmarb/pragma-rails), you may change the
+context passed to the policy by defining a `#policy_context` method on your controller. This way you
+are not forced to override `#current_user` or `#pragma_user`:
+
+```ruby
+module API
+ module V1
+ class PostsController < ApplicationController
+ # ...
+
+ private
+
+ def policy_context
+ OpenStruct.new(ip: request.remote_ip, user: current_user)
+ end
+ end
+ end
+end
```
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/pragmarb/pragma-policy.