auditea 0.1.0.beta.1

data/lib/auditea/transport/http.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Auditea
+  module Transport
+    class Http
+      DEFAULT_SLEEPER = ->(seconds) { sleep(seconds) }
+
+      def initialize(configuration, sleeper: DEFAULT_SLEEPER, random: Random.new)
+        @configuration = configuration
+        @sleeper = sleeper
+        @random = random
+      end
+
+      def post_event(event)
+        body = JSON.generate("event" => event)
+        request(@configuration.events_url, body, single: true, event_id: event["event_id"])
+      end
+
+      def post_batch(events)
+        body = JSON.generate("events" => events)
+        request(@configuration.event_batches_url, body, single: false, events: events)
+      end
+
+      private
+
+      def request(url, body, single:, event_id: nil, events: nil)
+        uri = URI.parse(url)
+        attempts = 0
+        max_attempts = @configuration.max_retries + 1
+
+        begin
+          attempts += 1
+          response = perform(uri, body)
+          result = classify(response, single: single, event_id: event_id, events: events)
+          return result unless result.retryable?
+
+          raise TransientError.new(result.message || "retryable HTTP #{result.status}", status: result.status)
+        rescue TransientError => error
+          if attempts >= max_attempts
+            return DeliveryResult.transient_failure(
+              outcome: :exhausted,
+              message: safe_message(error),
+              event_id: event_id,
+              status: error.status
+            )
+          end
+
+          backoff(attempts)
+          retry
+        rescue StandardError => error
+          raise if fatal_client_error?(error)
+
+          if attempts >= max_attempts
+            return DeliveryResult.transient_failure(
+              outcome: :exhausted,
+              message: safe_message(error),
+              event_id: event_id,
+              status: error.respond_to?(:status) ? error.status : nil
+            )
+          end
+
+          backoff(attempts)
+          retry
+        end
+      end
+
+      def fatal_client_error?(error)
+        error.is_a?(ConfigurationError) ||
+          error.is_a?(ArgumentError) ||
+          error.is_a?(NoMethodError) ||
+          error.is_a?(NameError) ||
+          error.is_a?(TypeError)
+      end
+
+      def perform(uri, body)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER if http.use_ssl?
+        http.open_timeout = @configuration.open_timeout
+        http.read_timeout = @configuration.timeout
+        http.write_timeout = @configuration.write_timeout if http.respond_to?(:write_timeout=)
+        http.max_retries = 0 if http.respond_to?(:max_retries=)
+
+        req = Net::HTTP::Post.new(uri.request_uri)
+        req["Content-Type"] = "application/json"
+        req["Accept"] = "application/json"
+        req["Authorization"] = "Bearer #{@configuration.source_token}"
+        req["User-Agent"] = "auditea-ruby/#{VERSION}"
+        req.body = body
+
+        http.request(req)
+      end
+
+      def classify(response, single:, event_id:, events:)
+        status = response.code.to_i
+        parsed = safe_parse(response.body)
+
+        case status
+        when 201
+          DeliveryResult.success(
+            status: status,
+            outcome: :accepted,
+            event_id: (parsed["event_id"] if parsed.is_a?(Hash)) || event_id,
+            body: parsed
+          )
+        when 200
+          if single
+            DeliveryResult.success(
+              status: status,
+              outcome: :duplicate,
+              event_id: (parsed["event_id"] if parsed.is_a?(Hash)) || event_id,
+              body: parsed
+            )
+          else
+            classify_batch(status, parsed, events)
+          end
+        when 409
+          DeliveryResult.permanent_failure(
+            status: status, outcome: :conflict,
+            event_id: (parsed["event_id"] if parsed.is_a?(Hash)) || event_id,
+            message: "conflict", body: parsed
+          )
+        when 422
+          DeliveryResult.permanent_failure(
+            status: status, outcome: :invalid,
+            event_id: (parsed["event_id"] if parsed.is_a?(Hash)) || event_id,
+            message: "validation_failed", body: parsed
+          )
+        when 401
+          DeliveryResult.permanent_failure(
+            status: status, outcome: :unauthorized,
+            event_id: event_id, message: "unauthorized", body: parsed
+          )
+        when 413
+          DeliveryResult.permanent_failure(
+            status: status, outcome: :payload_too_large,
+            event_id: event_id, message: "payload_too_large", body: parsed
+          )
+        when 415
+          DeliveryResult.permanent_failure(
+            status: status, outcome: :unsupported_media,
+            event_id: event_id, message: "unsupported_media", body: parsed
+          )
+        when 429
+          DeliveryResult.transient_failure(
+            status: status, outcome: :rate_limited,
+            message: "rate_limited", event_id: event_id
+          )
+        when 300..399
+          DeliveryResult.permanent_failure(
+            status: status, outcome: :redirect,
+            event_id: event_id, message: "redirect_not_followed", body: parsed
+          )
+        when 500..599
+          DeliveryResult.transient_failure(
+            status: status, outcome: :server_error,
+            message: "server_error", event_id: event_id
+          )
+        else
+          DeliveryResult.permanent_failure(
+            status: status, outcome: :unexpected_status,
+            event_id: event_id, message: "unexpected_status_#{status}", body: parsed
+          )
+        end
+      end
+
+      def classify_batch(status, parsed, events)
+        rows = Array(parsed.is_a?(Hash) ? parsed["results"] : nil)
+        by_index = {}
+        rows.each do |row|
+          next unless row.is_a?(Hash)
+
+          idx = row["index"]
+          by_index[idx] = row if idx.is_a?(Integer)
+        end
+
+        results = (events || []).each_with_index.map do |event, index|
+          row = by_index[index]
+          if row.nil?
+            {
+              "index" => index,
+              "status" => "missing_result",
+              "event_id" => event["event_id"],
+              "outcome" => "missing_result",
+              "ok" => false,
+              "retryable" => false
+            }
+          else
+            status_name = row["status"].to_s
+            outcome =
+              case status_name
+              when "accepted" then "accepted"
+              when "duplicate" then "duplicate"
+              when "conflict" then "conflict"
+              when "invalid" then "invalid"
+              else "unknown"
+              end
+            success = %w[accepted duplicate].include?(outcome)
+            {
+              "index" => index,
+              "status" => status_name,
+              "event_id" => row["event_id"] || event["event_id"],
+              "outcome" => outcome,
+              "ok" => success,
+              "retryable" => false
+            }
+          end
+        end
+
+        DeliveryResult.new(
+          ok: results.all? { |row| row["ok"] },
+          status: status,
+          outcome: :batch,
+          permanent: true,
+          retryable: false,
+          body: parsed,
+          results: results,
+          message: results.all? { |row| row["ok"] } ? nil : "mixed_batch_results"
+        )
+      end
+
+      def safe_parse(body)
+        text = body.to_s.byteslice(0, Limits::MAX_RESPONSE_BYTES).to_s
+        return {} if text.empty?
+
+        JSON.parse(text)
+      rescue JSON::ParserError
+        { "parse_error" => true, "snippet" => text.byteslice(0, 120) }
+      end
+
+      def backoff(attempt)
+        base = 0.05 * (2**(attempt - 1))
+        jitter = @random.rand * 0.05
+        @sleeper.call(base + jitter)
+      end
+
+      def safe_message(error)
+        "#{error.class}: #{error.message.to_s.byteslice(0, 200)}"
+      end
+
+      class TransientError < ::Auditea::Error
+        attr_reader :status
+
+        def initialize(message, status: nil)
+          super(message)
+          @status = status
+        end
+      end
+    end
+  end
+end

