sequel-privacy 0.6.1 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 627da75fe2db0e41382bd4b6a6e44cf85bb01a3a52aef9c1c16df85b0b4af5d8
-  data.tar.gz: e0cfd6b79e35d81a51d6897fa37f9130e5fb567f3422c0014500be6bb0d95183
+  metadata.gz: e06f6f240ee6789aee3cd1881290df4cdc503d0be754c94e9b2bdd516607bf22
+  data.tar.gz: a280c975257f069cf01db2ef9189a10e2ed2fb5af279bdb365da211485e47c71
 SHA512:
-  metadata.gz: c1450ee72abf6ef060a7d2f8d541f3d418724cca9650370746e996427d4da438e93fa96410b47b6606ab4a41542d014b46dbf97a08e3e4623cf120b419736372
-  data.tar.gz: 5ccadc4dfb1b84fb7ab9d3beefb2b396b2b1302239c0b63fc97a2c34a6fb9b5a025857542814167e007326a17e08e1697d56731cdff690a5c9d72d850cb96529
+  metadata.gz: d70745ff2e176a8d6e4ba3ad5f1c8ade864b44647392085ba86df00f5f3bdd78ca306d79776731a97c4c9aa769b5fd9009260b3f9b470c88b2ec985fde21aa46
+  data.tar.gz: d6f85561a19cc324e3ea99e0d0cfaef30ecb405dc6eecedeb349adb55c18596de0d8384624431a1857bbe8dda11866043093be22d4cbd34e7b8bf220b28ba3a9

data/CHANGELOG.md

@@ -1,13 +1,17 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-## [0.1.0] - 2024-01-24
+- Added `Sequel::Privacy.with_cache_scope` for nested, exception-safe policy
+  caches isolated between concurrent threads and fibers.
+
+## [0.7.0] – 2026-08-26
+- Removed `#for_vc` on `Sequel::Model` instances. Instead, call `#reset_viewer_context(vc, reason)`.
+- Removed `#viewer_context=` from `Sequel::Model` instances.
+- Added `#use(&block)` to Omniscient and AllPowerful viewer contexts. The block receives the viewer context and the reason it was created.
+
+## [0.1.0]
 
 ### Added
 - Initial release

data/README.md

@@ -260,31 +260,35 @@ 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. 
+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.
 
 ```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.
-def current_user 
+def current_user
   return @current_user if @current_user
-  login_vc = Sequel::Privacy::ViewerContext.omniscient(:login)
-  user = User.for_vc(login_vc)[session_user_id]
-  return nil unless user
 
-  # Attach an ActorVC to the loaded user so that future calls to its fields and 
-  # associations respect privacy .
-  @current_user ||= user.for_vc(Sequel::Privacy::ViewerContext.for_actor(user))
+  @current_user = Sequel::Privacy::ViewerContext.omniscient(:login).use do |vc, reason|
+    user = User.for_vc(vc)[session_user_id]
+    next nil unless user
+
+    # Give the row its own ActorVC, so its fields and associations respect
+    # privacy from here on — and so it can be written to. An OmniscientVC reads
+    # anything but refuses to mutate.
+    user.reset_viewer_context(Sequel::Privacy::ViewerContext.for_actor(user), reason)
+  end
 end
 
 def current_vc
   current_user&.viewer_context || Sequel::Privacy::ViewerContext.anonymous()
 end
-
 ```
 
+*Warning:* Skipping the reset leaves you holding an object that cannot be
+saved, but any association or field reads on it will be allowed. So you should always
+discard the OmniVC / APVCs used for things like this and call `reset_viewer_context` 
+with a more appropriate one as soon as you can.
+
 ## Mutation Enforcement
 
 When a viewer context is attached, mutations are automatically checked:
@@ -398,7 +402,9 @@ Sequel::Privacy.logger = SemanticLogger['Privacy']
 
 ## Cache Management
 
-Policy results are cached per-request to avoid redundant evaluation. Clear between requests:
+Policy results are cached per operation to avoid redundant evaluation. Wrap
+each request, job, or other independent operation in a cache scope. Scopes are
+isolated between concurrent threads and fibers:
 
 ```ruby
 # In Rack middleware
@@ -408,13 +414,14 @@ class PrivacyCacheMiddleware
   end
 
   def call(env)
-    Sequel::Privacy.clear_cache!
-    @app.call(env)
+    Sequel::Privacy.with_cache_scope { @app.call(env) }
   end
 end
 ```
 
