allstak 0.1.1 → 0.3.0

data/lib/allstak/transport/event_spool.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "json"
+require "tmpdir"
+require "fileutils"
+require "securerandom"
+
+module AllStak
+  module Transport
+    # Filesystem spool for un-sent telemetry envelopes (offline / outage /
+    # shutdown durability). One JSON file per envelope so a partially written
+    # file can be discarded without losing the rest of the queue.
+    #
+    # Wire-on-disk shape (already-scrubbed payload):
+    #   { "v" => 1, "path" => "/ingest/v1/errors", "payload" => {...},
+    #     "ts" => 1700000000.123 }
+    #
+    # Offline durability: an on-disk transport cache — events that cannot be
+    # delivered are persisted (PII-scrubbed) and replayed on the next init.
+    #
+    # HARD invariants:
+    #   * Fail-open everywhere. A read-only FS, a sandboxed/serverless runtime,
+    #     or any IO error degrades silently to in-memory behavior — never
+    #     raises, never blocks capture or init.
+    #   * Bounded by COUNT, BYTES, and AGE. When over a limit the OLDEST entry
+    #     is dropped first (files are time-ordered by an embedded counter).
+    #   * Caller scrubs BEFORE persist — the spool stores bytes verbatim and
+    #     does no scrubbing itself.
+    class EventSpool
+      FILE_PREFIX = "allstak-evt-"
+      FILE_SUFFIX = ".json"
+      FORMAT_VERSION = 1
+
+      # Sane server defaults: a few MB / ~100 envelopes / 48h.
+      DEFAULT_MAX_ENTRIES = 100
+      DEFAULT_MAX_BYTES   = 4 * 1024 * 1024 # 4 MiB
+      DEFAULT_MAX_AGE_S   = 48 * 60 * 60    # 48 hours
+
+      attr_reader :dir, :available
+
+      def initialize(dir: nil, max_entries: DEFAULT_MAX_ENTRIES,
+                     max_bytes: DEFAULT_MAX_BYTES, max_age_s: DEFAULT_MAX_AGE_S,
+                     logger: nil)
+        @logger      = logger
+        @max_entries = [max_entries.to_i, 1].max
+        @max_bytes   = [max_bytes.to_i, 1].max
+        @max_age_s   = max_age_s.to_i
+        @mutex       = Mutex.new
+        # Monotonic-ish ordering within a process so oldest-first eviction holds
+        # even when two writes land in the same wall-clock millisecond.
+        @seq         = 0
+        @dir         = resolve_dir(dir)
+        @available   = ensure_dir(@dir)
+      end
+
+      def available?
+        @available
+      end
+
+      # Persist one already-scrubbed envelope. `payload` MUST be a Ruby object
+      # (Hash/Array) that has ALREADY been run through the PII sanitizer by the
+      # caller. Fail-open: returns true on write, false on any problem.
+      def persist(path, payload)
+        return false unless @available
+
+        @mutex.synchronize do
+          begin
+            seq = (@seq += 1)
+            record = {
+              "v"       => FORMAT_VERSION,
+              "path"    => path.to_s,
+              "payload" => payload,
+              "ts"      => Time.now.to_f,
+              "seq"     => seq
+            }
+            json = JSON.generate(record)
+            return false if json.bytesize > @max_bytes # single oversized entry — skip
+
+            name = format("%s%013d-%06d-%s%s",
+                          FILE_PREFIX, (Time.now.to_f * 1000).to_i, seq,
+                          SecureRandom.hex(4), FILE_SUFFIX)
+            tmp  = File.join(@dir, "." + name + ".tmp")
+            dest = File.join(@dir, name)
+            File.open(tmp, "wb") { |f| f.write(json) }
+            File.rename(tmp, dest) # atomic publish
+            enforce_bounds_locked
+            true
+          rescue StandardError => e
+            @logger&.debug("[AllStak] spool persist failed: #{e.class}: #{e.message}")
+            # Best-effort cleanup of a stray temp file.
+            begin
+              File.unlink(tmp) if tmp && File.exist?(tmp)
+            rescue StandardError
+              nil
+            end
+            false
+          end
+        end
+      end
+
+      # Yield each persisted entry (oldest first) as [path, payload, handle].
+      # The caller decides per entry whether to {#remove}(handle) it (delivered
+      # or permanently undeliverable) or leave it for a future drain. Stale
+      # entries past max-age are dropped (and never yielded). Fail-open: yields
+      # nothing on any error.
+      def each
+        return unless @available
+        return unless block_given?
+
+        entries =
+          @mutex.synchronize do
+            drop_stale_locked
+            sorted_files_locked
+          end
+
+        entries.each do |file|
+          record =
+            begin
+              JSON.parse(File.read(file))
+            rescue StandardError => e
+              @logger&.debug("[AllStak] spool entry unreadable, dropping: #{e.class}: #{e.message}")
+              remove(file)
+              next
+            end
+          path    = record.is_a?(Hash) ? record["path"] : nil
+          payload = record.is_a?(Hash) ? record["payload"] : nil
+          if path.to_s.empty? || payload.nil?
+            remove(file)
+            next
+          end
+          yield(path, payload, file)
+        end
+      end
+
+      # Delete one entry by its handle (the file path yielded by {#each}).
+      # Fail-open.
+      def remove(handle)
+        return unless @available
+        File.unlink(handle) if handle && File.exist?(handle)
+      rescue StandardError => e
+        @logger&.debug("[AllStak] spool remove failed: #{e.class}: #{e.message}")
+      end
+
+      # Current persisted entry count (best-effort; for tests/diagnostics).
+      def size
+        return 0 unless @available
+        @mutex.synchronize { sorted_files_locked.length }
+      rescue StandardError
+        0
+      end
+
+      private
+
+      def resolve_dir(dir)
+        base = dir.to_s.strip
+        base.empty? ? File.join(Dir.tmpdir, "allstak-spool") : base
+      rescue StandardError
+        File.join(Dir.tmpdir, "allstak-spool")
+      end
+
+      # Create the dir if needed and confirm it is writable. Returns false (and
+      # disables the spool) on any failure — read-only FS, permission denied,
+      # serverless ephemeral-but-unwritable, etc.
+      def ensure_dir(path)
+        FileUtils.mkdir_p(path)
+        File.directory?(path) && File.writable?(path)
+      rescue StandardError => e
+        @logger&.debug("[AllStak] spool dir unavailable (#{path}): #{e.class}: #{e.message}")
+        false
+      end
+
+      # Files sorted oldest-first. The embedded zero-padded millis+seq prefix
+      # makes a plain lexical sort chronological.
+      def sorted_files_locked
+        Dir.glob(File.join(@dir, "#{FILE_PREFIX}*#{FILE_SUFFIX}")).sort
+      rescue StandardError
+        []
+      end
+
+      def drop_stale_locked
+        return if @max_age_s <= 0
+        cutoff = Time.now - @max_age_s
+        sorted_files_locked.each do |file|
+          begin
+            File.unlink(file) if File.mtime(file) < cutoff
+          rescue StandardError
+            nil
+          end
+        end
+      end
+
+      # Enforce count + byte caps, dropping OLDEST first. Called under @mutex.
+      def enforce_bounds_locked
+        files = sorted_files_locked
+
+        # Count cap.
+        while files.length > @max_entries
+          victim = files.shift
+          safe_unlink(victim)
+        end
+
+        # Byte cap.
+        total = 0
+        sizes = files.map do |f|
+          s = begin
+            File.size(f)
+          rescue StandardError
+            0
+          end
+          total += s
+          [f, s]
+        end
+        while total > @max_bytes && !sizes.empty?
+          file, s = sizes.shift
+          safe_unlink(file)
+          total -= s
+        end
+      end
+
+      def safe_unlink(file)
+        File.unlink(file) if file && File.exist?(file)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/allstak/transport/http_transport.rb

