pricing_plans 0.1.0

data/lib/pricing_plans/dsl.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  module DSL
+    # This module provides common DSL functionality that can be included
+    # in other classes to provide a consistent interface
+    
+    # Period constants for easy reference
+    PERIOD_OPTIONS = [
+      :billing_cycle,
+      :calendar_month,
+      :calendar_week,
+      :calendar_day,
+      :month,
+      :week,
+      :day
+    ].freeze
+    
+    private
+    
+    def validate_period_option(period)
+      return true if period.respond_to?(:call) # Custom callable
+      return true if PERIOD_OPTIONS.include?(period)
+      
+      # Allow ActiveSupport duration objects
+      return true if period.respond_to?(:seconds)
+      
+      false
+    end
+    
+    def normalize_period(period)
+      case period
+      when :month
+        :calendar_month
+      when :week
+        :calendar_week  
+      when :day
+        :calendar_day
+      else
+        period
+      end
+    end
+  end
+end

data/lib/pricing_plans/engine.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  class Engine < ::Rails::Engine
+    isolate_namespace PricingPlans
+
+    initializer "pricing_plans.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        # Make models available
+        require "pricing_plans/models/enforcement_state"
+        require "pricing_plans/models/usage"
+        require "pricing_plans/models/assignment"
+      end
+    end
+
+    initializer "pricing_plans.action_controller" do
+      ActiveSupport.on_load(:action_controller) do
+        # Include controller guards in ApplicationController
+        include PricingPlans::ControllerGuards
+        # Install a sensible default rescue for feature gating so apps get 403 by default.
+        # Apps can override by defining their own rescue_from in their controllers.
+        include PricingPlans::ControllerRescues if defined?(PricingPlans::ControllerRescues)
+      end
+    end
+
+    # Support API-only apps (ActionController::API)
+    initializer "pricing_plans.action_controller_api" do
+      ActiveSupport.on_load(:action_controller_api) do
+        include PricingPlans::ControllerGuards
+        include PricingPlans::ControllerRescues if defined?(PricingPlans::ControllerRescues)
+      end
+    end
+
+    # Include view helpers (pure-data, no HTML opinions)
+    initializer "pricing_plans.action_view" do
+      ActiveSupport.on_load(:action_view) do
+        include PricingPlans::ViewHelpers if defined?(PricingPlans::ViewHelpers)
+      end
+    end
+
+    # Ensure the configured plan owner class (e.g., Organization) gains the
+    # owner-centric helpers even if the model is not loaded during
+    # configuration time. Runs on each code reload in dev.
+    initializer "pricing_plans.plan_owner_helpers" do
+      ActiveSupport::Reloader.to_prepare do
+        begin
+          klass = PricingPlans::Registry.plan_owner_class
+          if klass && !klass.included_modules.include?(PricingPlans::PlanOwner)
+            klass.include(PricingPlans::PlanOwner)
+          end
+        rescue StandardError
+          # If the plan owner class isn't resolved yet, skip; next reload will try again.
+        end
+      end
+    end
+
+    # Add generator paths
+    config.generators do |g|
+      g.templates.unshift File.expand_path("../../generators", __dir__)
+    end
+
+    # Map FeatureDenied to HTTP 403 by default so unhandled exceptions don't become 500s.
+    initializer "pricing_plans.rescue_responses" do |app|
+      app.config.action_dispatch.rescue_responses.merge!(
+        "PricingPlans::FeatureDenied" => :forbidden
+      ) if app.config.respond_to?(:action_dispatch) && app.config.action_dispatch.respond_to?(:rescue_responses)
+    end
+  end
+end