-Or somewhere manually, like at the top of your Roda or Sinatra app:
+Scopes may be nested and are restored after exceptions. `clear_cache!` clears
+only the active scope. Applications not yet using scopes retain the legacy
+process-global cache and can clear it manually:
 
 ```ruby
 Sequel::Privacy.clear_cache!

data/lib/sequel/plugins/privacy.rb

@@ -639,13 +639,12 @@ module Sequel
           @viewer_context = T.let(@viewer_context, T.nilable(Sequel::Privacy::ViewerContext))
         end
 
-        sig { params(vc: T.nilable(Sequel::Privacy::ViewerContext)).returns(T.nilable(Sequel::Privacy::ViewerContext)) }
-        def viewer_context=(vc)
-          @viewer_context = T.let(vc, T.nilable(Sequel::Privacy::ViewerContext))
-        end
 
-        sig { params(vc: Sequel::Privacy::ViewerContext).returns(T.self_type) }
-        def for_vc(vc)
+        sig { params(vc: Sequel::Privacy::ViewerContext, reason: Symbol).returns(T.self_type) }
+        def reset_viewer_context(vc, reason)
+          Sequel::Privacy.logger&.debug do
+            "Resetting viewer context on #{self.class}[#{pk}] to #{vc.class.name.to_s.split('::').last} (#{reason})"
+          end
           @viewer_context = T.let(vc, T.nilable(Sequel::Privacy::ViewerContext))
           self
         end

data/lib/sequel/privacy/cache.rb

@@ -2,28 +2,82 @@
 # frozen_string_literal: true
 
 module Sequel
+  # Privacy enforcement and operation-scoped policy caching.
   module Privacy
-    # In-memory cache for policy evaluation results. Clear between
-    # requests (e.g. via Rack middleware).
+    # One policy cache scope. Kept separate from ViewerContext because a
+    # long-lived context may serve many independent operations.
+    class CacheScope
+      extend T::Sig
+
+      sig { returns(T::Hash[Integer, Symbol]) }
+      attr_reader :cache
+
+      sig { returns(T::Hash[Integer, Integer]) }
+      attr_reader :single_matches
+
+      sig { void }
+      def initialize
+        @cache = T.let({}, T::Hash[Integer, Symbol])
+        @single_matches = T.let({}, T::Hash[Integer, Integer])
+      end
+
+      sig { void }
+      def clear!
+        @cache = {}
+        @single_matches = {}
+      end
+    end
+    private_constant :CacheScope
+
+    # In-memory cache for policy evaluation results. Concurrent applications
+    # should wrap each independent operation in with_cache_scope.
     class << self
       extend T::Sig
 
+      CACHE_SCOPE_KEY = :sequel_privacy_cache_scope
+      private_constant :CACHE_SCOPE_KEY
+
+      sig do
+        type_parameters(:U)
+          .params(block: T.proc.returns(T.type_parameter(:U)))
+          .returns(T.type_parameter(:U))
+      end
+      def with_cache_scope(&block)
+        previous = Thread.current[CACHE_SCOPE_KEY]
+        Thread.current[CACHE_SCOPE_KEY] = CacheScope.new
+        block.()
+      ensure
+        Thread.current[CACHE_SCOPE_KEY] = previous
+      end
+
       sig { returns(T::Hash[Integer, Symbol]) }
       def cache
-        @cache ||= T.let({}, T.nilable(T::Hash[Integer, Symbol]))
+        active_cache_scope&.cache || (@cache ||= T.let({}, T.nilable(T::Hash[Integer, Symbol])))
       end
 
       # Tracks single-match optimization state.
       # Key: [policy, actor, viewer_context].hash → Value: subject.hash
       sig { returns(T::Hash[Integer, Integer]) }
       def single_matches
-        @single_matches ||= T.let({}, T.nilable(T::Hash[Integer, Integer]))
+        active_cache_scope&.single_matches ||
+          (@single_matches ||= T.let({}, T.nilable(T::Hash[Integer, Integer])))
       end
 
       sig { void }
       def clear_cache!
-        @cache = {}
-        @single_matches = {}
+        if (scope = active_cache_scope)
+          scope.clear!
+        else
+          @cache = {}
+          @single_matches = {}
+        end
+      end
+
+      private
+
+      sig { returns(T.nilable(CacheScope)) }
+      def active_cache_scope
+        T.cast(Thread.current[CACHE_SCOPE_KEY], T.nilable(CacheScope))
       end
     end
   end

data/lib/sequel/privacy/enforcer.rb

@@ -38,6 +38,8 @@ module Sequel
         ).returns(T::Boolean)
       end
       def self.enforce(policies, subject, viewer_context, direct_object = nil)
+        viewer_context.assert_usable!
+
         saved = Thread.current[EVAL_KEY]
         Thread.current[EVAL_KEY] = true
 

data/lib/sequel/privacy/errors.rb

@@ -15,6 +15,9 @@ module Sequel
     # Raised when an invalid viewer context is used
     class InvalidViewerContextError < StandardError; end
 
+    # Raised if #invalidates was called on this VC.
+    class InvalidatedViewerContext < InvalidViewerContextError; end
+
     class MissingViewerContext < StandardError; end
 
     # Raised when attempting to modify privacy settings after finalization

data/lib/sequel/privacy/version.rb

@@ -3,6 +3,6 @@
 
 module Sequel
   module Privacy
-    VERSION = '0.6.1'
+    VERSION = '0.7.1'
   end
 end

data/lib/sequel/privacy/viewer_context.rb

@@ -41,6 +41,54 @@ module Sequel
       def self.anonymous
         AnonymousVC.new
       end
+
+      sig { returns(T::Boolean) }
+      def invalidated?
+        @invalidated = T.let(@invalidated, T.nilable(T::Boolean))
+        @invalidated || false
+      end
+
+      sig { void }
+      def assert_usable!
+        return unless invalidated?
+
+        Kernel.raise InvalidatedViewerContext,
+                     "#{self.class.name.to_s.split('::').last} was invalidated and cannot be used again"
+      end
+    end
+
+    # Made available on OmniscientVC and AllPowerfulVCs. Transient contexts are
+    # invalidated when the use block exists. To help you keep these around for
+    # as short a time as possible.
+    module TransientViewerContext
+      extend T::Sig
+      extend T::Helpers
+
+      abstract!
+      requires_ancestor { ViewerContext }
+
+      sig { abstract.returns(Symbol) }
+      def reason; end
+
+      sig do
+        type_parameters(:U)
+          .params(block: T.proc.params(vc: T.untyped, reason: Symbol).returns(T.type_parameter(:U)))
+          .returns(T.type_parameter(:U))
+      end
+      def use(&block)
+        block.call(self, reason)
+      ensure
+        invalidate!
+      end
+
+      sig { returns(T.self_type) }
+      def invalidate!
+        unless invalidated?
+          Sequel::Privacy.logger&.debug("Invalidating viewer context: #{reason}")
+          @invalidated = T.let(true, T.nilable(T::Boolean))
+        end
+        self
+      end
     end
 
     # Standard viewer context with an actor (user/member)
@@ -65,6 +113,7 @@ module Sequel
     # Requires a reason for audit logging.
     class AllPowerfulVC < ViewerContext
       extend T::Sig
+      include TransientViewerContext
 
       sig { params(reason: Symbol).void }
       def initialize(reason)
@@ -72,7 +121,7 @@ module Sequel
         super()
       end
 
-      sig { returns(Symbol) }
+      sig { override.returns(Symbol) }
       attr_reader :reason
     end
 
@@ -80,6 +129,7 @@ module Sequel
     # Used for system operations like authentication lookups.
     class OmniscientVC < ViewerContext
       extend T::Sig
+      include TransientViewerContext
 
       sig { params(reason: Symbol).void }
       def initialize(reason)
@@ -87,7 +137,7 @@ module Sequel
         super()
       end
 
-      sig { returns(Symbol) }
+      sig { override.returns(Symbol) }
       attr_reader :reason
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sequel-privacy
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.1
 platform: ruby
 authors:
 - Austin Bales
@@ -93,6 +93,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.17'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A Sequel plugin that provides declarative privacy policies and automatic
   enforcement at field access and query boundaries.
 email:
@@ -138,7 +152,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.15
+rubygems_version: 4.0.21
 specification_version: 4
 summary: Privacy enforcement plugin for Sequel models
 test_files: []