lucerna 0.1.0

data/lib/lucerna/identity/client.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "../errors"
+require_relative "../http"
+require_relative "../reporting"
+require_relative "../version"
+
+module Lucerna
+  class Identity
+    # Fire-and-forget delivery of identify calls to People
+    # (POST /sdk/v1/people/identify). Mirrors the wire behavior of
+    # @lucerna/identity's sync layer, adapted to a server process: a
+    # bounded queue drained by one lazy background worker replaces the JS
+    # microtask, and flush/close exist because Ruby processes don't drain
+    # a microtask queue on exit.
+    #
+    # identify validates strictly (bad input is a programming error and
+    # fails loud); delivery never raises into the caller — failures report
+    # through on_error, and the server's idempotent upsert makes the next
+    # identify the retry.
+    class Client
+      DEFAULT_BASE_URL = "https://api.uselucerna.app"
+      DEFAULT_REQUEST_TIMEOUT = 5.0
+      DEFAULT_MAX_QUEUE = 1000
+
+      def initialize(api_key:, base_url: nil, request_timeout: nil, on_error: nil, logger: nil,
+        transport: nil, max_queue: DEFAULT_MAX_QUEUE, background: true)
+        raise ArgumentError, "api_key is required" if api_key.nil? || api_key.to_s.empty?
+
+        @url = "#{(base_url || DEFAULT_BASE_URL).sub(%r{/+\z}, "")}/sdk/v1/people/identify"
+        @request_timeout = (request_timeout || DEFAULT_REQUEST_TIMEOUT).to_f
+        @reporter = Reporting.reporter(on_error, logger)
+        @transport = transport || HTTP::NetHttpTransport.new
+        @max_queue = max_queue
+        @background = background
+        @headers = {
+          "Authorization" => "Bearer #{api_key}",
+          "Content-Type" => "application/json",
+          "x-lucerna-sdk" => SDK_IDENTITY,
+        }.freeze
+
+        @queue = Thread::Queue.new
+        @worker = nil
+        @pid = Process.pid
+        @lifecycle_mutex = Mutex.new
+        @last_sent = nil # worker-thread-private after spawn
+      end
+
+      # Accepts a Lucerna::Identity, a hash form, or the same keywords as
+      # Identity.new. Never blocks the caller: past max_queue the event is
+      # dropped and reported instead of applying backpressure.
+      def identify(identity = nil, **kwargs)
+        identity = identity.nil? && !kwargs.empty? ? Identity.new(**kwargs) : Identity.wrap(identity)
+        raise ArgumentError, "identify requires an identity" if identity.nil?
+
+        payload = JSON.generate(identity.to_payload)
+        if @queue.size >= @max_queue
+          @reporter.call(Error.new("identity queue full — dropped identify for #{identity.user_id}"))
+          return nil
+        end
+
+        if @background
+          # Fork guard first: in a freshly forked child it clears the
+          # inherited backlog — the enqueue below must survive that.
+          ensure_worker
+          @queue << payload
+        else
+          @queue << payload
+          drain_now # test seam: deliveries run synchronously on the caller
+        end
+        nil
+      end
+
+      # Blocks until everything queued before the call has been attempted,
+      # or the timeout elapses. Returns true when drained.
+      def flush(timeout: 2)
+        return true unless @background && @worker&.alive?
+
+        ack = Thread::Queue.new
+        @queue << [:flush, ack]
+        !ack.pop(timeout: timeout).nil?
+      end
+
+      # Flushes, then stops the worker. The client stays usable — the next
+      # identify re-arms it.
+      def close(timeout: 2)
+        drained = flush(timeout: timeout)
+        worker = @lifecycle_mutex.synchronize { @worker }
+        if worker&.alive?
+          @queue << :stop
+          worker.join(1)
+        end
+        drained
+      end
+
+      private
+
+      # Lazy worker spawn, fork-guarded: a forked child inherits the queue
+      # contents but not the thread; it must not replay the parent's
+      # backlog (N workers × the same events).
+      def ensure_worker
+        return if Process.pid == @pid && @worker&.alive?
+
+        @lifecycle_mutex.synchronize do
+          return if Process.pid == @pid && @worker&.alive?
+
+          if Process.pid != @pid
+            @queue.clear
+            @pid = Process.pid
+          end
+          @worker = Thread.new { work_loop }
+          @worker.name = "lucerna-identity-worker"
+        end
+      end
+
+      def work_loop
+        loop do
+          item = @queue.pop
+          case item
+          when :stop then return
+          when Array then item[1] << true if item[0] == :flush
+          else deliver(item)
+          end
+        end
+      end
+
+      def drain_now
+        until @queue.empty?
+          item = @queue.pop(true)
+          deliver(item) if item.is_a?(String)
+        end
+      rescue ThreadError
+        nil
+      end
+
+      # One attempt, no retry: the server upserts idempotently and the
+      # next identify is the retry. A resend of the exact previous
+      # successful payload is skipped (lastSent dedupe, sync.ts parity) —
+      # a failed send leaves lastSent unchanged so the retry goes through.
+      def deliver(payload)
+        return if payload == @last_sent
+
+        request = HTTP::Request.new(:post, @url, @headers, payload)
+        response = @transport.call(request, timeout: @request_timeout)
+        if (200..299).cover?(response.status)
+          @last_sent = payload
+        else
+          @reporter.call(
+            RequestError.new("identity sync failed with status #{response.status}", status: response.status),
+          )
+        end
+      rescue StandardError => error
+        @reporter.call(RequestError.new("#{error.class}: #{error.message}"))
+      end
+    end
+  end
+end

