lucerna 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bf8a610323ba01503dfe245ea129a8cdedfc2d9e916977fd34ce7cc1c85d04d3
+  data.tar.gz: 9c4c0c931b3bc9326a696d849873cd0741d546194eacdd4d038152e994bdb168
+SHA512:
+  metadata.gz: d3cedc4e00127c55d42fb9436acb15570d38f206f1aa2d2cce1c578fdf691a713b19d6940164b2bf35de6c012550b9894f432ca275027d7f74bf68825b7e6a59
+  data.tar.gz: 25c3407e10189105c8cbf1f37ac7b4513303308e669fcfed5409c24a949f913c273c36c1ac1684d3d8d186c25e528a0e7596d96821a07a00297b5510408926cc

data/README.md

@@ -0,0 +1,88 @@
+# lucerna
+
+Server-side Lucerna SDK for Ruby: local **Gates** evaluation (feature flags, experiments, kill switches) with a background runtime poll, and fire-and-forget **Identity** delivery into People. Pure Ruby, zero runtime dependencies, Ruby >= 3.2. Works in any Ruby process — Rails (a Railtie is included), Sinatra, Sidekiq, plain scripts.
+
+It takes a **server key** (`ck_srv_…` or `ck_key_…`). A publishable browser key (`ck_client_…`) cannot download gates rules and is rejected at construction. Never put a server key in code that ships to a client.
+
+This is the Ruby sibling of `@lucerna-dev/gates-node` + `@lucerna-dev/identity`: same wire protocol, same frozen bucketing contract, same golden vectors.
+
+## Install
+
+Not yet published to RubyGems — point Bundler at the monorepo:
+
+```ruby
+gem "lucerna", path: "../lucerna/sdks/ruby"
+```
+
+## Quickstart
+
+```ruby
+require "lucerna"
+
+Lucerna.configure do |config|
+  config.server_key = ENV["LUCERNA_SERVER_KEY"] # ck_srv_… or ck_key_…, never ck_client_…
+end
+
+# One identity per request feeds both products.
+identity = Lucerna::Identity.new(
+  user_id: "u_42",         # pseudonymous app id — never an email
+  email: "sofia@acme.com", # PII: first-class field, only identify transmits it
+  traits: { plan: "pro" },
+)
+
+Lucerna.gates.wait_until_ready(timeout: 5) # optional — reads are safe before ready
+
+enabled = Lucerna.gates.flag("new_billing", identity)       # => true / false
+variant = Lucerna.gates.experiment("checkout_v2", identity) # => "treatment", … or nil
+healthy = Lucerna.gates.switch("payments")                  # => false means killed
+
+Lucerna.identity.identify(identity) # fire-and-forget upsert into People
+```
+
+In Rails, put the `Lucerna.configure` block in `config/initializers/lucerna.rb`. The Railtie defaults `Lucerna.config.logger` to `Rails.logger`.
+
+## Documentation
+
+- [Getting started](docs/getting-started.md)
+- [Reference](docs/references.md) — every option, method, contract, error
+
+## API
+
+| Export                           | Signature                                       | What it does                                                           |
+| -------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------- |
+| `Lucerna.configure`              | `{ \|config\| … }`                              | Set config before first use. Raises if a client was already built.     |
+| `Lucerna.gates`                  | → `Gates::Client`                               | Lazy singleton, built from config on first access.                     |
+| `Lucerna.identity`               | → `Identity::Client`                            | Lazy singleton for identify delivery.                                  |
+| `Lucerna.close`                  | `(timeout: 2)`                                  | Stop polling/delivery, flush queues. Also runs via `at_exit`.          |
+| `Lucerna.restart`                |                                                 | Abandon clients after a fork (`on_worker_boot`); next access rebuilds. |
+| `Lucerna::Identity.new`          | `(user_id:, email: nil, name: nil, traits: {})` | Immutable identity value; validates strictly.                          |
+| `Gates::Client#flag`             | `(key, identity = nil)` → bool                  | Flag decision. Unknown key / pre-load: `false`.                        |
+| `Gates::Client#experiment`       | `(key, identity = nil)` → String?               | Variant name or `nil`. The only exposure-recording read.               |
+| `Gates::Client#switch`           | `(key)` → bool                                  | Kill switch. `false` means killed. Unknown: `true`.                    |
+| `Gates::Client#evaluate`         | `(identity = nil)` → Hash                       | All decisions (SSR/bootstrap). No exposures.                           |
+| `Gates::Client#inspect_gate`     | `(key, identity = nil)` → Hash                  | Decision + rule-by-rule trace. No exposures.                           |
+| `Gates::Client#wait_until_ready` | `(timeout: nil)` → bool                         | True after first load; raises `AuthError` on 401/403.                  |
+| `Gates::Client#close`            | `(timeout: 2)`                                  | Stop the poll, flush exposures. Stale reads keep answering.            |
+| `Identity::Client#identify`      | `(identity)` or kwargs                          | Validates, enqueues, returns immediately.                              |
+| `Identity::Client#flush`         | `(timeout: 2)` → bool                           | Block until queued identifies were attempted.                          |
+
+Anywhere an identity is accepted: a `Lucerna::Identity`, a `{ user_id:, email:, traits: }` hash, or `nil` (anonymous).
+
+## Guarantees & semantics
+
+- **Gate decisions are UX hints, never authorization.** Anything entitlement-shaped is re-checked server-side.
+- **Reads never raise** and fail open: flag → `false`, experiment → `nil`, switch → `true` (not killed). Last-known beats default — stale beats default, default beats crash.
+- **Bucketing is frozen**: murmur3 (x86 32-bit) over `"#{salt}:#{unit_id}"`, basis points (`hash % 10000`), stored salts. Renaming a key never reshuffles users. The golden vectors in `sdks/core/src/vectors.json` are the append-only cross-language contract and run in this gem's test suite.
+- **Startup download + 10s ETag poll** — kill switches propagate in ≤10s (poll) + ≤10s (server cache). The runtime swap is atomic: readers see the whole old or whole new document, never a torn one.
+- **Exposure-on-read**: only `experiment()` records, only when a variant was assigned to a known user. Deduped locally (10 min), batched (≤100/request), delivered on the poll tick, flushed on close. `track_exposures: false` opts out.
+- **Unknown rule elements fail safe**: a gate carrying an operator or override kind this version doesn't know answers whole with `unsupported_rule` — flag off, experiment unassigned.
+- **Fork-safe**: after `Process.fork` (Puma cluster, Unicorn, Sidekiq), the first read detects the dead poller and respawns it, starting warm from the inherited runtime; inherited exposure/identify backlogs are dropped, never replayed. `Lucerna.restart` in `on_worker_boot` / `after_fork` is optional and merely avoids the first-read latency blip.
+- **PII discipline**: `user_id` is a pseudonymous app id. `email` / `name` are first-class fields — never traits — and only `identify` transmits them. Gates evaluation is local and transmits nothing; exposure events carry only the `user_id`.
+
+## Errors & failure modes
+
+- `wait_until_ready` returns `true` on first successful load, `false` on timeout, and raises `Lucerna::AuthError` if the first settle was a 401/403 (bad key — discoverable, and sticky). The poll continues regardless: a key fixed later recovers reads without a restart.
+- Network errors and 5xx retry inside a fetch (3 attempts, jittered backoff), then the poll retries every interval. Any 4xx is a stable answer and fails the attempt immediately.
+- All background failures route to `config.on_error` (or `config.logger` at `warn`). A raising `on_error` is swallowed — it can never take down a read or a worker thread.
+- `identify` raises `ArgumentError` on invalid input (programming error); delivery never raises — one attempt, no retry, because the server upserts idempotently and the next identify is the retry.
+- A runtime document with a newer `schemaVersion` is rejected (upgrade the gem); the current runtime keeps answering.

