code_sunset 0.1.0

data/db/migrate/20260331000000_harden_code_sunset_reliability.rb

@@ -0,0 +1,39 @@
+class HardenCodeSunsetReliability < ActiveRecord::Migration[7.1]
+  def change
+    add_column :code_sunset_daily_rollups, :app_env, :string
+    reversible do |dir|
+      dir.up do
+        execute <<~SQL
+          UPDATE code_sunset_daily_rollups rollups
+          SET app_env = matched.app_env
+          FROM (
+            SELECT feature_key, DATE(occurred_at) AS day, MAX(app_env) AS app_env
+            FROM code_sunset_events
+            GROUP BY feature_key, DATE(occurred_at)
+          ) matched
+          WHERE rollups.feature_key = matched.feature_key
+            AND rollups.day = matched.day
+        SQL
+
+        execute "UPDATE code_sunset_daily_rollups SET app_env = 'unknown' WHERE app_env IS NULL"
+      end
+    end
+
+    change_column_null :code_sunset_daily_rollups, :app_env, false
+
+    remove_index :code_sunset_daily_rollups, column: [:feature_key, :day]
+    add_index :code_sunset_daily_rollups, [:feature_key, :app_env, :day], unique: true, name: "index_code_sunset_rollups_on_feature_env_day"
+
+    create_table :code_sunset_alert_deliveries do |t|
+      t.string :feature_key, null: false
+      t.string :status, null: false
+      t.string :alert_kind, null: false
+      t.datetime :delivered_at, null: false
+      t.jsonb :payload, null: false, default: {}
+      t.timestamps
+    end
+
+    add_index :code_sunset_alert_deliveries, [:feature_key, :status, :alert_kind, :delivered_at], name: "index_code_sunset_alerts_on_feature_status_kind_time"
+    add_index :code_sunset_alert_deliveries, :delivered_at
+  end
+end

data/lib/code_sunset/alert_dispatcher.rb

@@ -0,0 +1,103 @@
+module CodeSunset
+  class AlertDispatcher
+    ALERT_KIND = "deprecated_usage".freeze
+
+    def initialize(feature_key)
+      @feature = CodeSunset::Feature.find_by(key: feature_key)
+    end
+
+    def dispatch_if_due
+      return unless feature
+
+      snapshot = CodeSunset::FeatureQuery.new({}, scope: CodeSunset::Feature.where(id: feature.id)).call.first
+      return unless snapshot
+      return unless alertable?(snapshot)
+      return if recently_delivered?(snapshot)
+
+      payload = build_payload(snapshot)
+      notify_logger(payload)
+      notify_webhook(payload)
+      notify_slack(payload)
+      record_delivery(snapshot, payload)
+      payload
+    end
+
+    private
+
+    attr_reader :feature
+
+    def alertable?(snapshot)
+      snapshot.status != "active" && snapshot.hits_7d.to_i.positive?
+    end
+
+    def build_payload(snapshot)
+      sample_event = feature.events.recent_first.first
+
+      {
+        feature_key: feature.key,
+        status: snapshot.status,
+        last_seen_at: snapshot.last_seen_at,
+        hits_7d: snapshot.hits_7d,
+        hits_30d: snapshot.hits_30d,
+        unique_orgs_count: snapshot.unique_orgs_count,
+        unique_users_count: snapshot.unique_users_count,
+        example_org: sample_event&.display_org_identifier,
+        example_user: sample_event&.display_user_identifier
+      }
+    end
+
+    def recently_delivered?(snapshot)
+      CodeSunset::AlertDelivery.recent_for(
+        feature_key: feature.key,
+        status: snapshot.status,
+        alert_kind: ALERT_KIND,
+        since: CodeSunset.configuration.alert_cooldown.ago
+      ).exists?
+    end
+
+    def record_delivery(snapshot, payload)
+      CodeSunset::AlertDelivery.create!(
+        feature_key: feature.key,
+        status: snapshot.status,
+        alert_kind: ALERT_KIND,
+        delivered_at: Time.current,
+        payload: payload
+      )
+    end
+
+    def notify_logger(payload)
+      CodeSunset.logger.warn("[code_sunset] alert #{payload.to_json}")
+    end
+
+    def notify_webhook(payload)
+      proc_hook = CodeSunset.configuration.alert_webhook_proc
+      if proc_hook.respond_to?(:call)
+        CodeSunset.safe_execute("alert webhook proc") { proc_hook.call(payload) }
+      elsif CodeSunset.configuration.alert_webhook_url.present?
+        post_json(CodeSunset.configuration.alert_webhook_url, payload)
+      end
+    end
+
+    def notify_slack(payload)
+      return if CodeSunset.configuration.slack_webhook_url.blank?
+
+      message = {
+        text: "Feature #{payload[:feature_key]} is #{payload[:status]} and still saw #{payload[:hits_7d]} hits in the last 7 days across #{payload[:unique_orgs_count]} orgs."
+      }
+      post_json(CodeSunset.configuration.slack_webhook_url, message)
+    end
+
+    def post_json(url, payload)
+      CodeSunset.safe_execute("alert post #{url}") do
+        uri = URI.parse(url)
+        request = Net::HTTP::Post.new(uri.request_uri)
+        request["Content-Type"] = "application/json"
+        request.body = payload.to_json
+
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+          http.request(request)
+        end
+      end
+    end
+  end
+end

