dials 0.1.0

data/lib/dials/railtie.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Dials
+  # Present so future Rails integration points (rake tasks, reload hooks)
+  # have a home. Generators under lib/generators are discovered by Rails on
+  # their own; requiring the gem inside a Rails app is enough for
+  # `bin/rails generate dials:install` to work.
+  class Railtie < Rails::Railtie
+  end
+end

data/lib/dials/registry.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Dials
+  # The in-code catalog of every dial the application declares. A key's
+  # presence here is what makes it a dial at all: reads, writes, and scope
+  # validation all consult the registry, and an admin surface renders exactly
+  # these entries.
+  #
+  # Declarations accumulate across `Dials.define` blocks (so large apps can
+  # split declarations by domain), but a key declared twice raises — a dial's
+  # declaration is its single source of truth.
+  class Registry
+    include Enumerable
+
+    def initialize
+      @definitions = {}
+      @mutex = Mutex.new
+    end
+
+    # DSL entry point used by `Dials.define { dial ... }`. Registering a key
+    # also generates its per-dial methods (the Dials.<key> reader and the
+    # adjust_/clear_ writers);
+    # Generated.install! checks for name collisions before defining anything,
+    # so a raise here leaves neither a definition nor a stray method behind.
+    def dial(key, **)
+      definition = Definition.new(key, **)
+      @mutex.synchronize do
+        raise DuplicateDial, "dial #{definition.key} is already defined" if @definitions.key?(definition.key)
+
+        Generated.install!(definition)
+        @definitions[definition.key] = definition
+      end
+      definition
+    end
+
+    def fetch(key)
+      @definitions.fetch(key.to_sym) do
+        raise UnknownDial, "no dial defined for #{key.inspect} (defined: #{keys.join(', ')})"
+      end
+    end
+
+    def defined?(key)
+      @definitions.key?(key.to_sym)
+    end
+
+    def keys
+      @definitions.keys
+    end
+
+    def each(&)
+      @definitions.values.each(&)
+    end
+
+    def all
+      @definitions.values
+    end
+
+    # Test hook: wipe every declaration and its generated methods. Production
+    # code has no reason to call this; a registry that shrinks at runtime
+    # would strand stored rows.
+    def reset!
+      @mutex.synchronize do
+        @definitions.clear
+        Generated.uninstall_all!
+      end
+    end
+  end
+end

data/lib/dials/resolver.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Dials
+  # Resolution: scoped override → global override → code default.
+  #
+  # The matcher is deliberately more general than v1 needs. A stored scope
+  # matches a request when every pair it names is present in the request
+  # (subset match), and the most specific match — the one naming the most
+  # dimensions — wins, with ties broken by the dial's declared dimension
+  # order. Under the v1 write rule (stored scopes always name every declared
+  # dimension) this degenerates to exact-match-or-global, but relaxing the
+  # write rule later enables partial scopes ({market: "KE"} covering every
+  # platform) with no change here.
+  module Resolver
+    module_function
+
+    # `scope` is already normalized and validated. Returns the resolved value.
+    def resolve(definition, scope, snapshot)
+      stored = snapshot.scoped_overrides[definition.key]
+      if stored && !stored.empty? && !scope.empty?
+        match = best_match(definition, scope, stored)
+        return match[1] if match
+      end
+
+      snapshot.globals.fetch(definition.key) { definition.default }
+    end
+
+    def best_match(definition, scope, stored)
+      candidates = stored.filter_map do |canonical, value|
+        stored_scope = Scope.parse(canonical)
+        next unless stored_scope.all? { |name, v| scope[name] == v }
+
+        [stored_scope, value]
+      end
+      return nil if candidates.empty?
+
+      priority = definition.dimension_names.each_with_index.to_h
+      candidates.max_by do |stored_scope, _value|
+        # More named dimensions wins; among equals, earlier-declared
+        # dimensions outrank later ones (compared most-significant first).
+        [stored_scope.size, definition.dimension_names.map { |n| stored_scope.key?(n) ? priority.size - priority[n] : 0 }]
+      end
+    end
+  end
+end