@@ -1,6 +1,8 @@
 require "net/http"
 require "uri"
 require "json"
+require_relative "../sanitizer"
+require_relative "event_spool"
 
 module AllStak
   module Transport
@@ -19,6 +21,17 @@ module AllStak
     class HttpTransport
       NON_RETRYABLE_STATUSES = [400, 401, 403, 404, 422].freeze
       BACKOFF_DELAYS = [1.0, 2.0, 4.0, 8.0].freeze
+      # Statuses for which we honor a server-provided Retry-After header.
+      RETRY_AFTER_STATUSES = [429, 503].freeze
+      # Upper bound on any honored Retry-After delay, in seconds.
+      MAX_RETRY_AFTER = 300.0
+
+      # Session lifecycle calls are best-effort LIVE-only — a replayed stale
+      # session would skew durations, so they are NEVER spooled to disk.
+      NON_PERSISTABLE_PATHS = [
+        "/ingest/v1/sessions/start",
+        "/ingest/v1/sessions/end"
+      ].freeze
 
       attr_reader :disabled
 
@@ -28,6 +41,71 @@ module AllStak
         @base_url = config.host
         @api_key = config.api_key
         @disabled = false
+        @spool = build_spool(config, logger)
+      end
+
+      # The offline spool, or nil when disabled / unavailable. Exposed for
+      # diagnostics + tests.
+      attr_reader :spool
+
+      # True when this path's telemetry is eligible for the persistent spool.
+      # Excludes session lifecycle calls (live-only) and is a no-op when the
+      # spool is disabled/unavailable.
+      def persistable?(path)
+        return false unless @spool&.available?
+        !NON_PERSISTABLE_PATHS.include?(path.to_s)
+      end
+
+      # Persist a payload that could not be delivered. The payload is scrubbed
+      # through the SAME PII sanitizer used on the wire BEFORE it touches disk —
+      # secrets never get persisted. Fail-open: returns false and never raises.
+      # Session lifecycle paths are skipped.
+      def persist_failed(path, payload)
+        return false unless persistable?(path)
+        scrubbed =
+          begin
+            parsed = payload.is_a?(String) ? JSON.parse(payload) : payload
+            AllStak::Sanitizer.scrub(parsed, **scrub_options)
+          rescue StandardError => e
+            @logger.debug("[AllStak] spool scrub failed; not persisting: #{e.class}: #{e.message}") if @config.debug
+            return false
+          end
+        @spool.persist(path, scrubbed)
+      rescue StandardError => e
+        @logger.debug("[AllStak] persist_failed swallowed: #{e.class}: #{e.message}") if @config.debug
+        false
+      end
+
+      # Replay persisted envelopes through the live transport. An entry is
+      # removed only when it is ACCEPTED (2xx) or PERMANENTLY undeliverable
+      # (a 4xx that is not 429) — anything else (network error, 5xx, 429) leaves
+      # it on disk for a future drain. Honors the existing retry/backoff and the
+      # 401-disable circuit breaker. Fully fail-open; never raises.
+      def drain_spool
+        return unless @spool&.available?
+        @spool.each do |path, payload, handle|
+          break if @disabled
+          begin
+            status, _ = post(path, payload)
+            # post() returns for 2xx and non-retryable 4xx; raises otherwise.
+            if status && (status < 400 || (status >= 400 && status != 429))
+              @spool.remove(handle)
+            end
+          rescue AllStakAuthError
+            # 401 disabled the SDK mid-drain: stop, keep remaining entries.
+            break
+          rescue AllStakTransportError => e
+            # Retries exhausted (network/5xx/429): keep the entry, stop draining
+            # so we don't hammer a down endpoint.
+            @logger.debug("[AllStak] drain stopped (still undeliverable): #{e.message}") if @config.debug
+            break
+          rescue StandardError => e
+            @logger.debug("[AllStak] drain entry error: #{e.class}: #{e.message}") if @config.debug
+            break
+          end
+        end
+      rescue StandardError => e
+        @logger.debug("[AllStak] drain_spool swallowed: #{e.class}: #{e.message}") if @config.debug
       end
 
       def disabled?