data/lib/pricing_plans/grace_manager.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  class GraceManager
+    class << self
+      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
+          state = ensure_fresh_state_for_current_window!(state, plan_owner, limit_key)
+
+          return state if state.exceeded?
+
+          plan = PlanResolver.effective_plan_for(plan_owner)
+          limit_config = plan&.limit_for(limit_key)
+
+          grace_period ||= limit_config&.dig(:grace) || 7.days
+
+          state.update!(
+            exceeded_at: Time.current,
+            data: state.data.merge(
+              "grace_period" => grace_period.to_i,
+
+              # Track window for per-period limits
+              "window_start_epoch" => current_window_start_if_per(limit_config, plan_owner, limit_key)&.to_i,
+              "window_end_epoch" => current_window_end_if_per(limit_config, plan_owner, limit_key)&.to_i
+            )
+          )
+
+          # Emit grace start event
+          emit_grace_start_event(plan_owner, limit_key, state.grace_ends_at)
+
+          state
+        end
+      end
+
+      def grace_active?(plan_owner, limit_key)
+        state = fresh_state_or_nil(plan_owner, limit_key)
+        return false unless state&.exceeded?
+        !state.grace_expired?
+      end
+
+      def should_block?(plan_owner, limit_key)
+        plan = PlanResolver.effective_plan_for(plan_owner)
+        limit_config = plan&.limit_for(limit_key)
+        return false unless limit_config
+
+        after_limit = limit_config[:after_limit]
+        return false if after_limit == :just_warn
+
+        # Only block when usage has reached or exceeded the configured limit
+        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?
+
+        return exceeded if after_limit == :block_usage
+
+        # For :grace_then_block, check if grace period expired
+        state = fresh_state_or_nil(plan_owner, limit_key)
+        return false unless state&.exceeded?
+
+        state.grace_expired?
+      end
+
+      def mark_blocked!(plan_owner, limit_key)
+        with_lock(plan_owner, limit_key) do |state|
+          state = ensure_fresh_state_for_current_window!(state, plan_owner, limit_key)
+          return state if state.blocked?
+
+          state.update!(blocked_at: Time.current)
+
+          # Emit block event
+          emit_block_event(plan_owner, limit_key)
+
+          state
+        end
+      end
+
+      def maybe_emit_warning!(plan_owner, limit_key, threshold)
+        with_lock(plan_owner, limit_key) do |state|
+          state = ensure_fresh_state_for_current_window!(state, plan_owner, limit_key)
+          last_threshold = state.last_warning_threshold || 0.0
+
+          # Only emit if this is a higher threshold than last time
+          if threshold > last_threshold
+            plan = PlanResolver.effective_plan_for(plan_owner)
+            limit_config = plan&.limit_for(limit_key)
+            window_start_epoch = nil
+            window_end_epoch = nil
+            if limit_config && limit_config[:per]
+              period_start, period_end = PeriodCalculator.window_for(plan_owner, limit_key)
+              window_start_epoch = period_start.to_i
+              window_end_epoch = period_end.to_i
+            end
+
+            state.update!(
+              last_warning_threshold: threshold,
+              last_warning_at: Time.current,
+              data: state.data.merge(
+                "window_start_epoch" => window_start_epoch,
+                "window_end_epoch" => window_end_epoch
+              )
+            )
+
+            emit_warning_event(plan_owner, limit_key, threshold)
+          end
+
+          state
+        end
+      end
+
+      def reset_state!(plan_owner, limit_key)
+        state = find_state(plan_owner, limit_key)
+        return unless state
+
+        state.destroy!
+      end
+
+      def grace_ends_at(plan_owner, limit_key)
+        state = find_state(plan_owner, limit_key)
+        state&.grace_ends_at
+      end
+
+      private
+
+      def with_lock(plan_owner, limit_key)
+
+        # Use row-level locking to prevent race conditions
+        state = nil
+        begin
+          state = EnforcementState.lock.find_or_create_by!(
+            plan_owner: plan_owner,
+            limit_key: limit_key.to_s
+          ) { |new_state| new_state.data = {} }
+        rescue ActiveRecord::RecordNotUnique
+          # Concurrent creation; fetch the locked row and proceed
+          state = EnforcementState.lock.find_by!(plan_owner: plan_owner, limit_key: limit_key.to_s)
+        end
+
+        # Retry logic for deadlocks
+        retries = 0
+        begin
+          yield(state)
+        rescue ActiveRecord::Deadlocked, ActiveRecord::LockWaitTimeout => e
+          retries += 1
+          if retries < 3
+            sleep(0.1 * retries)
+            retry
+          else
+            raise e
+          end
+        end
+      end
+
+      def find_state(plan_owner, limit_key)
+        EnforcementState.find_by(plan_owner: plan_owner, limit_key: limit_key.to_s)
+      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)
+        return nil unless state
+
+        plan = PlanResolver.effective_plan_for(plan_owner)
+        limit_config = plan&.limit_for(limit_key)
+        return state unless limit_config && limit_config[:per]
+
+        period_start, _ = PeriodCalculator.window_for(plan_owner, limit_key)
+        window_start_epoch = state.data&.dig("window_start_epoch")
+        current_epoch = period_start.to_i
+
+        if stale_for_window?(state, period_start, window_start_epoch, current_epoch)
+          state.destroy!
+          return nil
+        end
+        state
+      end
+
+      def stale_for_window?(state, period_start, window_start_epoch, current_epoch)
+        (state.exceeded_at && state.exceeded_at < period_start) ||
+          (window_start_epoch && window_start_epoch < current_epoch) ||
+          (window_start_epoch && window_start_epoch != current_epoch)
+      end
+
+      def emit_warning_event(plan_owner, limit_key, threshold)
+        Registry.emit_event(:warning, limit_key.to_sym, plan_owner, threshold)
+      end
+
+      def emit_grace_start_event(plan_owner, limit_key, grace_ends_at)
+        Registry.emit_event(:grace_start, limit_key.to_sym, plan_owner, grace_ends_at)
+      end
+
+      def emit_block_event(plan_owner, limit_key)
+        Registry.emit_event(:block, limit_key.to_sym, plan_owner)
+      end
+
+
+      # Ensure the state aligns with the current period window for per-period limits
+      def ensure_fresh_state_for_current_window!(state, plan_owner, limit_key)
+        plan = PlanResolver.effective_plan_for(plan_owner)
+        limit_config = plan&.limit_for(limit_key)
+        return state unless limit_config && limit_config[:per]
+
+        period_start, _ = PeriodCalculator.window_for(plan_owner, limit_key)
+        window_start_epoch = state.data&.dig("window_start_epoch")
+        current_epoch = period_start.to_i
+        if stale_for_window?(state, period_start, window_start_epoch, current_epoch)
+          state.destroy!
+          state = EnforcementState.lock.find_or_create_by!(plan_owner: plan_owner, limit_key: limit_key.to_s) { |new_state| new_state.data = {} }
+        end
+        state
+      end
+
+      def current_window_start_if_per(limit_config, plan_owner, limit_key)
+        return nil unless limit_config && limit_config[:per]
+        PeriodCalculator.window_for(plan_owner, limit_key).first
+      end
+
+      def current_window_end_if_per(limit_config, plan_owner, limit_key)
+        return nil unless limit_config && limit_config[:per]
+        PeriodCalculator.window_for(plan_owner, limit_key).last
+      end
+    end
+  end
+end