data/lib/auditea/transport/limits.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Auditea
+  module Transport
+    module Limits
+      SINGLE_MAX_BYTES = 128 * 1024
+      BATCH_MAX_BYTES = 1024 * 1024
+      BATCH_MAX_EVENTS = 100
+      MAX_RESPONSE_BYTES = 64 * 1024
+      # Leave headroom for {"events":[...]} wrapper and commas.
+      BATCH_ENVELOPE_BUDGET = BATCH_MAX_BYTES - 256
+
+      module_function
+
+      def event_bytes(event)
+        JSON.generate(event).bytesize
+      end
+
+      def batch_body_bytes(events)
+        JSON.generate("events" => events).bytesize
+      end
+
+      def oversized_event?(event)
+        event_bytes(event) > SINGLE_MAX_BYTES
+      end
+    end
+  end
+end

data/lib/auditea/transport/queue.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module Auditea
+  module Transport
+    # Single worker + bounded queue. Process-aware for pre-fork servers.
+    # Replaces legacy Thread-per-event (REWRITE).
+    class Queue
+      DEFAULT_PID = -> { Process.pid }
+      DEFAULT_SLEEPER = ->(seconds) { sleep(seconds) }
+
+      def initialize(configuration, http:, pid_provider: DEFAULT_PID, sleeper: DEFAULT_SLEEPER)
+        @configuration = configuration
+        @http = http
+        @pid_provider = pid_provider
+        @sleeper = sleeper
+        @mutex = Mutex.new
+        @cv = ConditionVariable.new
+        @buffer = []
+        @stopped = false
+        @dropped = 0
+        @inflight = 0
+        @thread = nil
+        @owner_pid = nil
+      end
+
+      def start!
+        return unless @configuration.async?
+
+        ensure_process!
+        @mutex.synchronize do
+          return if @thread&.alive?
+
+          @stopped = false
+          @thread = Thread.new { run_loop }
+          @thread.name = "auditea-delivery" if @thread.respond_to?(:name=)
+        end
+      end
+
+      def enqueue(event)
+        ensure_process!
+        if Limits.oversized_event?(event)
+          log_drop(event["event_id"], "payload_too_large")
+          return false
+        end
+
+        if @configuration.async?
+          start!
+          @mutex.synchronize do
+            if @buffer.size >= @configuration.queue_capacity
+              @dropped += 1
+              @configuration.logger&.warn("[auditea] queue full; dropping event_id=#{event['event_id']}")
+              return false
+            end
+            @buffer << event
+            @cv.signal
+          end
+          true
+        else
+          deliver_now([event])
+        end
+      end
+
+      def flush(timeout: 5)
+        ensure_process!
+        deadline = monotonic + timeout
+        loop do
+          batch = nil
+          @mutex.synchronize do
+            batch = take_batch_locked
+          end
+          deliver_now(batch, reserved: true) if batch && !batch.empty?
+
+          done = @mutex.synchronize { @buffer.empty? && @inflight.zero? }
+          break if done || monotonic >= deadline
+
+          @mutex.synchronize do
+            remaining = deadline - monotonic
+            @cv.wait(@mutex, [remaining, 0.05].min) if remaining.positive? && (@inflight.positive? || !@buffer.empty?)
+          end
+        end
+        @mutex.synchronize { @buffer.empty? && @inflight.zero? }
+      end
+
+      def shutdown
+        ensure_process!
+        @mutex.synchronize do
+          @stopped = true
+          @cv.broadcast
+        end
+        flush(timeout: 5)
+        thread = nil
+        @mutex.synchronize { thread = @thread }
+        thread&.join(2)
+      end
+
+      def stats
+        ensure_process!
+        @mutex.synchronize { { size: @buffer.size, dropped: @dropped, inflight: @inflight, pid: @owner_pid } }
+      end
+
+      private
+
+      def ensure_process!
+        pid = @pid_provider.call
+        @mutex.synchronize do
+          if @owner_pid.nil?
+            @owner_pid = pid
+          elsif @owner_pid != pid
+            # Child after fork: drop inherited buffer/worker; do not deliver parent data.
+            @buffer = []
+            @inflight = 0
+            @dropped = 0
+            @stopped = false
+            @thread = nil
+            @owner_pid = pid
+          end
+        end
+      end
+
+      def run_loop
+        loop do
+          batch = nil
+          @mutex.synchronize do
+            @cv.wait(@mutex, @configuration.flush_interval) while @buffer.empty? && !@stopped
+            break if @stopped && @buffer.empty? && @inflight.zero?
+
+            batch = take_batch_locked
+          end
+          break if batch.nil? && @stopped && empty_and_idle?
+
+          deliver_now(batch, reserved: true) if batch && !batch.empty?
+        end
+      rescue StandardError => error
+        @configuration.logger&.warn("[auditea] worker error: #{error.class}: #{error.message.to_s.byteslice(0, 200)}")
+        retry unless @stopped
+      end
+
+      def empty_and_idle?
+        @mutex.synchronize { @buffer.empty? && @inflight.zero? }
+      end
+
+      # Caller must hold @mutex. Reserving in-flight ownership while removing the
+      # batch closes the gap where flush could observe an empty buffer before the
+      # worker had marked that batch as being delivered.
+      def take_batch_locked
+        return [] if @buffer.empty?
+
+        max_count = [@configuration.batch_size, Limits::BATCH_MAX_EVENTS].min
+        batch = []
+        while !@buffer.empty? && batch.size < max_count
+          candidate = @buffer.first
+          if Limits.oversized_event?(candidate)
+            dropped = @buffer.shift
+            @dropped += 1
+            log_drop(dropped["event_id"], "payload_too_large")
+            next
+          end
+
+          trial = batch + [candidate]
+          break if !batch.empty? && Limits.batch_body_bytes(trial) > Limits::BATCH_ENVELOPE_BUDGET
+
+          if batch.empty? && Limits.batch_body_bytes(trial) > Limits::BATCH_ENVELOPE_BUDGET
+            # Single event fits SINGLE_MAX but somehow exceeds batch budget with wrapper —
+            # still attempt as single-event POST path later if batch size becomes 1.
+            batch << @buffer.shift
+            break
+          end
+
+          batch << @buffer.shift
+        end
+        @inflight += 1 unless batch.empty?
+        batch
+      end
+
+      def deliver_now(events, reserved: false)
+        return true if events.nil? || events.empty?
+
+        @mutex.synchronize { @inflight += 1 } unless reserved
+        begin
+          result =
+            if events.size == 1
+              @http.post_event(events.first)
+            else
+              @http.post_batch(events)
+            end
+          handle_result(events, result)
+          result
+        rescue StandardError => error
+          @configuration.logger&.warn("[auditea] delivery failed: #{error.class}: #{error.message.to_s.byteslice(0,
+                                                                                                                 200)}")
+          raise if @configuration.raise_errors
+
+          false
+        ensure
+          @mutex.synchronize do
+            @inflight -= 1 if @inflight.positive?
+            @cv.broadcast
+          end
+        end
+      end
+
+      def handle_result(events, result)
+        return unless result.is_a?(DeliveryResult)
+
+        if result.results
+          result.results.each do |row|
+            next if row["ok"]
+
+            @configuration.logger&.warn(
+              "[auditea] event_id=#{row['event_id']} outcome=#{row['outcome']} reason=batch_row"
+            )
+          end
+        elsif !result.ok?
+          @configuration.logger&.warn(
+            "[auditea] event_id=#{result.event_id || events.first&.dig('event_id')} " \
+            "outcome=#{result.outcome} reason=#{result.message}"
+          )
+        end
+        # Permanent and mixed batch outcomes are not re-queued (accepted siblings must not retry).
+        nil
+      end
+
+      def log_drop(event_id, reason)
+        @configuration.logger&.warn("[auditea] event_id=#{event_id} reason=#{reason}")
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/auditea/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Auditea
+  VERSION = "0.1.0.beta.1"
+end

