Add time-based feature enablements to expressions (#971)

* Add time-based feature enablements to expressions

Introduce Flipper.now, Flipper.time, and Flipper.duration DSL methods
to enable scheduling features, setting expiration times, and defining
time windows without requiring custom properties on actors. Enhance the
Time expression to handle both epoch timestamps (integers/floats) and
ISO8601 datetime strings. Include comprehensive tests for time-based
feature flag scenarios.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

* Ensure Time.parse returns UTC for consistency with Numeric path

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add UTC tests, conductor-setup script, and mise activation for scripts

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>

Author: jnunemaker

examples/expressions.rb

@@ -31,13 +31,9 @@ class Org < Struct.new(:id, :flipper_properties)
   include Flipper::Identifier
 end
 
-NOW = Time.now.to_i
-DAY = 60 * 60 * 24
-
 org = Org.new(1, {
   "type" => "Org",
   "id" => 1,
-  "now" => NOW,
 })
 
 user = User.new(1, {
@@ -46,15 +42,13 @@ class Org < Struct.new(:id, :flipper_properties)
   "plan" => "basic",
   "age" => 39,
   "team_user" => true,
-  "now" => NOW,
 })
 
 admin_user = User.new(2, {
   "type" => "User",
   "id" => 2,
   "admin" => true,
   "team_user" => true,
-  "now" => NOW,
 })
 
 other_user = User.new(3, {
@@ -63,7 +57,6 @@ class Org < Struct.new(:id, :flipper_properties)
   "plan" => "plus",
   "age" => 18,
   "org_admin" => true,
-  "now" => NOW - DAY,
 })
 
 age_expression = Flipper.property(:age).gte(21)
@@ -205,9 +198,40 @@ class Org < Struct.new(:id, :flipper_properties)
 assert Flipper.enabled?(:something, admin_user)
 refute Flipper.enabled?(:something, other_user)
 
-puts "\n\nEnabling based on time"
-scheduled_time_expression = Flipper.property(:now).gte(NOW)
-Flipper.enable :something, scheduled_time_expression
+puts "\n\nEnabling based on time (epoch)"
+scheduled_epoch = Flipper.now.gte(Flipper.time(Time.now.to_i - 86_400))
+Flipper.enable :something, scheduled_epoch
 assert Flipper.enabled?(:something, user)
 assert Flipper.enabled?(:something, admin_user)
-refute Flipper.enabled?(:something, other_user)
+assert Flipper.enabled?(:something, other_user)
+reset
+
+puts "\n\nEnabling based on time (datetime)"
+past_time = (Time.now.utc - 86_400).iso8601
+scheduled_datetime = Flipper.now.gte(Flipper.time(past_time))
+Flipper.enable :something, scheduled_datetime
+assert Flipper.enabled?(:something, user)
+assert Flipper.enabled?(:something, admin_user)
+assert Flipper.enabled?(:something, other_user)
+reset
+
+puts "\n\nDisabling after a time (expiring feature)"
+future_time = (Time.now.utc + 86_400).iso8601
+expiring_expression = Flipper.now.lt(Flipper.time(future_time))
+Flipper.enable :something, expiring_expression
+assert Flipper.enabled?(:something, user)
+assert Flipper.enabled?(:something, admin_user)
+assert Flipper.enabled?(:something, other_user)
+reset
+
+puts "\n\nEnabling within a time window"
+start_time = (Time.now.utc - 86_400).iso8601
+end_time = (Time.now.utc + 86_400).iso8601
+time_window = Flipper.all(
+  Flipper.now.gte(Flipper.time(start_time)),
+  Flipper.now.lt(Flipper.time(end_time))
+)
+Flipper.enable :something, time_window
+assert Flipper.enabled?(:something, user)
+assert Flipper.enabled?(:something, admin_user)
+assert Flipper.enabled?(:something, other_user)

lib/flipper.rb

@@ -100,6 +100,18 @@ def random(max)
     Expression.build({ Random: max })
   end
 
+  def now
+    Expression.build({ Now: [] })
+  end
+
+  def time(value)
+    Expression.build({ Time: value })
+  end
+
+  def duration(scalar, unit = 'second')
+    Expression.build({ Duration: [scalar, unit] })
+  end
+
   def feature_enabled(name)
     Expression.build({ FeatureEnabled: name })
   end

lib/flipper/expressions/time.rb

@@ -1,8 +1,15 @@
+require "time"
+
 module Flipper
   module Expressions
     class Time
       def self.call(value)
-        ::Time.parse(value)
+        case value
+        when Numeric
+          ::Time.at(value).utc
+        else
+          ::Time.parse(value).utc
+        end
       end
     end
   end

script/conductor-setup

@@ -0,0 +1,22 @@
+#!/bin/bash
+set -e
+cd "$(dirname "$0")/.."
+
+if command -v mise &> /dev/null; then
+  # Copy .tool-versions from root workspace if it exists
+  if [ -n "$CONDUCTOR_ROOT_PATH" ] && [ -f "$CONDUCTOR_ROOT_PATH/.tool-versions" ]; then
+    ln -sf "$CONDUCTOR_ROOT_PATH/.tool-versions" .tool-versions
+  fi
+
+  # Install ruby version from .tool-versions
+  mise install
+
+  # Activate mise so gem/bundle use the correct ruby
+  eval "$(mise activate bash)"
+fi
+
+# Install the required bundler version
+gem install bundler:4.0.6
+
+# Bundle install and setup binstubs
+script/bootstrap

script/server

@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/bin/bash
 #/ Usage: server
 #/
 #/ Starts a server for perusing the UI locally.
@@ -16,4 +16,10 @@ cd $(dirname "$0")/..
     exit 0
 }
 
