oppex_sdk 1.0.0

data/lib/oppex_sdk/incident_request.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "severity"
+
+module Oppex
+  # A validated, immutable incident submission.
+  #
+  # Validation happens in the constructor, so a malformed incident is rejected at
+  # the call site rather than inside a worker thread where only a log line would
+  # remain.
+  #
+  #   request = Oppex::IncidentRequest.new(
+  #     title: "Checkout latency breached the SLO",
+  #     source: "checkout-api",
+  #     severity: Oppex::Severity::HIGH
+  #   )
+  #
+  # A request may override the service key configured on the client.
+  class IncidentRequest
+    # The maximum length of +source+, counted in characters.
+    MAX_SOURCE_LENGTH = 255
+
+    attr_reader :title, :source, :severity, :priority, :src_timestamp,
+                :service_key, :component, :group, :type, :details
+
+    def initialize(title:, source:, severity:, priority: 1, src_timestamp: nil,
+                   service_key: nil, component: nil, group: nil, type: nil, details: nil)
+      @title = require_non_blank(title, "title")
+      @source = require_source(source)
+      @severity = Severity.validate!(severity)
+      @priority = validate_priority(priority)
+      @src_timestamp = validate_timestamp(src_timestamp)
+      @service_key = reject_blank(service_key, "service_key")
+      @component = reject_blank(component, "component")
+      @group = reject_blank(group, "group")
+      @type = reject_blank(type, "type")
+      @details = reject_blank(details, "details")
+      freeze
+    end
+
+    private
+
+    def require_non_blank(value, field)
+      raise TypeError, "#{field} must be a String" unless value.is_a?(String)
+      raise ArgumentError, "#{field} must not be blank" if value.strip.empty?
+
+      value
+    end
+
+    def require_source(source)
+      source = require_non_blank(source, "source")
+      raise ArgumentError, "source must not exceed #{MAX_SOURCE_LENGTH} characters" if source.length > MAX_SOURCE_LENGTH
+
+      source
+    end
+
+    # An optional field may be absent, but a present-yet-blank value is nearly
+    # always a bug at the call site, so it is rejected rather than silently sent.
+    def reject_blank(value, field)
+      return nil if value.nil?
+
+      require_non_blank(value, field)
+    end
+
+    def validate_priority(priority)
+      raise TypeError, "priority must be an Integer" unless priority.is_a?(Integer)
+      raise ArgumentError, "priority must be between 1 and 5" unless (1..5).cover?(priority)
+
+      priority
+    end
+
+    def validate_timestamp(src_timestamp)
+      return (Time.now.to_f * 1000).to_i if src_timestamp.nil?
+
+      raise TypeError, "src_timestamp must be an Integer" unless src_timestamp.is_a?(Integer)
+      raise ArgumentError, "src_timestamp must be greater than zero" unless src_timestamp.positive?
+
+      src_timestamp
+    end
+  end
+end

data/lib/oppex_sdk/incident_response.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Oppex
+  # The immutable result of a delivered incident.
+  #
+  # +successful+ and +code+ fall back to what the HTTP status already said when
+  # the response body does not carry its own.
+  IncidentResponse = Data.define(:successful, :code, :message, :incident_id) do
+    # @return [Boolean]
+    def successful?
+      successful
+    end
+  end
+end