data/lib/code_sunset/analytics_filters.rb

@@ -0,0 +1,59 @@
+module CodeSunset
+  class AnalyticsFilters
+    RAW_DIMENSION_KEYS = %i[org_id user_id plan paid_only exclude_internal].freeze
+
+    def initialize(filters = {})
+      @filters = filters.to_h.symbolize_keys
+    end
+
+    def raw_dimension_filters?
+      raw_dimension_keys.any? { |key| filters[key].present? }
+    end
+
+    def raw_dimension_keys
+      (RAW_DIMENSION_KEYS + CodeSunset.configuration.custom_filters.keys).select { |key| filters[key].present? }
+    end
+
+    def raw_filters
+      filters.slice(:app_env, :plan, :org_id, :user_id, :paid_only, :exclude_internal, :from, :to, *CodeSunset.configuration.custom_filters.keys)
+    end
+
+    def recent_raw_filters
+      filters.slice(:app_env)
+    end
+
+    def rollup_filters
+      filters.slice(:app_env, :from, :to)
+    end
+
+    def retain_range(range)
+      [range.begin, raw_retention_start].max..range.end
+    end
+
+    def raw_retained_range
+      raw_retention_start..Time.current.end_of_day
+    end
+
+    def raw_filter_notice
+      return unless raw_dimension_filters?
+
+      keys = raw_dimension_keys.map { |key| filter_label_for(key) }.join(", ")
+      "Filters for #{keys} use retained raw events only. Historical results are limited to the last #{CodeSunset.configuration.event_retention_days} days."
+    end
+
+    private
+
+    attr_reader :filters
+
+    def raw_retention_start
+      CodeSunset.configuration.event_retention_days.days.ago.beginning_of_day
+    end
+
+    def filter_label_for(key)
+      configured = CodeSunset.configuration.custom_filters[key.to_sym]
+      return configured[:label] if configured
+
+      key.to_s.tr("_", " ")
+    end
+  end
+end

data/lib/code_sunset/configuration.rb

@@ -0,0 +1,104 @@
+module CodeSunset
+  class Configuration
+    attr_accessor :enabled,
+      :environment,
+      :async,
+      :sample_rate,
+      :app_version,
+      :identity_fields,
+      :hash_identity,
+      :dashboard_authorizer,
+      :org_resolver,
+      :user_resolver,
+      :plan_resolver,
+      :internal_org_resolver,
+      :paid_org_resolver,
+      :alert_webhook_url,
+      :alert_webhook_proc,
+      :slack_webhook_url,
+      :event_retention_days,
+      :enqueue_failure_policy,
+      :enqueue_buffer_size,
+      :alert_cooldown
+
+    def initialize
+      @enabled = true
+      @environment = defined?(Rails) ? Rails.env : ENV.fetch("RAILS_ENV", ENV.fetch("RACK_ENV", "development"))
+      @async = true
+      @sample_rate = 1.0
+      @app_version = ENV["CODE_SUNSET_APP_VERSION"] || ENV["APP_VERSION"] || ENV["GIT_SHA"]
+      @identity_fields = %i[user_id org_id]
+      @hash_identity = false
+      @dashboard_authorizer = nil
+      @org_resolver = nil
+      @user_resolver = nil
+      @plan_resolver = nil
+      @internal_org_resolver = nil
+      @paid_org_resolver = nil
+      @alert_webhook_url = nil
+      @alert_webhook_proc = nil
+      @slack_webhook_url = nil
+      @event_retention_days = 90
+      @enqueue_failure_policy = :drop
+      @enqueue_buffer_size = 1000
+      @alert_cooldown = 24.hours
+      @custom_filters = {}
+    end
+
+    def sample_rate=(value)
+      numeric = value.to_f
+      @sample_rate = numeric.clamp(0.0, 1.0)
+    end
+
+    def identity_fields=(value)
+      @identity_fields = Array(value).map(&:to_sym)
+    end
+
+    def enqueue_failure_policy=(value)
+      @enqueue_failure_policy = (value || :drop).to_sym
+    end
+
+    def enqueue_buffer_size=(value)
+      @enqueue_buffer_size = [value.to_i, 1].max
+    end
+
+    def alert_cooldown=(value)
+      @alert_cooldown = value.is_a?(Numeric) ? value.seconds : value
+    end
+
+    def custom_filters
+      @custom_filters ||= {}
+    end
+
+    def custom_filters=(value)
+      @custom_filters = value.to_h.each_with_object({}) do |(key, definition), memo|
+        next if definition.blank?
+
+        normalized = definition.to_h.symbolize_keys
+        memo[key.to_sym] = {
+          label: normalized[:label].presence || key.to_s.humanize,
+          type: (normalized[:type] || :string).to_sym,
+          metadata_key: (normalized[:metadata_key] || key).to_s,
+          options: normalize_filter_options(normalized[:options]),
+          placeholder: normalized[:placeholder].presence
+        }.compact
+      end
+    end
+
+    private
+
+    def normalize_filter_options(options)
+      return unless options.present?
+
+      Array(options).map do |option|
+        if option.is_a?(Array)
+          [option[0].to_s, option[1].to_s]
+        elsif option.is_a?(Hash)
+          [option[:label].to_s, option[:value].to_s]
+        else
+          [option.to_s.humanize, option.to_s]
+        end
+      end
+    end
+  end
+end

