sponsored_logs 0.1.0

data/lib/sponsored_logs/advertisers.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "time"
+
+module SponsoredLogs
+  module Advertisers
+    DEFAULT_ADS = [
+      { text: "This log line brought to you by Shopify. Start selling in the time it took to raise that exception.", weight: 1, cpm: 22.0 },
+      { text: "Mint Mobile: premium wireless for the price of one deprecated dependency. Go to mintmobile.com/logs.", weight: 1,
+        cpm: 18.0 },
+      { text: "Quince: luxury log output at radically low overhead. Free returns on any stack trace.", weight: 1, cpm: 16.0 },
+      { text: "Feeling stressed about that stack trace? BetterHelp connects you with a licensed therapist. First segfault 10% off.",
+        weight: 1, cpm: 25.0 },
+      { text: "Wayfair has just what your codebase needs. Got a memory leak? Wayfair's got a couch for that.", weight: 1, cpm: 14.0 },
+      { text: "Amazon: everything you need to ship, delivered before your test suite finishes.", weight: 1, cpm: 20.0 },
+      { text: "Like a good neighbor, State Farm is there -- unlike your on-call engineer at 3am.", weight: 1, cpm: 12.0 },
+      { text: "Ba da ba ba ba, I'm loggin' it. McDonald's.", weight: 1, cpm: 15.0 },
+      { text: "Squarespace: build a beautiful website faster than this build compiles. Use code STDOUT.", weight: 1, cpm: 17.0 },
+      { text: "Let's go places. Toyota. (Preferably away from this NullPointerException.)", weight: 1, cpm: 13.0 }
+    ].freeze
+
+    SELECTION_MODES = %i[weight cpm].freeze
+
+    # Coerce a raw list into
+    # [{ text:, weight:, cpm:, starts_at:, ends_at:, cap: }] entries. Accepts
+    # symbol- or string-keyed hashes; drops entries with blank text. Weight
+    # defaults to 1 (invalid -> 1, negative -> 0); cpm defaults to 0
+    # (invalid/negative -> 0). starts_at/ends_at are optional flight bounds
+    # (nil = unbounded). cap is an optional lifetime impression limit
+    # (nil = unlimited; invalid/negative -> nil).
+    #
+    def self.normalize(ads)
+      Array(ads).filter_map do |entry|
+        next unless entry.is_a?(Hash)
+
+        text = (entry[:text] || entry["text"]).to_s.strip
+        next if text.empty?
+
+        {
+          text: text,
+          weight: coerce_number(entry[:weight] || entry["weight"], default: 1.0),
+          cpm: coerce_number(entry[:cpm] || entry["cpm"], default: 0.0),
+          starts_at: coerce_time(entry[:starts_at] || entry["starts_at"]),
+          ends_at: coerce_time(entry[:ends_at] || entry["ends_at"]),
+          cap: coerce_cap(entry[:cap] || entry["cap"])
+        }
+      end
+    end
+
+    # Parse an impression cap into a positive Integer, or nil (unlimited) when
+    # absent, non-positive, or unparseable.
+    #
+    def self.coerce_cap(value)
+      return nil if value.nil?
+
+      cap = Integer(value)
+      cap.positive? ? cap : nil
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def self.coerce_number(value, default:)
+      return default if value.nil?
+
+      number = Float(value)
+      number.negative? ? 0.0 : number
+    rescue ArgumentError, TypeError
+      default
+    end
+
+    # Parse a flight bound into a Time. Accepts a Time/DateTime directly or a
+    # string (ISO 8601 etc.); anything unparseable or blank becomes nil.
+    #
+    def self.coerce_time(value)
+      return nil if value.nil?
+      return value.to_time if value.respond_to?(:to_time)
+
+      str = value.to_s.strip
+      return nil if str.empty?
+
+      Time.parse(str)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    # Whether an ad is within its flight window at `now`. Missing bounds are
+    # open-ended (nil starts_at = always started; nil ends_at = never ends).
+    #
+    def self.live?(ad, now)
+      return false if ad[:starts_at] && now < ad[:starts_at]
+      return false if ad[:ends_at] && now > ad[:ends_at]
+
+      true
+    end
+
+    # Whether an ad has reached its impression cap given a current count.
+    # Uncapped ads (nil cap) are never capped.
+    #
+    def self.capped?(ad, count)
+      cap = ad[:cap]
+      return false if cap.nil?
+
+      count.to_i >= cap
+    end
+
+    # Whether an ad is eligible for selection: live at `now` and not capped.
+    #
+    def self.eligible?(ad, now, count)
+      live?(ad, now) && !capped?(ad, count)
+    end
+
+    # Status of an ad at `now` given its impression count: :exhausted (cap
+    # reached), :scheduled (window not started), :ended (window passed),
+    # :evergreen (no bounds), or :active.
+    #
+    def self.status(ad, now = Time.now, count = 0)
+      return :exhausted if capped?(ad, count)
+      return :scheduled if ad[:starts_at] && now < ad[:starts_at]
+      return :ended if ad[:ends_at] && now > ad[:ends_at]
+      return :evergreen if ad[:starts_at].nil? && ad[:ends_at].nil?
+
+      :active
+    end
+
+    # Pick one normalized ad entry using the given selection mode, considering
+    # only ads eligible at `now` -- live within their flight window and under
+    # their impression cap (counts is a text => impressions map). In :cpm mode
+    # the cpm drives the odds; if every eligible cpm is 0 we fall back to manual
+    # weights so selection never stalls. A pool with no eligible ads (or whose
+    # eligible weights sum to zero) falls back to the built-in list. Returns nil
+    # only when the pool is truly empty.
+    #
+    def self.pick(ads = DEFAULT_ADS, mode: :weight, now: Time.now, counts: {})
+      pool = eligible(normalize(ads), now, counts)
+      pool = eligible(normalize(DEFAULT_ADS), now, counts) if pool.empty? || pool.sum { |ad| ad[:weight] }.zero?
+
+      key = SELECTION_MODES.include?(mode) ? mode : :weight
+      key = :weight if key == :cpm && pool.sum { |ad| ad[:cpm] }.zero?
+
+      weighted_pick(pool, key)
+    end
+
+    def self.eligible(pool, now, counts)
+      pool.select { |ad| eligible?(ad, now, counts[ad[:text]].to_i) }
+    end
+
+    def self.render(entry, prefix = "[AD]")
+      return if entry.nil?
+
+      prefix = prefix.to_s.strip
+      prefix.empty? ? entry[:text] : "#{prefix} #{entry[:text]}"
+    end
+
+    def self.weighted_pick(pool, key)
+      total = pool.sum { |ad| ad[key] }
+      return pool.sample if total.zero?
+
+      target = rand * total
+      cumulative = 0.0
+      pool.each do |ad|
+        cumulative += ad[key]
+        return ad if target < cumulative
+      end
+
+      pool.last
+    end
+  end
+end

