pricing_plans 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99983bea54e570eebe0d01fecb11245816a95ed60eb7cc87a61756009764817f
-  data.tar.gz: 388d3c8b0791cf5388dda9d670a21fd53613105cefcf861c2769667f9f15fab1
+  metadata.gz: 5d4d6193dae586244d9a5eb2780ca9f1b2447636fac1b832cca17832adb19280
+  data.tar.gz: aacfdf85b8f20fca5d2c81d4118a053e47f2636304330c399804d978035b2275
 SHA512:
-  metadata.gz: f99451ddc7aaba6ea9cf5bebf81395ee88383cb5a27cd2efb491ae78a711d99115f4cb5c1fade02aaa9d8cc6b09afcefe96abc8e3f00cf772d4e797b66a13424
-  data.tar.gz: bd14a7080334f2e6aeb215739d33ac3d91f97803a706dfcd83c8053b185ba36fd7797804e4a41a10500946acb00667dfabb6536fa3e184bbac41923e3adef375
+  metadata.gz: b245d32bc4c997d3422aae208fbdd345d06cc6b4473fc2c1712cbabf5be48eb0962879de5dd3410e07191a629f6ea5df296f09525841d60aaa519f978619128a
+  data.tar.gz: 65ac67157b979b0d84590463082d71101cd5ff0d73afc528e54357eecb0e4db365f03a50e57ef5949db699f50d1a010ec72f3e211312dbeeae030bbc9c119e96

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.3.2] - 2026-02-25
+
+- **Fix stale grace warnings after plan upgrades**: Grace/blocked flags now auto-clear when usage drops below limit (self-healing state)
+- **Fix grace triggering at exact limit**: `grace_then_block` now uses `>` (over limit) not `>=` (at limit)
+- **Add lazy grace creation**: Grace starts on-demand when checking status, even if callbacks were bypassed
+- **Add `ExceededStateUtils` module**: DRY extraction for shared exceeded/blocked logic
+
 ## [0.3.1] - 2026-02-16
 
 - **Add `has_plan_assignment?` helper**: Check if a plan owner has a manual assignment without full plan resolution

data/README.md

@@ -180,10 +180,14 @@ Enforcing pricing plans is one of those boring plumbing problems that look easy
 
 - Safe under load: we use row locks and retries when setting grace/blocked/warning state, and we avoid firing the same event twice. See [grace_manager.rb](lib/pricing_plans/grace_manager.rb).
 
+- Self-healing state: when usage drops below the limit (e.g., user deletes resources, upgrades plan, or reduces usage), stale exceeded/blocked flags are automatically cleared. Methods like `grace_active?` and `should_block?` will clear outdated enforcement state as a side effect. This prevents users from remaining incorrectly flagged after remediation.
+
 - Accurate counting: persistent limits count live current rows (using `COUNT(*)`, make sure to index your foreign keys to make it fast at scale); per‑period limits record usage for the current window only. You can filter what counts with `count_scope` (Symbol/Hash/Proc/Array), and plan settings override model defaults. See [limitable.rb](lib/pricing_plans/limitable.rb) and [limit_checker.rb](lib/pricing_plans/limit_checker.rb).
 
 - Clear rules: default is to block when you hit the cap; grace periods are opt‑in. In status/UI, 0 of 0 isn’t shown as blocked. See [plan.rb](lib/pricing_plans/plan.rb), [grace_manager.rb](lib/pricing_plans/grace_manager.rb), and [view_helpers.rb](lib/pricing_plans/view_helpers.rb).
 
+- Semantic enforcement: for `grace_then_block`, grace periods start when usage goes *over* the limit (e.g., 6/5), not when it *reaches* the limit (5/5). This allows users to use their full allocation before grace begins. For `block_usage`, blocking occurs at or over the limit (e.g., at 5/5, the next creation is blocked).
+
 - Simple controllers: one‑liners to guard actions, predictable redirect order (per‑call → per‑controller → global → pricing_path), and an optional central handler. See [controller_guards.rb](lib/pricing_plans/controller_guards.rb).
 
 - Billing‑aware periods: supports billing cycle (when Pay is present), calendar month/week/day, custom time windows, and durations. See [period_calculator.rb](lib/pricing_plans/period_calculator.rb).