data/lib/lucerna/identity.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "traits"
+
+module Lucerna
+  # The shared "who is the user" primitive — one immutable value, built
+  # once per request, that feeds both products: gates reads take it
+  # positionally, Lucerna.identity.identify sends it to People. Mirrors
+  # GatesIdentity / identity.current() in the JS SDKs.
+  #
+  # PII rules: user_id is a pseudonymous app id ("u_42"), never an email.
+  # email and name are first-class fields — never traits — and are only
+  # ever transmitted by identify, which routes them to People's encrypted
+  # columns. Traits are plaintext targeting data.
+  class Identity
+    attr_reader :user_id, :email, :name, :traits
+
+    def initialize(user_id:, email: nil, name: nil, traits: {})
+      unless user_id.is_a?(String) && !user_id.empty?
+        raise ArgumentError, "user_id must be a non-empty String (got #{user_id.inspect})"
+      end
+
+      @user_id = -user_id
+      @email = email&.to_s
+      @name = name&.to_s
+      @traits = Traits.normalize!(traits).freeze
+      freeze
+    end
+
+    # Coerces the accepted identity forms — Identity, Hash, nil — into an
+    # Identity (or nil for anonymous). Strict: bad input is a programming
+    # error. Gates reads have their own lenient path and never raise.
+    def self.wrap(value)
+      case value
+      when nil then nil
+      when Identity then value
+      when Hash
+        new(
+          user_id: value[:user_id] || value["user_id"],
+          email: value[:email] || value["email"],
+          name: value[:name] || value["name"],
+          traits: value[:traits] || value["traits"] || {},
+        )
+      else
+        raise ArgumentError, "expected a Lucerna::Identity, Hash, or nil (got #{value.class})"
+      end
+    end
+
+    # Projection for gates evaluation: user id + traits, with the
+    # first-class email merged in as a trait fallback so the engine's
+    # email→domain derivation makes domain overrides work. Purely local —
+    # gates evaluation transmits nothing; only identify sends PII.
+    def for_gates
+      traits = @traits
+      traits = traits.merge("email" => @email) if @email && !traits.key?("email")
+      { user_id: @user_id, traits: traits }
+    end
+
+    # Wire payload for POST /sdk/v1/people/identify. Note the rename:
+    # local user_id -> wire appUserId. email/name keys are omitted
+    # entirely when absent; traits are always present.
+    def to_payload
+      payload = { "appUserId" => @user_id }
+      payload["email"] = @email if @email
+      payload["name"] = @name if @name
+      payload["traits"] = @traits
+      payload
+    end
+  end
+end
+
+require_relative "identity/client"

