demo_mode 3.6.0 → 3.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b2e916a3b2b58e6f3cbd027fad72a91b8cb550443a50e64988caa0dbd1ff6fa
-  data.tar.gz: ff00e7655ecf6d9e5ae118b84542bf97ec6e568143e4c2961ef42b1c28e0894c
+  metadata.gz: 268e07b92704ae904b434f1c2865a8a21ece4adfc51775339aa2f5243a7e4624
+  data.tar.gz: fe8974ba779ad030bf120811158e19f767c736c3c4faecf1c59a40dd019c7298
 SHA512:
-  metadata.gz: b240952b7f353fff7cb723a409cc07806ffc477d83640968d486d4050f69d37d51777fa93e603f3e41b869226314cffba020fc7df96f640220dd5389591c0895
-  data.tar.gz: ee5ebfd9364b612abaa6dbff7b0f6d6f0e3624dbd7383486282c9504e85d4d96ee54c39c76b143f4d4f10cb06f557ee0355595b57ca35faf5384ca951f6d883f
+  metadata.gz: f0da8528e1c63ea16b3ca1f9c1e3a6fb1731ea4e5e406bb93e5512422e311139a4e27c1fe6fc38ec45dc9b9be10223625ad15455b73765025d31480a4b8f0fe4
+  data.tar.gz: 75382c2d121e8308a9155280320ce94e3a7a04e0021161c3145a78ec6b6f8ec31815c15562197031cc55a757791cde01be774d4bc1a8a2312853dd6efa8d1bad

data/README.md