-script/bootstrap && bundle exec rackup examples/ui/basic.ru -p 9999
+# Activate mise if available so we use the correct ruby
+if command -v mise &> /dev/null; then
+  eval "$(mise activate bash)"
+fi
+
+PORT="${CONDUCTOR_PORT:-9999}"
+script/bootstrap && bundle exec rackup examples/ui/basic.ru -p "$PORT"

spec/flipper/expressions/time_spec.rb

@@ -9,5 +9,21 @@
     it "returns time for #iso8601 format" do
       expect(described_class.call(time.iso8601)).to eq(time)
     end
+
+    it "returns time for epoch integer" do
+      expect(described_class.call(time.to_i)).to eq(Time.at(time.to_i).utc)
+    end
+
+    it "returns time for epoch float" do
+      expect(described_class.call(time.to_f)).to be_within(0.001).of(time)
+    end
+
+    it "returns utc for string input" do
+      expect(described_class.call(time.to_s).utc?).to be(true)
+    end
+
+    it "returns utc for numeric input" do
+      expect(described_class.call(time.to_i).utc?).to be(true)
+    end
   end
 end

spec/flipper/gates/expression_spec.rb

@@ -99,6 +99,64 @@ def context(expression, properties: {})
         expect(subject.open?(context)).to be(false)
       end
     end
+
+    context 'for time-based expressions' do
+      it 'enables when now is past a scheduled epoch' do
+        past_epoch = Time.now.to_i - 86_400
+        expression = Flipper.now.gte(Flipper.time(past_epoch))
+        expect(subject.open?(context(expression.value))).to be(true)
+      end
+
+      it 'does not enable when now is before a future epoch' do
+        future_epoch = Time.now.to_i + 86_400
+        expression = Flipper.now.gte(Flipper.time(future_epoch))
+        expect(subject.open?(context(expression.value))).to be(false)
+      end
+
+      it 'enables when now is past a scheduled datetime' do
+        past_time = (Time.now.utc - 86_400).iso8601
+        expression = Flipper.now.gte(Flipper.time(past_time))
+        expect(subject.open?(context(expression.value))).to be(true)
+      end
+
+      it 'does not enable when now is before a future datetime' do
+        future_time = (Time.now.utc + 86_400).iso8601
+        expression = Flipper.now.gte(Flipper.time(future_time))
+        expect(subject.open?(context(expression.value))).to be(false)
+      end
+
+      it 'enables expiring features with lt' do
+        future_time = (Time.now.utc + 86_400).iso8601
+        expression = Flipper.now.lt(Flipper.time(future_time))
+        expect(subject.open?(context(expression.value))).to be(true)
+      end
+
+      it 'disables expired features with lt' do
+        past_time = (Time.now.utc - 86_400).iso8601
+        expression = Flipper.now.lt(Flipper.time(past_time))
+        expect(subject.open?(context(expression.value))).to be(false)
+      end
+
+      it 'enables within a time window using all' do
+        start_time = (Time.now.utc - 86_400).iso8601
+        end_time = (Time.now.utc + 86_400).iso8601
+        expression = Flipper.all(
+          Flipper.now.gte(Flipper.time(start_time)),
+          Flipper.now.lt(Flipper.time(end_time))
+        )
+        expect(subject.open?(context(expression.value))).to be(true)
+      end
+
+      it 'does not enable outside a time window' do
+        start_time = (Time.now.utc + 86_400).iso8601
+        end_time = (Time.now.utc + 172_800).iso8601
+        expression = Flipper.all(
+          Flipper.now.gte(Flipper.time(start_time)),
+          Flipper.now.lt(Flipper.time(end_time))
+        )
+        expect(subject.open?(context(expression.value))).to be(false)
+      end
+    end
   end
 
   describe '#protects?' do