demo_mode 3.4.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0cf4bfb4f300ba2c592c20287bfbb36eba0670f4e36f41da729712366637917
-  data.tar.gz: fc4ce80f27450f77d04b5f12668b32a2bb2d8b246919884a193810cbbd6776c1
+  metadata.gz: a112b6f295027661f77ad3e708d373f6e24483ee562aa23307787c29f5cb45a9
+  data.tar.gz: 61c4948ea423a70295d48ed8b62a2d7de6359efa30560a8b40faa6831e2ada3a
 SHA512:
-  metadata.gz: 59d84c5fec1c5971a5661cb19383b4a831e59378ddaa9958f17f0577453706f2fb58eee90d71b2fa1870b22287a519f59f910fa828e72600b75b1c98435a2e0f
-  data.tar.gz: 857e22d08f59ed49830170b8b7aa5446c276dd13d44a86a1ae1e6fbeebf991cf53a15cc833059eaa8a243481d38a8644845b1476769a8475c21044ac2117cbca
+  metadata.gz: 85fc9433912c6d7b9272cb9e7c526b9fdb7f3326784d6b65ba0b42dd9b9b022f643b79c7f7f5a299af5ee9bddf6c3594414a010fb1dc2bf670642a25b4c363c2
+  data.tar.gz: e05fed5948d72ef9cdd31bf01be8a9589648cdee0da4c6e24c080e1f82fab3cf2c669b6eb47dab470e730b8adbce943cd85c76c3c160f3bc1ed6bc458aaffad3

data/README.md