data/lib/code_sunset/context.rb

@@ -0,0 +1,49 @@
+module CodeSunset
+  class Context
+    THREAD_KEY = :code_sunset_context_stack
+
+    class << self
+      def current
+        stack.last.deep_dup
+      end
+
+      def push(context)
+        stack << merge(current, normalize(context))
+      end
+
+      def pop
+        stack.pop if stack.size > 1
+        current
+      end
+
+      def with(context)
+        push(context)
+        yield
+      ensure
+        pop
+      end
+
+      private
+
+      def stack
+        Thread.current[THREAD_KEY] ||= [default_context]
+      end
+
+      def default_context
+        { metadata: {} }
+      end
+
+      def normalize(context)
+        context.to_h.symbolize_keys.tap do |normalized|
+          normalized[:metadata] = normalized.fetch(:metadata, {}).to_h.deep_symbolize_keys
+        end
+      end
+
+      def merge(left, right)
+        left.deep_merge(right) do |key, left_value, right_value|
+          key == :metadata ? left_value.to_h.merge(right_value.to_h) : right_value
+        end
+      end
+    end
+  end
+end

data/lib/code_sunset/controller_context.rb

@@ -0,0 +1,23 @@
+module CodeSunset
+  module ControllerContext
+    extend ActiveSupport::Concern
+
+    included do
+      around_action :with_code_sunset_request_context
+    end
+
+    private
+
+    def with_code_sunset_request_context
+      CodeSunset.with_context(
+        request_id: request.request_id,
+        request_path: request.fullpath,
+        controller: controller_name,
+        action: action_name,
+        source: "request"
+      ) do
+        yield
+      end
+    end
+  end
+end

data/lib/code_sunset/engine.rb

@@ -0,0 +1,24 @@
+module CodeSunset
+  class Engine < ::Rails::Engine
+    isolate_namespace CodeSunset
+    engine_name "code_sunset"
+
+    config.generators do |g|
+      g.test_framework :test_unit
+    end
+
+    initializer "code_sunset.controller_context" do
+      ActiveSupport.on_load(:action_controller_base) do
+        include CodeSunset::ControllerContext
+      end
+
+      ActiveSupport.on_load(:active_job) do
+        include CodeSunset::JobContext
+      end
+    end
+
+    config.after_initialize do
+      CodeSunset::Subscriber.subscribe!
+    end
+  end
+end

data/lib/code_sunset/event_buffer.rb

@@ -0,0 +1,28 @@
+module CodeSunset
+  class EventBuffer
+    def initialize
+      @payloads = []
+      @mutex = Mutex.new
+    end
+
+    def store(payload, limit:)
+      @mutex.synchronize do
+        return false if @payloads.size >= limit
+
+        @payloads << payload.deep_dup
+        true
+      end
+    end
+
+    def drain(limit: nil)
+      @mutex.synchronize do
+        count = limit ? [limit.to_i, 0].max : @payloads.size
+        @payloads.shift(count)
+      end
+    end
+
+    def size
+      @mutex.synchronize { @payloads.size }
+    end
+  end
+end