data/lib/dials/schema.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module Dials
+  # A dial's value constraints, spoken in JSON Schema's vocabulary
+  # (snake_cased for Ruby): `enum`; `minimum` / `maximum` /
+  # `exclusive_minimum` / `exclusive_maximum` / `multiple_of` for numbers;
+  # `min_length` / `max_length` / `pattern` for strings; `properties` /
+  # `required` for :json objects (with `items` available inside nested array
+  # schemas). Borrowing the standard's words means no bespoke vocabulary
+  # decisions when the API grows, and constraints are declarative data an
+  # admin surface can render — see #to_json_schema. Rules a schema cannot
+  # express use the dial's `validate:` callable instead (see Definition).
+  #
+  # Nested schemas (inside properties/items) must declare a `type:` — the
+  # value checks are type-driven, and an untyped nested constraint would
+  # silently skip them (JSON Schema's "keywords ignore mismatched types" rule
+  # is exactly the footgun this gem's boot-time strictness exists to avoid).
+  # For the same reason, declaring `properties`/`required` on a :json dial
+  # pins its values to JSON objects.
+  class Schema
+    NUMERIC_KEYWORDS = %i[minimum maximum exclusive_minimum exclusive_maximum multiple_of].freeze
+    STRING_KEYWORDS = %i[min_length max_length pattern].freeze
+    OBJECT_KEYWORDS = %i[properties required].freeze
+
+    # Keywords a dial declaration may use, by dial type.
+    DIAL_KEYWORDS = {
+      boolean: [:enum].freeze,
+      integer: ([:enum] + NUMERIC_KEYWORDS).freeze,
+      float: ([:enum] + NUMERIC_KEYWORDS).freeze,
+      string: ([:enum] + STRING_KEYWORDS).freeze,
+      json: ([:enum] + OBJECT_KEYWORDS).freeze
+    }.freeze
+
+    # Types and keywords available inside nested schemas. These are JSON
+    # Schema's own type names (:number, :object, :array), not the dial types.
+    NESTED_KEYWORDS = {
+      boolean: [:enum].freeze,
+      integer: ([:enum] + NUMERIC_KEYWORDS).freeze,
+      number: ([:enum] + NUMERIC_KEYWORDS).freeze,
+      string: ([:enum] + STRING_KEYWORDS).freeze,
+      object: ([:enum] + OBJECT_KEYWORDS).freeze,
+      array: %i[enum items].freeze
+    }.freeze
+
+    TYPE_CHECKS = {
+      boolean: ["must be true or false", ->(v) { [true, false].include?(v) }].freeze,
+      integer: ["must be an integer", ->(v) { v.is_a?(Integer) }].freeze,
+      number: ["must be a number", ->(v) { v.is_a?(Integer) || v.is_a?(Float) }].freeze,
+      string: ["must be a string", ->(v) { v.is_a?(String) }].freeze,
+      object: ["must be a JSON object", ->(v) { v.is_a?(Hash) }].freeze,
+      array: ["must be an array", ->(v) { v.is_a?(Array) }].freeze
+    }.freeze
+
+    CAMEL = {
+      exclusive_minimum: "exclusiveMinimum", exclusive_maximum: "exclusiveMaximum",
+      multiple_of: "multipleOf", min_length: "minLength", max_length: "maxLength"
+    }.freeze
+
+    def initialize(key, type, constraints)
+      @key = key
+      @constraints = normalize!(constraints, allowed: DIAL_KEYWORDS.fetch(type), path: nil)
+      Freeze.deep(@constraints)
+      freeze
+    end
+
+    def empty?
+      @constraints.empty?
+    end
+
+    # True when the schema constrains :json values to objects
+    # (properties/required declared) — used for the emitted "type".
+    def object?
+      @constraints.key?(:properties) || @constraints.key?(:required)
+    end
+
+    # Validation problems for a type-checked value; [] when it conforms.
+    def problems_for(value)
+      problems(@constraints, value, nil)
+    end
+
+    # The constraints as a JSON Schema fragment (camelCase keywords, pattern
+    # as its regexp source). The dial's `validate:` callable, if any, is not
+    # representable here — that is the deal it offers.
+    def to_json_schema
+      render(@constraints)
+    end
+
+    private
+
+    # -- declaration-time normalization --------------------------------------
+
+    def normalize!(constraints, allowed:, path:)
+      if constraints.key?(:bounds)
+        boom(path, "bounds: was replaced by JSON Schema keywords " \
+                   "(minimum:/maximum:/enum:/pattern:/... — validate: for arbitrary rules)")
+      end
+
+      unknown = constraints.keys - allowed
+      unless unknown.empty?
+        boom(path, "unknown keyword#{'s' if unknown.size > 1} #{unknown.join(', ')} " \
+                   "(allows: #{allowed.join(', ')})")
+      end
+
+      constraints.to_h { |keyword, spec| [keyword, normalize_keyword!(keyword, spec, path)] }
+    end
+
+    def normalize_keyword!(keyword, spec, path)
+      case keyword
+      when :enum
+        boom(path, "enum must be a non-empty Array") unless spec.is_a?(Array) && !spec.empty?
+        spec.dup
+      when :minimum, :maximum, :exclusive_minimum, :exclusive_maximum
+        boom(path, "#{keyword} must be a number") unless spec.is_a?(Numeric)
+        spec
+      when :multiple_of
+        boom(path, "multiple_of must be a positive number") unless spec.is_a?(Numeric) && spec.positive?
+        spec
+      when :min_length, :max_length
+        boom(path, "#{keyword} must be a non-negative integer") unless spec.is_a?(Integer) && spec >= 0
+        spec
+      when :pattern then normalize_pattern!(spec, path)
+      when :properties then normalize_properties!(spec, path)
+      when :required then normalize_required!(spec, path)
+      when :items then normalize_nested!(spec, join(path, "items"))
+      end
+    end
+
+    def normalize_pattern!(spec, path)
+      case spec
+      when Regexp then spec
+      when String
+        begin
+          Regexp.new(spec)
+        rescue RegexpError => e
+          boom(path, "pattern is not a valid regexp (#{e.message})")
+        end
+      else
+        boom(path, "pattern must be a Regexp or String")
+      end
+    end
+
+    def normalize_properties!(spec, path)
+      boom(path, "properties must be a Hash of name => schema") unless spec.is_a?(Hash)
+
+      spec.to_h { |name, sub| [name.to_s, normalize_nested!(sub, join(path, name))] }
+    end
+
+    def normalize_required!(spec, path)
+      unless spec.is_a?(Array) && spec.all? { |k| k.is_a?(String) || k.is_a?(Symbol) }
+        boom(path, "required must be an Array of key names")
+      end
+      spec.map(&:to_s)
+    end
+
+    def normalize_nested!(spec, path)
+      boom(path, "schema must be a Hash") unless spec.is_a?(Hash)
+
+      spec = spec.transform_keys(&:to_sym)
+      type = spec[:type]&.to_sym
+      allowed = NESTED_KEYWORDS.fetch(type) do
+        boom(path, "schema needs a type: (one of #{NESTED_KEYWORDS.keys.join(', ')})")
+      end
+
+      { type: type }.merge(normalize!(spec.except(:type), allowed: allowed, path: path))
+    end
+
+    def join(path, name)
+      path ? "#{path}.#{name}" : name.to_s
+    end
+
+    def boom(path, message)
+      raise InvalidDefinition, ["#{@key}:", path, message].compact.join(" ")
+    end
+
+    # -- value validation -----------------------------------------------------
+
+    def problems(cons, value, path)
+      if cons[:type]
+        problem = type_problem(cons[:type], value)
+        return [at(path, problem)] if problem
+      elsif (cons.key?(:properties) || cons.key?(:required)) && !value.is_a?(Hash)
+        # Dial-level :json only; nested schemas carry an explicit type.
+        return [at(path, "must be a JSON object (its schema declares properties)")]
+      end
+
+      out = []
+      out << at(path, "must be one of #{cons[:enum].inspect}") if cons.key?(:enum) && !cons[:enum].include?(value)
+      out << at(path, "must be >= #{cons[:minimum]}") if cons.key?(:minimum) && value < cons[:minimum]
+      out << at(path, "must be <= #{cons[:maximum]}") if cons.key?(:maximum) && value > cons[:maximum]
+      if cons.key?(:exclusive_minimum) && value <= cons[:exclusive_minimum]
+        out << at(path, "must be > #{cons[:exclusive_minimum]}")
+      end
+      if cons.key?(:exclusive_maximum) && value >= cons[:exclusive_maximum]
+        out << at(path, "must be < #{cons[:exclusive_maximum]}")
+      end
+      if cons.key?(:multiple_of) && !(value % cons[:multiple_of]).zero?
+        out << at(path, "must be a multiple of #{cons[:multiple_of]}")
+      end
+      if cons.key?(:min_length) && value.length < cons[:min_length]
+        out << at(path, "must be at least #{cons[:min_length]} characters")
+      end
+      if cons.key?(:max_length) && value.length > cons[:max_length]
+        out << at(path, "must be at most #{cons[:max_length]} characters")
+      end
+      out << at(path, "must match #{cons[:pattern].inspect}") if cons.key?(:pattern) && !cons[:pattern].match?(value)
+
+      out.concat(object_problems(cons, value, path)) if value.is_a?(Hash)
+      if cons[:items] && value.is_a?(Array)
+        value.each_with_index { |element, i| out.concat(problems(cons[:items], element, "#{path}[#{i}]")) }
+      end
+      out
+    end
+
+    def object_problems(cons, value, path)
+      out = (cons[:required] || []).filter_map do |name|
+        at(path, "is missing required key #{name.inspect}") unless value.key?(name)
+      end
+      (cons[:properties] || {}).each do |name, sub|
+        out.concat(problems(sub, value[name], join(path, name))) if value.key?(name)
+      end
+      out
+    end
+
+    def type_problem(type, value)
+      message, check = TYPE_CHECKS.fetch(type)
+      message unless check.call(value)
+    end
+
+    def at(path, message)
+      path ? "#{path} #{message}" : message
+    end
+
+    # -- serialization --------------------------------------------------------
+
+    def render(cons)
+      cons.each_with_object({}) do |(keyword, spec), out|
+        case keyword
+        when :type then out["type"] = spec.to_s
+        when :pattern then out["pattern"] = spec.source
+        when :properties then out["properties"] = spec.transform_values { |sub| render(sub) }
+        when :items then out["items"] = render(spec)
+        else out[CAMEL.fetch(keyword, keyword.to_s)] = spec
+        end
+      end
+    end
+  end
+end