data/lib/sponsored_logs/configuration.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module SponsoredLogs
+  class Configuration
+    attr_accessor :probability, :periodic, :interval, :output, :ad_prefix, :ads, :selection, :store, :report_page
+
+    # Settings that map 1:1 onto an accessor. ads/ads_file are handled
+    # separately because they interact (ads wins; ads_file loads into ads).
+    #
+    DIRECT_KEYS = %i[probability periodic interval output ad_prefix selection store report_page].freeze
+    KNOWN_KEYS = (DIRECT_KEYS + %i[ads ads_file]).freeze
+
+    def initialize
+      @probability = 0.001
+      @periodic = false
+      @interval = 30
+      @output = $stdout
+      @ad_prefix = "[AD]"
+      @ads = Advertisers::DEFAULT_ADS
+      @selection = :weight
+      @store = Ledger::Store::Memory.new
+      @report_page = false
+    end
+
+    # Apply a hash of settings. Symbol or string keys are accepted; unknown
+    # keys warn rather than raise. Only keys actually present are applied, so
+    # partial updates leave everything else intact.
+    #
+    def assign(opts = {}, warn_to: $stderr)
+      opts = normalize_keys(opts)
+
+      opts.each_key do |key|
+        next if KNOWN_KEYS.include?(key)
+
+        warn_to.puts("[sponsored_logs] unknown setting: #{key.inspect}; ignored.")
+      end
+
+      DIRECT_KEYS.each do |key|
+        public_send("#{key}=", opts[key]) if opts.key?(key)
+      end
+
+      assign_ads(opts, warn_to: warn_to)
+      self
+    end
+
+    private
+
+    def assign_ads(opts, warn_to:)
+      if opts.key?(:ads)
+        self.ads = opts[:ads]
+      elsif opts.key?(:ads_file)
+        loaded = AdsFile.load(opts[:ads_file], warn_to: warn_to)
+        self.ads = loaded unless loaded.nil?
+      end
+    end
+
+    def normalize_keys(opts)
+      opts.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+    end
+  end
+end