data/lib/pricing_plans/callbacks.rb

@@ -106,17 +106,24 @@ module PricingPlans
       return if limit_config[:to] == :unlimited
 
       limit_amount = limit_config[:to].to_i
-      return unless current_usage >= limit_amount
+      after_limit = limit_config[:after_limit]
 
-      case limit_config[:after_limit]
+      case after_limit
       when :just_warn
+        return unless current_usage >= limit_amount
+
         # Just emit warning, don't track grace/block
         check_and_emit_warnings!(plan_owner, limit_key, current_usage, limit_amount)
       when :block_usage
+        return unless current_usage >= limit_amount
+
         # Do NOT mark as blocked here - this callback runs after SUCCESSFUL creation.
         # Block events are emitted from validation when creation is actually blocked.
         nil
       when :grace_then_block
+        # Grace semantics are for over-limit usage, not exact-at-limit.
+        return unless current_usage > limit_amount
+
         # Start grace period if not already in grace/blocked
         unless GraceManager.grace_active?(plan_owner, limit_key) || GraceManager.should_block?(plan_owner, limit_key)
           GraceManager.mark_exceeded!(plan_owner, limit_key, grace_period: limit_config[:grace])

data/lib/pricing_plans/exceeded_state_utils.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  # Shared utilities for checking and managing exceeded state.
+  #
+  # This module provides common logic for determining whether usage has exceeded
+  # limits and for clearing stale exceeded flags. It is included by both
+  # GraceManager (class methods) and StatusContext (instance methods) to ensure
+  # consistent behavior.
+  #
+  # NOTE: Methods that modify state (`clear_exceeded_flags!`) are intentionally
+  # included here. The design decision is that grace/block checks should be
+  # "self-healing" - if usage drops below the limit, stale exceeded flags are
+  # automatically cleared. This prevents situations where users remain incorrectly
+  # flagged as exceeded after deleting resources or after plan upgrades.
+  module ExceededStateUtils
+    # Determine if usage has exceeded the limit based on the after_limit policy.
+    #
+    # For :grace_then_block, exceeded means strictly OVER the limit (>).
+    # For :block_usage and :just_warn, exceeded means AT or over the limit (>=).
+    #
+    # This distinction exists because:
+    # - :block_usage blocks creation of the Nth item (at limit = blocked)
+    # - :grace_then_block allows the Nth item, only starting grace when OVER
+    #
+    # @param current_usage [Integer] Current usage count
+    # @param limit_amount [Integer, Symbol] The configured limit (may be :unlimited)
+    # @param after_limit [Symbol] The enforcement policy (:block_usage, :grace_then_block, :just_warn)
+    # @return [Boolean] true if usage is considered exceeded for this policy
+    def exceeded_now?(current_usage, limit_amount, after_limit:)
+      # 0-of-0 is a special case: not considered exceeded for UX purposes
+      return false if limit_amount.to_i.zero? && current_usage.to_i.zero?
+
+      if after_limit == :grace_then_block
+        current_usage > limit_amount.to_i
+      else
+        current_usage >= limit_amount.to_i
+      end
+    end
+
+    # Clear exceeded and blocked flags from an enforcement state record.
+    #
+    # This is called when usage drops below the limit to "heal" stale state.
+    # Uses update_columns for efficiency (skips validations/callbacks).
+    #
+    # @param state [EnforcementState] The state record to clear
+    # @return [EnforcementState, nil] The updated state, or nil if no updates needed
+    def clear_exceeded_flags!(state)
+      return unless state
+
+      updates = {}
+      updates[:exceeded_at] = nil if state.exceeded_at.present?
+      updates[:blocked_at] = nil if state.blocked_at.present?
+      return state if updates.empty?
+
+      updates[:updated_at] = Time.current
+      state.update_columns(updates)
+      state
+    end
+  end
+end

data/lib/pricing_plans/grace_manager.rb