@@ -1,5 +1,5 @@
-Demo Mode
-=========
+# Demo Mode
+
 [![Gem Version](https://badge.fury.io/rb/demo_mode.svg)](https://rubygems.org/gems/demo_mode)
 [![Tests](https://github.com/Betterment/demo_mode/actions/workflows/tests.yml/badge.svg)](https://github.com/Betterment/demo_mode/actions/workflows/tests.yml)
 
@@ -35,22 +35,23 @@ To learn more about how we use `demo_mode` at **Betterment**, check out :sparkle
 
 ## Table of Contents
 
-* [Getting Started](#getting-started)
-  * [Installation](#installation)
-  * [App-Specific Setup](#app-specific-setup)
-* [Defining Personas](#defining-personas)
-* [Customizing the Design](#customizing-the-design)
-* [Optional Features](#optional-features)
-  * [The "Sign Up" Link](#the-sign-up-link)
-  * [The "Display Credentials" feature](#the-display-credentials-feature)
-  * [Developer CLI](#developer-cli)
-  * [Callbacks](#callbacks)
-  * [Non-User Personas](#non-user-personas)
-  * [FactoryBot `sequence` extension](#factorybot-sequence-extension)
-* [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)
-  * [Suggested Workflow](#suggested-workflow)
+- [Getting Started](#getting-started)
+  - [Installation](#installation)
+  - [App-Specific Setup](#app-specific-setup)
+- [Defining Personas](#defining-personas)
+- [Customizing the Design](#customizing-the-design)
+- [Optional Features](#optional-features)
+  - [The "Sign Up" Link](#the-sign-up-link)
+  - [The "Display Credentials" feature](#the-display-credentials-feature)
+  - [Developer CLI](#developer-cli)
+  - [Callbacks](#callbacks)
+  - [Non-User Personas](#non-user-personas)
+  - [FactoryBot `sequence` extension](#factorybot-sequence-extension)
+  - [Database-backed sequences](#database-backed-sequences)
+- [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)
+  - [Suggested Workflow](#suggested-workflow)
 
 ## Getting Started
 
@@ -538,6 +539,38 @@ end
   conditionally disable any uniqueness validations (e.g.
   `validates ... unless DemoMode.enabled?`).
 
+### Database-backed sequences
+
+By default, `CleverSequence` (used by the FactoryBot `sequence` extension) uses an in-memory Ruby counter. For production demo environments running multiple processes or requiring persistence across restarts, you can enable PostgreSQL-backed sequences:
+
+```ruby
+DemoMode.configure do
+  CleverSequence.use_database_sequences = true
+end
+```
+
+This feature flag controls whether `CleverSequence` uses PostgreSQL native sequences or the existing Ruby-based counter, allowing for gradual rollout and easy rollback. By default, `use_database_sequences` is `false`.
+
+You can check the current setting with:
+
+```ruby
+CleverSequence.use_database_sequences? # => false (default)
+```
+
+You can also enforce that database sequences exist before they are used. When enabled, `CleverSequence` will raise an error if a sequence is requested but the corresponding PostgreSQL SEQUENCE does not exist yet (prompting the engineer to run a migration that creates the SEQUENCE). When disabled (the default), `CleverSequence` will fall back to calculating the next sequence value based on existing database data:
+
+```ruby
+DemoMode.configure do
+  CleverSequence.enforce_sequences_exist = true
+end
+```
+
+You can check this setting with:
+
+```ruby
+CleverSequence.enforce_sequences_exist? # => false (default)
+```
+
 ## Deploying a demo environment to the cloud
 
 This gem truly shines when used to deploy a "demo" version of
@@ -652,6 +685,13 @@ you operate an "on call" process, engineers should be made aware
 that this demo environment _is_ a "production-like" environment
 and should expect "production-like" uptime guarantees.
 
+We also emit an `ActiveSupport::Notifications` event
+(`demo_mode.persona_generated`) every time a persona is generated, which can be
+useful for tracking usage over time and alerting to any unexpected spikes,
+drops in usage, and changes to performance. The custom event payload includes the
+persona name and variant, in addition to standard attributes like execution
+duration and exception details (if an error occurred during generation).
+
 Again, to learn more about how we use and operate our "demo"
 environments at **Betterment**, check out our ✨ [RailsConf 2022 talk entitled
 "RAILS_ENV=demo"](https://youtu.be/VibJu9IMohc)
@@ -669,7 +709,7 @@ creating a new issue to get early feedback on your proposed change.
 
 ### Suggested Workflow
 
-* Fork the project and create a new branch for your contribution.
-* Write your contribution (and any applicable test coverage).
-* Make sure all tests pass (`bundle exec rake`).
-* Submit a pull request.
+- Fork the project and create a new branch for your contribution.
+- Write your contribution (and any applicable test coverage).
+- Make sure all tests pass (`bundle exec rake`).
+- Submit a pull request.

data/lib/demo_mode/clever_sequence/lower_bound_finder.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class CleverSequence
+  LowerBoundFinder = Struct.new(:klass, :column_name, :block) do
+    def lower_bound(current = 1, lower = 0, upper = Float::INFINITY)
+      if exists?(current)
+        lower_bound(next_between(current, upper), [current, lower].max, upper)
+      elsif current - lower > 1
+        lower_bound(next_between(lower, current), lower, [current, upper].min)
+      else # current should == lower + 1
+        lower
+      end
+    end
+
+    private
+
+    def next_between(lower, upper)
+      [((lower + 1) / 2) + (upper / 2), lower * 2].min
+    end
+
+    def exists?(value)
+      klass.public_send(finder_method, block.call(value))
+    end
+
+    # TODO: Move onto modern finder methods.
+    def finder_method
+      :"find_by_#{column_name.to_s.underscore.sub('_crypt', '')}"
+    end
+  end
+end

data/lib/demo_mode/clever_sequence/postgres_backend.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+class CleverSequence
+  module PostgresBackend
+    SEQUENCE_PREFIX = 'cs_'
+
+    class SequenceNotFoundError < StandardError
+      attr_reader :sequence_name, :klass, :attribute
+
+      def initialize(sequence_name:, klass:, attribute:)
+        @sequence_name = sequence_name
+        @klass = klass
+        @attribute = attribute
+
+        super(
+          "Sequence '#{sequence_name}' not found for #{klass.name}##{attribute}. "
+        )
+      end
+    end
+
+    module SequenceResult
+      Exists = Data.define(:sequence_name)
+      Missing = Data.define(:sequence_name, :klass, :attribute, :calculated_start_value)
+    end
+
+    class << self
+      def nextval(klass, attribute, block)
+        name = sequence_name(klass, attribute)
+
+        if sequence_exists?(name)
+          sequence_cache[name] = SequenceResult::Exists.new(name)
+
+          result = ActiveRecord::Base.connection.execute(
+            "SELECT nextval('#{name}')",
+          )
+          result.first['nextval'].to_i
+        else
+          start_value = calculate_sequence_value(klass, attribute, block)
+
+          sequence_cache[name] = SequenceResult::Missing.new(
+            sequence_name: name,
+            klass: klass,
+            attribute: attribute,
+            calculated_start_value: start_value + 1,
+          )
+
+          if CleverSequence.enforce_sequences_exist
+            raise SequenceNotFoundError.new(
+              sequence_name: name,
+              klass: klass,
+              attribute: attribute,
+            )
+          else
+            start_value + 1
+          end
+        end
+      end
+
+      def sequence_name(klass, attribute)
+        table = klass.table_name.gsub(/[^a-z0-9_]/i, '_')
+        attr = attribute.to_s.gsub(/[^a-z0-9_]/i, '_')
+        # Handle PostgreSQL identifier limit:
+        limit = (63 - SEQUENCE_PREFIX.length) / 2
+        "#{SEQUENCE_PREFIX}#{table[0, limit]}_#{attr[0, limit]}"
+      end
+
+      def sequence_cache
+        @sequence_cache ||= {}
+      end
+
+      private
+
+      def sequence_exists?(sequence_name)
+        if sequence_cache.key?(sequence_name)
+          case sequence_cache[sequence_name]
+          when SequenceResult::Exists
+            return true
+          else
+            return false
+          end
+        end
+
+        ActiveRecord::Base.connection.execute(
+          "SELECT 1 FROM information_schema.sequences WHERE sequence_name = '#{sequence_name}' LIMIT 1",
+        ).any?
+      end
+
+      def calculate_sequence_value(klass, attribute, block)
+        column_name = klass.attribute_aliases.fetch(attribute.to_s, attribute.to_s)
+        return 0 unless klass.column_names.include?(column_name)
+
+        ActiveRecord::Base.with_transactional_lock("lower-bound-#{klass}-#{column_name}") do
+          LowerBoundFinder.new(klass, column_name, block).lower_bound
+        end
+      end
+    end
+  end
+end

data/lib/demo_mode/clever_sequence.rb

@@ -1,9 +1,19 @@
 # frozen_string_literal: true
 
+require_relative 'clever_sequence/lower_bound_finder'
+require_relative 'clever_sequence/postgres_backend'
+
 class CleverSequence
   DEFAULT_BLOCK = ->(i) { i }
 
+  cattr_accessor(:sequences) { {} }
+  cattr_accessor(:use_database_sequences) { false }
+  cattr_accessor(:enforce_sequences_exist) { false }
+
   class << self
+    alias use_database_sequences? use_database_sequences
+    alias enforce_sequences_exist? enforce_sequences_exist
+
     def reset!
       sequences.each_value(&:reset!)
     end
@@ -23,7 +33,6 @@ class CleverSequence
     end
   end
 
-  cattr_accessor(:sequences) { {} }
   attr_reader :klass, :attribute, :block
 
   def initialize(attribute, &block)
@@ -38,7 +47,11 @@ class CleverSequence
   end
 
   def next
-    @last_value = last_value + 1
+    @last_value = if CleverSequence.use_database_sequences?
+      PostgresBackend.nextval(klass, attribute, block)
+    else
+      last_value + 1
+    end
     last
   end
 
@@ -71,31 +84,4 @@ class CleverSequence
   def column_exists?
     klass && klass.column_names.include?(column_name)
   end
-
-  LowerBoundFinder = Struct.new(:klass, :column_name, :block) do
-    def lower_bound(current = 1, lower = 0, upper = Float::INFINITY)
-      if exists?(current)
-        lower_bound(next_between(current, upper), [current, lower].max, upper)
-      elsif current - lower > 1
-        lower_bound(next_between(lower, current), lower, [current, upper].min)
-      else # current should == lower + 1
-        lower
-      end
-    end
-
-    private
-
-    def next_between(lower, upper)
-      [((lower + 1) / 2) + (upper / 2), lower * 2].min
-    end
-
-    def exists?(value)
-      klass.public_send(finder_method, block.call(value))
-    end
-
-    # TODO: Move onto modern finder methods.
-    def finder_method
-      :"find_by_#{column_name.to_s.underscore.sub('_crypt', '')}"
-    end
-  end
 end

data/lib/demo_mode/persona.rb

@@ -63,12 +63,14 @@ module DemoMode
     end
 
     def generate!(variant: :default, password: nil, options: {})
-      variant = variants[variant]
-      CleverSequence.reset! if defined?(CleverSequence)
-      DemoMode.current_password = password if password
-      DemoMode.around_persona_generation.call(variant.signinable_generator, **options)
-    ensure
-      DemoMode.current_password = nil
+      ActiveSupport::Notifications.instrument('demo_mode.persona.generate', name: name, variant: variant) do
+        variant = variants[variant]
+        CleverSequence.reset! if defined?(CleverSequence)
+        DemoMode.current_password = password if password
+        DemoMode.around_persona_generation.call(variant.signinable_generator, **options)
+      ensure
+        DemoMode.current_password = nil
+      end
     end
 
     def callout(callout = true) # rubocop:disable Style/OptionalBooleanParameter

data/lib/demo_mode/version.rb

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

data/lib/generators/templates/initializer.rb

@@ -34,6 +34,14 @@ DemoMode.configure do
   # ====================================
   # personas_path 'config/personas'
 
+  # CleverSequence configuration (for FactoryBot sequence extension):
+  # ==================================================================
+  # Enable PostgreSQL-backed sequences (defaults to false):
+  # CleverSequence.use_database_sequences = true
+  #
+  # Raise an error if a database sequence doesn't exist (defaults to false):
+  # CleverSequence.enforce_sequences_exist = true
+
   # A callback that wraps persona-based account generation.
   # You must run `generator.call` and return the "signinable" object:
   # ==================================================

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: demo_mode
 version: !ruby/object:Gem::Version
-  version: 3.4.0
+  version: 3.5.0
 platform: ruby
 authors:
 - Nathan Griffith
@@ -227,6 +227,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  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'
 - !ruby/object:Gem::Dependency
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
@@ -324,6 +338,8 @@ files:
 - db/migrate/20250210222933_add_demo_mode_sessions_status.rb
 - lib/demo_mode.rb
 - lib/demo_mode/clever_sequence.rb
+- lib/demo_mode/clever_sequence/lower_bound_finder.rb
+- lib/demo_mode/clever_sequence/postgres_backend.rb
 - lib/demo_mode/cli.rb
 - lib/demo_mode/clis/multi_word_search_patch.rb
 - lib/demo_mode/concerns/configurable.rb
@@ -364,7 +380,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.8
+rubygems_version: 4.0.6
 specification_version: 4
 summary: A configurable demo mode for your Rails app.
 test_files: []