sequel-privacy 0.5.3 → 0.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f2538fcf5aee16c7b624701e81d936df211b20fa007cf9fa1fffc893bda0105
-  data.tar.gz: e1df8a2b58c2e6851447e2874c837a865641be73ed0adc25c255bcb9076d4087
+  metadata.gz: 54198780e9744c541e3915d3ac5722ccb16b119a77729b5013b854e698604511
+  data.tar.gz: 5219bec34c9542ce88f928bc39c1998586e6ed2c15637296dead03d958e12db1
 SHA512:
-  metadata.gz: 68996d09fde85691254e51d6edb40f4a32007c07a232b768a705d29b7b4ea37ebe95a2ac092c18f201a7516b53108d4a8ff8356a0f860c288a18903648b5c1b6
-  data.tar.gz: d1b9364e64145dbe2993c18bb8db458826b2480e9e827f589ed6cecefdbb1e2c82e0c2fdd72a3542946fb4bea70e2d58c37f81889067b3b5e7c5ce7912032477
+  metadata.gz: 8673ccf1e4e6cb592299c9a930ee7ff779e0343e66753a245f71f4aa26d21906c486dc1435d55af53c1c8b09c8166f24fec2e8036ce3f962598df4d8a29cadf9
+  data.tar.gz: 34bc11e989421e4cd7d5207fc531d7bcf17cf681c8b10c3104918c12d5d2a9eb8cdf68274dd64397c8b49ba51b6c59b3de4fd4ef73e8acbf06b1fdd671039cce

data/README.md

@@ -110,13 +110,12 @@ member.phone  # => nil if :view_phone denies
 
 ## Policy Definition
 
-Policies are lambdas that execute in the context of an `Actions` struct, giving access to `allow`, `deny`, and `pass` outcome methods, as well as the `all` combinator. `allow` and `deny` will end evaluation of the chain of policies, whereas `pass` will continue to the next policy in the chain.
+Policies are lambdas that execute in the context of an `Actions` class, giving access to `allow`, `deny`, and `pass` outcome methods, as well as the `all` combinator. `allow` and `deny` will end evaluation of the chain of policies, whereas `pass` will continue to the next policy in the chain.
 
-Policies are **actor-first**. Arities map to:
 - 0 args — global decision (`-> { allow if Time.now.sunday? }`)
-- 1 arg  — `(actor)`: role / identity checks
-- 2 args — `(actor, subject)`: ownership, membership
-- 3 args — `(actor, subject, direct_object)`: "can actor do X to subject with direct_object?"
+- 1 arg  — `(actor)`: Useful for role / identity checks
+- 2 args — `(actor, subject)`: General purpose relationship checks
+- 3 args — `(actor, subject, direct_object)`: "Allow members to remove themselves from a group they're in"
 
 Policies of arity ≥ 1 auto-deny for anonymous viewers (nil actor). Use `allow_anonymous: true` to opt out — meant for state-gate policies that examine only the subject.
 
@@ -175,7 +174,7 @@ policy :MyPolicy, ->() { ... },
 
 **`cacheable: true`** (default): Results are cached for the duration of the request, keyed by policy + arguments. Use for policies that don't depend on mutable state.
 
-**`single_match: true`**: Optimization for policies for which there is only one matching Actor possible for a given Subject. For example in `AllowAuthors`, since a `Post` can have only one other, it's not worth a potentially expensive check on other combinations once you've found the winner.
+**`single_match: true`**: Optimization for policies for which there is only one matching Actor possible for a given Subject. For example in `AllowAuthors`, since a `Post` can have only one author, it's not worth a potentially expensive check on other combinations once you've found the winner.
 
 **`cache_by:`** (Symbol or Array of `:actor`, `:subject`, `:direct_object`): Override the cache-key dimensions. By default the key uses every input the policy receives. Pass a subset when the policy ignores some of its inputs — e.g. `AllowAdmins` takes `(actor, subject)` but only examines actor, so `cache_by: :actor` shares one entry across subjects.
 
@@ -217,9 +216,28 @@ All-Powerful VCs bypass all privacy checks and are used in situations where the
 to models. In a production setting, your application should prohibit raw Database access outside of the privacy-aware
 system, so these VCs give you an escape hatch for things like scripts while also keeping an audit trail. 
 
-`omniscient` and `all_powerful` require a reason (symbol) for audit logging.
+`omniscient` and `all_powerful` require a reason, given as a Symbol, for audit logging.
 You could also create lint rules that prevent the casual creation of these viewer contexts.
 
+```ruby
+# Standard viewer (most common)
+users_groups = Group.for_vc(current_vc).where(creator: current_user).all
+
+# Anonymous viewer (logged-out users)
+logged_out_vc = Sequel::Privacy::ViewerContext.anonymous
+posts = Post.for_vc(logged_out_vc).where(published: true).all
+
+# All-powerful ViewerContexts dangerously bypass all read and write checks.
+admin_vc = Sequel::Privacy::ViewerContext.all_powerful(:admin_migration)
+```
+
+### Login, Sessions & `current_user` and `current_vc`
+
+Unless you allow unsafe access to your User (or equivalent) model, you will need 
+a way to load it and create a ViewerContext for them. An Omniscient ViewerContext 
+is useful for this. Be sure to properly set to an Actor VC after you've logged-in 
+or materialized a user from the session. 
+
 ```ruby
 # You can use an omniscient viewer context to load the user from a session
 # or however you store them. Discard this viewer context when you're done with it.
@@ -235,18 +253,9 @@ def current_user
 end
 
 def current_vc
-  current_user&.vc || Sequel::Privacy::ViewerContext.anonymous()
+  current_user&.viewer_context || Sequel::Privacy::ViewerContext.anonymous()
 end
 
-# Standard viewer (most common)
-users_groups = Group.for_vc(current_vc).where(creator: current_user).all
-
-# Anonymous viewer (logged-out users)
-logged_out_vc = Sequel::Privacy::ViewerContext.anonymous
-posts = Post.for_vc(logged_out_vc).where(published: true).all
-
-# All-powerful ViewerContexts dangerously bypass all read and write checks.
-admin_vc = Sequel::Privacy::ViewerContext.all_powerful(:admin_migration)
 ```
 
 ## Mutation Enforcement
@@ -378,11 +387,10 @@ class PrivacyCacheMiddleware
 end
 ```
 
-Or manually:
+Or somewhere manually, like at the top of your Roda or Sinatra app:
 
 ```ruby
-Sequel::Privacy.cache.clear
-Sequel::Privacy.single_matches.clear
+Sequel::Privacy.clear_cache!
 ```
 
 ## Actor Interface

data/lib/sequel/privacy/version.rb

@@ -3,6 +3,6 @@
 
 module Sequel
   module Privacy
-    VERSION = '0.5.3'
+    VERSION = '0.5.4'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sequel-privacy
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.5.4
 platform: ruby
 authors:
 - Austin Bales