data/lib/oppex_sdk/internal/async_dispatcher.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative "rate_limited_drop_logger"
+
+module Oppex
+  module Internal
+    # Delivers asynchronous incidents on a fixed number of worker threads,
+    # queueing the rest up to +capacity+ and dropping the oldest entry once full.
+    #
+    # Dropping the oldest keeps the newest incident, which is the one most likely
+    # to still matter, and submission never blocks the application.
+    #
+    # Not public API.
+    class AsyncDispatcher
+      QUEUE_CAPACITY = 5000
+      WORKER_COUNT = 2
+      CLOSE_DRAIN_TIMEOUT_SECONDS = 10.0
+
+      def initialize(logger, worker_count: WORKER_COUNT, capacity: QUEUE_CAPACITY)
+        @logger = logger
+        @capacity = capacity
+        # One mutex guards the queue and every lifecycle flag together. Splitting
+        # them would reintroduce the missed-wakeup race: a worker reads
+        # "draining", close clears it and broadcasts, and only then does the
+        # worker start waiting, on a broadcast that already happened.
+        @mutex = Mutex.new
+        @changed = ConditionVariable.new
+        @tasks = []
+        @accepting = true
+        @draining = true
+        @active = 0
+        @drop_logger = RateLimitedDropLogger.new
+        @workers = Array.new(worker_count) { Thread.new { work } }
+      end
+
+      # Queues a task, evicting the oldest queued task when the queue is full.
+      # Returns whether the task was accepted; only a closed dispatcher refuses.
+      #
+      # rubocop:disable Naming/PredicateMethod -- this is a command that reports
+      # whether it was accepted, not a question; `submit?` would read as one.
+      def submit(&task)
+        dropped = @mutex.synchronize do
+          next :refused unless @accepting
+
+          evicted = if @tasks.length >= @capacity
+                      @tasks.shift
+                      @drop_logger.record_drop
+                    end
+          @tasks.push(task)
+          @changed.broadcast
+          evicted
+        end
+        return false if dropped == :refused
+
+        @logger.warn("oppex: dropped #{dropped} incidents in the last minute") if dropped
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      # Stops admitting work and drains what is already queued and in flight for
+      # up to +timeout_seconds+, then abandons the rest. Idempotent, and safe to
+      # call from any thread.
+      def close(timeout_seconds = CLOSE_DRAIN_TIMEOUT_SECONDS)
+        was_accepting = @mutex.synchronize do
+          accepting = @accepting
+          @accepting = false
+          accepting
+        end
+        return unless was_accepting
+
+        abandoned = drain_until(monotonic_now + timeout_seconds)
+
+        # The workers are deliberately not joined without a bound. A Ruby thread
+        # cannot be interrupted safely, so waiting on one that is blocked in an
+        # HTTP attempt would push close past its own timeout. Java makes the same
+        # trade: it waits for the drain, calls shutdownNow, and returns without
+        # waiting for whatever that failed to interrupt.
+        @workers.each { |worker| worker.join(0) }
+
+        # Reported once and directly, rather than through the rate-limited
+        # overflow counter: a shutdown loss and an overload loss are different
+        # events, and a rate-limited counter's last batch can go unreported.
+        @logger.warn("oppex: force-dropped #{abandoned} pending incidents during close") if abandoned.positive?
+      end
+
+      private
+
+      def work
+        loop do
+          task = @mutex.synchronize do
+            while @tasks.empty?
+              return unless @draining
+
+              @changed.wait(@mutex)
+            end
+            @active += 1
+            @tasks.shift
+          end
+
+          begin
+            task.call
+          ensure
+            @mutex.synchronize do
+              @active -= 1
+              @changed.broadcast
+            end
+          end
+        end
+      end
+
+      # Waits until nothing is queued or in flight, or the deadline passes. Then
+      # stops the workers and returns how many tasks were abandoned.
+      def drain_until(deadline)
+        @mutex.synchronize do
+          until @tasks.empty? && @active.zero?
+            remaining = deadline - monotonic_now
+            break if remaining <= 0
+
+            @changed.wait(@mutex, remaining)
+          end
+
+          @draining = false
+          @changed.broadcast
+          abandoned = @tasks.length
+          @tasks.clear
+          abandoned
+        end
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/oppex_sdk/internal/http_executor.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+require_relative "../endpoint"
+require_relative "../errors"
+require_relative "retry_executor"
+require_relative "wire_codec"
+
+module Oppex
+  module Internal
+    # The HTTP adapter. Not public API.
+    class HttpExecutor
+      OPEN_TIMEOUT_SECONDS = 3
+      READ_TIMEOUT_SECONDS = 5
+      WRITE_TIMEOUT_SECONDS = 5
+      # The API returns a small envelope. Anything larger is a misbehaving proxy,
+      # and reading it in full would let that proxy dictate this client's memory
+      # use.
+      MAX_RESPONSE_BYTES = 1024 * 1024
+
+      # Resolves the target URL.
+      #
+      # The override exists so tests and the external smoke consumer can point the
+      # whole delivery path at a loopback server. It is deliberately not client
+      # configuration, which would add a public knob that exists only to ease
+      # testing.
+      def self.resolve_endpoint
+        override = ENV.fetch("OPPEX_TEST_ENDPOINT_URL", nil)
+        override.nil? || override.empty? ? Oppex::DEFAULT_ENDPOINT : override
+      end
+
+      def initialize(api_key, endpoint: nil)
+        @api_key = api_key
+        @uri = URI.parse(endpoint || self.class.resolve_endpoint)
+      end
+
+      # Performs one attempt. Every failure it raises is an IncidentError whose
+      # +retryable?+ already carries the retry decision, so the retry policy never
+      # has to know which library raised what.
+      def execute(payload)
+        response = send_request(payload)
+        status = response.code.to_i
+        body = truncate(response.body)
+
+        return WireCodec.parse_response(status, body) if (200...300).cover?(status)
+
+        raise status_failure(status, body)
+      end
+
+      def close
+        # Net::HTTP instances are not thread safe, so this executor opens a
+        # connection per attempt rather than holding a pool. There is nothing to
+        # release here; the method exists so the client's lifecycle stays the same
+        # shape as every other Oppex SDK's.
+        nil
+      end
+
+      private
+
+      def send_request(payload)
+        request = Net::HTTP::Post.new(@uri)
+        request["Content-Type"] = "application/json"
+        request["Accept"] = "application/json"
+        request["X-API-KEY"] = @api_key
+        request.body = payload
+
+        Net::HTTP.start(@uri.hostname, @uri.port, use_ssl: @uri.scheme == "https",
+                                                  open_timeout: OPEN_TIMEOUT_SECONDS,
+                                                  read_timeout: READ_TIMEOUT_SECONDS,
+                                                  write_timeout: WRITE_TIMEOUT_SECONDS) do |http|
+          http.request(request)
+        end
+      rescue StandardError => e
+        # No status line was received, so the failure is transport-level and
+        # retryable regardless of which library raised it. Catching StandardError
+        # rather than an enumerated list is deliberate: Net::HTTP, OpenSSL,
+        # resolv and socket code between them raise well over a dozen classes, and
+        # an omission would escape as a raw exception from a public method.
+        raise IncidentError.new("incident delivery failed before a response was received",
+                                retryable: true, cause_error: e)
+      end
+
+      def truncate(body)
+        return body if body.nil? || body.bytesize <= MAX_RESPONSE_BYTES
+
+        body.byteslice(0, MAX_RESPONSE_BYTES)
+      end
+
+      # Turns a non-2xx response into a delivery failure, adding the API's own
+      # message when the body carries one.
+      def status_failure(status, body)
+        message = "Oppex returned HTTP #{status}"
+        detail = begin
+          WireCodec.parse_response(status, body).message
+        rescue IncidentError
+          nil # The status code remains sufficient when the body is not JSON.
+        end
+        message = "#{message}: #{detail}" if detail && !detail.strip.empty?
+
+        IncidentError.new(message, status_code: status, retryable: RetryExecutor.retryable_status?(status))
+      end
+    end
+  end
+end