data/lib/pricing_plans/integer_refinements.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  # Refinements for Integer to provide DSL sugar like `5.max`
+  # This is scoped only to our DSL usage to avoid polluting the global namespace
+  module IntegerRefinements
+    refine Integer do
+      def max
+        self
+      end
+      
+      # Additional convenience methods for time periods that read well in DSL
+      alias_method :day, :day if method_defined?(:day)
+      alias_method :days, :days if method_defined?(:days)
+      alias_method :week, :week if method_defined?(:week)
+      alias_method :weeks, :weeks if method_defined?(:weeks)
+      alias_method :month, :month if method_defined?(:month) 
+      alias_method :months, :months if method_defined?(:months)
+      
+      # If ActiveSupport isn't loaded, provide basic duration support
+      unless method_defined?(:days)
+        def days
+          self * 86400 # seconds in a day
+        end
+        
+        def day
+          days
+        end
+        
+        def weeks
+          days * 7
+        end
+        
+        def week
+          weeks
+        end
+        
+        def months
+          days * 30 # approximate for basic support
+        end
+        
+        def month
+          months
+        end
+      end
+    end
+  end
+end

data/lib/pricing_plans/job_guards.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  # Lightweight ergonomics for background jobs and services
+  module JobGuards
+    module_function
+
+    # Runs the given block only if within limit or when system override is allowed.
+    # Returns the Result in all cases so callers can inspect state.
+    # Usage:
+    #   PricingPlans::JobGuards.with_plan_limit(:licenses, plan_owner: org, by: 1, allow_system_override: true) do |result|
+    #     # perform work; result.warning?/grace? can be surfaced
+    #   end
+    def with_plan_limit(limit_key, plan_owner:, by: 1, allow_system_override: false)
+      result = ControllerGuards.require_plan_limit!(limit_key, plan_owner: plan_owner, by: by, allow_system_override: allow_system_override)
+
+      blocked_without_override = result.blocked? && !(allow_system_override && result.metadata && result.metadata[:system_override])
+      return result if blocked_without_override
+
+      yield(result) if block_given?
+      result
+    end
+  end
+end