data/lib/dials/scope.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Dials
+  # Scope handling: validation against a dial's declared dimensions and a
+  # canonical string form for storage and lookup.
+  #
+  # The canonical form is a JSON object with sorted keys and string values —
+  # `{market: :KE}` and `{"market" => "KE"}` both canonicalize to
+  # `{"market":"KE"}` — so a scope written once can never be re-stored under a
+  # cosmetically different spelling. Uniqueness lives on (key, canonical
+  # scope) in whatever store persists it.
+  #
+  # v1 write rule: a scoped override names ALL of its dial's declared
+  # dimensions (exact scope). The matching code in Resolver is already
+  # general (subset match, most-specific wins), so partial scopes are a
+  # planned write-side relaxation, not a redesign. See docs/design.
+  module Scope
+    # The canonical encoding of the EMPTY scope — what Scope.canonical({})
+    # returns. Storage uses it as the scope of a global override: a global is
+    # simply the override that constrains no dimensions. This is the truthful
+    # encoding of a real value in the scope algebra, not a sentinel invented
+    # outside it.
+    GLOBAL = "{}"
+
+    module_function
+
+    # Normalize a caller-supplied scope hash into {symbol => string}. A hash
+    # naming the same dimension twice under different spellings
+    # ({"market" => "KE", market: "NG"}) is a caller bug — one value would
+    # silently win by insertion order — so it raises instead.
+    def normalize(scope)
+      scope ||= {}
+      normalized = scope.to_h { |k, v| [k.to_sym, v.to_s] }
+      if normalized.size != scope.size
+        raise InvalidScope, "scope names the same dimension more than once: #{scope.keys.inspect}"
+      end
+
+      normalized
+    end
+
+    # Stored canonical scopes land in an indexed VARCHAR(255); a longer
+    # string would fail (or truncate and collide) at the database on some
+    # adapters, so it fails validation here instead.
+    MAX_CANONICAL_BYTES = 255
+
+    # Canonical storage/lookup string for a normalized scope.
+    def canonical(scope)
+      result = JSON.generate(normalize(scope).sort.to_h { |k, v| [k.to_s, v] })
+      if result.bytesize > MAX_CANONICAL_BYTES
+        raise InvalidScope, "canonical scope exceeds #{MAX_CANONICAL_BYTES} bytes: #{result[0, 80]}…"
+      end
+
+      result
+    end
+
+    # Inverse of .canonical — used when loading stored rows. A stored scope
+    # that is valid JSON but not an object ("42", "[]") is corrupt data, not
+    # a scope; raising InvalidScope lets loaders quarantine the row.
+    def parse(canonical_string)
+      parsed = JSON.parse(canonical_string)
+      raise InvalidScope, "stored scope is not a JSON object: #{canonical_string.inspect}" unless parsed.is_a?(Hash)
+
+      parsed.to_h { |k, v| [k.to_sym, v] }
+    end
+
+    # Validate a scope against a definition. `exact:` requires every declared
+    # dimension to be present (the v1 rule for both reads and writes);
+    # without it, any subset of declared dimensions passes (the future
+    # partial-scope rule). Raises InvalidScope; returns the normalized hash.
+    def validate!(definition, scope, exact: true)
+      normalized = normalize(scope)
+
+      if definition.dimensions.empty?
+        return normalized if normalized.empty?
+
+        raise InvalidScope, "dial #{definition.key} declares no dimensions; scope #{normalized.inspect} is not allowed"
+      end
+
+      declared = definition.dimensions.to_h { |d| [d.name, d] }
+
+      normalized.each_key do |name|
+        next if declared.key?(name)
+
+        raise InvalidScope, "dial #{definition.key} has no dimension #{name} (declares: #{declared.keys.join(', ')})"
+      end
+
+      if exact
+        missing = declared.keys - normalized.keys
+        unless missing.empty?
+          raise InvalidScope, "dial #{definition.key} requires scope for: #{missing.join(', ')}"
+        end
+      end
+
+      normalized.each do |name, value|
+        dimension = declared.fetch(name)
+        next if dimension.valid_value?(value)
+
+        raise InvalidScope, "#{value.inspect} is not a valid #{name} for dial #{definition.key}"
+      end
+
+      normalized
+    end
+  end
+end