@@ -37,6 +115,8 @@ module AllStak
       def post(path, payload)
         raise AllStakAuthError, "SDK disabled" if @disabled
 
+        wire_payload = serialize_payload(payload)
+
         uri = URI.parse("#{@base_url}#{path}")
         http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = (uri.scheme == "https")
@@ -45,16 +125,18 @@ module AllStak
 
         last_exc = nil
         last_status = 0
+        retry_after_delay = nil
         max_attempts = [[@config.max_retries.to_i, 1].max, 5].min
 
         (1..max_attempts).each do |attempt|
+          retry_after_delay = nil
           begin
             req = Net::HTTP::Post.new(uri.request_uri, {
               "Content-Type"   => "application/json",
               "X-AllStak-Key"  => @api_key,
               "User-Agent"     => "allstak-ruby/#{AllStak::VERSION}"
             })
-            req.body = payload.is_a?(String) ? payload : JSON.generate(payload)
+            req.body = wire_payload
             @logger.debug("[AllStak] POST #{path} attempt=#{attempt}") if @config.debug
 
             resp = http.request(req)
@@ -70,7 +152,13 @@ module AllStak
             return [last_status, body] if NON_RETRYABLE_STATUSES.include?(last_status)
             return [last_status, body] if last_status < 400
 
-            # 5xx → retry
+            # 429 (rate limited) / 503 (unavailable) → honor Retry-After when present.
+            if RETRY_AFTER_STATUSES.include?(last_status)
+              parsed = parse_retry_after(resp["Retry-After"])
+              retry_after_delay = parsed if parsed > 0
+            end
+
+            # 5xx / 429 → retry
           rescue AllStakAuthError
             raise
           rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED, Errno::ECONNRESET,