data/lib/sponsored_logs/engine.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module SponsoredLogs
+  # Mountable engine serving the campaign performance report. Mount it in the
+  # host app's routes to expose the page:
+  #
+  #   mount SponsoredLogs::Engine => "/sponsored_logs_report"
+  #
+  # Even when mounted, every action returns 404 unless
+  # SponsoredLogs.configuration.report_page is true.
+  #
+  class Engine < ::Rails::Engine
+    isolate_namespace SponsoredLogs
+
+    # The engine's app/ and config/ live alongside this file, under report/.
+    #
+    config.root = File.expand_path("report", __dir__)
+  end
+end

data/lib/sponsored_logs/env.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SponsoredLogs
+  module Env
+    TRUTHY = %w[1 true yes on].freeze
+
+    def self.activate?(env = ENV)
+      truthy?(env["SPONSORED_LOGS"])
+    end
+
+    def self.options(env = ENV)
+      opts = {}
+      opts[:probability] = Float(env["SPONSORED_LOGS_PROBABILITY"]) if env["SPONSORED_LOGS_PROBABILITY"]
+      opts[:interval]    = Float(env["SPONSORED_LOGS_INTERVAL"])    if env["SPONSORED_LOGS_INTERVAL"]
+      opts[:periodic]    = truthy?(env["SPONSORED_LOGS_PERIODIC"])  if env["SPONSORED_LOGS_PERIODIC"]
+      opts[:ad_prefix]   = env["SPONSORED_LOGS_PREFIX"]             if env["SPONSORED_LOGS_PREFIX"]
+      opts[:ads_file]    = env["SPONSORED_LOGS_ADS_FILE"]           if env["SPONSORED_LOGS_ADS_FILE"]
+      opts[:selection]   = env["SPONSORED_LOGS_SELECTION"].to_sym   if env["SPONSORED_LOGS_SELECTION"]
+      opts
+    end
+
+    def self.truthy?(value)
+      return false if value.nil?
+
+      TRUTHY.include?(value.strip.downcase)
+    end
+  end
+end

data/lib/sponsored_logs/injector.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module SponsoredLogs
+  module Injector
+    # A prepend can't be undone, so SponsoredLogs.active? is what actually
+    # gates emission -- install! runs once, unsponsor! just flips the flag.
+    #
+    module KernelPatch
+      def puts(*args)
+        result = super
+        SponsoredLogs.maybe_emit(target: $stdout)
+        result
+      end
+    end
+
+    module LoggerPatch
+      def add(severity, message = nil, progname = nil, &)
+        result = super
+        SponsoredLogs.maybe_emit(target: self)
+        result
+      end
+    end
+
+    def self.install!
+      return if @installed
+
+      Kernel.prepend(KernelPatch)
+      Logger.prepend(LoggerPatch)
+      @installed = true
+    end
+
+    def self.installed?
+      @installed == true
+    end
+  end
+end