data/lib/pricing_plans/limit_checker.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module PricingPlans
+  class LimitChecker
+    class << self
+      # English-y aliases used widely across helpers/tests
+      def plan_limit_remaining(plan_owner, limit_key)
+        remaining(plan_owner, limit_key)
+      end
+
+      def plan_limit_percent_used(plan_owner, limit_key)
+        percent_used(plan_owner, limit_key)
+      end
+      def within_limit?(plan_owner, limit_key, by: 1)
+        remaining_amount = remaining(plan_owner, limit_key)
+        return true if remaining_amount == :unlimited
+        remaining_amount >= by
+      end
+
+      def remaining(plan_owner, limit_key)
+        plan = PlanResolver.effective_plan_for(plan_owner)
+        limit_config = plan&.limit_for(limit_key)
+        return :unlimited unless limit_config
+
+        limit_amount = limit_config[:to]
+        return :unlimited if limit_amount == :unlimited
+
+        current_usage = current_usage_for(plan_owner, limit_key, limit_config)
+        [0, limit_amount - current_usage].max
+      end
+
+      def percent_used(plan_owner, limit_key)
+        plan = PlanResolver.effective_plan_for(plan_owner)
+        limit_config = plan&.limit_for(limit_key)
+        return 0.0 unless limit_config
+
+        limit_amount = limit_config[:to]
+        return 0.0 if limit_amount == :unlimited || limit_amount.zero?
+
+        current_usage = current_usage_for(plan_owner, limit_key, limit_config)
+        [(current_usage.to_f / limit_amount) * 100, 100.0].min
+      end
+
+      # Keep short helpers undocumented; public API is plan_limit_* aliases
+
+      def after_limit_action(plan_owner, limit_key)
+        plan = PlanResolver.effective_plan_for(plan_owner)
+        limit_config = plan&.limit_for(limit_key)
+        return :block_usage unless limit_config
+
+        limit_config[:after_limit]
+      end
+
+      def limit_amount(plan_owner, limit_key)
+        plan = PlanResolver.effective_plan_for(plan_owner)
+        limit_config = plan&.limit_for(limit_key)
+        return :unlimited unless limit_config
+
+        limit_config[:to]
+      end
+
+      def current_usage_for(plan_owner, limit_key, limit_config = nil)
+        limit_config ||= begin
+          plan = PlanResolver.effective_plan_for(plan_owner)
+          plan&.limit_for(limit_key)
+        end
+
+        return 0 unless limit_config
+
+        if limit_config[:per]
+          # Per-period allowance - check usage table
+          per_period_usage(plan_owner, limit_key)
+        else
+          # Persistent cap - count live objects
+          persistent_usage(plan_owner, limit_key)
+        end
+      end
+
+      def warning_thresholds(plan_owner, limit_key)
+        plan = PlanResolver.effective_plan_for(plan_owner)
+        limit_config = plan&.limit_for(limit_key)
+        return [] unless limit_config
+
+        limit_config[:warn_at] || []
+      end
+
+      def should_warn?(plan_owner, limit_key)
+        percent = percent_used(plan_owner, limit_key)
+        thresholds = warning_thresholds(plan_owner, limit_key)
+
+        # Find the highest threshold that has been crossed
+        crossed_threshold = thresholds.select { |t| percent >= (t * 100) }.max
+        return nil unless crossed_threshold
+
+        # Check if we've already warned for this threshold
+        state = enforcement_state(plan_owner, limit_key)
+        last_threshold = state&.last_warning_threshold
+
+        # Return the threshold if this is a new higher threshold, nil otherwise
+        crossed_threshold > (last_threshold || 0) ? crossed_threshold : nil
+      end
+
+      private
+
+      def per_period_usage(plan_owner, limit_key)
+        period_start, period_end = PeriodCalculator.window_for(plan_owner, limit_key)
+
+        usage = Usage.find_by(
+          plan_owner: plan_owner,
+          limit_key: limit_key.to_s,
+          period_start: period_start,
+          period_end: period_end
+        )
+
+        usage&.used || 0
+      end
+
+      def persistent_usage(plan_owner, limit_key)
+        # This is provided by the Limitable mixin, which registers per-model counters
+        # keyed by limit key. When declared via has_many limited_by_pricing_plans, the
+        # child model registers the counter as well.
+        counter = LimitableRegistry.counter_for(limit_key)
+        return 0 unless counter
+
+        counter.call(plan_owner)
+      end
+
+      def enforcement_state(plan_owner, limit_key)
+        EnforcementState.find_by(
+          plan_owner: plan_owner,
+          limit_key: limit_key.to_s
+        )
+      end
+    end
+  end
+
+  # Registry for Limitable counters
+  class LimitableRegistry
+    class << self
+      def register_counter(limit_key, &block)
+        counters[limit_key.to_sym] = block
+      end
+
+      def counter_for(limit_key)
+        counters[limit_key.to_sym]
+      end
+
+      def counters
+        @counters ||= {}
+      end
+
+      def clear!
+        @counters = {}
+      end
+    end
+  end
+end