data/lib/lucerna/railtie.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Lucerna
+  # Thin Rails integration — deliberately two hooks and nothing else.
+  # Everything that matters (at_exit flush, fork recovery, lazy singleton
+  # construction) lives in the core and works without Rails.
+  class Railtie < ::Rails::Railtie
+    # Runs after config/initializers/lucerna.rb has called
+    # Lucerna.configure; fills the logger only when the app didn't set one.
+    initializer "lucerna.defaults", after: :load_config_initializers do
+      Lucerna.config.logger ||= ::Rails.logger
+    end
+
+    # Warm the gates runtime before the first request instead of on the
+    # first read. Off by default: lazy init is fork-safe by construction,
+    # and eager threads in a preloading master are wasted work the PID
+    # guard would just redo in each worker.
+    config.after_initialize do
+      Lucerna.gates if Lucerna.config.eager_init && Lucerna.config.server_key
+    end
+  end
+end

data/lib/lucerna/reporting.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Lucerna
+  module Reporting
+    module_function
+
+    # Wraps on_error / logger into an always-callable reporter. A raising
+    # handler must never take down a read, the poller, or a worker thread.
+    def reporter(on_error, logger)
+      handler =
+        if on_error
+          on_error
+        elsif logger
+          ->(error) { logger.warn("[lucerna] #{error.class}: #{error.message}") }
+        end
+      lambda do |error|
+        handler&.call(error)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/lucerna/traits.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Lucerna
+  # Trait normalization. Traits are always Record<string, string> on the
+  # wire and in the engine — stringification happens at the boundary.
+  module Traits
+    module_function
+
+    # Strict normalization for Identity construction / identify: bad input
+    # is a programming error and fails loud.
+    def normalize!(traits)
+      raise ArgumentError, "traits must be a Hash (got #{traits.class})" unless traits.is_a?(Hash)
+
+      traits.each_with_object({}) do |(key, value), out|
+        unless value.is_a?(String) || value.is_a?(Symbol) || value.is_a?(Numeric) ||
+            value.equal?(true) || value.equal?(false)
+          raise ArgumentError,
+            "trait #{key.inspect} must be a String, Symbol, Numeric, or boolean (got #{value.class})"
+        end
+        out[key.to_s] = value.to_s
+      end
+    end
+
+    # Lenient normalization for gates reads, which never raise: anything
+    # stringifiable passes.
+    def normalize(traits)
+      return {} unless traits.is_a?(Hash)
+
+      traits.each_with_object({}) { |(key, value), out| out[key.to_s] = value.to_s }
+    end
+  end
+end

data/lib/lucerna/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Lucerna
+  VERSION = "0.1.0"
+
+  # Value of the x-lucerna-sdk header on every request.
+  SDK_IDENTITY = "ruby/#{VERSION}"
+end