@@ -3,6 +3,7 @@
 module PricingPlans
   class GraceManager
     class << self
+      include ExceededStateUtils
       def mark_exceeded!(plan_owner, limit_key, grace_period: nil)
         with_lock(plan_owner, limit_key) do |state|
           # Ensure state is for the current window for per-period limits
@@ -36,6 +37,14 @@ module PricingPlans
       def grace_active?(plan_owner, limit_key)
         state = fresh_state_or_nil(plan_owner, limit_key)
         return false unless state&.exceeded?
+
+        plan = PlanResolver.effective_plan_for(plan_owner)
+        limit_config = plan&.limit_for(limit_key)
+        unless currently_exceeded?(plan_owner, limit_key, limit_config)
+          clear_exceeded_flags!(state)
+          return false
+        end
+
         !state.grace_expired?
       end
 
@@ -51,11 +60,16 @@ module PricingPlans
         limit_amount = limit_config[:to]
         return false if limit_amount == :unlimited
         current_usage = LimitChecker.current_usage_for(plan_owner, limit_key, limit_config)
-        exceeded = current_usage >= limit_amount.to_i
-        # Treat 0-of-0 as not blocked for UX/severity/status purposes
-        exceeded = false if limit_amount.to_i.zero? && current_usage.to_i.zero?
+        exceeded = exceeded_now?(current_usage, limit_amount, after_limit: after_limit)
 
-        return exceeded if after_limit == :block_usage
+        unless exceeded
+          if (state = fresh_state_or_nil(plan_owner, limit_key))
+            clear_exceeded_flags!(state)
+          end
+          return false
+        end
+
+        return true if after_limit == :block_usage
 
         # For :grace_then_block, check if grace period expired
         state = fresh_state_or_nil(plan_owner, limit_key)
@@ -119,7 +133,7 @@ module PricingPlans
       end
 
       def grace_ends_at(plan_owner, limit_key)
-        state = find_state(plan_owner, limit_key)
+        state = fresh_state_or_nil(plan_owner, limit_key)
         state&.grace_ends_at
       end
 
@@ -158,6 +172,17 @@ module PricingPlans
         EnforcementState.find_by(plan_owner: plan_owner, limit_key: limit_key.to_s)
       end
 
+      def currently_exceeded?(plan_owner, limit_key, limit_config = nil)
+        limit_config ||= PlanResolver.effective_plan_for(plan_owner)&.limit_for(limit_key)
+        return false unless limit_config
+
+        limit_amount = limit_config[:to]
+        return false if limit_amount == :unlimited
+
+        current_usage = LimitChecker.current_usage_for(plan_owner, limit_key, limit_config)
+        exceeded_now?(current_usage, limit_amount, after_limit: limit_config[:after_limit])
+      end
+
       # Returns nil if state is stale for the current period window for per-period limits
       def fresh_state_or_nil(plan_owner, limit_key)
         state = find_state(plan_owner, limit_key)

data/lib/pricing_plans/status_context.rb

@@ -7,6 +7,8 @@ module PricingPlans
   #
   # Thread-safe by design: each call to status() gets its own context instance.
   class StatusContext
+    include ExceededStateUtils
+
     attr_reader :plan_owner
 
     def initialize(plan_owner)
@@ -67,7 +69,26 @@ module PricingPlans
       return @grace_active_cache[key] if @grace_active_cache.key?(key)
 
       state = fresh_enforcement_state(limit_key)
-      return @grace_active_cache[key] = false unless state&.exceeded?
+
+      # If no state exists but we're over limit for grace_then_block, lazily create grace
+      unless state&.exceeded?
+        if should_lazily_start_grace?(limit_key)
+          limit_config = limit_config_for(limit_key)
+          GraceManager.mark_exceeded!(@plan_owner, limit_key, grace_period: limit_config[:grace])
+          # Clear caches to get fresh state
+          @fresh_enforcement_state_cache&.delete(key)
+          @enforcement_state_cache&.delete(key)
+          state = fresh_enforcement_state(limit_key)
+        else
+          return @grace_active_cache[key] = false
+        end
+      end
+
+      unless currently_exceeded?(limit_key)
+        clear_exceeded_flags!(state)
+        return @grace_active_cache[key] = false
+      end
+
       @grace_active_cache[key] = !state.grace_expired?
     end
 