data/lib/dials/snapshot.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Dials
+  # An immutable point-in-time copy of every stored override.
+  #
+  #   globals::    { key(Symbol) => value } — only dials with a stored global
+  #                override appear; absence means "inherit the code default".
+  #   scoped_overrides:: { key(Symbol) => { canonical_scope(String) => value } }
+  #   row_versions:: { key(Symbol) => { canonical_scope(String) => Integer } }
+  #                — the per-override version stamps (the global's under
+  #                Scope::GLOBAL), for stale-write tokens.
+  #   version::    the store's monotonic write counter at load time.
+  #
+  # Values are deep-frozen: reads hand out references into the shared
+  # snapshot, and a caller mutating a returned :json value must not be able
+  # to corrupt what every other thread reads.
+  class Snapshot
+    attr_reader :globals, :scoped_overrides, :row_versions, :version
+
+    def initialize(globals:, scoped_overrides:, version:, row_versions: {})
+      @globals = Freeze.deep(globals)
+      @scoped_overrides = Freeze.deep(scoped_overrides)
+      @row_versions = Freeze.deep(row_versions)
+      @version = version
+      freeze
+    end
+  end
+
+  Snapshot::EMPTY = Snapshot.new(globals: {}, scoped_overrides: {}, version: 0)
+end