data/lib/code_sunset/event_ingestor.rb

@@ -0,0 +1,57 @@
+module CodeSunset
+  class EventIngestor
+    class << self
+      def ingest(payload)
+        return if payload.blank?
+
+        if CodeSunset.configuration.async && defined?(CodeSunset::PersistEventJob)
+          enqueue(payload)
+        else
+          persist(payload)
+        end
+      rescue StandardError => error
+        CodeSunset.log_error("event ingestion", error)
+        handle_async_failure(payload, error)
+      end
+
+      def persist(payload)
+        return unless defined?(CodeSunset::Event)
+
+        CodeSunset::Event.create_from_payload(payload)
+      rescue StandardError => error
+        CodeSunset.log_error("event persistence", error)
+        nil
+      end
+
+      def flush_buffer(limit: nil)
+        drained = CodeSunset.event_buffer.drain(limit: limit)
+        drained.each { |payload| persist(payload) }
+        drained.size
+      rescue StandardError => error
+        CodeSunset.log_error("buffer flush", error)
+        0
+      end
+
+      private
+
+      def enqueue(payload)
+        CodeSunset::PersistEventJob.perform_later(payload)
+      rescue StandardError => error
+        CodeSunset.log_error("persist event job enqueue", error)
+        handle_async_failure(payload, error)
+      end
+
+      def handle_async_failure(payload, _error)
+        case CodeSunset.configuration.enqueue_failure_policy
+        when :memory_buffer
+          stored = CodeSunset.event_buffer.store(payload, limit: CodeSunset.configuration.enqueue_buffer_size)
+          CodeSunset.logger.warn("[code_sunset] event buffer full, dropping payload for #{payload[:feature_key]}") unless stored
+          stored
+        else
+          CodeSunset.logger.warn("[code_sunset] dropping payload after async enqueue failure for #{payload[:feature_key]}")
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/code_sunset/event_payload.rb

@@ -0,0 +1,79 @@
+module CodeSunset
+  class EventPayload
+    class << self
+      def build(feature_key, attrs = {})
+        return unless CodeSunset.enabled?
+
+        key = feature_key.to_s.strip
+        return if key.blank?
+        return if sampled_out?
+
+        merged = merge_context(attrs)
+        metadata = merged.delete(:metadata).to_h.deep_symbolize_keys
+        org_id = merged[:org_id]
+        user_id = merged[:user_id]
+
+        {
+          feature_key: key,
+          occurred_at: (merged[:occurred_at] || Time.current).utc,
+          user_id: resolve(:user_resolver, user_id, metadata, merged) || user_id,
+          org_id: resolve(:org_resolver, org_id, metadata, merged) || org_id,
+          request_id: merged[:request_id],
+          metadata: metadata,
+          source: merged[:source].presence || infer_source(merged),
+          request_path: merged[:request_path],
+          controller: merged[:controller],
+          action: merged[:action],
+          job_class: merged[:job_class],
+          app_env: merged[:app_env].presence || CodeSunset.configuration.environment,
+          app_version: merged[:app_version].presence || CodeSunset.configuration.app_version,
+          plan: merged[:plan].presence || resolve(:plan_resolver, org_id, metadata, merged),
+          internal_org: coerce_boolean(merged.fetch(:internal_org, resolve(:internal_org_resolver, org_id, metadata, merged))),
+          paid_org: coerce_boolean(merged.fetch(:paid_org, resolve(:paid_org_resolver, org_id, metadata, merged)))
+        }.compact
+      end
+
+      private
+
+      def merge_context(attrs)
+        context = CodeSunset::Context.current
+        normalized = attrs.to_h.symbolize_keys
+        context.deep_merge(normalized) do |key, left_value, right_value|
+          key == :metadata ? left_value.to_h.merge(right_value.to_h) : right_value
+        end
+      end
+
+      def sampled_out?
+        sample_rate = CodeSunset.configuration.sample_rate.to_f
+        sample_rate < 1.0 && rand >= sample_rate
+      end
+
+      def resolve(name, *args)
+        resolver = CodeSunset.configuration.public_send(name)
+        return unless resolver.respond_to?(:call)
+
+        CodeSunset.safe_execute("resolver #{name}") do
+          case resolver.arity
+          when 1 then resolver.call(args[0])
+          when 2 then resolver.call(args[0], args[1])
+          else resolver.call(*args)
+          end
+        end
+      end
+
+      def infer_source(payload)
+        return "job" if payload[:job_class].present?
+        return "request" if payload[:request_path].present?
+
+        "manual"
+      end
+
+      def coerce_boolean(value)
+        return if value.nil?
+        return value if value == true || value == false
+
+        ActiveModel::Type::Boolean.new.cast(value)
+      end
+    end
+  end
+end

