apirelio 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fce9ddd2aa09cd6234e1b0c7b2fb7df415d107ff534a9472dfd7883f06e1c116
+  data.tar.gz: b27c9db466b05fb1a54fcd3efdb9f2ddf5850bfd2c52417e2c1a0871dc30d06c
+SHA512:
+  metadata.gz: 75345de07ce8a68b25779dc450fa9619f4b238780d46a1e9a206c3c13b7e9e33e8a46fee331e380a0362b01c9c2b046931c8826e5abfcb052f0909aa76892e25
+  data.tar.gz: 8a37deb8eb1a66c2fb0e2d0078253f37e670797ed8c683fbb9cd1d5b56b660bfb9a0436abe5af8bd3e82bce8ae883e49fffbb284e23f95f35db1beca05c708cc

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 - 2026-08-12
+
+- Add privacy-safe event normalization and metadata filtering.
+- Add bounded asynchronous batch delivery with retries and fail-safe callbacks.
+- Add Rack middleware with customer, application and error-code resolvers.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Apirelio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,27 @@
+# Apirelio Ruby
+
+[Documentation](https://apirelio.com/docs/ruby) · [RubyGems](https://rubygems.org/gems/apirelio) · [Apirelio](https://apirelio.com)
+
+Privacy-safe customer-aware API analytics for Ruby and Rack applications.
+
+```bash
+bundle add apirelio
+```
+
+```ruby
+client = Apirelio::Client.new(
+  api_key: ENV.fetch("APIRELIO_API_KEY", ""),
+  service: "billing-api"
+)
+
+use Apirelio::Rack::Middleware,
+  client: client,
+  customer_resolver: ->(env) {
+    account = env["current_account"]
+    account && { id: account.id.to_s, name: account.name, plan: account.plan }
+  }
+```
+
+The middleware records the final status, duration and normalized route without collecting request or response bodies, query strings, credentials, cookies or client IP addresses. Delivery uses a bounded background queue and never changes the observed response or exception.
+
+Use [`apirelio-rails`](https://github.com/pryznar/apirelio-rails) for automatic Rails registration.

data/lib/apirelio/client.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Apirelio
+  class Client
+    attr_reader :dropped_count
+
+    def initialize(api_key:, service:, endpoint: "https://apirelio.com", environment: "production", release: nil,
+                   enabled: true, batch_size: 100, flush_interval: 5.0, max_queue_size: 10_000,
+                   timeout: 2.0, max_retries: 2, metadata_keys: [], transport: nil,
+                   on_error: nil, on_dropped: nil)
+      @api_key = api_key.to_s
+      @service = service.to_s
+      @environment = environment.to_s
+      @release = release
+      @enabled = enabled
+      @batch_size = [[batch_size.to_i, 1].max, 500].min
+      @flush_interval = [flush_interval.to_f, 0.1].max
+      @max_queue_size = [max_queue_size.to_i, 1].max
+      @metadata_keys = metadata_keys.map(&:to_s).freeze
+      @transport = transport || HttpBatchTransport.new(endpoint: endpoint, api_key: @api_key, timeout: timeout, max_retries: max_retries)
+      @on_error = on_error
+      @on_dropped = on_dropped
+      @queue = []
+      @mutex = Mutex.new
+      @flush_mutex = Mutex.new
+      @condition = ConditionVariable.new
+      @closed = false
+      @dropped_count = 0
+      @worker = Thread.new { worker_loop }
+      @worker.name = "apirelio" if @worker.respond_to?(:name=)
+    end
+
+    def capture(context)
+      return false if @closed || !@enabled || @api_key.empty?
+
+      event = Event.build(context, service: @service, environment: @environment, release: @release, metadata_keys: @metadata_keys)
+      dropped = false
+      @mutex.synchronize do
+        if @queue.length >= @max_queue_size
+          @dropped_count += 1
+          dropped = true
+        else
+          @queue << event
+          @condition.signal if @queue.length >= @batch_size
+        end
+      end
+      if dropped
+        report_dropped(event)
+        return false
+      end
+      true
+    rescue StandardError => error
+      report(error)
+      false
+    end
+
+    def pending_count
+      @mutex.synchronize { @queue.length }
+    end
+
+    def flush
+      @flush_mutex.synchronize do
+        loop do
+          batch = @mutex.synchronize { @queue.shift(@batch_size) }
+          return true if batch.empty?
+
+          begin
+            @transport.send(batch)
+          rescue StandardError
+            dropped_events = []
+            @mutex.synchronize do
+              @queue.unshift(*batch)
+              dropped_events = trim_queue
+            end
+            dropped_events.each { |event| report_dropped(event) }
+            raise
+          end
+        end
+      end
+    end
+
+    def shutdown(timeout: 5.0)
+      @mutex.synchronize do
+        @closed = true
+        @condition.broadcast
+      end
+      @worker.join([timeout.to_f, 0].max)
+      flush
+    rescue StandardError => error
+      report(error)
+      false
+    end
+
+    private
+
+    def worker_loop
+      loop do
+        closed = @mutex.synchronize do
+          @condition.wait(@mutex, @flush_interval) unless @closed
+          @closed
+        end
+        break if closed
+        flush if pending_count.positive?
+      rescue StandardError => error
+        report(error)
+      end
+    end
+
+    def trim_queue
+      dropped_events = []
+      while @queue.length > @max_queue_size
+        dropped_events << @queue.pop
+        @dropped_count += 1
+      end
+      dropped_events
+    end
+
+    def report(error)
+      @on_error&.call(error)
+    rescue StandardError
+      nil
+    end
+
+    def report_dropped(event)
+      @on_dropped&.call(event, @dropped_count)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/apirelio/event.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Apirelio
+  module Event
+    module_function
+
+    def build(context, service:, environment:, release:, metadata_keys:)
+      customer = context[:customer] || {}
+      application = context[:application] || {}
+      {
+        event_id: SecureRandom.uuid,
+        occurred_at: Time.now.utc.iso8601(3),
+        service: text(service, 120) || "ruby-api",
+        environment: environment.to_s,
+        method: (text(context[:method], 16) || "GET").upcase,
+        route: Route.normalize(context[:route]),
+        route_name: text(context[:route_name], 255),
+        status: integer(context.fetch(:status, 200), 100, 599),
+        duration_ms: integer(context.fetch(:duration_ms, 0), 0, 4_294_967_295),
+        request_bytes: optional_integer(context[:request_bytes]),
+        response_bytes: optional_integer(context[:response_bytes]),
+        customer_id: text(value(customer, :id), 255),
+        customer_name: text(value(customer, :name), 255),
+        customer_plan: text(value(customer, :plan), 120),
+        application_id: text(value(application, :id), 255),
+        application_name: text(value(application, :name), 255),
+        api_version: text(context[:api_version], 120),
+        sdk: text(context[:sdk], 120) || "ruby",
+        sdk_version: text(context[:sdk_version], 120) || "0.0.0",
+        release: text(release, 255),
+        error_code: text(context[:error_code], 255),
+        metadata: Metadata.sanitize(context[:metadata] || {}, allowed_keys: metadata_keys)
+      }
+    end
+
+    def value(hash, key)
+      hash[key] || hash[key.to_s]
+    end
+    private_class_method :value
+
+    def text(value, length)
+      string = value.is_a?(String) ? value : value&.to_s
+      string && !string.empty? ? string[0, length] : nil
+    end
+    private_class_method :text
+
+    def integer(value, minimum, maximum)
+      numeric = value.is_a?(Numeric) && (!value.respond_to?(:finite?) || value.finite?) ? value.round : minimum
+      [[numeric, minimum].max, maximum].min
+    end
+    private_class_method :integer
+
+    def optional_integer(value)
+      value.nil? ? nil : integer(value, 0, 4_294_967_295)
+    end
+    private_class_method :optional_integer
+  end
+end

data/lib/apirelio/http_batch_transport.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Apirelio
+  class IngestionError < StandardError
+    attr_reader :status
+
+    def initialize(message, status = 0)
+      super(message)
+      @status = status
+    end
+  end
+
+  class HttpBatchTransport
+    def initialize(endpoint:, api_key:, timeout: 2.0, max_retries: 2)
+      @uri = URI.join("#{endpoint.to_s.sub(%r{/+\z}, "")}/", "ingest/v1/events/batch")
+      @api_key = api_key
+      @timeout = [timeout.to_f, 0.1].max
+      @max_retries = [[max_retries.to_i, 0].max, 10].min
+    end
+
+    def send(events)
+      return if events.empty?
+
+      request = Net::HTTP::Post.new(@uri)
+      request["Accept"] = "application/json"
+      request["Authorization"] = "Bearer #{@api_key}"
+      request["Content-Type"] = "application/json"
+      request["User-Agent"] = "apirelio-ruby/#{VERSION}"
+      request.body = JSON.generate(events: events)
+
+      attempts = 0
+      begin
+        response = Net::HTTP.start(@uri.host, @uri.port, use_ssl: @uri.scheme == "https", open_timeout: @timeout, read_timeout: @timeout) do |http|
+          http.request(request)
+        end
+        status = response.code.to_i
+        return if status.between?(200, 299)
+
+        error = IngestionError.new("Apirelio ingestion returned HTTP #{status}.", status)
+        raise error if status < 500 && status != 429
+        raise error
+      rescue StandardError => error
+        if error.is_a?(IngestionError) && error.status < 500 && error.status != 429
+          raise error
+        end
+        attempts += 1
+        raise error if attempts > @max_retries
+
+        sleep(0.1 * (2**(attempts - 1)))
+        retry
+      end
+    end
+  end
+end

data/lib/apirelio/metadata.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Apirelio
+  module Metadata
+    MAX_ITEMS = 20
+    MAX_BYTES = 4096
+    SENSITIVE = %w[authorization cookie password token secret email ip].freeze
+
+    module_function
+
+    def sanitize(values, allowed_keys: [])
+      safe = {}
+      values.to_h.each do |raw_key, raw_value|
+        key = raw_key.to_s
+        next unless scalar?(raw_value)
+        next if sensitive?(key)
+        next unless key.start_with?("header.") || key == "exception" || allowed_keys.map(&:to_s).include?(key)
+
+        key = key[0, 120]
+        value = raw_value.is_a?(String) ? raw_value[0, 1000] : raw_value
+        candidate = safe.merge(key => value)
+        next if JSON.generate(candidate).bytesize > MAX_BYTES
+
+        safe[key] = value
+        break if safe.length >= MAX_ITEMS
+      end
+      safe
+    end
+
+    def scalar?(value)
+      value.nil? || value == true || value == false || value.is_a?(String) ||
+        (value.is_a?(Numeric) && (!value.respond_to?(:finite?) || value.finite?))
+    end
+    private_class_method :scalar?
+
+    def sensitive?(key)
+      normalized = key.downcase
+      SENSITIVE.any? { |fragment| normalized.include?(fragment) }
+    end
+    private_class_method :sensitive?
+  end
+end

data/lib/apirelio/rack/context.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Apirelio
+  module Rack
+    class Context
+      attr_reader :metadata
+      attr_accessor :error_code
+
+      def initialize
+        @metadata = {}
+        @error_code = nil
+      end
+
+      def add_metadata(values)
+        @metadata.merge!(values)
+        self
+      end
+
+      def set_error_code(value)
+        @error_code = value&.to_s&.slice(0, 255)
+        self
+      end
+    end
+  end
+end

data/lib/apirelio/rack/middleware.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Apirelio
+  module Rack
+    CONTEXT_KEY = "apirelio.context"
+
+    class Middleware
+      def initialize(app, client:, include_routes: [], exclude_routes: [], customer_resolver: nil,
+                     application_resolver: nil, error_code_resolver: nil, metadata_resolver: nil,
+                     route_resolver: nil, api_version_header: "HTTP_X_API_VERSION",
+                     capture_headers: %w[HTTP_X_SDK_VERSION HTTP_USER_AGENT], sdk: "rack",
+                     sdk_version: VERSION)
+        @app = app
+        @client = client
+        @include_routes = include_routes
+        @exclude_routes = exclude_routes
+        @customer_resolver = customer_resolver
+        @application_resolver = application_resolver
+        @error_code_resolver = error_code_resolver
+        @metadata_resolver = metadata_resolver
+        @route_resolver = route_resolver
+        @api_version_header = api_version_header
+        @capture_headers = capture_headers
+        @sdk = sdk
+        @sdk_version = sdk_version
+      end
+
+      def call(env)
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        env[CONTEXT_KEY] = Context.new
+        status, headers, body = @app.call(env)
+        capture(env, status, headers, nil, started_at)
+        [status, headers, body]
+      rescue StandardError => error
+        capture(env, 500, {}, error, started_at)
+        raise
+      end
+
+      private
+
+      def capture(env, status, headers, error, started_at)
+        route = resolved_route(env)
+        return unless Route.capture?(route, include_routes: @include_routes, exclude_routes: @exclude_routes)
+
+        context = env[CONTEXT_KEY]
+        metadata = captured_headers(env)
+        metadata.merge!(resolve(@metadata_resolver, env) || {})
+        metadata.merge!(context.metadata) if context.is_a?(Context)
+        @client.capture(
+          method: env["REQUEST_METHOD"] || "UNKNOWN",
+          route: route,
+          route_name: route_name(env),
+          status: status.to_i,
+          duration_ms: (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000,
+          request_bytes: integer(env["CONTENT_LENGTH"]),
+          response_bytes: integer(header(headers, "content-length")),
+          customer: resolve(@customer_resolver, env),
+          application: resolve(@application_resolver, env),
+          api_version: env[@api_version_header],
+          sdk: @sdk,
+          sdk_version: @sdk_version,
+          error_code: error_code(env, error, status, context),
+          metadata: metadata
+        )
+      rescue StandardError
+        nil
+      end
+
+      def resolved_route(env)
+        value = resolve(@route_resolver, env) || env["action_dispatch.route_uri_pattern"] || env["sinatra.route"] || env["PATH_INFO"] || "/"
+        template = value.to_s.sub(/\(\.:format\)\z/, "").gsub(/:([a-zA-Z_][a-zA-Z0-9_]*)/, "{\\1}")
+        Route.normalize(template)
+      end
+
+      def route_name(env)
+        parameters = env["action_dispatch.request.path_parameters"]
+        return nil unless parameters.respond_to?(:[])
+
+        controller = parameters[:controller] || parameters["controller"]
+        action = parameters[:action] || parameters["action"]
+        [controller, action].compact.join("#").then { |value| value.empty? ? nil : value }
+      end
+
+      def error_code(env, error, status, context)
+        return context.error_code if context.is_a?(Context) && context.error_code
+
+        resolved = @error_code_resolver&.call(env, error, status)
+        resolved ? resolved.to_s[0, 255] : error&.class&.name&.slice(0, 255)
+      rescue StandardError
+        error&.class&.name&.slice(0, 255)
+      end
+
+      def resolve(resolver, env)
+        resolver&.call(env)
+      rescue StandardError
+        nil
+      end
+
+      def captured_headers(env)
+        @capture_headers.each_with_object({}) do |name, values|
+          value = env[name]
+          next if value.nil?
+
+          label = name.to_s.sub(/\AHTTP_/, "").downcase.tr("_", "-")
+          values["header.#{label}"] = value.to_s
+        end
+      end
+
+      def header(headers, name)
+        pair = headers.to_h.find { |key, _| key.to_s.downcase == name }
+        pair&.last
+      end
+
+      def integer(value)
+        Integer(value, exception: false)
+      end
+    end
+
+    module_function
+
+    def context(env)
+      value = env[CONTEXT_KEY]
+      value if value.is_a?(Context)
+    end
+  end
+end

data/lib/apirelio/route.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Apirelio
+  module Route
+    UUID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i
+    ULID = /\A[0-9A-HJKMNP-TV-Z]{26}\z/i
+    INTEGER = /\A\d+\z/
+    HEX_IDENTIFIER = /\A[0-9a-f]{16,}\z/i
+
+    module_function
+
+    def normalize(value)
+      path = value.to_s.split(/[?#]/, 2).first.to_s.strip
+      path = "/" if path.empty?
+      path = "/#{path}" unless path.start_with?("/")
+      normalized = path.split("/", -1).map { |segment| identifier?(segment) ? "{id}" : segment }.join("/")
+      normalized[0, 500]
+    end
+
+    def capture?(value, include_routes: [], exclude_routes: [])
+      included = include_routes.empty? || include_routes.any? { |pattern| match?(value, pattern) }
+      excluded = exclude_routes.any? { |pattern| match?(value, pattern) }
+      included && !excluded
+    end
+
+    def match?(value, pattern)
+      route = normalize(value)
+      expected = normalized_pattern(pattern)
+      return route == expected unless expected.end_with?("/**")
+
+      prefix = expected[0...-3]
+      prefix = "/" if prefix.empty?
+      route == prefix || route.start_with?(prefix == "/" ? "/" : "#{prefix}/")
+    end
+
+    def identifier?(value)
+      INTEGER.match?(value) || UUID.match?(value) || ULID.match?(value) || HEX_IDENTIFIER.match?(value)
+    end
+    private_class_method :identifier?
+
+    def normalized_pattern(value)
+      path = value.to_s.split(/[?#]/, 2).first.to_s.strip
+      path = "/" if path.empty?
+      path = "/#{path}" unless path.start_with?("/")
+      path.length > 1 && path.end_with?("/") ? path[0...-1] : path
+    end
+    private_class_method :normalized_pattern
+  end
+end

data/lib/apirelio/version.rb

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

data/lib/apirelio.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "apirelio/version"
+require_relative "apirelio/route"
+require_relative "apirelio/metadata"
+require_relative "apirelio/event"
+require_relative "apirelio/http_batch_transport"
+require_relative "apirelio/client"
+require_relative "apirelio/rack/context"
+require_relative "apirelio/rack/middleware"
+
+module Apirelio
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: apirelio
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Apirelio
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.20'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.20'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14'
+description: Fail-safe, privacy-safe event delivery and Rack middleware for Apirelio.
+email:
+- info@apirelio.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/apirelio.rb
+- lib/apirelio/client.rb
+- lib/apirelio/event.rb
+- lib/apirelio/http_batch_transport.rb
+- lib/apirelio/metadata.rb
+- lib/apirelio/rack/context.rb
+- lib/apirelio/rack/middleware.rb
+- lib/apirelio/route.rb
+- lib/apirelio/version.rb
+homepage: https://apirelio.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://apirelio.com
+  source_code_uri: https://github.com/pryznar/apirelio-ruby
+  changelog_uri: https://github.com/pryznar/apirelio-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://apirelio.com/docs/ruby
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Customer-aware API analytics for Ruby and Rack applications.
+test_files: []