data/lib/sponsored_logs/ledger/report.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module SponsoredLogs
+  module Ledger
+    # Computes impression/spend figures over a store adapter. The store holds
+    # raw tallies; Report derives totals and per-ad entries from #snapshot.
+    # Spend for an ad is impressions / 1000.0 * cpm (cost per mille).
+    #
+    class Report
+      Entry = Struct.new(:text, :impressions, :cpm, :spend, keyword_init: true)
+
+      def initialize(store)
+        @store = store
+      end
+
+      def record(ad)
+        @store.record(ad)
+      end
+
+      def total_impressions
+        @store.snapshot.sum { |_text, data| data[:impressions] }
+      end
+
+      def total_spend
+        @store.snapshot.sum { |_text, data| spend_for(data[:impressions], data[:cpm]) }
+      end
+
+      def entries
+        @store.snapshot.map do |text, data|
+          Entry.new(
+            text: text,
+            impressions: data[:impressions],
+            cpm: data[:cpm].to_f,
+            spend: spend_for(data[:impressions], data[:cpm])
+          )
+        end
+      end
+
+      # Map of ad text => recorded impressions, for cap enforcement.
+      #
+      def impression_counts
+        @store.snapshot.transform_values { |data| data[:impressions] }
+      end
+
+      def reset
+        @store.reset
+        self
+      end
+
+      private
+
+      def spend_for(impressions, cpm)
+        impressions / 1000.0 * cpm.to_f
+      end
+    end
+  end
+end

data/lib/sponsored_logs/ledger/store/active_record.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module SponsoredLogs
+  module Ledger
+    module Store
+      # Persistent store backed by ActiveRecord, one row per ad keyed by a
+      # SHA256 digest of the ad text (the full text is stored alongside for
+      # reporting). Rows live in `sponsored_logs_impressions`; run the
+      # `sponsored_logs:install` generator to create the migration.
+      #
+      # ActiveRecord is required lazily, so it stays an optional dependency.
+      # Pass model: to use your own class instead of the bundled one.
+      #
+      class ActiveRecord < Base
+        def initialize(model: nil)
+          super()
+          @model = model || build_default_model
+        end
+
+        def record(ad)
+          digest = digest_for(ad[:text])
+
+          # insert skips on conflict (INSERT ... ON CONFLICT DO NOTHING), so an
+          # existing row keeps its impression count. Then atomically bump the
+          # counter and refresh cpm in a single UPDATE.
+          #
+          @model.insert(
+            { text_digest: digest, text: ad[:text], cpm: ad[:cpm].to_f, impressions: 0 },
+            unique_by: :text_digest
+          )
+          @model.where(text_digest: digest).update_all(
+            ["impressions = impressions + 1, cpm = ?", ad[:cpm].to_f]
+          )
+        end
+
+        def snapshot
+          @model.all.to_h do |row|
+            [row.text, { impressions: row.impressions.to_i, cpm: row.cpm.to_f }]
+          end
+        end
+
+        def reset
+          @model.delete_all
+          self
+        end
+
+        private
+
+        def digest_for(text)
+          Digest::SHA256.hexdigest(text.to_s)
+        end
+
+        # Defined lazily so requiring this file never needs ActiveRecord loaded.
+        #
+        def build_default_model
+          require "active_record"
+
+          @default_model ||= Class.new(::ActiveRecord::Base) do
+            self.table_name = "sponsored_logs_impressions"
+          end
+        rescue LoadError
+          raise LoadError, "SponsoredLogs::Ledger::Store::ActiveRecord requires the " \
+                           "`activerecord` gem. Add it to your Gemfile, or pass model: " \
+                           "with your own ActiveRecord class."
+        end
+      end
+    end
+  end
+end

data/lib/sponsored_logs/ledger/store/base.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module SponsoredLogs
+  module Ledger
+    module Store
+      # Contract for ledger store adapters. Subclass this (or duck-type the
+      # three methods) and pass an instance via config.store to persist
+      # impressions wherever you like -- Redis, a database, a file, and so on.
+      #
+      # Ledger::Report computes spend and the report on top of #snapshot, so an
+      # adapter only has to store and return raw tallies.
+      #
+      class Base
+        # Record a single impression for the given normalized ad hash
+        # ({ text:, weight:, cpm: }). Called once per emitted message.
+        #
+        def record(_ad)
+          raise NotImplementedError, "#{self.class}#record must be implemented"
+        end
+
+        # Return the current tallies as { text => { impressions: Integer,
+        # cpm: Float } }. The ledger derives everything else from this.
+        #
+        def snapshot
+          raise NotImplementedError, "#{self.class}#snapshot must be implemented"
+        end
+
+        # Clear all stored impressions.
+        #
+        def reset
+          raise NotImplementedError, "#{self.class}#reset must be implemented"
+        end
+      end
+    end
+  end
+end