@@ -83,15 +171,90 @@ module AllStak
           end
 
           if attempt < max_attempts
-            delay = BACKOFF_DELAYS[[attempt - 1, BACKOFF_DELAYS.length - 1].min]
-            delay += rand * 0.5
-            sleep(delay)
+            if retry_after_delay
+              # Server told us how long to wait; honor it (already clamped).
+              sleep(retry_after_delay)
+            else
+              delay = BACKOFF_DELAYS[[attempt - 1, BACKOFF_DELAYS.length - 1].min]
+              delay += rand * 0.5
+              sleep(delay)
+            end
           end
         end
 
         raise AllStakTransportError,
               "All #{max_attempts} attempts failed for POST #{path}. last_status=#{last_status} last_error=#{last_exc&.message}"
       end
+
+      def serialize_payload(payload)
+        parsed = payload.is_a?(String) ? JSON.parse(payload) : payload
+        JSON.generate(AllStak::Sanitizer.scrub(parsed, **scrub_options))
+      rescue StandardError => san_err
+        @logger.warn("[AllStak] sanitizer failed; dropping payload: #{san_err.class}: #{san_err.message}")
+        raise AllStakTransportError, "sanitizer failed; payload dropped"
+      end
+
+      # Sanitizer options derived from config. Guarded with respond_to? so a
+      # bare/stub config (some transport unit tests) still scrubs with safe
+      # defaults: PII off (privacy-safe), no extra denylist.
+      def scrub_options
+        {
+          send_default_pii: @config.respond_to?(:send_default_pii?) ? @config.send_default_pii? : false,
+          extra_denylist:   (@config.respond_to?(:extra_denylist) ? @config.extra_denylist : nil)
+        }
+      end
+
+      # Parse an HTTP `Retry-After` header into a non-negative delay in seconds.
+      #
+      # Supports both forms from RFC 7231 §7.1.3:
+      #   - delta-seconds: an integer number of seconds ("120" → 120.0)
+      #   - HTTP-date:     an absolute date; returns the delta from `now`
+      #
+      # Returns 0.0 when the header is absent, blank, malformed, or resolves
+      # to a non-positive delay (e.g. a date in the past). The result is
+      # clamped to {MAX_RETRY_AFTER}. Pure and side-effect free.
+      def parse_retry_after(header, now = Time.now)
+        return 0.0 if header.nil?
+
+        value = header.to_s.strip
+        return 0.0 if value.empty?
+
+        seconds =
+          if value.match?(/\A\d+\z/)
+            value.to_i.to_f
+          else
+            begin
+              # HTTP-date (RFC 1123 / RFC 850 / asctime). httpdate raises on junk.
+              target = Time.httpdate(value)
+              target - now
+            rescue ArgumentError
+              return 0.0
+            end
+          end
+
+        return 0.0 if seconds.nil? || seconds <= 0
+        [seconds.to_f, MAX_RETRY_AFTER].min
+      end
+
+      private
+
+      # Build the offline spool from config, or nil when opted out. The spool
+      # itself fails open (an unwritable dir leaves it `available? == false`),
+      # so a non-nil-but-unavailable spool is fine — every public method guards
+      # on `available?`. Never raises.
+      def build_spool(config, logger)
+        return nil unless config.respond_to?(:enable_offline_queue)
+        return nil unless config.enable_offline_queue
+
+        opts = { dir: config.offline_queue_dir, logger: logger }
+        opts[:max_entries] = config.offline_queue_max_entries if config.offline_queue_max_entries
+        opts[:max_bytes]   = config.offline_queue_max_bytes   if config.offline_queue_max_bytes
+        opts[:max_age_s]   = config.offline_queue_max_age_s   if config.offline_queue_max_age_s
+        EventSpool.new(**opts)
+      rescue StandardError => e
+        logger&.debug("[AllStak] offline spool init failed; in-memory only: #{e.class}: #{e.message}")
+        nil
+      end
     end
   end
 end