data/lib/lucerna/config.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Lucerna
+  # Configuration for the module-level singletons. Set via
+  # Lucerna.configure before the first use of Lucerna.gates /
+  # Lucerna.identity.
+  class Config
+    # Required for Lucerna.gates: a server key (ck_srv_… / ck_key_…).
+    attr_accessor :server_key
+    # Defaults to https://api.uselucerna.app.
+    attr_accessor :base_url
+    # Runtime poll cadence in seconds. Default 10, floored at 1.
+    attr_accessor :refresh_interval
+    # Per-request timeout in seconds. Default 5.
+    attr_accessor :request_timeout
+    # callable(Error) — failures from polling and delivery. Reads never raise.
+    attr_accessor :on_error
+    # Used at :warn when on_error is not set. The Railtie defaults this to
+    # Rails.logger.
+    attr_accessor :logger
+    # Record experiment exposures on variant reads. Default true.
+    attr_accessor :track_exposures
+    # Key for Lucerna.identity; defaults to server_key. Any key granted
+    # people:identify works.
+    attr_accessor :identity_key
+    # Injectable transport (test seam): responds to call(request, timeout:).
+    attr_accessor :transport
+    # Warm Lucerna.gates after Rails boot instead of on first read.
+    # Default false — lazy init is fork-safe by construction.
+    attr_accessor :eager_init
+
+    def initialize
+      @track_exposures = true
+      @eager_init = false
+    end
+  end
+end