data/lib/dials/store_version.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Dials
+  # Per-override version tokens (opaque frozen Strings, safe to round-trip
+  # through JSON, HTML forms, and HTTP params). Every stored override row
+  # carries a version stamped from its last change-log entry — monotonic
+  # across the whole store, so a row deleted and re-created can never revisit
+  # an old version (no ABA). "No override" has the well-known token ABSENT.
+  #
+  # Callers obtain tokens from Dials.overview (or as the return value of a
+  # write that carried `expected_version:`) and echo them back on writes —
+  # they never construct or parse one, so the representation stays free to
+  # change. Comparison is plain string equality; a token from a different
+  # store shape (or garbage) simply never matches and surfaces as StaleWrite,
+  # the safe direction.
+  module StoreVersion
+    module_function
+
+    def token(raw)
+      JSON.generate(raw).freeze
+    end
+
+    # The token of an override stream that has NEVER been written. A cleared
+    # override is not ABSENT — its tombstone keeps a stamp (handed out by
+    # Dials.overview), so "absent because cleared" and "absent because never
+    # written" can never be confused, and an old ABSENT token goes stale the
+    # moment any write touches the stream.
+    #
+    # A token minted by a write inside a database transaction that later
+    # ROLLS BACK is void — it describes a write that never happened; discard
+    # it with the rest of the transaction's effects.
+    ABSENT = token(0)
+  end
+end