beacon-client 0.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3e95a63ccca5c5cfcad6a8b6f725109ff817a747b099f5800cadfdc214a53b96
+  data.tar.gz: 847ba604959ff63d15ef4f654a42935bc8404d5443e562ad9f1676eaeef37fd3
+SHA512:
+  metadata.gz: 68563de7a536e9149ea4ffcea3c307a61ff3fb1bfb2dd3ca064716ca3ba12bccf924aabb538d8236d02d5c9daa75ef8786f5b460d57ffea79ed3cb55ccf5f423
+  data.tar.gz: d8f5ab65210df3b35f55127a1ab6b57e5c349d6fcc84c9798ca785c00be95dbef5462d1590d74da1f7705663e7df0a2fb86ea1e315f433084f291e3ee958ae8f

data/README.md

@@ -0,0 +1,165 @@
+# beacon-client
+
+The Ruby client for [Beacon](https://github.com/luuuc/beacon) — the small
+observability accessory for self-hosted apps.
+
+One initializer wires up three pillars:
+
+- **Performance** — every Rack request is auto-instrumented
+- **Errors** — every unhandled exception is fingerprinted and shipped
+- **Outcomes** — `Beacon.track("signup.completed", user: current_user)`
+
+## Install
+
+```ruby
+gem "beacon-client"
+```
+
+> **Do not add `require: "beacon/testing"` in your Gemfile.** The `beacon/testing` file contains test helpers (`NullSink`, `FakeTransport`, `Beacon::Testing.reset_config!`) that should only be loaded from `spec/test_helper.rb` — loading them into production Rails boot is a footgun that leaks test-only classes into your host namespace. `beacon-client` itself is safe to auto-require; only `beacon/testing` is not.
+
+## Configure
+
+```ruby
+# config/initializers/beacon.rb
+Beacon.configure do |c|
+  c.endpoint    = "http://beacon:4680"
+  c.environment = Rails.env
+  c.deploy_sha  = ENV["GIT_SHA"]                            # optional
+  c.auth_token  = Rails.application.credentials.beacon_token # optional
+end
+```
+
+In a Rails app, that's **all** you write. The gem ships a Railtie that:
+
+- Inserts `Beacon::Middleware` into the stack, right after `ActionDispatch::DebugExceptions` (so host errors flow through Beacon before Rails renders them).
+- Auto-installs the ActiveJob and ActionMailer integrations — no `require "beacon/integrations/..."` needed.
+- Installs a `Process._fork` hook that runs `Beacon.client.after_fork` in every fork child, so clustered Puma / Unicorn / Passenger workers get their own flusher thread automatically. **No manual `on_worker_boot` needed.**
+
+In a plain Rack app (no Rails), mount the middleware manually:
+
+```ruby
+# config.ru
+require "beacon"
+require "beacon/middleware"
+use Beacon::Middleware
+```
+
+### Ambient mode + enrichment
+
+Enable ambient mode to passively capture operational telemetry (HTTP requests, jobs, mailers) alongside the standard three pillars. Add an `enrich_context` block to attach dimensions (country, plan, locale) to every event:
+
+```ruby
+Beacon.configure do |c|
+  c.endpoint = "http://beacon:4680"
+  c.ambient  = true
+
+  c.enrich_context do |request|
+    user = request.env["warden"]&.user
+    {
+      country: user&.country || Beacon::Enrichment.country_from_cdn(request),
+      plan:    user&.plan_name
+    }
+  end
+end
+```
+
+The enrichment block runs on every request. Keep it fast — use data already loaded by the app, don't make database queries. If the block raises, the event sends without dimensions and a warning is logged once.
+
+#### Enrichment examples
+
+**Devise/Warden (most Rails apps):**
+```ruby
+c.enrich_context do |request|
+  user = request.env["warden"]&.user
+  { country: user&.country, plan: user&.plan_name }
+end
+```
+
+**CDN geo headers (Cloudflare, Fastly, or CloudFront):**
+```ruby
+c.enrich_context do |request|
+  { country: Beacon::Enrichment.country_from_cdn(request) }
+end
+```
+The helper checks all three CDNs in priority order — no CDN-specific code needed.
+
+**No CDN, no auth — just browser locale:**
+```ruby
+c.enrich_context do |request|
+  { locale: request.env["HTTP_ACCEPT_LANGUAGE"]&.split(",")&.first }
+end
+```
+
+`Beacon::Enrichment.country_from_cdn` checks Cloudflare, Fastly, and CloudFront headers in priority order. Returns a two-letter ISO code or `nil`.
+
+### Kill switch
+
+To silence Beacon entirely without removing the gem:
+
+```ruby
+# config/initializers/beacon.rb
+Beacon.configure { |c| c.enabled = false }
+```
+
+Or at the operating-system level:
+
+```bash
+BEACON_DISABLED=1 bin/rails server
+```
+
+A disabled Beacon is a pure passthrough: the middleware adds one
+boolean check per request, nothing is captured, no flusher thread
+is started, no network connection is opened.
+
+**`BEACON_DISABLED` is read once at process start.** Setting it after
+the Ruby process has already booted has no effect — you must restart
+the worker. Accepted truthy values: `1`, `true`, `yes`, `on`
+(case-insensitive). Everything else (including `0`, `false`, `no`,
+`off`, and the empty string) leaves Beacon enabled.
+
+If `c.endpoint` is nil or unparseable, Beacon prints one boot warning
+to stderr and then behaves the same as `c.enabled = false` — no crash,
+no spam, no network traffic.
+
+### A note on the fork hook
+
+Because the Railtie prepends `Process._fork`, Beacon's `after_fork` runs in
+**every** forked child in the process — not just Puma workers. Short-lived
+forks like `rails runner`, `system`, and `Open3` subshells will briefly
+initialize Beacon in the child. The reinit is idempotent and the flusher is
+bounded, but it's a global behavior worth knowing about when you see
+`beacon-flusher` threads show up in unexpected places.
+
+## Usage
+
+```ruby
+Beacon.track("signup.completed", user: current_user, plan: "pro")
+Beacon.track("checkout.failed",  user: current_user, reason: "card_declined")
+Beacon.flush  # synchronous, drains the queue (rake tasks, shutdown)
+```
+
+## Hot-path guarantees
+
+- **<50µs added P95** on a reference Rack endpoint (enforced by
+  `spec/bench/rack_overhead_bench.rb` in CI — the bench fails the build if
+  the middleware regresses)
+- **Bounded queue** with oldest-drop semantics (default 10,000 events)
+- **Rescue-all** — Beacon never raises into the host application
+- **Fork-safe** — re-spawns the flusher in clustered Puma/Unicorn workers
+- **Idempotency keys** on every retry so safe retries never double-count
+
+See `.doc/definition/05-clients.md` and `.doc/definition/07-writing-a-client.md`
+in the Beacon repo for the full contract.
+
+## Development
+
+```bash
+gem install minitest rack
+rake test    # 32 tests, 102 assertions
+rake bench   # Rack overhead bench, fails if added P95 > 50µs
+rake         # both
+```
+
+The conformance fixtures live at `../../../spec/fixtures.json` (shared with
+the Go reference server). Fingerprint and path-normalization tests load
+those fixtures directly so client and server can never drift.

data/lib/beacon/client.rb

@@ -0,0 +1,132 @@
+require "beacon/queue"
+require "beacon/flusher"
+require "beacon/transport"
+
+module Beacon
+  # The top-level client. Owns the queue and the flusher, exposes track,
+  # implements fork safety. Beacon.track / Beacon.flush / Beacon.shutdown
+  # all delegate here.
+  class Client
+    LANGUAGE = "ruby".freeze
+
+    attr_reader :config, :queue, :flusher
+
+    def initialize(config:, transport: nil, autostart: true)
+      @config    = config
+      @enabled   = config.enabled?
+      # When disabled, build no transport and no flusher — the no-op
+      # path does not touch the network and does not spawn threads.
+      @transport = transport || (@enabled ? Transport::Http.new(config) : nil)
+      @queue     = Beacon::Queue.new(max: config.queue_size, flush_threshold: config.flush_threshold)
+      @pid       = Process.pid
+      @mutex     = Mutex.new
+      start_flusher if autostart && @enabled && config.async
+    end
+
+    # Outcomes API. The :user shorthand is the only magic — everything else
+    # in the properties hash flows through unchanged.
+    def track(name, properties = {})
+      return nil unless @enabled
+      return nil unless @config.pillar?(:outcomes)
+      props      = properties.dup
+      actor_type, actor_id = extract_actor(props)
+
+      push({
+        kind:          :outcome,
+        name:          name.to_s,
+        created_at_ns: realtime_ns,
+        actor_type:    actor_type,
+        actor_id:      actor_id,
+        properties:    props,
+        context:       base_context,
+      })
+    rescue => e
+      warn "[beacon] track failed: #{e.class}: #{e.message}"
+      nil
+    end
+
+    # Sink interface — what middleware and integrations push into.
+    def push(event)
+      return nil unless @enabled
+      ensure_forked!
+      @queue.push(event)
+    end
+    alias << push
+
+    def enabled?
+      @enabled
+    end
+
+    # Reconnect counter passthrough for Beacon.stats. Returns 0 when
+    # no transport is held (disabled client) or when the transport
+    # doesn't implement the counter (test doubles).
+    def transport_reconnects
+      return 0 unless @transport && @transport.respond_to?(:reconnects)
+      @transport.reconnects
+    end
+
+    def flush
+      @flusher&.flush_now
+    end
+
+    def shutdown
+      @flusher&.stop
+      @flusher = nil
+    end
+
+    # Re-spawn flusher in a forked child. Hosted servers (Puma clustered,
+    # Unicorn, Passenger) MUST call this in their on_worker_boot hook.
+    # Beacon detects forks lazily on the next push too — but explicit is
+    # cheaper than waiting for the first event.
+    def after_fork
+      @mutex.synchronize do
+        @pid     = Process.pid
+        @queue   = Beacon::Queue.new(max: @config.queue_size, flush_threshold: @config.flush_threshold)
+        @flusher = nil
+        # Drop any socket FD inherited from the parent — sharing one
+        # across parent and child is undefined. The transport will
+        # re-open lazily on the child's first flush.
+        @transport.after_fork if @transport.respond_to?(:after_fork)
+        start_flusher if @enabled && @config.async
+      end
+    end
+
+    private
+
+    def ensure_forked!
+      return if @pid == Process.pid
+      after_fork
+    end
+
+    def start_flusher
+      @flusher = Flusher.new(self, transport: @transport)
+      @flusher.start
+    end
+
+    # Extract actor_type / actor_id from the :user shorthand. user.id is
+    # stringified so UUIDs (Rails 7.1+), ULIDs, Snowflakes, and legacy
+    # integer IDs all land in the server's TEXT actor_id column without
+    # the caller having to know the difference. Stringifying an integer
+    # is free; skipping it for integers and stringifying for UUIDs would
+    # just be a branch with no upside.
+    def extract_actor(props)
+      user = props.delete(:user)
+      return [nil, nil] unless user
+      type = user.class.name
+      id   = user.respond_to?(:id) ? user.id : nil
+      [type, id.nil? ? nil : id.to_s]
+    end
+
+    def base_context
+      @base_context ||= {
+        environment: @config.environment,
+        deploy_sha:  @config.deploy_sha,
+        language:    LANGUAGE,
+      }.compact.freeze
+    end
+
+    def realtime_ns
+      Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
+    end
+  end
+end

data/lib/beacon/configuration.rb

@@ -0,0 +1,104 @@
+require "uri"
+
+module Beacon
+  class Configuration
+    attr_accessor :endpoint, :environment, :deploy_sha, :auth_token,
+                  :async, :app_root, :pillars,
+                  :flush_interval, :flush_threshold, :queue_size,
+                  :connect_timeout, :read_timeout,
+                  :cache_size, :enabled, :ambient
+
+    def initialize
+      @endpoint        = ENV["BEACON_ENDPOINT"] || "http://127.0.0.1:4680"
+      @environment     = ENV["BEACON_ENVIRONMENT"] || ENV["RAILS_ENV"] || "development"
+      @deploy_sha      = ENV["GIT_SHA"] || ENV["KAMAL_VERSION"]
+      @auth_token      = ENV["BEACON_AUTH_TOKEN"]
+      @async           = true
+      @app_root        = Dir.pwd
+      @pillars         = %i[outcomes perf errors]
+      @flush_interval  = 1.0
+      @flush_threshold = 100
+      @queue_size      = 10_000
+      @connect_timeout = 1.0
+      @read_timeout    = 2.0
+      # Shared cap for the middleware's LRU caches (per-request path
+      # name cache and per-fingerprint stack-throttle cache). One knob
+      # because both caches sit on the same Middleware instance, both
+      # are bounded for the same reason (protect against high-cardinality
+      # probes), and there is no realistic scenario where one should be
+      # tuned independently of the other.
+      @cache_size = 1024
+
+      # Ambient mode: when true, middleware sends kind: 'ambient' events
+      # for HTTP requests in addition to perf events.
+      @ambient = false
+
+      # Enrichment block: called on every request to provide dimensions
+      # (country, plan, locale, etc.) that flow to all event kinds.
+      @enrich_context_block = nil
+
+      # Global kill switch. When false, Beacon::Middleware is a
+      # passthrough, Beacon.track returns nil, and the flusher thread
+      # is not started.
+      #
+      # Default resolution (in priority order):
+      #   1. BEACON_DISABLED explicitly set → honored in both directions.
+      #        "1" / "true" / "yes" / "on"   → disabled
+      #        "0" / "false" / "no" / "off"  → forced enabled
+      #   2. RAILS_ENV / RACK_ENV is "test" → disabled.
+      #   3. Otherwise → enabled (development, staging, production).
+      #
+      # The test-env default matches Honeybadger/Sentry/AppSignal: an
+      # observability gem should not chatter across a hermetic test
+      # suite by default. A test that WANTS to assert Beacon was called
+      # (via Beacon::Testing::FakeTransport) opts back in locally, or
+      # sets BEACON_DISABLED=0 for the whole run.
+      @enabled = default_enabled
+    end
+
+    def enabled?
+      @enabled && endpoint_usable?
+    end
+
+    def pillar?(name)
+      @pillars.include?(name)
+    end
+
+    # Register or read the enrichment block. With a block: registers it.
+    # Without: returns the current block (or nil). The block receives a
+    # Rack request and returns a Hash of dimensions (e.g. { country: "US" }).
+    def enrich_context(&block)
+      if block
+        @enrich_context_block = block
+      else
+        @enrich_context_block
+      end
+    end
+
+    private
+
+    def default_enabled
+      v = ENV["BEACON_DISABLED"]
+      return !truthy_env?("BEACON_DISABLED") unless v.nil? || v.empty?
+      !test_environment?
+    end
+
+    def test_environment?
+      ENV["RAILS_ENV"] == "test" || ENV["RACK_ENV"] == "test"
+    end
+
+    def truthy_env?(name)
+      v = ENV[name]
+      return false if v.nil? || v.empty?
+      !%w[0 false no off].include?(v.downcase)
+    end
+
+    def endpoint_usable?
+      return false if endpoint.nil? || endpoint.to_s.empty?
+      URI.parse(endpoint.to_s)
+      true
+    rescue URI::InvalidURIError
+      false
+    end
+  end
+end

data/lib/beacon/enrichment.rb

@@ -0,0 +1,36 @@
+module Beacon
+  # Optional helpers for the `enrich_context` block. These are convenience
+  # methods — the block can return any Hash with string keys. None of these
+  # are required; an app that knows its users' countries from their profile
+  # doesn't need CDN header sniffing.
+  module Enrichment
+    # CDN geo headers checked in priority order: Cloudflare, Fastly,
+    # CloudFront. Returns a two-letter ISO 3166-1 country code or nil.
+    CDN_GEO_HEADERS = %w[
+      HTTP_CF_IPCOUNTRY
+      HTTP_FASTLY_GEO_COUNTRY
+      HTTP_CLOUDFRONT_VIEWER_COUNTRY
+    ].freeze
+
+    # Returns the two-letter ISO 3166-1 country code from CDN geo headers,
+    # or nil when no CDN header is present. Checks Cloudflare, Fastly, and
+    # CloudFront in order.
+    #
+    # Usage inside enrich_context:
+    #   c.enrich_context do |request|
+    #     { country: Beacon::Enrichment.country_from_cdn(request) }
+    #   end
+    def self.country_from_cdn(request)
+      env = request.respond_to?(:env) ? request.env : request
+      CDN_GEO_HEADERS.each do |header|
+        value = env[header]
+        next if value.nil? || value.empty?
+        code = value.strip.upcase
+        # "XX" is Cloudflare's "unknown" sentinel; skip it.
+        next if code == "XX"
+        return code if code.match?(/\A[A-Z]{2}\z/)
+      end
+      nil
+    end
+  end
+end

data/lib/beacon/fingerprint.rb

@@ -0,0 +1,16 @@
+require "digest/sha1"
+
+module Beacon
+  # Fingerprint algorithm — normative, see .doc/definition/06-http-api.md.
+  #   SHA1("<exception_class>|<first_app_frame_path>")
+  # Line numbers are intentionally excluded so cosmetic edits above the
+  # failing line don't shatter grouping across deploys.
+  module Fingerprint
+    LINE_SUFFIX = /:\d+\z/.freeze
+
+    def self.compute(exception_class, first_app_frame)
+      path = first_app_frame.to_s.sub(LINE_SUFFIX, "")
+      Digest::SHA1.hexdigest("#{exception_class}|#{path}")
+    end
+  end
+end