data/lib/oppex_sdk/internal/interrupt.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Oppex
+  module Internal
+    # A one-way "stop waiting" signal.
+    #
+    # A sleeping Ruby thread cannot be interrupted safely the way a Java thread
+    # can, so a backoff delay waits on this condition variable instead of calling
+    # +sleep+. Closing the client signals it once, which wakes every waiting
+    # retry immediately rather than after up to eight more seconds.
+    #
+    # Not public API.
+    class Interrupt
+      def initialize
+        @mutex = Mutex.new
+        @changed = ConditionVariable.new
+        @signalled = false
+      end
+
+      # Signals every current and future waiter. Idempotent.
+      def signal
+        @mutex.synchronize do
+          @signalled = true
+          @changed.broadcast
+        end
+      end
+
+      def signalled?
+        @mutex.synchronize { @signalled }
+      end
+
+      # Waits up to +seconds+. Returns true when the wait was cut short by a
+      # signal, false when the full duration elapsed.
+      def wait(seconds)
+        deadline = monotonic_now + seconds
+        @mutex.synchronize do
+          until @signalled
+            remaining = deadline - monotonic_now
+            return false if remaining <= 0
+
+            @changed.wait(@mutex, remaining)
+          end
+          true
+        end
+      end
+
+      private
+
+      # A monotonic clock, so a system clock adjustment mid-backoff cannot turn a
+      # half-second wait into a very long one.
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/oppex_sdk/internal/rate_limited_drop_logger.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Oppex
+  module Internal
+    # Counts every dropped incident but reports at most one summary per interval.
+    #
+    # A saturated queue drops continuously, so logging each drop would replace
+    # one overload with another. Not public API.
+    class RateLimitedDropLogger
+      INTERVAL_SECONDS = 60.0
+
+      def initialize(interval_seconds: INTERVAL_SECONDS, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+        @interval_seconds = interval_seconds
+        @clock = clock
+        @mutex = Mutex.new
+        @dropped = 0
+        @started_at = clock.call
+      end
+
+      # Records one drop.
+      #
+      # Returns the accumulated count when the interval has elapsed and the
+      # caller should emit a summary, or nil otherwise. Returning the count
+      # instead of logging keeps this class free of any logging decision, which
+      # is also what makes it testable without capturing output.
+      def record_drop
+        @mutex.synchronize do
+          @dropped += 1
+          now = @clock.call
+          next nil if now - @started_at < @interval_seconds
+
+          dropped = @dropped
+          @dropped = 0
+          @started_at = now
+          dropped
+        end
+      end
+    end
+  end
+end

data/lib/oppex_sdk/internal/retry_executor.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module Oppex
+  module Internal
+    # The retry policy. Not public API.
+    module RetryExecutor
+      # Five retries after the first attempt, doubling, without jitter.
+      # Deliberately not configurable.
+      DEFAULT_DELAYS = [0.5, 1.0, 2.0, 4.0, 8.0].freeze
+
+      # An explicit list rather than "any 5xx". Widening it is a deliberate
+      # policy change, not an incidental one.
+      RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+
+      INTERRUPTED_MESSAGE = "incident delivery was interrupted during retry"
+
+      module_function
+
+      def retryable_status?(status)
+        RETRYABLE_STATUSES.include?(status)
+      end
+
+      # Runs the block until it succeeds, fails with a non-retryable error, or
+      # exhausts +delays+.
+      #
+      # Only the final failure is raised. Individual attempts are never logged,
+      # so a saturated Oppex API cannot flood the host's logs.
+      def execute(interrupt, delays: DEFAULT_DELAYS)
+        attempt = 0
+        loop do
+          begin
+            return yield
+          rescue IncidentError => e
+            raise annotate(e, attempt + 1) if !e.retryable? || attempt >= delays.length
+
+            raise IncidentError, INTERRUPTED_MESSAGE if interrupt.wait(delays[attempt])
+          end
+          attempt += 1
+        end
+      end
+
+      # Annotates only a failure that never reached a status line. An HTTP
+      # failure keeps the message its status already explains.
+      def annotate(error, attempts)
+        return error if error.http_status? || attempts < 2
+
+        IncidentError.new("#{error.message} (after #{attempts} attempts)",
+                          status_code: error.status_code,
+                          retryable: error.retryable?,
+                          cause_error: error.cause_error)
+      end
+    end
+  end
+end

data/lib/oppex_sdk/internal/wire_codec.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "../errors"
+require_relative "../incident_response"
+
+module Oppex
+  module Internal
+    # Renders the wire payload and decodes the response envelope.
+    #
+    # Not public API; every method here may change in any release.
+    module WireCodec
+      # Wire field order. Ruby hashes preserve insertion order, and +to_json+
+      # follows it, so the payload matches the other SDKs byte for byte.
+
+      module_function
+
+      # A nil resolved service key is omitted entirely so the API routes the
+      # incident by its own rules. Every other absent optional field is omitted
+      # rather than sent as null.
+      def serialize_request(request, resolved_service_key)
+        fields = {
+          serviceKey: resolved_service_key,
+          title: request.title,
+          source: request.source,
+          severity: request.severity,
+          priority: request.priority,
+          srcTimestamp: request.src_timestamp,
+          component: request.component,
+          group: request.group,
+          type: request.type,
+          detailsJSON: request.details
+        }
+        # One rejection covers every optional field, including the service key.
+        # The required fields cannot be nil: IncidentRequest validated them.
+        JSON.generate(fields.compact)
+      end
+
+      # Decodes a response body, falling back to the HTTP status for any field
+      # the body does not carry.
+      #
+      # A body that is not JSON is never echoed into the raised error: a proxy or
+      # WAF can return an error page that repeats request headers, including
+      # X-API-KEY, and that text would then leak into the host's logs.
+      def parse_response(http_status, body)
+        successful = (200...300).cover?(http_status)
+        return IncidentResponse.new(successful:, code: http_status, message: nil, incident_id: nil) if blank?(body)
+
+        envelope = parse_json(body, http_status)
+        IncidentResponse.new(
+          successful: boolean_or(envelope["success"], successful),
+          code: integer_or(envelope["code"], http_status),
+          message: string_or_nil(envelope["message"]),
+          incident_id: string_or_nil(envelope["data"])
+        )
+      end
+
+      def blank?(body)
+        body.nil? || body.strip.empty?
+      end
+
+      def parse_json(body, http_status)
+        envelope = JSON.parse(body)
+        unless envelope.is_a?(Hash)
+          raise IncidentError.new("Oppex returned a non-object JSON response (status #{http_status})",
+                                  status_code: http_status)
+        end
+
+        envelope
+      rescue JSON::ParserError => e
+        raise IncidentError.new("Oppex returned a non-JSON response (status #{http_status})",
+                                status_code: http_status, cause_error: e)
+      end
+
+      def boolean_or(value, fallback)
+        [true, false].include?(value) ? value : fallback
+      end
+
+      def integer_or(value, fallback)
+        value.is_a?(Integer) ? value : fallback
+      end
+
+      def string_or_nil(value)
+        value.is_a?(String) ? value : nil
+      end
+    end
+  end
+end

data/lib/oppex_sdk/logging.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Oppex
+  # The default logging sink: writes one line per message to standard error.
+  #
+  # This SDK deliberately does not require the +logger+ standard library. It
+  # stops being a default gem in Ruby 4.0, so requiring it would turn a
+  # dependency-free gem into one with a runtime dependency, for four method
+  # calls. Any object that responds to +debug+, +info+, +warn+ and +error+ works
+  # instead, which means a host's +Logger+, +Rails.logger+, SemanticLogger or
+  # anything else drops in with no adapter.
+  class StderrLogger
+    LEVELS = %i[debug info warn error].freeze
+
+    LEVELS.each do |level|
+      define_method(level) do |message|
+        # A broken logging destination must never crash incident delivery.
+        warn("[oppex-sdk] #{level.to_s.upcase} #{message}")
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/oppex_sdk/severity.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Oppex
+  # Oppex incident severity, on a scale from 1 (lowest) to 5 (highest).
+  #
+  # The constants are the wire values, so an integer from another system can be
+  # passed straight through after {Severity.validate!}.
+  module Severity
+    LOWEST = 1
+    LOW = 2
+    MEDIUM = 3
+    HIGH = 4
+    CRITICAL = 5
+
+    ALL = [LOWEST, LOW, MEDIUM, HIGH, CRITICAL].freeze
+
+    NAMES = {
+      LOWEST => "LOWEST",
+      LOW => "LOW",
+      MEDIUM => "MEDIUM",
+      HIGH => "HIGH",
+      CRITICAL => "CRITICAL"
+    }.freeze
+
+    class << self
+      # @return [Boolean] whether +value+ is within the Oppex scale.
+      def valid?(value)
+        ALL.include?(value)
+      end
+
+      # @return [Integer] +value+ unchanged.
+      # @raise [ArgumentError] when +value+ is outside 1 to 5.
+      # @raise [TypeError] when +value+ is not an Integer.
+      def validate!(value)
+        # true and false are not Integers in Ruby, so no bool special case is
+        # needed the way the Python SDK needs one.
+        raise TypeError, "severity must be an Integer" unless value.is_a?(Integer)
+        raise ArgumentError, "severity must be between 1 and 5" unless valid?(value)
+
+        value
+      end
+
+      # @return [String, nil] the constant name for a wire value.
+      def name_for(value)
+        NAMES[value]
+      end
+    end
+  end
+end

data/lib/oppex_sdk/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Oppex
+  # The released gem version. The release workflow checks this against the tag.
+  VERSION = "1.0.0"
+end