data/lib/lucerna.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require_relative "lucerna/version"
+require_relative "lucerna/errors"
+require_relative "lucerna/reporting"
+require_relative "lucerna/traits"
+require_relative "lucerna/http"
+require_relative "lucerna/config"
+require_relative "lucerna/identity"
+require_relative "lucerna/gates/hashing"
+require_relative "lucerna/gates/evaluate"
+require_relative "lucerna/gates/runtime"
+require_relative "lucerna/gates/exposures"
+require_relative "lucerna/gates/client"
+
+# Lucerna SDK for Ruby — Gates feature flags/experiments and Identity.
+#
+#   Lucerna.configure do |c|
+#     c.server_key = ENV["LUCERNA_SERVER_KEY"]
+#   end
+#
+#   identity = Lucerna::Identity.new(user_id: user.id.to_s, traits: { plan: "pro" })
+#   Lucerna.gates.flag("new_billing", identity)
+#   Lucerna.identity.identify(identity)
+module Lucerna
+  @mutex = Mutex.new
+  @config = nil
+  @gates = nil
+  @identity = nil
+  @at_exit_registered = false
+
+  class << self
+    def config
+      @config || @mutex.synchronize { @config ||= Config.new }
+    end
+
+    # Yields the Config. Must run before the first use of Lucerna.gates /
+    # Lucerna.identity — configuring an already-built client would be a
+    # silent no-op, so it raises instead.
+    def configure
+      configuration = @mutex.synchronize do
+        if @gates || @identity
+          raise Error,
+            "Lucerna.configure must run before the first use of Lucerna.gates / " \
+            "Lucerna.identity — or call Lucerna.restart first"
+        end
+        @config ||= Config.new
+      end
+      yield configuration if block_given?
+      configuration
+    end
+
+    # The Gates client singleton, built lazily from config on first use.
+    def gates
+      @gates || @mutex.synchronize { @gates ||= build_gates }
+    end
+
+    # The Identity delivery client singleton, built lazily on first use.
+    def identity
+      @identity || @mutex.synchronize { @identity ||= build_identity }
+    end
+
+    # Stops polling/delivery and flushes queued exposures and identifies.
+    # Also registered via at_exit when the first singleton is built. The
+    # clients keep answering stale reads after close.
+    def close(timeout: 2)
+      gates_client, identity_client = @mutex.synchronize { [@gates, @identity] }
+      gates_client&.close(timeout: timeout)
+      identity_client&.close(timeout: timeout)
+      nil
+    end
+
+    # Abandons the current clients (no flush — the parent process owns its
+    # own at_exit flush) and lets the next access rebuild them. For
+    # Puma on_worker_boot / Unicorn after_fork / Sidekiq startup; optional,
+    # since the clients also self-heal on first read after a fork.
+    def restart
+      @mutex.synchronize do
+        @gates = nil
+        @identity = nil
+      end
+      nil
+    end
+
+    private
+
+    def build_gates
+      configuration = @config ||= Config.new
+      key = configuration.server_key
+      if key.nil? || key.to_s.empty?
+        raise Error, "Lucerna.config.server_key is required for Lucerna.gates — set it in Lucerna.configure"
+      end
+
+      register_at_exit
+      Gates::Client.new(
+        server_key: key,
+        base_url: configuration.base_url,
+        refresh_interval: configuration.refresh_interval,
+        request_timeout: configuration.request_timeout,
+        on_error: configuration.on_error,
+        logger: configuration.logger,
+        track_exposures: configuration.track_exposures,
+        transport: configuration.transport,
+      )
+    end
+
+    def build_identity
+      configuration = @config ||= Config.new
+      key = configuration.identity_key || configuration.server_key
+      if key.nil? || key.to_s.empty?
+        raise Error,
+          "Lucerna.config.identity_key (or server_key) is required for Lucerna.identity — " \
+          "set it in Lucerna.configure"
+      end
+
+      register_at_exit
+      Identity::Client.new(
+        api_key: key,
+        base_url: configuration.base_url,
+        request_timeout: configuration.request_timeout,
+        on_error: configuration.on_error,
+        logger: configuration.logger,
+        transport: configuration.transport,
+      )
+    end
+
+    def register_at_exit
+      return if @at_exit_registered
+
+      @at_exit_registered = true
+      at_exit { Lucerna.close }
+    end
+  end
+end
+
+require_relative "lucerna/railtie" if defined?(::Rails::Railtie)

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: lucerna
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lucerna
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Server-side Lucerna SDK: local Gates evaluation (feature flags, experiments,
+  kill switches) with background runtime sync, and fire-and-forget People identify.
+  Pure Ruby, zero runtime dependencies, Rails Railtie included.'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/lucerna.rb
+- lib/lucerna/config.rb
+- lib/lucerna/errors.rb
+- lib/lucerna/gates/client.rb
+- lib/lucerna/gates/evaluate.rb
+- lib/lucerna/gates/exposures.rb
+- lib/lucerna/gates/hashing.rb
+- lib/lucerna/gates/runtime.rb
+- lib/lucerna/http.rb
+- lib/lucerna/identity.rb
+- lib/lucerna/identity/client.rb
+- lib/lucerna/railtie.rb
+- lib/lucerna/reporting.rb
+- lib/lucerna/traits.rb
+- lib/lucerna/version.rb
+homepage: https://uselucerna.app
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Lucerna SDK for Ruby — Gates feature flags and experiments, and Identity.
+test_files: []