data/lib/code_sunset/feature_query.rb

@@ -0,0 +1,69 @@
+module CodeSunset
+  class FeatureQuery
+    def initialize(filters = {}, scope: CodeSunset::Feature.ordered)
+      @filters = filters.to_h.symbolize_keys
+      @scope = scope
+    end
+
+    def call
+      features = scope.to_a
+      return [] if features.empty?
+
+      metrics = metrics_by_feature_key(features.map(&:key))
+
+      features.map do |feature|
+        feature_metrics = metrics.fetch(feature.key, {})
+        last_seen_at = feature_metrics[:last_seen_at]
+        snapshot = CodeSunset::FeatureSnapshot.new(
+          feature: feature,
+          last_seen_at: last_seen_at,
+          hits_7d: feature_metrics[:hits_7d].to_i,
+          hits_30d: feature_metrics[:hits_30d].to_i,
+          unique_orgs_count: feature_metrics[:unique_orgs_count].to_i,
+          unique_users_count: feature_metrics[:unique_users_count].to_i,
+          paid_hits_30d: feature_metrics[:paid_hits_30d].to_i,
+          status: feature.computed_status(last_seen_at: last_seen_at),
+          score: 0.0
+        )
+
+        snapshot.score = CodeSunset::ScoreCalculator.new(feature: feature, snapshot: snapshot).score
+        snapshot
+      end
+    end
+
+    private
+
+    attr_reader :filters, :scope
+
+    def metrics_by_feature_key(feature_keys)
+      metrics = Hash.new { |hash, key| hash[key] = {} }
+      analytics = CodeSunset::AnalyticsFilters.new(filters)
+
+      if analytics.raw_dimension_filters?
+        event_scope = CodeSunset::Event.where(feature_key: feature_keys).apply_filters(analytics.raw_filters)
+        event_scope = event_scope.where(occurred_at: analytics.raw_retained_range)
+        merge_metric!(metrics, CodeSunset::Event.grouped_last_seen(event_scope), :last_seen_at)
+        recent_event_scope = event_scope
+      else
+        rollup_scope = CodeSunset::DailyRollup.where(feature_key: feature_keys).apply_filters(analytics.rollup_filters)
+        merge_metric!(metrics, rollup_scope.group(:feature_key).maximum(:last_seen_at), :last_seen_at)
+        current_event_scope = CodeSunset::Event.where(feature_key: feature_keys).apply_filters(analytics.rollup_filters)
+        merge_metric!(metrics, CodeSunset::Event.grouped_last_seen(current_event_scope), :last_seen_at)
+        recent_event_scope = CodeSunset::Event.where(feature_key: feature_keys).apply_filters(analytics.recent_raw_filters)
+      end
+
+      merge_metric!(metrics, CodeSunset::Event.grouped_counts(recent_event_scope.where(occurred_at: 7.days.ago..Time.current)), :hits_7d)
+      merge_metric!(metrics, CodeSunset::Event.grouped_counts(recent_event_scope.where(occurred_at: 30.days.ago..Time.current)), :hits_30d)
+      merge_metric!(metrics, CodeSunset::Event.grouped_counts(recent_event_scope.where(occurred_at: 30.days.ago..Time.current, paid_org: true)), :paid_hits_30d)
+      merge_metric!(metrics, CodeSunset::Event.grouped_distinct_org_counts(recent_event_scope.where(occurred_at: 30.days.ago..Time.current)), :unique_orgs_count)
+      merge_metric!(metrics, CodeSunset::Event.grouped_distinct_user_counts(recent_event_scope.where(occurred_at: 30.days.ago..Time.current)), :unique_users_count)
+      metrics
+    end
+
+    def merge_metric!(metrics, values, key)
+      values.each do |feature_key, value|
+        metrics[feature_key][key] = value
+      end
+    end
+  end
+end

data/lib/code_sunset/feature_snapshot.rb

@@ -0,0 +1,14 @@
+module CodeSunset
+  FeatureSnapshot = Struct.new(
+    :feature,
+    :last_seen_at,
+    :hits_7d,
+    :hits_30d,
+    :unique_orgs_count,
+    :unique_users_count,
+    :paid_hits_30d,
+    :status,
+    :score,
+    keyword_init: true
+  )
+end