greenroom 0.1.0

data/lib/greenroom/reporter.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Greenroom
+  # The seam between the parts of this gem that produce events (the recorder,
+  # the experiment behavior) and wherever those events actually go. Kept as
+  # an abstract base plus two concrete subclasses here, and any real delivery
+  # implementation in its own file, so the core of the gem never has to load
+  # a delivery library it does not use.
+  class Reporter
+    # Greenroom's own bound, chosen rather than mirrored. Measured against
+    # the New Relic Ruby agent at version 10.7.1, that agent truncates an
+    # attribute name at 255 characters and an attribute value at 4095, so
+    # this cap is stricter than the value limit of the one delivery target
+    # written so far.
+    #
+    # It is stricter on purpose. Every attribute this gem sends is meant to
+    # be short: a digest, a class name, a count, an identifier. A string
+    # long enough to reach this cap is a sign that something a host supplied
+    # -- an experiment name, a row identifier -- is carrying more than a
+    # label, and cutting it keeps one such value from bloating every event
+    # of a run.
+    MAX_ATTRIBUTE_LENGTH = 255
+
+    def record(event_type, attributes)
+      raise NotImplementedError, "#{self.class} must implement #record"
+    end
+
+    private
+
+    def truncate(attributes)
+      attributes.transform_values do |value|
+        value.is_a?(String) ? value[0, MAX_ATTRIBUTE_LENGTH] : value
+      end
+    end
+  end
+
+  # The default reporter. A host that never configures `Greenroom.reporter`
+  # gets silence rather than a NotImplementedError, so requiring this gem
+  # alone never breaks a caller that has not wired up delivery yet.
+  class Reporter::Null < Reporter
+    def record(event_type, attributes)
+    end
+  end
+
+  # Accumulates every recorded event in memory instead of sending it
+  # anywhere. Exists for tests: a spec can install this reporter and then
+  # assert on `#events` instead of stubbing a real delivery library.
+  class Reporter::Memory < Reporter
+    Event = Struct.new(:type, :attributes)
+
+    attr_reader :events
+
+    def initialize
+      @events = []
+    end
+
+    def record(event_type, attributes)
+      @events << Event.new(event_type, truncate(attributes))
+    end
+  end
+end

data/lib/greenroom/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Greenroom
+  VERSION = "0.1.0"
+end

data/lib/greenroom.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "scientist"
+
+require_relative "greenroom/version"
+require_relative "greenroom/digest"
+require_relative "greenroom/reporter"
+require_relative "greenroom/recorder"
+require_relative "greenroom/experiment_behavior"
+require_relative "greenroom/census/run"
+
+module Greenroom
+  class Error < StandardError; end
+
+  # Raised by `assert_registered!` when no host class has claimed
+  # `Scientist::Experiment`'s one registration slot yet.
+  class NotRegisteredError < Error; end
+
+  # Raised by `Census::Job#build_enumerator` when the host's Sidekiq server
+  # middleware chain does not include `Census::Middleware` yet. Without that
+  # middleware, an error escaping `each_iteration` leaves the thread-local
+  # recorder installed (Sidekiq skips `on_stop` in that case), and the next,
+  # unrelated job Sidekiq happens to run on the same thread would find an
+  # experiment already turned on. Checking at the start of every run turns
+  # that silent leak into a startup-time failure instead.
+  #
+  # Defined here, alongside `NotRegisteredError`, rather than in
+  # `census/middleware.rb`: this file is the one place that never requires
+  # Sidekiq, so every error this gem can raise stays nameable and
+  # rescuable from `require "greenroom"` alone, without also pulling in
+  # the census machinery.
+  class MiddlewareNotRegisteredError < Error; end
+
+  class << self
+    # Where recorded events go. Defaults to `Reporter::Null`, so a host that
+    # has not configured delivery yet gets silence instead of a load-time
+    # error.
+    attr_accessor :reporter
+
+    # Meant to run at boot. A host that includes only `ExperimentBehavior`
+    # in its experiment class, and forgets `Scientist::Experiment`, gets no
+    # error and no candidate ever runs: `enabled?` and `publish` both exist,
+    # but `Scientist::Experiment.new` still returns a `Scientist::Default`
+    # (`enabled?` always false), so every experiment stays quietly inert
+    # forever. Probing at boot turns that silent misconfiguration into a
+    # startup failure instead.
+    def assert_registered!
+      return unless Scientist::Experiment.new("greenroom-probe").instance_of?(Scientist::Default)
+
+      raise NotRegisteredError,
+        "No class includes Scientist::Experiment yet. Add `include Scientist::Experiment` " \
+        "to the class that runs your experiments."
+    end
+  end
+
+  self.reporter = Reporter::Null.new
+end

data/sig/greenroom.rbs

@@ -0,0 +1,4 @@
+module Greenroom
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: greenroom
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- meganemura
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: scientist
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.6.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.6.5
+- !ruby/object:Gem::Dependency
+  name: rubocop-ast
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+description: Greenroom gives a Rails application the parts that turn a Scientist experiment
+  into evidence. An experiment stays inactive until a census job starts a recorder,
+  so a team can merge agent-written code early and run nothing new. The recorder counts
+  the rows, the comparisons, the mismatches, and the candidate errors. At the end
+  of the run it sends one aggregate event and a limited number of sample events. A
+  sample carries an identifier and a digest, and never the value itself.
+email:
+- meganemura@users.noreply.github.com
+executables:
+- greenroom
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/greenroom
+- lib/greenroom.rb
+- lib/greenroom/census/cursor.rb
+- lib/greenroom/census/job.rb
+- lib/greenroom/census/middleware.rb
+- lib/greenroom/census/run.rb
+- lib/greenroom/cli.rb
+- lib/greenroom/cli/check.rb
+- lib/greenroom/cli/judge.rb
+- lib/greenroom/digest.rb
+- lib/greenroom/experiment_behavior.rb
+- lib/greenroom/recorder.rb
+- lib/greenroom/reporter.rb
+- lib/greenroom/reporter/new_relic.rb
+- lib/greenroom/version.rb
+- sig/greenroom.rbs
+homepage: https://github.com/meganemura/greenroom
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/meganemura/greenroom
+  source_code_uri: https://github.com/meganemura/greenroom
+  changelog_uri: https://github.com/meganemura/greenroom/blob/main/gems/greenroom/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Judge a Scientist experiment by a nightly full-table census.
+test_files: []