data/lib/lucerna/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Lucerna
+  class Error < StandardError; end
+
+  # A transport or API failure. +status+ is nil for network-level failures
+  # (timeout, refused connection), the HTTP status otherwise.
+  class RequestError < Error
+    attr_reader :status
+
+    def initialize(message, status: nil)
+      super(message)
+      @status = status
+    end
+  end
+
+  # 401/403 — the key is unknown, revoked, or lacks the required grant.
+  class AuthError < RequestError; end
+end

data/lib/lucerna/gates/client.rb

@@ -0,0 +1,355 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "../errors"
+require_relative "../http"
+require_relative "../reporting"
+require_relative "../traits"
+require_relative "../version"
+require_relative "evaluate"
+require_relative "exposures"
+require_relative "runtime"
+
+module Lucerna
+  module Gates
+    # The Gates server client: polls the compiled runtime in a background
+    # thread and evaluates locally. Mirrors @lucerna/gates-node
+    # (sdks/node/src/client.ts).
+    #
+    # Guarantees:
+    # - Reads never raise. Before the first load (or through sustained
+    #   failure) they answer safe defaults: flag false, experiment nil,
+    #   switch true, evaluate empty. Stale beats default, default beats
+    #   crash.
+    # - The runtime swap is atomic — readers see the whole old or the
+    #   whole new document, never a torn one.
+    # - Exposures are recorded on variant reads only, delivered on the
+    #   poll tick, and are always best-effort.
+    # - Survives fork: reads in a forked child detect the dead poller and
+    #   respawn it, starting warm from the inherited runtime.
+    class Client
+      DEFAULT_BASE_URL = "https://api.uselucerna.app"
+      DEFAULT_REFRESH_INTERVAL = 10.0
+      MIN_REFRESH_INTERVAL = 1.0
+      DEFAULT_REQUEST_TIMEOUT = 5.0
+
+      def initialize(server_key:, base_url: nil, refresh_interval: nil, request_timeout: nil,
+        on_error: nil, logger: nil, track_exposures: true, transport: nil, sleeper: nil,
+        background: true)
+        raise ArgumentError, "server_key is required" if server_key.nil? || server_key.to_s.empty?
+        if server_key.start_with?("ck_client_")
+          raise ArgumentError,
+            "ck_client_… is a publishable browser key and cannot download gates rules — " \
+            "use a server key (ck_srv_… or ck_key_…) from your environment settings"
+        end
+
+        @base_url = (base_url || DEFAULT_BASE_URL).sub(%r{/+\z}, "")
+        @refresh_interval = [(refresh_interval || DEFAULT_REFRESH_INTERVAL).to_f, MIN_REFRESH_INTERVAL].max
+        @request_timeout = (request_timeout || DEFAULT_REQUEST_TIMEOUT).to_f
+        @reporter = Reporting.reporter(on_error, logger)
+        @transport = transport || HTTP::NetHttpTransport.new
+        @sleeper = sleeper || HTTP::DEFAULT_SLEEPER
+        @headers = {
+          "Authorization" => "Bearer #{server_key}",
+          "Accept" => "application/json",
+          "x-lucerna-sdk" => SDK_IDENTITY,
+        }.freeze
+        @background = background
+
+        @runtime = nil
+        @etag = nil
+        @closed = false
+        @poller = nil
+        @pid = Process.pid
+
+        @lifecycle_mutex = Mutex.new
+        @wakeup = ConditionVariable.new
+        @ready_mutex = Mutex.new
+        @ready_cv = ConditionVariable.new
+        @ready_state = :pending
+        @ready_error = nil
+
+        @exposures =
+          if track_exposures
+            Exposures.new(
+              url: "#{@base_url}/sdk/v1/events",
+              headers: @headers,
+              transport: @transport,
+              timeout: @request_timeout,
+              on_error: @reporter,
+            )
+          end
+
+        start_poller if @background
+      end
+
+      # Blocks until the first runtime load succeeds (true), the timeout
+      # elapses (false), or the first settle was a 401/403 (raises
+      # AuthError — a bad key should be discoverable, exactly like the
+      # node ready() rejection). Optional to call: reads are safe before
+      # ready. Network errors and 5xx keep waiting — polling retries them.
+      def wait_until_ready(timeout: nil)
+        deadline = timeout && monotonic_now + timeout
+        @ready_mutex.synchronize do
+          loop do
+            case @ready_state
+            when :ready then return true
+            when :auth_failed then raise @ready_error
+            end
+            remaining = deadline && deadline - monotonic_now
+            return false if remaining && remaining <= 0
+
+            @ready_cv.wait(@ready_mutex, remaining)
+          end
+        end
+      end
+
+      # The flag's decision for this identity. Unknown key or no runtime
+      # yet: false.
+      def flag(key, identity = nil)
+        safe_read(false) do |runtime|
+          config = runtime["flags"][key]
+          next false unless config
+
+          user_id, traits = resolve_identity(identity)
+          Evaluate.flag(config, user_id: user_id, traits: traits)[:on]
+        end
+      end
+
+      # The assigned variant name, or nil (not assigned / unknown key / no
+      # runtime yet). This is the only read that records an exposure — and
+      # only when a variant was assigned to a known user.
+      def experiment(key, identity = nil)
+        safe_read(nil) do |runtime|
+          config = runtime["experiments"][key]
+          next nil unless config
+
+          user_id, traits = resolve_identity(identity)
+          assignment = Evaluate.experiment(config, runtime["audiences"], user_id: user_id, traits: traits)
+          variant = assignment[:variant]
+          record_exposure(key, assignment, user_id) if variant && user_id && !user_id.empty?
+          variant && variant[:name]
+        end
+      end
+
+      # Kill switch state — false means the guarded path IS killed.
+      # Unknown key or no runtime yet: true (not killed).
+      def switch(key)
+        safe_read(true) do |runtime|
+          state = runtime["kills"][key]
+          state.nil? ? true : state
+        end
+      end
+
+      # Debug projection of one key across all three gate kinds, with the
+      # rule-by-rule trail. Never records exposures.
+      def inspect_gate(key, identity = nil)
+        safe_read({ key: key, loaded: false }) do |runtime|
+          user_id, traits = resolve_identity(identity)
+          result = { key: key, loaded: true }
+
+          kill = runtime["kills"][key]
+          result[:kill] = kill unless kill.nil?
+
+          if (config = runtime["flags"][key])
+            trace = []
+            decision = Evaluate.flag(config, user_id: user_id, traits: traits, trace: trace)
+            result[:flag] = { decision: decision, trace: trace }
+          end
+
+          if (config = runtime["experiments"][key])
+            trace = []
+            assignment = Evaluate.experiment(
+              config, runtime["audiences"], user_id: user_id, traits: traits, trace: trace,
+            )
+            result[:experiment] = { assignment: assignment, trace: trace }
+          end
+
+          result
+        end
+      end
+
+      # One identity's decisions over the entire runtime — for SSR or
+      # bootstrapping a client. Never records exposures.
+      def evaluate(identity = nil)
+        safe_read({ kills: {}, flags: {}, experiments: {} }) do |runtime|
+          user_id, traits = resolve_identity(identity)
+          Evaluate.all(runtime, user_id: user_id, traits: traits)
+        end
+      end
+
+      # The last-known compiled runtime document (wire shape), or nil.
+      def runtime
+        ensure_live!
+        @runtime
+      end
+
+      # Stops the poll and flushes queued exposures. Reads keep answering
+      # from the last-known runtime.
+      def close(timeout: 2)
+        poller = @lifecycle_mutex.synchronize do
+          @closed = true
+          @wakeup.broadcast
+          @poller
+        end
+        poller&.join(timeout)
+        @exposures&.flush
+        nil
+      end
+
+      def closed?
+        @lifecycle_mutex.synchronize { @closed }
+      end
+
+      private
+
+      # -- reads ----------------------------------------------------------
+
+      def safe_read(fallback)
+        ensure_live!
+        snapshot = @runtime
+        return fallback if snapshot.nil?
+
+        begin
+          yield snapshot
+        rescue StandardError => error
+          @reporter.call(error)
+          fallback
+        end
+      end
+
+      # Accepts nil (anonymous), anything responding to #for_gates
+      # (Lucerna::Identity), or a hash with user_id/traits/email keys.
+      # Lenient by design — reads never raise.
+      def resolve_identity(identity)
+        return [nil, {}] if identity.nil?
+
+        if identity.respond_to?(:for_gates)
+          projection = identity.for_gates
+          return [projection[:user_id], projection[:traits]]
+        end
+
+        if identity.is_a?(Hash)
+          user_id = identity[:user_id] || identity["user_id"]
+          traits = Traits.normalize(identity[:traits] || identity["traits"])
+          email = identity[:email] || identity["email"]
+          traits["email"] = email.to_s if email && !traits.key?("email")
+          return [user_id&.to_s, traits]
+        end
+
+        [nil, {}]
+      end
+
+      def record_exposure(key, assignment, user_id)
+        return unless @exposures
+
+        variant = assignment[:variant]
+        hint = @exposures.record(
+          "type" => "exposure",
+          "experimentKey" => key,
+          "iteration" => assignment[:iteration],
+          "userId" => user_id,
+          "variantId" => variant[:id],
+          "variantName" => variant[:name],
+        )
+        wake_poller if hint
+      end
+
+      # -- polling --------------------------------------------------------
+
+      def start_poller
+        @pid = Process.pid
+        @poller = Thread.new { poll_loop }
+        @poller.name = "lucerna-gates-poller"
+      end
+
+      def poll_loop
+        loop do
+          refresh_once
+          flush_exposures
+          @lifecycle_mutex.synchronize do
+            return if @closed
+
+            @wakeup.wait(@lifecycle_mutex, @refresh_interval)
+            return if @closed
+          end
+        end
+      end
+
+      # One conditional fetch of the runtime. Rescues everything: errors
+      # report through on_error and the current runtime keeps answering.
+      # A 401/403 before the first success settles the ready gate as
+      # auth-failed (sticky) — but polling continues, so a key re-enabled
+      # later starts working without a restart.
+      def refresh_once
+        etag = @etag
+        headers = etag ? @headers.merge("If-None-Match" => etag) : @headers
+        request = HTTP::Request.new(:get, "#{@base_url}/sdk/v1/gates/runtime", headers, nil)
+
+        response = HTTP.with_retry(sleeper: @sleeper) { @transport.call(request, timeout: @request_timeout) }
+        return if response.status == 304
+
+        document = JSON.parse(response.body)
+        unless Runtime.acceptable?(document)
+          raise RequestError, "runtime document is not usable by this SDK version — upgrade the lucerna gem"
+        end
+
+        @lifecycle_mutex.synchronize do
+          @runtime = document
+          @etag = response.headers["etag"]
+        end
+        settle_ready(:ready)
+      rescue StandardError => error
+        @reporter.call(error)
+        settle_ready(:auth_failed, error) if error.is_a?(AuthError)
+      end
+
+      def flush_exposures
+        @exposures&.flush
+      rescue StandardError => error
+        @reporter.call(error)
+      end
+
+      def settle_ready(state, error = nil)
+        @ready_mutex.synchronize do
+          return unless @ready_state == :pending
+
+          @ready_state = state
+          @ready_error = error
+          @ready_cv.broadcast
+        end
+      end
+
+      def wake_poller
+        @lifecycle_mutex.synchronize { @wakeup.broadcast }
+      end
+
+      # -- fork / thread liveness -----------------------------------------
+
+      # Fast path: same process, live poller (or deliberately not running).
+      # After a fork the inherited poller thread doesn't exist in the
+      # child: keep the runtime (start warm), drop the inherited exposure
+      # queue (N workers must not replay the parent's backlog), respawn.
+      def ensure_live!
+        return unless @background
+        return if @closed
+        return if Process.pid == @pid && @poller&.alive?
+
+        @lifecycle_mutex.synchronize do
+          return if @closed
+          return if Process.pid == @pid && @poller&.alive?
+
+          @exposures&.clear if Process.pid != @pid
+          start_poller
+        end
+      end
+
+      # -- misc -----------------------------------------------------------
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end