data/lib/auditea.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "time"
+require "timeout"
+require "uri"
+require "net/http"
+require "logger"
+require "openssl"
+
+require_relative "auditea/version"
+
+module Auditea
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+end
+
+require_relative "auditea/configuration"
+require_relative "auditea/sanitizer"
+require_relative "auditea/event_builder"
+require_relative "auditea/actor"
+require_relative "auditea/target"
+require_relative "auditea/current_context"
+require_relative "auditea/transport/limits"
+require_relative "auditea/transport/delivery_result"
+require_relative "auditea/transport/http"
+require_relative "auditea/transport/queue"
+require_relative "auditea/client"
+require_relative "auditea/log"
+require_relative "auditea/instrumentation/request"
+require_relative "auditea/instrumentation/exception"
+require_relative "auditea/instrumentation/logger_adapter"
+require_relative "auditea/instrumentation/active_job"
+require_relative "auditea/middleware/context"
+require_relative "auditea/railtie" if defined?(Rails::Railtie)
+
+# AudiTea Ruby SDK — capture, structure, sanitize, enrich, transport.
+# Taxonomy / dictionary / human labels remain server-side.
+module Auditea
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+      configuration.validate!
+      @client&.reset!
+      self
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+      @client&.shutdown
+      @client = nil
+    end
+
+    def client
+      @client ||= Client.new
+    end
+
+    # Explicit business / technical event capture.
+    #
+    # @param action [String] machine key, e.g. "project.approved"
+    # @return [Hash] delivery outcome
+    def capture(action, category: nil, severity: nil, actor: nil, target: nil,
+                context: nil, evidence: nil, provenance: nil, metadata: nil,
+                privacy: nil, occurred_at: nil, event_id: nil)
+      deliver_built(
+        EventBuilder.build(
+          action: action,
+          category: category,
+          severity: severity,
+          actor: actor,
+          target: target,
+          context: context,
+          evidence: evidence,
+          provenance: provenance,
+          metadata: metadata,
+          privacy: privacy,
+          occurred_at: occurred_at,
+          event_id: event_id
+        )
+      )
+    rescue StandardError => error
+      handle_error(error)
+    end
+
+    # Alias kept for legacy familiarity (KEEP CONCEPT).
+    alias track capture
+
+    # Structured application log as a first-class event (not Rails.logger auto-forward).
+    def log(level, message, context: {}, metadata: {})
+      Log.record(level, message, context: context, metadata: metadata)
+    rescue StandardError => error
+      handle_error(error)
+    end
+
+    def flush(timeout: 5)
+      client.flush(timeout: timeout)
+    rescue StandardError => error
+      handle_error(error)
+    end
+
+    def shutdown
+      client.shutdown
+    rescue StandardError => error
+      handle_error(error)
+    end
+
+    def handle_error(error)
+      configuration.logger&.warn("[auditea] #{error.class}: #{error.message}")
+      raise error if configuration.raise_errors
+
+      { ok: false, skipped: true, error: error.message }
+    end
+
+    private
+
+    def deliver_built(event)
+      return { ok: false, skipped: true, reason: "disabled" } unless configuration.enabled?
+      return { ok: false, skipped: true, reason: "not_configured" } unless configuration.configured?
+
+      sanitized = Sanitizer.sanitize_event(event)
+      if Transport::Limits.oversized_event?(sanitized)
+        configuration.logger&.warn(
+          "[auditea] event_id=#{sanitized['event_id']} reason=payload_too_large"
+        )
+        return { ok: false, skipped: true, reason: "payload_too_large", event_id: sanitized["event_id"] }
+      end
+
+      result = client.enqueue(sanitized)
+      if configuration.async?
+        if result
+          { ok: true, event_id: sanitized["event_id"], queued: true }
+        else
+          { ok: false, skipped: true, reason: "delivery_failed", event_id: sanitized["event_id"] }
+        end
+      elsif result.is_a?(Transport::DeliveryResult)
+        result.to_h.merge(event_id: sanitized["event_id"])
+      elsif result
+        { ok: true, event_id: sanitized["event_id"] }
+      else
+        { ok: false, skipped: true, reason: "delivery_failed", event_id: sanitized["event_id"] }
+      end
+    end
+  end
+end