@@ -48,6 +48,8 @@ To learn more about how we use `demo_mode` at **Betterment**, check out :sparkle
   - [Non-User Personas](#non-user-personas)
   - [FactoryBot `sequence` extension](#factorybot-sequence-extension)
   - [Database-backed sequences](#database-backed-sequences)
+  - [Persona Pooling](#persona-pooling)
+  - [Disabling Personas or Variants](#disabling-personas-or-variants)
 - [Deploying a demo environment to the cloud](#deploying-a-demo-environment-to-the-cloud)
   - [How to avoid breaking your new "demo" env](#how-to-avoid-breaking-your-new-demo-env)
 - [How to Contribute](#how-to-contribute)
@@ -571,6 +573,66 @@ You can check this setting with:
 CleverSequence.enforce_sequences_exist? # => false (default)
 ```
 
+### Persona Pooling
+
+By default, Demo Mode generates persona accounts on-demand when a user clicks the persona picker. This means each click triggers a background job, and the user waits on a loading spinner. With persona pooling, accounts are pre-generated in the background so that sign-in is near-instant.
+
+To enable pooling, schedule `DemoMode::PoolHydrationJob` to run periodically — every few minutes is a good starting point:
+
+```ruby
+# Enqueue via your scheduler (e.g. Sidekiq-Cron, GoodJob, solid_queue, etc.)
+DemoMode::PoolHydrationJob.perform_later
+```
+
+When called without arguments, the job runs in "orchestrator" mode: it checks the current pool depth for every persona+variant combination and enqueues individual hydration jobs for any that fall below the target size. Those leaf jobs each create one pre-generated session, then re-enqueue themselves until the target is reached.
+
+```ruby
+DemoMode.configure do
+  minimum_pool_size 10
+end
+```
+
+When a user selects a persona, Demo Mode atomically claims a pre-generated session from the pool ("pool hit") or falls back to on-demand generation if the pool is empty.
+
+**Automatic invalidation:** Pool sessions are tied to a checksum of the persona file. If you change a persona's definition, stale sessions are automatically skipped and fresh ones are generated on the next hydration run — no manual cleanup required.
+
+**Monitoring:** Demo Mode emits `ActiveSupport::Notifications` events you can subscribe to:
+
+| Event | Emitted when | Notable payload |
+|---|---|---|
+| `demo_mode.pool.depth` | Each orchestration run, per persona+variant | `persona_name`, `variant`, `value` (sessions needed to reach target) |
+| `demo_mode.session.claimed` | Each sign-in | `persona_name`, `variant`, `pool_hit: true/false` |
+
+A `pool_hit: false` on `demo_mode.session.claimed` means the pool was empty at sign-in time and generation happened on-demand — a signal to increase `minimum_pool_size` or run hydration more frequently.
+
+### Disabling Personas or Variants
+
+You can conditionally disable a persona or a variant by providing an `enabled` block. When the block returns false, the persona (or variant) is hidden from the picker UI, excluded from pool hydration, and treated as non-existent for session creation.
+
+**Persona-level:**
+
+```ruby
+DemoMode.add_persona 'Beta Feature' do
+  enabled { FeatureFlags.beta_enabled? }
+  features << 'Access to beta'
+  sign_in_as { FactoryBot.create(:user, :beta) }
+end
+```
+
+**Variant-level:**
+
+```ruby
+DemoMode.add_persona 'Investor' do
+  variant('default') { sign_in_as { FactoryBot.create(:investor) } }
+  variant('accredited') do
+    enabled { ENV['ACCREDITED_ENABLED'].present? }
+    sign_in_as { FactoryBot.create(:investor, :accredited) }
+  end
+end
+```
+
+Common use cases include feature-flag-gated personas, environment-specific personas (e.g. only in staging), and temporarily hiding a persona without deleting its definition.
+
 ## Deploying a demo environment to the cloud
 
 This gem truly shines when used to deploy a "demo" version of

data/app/controllers/demo_mode/sessions_controller.rb

@@ -24,8 +24,7 @@ module DemoMode
     end
 
     def create
-      @session = Session.new(create_params)
-      @session.save_and_generate_account_later!(**options_params.to_unsafe_h.deep_symbolize_keys)
+      @session = Session.claim_for(**create_params.to_h.symbolize_keys, **options_params.to_h.deep_symbolize_keys)
       @session.reload
       session[:demo_session] = { 'id' => @session.id, 'last_request_at' => Time.zone.now }
       respond_to do |f|
@@ -51,12 +50,12 @@ module DemoMode
 
     def render_signinable_json
       if @session.signinable.blank?
-        render json: { id: @session.id, processing: @session.processing?, status: @session.status }
+        render json: { id: @session.id, processing: @session.processing?, status: @session.status.to_s }
       else
         render json: {
           id: @session.id,
           processing: @session.processing?,
-          status: @session.status,
+          status: @session.status.to_s,
           username: @session.signinable_username,
           password: @session.signinable_password,
           metadata: @session.signinable_metadata,

data/app/jobs/demo_mode/account_generation_job.rb

@@ -8,7 +8,8 @@ module DemoMode
         raise "Unknown persona: #{session.persona_name}" if persona.blank?
 
         signinable = persona.generate!(variant: session.variant, password: session.signinable_password, options: options)
-        session.update!(signinable: signinable, status: 'successful')
+        new_status = session.claimed_at? ? 'in_use' : 'available'
+        session.update!(signinable: signinable, status: new_status, persona_checksum: persona.file_checksum)
       end
     rescue StandardError => e
       session.update!(status: 'failed')

data/app/jobs/demo_mode/pool_hydration_job.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module DemoMode
+  class PoolHydrationJob < DemoMode.base_job_name.constantize
+    def perform(persona_name: nil, variant: nil, count: nil)
+      if persona_name && variant
+        hydrate(persona_name, variant, count)
+      else
+        orchestrate(count)
+      end
+    end
+
+    private
+
+    def orchestrate(count)
+      target = count || DemoMode.minimum_pool_size
+
+      DemoMode.personas.each do |persona|
+        persona.variants.each_key do |v|
+          available = DemoMode::Session.available_for(persona.name, v).count
+          ActiveSupport::Notifications.instrument('demo_mode.pool.depth',
+            persona_name: persona.name, variant: v, value: target - available)
+          next if available >= target
+
+          PoolHydrationJob.perform_later(persona_name: persona.name, variant: v, count: count)
+        end
+      end
+    end
+
+    def hydrate(persona_name, variant, count)
+      return unless DemoMode.personas.any? { |p| p.name.to_s == persona_name.to_s && p.variants.key?(variant) }
+
+      target = count || DemoMode.minimum_pool_size
+      return if DemoMode::Session.available_for(persona_name, variant).count >= target
+
+      DemoMode::Session.new(persona_name: persona_name, variant: variant, pool_session: true)
+        .save_and_generate_account!
+
+      if DemoMode::Session.available_for(persona_name, variant).count < target
+        PoolHydrationJob.perform_later(persona_name: persona_name, variant: variant, count: count)
+      end
+    end
+  end
+end

data/app/models/demo_mode/session.rb

@@ -2,17 +2,38 @@
 
 module DemoMode
   class Session < ActiveRecord::Base
-    attribute :variant, default: :default
+    include ::SteadyState
 
-    enum :status, { processing: 'processing', successful: 'successful', failed: 'failed' }, default: 'processing'
+    DEFAULT_VARIANT = 'default'
+
+    attribute :variant, default: DEFAULT_VARIANT
+
+    attr_accessor :pool_session
+
+    steady_state :status do
+      state 'processing', default: true
+      state 'available', from: 'processing'
+      state 'in_use', from: %w(processing available)
+      state 'failed', from: 'processing'
+    end
+
+    scope :unclaimed, -> { where(claimed_at: nil) }
+    scope :claimed,   -> { where.not(claimed_at: nil) }
+    scope :available_for, ->(persona_name, variant) {
+      persona = DemoMode.personas.find { |p| p.name.to_s == persona_name.to_s }
+      available.unclaimed.where(persona_name: persona_name, variant: variant, persona_checksum: persona&.file_checksum)
+    }
 
     validates :persona_name, :variant, presence: true
     validates :persona, presence: { message: :required }, on: :create, if: :persona_name?
-    validate :successful_status_requires_signinable
+    validates :claimed_at, absence: true, if: :available?
+    validates :claimed_at, presence: true, if: :in_use?
+    validate :terminal_status_requires_signinable
 
     belongs_to :signinable, polymorphic: true, optional: true
 
     before_create :set_password!
+    before_create :claim_if_not_pooled!
 
     delegate :begin_demo,
       :custom_sign_in?,
@@ -26,12 +47,36 @@ module DemoMode
     end
 
     def signinable_metadata
-      successful? ? metadata.call(self) : {}
+      available? || in_use? ? metadata.call(self) : {}
     end
 
     # Heads up: finding a persona is not guaranteed (e.g. past sessions)
     def persona
-      DemoMode.personas.find { |p| p.name.to_s == persona_name.to_s }
+      DemoMode.personas.find { |p| p.name.to_s == persona_name.to_s && p.variants.key?(variant) }
+    end
+
+    def self.claim_for(persona_name:, variant: DEFAULT_VARIANT, **generation_opts)
+      pool_hit = false
+      session = transaction do
+        existing = available_for(persona_name, variant).lock.first
+        pool_hit = existing.present?
+        (existing || new(persona_name: persona_name, variant: variant)).tap do |s|
+          s.claim!
+          AccountGenerationJob.perform_later(s, **generation_opts) if s.signinable.blank?
+        end
+      end
+      ActiveSupport::Notifications.instrument('demo_mode.session.claimed',
+        persona_name: persona_name, variant: variant, pool_hit: pool_hit)
+      session
+    end
+
+    def claim!
+      if new_record?
+        self.claimed_at = Time.zone.now
+        save!
+      else
+        lock!.update!(claimed_at: Time.zone.now, status: 'in_use')
+      end
     end
 
     def save_and_generate_account!(**options)
@@ -54,9 +99,13 @@ module DemoMode
       self.signinable_password ||= DemoMode.current_password
     end
 
-    def successful_status_requires_signinable
-      if status == 'successful' && signinable.blank?
-        errors.add(:status, 'cannot be successful if signinable is not present')
+    def claim_if_not_pooled!
+      self.claimed_at ||= Time.zone.now unless pool_session
+    end
+
+    def terminal_status_requires_signinable
+      if (available? || in_use?) && signinable.blank?
+        errors.add(:status, 'cannot be available or in_use if signinable is not present')
       end
     end
   end

data/db/migrate/20260326000000_add_claimed_at_to_demo_mode_sessions.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class AddClaimedAtToDemoModeSessions < ActiveRecord::Migration[5.1]
+  disable_ddl_transaction!
+
+  def change
+    add_column :demo_mode_sessions, :claimed_at, :datetime
+
+    reversible do |dir|
+      dir.up { safety_assured { execute "UPDATE demo_mode_sessions SET claimed_at = created_at" } }
+    end
+
+    safety_assured do
+      add_index :demo_mode_sessions,
+        %i(persona_name variant status claimed_at),
+        name: :index_demo_mode_sessions_on_pool_lookup,
+        algorithm: :concurrently
+    end
+  end
+end

data/db/migrate/20260331000000_rename_successful_to_in_use_in_demo_mode_sessions.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class RenameSuccessfulToInUseInDemoModeSessions < ActiveRecord::Migration[5.1]
+  def up
+    safety_assured { execute "UPDATE demo_mode_sessions SET status = 'in_use' WHERE status = 'successful'" }
+  end
+
+  def down
+    safety_assured { execute "UPDATE demo_mode_sessions SET status = 'successful' WHERE status = 'in_use'" }
+  end
+end

data/db/migrate/20260409000000_add_persona_checksum_to_demo_mode_sessions.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class AddPersonaChecksumToDemoModeSessions < ActiveRecord::Migration[5.1]
+  disable_ddl_transaction!
+
+  def change
+    add_column :demo_mode_sessions, :persona_checksum, :string
+  end
+end

data/lib/demo_mode/config.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'digest'
 require_relative 'concerns/configurable'
 
 module DemoMode
@@ -14,6 +15,7 @@ module DemoMode
     configurable_value(:personas_path) { 'config/personas' }
     configurable_value(:session_timeout) { 30.minutes }
     configurable_value(:log_level) { :debug }
+    configurable_value(:minimum_pool_size) { 5 }
     configurable_boolean(:display_credentials)
     configurations << :stylesheets
     configurations << :logo
@@ -21,7 +23,6 @@ module DemoMode
     configurations << :icon
     configurations << :password
     configurations << :around_persona_generation
-    configurations << :personas
     configurations << :sign_up_path
     configurations << :sign_in_path
 
@@ -120,13 +121,16 @@ module DemoMode
     private
 
     def auto_load_personas!
-      Rails.root.glob("#{personas_path}/**/*.rb").sort.each do |persona|
-        raise <<~ERROR if File.readlines(persona).grep(/DemoMode\.add_persona/).empty?
-          This file does not define a persona: #{persona}\n
+      Rails.root.glob("#{personas_path}/**/*.rb").sort.each do |persona_file|
+        raise <<~ERROR if File.readlines(persona_file).grep(/DemoMode\.add_persona/).empty?
+          This file does not define a persona: #{persona_file}\n
           Please use `DemoMode.add_persona`
         ERROR
 
-        load(persona)
+        checksum = Digest::SHA256.hexdigest(File.read(persona_file))
+        before_count = @personas.length
+        load(persona_file)
+        @personas[before_count..].each { |p| p.file_checksum = checksum }
       end
     end
   end

data/lib/demo_mode/persona.rb

@@ -6,7 +6,7 @@ module DemoMode
   class Persona
     include ActiveModel::Model
 
-    attr_accessor :name
+    attr_accessor :name, :file_checksum
 
     validates :name, presence: true
     validate :persona_must_have_at_least_one_feature
@@ -53,13 +53,13 @@ module DemoMode
     end
 
     def variant(name, &block)
-      variants[name] = Variant.new(name: name).tap do |v|
+      (@variants ||= {}.with_indifferent_access)[name] = Variant.new(name: name).tap do |v|
         v.instance_eval(&block)
       end
     end
 
     def variants
-      @variants ||= {}.with_indifferent_access
+      (@variants ||= {}.with_indifferent_access).select { |_, v| v.enabled? }
     end
 
     def generate!(variant: :default, password: nil, options: {})
@@ -89,6 +89,14 @@ module DemoMode
       true
     end
 
+    def enabled(&block)
+      @enabled_condition = block
+    end
+
+    def enabled?
+      @enabled_condition ? @enabled_condition.call : true
+    end
+
     def callout(callout = true) # rubocop:disable Style/OptionalBooleanParameter
       @callout = callout
     end
@@ -138,6 +146,14 @@ module DemoMode
         @signinable_generator = signinable_generator
       end
 
+      def enabled(&block)
+        @enabled_condition = block
+      end
+
+      def enabled?
+        @enabled_condition ? @enabled_condition.call : true
+      end
+
       def title
         name.is_a?(Symbol) ? name.to_s.titleize : name.to_s
       end

data/lib/demo_mode/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DemoMode
-  VERSION = '3.6.0'
+  VERSION = '3.7.1'
 end

data/lib/demo_mode.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'rails'
+require 'steady_state'
 require 'demo_mode/version'
 require 'demo_mode/clever_sequence'
 require 'demo_mode/config'
@@ -35,6 +36,10 @@ module DemoMode
       configuration.persona(name, &)
     end
 
+    def personas
+      configuration.personas.select(&:enabled?)
+    end
+
     def callout_personas
       personas.select(&:callout?)
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: demo_mode
 version: !ruby/object:Gem::Version
-  version: 3.6.0
+  version: 3.7.1
 platform: ruby
 authors:
 - Nathan Griffith
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-20 00:00:00.000000000 Z
+date: 2026-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -124,6 +124,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: steady_state
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: actionmailer
   requirement: !ruby/object:Gem::Requirement
@@ -327,6 +341,7 @@ files:
 - app/controllers/demo_mode/application_controller.rb
 - app/controllers/demo_mode/sessions_controller.rb
 - app/jobs/demo_mode/account_generation_job.rb
+- app/jobs/demo_mode/pool_hydration_job.rb
 - app/models/demo_mode/session.rb
 - app/views/demo_mode/sessions/_variant_dropdown.html.erb
 - app/views/demo_mode/sessions/new.html.erb
@@ -337,6 +352,9 @@ files:
 - db/migrate/20201111000000_add_demo_mode_sessions_variant.rb
 - db/migrate/20210505000000_add_demo_mode_sessions_password.rb
 - db/migrate/20250210222933_add_demo_mode_sessions_status.rb
+- db/migrate/20260326000000_add_claimed_at_to_demo_mode_sessions.rb
+- db/migrate/20260331000000_rename_successful_to_in_use_in_demo_mode_sessions.rb
+- db/migrate/20260409000000_add_persona_checksum_to_demo_mode_sessions.rb
 - lib/demo_mode.rb
 - lib/demo_mode/clever_sequence.rb
 - lib/demo_mode/clever_sequence/in_memory_backend.rb