data/lib/sponsored_logs/ledger/store/memory.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module SponsoredLogs
+  module Ledger
+    module Store
+      # Default adapter. Keeps impression counts and CPMs in memory, keyed by ad
+      # text. Not persisted across process restarts. A mutex guards writes so the
+      # periodic thread and request threads can record concurrently.
+      #
+      class Memory < Base
+        def initialize
+          super
+          @mutex = Mutex.new
+          @impressions = Hash.new(0)
+          @cpm = {}
+        end
+
+        def record(ad)
+          @mutex.synchronize do
+            @impressions[ad[:text]] += 1
+            @cpm[ad[:text]] = ad[:cpm].to_f
+          end
+        end
+
+        def snapshot
+          @mutex.synchronize do
+            @impressions.each_with_object({}) do |(text, count), acc|
+              acc[text] = { impressions: count, cpm: @cpm[text].to_f }
+            end
+          end
+        end
+
+        def reset
+          @mutex.synchronize do
+            @impressions = Hash.new(0)
+            @cpm = {}
+          end
+          self
+        end
+      end
+    end
+  end
+end

data/lib/sponsored_logs/ledger/store/redis.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module SponsoredLogs
+  module Ledger
+    module Store
+      class Redis < Base
+        DEFAULT_NAMESPACE = "sponsored_logs"
+
+        def initialize(client: nil, namespace: DEFAULT_NAMESPACE)
+          super()
+          @client = client || build_default_client
+          @impressions_key = "#{namespace}:impressions"
+          @cpm_key = "#{namespace}:cpm"
+        end
+
+        def record(ad)
+          @client.hincrby(@impressions_key, ad[:text], 1)
+          @client.hset(@cpm_key, ad[:text], ad[:cpm].to_f)
+        end
+
+        def snapshot
+          impressions = @client.hgetall(@impressions_key)
+          cpm = @client.hgetall(@cpm_key)
+
+          impressions.each_with_object({}) do |(text, count), acc|
+            acc[text] = { impressions: count.to_i, cpm: cpm[text].to_f }
+          end
+        end
+
+        def reset
+          @client.del(@impressions_key, @cpm_key)
+          self
+        end
+
+        private
+
+        # Lazy-require keeps redis an optional dependency.
+        #
+        def build_default_client
+          require "redis"
+          ::Redis.new
+        rescue LoadError
+          raise LoadError, "SponsoredLogs::Ledger::Store::Redis requires the `redis` gem. " \
+                           "Add it to your Gemfile, or pass a client: to the constructor."
+        end
+      end
+    end
+  end
+end

data/lib/sponsored_logs/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module SponsoredLogs
+  class Railtie < Rails::Railtie
+    initializer "sponsored_logs.sponsor_from_env" do
+      config.after_initialize do
+        next unless Env.activate?
+
+        opts = Env.options
+        opts[:output] ||= Rails.logger if Rails.respond_to?(:logger) && Rails.logger
+        SponsoredLogs.sponsor!(opts)
+      end
+    end
+  end
+end

data/lib/sponsored_logs/report/app/controllers/sponsored_logs/reports_controller.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module SponsoredLogs
+  class ReportsController < ActionController::Base
+    # Self-contained page; do not inherit the host application's layout.
+    #
+    layout false
+
+    def show
+      return head(:not_found) unless SponsoredLogs.configuration.report_page
+
+      @report = SponsoredLogs.report
+
+      respond_to do |format|
+        format.html
+        format.json { render json: json_report(@report) }
+      end
+    end
+
+    private
+
+    # Serialize flight bounds as ISO 8601 strings for the JSON API; the HTML
+    # view keeps the Time objects for formatting.
+    #
+    def json_report(report)
+      report.merge(
+        ads: iso_rows(report[:ads]),
+        upcoming: iso_rows(report[:upcoming]),
+        finished: iso_rows(report[:finished])
+      )
+    end
+
+    def iso_rows(rows)
+      rows.map do |ad|
+        ad.merge(starts_at: ad[:starts_at]&.iso8601, ends_at: ad[:ends_at]&.iso8601)
+      end
+    end
+  end
+end