@@ -77,7 +98,10 @@ module PricingPlans
       return @grace_ends_at_cache[key] if @grace_ends_at_cache.key?(key)
 
       state = fresh_enforcement_state(limit_key)
-      @grace_ends_at_cache[key] = state&.grace_ends_at
+      return @grace_ends_at_cache[key] = nil unless state&.exceeded?
+      return @grace_ends_at_cache[key] = nil unless grace_active?(limit_key)
+
+      @grace_ends_at_cache[key] = state.grace_ends_at
     end
 
     # Cached should block check - implemented directly to avoid GraceManager's plan resolution
@@ -95,13 +119,16 @@ module PricingPlans
       return @should_block_cache[key] = false if limit_amount == :unlimited
 
       current_usage = current_usage_for(limit_key)
-      exceeded = current_usage >= limit_amount.to_i
-      exceeded = false if limit_amount.to_i.zero? && current_usage.to_i.zero?
+      exceeded = exceeded_now?(current_usage, limit_amount, after_limit: after_limit)
 
       return @should_block_cache[key] = exceeded if after_limit == :block_usage
 
       # For :grace_then_block, check if grace period expired
-      return @should_block_cache[key] = false unless exceeded
+      unless exceeded
+        state = fresh_enforcement_state(limit_key)
+        clear_exceeded_flags!(state) if state
+        return @should_block_cache[key] = false
+      end
 
       state = fresh_enforcement_state(limit_key)
       return @should_block_cache[key] = false unless state&.exceeded?
@@ -339,5 +366,32 @@ module PricingPlans
       highest_warn = warn_thresholds.max.to_f * 100.0
       (percent >= highest_warn && highest_warn.positive?) ? :warning : :ok
     end
+
+    def currently_exceeded?(limit_key)
+      limit_config = limit_config_for(limit_key)
+      return false unless limit_config
+
+      limit_amount = limit_config[:to]
+      return false if limit_amount == :unlimited
+
+      current_usage = current_usage_for(limit_key)
+      exceeded_now?(current_usage, limit_amount, after_limit: limit_config[:after_limit])
+    end
+
+    # Check if we should lazily start grace for this limit.
+    # This handles edge cases where usage increased without triggering callbacks
+    # (e.g., status changes, bulk imports, manual DB updates).
+    def should_lazily_start_grace?(limit_key)
+      limit_config = limit_config_for(limit_key)
+      return false unless limit_config
+      return false unless limit_config[:after_limit] == :grace_then_block
+
+      limit_amount = limit_config[:to]
+      return false if limit_amount == :unlimited
+
+      current_usage = current_usage_for(limit_key)
+      current_usage > limit_amount.to_i
+    end
+
   end
 end

data/lib/pricing_plans/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PricingPlans
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 end

data/lib/pricing_plans.rb

@@ -27,6 +27,7 @@ module PricingPlans
   autoload :PaySupport, "pricing_plans/pay_support"
   autoload :LimitChecker, "pricing_plans/limit_checker"
   autoload :LimitableRegistry, "pricing_plans/limit_checker"
+  autoload :ExceededStateUtils, "pricing_plans/exceeded_state_utils"
   autoload :GraceManager, "pricing_plans/grace_manager"
   autoload :Callbacks, "pricing_plans/callbacks"
   autoload :PeriodCalculator, "pricing_plans/period_calculator"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: pricing_plans
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-02-16 00:00:00.000000000 Z
+date: 2026-02-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -93,6 +93,7 @@ files:
 - lib/pricing_plans/controller_rescues.rb
 - lib/pricing_plans/dsl.rb
 - lib/pricing_plans/engine.rb
+- lib/pricing_plans/exceeded_state_utils.rb
 - lib/pricing_plans/grace_manager.rb
 - lib/pricing_plans/integer_refinements.rb
 - lib/pricing_plans/job_guards.rb