kilden 0.1.0.alpha.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 40a40f42c4bc36e6168968c964a6f027fbb0a5a2e72567d18cc056c199d4ea57
+  data.tar.gz: aac87c93c2ae56d86f38ff80e214b95bfec01771122d1a1d38ce08c773fb38cf
+SHA512:
+  metadata.gz: 5adedf1b530c90e61417e9b199bb927ccb66099c3abe43055159b41e09136f9d67f937126bf8565338bfbad2c0410365edd81687c362c2e8e16a477809d57aa3
+  data.tar.gz: 56835a2ee186f650633226a60ef5b69ca6308ebf4244b42031df016382ea2fc9c055568b90e4ccc22b2f98442d626a256cb416af4cd59d810932c3a0428e52ce

data/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0.alpha.3] - 2026-07-14
+
+### Changed
+
+- Repository moved to the kildenhq org; releases publish to RubyGems via
+  OIDC trusted publishing.
+
+## [0.1.0.alpha.2] - 2026-07-14
+
+### Fixed
+
+- Any 2xx from `/capture` is success; the response body is never parsed
+  (spec clarification — a 200 with a corrupt body was retried before).
+- The transport detects responses truncated mid-body (connection cut) and
+  classifies them as retryable network errors.
+- `EventQueue#empty?` was missing, silently killing and respawning the
+  worker thread after every batch.
+
+## [0.1.0.alpha.1] - 2026-07-14
+
+### Added
+
+- `Kilden::Client`: `track`, `identify`, `alias`, `flush`, `close` with a
+  bounded in-memory queue, background worker, gzip, and retries with
+  exponential backoff honoring `Retry-After`.
+- Fork safety under preforking servers (puma/unicorn), tested against a real
+  `puma -w 2 --preload` in CI.
+- `Kilden::IdentitySigner`: hand-rolled HS256 identity tokens, byte-exact
+  against the platform's vectors.
+- Feature flags: `enabled?` / `feature_flag` over `/decide` with a 30s
+  TTL + LRU cache and `person_properties` / `default:` options.
+- Frozen rollout hashing (spec §8.3), vector-tested for future local eval.
+- Vector runners for the three kilden-sdk-spec vector files, wired into CI
+  against the spec's mock capture server.
+
+[Unreleased]: https://github.com/kildenhq/kilden-sdk-ruby/compare/v0.1.0-alpha.2...HEAD
+[0.1.0.alpha.2]: https://github.com/kildenhq/kilden-sdk-ruby/compare/v0.1.0-alpha.1...v0.1.0-alpha.2
+[0.1.0.alpha.1]: https://github.com/kildenhq/kilden-sdk-ruby/releases/tag/v0.1.0-alpha.1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Freshwork S.p.A.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,151 @@
+<p align="center">
+  <img src=".github/assets/hero.png" alt="Kilden Ruby SDK" width="800">
+</p>
+
+# kilden
+
+[![Gem Version](https://img.shields.io/gem/v/kilden)](https://rubygems.org/gems/kilden)
+[![ci](https://github.com/kildenhq/kilden-sdk-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/kildenhq/kilden-sdk-ruby/actions/workflows/ci.yml)
+[![license](https://img.shields.io/github/license/kildenhq/kilden-sdk-ruby)](LICENSE)
+
+[Kilden](https://kilden.io) is a customer data platform — product analytics,
+campaigns and session replay on one event pipeline. This is the server-side
+Ruby SDK: events your backend can vouch for, identity-token signing, and
+feature flags. Zero runtime dependencies, fork-safe under puma and unicorn.
+
+```sh
+gem install kilden --pre
+```
+
+```ruby
+require "kilden"
+
+kilden = Kilden::Client.new(ENV["KILDEN_SECRET_KEY"])
+kilden.track("user_42", "order_completed", { "revenue" => 99.9, "currency" => "CLP" })
+kilden.close # drain before the process exits
+```
+
+Use your project's **secret key** (`sk_…`), never the public one. Events sent
+with the secret key land as `source=server`, `verified=true` — facts the
+campaign engine can act on. The constructor rejects public keys outright, and
+the secret key must never reach a browser.
+
+## Identity verification
+
+Anyone can open a devtools console and send events as `ceo@yourcompany.com`
+with your public key. Kilden's fix is a short-lived JWT your backend signs;
+the platform then marks those browser events verified. Signing it is the part
+of the trust model only your backend can do, and it is three lines:
+
+```ruby
+signer = Kilden::IdentitySigner.new(ENV["KILDEN_IDENTITY_SECRET"], kid: "k1")
+
+# In the controller that renders your page or serves your token endpoint:
+token = signer.sign(current_user.id.to_s, traits: { "plan" => current_user.plan })
+```
+
+Hand `token` to the web SDK (`kilden.identify(id, traits, { token })` or its
+refresh endpoint). Signed traits override unsigned ones during enrichment.
+
+**Only sign a `sub` your backend authenticated.** Signing request input —
+`signer.sign(params[:user_id])` — lets anyone impersonate anyone, with a
+"verified" stamp on top. TTL defaults to 1 hour and is capped at 7 days.
+
+A Rails token endpoint, for the web SDK to refresh against:
+
+```ruby
+# config/routes.rb
+post "/kilden/identity", to: "kilden_identity#create"
+
+# app/controllers/kilden_identity_controller.rb
+class KildenIdentityController < ApplicationController
+  before_action :authenticate_user!
+
+  def create
+    signer = Kilden::IdentitySigner.new(ENV["KILDEN_IDENTITY_SECRET"], kid: "k1")
+    render json: {
+      distinct_id: current_user.id.to_s,
+      token: signer.sign(current_user.id.to_s),
+      traits: {}
+    }
+  end
+end
+```
+
+## Feature flags
+
+Flags are evaluated remotely against `{host}/decide` and cached for 30
+seconds per `distinct_id`. Always pass a `default:` — it is what you get when
+Kilden cannot answer in time:
+
+```ruby
+if kilden.enabled?("new_checkout", "user_42",
+                   person_properties: { "plan" => "pro" }, default: false)
+  render_new_checkout
+end
+
+kilden.feature_flag("experiment_button", "user_42", default: false)
+# => false | true | "variant_b"
+```
+
+`person_properties` overrides the stored person traits for that evaluation
+only (and bypasses the cache). The signature is already shaped for local
+evaluation, which will arrive without an API change.
+
+## Batching and shutdown
+
+Events queue in memory (bounded, default 10 000) and a background thread
+flushes every 10 seconds or every 20 events, whichever comes first. The
+queue never blocks your request thread; when it is full, new events are
+dropped and counted in `kilden.dropped_count`.
+
+**Call `close` when your process exits.** It drains the queue with a
+10-second deadline and stops the worker. An `at_exit` hook covers the
+forgetful, but a hard kill (SIGKILL, OOM) loses whatever was still queued —
+that is the price of never blocking your app. `flush` forces a synchronous
+drain without shutting down.
+
+Retries: 429/5xx/network errors retry up to 3 times with exponential backoff
+and jitter, honoring `Retry-After`. Other 4xx responses are dropped and
+logged — retrying a 401 is spam.
+
+### Preforking servers (puma, unicorn) and Sidekiq
+
+Nothing to configure. The SDK detects the PID change after a fork, discards
+the queue inherited from the master (the master still owns those events) and
+starts a fresh worker thread in the child. This is tested in CI against a
+real preforked puma. Sidekiq processes are plain long-lived processes: build
+one client and reuse it.
+
+## Configuration
+
+```ruby
+Kilden::Client.new(
+  ENV["KILDEN_SECRET_KEY"],
+  host: "https://ingest.kilden.io", # self-hosted: your ingest URL
+  flush_at: 20,                     # queue length that triggers a flush
+  flush_interval: 10,               # seconds between periodic flushes
+  max_queue_size: 10_000,           # hard cap; new events drop beyond it
+  timeout: 3,                       # seconds per HTTP request
+  debug: false,                     # verbose logging, $-prefix warnings
+  enabled: true                     # false = full no-op for tests/CI
+)
+```
+
+## Spec
+
+This SDK implements the
+[Kilden server SDK spec](https://github.com/kildenhq/kilden-sdk-spec)
+(v0.1) and runs its frozen test vectors — including byte-exact identity
+tokens and the flag rollout hashing — against the spec's mock capture server
+in CI. Behavior changes land in the spec first.
+
+## Community
+
+- [Docs](https://docs.kilden.io)
+- [Discussions](https://github.com/kildenhq/kilden-sdk-ruby/discussions)
+  for questions — answers stay searchable.
+
+## License
+
+[MIT](LICENSE)

data/lib/kilden/canonical_json.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Kilden
+  # The canonical JSON form frozen by the spec (§6.1) so identity tokens are
+  # byte-identical across the five SDKs: object keys sorted lexicographically
+  # (byte order) at every nesting level, compact separators, UTF-8 preserved,
+  # and the three HTML-unsafe ASCII characters escaped the way Go's
+  # encoding/json does — the platform's reference generator.
+  # @api private
+  module CanonicalJSON
+    HTML_UNSAFE = { "&" => "\\u0026", "<" => "\\u003c", ">" => "\\u003e" }.freeze
+
+    module_function
+
+    def generate(value)
+      case value
+      when Hash
+        pairs = value.keys.map(&:to_s).sort.map do |key|
+          raw = value.key?(key) ? value[key] : value[key.to_sym]
+          "#{string(key)}:#{generate(raw)}"
+        end
+        "{#{pairs.join(',')}}"
+      when Array
+        "[#{value.map { |v| generate(v) }.join(',')}]"
+      when String
+        string(value)
+      when Integer, Float, TrueClass, FalseClass
+        JSON.generate(value)
+      when nil
+        "null"
+      else
+        string(value.to_s)
+      end
+    end
+
+    def string(value)
+      JSON.generate(value).gsub(/[&<>]/, HTML_UNSAFE)
+    end
+  end
+end

data/lib/kilden/client.rb

@@ -0,0 +1,374 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Kilden
+  # The Kilden server-side client: bounded in-memory queue, background
+  # worker, retries with backoff, remote feature flags. Construction is the
+  # only place that raises (spec contract 2); after that every public method
+  # is exception-safe — telemetry never takes down a request.
+  #
+  #   kilden = Kilden::Client.new(ENV["KILDEN_SECRET_KEY"])
+  #   kilden.track("user_42", "order_completed", { "revenue" => 99.9 })
+  #   kilden.close # on shutdown; an at_exit hook covers the forgetful
+  class Client
+    DEFAULT_HOST = "https://ingest.kilden.io"
+    MAX_EVENT_BYTES = 200
+    MAX_DISTINCT_ID_BYTES = 512
+    BATCH_LIMIT = 1000
+    CLOSE_DEADLINE = 10
+
+    # dropped_count: events lost to a full queue or exhausted retries
+    # (contract 7/8) — observable so operators can alert on it.
+    def dropped_count
+      return 0 unless @enabled
+
+      @queue.dropped_count + @sender.dropped_total
+    end
+
+    def initialize(write_key, host: DEFAULT_HOST, flush_at: 20, flush_interval: 10,
+                   max_queue_size: 10_000, timeout: 3, transport: nil, debug: false,
+                   enabled: true, logger: nil)
+      unless write_key.is_a?(String) && !write_key.empty?
+        raise ConfigurationError,
+              "a write key is required — find your project's secret key (sk_...) in the Kilden panel"
+      end
+      if write_key.start_with?("wk_")
+        raise ConfigurationError,
+              "#{write_key[0, 10]}… is a public write key. Server SDKs authenticate with the secret key (sk_...): " \
+              "public keys degrade events to source=client and break verified revenue. " \
+              "Never ship the secret key to a browser."
+      end
+
+      @debug = debug ? true : false
+      @logger = logger || Log.new(@debug ? :debug : :warn)
+      @enabled = enabled ? true : false
+      @flush_interval = flush_interval
+      return unless @enabled
+
+      @queue = EventQueue.new(max_size: max_queue_size, flush_at: flush_at)
+      @sender = Sender.new(
+        write_key: write_key,
+        host: host,
+        transport: transport || Transport::NetHttp.new(timeout: timeout),
+        logger: @logger
+      )
+      @decide = Decide.new(write_key: write_key, host: host, timeout: timeout,
+                           transport: transport, logger: @logger)
+      @flag_cache = FlagCache.new
+      @pid = Process.pid
+      @worker = nil
+      @lifecycle = Mutex.new
+      @closed = false
+      @shutdown_deadline = nil
+
+      at_exit { close }
+    end
+
+    def track(distinct_id, event, properties = {}, opts = {})
+      guard do
+        next unless @enabled && open_for_events?
+
+        payload = build_event(distinct_id, event, properties, opts)
+        enqueue(payload) if payload
+        nil
+      end
+    end
+
+    def identify(distinct_id, traits = {}, opts = {})
+      guard do
+        next unless @enabled && open_for_events?
+
+        traits = {} if traits.nil?
+        unless traits.is_a?(Hash)
+          @logger.warn("kilden: identify traits must be a Hash; event dropped")
+          next
+        end
+        payload = build_event(distinct_id, "$identify", { "$set" => traits }, opts, reserved: true)
+        enqueue(payload) if payload
+        nil
+      end
+    end
+
+    # `alias` is a Ruby keyword, so the method is defined dynamically; the
+    # call site reads naturally: kilden.alias("anon_…", "user_42").
+    define_method(:alias) do |previous_id, distinct_id|
+      guard do
+        next unless @enabled && open_for_events?
+
+        next unless valid_id?(distinct_id, "alias distinct_id")
+
+        payload = build_event(previous_id, "$alias", { "$alias" => distinct_id }, {}, reserved: true)
+        enqueue(payload) if payload
+        nil
+      end
+    end
+
+    def enabled?(flag_key, distinct_id, person_properties: nil, default: false)
+      guard(default) do
+        state, value = fetch_flag(flag_key, distinct_id, person_properties)
+        next default unless state == :ok
+
+        value == true || value.is_a?(String)
+      end
+    end
+
+    def feature_flag(flag_key, distinct_id, person_properties: nil, default: false)
+      guard(default) do
+        state, value = fetch_flag(flag_key, distinct_id, person_properties)
+        state == :ok ? value : default
+      end
+    end
+
+    # Blocking: drains everything queued at this moment, retries included.
+    def flush
+      guard do
+        next unless @enabled
+
+        check_fork
+        @queue.drain.each_slice(BATCH_LIMIT) { |batch| @sender.send_batch(batch) }
+        nil
+      end
+    end
+
+    # flush with a 10-second deadline, then worker shutdown. Idempotent;
+    # events sent after close are dropped with a warning.
+    def close
+      guard do
+        next unless @enabled
+
+        @lifecycle.synchronize do
+          next if @closed
+
+          @closed = true
+          @shutdown_deadline = monotonic + CLOSE_DEADLINE
+          @queue.close
+        end
+
+        worker = @worker
+        if worker&.alive?
+          worker.join([@shutdown_deadline - monotonic, 0].max)
+          if worker.alive?
+            worker.kill
+            abandoned = @queue.drain.size
+            if abandoned.positive?
+              @sender.dropped!(abandoned)
+              @logger.warn("kilden: close deadline hit; dropped #{abandoned} events")
+            end
+          end
+        else
+          @queue.drain.each_slice(BATCH_LIMIT) do |batch|
+            @sender.send_batch(batch, deadline: @shutdown_deadline)
+          end
+        end
+        nil
+      end
+    end
+
+    # Frozen wire format for timestamps (spec §4.4).
+    def self.format_time(time)
+      time.getutc.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+    end
+
+    private
+
+    def guard(fallback = nil)
+      yield
+    rescue StandardError => e
+      # Contract 1: the public API never raises after construction.
+      @logger&.error("kilden: suppressed #{e.class}: #{e.message}")
+      fallback
+    end
+
+    def open_for_events?
+      if @closed
+        @logger.warn("kilden: client is closed; event dropped")
+        return false
+      end
+      true
+    end
+
+    def valid_id?(value, label)
+      unless value.is_a?(String) && !value.empty?
+        @logger.warn("kilden: #{label} must be a non-empty string; event dropped")
+        return false
+      end
+      if value.bytesize > MAX_DISTINCT_ID_BYTES
+        @logger.warn("kilden: #{label} exceeds #{MAX_DISTINCT_ID_BYTES} bytes; event dropped")
+        return false
+      end
+      true
+    end
+
+    def build_event(distinct_id, event, properties, opts, reserved: false)
+      return nil unless valid_id?(distinct_id, "distinct_id")
+
+      unless event.is_a?(String) && !event.empty?
+        @logger.warn("kilden: event must be a non-empty string; event dropped")
+        return nil
+      end
+      if event.bytesize > MAX_EVENT_BYTES
+        @logger.warn("kilden: event name exceeds #{MAX_EVENT_BYTES} bytes; event dropped")
+        return nil
+      end
+      properties = {} if properties.nil?
+      unless properties.is_a?(Hash)
+        @logger.warn("kilden: properties must be a Hash; event dropped")
+        return nil
+      end
+      if @debug && !reserved && (event.start_with?("$") || properties.keys.any? { |k| k.to_s.start_with?("$") })
+        @logger.debug("kilden: the $ prefix is reserved for Kilden events/properties (sent anyway)")
+      end
+
+      begin
+        JSON.generate(properties)
+      rescue StandardError
+        @logger.warn("kilden: properties are not JSON-serializable; event dropped")
+        return nil
+      end
+
+      timestamp = event_timestamp(opts)
+      return nil unless timestamp
+
+      uuid = opts[:uuid] || opts["uuid"]
+      if uuid && !UUID.canonical?(uuid)
+        @logger.warn("kilden: uuid option is not a canonical UUID; event dropped")
+        return nil
+      end
+
+      {
+        "uuid" => uuid || UUID.v7,
+        "event" => event,
+        "distinct_id" => distinct_id,
+        "properties" => properties,
+        "timestamp" => timestamp
+      }
+    end
+
+    def event_timestamp(opts)
+      raw = opts[:timestamp] || opts["timestamp"]
+      return Client.format_time(Time.now) if raw.nil?
+
+      time = case raw
+             when Time then raw
+             when String then Time.iso8601(raw)
+             else raw.respond_to?(:to_time) ? raw.to_time : nil
+             end
+      return Client.format_time(time) if time
+
+      @logger.warn("kilden: timestamp option is not a time; event dropped")
+      nil
+    rescue ArgumentError
+      @logger.warn("kilden: timestamp option is not a valid ISO 8601 time; event dropped")
+      nil
+    end
+
+    def enqueue(payload)
+      check_fork
+      unless @queue.push(payload)
+        @logger.warn("kilden: queue full (#{payload['event']} dropped)")
+        return
+      end
+      ensure_worker
+    end
+
+    # Contract 9: preforking servers (puma, unicorn) fork after boot. The
+    # child inherits the parent's queue and a dead worker thread; detect the
+    # PID change, discard the inherited events (the parent owns them —
+    # resending duplicates) and start a fresh worker.
+    def check_fork
+      return if @pid == Process.pid
+
+      @lifecycle.synchronize do
+        next if @pid == Process.pid
+
+        discarded = @queue.reset!
+        @flag_cache.clear
+        @worker = nil
+        @closed = false
+        @shutdown_deadline = nil
+        @pid = Process.pid
+        @logger.info("kilden: fork detected (pid #{@pid}); " \
+                     "discarded #{discarded} inherited events and restarted the worker")
+      end
+    end
+
+    def ensure_worker
+      return if @worker&.alive?
+
+      @lifecycle.synchronize do
+        next if @worker&.alive?
+
+        @worker = Thread.new do
+          loop do
+            batch = @queue.wait_batch(@flush_interval, max: BATCH_LIMIT)
+            @sender.send_batch(batch, deadline: @shutdown_deadline) unless batch.empty?
+            break if @queue.closed? && @queue.empty?
+          end
+        end
+        @worker.name = "kilden-worker"
+      end
+    end
+
+    def fetch_flag(flag_key, distinct_id, person_properties)
+      return [:miss, nil] unless @enabled
+
+      unless flag_key.is_a?(String) && !flag_key.empty?
+        @logger.warn("kilden: flag_key must be a non-empty string")
+        return [:miss, nil]
+      end
+      return [:miss, nil] unless valid_id?(distinct_id, "distinct_id")
+
+      check_fork
+
+      # person_properties make the evaluation non-reusable: bypass the cache
+      # entirely (no read, no write) per spec §8.2.
+      if person_properties.nil? && (cached = @flag_cache.get(distinct_id))
+        return cached.key?(flag_key) ? [:ok, cached[flag_key]] : [:miss, nil]
+      end
+
+      flags = @decide.flags_for(distinct_id, person_properties)
+      return [:miss, nil] unless flags
+
+      @flag_cache.set(distinct_id, flags) if person_properties.nil?
+      flags.key?(flag_key) ? [:ok, flags[flag_key]] : [:miss, nil]
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+
+  # One-attempt /decide lookups (spec §8.2: a flag answer that arrives after
+  # a retry budget is useless — return the default instead).
+  # @api private
+  class Decide
+    def initialize(write_key:, host:, timeout:, transport:, logger:)
+      @write_key = write_key
+      @url = "#{host.chomp('/')}/decide"
+      @transport = transport || Transport::NetHttp.new(timeout: timeout)
+      @logger = logger
+    end
+
+    def flags_for(distinct_id, person_properties)
+      request = { "write_key" => @write_key, "distinct_id" => distinct_id }
+      request["person_properties"] = person_properties unless person_properties.nil?
+
+      response = @transport.post(@url, JSON.generate(request),
+                                 "Content-Type" => "application/json",
+                                 "User-Agent" => "kilden-ruby/#{VERSION}")
+      unless response.status == 200
+        reason = response.network_error? ? response.error&.class : "HTTP #{response.status}"
+        @logger.warn("kilden: /decide failed (#{reason}); using defaults")
+        return nil
+      end
+
+      flags = JSON.parse(response.body)["flags"]
+      flags.is_a?(Hash) ? flags : nil
+    rescue JSON::ParserError
+      @logger.warn("kilden: /decide returned a malformed body; using defaults")
+      nil
+    end
+  end
+end

data/lib/kilden/event_queue.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Kilden
+  # Bounded in-memory queue (spec contract 7): at capacity the NEW event is
+  # dropped, never the old ones, and the drop is counted. Wakes the worker
+  # when flush_at is reached.
+  # @api private
+  class EventQueue
+    attr_reader :dropped_count
+
+    def initialize(max_size:, flush_at:)
+      @max_size = max_size
+      @flush_at = flush_at
+      @items = []
+      @dropped_count = 0
+      @mutex = Mutex.new
+      @signal = ConditionVariable.new
+      @closed = false
+    end
+
+    # Returns false when the event was dropped because the queue is full.
+    def push(event)
+      @mutex.synchronize do
+        if @items.size >= @max_size
+          @dropped_count += 1
+          return false
+        end
+        @items << event
+        @signal.signal if @items.size >= @flush_at
+        true
+      end
+    end
+
+    # Blocks until flush_at is reached, `interval` elapses, or close; then
+    # pops up to `max` events. Returns [] on a quiet interval tick.
+    def wait_batch(interval, max: 1000)
+      @mutex.synchronize do
+        @signal.wait(@mutex, interval) if @items.size < @flush_at && !@closed
+        @items.shift(max)
+      end
+    end
+
+    # Everything queued at the moment of the call (for flush/shutdown).
+    def drain
+      @mutex.synchronize { @items.slice!(0, @items.size) }
+    end
+
+    def size
+      @mutex.synchronize { @items.size }
+    end
+
+    def empty?
+      size.zero?
+    end
+
+    def close
+      @mutex.synchronize do
+        @closed = true
+        @signal.broadcast
+      end
+    end
+
+    def closed?
+      @mutex.synchronize { @closed }
+    end
+
+    # Fork recovery (contract 9): the child discards the inherited queue —
+    # those events belong to the parent; sending them twice would duplicate.
+    def reset!
+      @mutex.synchronize do
+        discarded = @items.size
+        @items.clear
+        @closed = false
+        discarded
+      end
+    end
+  end
+end

data/lib/kilden/flag_cache.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Kilden
+  # TTL + LRU cache of /decide responses, keyed by distinct_id (spec §8.2:
+  # TTL 30s, at most 1000 ids). Ruby's insertion-ordered Hash doubles as the
+  # LRU list: delete + reinsert on hit, shift the oldest on overflow.
+  # @api private
+  class FlagCache
+    TTL = 30
+    MAX_IDS = 1000
+
+    def initialize(clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      @clock = clock
+      @entries = {}
+      @mutex = Mutex.new
+    end
+
+    def get(distinct_id)
+      @mutex.synchronize do
+        entry = @entries.delete(distinct_id)
+        return nil unless entry
+        return nil if @clock.call >= entry[0]
+
+        @entries[distinct_id] = entry
+        entry[1]
+      end
+    end
+
+    def set(distinct_id, flags)
+      @mutex.synchronize do
+        @entries.delete(distinct_id)
+        @entries[distinct_id] = [@clock.call + TTL, flags]
+        @entries.shift if @entries.size > MAX_IDS
+      end
+    end
+
+    def clear
+      @mutex.synchronize { @entries.clear }
+    end
+  end
+end

data/lib/kilden/hashing.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Kilden
+  # The frozen rollout hashing (spec §8.3). v1 never evaluates flags locally
+  # — /decide does — but the algorithm is pinned now, tested against the
+  # platform-generated vectors, so local evaluation can arrive later without
+  # an API change or a bucketing flicker.
+  # @api private
+  module Hashing
+    TWO_POW_64 = 2.0**64
+
+    module_function
+
+    def bucket(flag_key, distinct_id)
+      fraction("#{flag_key}:#{distinct_id}") * 100
+    end
+
+    def variant_for(flag_key, distinct_id, variants)
+      point = fraction("#{flag_key}:#{distinct_id}:variant") * 100
+      cumulative = 0.0
+      variants.each do |variant|
+        cumulative += variant.fetch("rollout_percentage")
+        return variant.fetch("key") if point < cumulative
+      end
+      true
+    end
+
+    def fraction(input)
+      Digest::SHA256.digest(input)[0, 8].unpack1("Q>") / TWO_POW_64
+    end
+  end
+end

data/lib/kilden/identity_signer.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Kilden
+  # Signs the short-lived identity tokens that make browser events
+  # verifiable (Kilden's trust model). Deliberately separate from Client: a
+  # controller rendering a page wants a token, not an event queue.
+  #
+  #   signer = Kilden::IdentitySigner.new(ENV["KILDEN_IDENTITY_SECRET"], kid: "k1")
+  #   token  = signer.sign(current_user.id.to_s, traits: { plan: "pro" })
+  #
+  # Only sign a +sub+ your backend authenticated. Signing user input
+  # (params[:user_id]) lets anyone impersonate anyone — with a "verified"
+  # stamp on top.
+  #
+  # HS256 is implemented by hand because the spec freezes the byte form of
+  # the token (kilden-sdk-spec §6.1); a JWT library's serialization choices
+  # would silently diverge.
+  class IdentitySigner
+    MAX_TTL = 604_800 # 7 days; identity tokens are short-lived by design
+
+    def initialize(identity_secret, kid:)
+      if !identity_secret.is_a?(String) || identity_secret.empty?
+        raise ConfigurationError,
+              "identity secret is required"
+      end
+      if !kid.is_a?(String) || kid.empty?
+        raise ConfigurationError,
+              "kid is required (the platform looks the secret up by kid)"
+      end
+
+      @secret = identity_secret
+      @kid = kid
+    end
+
+    # Returns the signed JWT for +sub+ (the distinct_id the token vouches
+    # for). ttl defaults to one hour and is capped at 7 days.
+    def sign(sub, ttl: 3600, traits: nil)
+      raise ArgumentError, "sub must be a non-empty string" if !sub.is_a?(String) || sub.empty?
+      raise ArgumentError, "ttl must be in (0, #{MAX_TTL}] seconds" if !ttl.is_a?(Integer) || ttl <= 0 || ttl > MAX_TTL
+
+      iat = Time.now.to_i
+      build(sub, iat: iat, exp: iat + ttl, traits: traits)
+    end
+
+    private
+
+    def build(sub, iat:, exp:, traits:)
+      header = CanonicalJSON.generate({ "alg" => "HS256", "kid" => @kid, "typ" => "JWT" })
+      claims = { "exp" => exp, "iat" => iat, "sub" => sub }
+      claims["traits"] = traits if traits && !traits.empty?
+      payload = CanonicalJSON.generate(claims)
+
+      signing_input = "#{b64url(header)}.#{b64url(payload)}"
+      signature = OpenSSL::HMAC.digest("SHA256", @secret, signing_input)
+      "#{signing_input}.#{b64url(signature)}"
+    end
+
+    # base64url without padding, via Array#pack — the base64 stdlib moved
+    # out of the default gems in Ruby 3.4 and this SDK ships zero deps.
+    def b64url(bytes)
+      [bytes].pack("m0").tr("+/", "-_").delete("=")
+    end
+  end
+end

data/lib/kilden/log.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Kilden
+  # Minimal leveled logger writing to $stderr. The stdlib logger is leaving
+  # the default gems (Ruby 4), and this SDK ships zero dependencies — so the
+  # default is this. Anything responding to debug/info/warn/error can
+  # replace it through the client's logger: option.
+  # @api private
+  class Log
+    LEVELS = { debug: 0, info: 1, warn: 2, error: 3 }.freeze
+
+    def initialize(level)
+      @threshold = LEVELS.fetch(level)
+    end
+
+    LEVELS.each do |name, severity|
+      define_method(name) do |message|
+        warn("kilden [#{name}] #{message}") if severity >= @threshold
+        nil
+      end
+    end
+  end
+end

data/lib/kilden/sender.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "json"
+require "zlib"
+
+module Kilden
+  # Owns one batch from build to success or exhaustion (spec §4.3). Failed
+  # batches never go back into the main queue — that would shuffle ordering
+  # and could evict fresh events.
+  # @api private
+  class Sender
+    MAX_RETRIES = 3
+    GZIP_THRESHOLD = 1024
+
+    attr_reader :dropped_count
+
+    def initialize(write_key:, host:, transport:, logger:, sleeper: nil, rng: Random.new)
+      @write_key = write_key
+      @capture_url = "#{host.chomp('/')}/capture"
+      @transport = transport
+      @logger = logger
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      @rng = rng
+      @dropped = 0
+      @mutex = Mutex.new
+    end
+
+    def dropped!(count)
+      @mutex.synchronize { @dropped += count }
+    end
+
+    def dropped_total
+      @mutex.synchronize { @dropped }
+    end
+
+    # Sends up to MAX_RETRIES + 1 attempts. deadline (monotonic seconds) cuts
+    # the loop short during shutdown: telemetry never hangs a process.
+    def send_batch(events, deadline: nil)
+      return :ok if events.empty?
+
+      attempt = 0
+      loop do
+        response = deliver(events)
+        return :ok if success?(response)
+
+        unless retryable?(response)
+          drop(events,
+               "kilden: dropped #{events.size} events (HTTP #{response.status}: #{response.body.to_s.strip[0, 120]})")
+          return :dropped
+        end
+
+        attempt += 1
+        if attempt > MAX_RETRIES || past?(deadline)
+          drop(events, "kilden: dropped #{events.size} events after #{attempt} attempts")
+          return :dropped
+        end
+
+        delay = backoff(attempt, response)
+        if deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) + delay > deadline
+          drop(events, "kilden: dropped #{events.size} events (shutdown deadline)")
+          return :dropped
+        end
+        @sleeper.call(delay)
+      end
+    end
+
+    private
+
+    def deliver(events)
+      # sent_at is stamped when the request is built (clock-skew correction
+      # happens server-side against this value).
+      payload = {
+        "write_key" => @write_key,
+        "sent_at" => Client.format_time(Time.now),
+        "batch" => events
+      }
+      body = JSON.generate(payload)
+      headers = {
+        "Content-Type" => "application/json",
+        "User-Agent" => "kilden-ruby/#{VERSION}"
+      }
+      if body.bytesize > GZIP_THRESHOLD
+        body = Zlib.gzip(body)
+        headers["Content-Encoding"] = "gzip"
+      end
+      @transport.post(@capture_url, body, headers)
+    end
+
+    def success?(response)
+      # Any 2xx is success — the response body is never parsed; the status
+      # is the whole signal (§4.3).
+      (200..299).cover?(response.status)
+    end
+
+    def retryable?(response)
+      response.network_error? || response.status == 429 || response.status >= 500
+    end
+
+    def backoff(retry_number, response)
+      if response.status == 429 && (after = response.headers["retry-after"]) && after.to_i.positive?
+        return after.to_i
+      end
+
+      base = [0.5 * (2**(retry_number - 1)), 30].min
+      base * @rng.rand(0.5..1.5)
+    end
+
+    def past?(deadline)
+      deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+    end
+
+    def drop(events, message)
+      dropped!(events.size)
+      @logger.warn(message)
+    end
+  end
+end

data/lib/kilden/transport.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Kilden
+  # Transport seam: anything responding to
+  # +post(url, body, headers) -> Kilden::Transport::Response+ can replace the
+  # default. A transport never raises — network failures come back as
+  # status 0 so the retry loop can treat them uniformly.
+  # @api private
+  module Transport
+    Response = Struct.new(:status, :headers, :body, :error, keyword_init: true) do
+      def network_error?
+        status.zero?
+      end
+    end
+
+    # Default transport on Net::HTTP. One connection per request: the SDK
+    # flushes at most every few seconds, so pooling buys nothing and costs
+    # state that would go stale across forks.
+    class NetHttp
+      def initialize(timeout:)
+        @timeout = timeout
+      end
+
+      def post(url, body, headers)
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+        http.write_timeout = @timeout if http.respond_to?(:write_timeout=)
+
+        response = http.post(uri.path.empty? ? "/" : uri.path, body, headers)
+        normalized = {}
+        response.each_header { |k, v| normalized[k.downcase] = v }
+        payload = response.body.to_s
+        # A body shorter than Content-Length is a connection cut mid-response
+        # (Net::HTTP returns the partial read silently). Malformed HTTP is a
+        # network error per SPEC §4.3, so the batch retries.
+        declared = normalized["content-length"]&.to_i
+        if declared && payload.bytesize < declared
+          return Response.new(status: 0, headers: normalized, body: payload,
+                              error: EOFError.new("response truncated at #{payload.bytesize}/#{declared} bytes"))
+        end
+        Response.new(status: response.code.to_i, headers: normalized, body: payload)
+      rescue StandardError => e
+        Response.new(status: 0, headers: {}, body: "", error: e)
+      ensure
+        begin
+          http&.finish if http&.started?
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/kilden/uuid.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Kilden
+  # UUID v7 (RFC 9562): 48-bit unix milliseconds, then random bits with the
+  # version/variant nibbles pinned. Generated client-side per event so
+  # retries stay idempotent — the platform deduplicates on this value.
+  # @api private
+  module UUID
+    CANONICAL = /\A[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\z/
+    V7 = /\A[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/
+
+    module_function
+
+    def v7(now_ms = (Process.clock_gettime(Process::CLOCK_REALTIME) * 1000).to_i)
+      bytes = [now_ms >> 16, now_ms & 0xFFFF].pack("NS>") + SecureRandom.bytes(10)
+      bytes.setbyte(6, (bytes.getbyte(6) & 0x0F) | 0x70)
+      bytes.setbyte(8, (bytes.getbyte(8) & 0x3F) | 0x80)
+      hex = bytes.unpack1("H*")
+      "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
+    end
+
+    def canonical?(value)
+      value.is_a?(String) && CANONICAL.match?(value)
+    end
+  end
+end

data/lib/kilden/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Kilden
+  VERSION = "0.1.0.alpha.3"
+end

data/lib/kilden.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Kilden server-side SDK. Public surface: Kilden::Client and
+# Kilden::IdentitySigner — everything else is internal.
+#
+# The behavior of this SDK is specified, together with the other four server
+# SDKs, in https://github.com/kildenhq/kilden-sdk-spec — changes that
+# alter observable behavior land there first.
+module Kilden
+  # Raised only at construction time (spec contract 2): bad write key,
+  # bad signer configuration. Nothing raises after construction.
+  class ConfigurationError < ArgumentError
+  end
+end
+
+require "kilden/version"
+require "kilden/log"
+require "kilden/uuid"
+require "kilden/canonical_json"
+require "kilden/identity_signer"
+require "kilden/transport"
+require "kilden/sender"
+require "kilden/event_queue"
+require "kilden/hashing"
+require "kilden/flag_cache"
+require "kilden/client"

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: kilden
+version: !ruby/object:Gem::Version
+  version: 0.1.0.alpha.3
+platform: ruby
+authors:
+- Freshwork
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Server-side events, identity signing and feature flags for Kilden. Zero
+  runtime dependencies, fork-safe under preforking servers.
+email:
+- hello@kilden.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/kilden.rb
+- lib/kilden/canonical_json.rb
+- lib/kilden/client.rb
+- lib/kilden/event_queue.rb
+- lib/kilden/flag_cache.rb
+- lib/kilden/hashing.rb
+- lib/kilden/identity_signer.rb
+- lib/kilden/log.rb
+- lib/kilden/sender.rb
+- lib/kilden/transport.rb
+- lib/kilden/uuid.rb
+- lib/kilden/version.rb
+homepage: https://github.com/kildenhq/kilden-sdk-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kildenhq/kilden-sdk-ruby
+  source_code_uri: https://github.com/kildenhq/kilden-sdk-ruby
+  changelog_uri: https://github.com/kildenhq/kilden-sdk-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://docs.kilden.io
+  bug_tracker_uri: https://github.com/kildenhq/kilden-sdk-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Kilden server-side SDK for Ruby
+test_files: []