data/lib/allstak/version.rb

@@ -1,3 +1,3 @@
 module AllStak
-  VERSION = "0.1.1"
+  VERSION = "0.3.0"
 end

data/lib/allstak.rb

@@ -6,6 +6,10 @@ require_relative "allstak/config"
 require_relative "allstak/transport/http_transport"
 require_relative "allstak/transport/flush_buffer"
 require_relative "allstak/models/user_context"
+require_relative "allstak/propagation"
+require_relative "allstak/sampling"
+require_relative "allstak/session_tracker"
+require_relative "allstak/global_handler"
 require_relative "allstak/modules/errors"
 require_relative "allstak/modules/logs"
 require_relative "allstak/modules/http_monitor"
@@ -16,6 +20,15 @@ require_relative "allstak/client"
 require_relative "allstak/integrations/rack"
 require_relative "allstak/integrations/active_record"
 require_relative "allstak/integrations/net_http"
+require_relative "allstak/integrations/sidekiq"
+# Optional structured-log adapter. Defined on require but NOT auto-attached —
+# it only ships logs once the app opts in via Logger.attach_to_rails! /
+# Logger.broadcast, so existing logging behavior is preserved by default.
+require_relative "allstak/integrations/logger"
+# The Rails Railtie self-installs on require when Rails is present, and is a
+# guarded no-op otherwise. Loading it here means Rails apps that `require
+# "allstak"` get the Rack middleware auto-wired without manual setup.
+require_relative "allstak/integrations/rails"
 
 # Official AllStak Ruby SDK.
 #
@@ -30,8 +43,10 @@ require_relative "allstak/integrations/net_http"
 #     c.service_name = "myapp-api"
 #   end
 #
-#   # Rack / Rails: add the middleware
+#   # Rails: auto-installed via Railtie — no manual wiring needed.
+#   # Plain Rack: add the middleware yourself
 #   use AllStak::Integrations::Rack::Middleware
+#   # Sidekiq: server middleware auto-registered on configure.
 #
 #   # Manual:
 #   AllStak.capture_exception(exc)
@@ -47,15 +62,45 @@ module AllStak
       @mutex.synchronize do
         @config ||= Config.new
         yield @config if block_given?
+        # Resolve release now that explicit user config has been applied:
+        # explicit > env (set in #initialize) > local git > SDK version.
+        @config.finalize_release!
         @logger = Logger.new($stderr).tap do |l|
           l.level = @config.debug ? Logger::DEBUG : Logger::WARN
           l.progname = "allstak"
         end
         if @config.valid?
           @client = Client.new(@config, @logger)
