alplus-ruby 0.1.0

data/lib/alplus/stack.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Alplus
+  # Maps a Ruby backtrace to the wire `frames[]` shape
+  # (`{file, function, lineno, in_app}`) with in-app vs library detection.
+  #
+  # Prefers `Exception#backtrace_locations` (structured, available since
+  # Ruby 2.0) over parsing `#backtrace` strings; falls back to string
+  # parsing only for backtraces that don't expose locations (e.g. a
+  # synthetic backtrace assigned by hand).
+  module Stack
+    # Path fragments that mark a frame as library code regardless of
+    # `app_dirs`: installed gems, the Ruby stdlib, and common version
+    # manager layouts. Checked before `app_dirs`, so a gem vendored inside
+    # the app directory is still treated as library code.
+    LIBRARY_MARKERS = [
+      "/gems/",
+      "/lib/ruby/",
+      "/vendor/bundle/",
+      "/.rbenv/",
+      "/.rvm/",
+      "/.asdf/",
+      "<internal:"
+    ].freeze
+
+    LINE_PATTERN = /\A(.+):(\d+):in [`'"](.+)['"]\z/.freeze
+
+    # Longest source line kept in `pre_context`/`context_line`/
+    # `post_context` (issue: source-context frames) -- a single absurdly
+    # long line (minified/generated code) is truncated rather than blowing
+    # up the envelope.
+    MAX_SOURCE_LINE_CHARS = 500
+
+    # Per-process cache of a source file's lines. A deep in-app backtrace,
+    # or an error storm, otherwise re-reads the same files on the capturing
+    # thread on every event. Source does not change within a process, so
+    # each file is read at most once. Bounded (FIFO eviction) so it cannot
+    # grow without limit.
+    MAX_CACHED_SOURCE_FILES = 256
+    SOURCE_CACHE = {}
+    SOURCE_CACHE_MUTEX = Mutex.new
+    private_constant :SOURCE_CACHE, :SOURCE_CACHE_MUTEX
+
+    module_function
+
+    # `context_lines:` (default `0`, i.e. disabled) is `config.context_lines`
+    # at call sites -- see `Envelope.exception_item`. Source context is only
+    # ever attached to `in_app` frames: library/gem frames have no value to
+    # a host app's developer and reading arbitrary gem source is wasted
+    # work.
+    def frames_for(exception, app_dirs: [], context_lines: 0)
+      locations = exception.respond_to?(:backtrace_locations) ? exception.backtrace_locations : nil
+      if locations
+        locations.map { |loc| build_frame(loc.path, loc.lineno, loc.label, app_dirs, context_lines) }
+      else
+        Array(exception.backtrace).filter_map { |line| frame_from_line(line, app_dirs, context_lines) }
+      end
+    end
+
+    def build_frame(path, lineno, label, app_dirs, context_lines = 0)
+      in_app = in_app?(path, app_dirs)
+      frame = { file: path, lineno: lineno, function: label, in_app: in_app }
+      frame.merge!(source_context(path, lineno, context_lines)) if in_app && context_lines.to_i.positive?
+      frame.compact
+    end
+
+    def frame_from_line(line, app_dirs, context_lines = 0)
+      match = LINE_PATTERN.match(line)
+      return nil unless match
+
+      build_frame(match[1], match[2].to_i, match[3], app_dirs, context_lines)
+    end
+
+    # Reads `context_lines` lines before/after `lineno` (1-indexed, as
+    # backtraces report it) from `path`. Returns `{}` (attaching nothing)
+    # for a missing/unreadable file or an out-of-range line number --
+    # never raises, matching every other fail-safe boundary in this SDK.
+    def source_context(path, lineno, context_lines)
+      return {} unless path && File.file?(path) && File.readable?(path)
+
+      lines = cached_source_lines(path)
+      index = lineno - 1
+      return {} unless index >= 0 && index < lines.length
+
+      start_index = [index - context_lines, 0].max
+      end_index = [index + context_lines, lines.length - 1].min
+
+      {
+        pre_context: lines[start_index...index].map { |line| cap_source_line(line) },
+        context_line: cap_source_line(lines[index]),
+        post_context: lines[(index + 1)..end_index].map { |line| cap_source_line(line) }
+      }
+    rescue StandardError
+      {}
+    end
+
+    # Returns `path`'s lines, reading from disk at most once per process.
+    # FIFO-evicts the oldest entry past the cap. Holds the mutex across the
+    # read so concurrent captures of the same file do not each read it.
+    def cached_source_lines(path)
+      SOURCE_CACHE_MUTEX.synchronize do
+        return SOURCE_CACHE[path] if SOURCE_CACHE.key?(path)
+
+        lines = File.readlines(path)
+        SOURCE_CACHE[path] = lines
+        SOURCE_CACHE.shift if SOURCE_CACHE.size > MAX_CACHED_SOURCE_FILES
+        lines
+      end
+    end
+
+    def cap_source_line(line)
+      line = line.chomp
+      line.length > MAX_SOURCE_LINE_CHARS ? line[0, MAX_SOURCE_LINE_CHARS] : line
+    end
+
+    def in_app?(path, app_dirs)
+      return false if path.nil?
+      return false if LIBRARY_MARKERS.any? { |marker| path.include?(marker) }
+      return true if app_dirs.empty?
+
+      app_dirs.any? { |dir| path.start_with?(dir.to_s) }
+    end
+  end
+end

data/lib/alplus/testing.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Alplus
+  # In-memory recorder for host tests. Start with `config.test_mode = true`.
+  #
+  #   Alplus.configure { |c| c.test_mode = true }
+  #   Alplus.capture_exception(error)
+  #   Alplus.flush
+  #   item = Alplus::Testing.events.first
+  module Testing
+    def self.events
+      Array(transport&.envelopes).flat_map { |envelope| envelope[:items] || [] }
+    end
+
+    def self.sessions
+      Array(transport&.session_envelopes).flat_map { |envelope| envelope[:items] || [] }
+    end
+
+    def self.reset!
+      Alplus.reset!
+    end
+
+    def self.transport
+      Alplus.initialized_client&.transport
+    end
+    private_class_method :transport
+  end
+end

data/lib/alplus/transport.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Alplus
+  # Sends one envelope to `POST /e/errors` over `Net::HTTP` with an explicit
+  # open/read timeout. Never raises: every transport failure (timeout,
+  # connection refused, 4xx/5xx, an unparseable response) is swallowed and
+  # reported as `:error`/`:rejected` so the caller (the background worker)
+  # can log it without ever propagating into the host app (issue #14 story
+  # 8).
+  #
+  # Retries a transient failure up to `Retry::MAX_ATTEMPTS` times with
+  # jittered exponential backoff, honoring a 429's `Retry-After` header
+  # (issue #15) — see `Retry` for the shared loop with `Heartbeat`. Runs on
+  # the existing background `Worker` thread, never the request thread.
+  class Transport
+    def initialize(config, sleeper: method(:sleep))
+      @config = config
+      @sleeper = sleeper
+    end
+
+    # `kind:` selects the ingest path (issue #12): `:error` (default) posts
+    # to `POST /e/errors`, `:session` to `POST /e/sessions`. The error
+    # envelope's shape and endpoint are unchanged — this is purely additive
+    # routing on the same `Worker` queue/thread.
+    def send_envelope(envelope, kind: :error)
+      body = JSON.generate(envelope)
+      return :oversized if body.bytesize > Envelope::MAX_ENVELOPE_BYTES
+
+      uri = URI.join(@config.endpoint, path_for(kind))
+      result = Retry.perform(sleeper: @sleeper) { post(uri, body) }
+      outcome(result)
+    end
+
+    private
+
+    def path_for(kind)
+      kind == :session ? "/e/sessions" : "/e/errors"
+    end
+
+    def post(uri, body)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @config.open_timeout
+      http.read_timeout = @config.read_timeout
+
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request["Content-Type"] = "application/json"
+      request["Authorization"] = "Bearer #{@config.key}"
+      request.body = body
+
+      http.request(request)
+    end
+
+    def outcome(result)
+      case result.outcome
+      when :sent then :sent
+      when :permanent then :rejected
+      else
+        if result.error
+          @config.logger&.warn("[alplus] transport failed: #{result.error.class}: #{result.error.message}")
+          :error
+        else
+          :rejected
+        end
+      end
+    end
+  end
+
+  # In-memory transport used when `config.test_mode` is true. Records every
+  # envelope it would have sent instead of touching the network, so specs
+  # can assert on the exact shape without a stubbed HTTP endpoint —
+  # `Alplus.test_transport.envelopes` (issue #14 story 9).
+  class TestTransport
+    attr_reader :envelopes, :session_envelopes
+
+    def initialize(*)
+      @envelopes = []
+      @session_envelopes = []
+    end
+
+    # `kind:` mirrors `Transport#send_envelope` (issue #12): a `:session`
+    # envelope records to `session_envelopes` instead of `envelopes`, so
+    # existing specs asserting on `envelopes` (error envelopes only) are
+    # unaffected by session traffic.
+    def send_envelope(envelope, kind: :error)
+      if kind == :session
+        @session_envelopes << envelope
+      else
+        @envelopes << envelope
+      end
+
+      :sent
+    end
+
+    def clear
+      @envelopes.clear
+      @session_envelopes.clear
+    end
+  end
+end

data/lib/alplus/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Alplus
+  VERSION = "0.1.0"
+  SDK_NAME = "alplus-ruby"
+
+  # Sentinel default for `user:` on `Client#capture_exception`/
+  # `#capture_message` — distinguishes "no per-call override given" (fall
+  # back to the ambient `Scope` user) from an explicit `user: nil` (clear
+  # the ambient user for this one capture), matching the JS SDK's
+  # `overrides.user !== undefined` check in `scope.ts`'s `mergeScope`.
+  UNSET = Object.new.freeze
+end

data/lib/alplus/worker.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module Alplus
+  # Background-thread sender with a bounded queue: `#enqueue` never blocks
+  # the caller. When the queue is full, the event is dropped (non-
+  # authoritative, matching the JS SDK's own batching drop behavior) rather
+  # than applying backpressure to the request thread (issue #14 story 7/8).
+  #
+  # The worker thread is lazily started on first enqueue and is never
+  # joined/killed explicitly: Ruby terminates all non-main threads when the
+  # process exits, so there is nothing to supervise for a short-lived
+  # script or a `Rack::Handler` process to leak.
+  #
+  # One `Worker` instance is ONE independent delivery lane: its own
+  # `SizedQueue` and its own background thread, fixed to one `kind:`
+  # (`:error` or `:session`) for its whole lifetime (issue #12 fix). A
+  # PRIOR version routed both kinds through a single shared queue/thread —
+  # a stalled or slow `/e/errors` POST (up to ~20s across
+  # `Retry::MAX_ATTEMPTS` retries) head-of-line-blocked every queued
+  # session behind it, and a full queue during an error storm silently
+  # dropped the next session, exactly when crash-free data matters most.
+  # `Client` now owns two `Worker`s so error backpressure can never delay
+  # or drop session delivery, or vice versa.
+  class Worker
+    def initialize(config, transport, kind: :error)
+      @config = config
+      @transport = transport
+      @kind = kind
+      @queue = SizedQueue.new(config.max_queue_size)
+      @mutex = Mutex.new
+      @thread = nil
+      # Outstanding work count: incremented (under `@mutex`) the moment an
+      # envelope is successfully pushed, decremented only after
+      # `Transport#send_envelope` returns. `SizedQueue#pop` removes an item
+      # from the queue *before* the worker thread finishes sending it, so
+      # `@queue.empty?` alone goes true while a send is still in flight —
+      # a concurrent `#flush`/`#close` reading only queue emptiness would
+      # return early (TOCTOU). Counting outstanding work instead of
+      # sampling a flag set after pop closes that window: the increment
+      # happens atomically with the enqueue that a caller already observed
+      # succeeding, not after some later point the reader could race.
+      @outstanding = 0
+    end
+
+    # Enqueues an envelope for background delivery on THIS worker's own
+    # lane (its `kind:`, fixed at construction). Returns `true` if queued,
+    # `false` if dropped because the queue is full. Never raises.
+    def enqueue(envelope)
+      @mutex.synchronize do
+        @queue.push(envelope, true)
+        @outstanding += 1
+      end
+      ensure_thread_started
+      true
+    rescue ThreadError
+      @config.logger&.warn("[alplus] #{@kind} queue full (max #{@config.max_queue_size}); dropping event")
+      false
+    end
+
+    # Blocks up to `timeout` seconds for the queue to drain and any
+    # in-flight send to finish. Returns `true` if it drained in time,
+    # `false` on timeout. Never raises.
+    def flush(timeout: 2)
+      deadline = Time.now + timeout
+      sleep(0.01) while !idle? && Time.now < deadline
+      idle?
+    end
+
+    def queue_size
+      @queue.size
+    end
+
+    private
+
+    def idle?
+      @mutex.synchronize { @outstanding.zero? }
+    end
+
+    def ensure_thread_started
+      return if @thread&.alive?
+
+      @mutex.synchronize do
+        next if @thread&.alive?
+
+        @thread = Thread.new { run }
+        @thread.abort_on_exception = false
+        @thread.report_on_exception = false if @thread.respond_to?(:report_on_exception=)
+      end
+    end
+
+    def run
+      loop do
+        envelope = @queue.pop
+        begin
+          @transport.send_envelope(envelope, kind: @kind)
+        rescue StandardError => e
+          @config.logger&.warn("[alplus] worker error: #{e.class}: #{e.message}")
+        ensure
+          @mutex.synchronize { @outstanding -= 1 }
+        end
+      end
+    end
+  end
+end

data/lib/alplus.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require_relative "alplus/version"
+require_relative "alplus/id"
+require_relative "alplus/scrubber"
+require_relative "alplus/configuration"
+require_relative "alplus/stack"
+require_relative "alplus/envelope"
+require_relative "alplus/retry"
+require_relative "alplus/transport"
+require_relative "alplus/worker"
+require_relative "alplus/dedup"
+require_relative "alplus/scope"
+require_relative "alplus/session"
+require_relative "alplus/pending_window"
+require_relative "alplus/client"
+require_relative "alplus/logger_breadcrumbs"
+require_relative "alplus/rack_middleware"
+require_relative "alplus/heartbeat"
+
+# Error reporting for `POST /e/errors` on AL+ Observe. Mirrors the wire
+# contract of `@alplus/sdk` (TypeScript) and the Elixir SDK (see
+# docs/ARCHITECTURE.md §8, docs/BUILD.md §5).
+#
+#   Alplus.configure do |config|
+#     config.key = ENV["ALPLUS_KEY"]      # alp_... ingest key, `ingest` scope
+#     config.environment = "production"
+#     config.release = "v1.2.3"
+#   end
+#
+#   Alplus.capture_exception(exception)
+#   Alplus.capture_message("something happened", level: "warning")
+#
+# Never raises into the host app: every public method here swallows its own
+# internal errors and always returns the generated `err_` event id.
+module Alplus
+  # Guards the `@client`/`@configuration` singleton memoization below.
+  # Module-level (not lazily built) so there is no first-access race on the
+  # mutex itself.
+  CLIENT_MUTEX = Mutex.new
+  private_constant :CLIENT_MUTEX
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration) if block_given?
+      CLIENT_MUTEX.synchronize { @client = nil }
+      configuration
+    end
+
+    # Memoized under a mutex: two threads racing the very first capture
+    # call must not each construct a `Client` (and, with it, a second
+    # background `Worker` thread).
+    def client
+      return @client if @client
+
+      CLIENT_MUTEX.synchronize { @client ||= Client.new(configuration) }
+    end
+
+    # The memoized client if one exists, without constructing it. The
+    # log-breadcrumb hook (issue #47) uses this: a boot-time log line must
+    # not force client construction before the host finishes configuring.
+    def initialized_client
+      @client
+    end
+
+    def capture_exception(exception, **options)
+      client.capture_exception(exception, **options)
+    rescue StandardError
+      Id.generate_event_id
+    end
+
+    def capture_message(message, **options)
+      client.capture_message(message, **options)
+    rescue StandardError
+      Id.generate_event_id
+    end
+
+    # Blocks up to `timeout` seconds for the background queue to drain.
+    # Mainly useful in tests and at the end of a short-lived script.
+    def flush(timeout: 2)
+      client.flush(timeout: timeout)
+    rescue StandardError
+      false
+    end
+
+    # Pings AL+ Monitor's `GET|POST /h/:token` for cron/job liveness
+    # (issue #16): `state:` is `"start"`, `"finish"` (the default), or
+    # `"fail"`. Reuses the same retry/backoff as event delivery (`Retry`).
+    # Fail-safe: never raises into the caller, always returns `nil`.
+    def heartbeat(token, state: "finish")
+      Heartbeat.ping(token, state: state, config: configuration)
+      nil
+    rescue StandardError
+      nil
+    end
+
+    # Request-scoped scope ergonomics (issue #17): set once (typically at
+    # the top of a request, e.g. in a `before_action`) and applied to every
+    # `capture_exception`/`capture_message` call for the rest of the
+    # current thread/request. See `Scope`. Every setter is fail-safe.
+    def set_user(user)
+      Scope.current.set_user(user)
+      nil
+    rescue StandardError
+      nil
+    end
+
+    def set_tag(key, value)
+      Scope.current.set_tag(key, value)
+      nil
+    rescue StandardError
+      nil
+    end
+
+    def set_context(name, data)
+      Scope.current.set_context(name, data)
+      nil
+    rescue StandardError
+      nil
+    end
+
+    def add_breadcrumb(message: nil, category: nil, level: nil, data: nil, ts: nil)
+      Scope.current.add_breadcrumb(message: message, category: category, level: level, data: data, ts: ts)
+      nil
+    rescue StandardError
+      nil
+    end
+
+    # Closes the current thread's request-scoped `Session` (issue #12), if
+    # one is active (see `RackMiddleware`): reports it to
+    # `POST /e/sessions` via `Client#report_session`. A no-op if no session
+    # is active. Fail-safe: never raises. Not typically called directly —
+    # `RackMiddleware` calls this once `@app.call` returns or raises.
+    def close_session
+      session = Session.current
+      return nil unless session
+
+      client.report_session(session)
+      nil
+    rescue StandardError
+      nil
+    end
+
+    # :nodoc: host tests use `Alplus::Testing`.
+    def test_transport
+      client.transport
+    end
+
+    # :nodoc: host tests use `Alplus::Testing.reset!`.
+    def reset!
+      CLIENT_MUTEX.synchronize { @client = nil }
+      @configuration = nil
+      Dedup.reset!
+    end
+  end
+end
+
+require_relative "alplus/testing"
+require_relative "alplus/railtie" if defined?(::Rails::Railtie)
+
+# Optional integrations (issue: SDK parity #4/#5): only loaded/activated
+# when the host app already loaded the corresponding library. Neither gem
+# is ever `require`d by this file, and this SDK never declares either as a
+# runtime dependency -- see `lib/alplus/sidekiq.rb`/`lib/alplus/active_job.rb`.
+#
+# This top-level block is the NON-RAILS fallback (or the case where the
+# host requires `sidekiq`/`active_job` before `alplus`). Under Rails,
+# `ActiveJob::Base` autoloads only after boot, so these `defined?` checks
+# are false when the gem loads; the Railtie re-runs the install after boot
+# with correct timing (see `railtie.rb`). `install!` is idempotent, so the
+# two paths never double-install.
+if defined?(::Sidekiq)
+  require_relative "alplus/sidekiq"
+  Alplus::Sidekiq.install!
+end
+
+if defined?(::ActiveJob::Base)
+  require_relative "alplus/active_job"
+  Alplus::ActiveJob.install!
+end