+          register_runtime_release(@config, @logger)
+          # Release-health: open one session per process now that config +
+          # release are resolved. Idempotent + fully fail-open; self-disables
+          # under a unit-test runtime and when enable_auto_session_tracking is
+          # false.
+          @client.start_session
+          # Offline durability: replay telemetry persisted by a previous
+          # process/outage through the live transport (respects retry/backoff +
+          # circuit breaker). Async + fully fail-open; no-op when disabled.
+          @client.drain_offline_queue
           # Auto-wire integrations that are safe to install
           AllStak::Integrations::ActiveRecordIntegration::Subscriber.install!
           AllStak::Integrations::NetHTTP.install!
+          # Sidekiq + Rails self-guard: each is a graceful no-op when its host
+          # framework is absent, and idempotent when present.
+          AllStak::Integrations::Sidekiq.install!
+          AllStak::Integrations::Rails.install!
+          # Global uncaught-exception capture via at_exit. Idempotent and
+          # opt-out via config.install_at_exit_handler.
+          if @config.install_at_exit_handler
+            # report_on_exception makes Ruby print (and lets us reason about)
+            # exceptions that kill non-main threads; keep it on so background
+            # thread crashes are at least visible. Best-effort.
+            begin
+              Thread.report_on_exception = true if Thread.respond_to?(:report_on_exception=)
+            rescue StandardError
+              # never let observability config break startup
+            end
+            AllStak::GlobalHandler.install!(@logger)
+          end
         else
           @logger.warn("[AllStak] api_key not set — SDK not started")
           @client = nil
@@ -72,6 +117,32 @@ module AllStak
       @client or raise "AllStak not configured. Call AllStak.configure { |c| ... } first."
     end
 
+    def register_runtime_release(config, logger)
+      return unless config.auto_register_release
+      return if config.release.to_s.empty? || config.api_key.to_s.empty?
+      return if ENV["MT_TEST"] ||
+                ENV["RACK_ENV"] == "test" ||
+                ENV["RAILS_ENV"] == "test" ||
+                ENV["RUBYOPT"].to_s.include?("minitest") ||
+                $PROGRAM_NAME.to_s.include?("rspec")
+
+      thread = Thread.new do
+        begin
+          AllStak::Transport::HttpTransport.new(config, logger).post("/ingest/v1/releases", {
+            version: config.release,
+            environment: config.environment || "production",
+            commitSha: config.commit_sha,
+            branch: config.branch,
+            author: "#{config.sdk_name}/#{config.sdk_version}",
+            message: "Registered automatically by AllStak Ruby SDK at runtime"
+          })
+        rescue StandardError => e
+          logger.debug("[AllStak] runtime release registration failed: #{e.class}: #{e.message}") if logger
+        end
+      end
+      thread.abort_on_exception = false
+    end
+
     def capture_exception(exc, **kw)
       @client&.capture_exception(exc, **kw)
     end
@@ -87,6 +158,24 @@ module AllStak
       @client&.capture_message(message, level: level, **kw)
     end
 
+    # Manually capture an exception as a global, *unhandled* event
+    # (mechanism=at_exit, handled=false) and flush synchronously. Use this at
+    # the top of a worker/thread/process boundary where the framework would
+    # not otherwise route the exception through the Rack middleware. Safe
+    # no-op when the SDK is not configured.
+    def capture_unhandled(exc)
+      AllStak::GlobalHandler.capture_unhandled(exc)
+    end
+
+    # Manually record a breadcrumb on the current thread's ring buffer. It is
+    # attached to the next captured exception on this thread. Cross-SDK parity
+    # with JS addBreadcrumb / Python add_breadcrumb. Safe no-op when the SDK is
+    # not configured. Manual breadcrumbs are always recorded (independent of
+    # the enable_auto_breadcrumbs toggle, which only gates auto-instrumentation).
+    def add_breadcrumb(type:, message:, level: "info", data: nil)
+      @client&.errors&.add_breadcrumb(type: type, message: message, level: level, data: data)
+    end
+
     def set_user(**kw)
       @client&.set_user(**kw)
     end