hawk-ruby 0.1.0

data/lib/hawk/source.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Hawk
+  # Backtraces remain useful when source files are unavailable or excluded.
+  class Source
+    def initialize(configuration)
+      @enabled = configuration.send_source
+      @roots = configuration.source_roots.filter_map { |root| realpath(root) }
+    end
+
+    def frames(exception)
+      locations = exception.backtrace_locations
+      if locations && !locations.empty?
+        locations.take(100).filter_map { |location| location_frame(location) }
+      else
+        (exception.backtrace || []).take(100).filter_map { |line| parse(line) }
+      end
+    rescue StandardError
+      []
+    end
+
+    private
+
+    def location_frame(location)
+      path = location.absolute_path || location.path
+      frame(path, location.lineno, location.base_label) if path
+    end
+
+    def realpath(path)
+      File.realpath(path)
+    rescue SystemCallError, ArgumentError
+      nil
+    end
+
+    def parse(value)
+      match = /\A(.+):(\d+)(?::in [`'](.*)[`'])?\z/.match(value)
+      return unless match
+
+      frame(match[1].to_s, match[2].to_i, match[3])
+    end
+
+    def frame(path, line, function)
+      return unless line.positive?
+
+      # @type var result: payload
+      result = { "file" => path, "line" => line }
+      result["function"] = function if function
+      snippets = snippets(path, line)
+      result["sourceCode"] = snippets unless snippets.empty?
+      result
+    end
+
+    def snippets(path, line)
+      return [] unless @enabled
+
+      resolved = readable_path(path)
+      return [] unless resolved
+
+      content = File.binread(resolved, 1_048_577)
+      return [] if content.bytesize > 1_048_576
+
+      excerpt(content, line)
+    rescue SystemCallError, IOError, ArgumentError
+      []
+    end
+
+    def readable_path(path)
+      resolved = realpath(path)
+      return unless resolved && @roots.any? { |root| resolved.start_with?("#{root}/") }
+
+      resolved if File.file?(resolved) && File.size(resolved) <= 1_048_576
+    end
+
+    def excerpt(content, line)
+      lines = content.force_encoding(Encoding::UTF_8).scrub.lines
+      first = [line - 6, 0].max
+      width = [line + 5 - first, 11].min
+      (lines[first, width] || []).each_with_index.map do |text, index|
+        { "line" => first + index + 1, "content" => text.chomp }
+      end
+    end
+  end
+end

data/lib/hawk/token.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "uri"
+
+module Hawk
+  class ConfigurationError < ArgumentError; end
+
+  # Resolves collector identity without exposing the integration secret.
+  class Token
+    LABEL = /\A[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\z/i
+
+    def self.decode(value)
+      raise ConfigurationError, "Invalid Hawk integration token" if value.bytesize > 8192
+
+      # @type var data: top
+      data = JSON.parse(Base64.strict_decode64(value))
+      id = integration_id(data)
+      raise ConfigurationError, "Invalid Hawk integration token" unless id
+
+      new(id)
+    rescue JSON::ParserError, ArgumentError
+      raise ConfigurationError, "Invalid Hawk integration token"
+    end
+
+    def self.integration_id(data)
+      case data
+      when Hash
+        id = data["integrationId"]
+        case id
+        when String
+          id if LABEL.match?(id) && valid_secret?(data["secret"])
+        end
+      end
+    end
+
+    def self.valid_secret?(value)
+      case value
+      when String then !value.empty?
+      else false
+      end
+    end
+
+    def initialize(integration_id)
+      @integration_id = integration_id
+    end
+
+    def endpoint
+      URI::HTTPS.build(host: "#{@integration_id}.k1.hawk.so")
+    end
+  end
+end

data/lib/hawk/transport.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "timeout"
+require "time"
+
+module Hawk
+  # Every send performs at most one POST, with a bounded response and deadline.
+  class Transport
+    class ResponseTooLarge < StandardError; end
+
+    def initialize(configuration)
+      configuration.validate!
+      @configuration = configuration
+      uri = configuration.collector_uri if configuration.enabled?
+      @uri = uri.is_a?(URI::HTTP) ? uri : nil
+      reset
+    end
+
+    def available?
+      reset if @pid != Process.pid
+      @mutex.synchronize { !@uri.nil? && monotonic >= @cooldown_until }
+    end
+
+    def send(encoded)
+      uri = @uri
+      return :limited unless uri && available?
+
+      Breadcrumbs.guard(:sdk) { Timeout.timeout(5.0) { request(encoded, uri) } }
+    rescue StandardError
+      :failed
+    end
+
+    private
+
+    def reset
+      @mutex = Mutex.new
+      @cooldown_until = 0.0
+      @pid = Process.pid
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def connection(uri)
+      http = Net::HTTP.new(uri.hostname.to_s, uri.port, nil)
+      http.use_ssl = uri.is_a?(URI::HTTPS)
+      http.open_timeout = @configuration.connect_timeout
+      http.read_timeout = @configuration.read_timeout
+      http.write_timeout = @configuration.write_timeout
+      http.max_retries = 0
+      http
+    end
+
+    def request(encoded, uri)
+      post = Net::HTTP::Post.new(uri.request_uri)
+      post["Content-Type"] = "application/json"
+      post.body = encoded
+      result = :failed
+      connection(uri).start do |http|
+        http.request(post) { |response| result = handle(response) }
+      end
+      result
+    end
+
+    def handle(response)
+      case response.code
+      when "402", "429"
+        cooldown(response["Retry-After"])
+        :limited
+      when "200"
+        success?(response_body(response)) ? :accepted : :failed
+      else :failed
+      end
+    end
+
+    def response_body(response)
+      content = +""
+      response.read_body do |part|
+        raise ResponseTooLarge, "Collector response exceeds limit" if content.bytesize + part.bytesize > 16_384
+
+        content << part
+      end
+      content
+    end
+
+    def success?(content)
+      # @type var data: top
+      data = JSON.parse(content)
+      case data
+      when Hash then JSONValue.object(data).values_at("code", "error") == [200, false]
+      else false
+      end
+    end
+
+    def cooldown(header)
+      delay = retry_delay(header)
+      @mutex.synchronize { @cooldown_until = monotonic + delay.clamp(0.0, 300.0) }
+    end
+
+    def retry_delay(header)
+      return @configuration.limit_cooldown unless header
+      return header.to_f if /\A\d+\z/.match?(header)
+
+      Time.httpdate(header) - Time.now
+    rescue ArgumentError
+      @configuration.limit_cooldown
+    end
+  end
+end

data/lib/hawk/version.rb

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

data/lib/hawk.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "hawk/version"
+require_relative "hawk/token"
+require_relative "hawk/configuration"
+require_relative "hawk/release"
+require_relative "hawk/json_value"
+require_relative "hawk/filter"
+require_relative "hawk/hook"
+require_relative "hawk/filtered_fields"
+require_relative "hawk/framework_filter"
+require_relative "hawk/source"
+require_relative "hawk/event"
+require_relative "hawk/diagnostics"
+require_relative "hawk/scope"
+require_relative "hawk/scope_store"
+require_relative "hawk/client"
+require_relative "hawk/breadcrumbs"
+require_relative "hawk/job_context"
+require_relative "hawk/boundary"
+require_relative "hawk/transport"
+require_relative "hawk/delivery"
+require_relative "hawk/process_hooks"
+
+# The default client offers the same capture API as independent project clients.
+module Hawk
+  class << self
+    attr_reader :client
+
+    def init
+      configuration = Configuration.new
+      yield configuration
+      Rails.configure(configuration) if defined?(Hawk::Rails)
+      replacement = Client.build(configuration)
+      @client&.close
+      @client = replacement
+      Breadcrumbs.install(configuration)
+      ProcessHooks.install if configuration.enabled? && configuration.global_errors
+      replacement
+    end
+
+    def capture_exception(exception, context: {}, user: nil, level: :error)
+      @client&.capture_exception(exception, context: context, user: user, level: level)
+    end
+
+    def capture_message(message, context: {}, user: nil, level: :info)
+      @client&.capture_message(message, context: context, user: user, level: level)
+    end
+
+    def set_context(context)
+      @client&.set_context(context)
+    end
+
+    def add_breadcrumb(entry)
+      @client&.add_breadcrumb(entry)
+    end
+
+    def set_user(user)
+      @client&.set_user(user)
+    end
+
+    def with_scope(&)
+      client = @client
+      client ? client.with_scope(&) : yield(Scope.new)
+    end
+
+    def capture(&)
+      client = @client
+      client ? client.capture(&) : yield
+    end
+
+    def flush(timeout: nil)
+      client = @client
+      client ? client.flush(timeout: timeout || client.configuration.flush_timeout) : true
+    end
+
+    def close(timeout: nil)
+      previous = @client
+      @client = nil
+      previous ? previous.close(timeout: timeout || previous.configuration.flush_timeout) : true
+    end
+  end
+end
+
+require_relative "hawk/rails/integration" if defined?(Rails::Railtie)

data/sig/hawk/boundary.rbs

@@ -0,0 +1,7 @@
+module Hawk
+  module Boundary
+    def self.run: [A] (Client, kind: Symbol, metadata: payload, ?inherit: bool) { () -> A } -> A
+    def self.resume: [A] (Client, Scope) { () -> A } -> A
+    private def self.protect: [A] (Client, Symbol) { () -> A } -> A
+  end
+end

data/sig/hawk/breadcrumbs/logger.rbs

@@ -0,0 +1,17 @@
+module Hawk::Breadcrumbs
+  interface _Logger
+    def level: () -> Integer
+    def add: (Integer?, ?top, ?String?) ?{ () -> top } -> bool
+  end
+  module Logger
+    LEVELS: Array[Symbol]
+    def self.install: () -> void
+    def self.record: (Hawk::Client, Integer, top) -> void
+    def self.empty_message?: (top) -> bool
+    def self.message: (top, String?) -> top
+    module Methods : _Logger
+      def add: (Integer?, ?top, ?String?) ?{ () -> top } -> bool
+      alias log add
+    end
+  end
+end

data/sig/hawk/breadcrumbs/net_http.rbs

@@ -0,0 +1,16 @@
+module Hawk::Breadcrumbs
+  interface _HTTP
+    def start: [A] () ?{ (::Net::HTTP) -> A } -> (::Net::HTTP | A)
+    def address: () -> String
+    def request: (::Net::HTTPRequest, ?String?) ?{ (::Net::HTTPResponse) -> top } -> ::Net::HTTPResponse
+  end
+  module NetHTTP
+    def self.install: () -> void
+    def self.record: (Hawk::Client, ::Net::HTTPRequest, String, String?, Float) -> void
+    def self.connection_failed: (Hawk::Client, String, Float) -> void
+    module Methods : _HTTP
+      def start: [A] () ?{ (::Net::HTTP) -> A } -> (::Net::HTTP | A)
+      def request: (::Net::HTTPRequest, ?String?) ?{ (::Net::HTTPResponse) -> top } -> ::Net::HTTPResponse
+    end
+  end
+end

data/sig/hawk/breadcrumbs/rails.rbs

@@ -0,0 +1,7 @@
+module Hawk::Breadcrumbs
+  module Rails
+    self.@installed: bool?
+    EVENTS: Regexp
+    def self.install: () -> void
+  end
+end

data/sig/hawk/breadcrumbs.rbs

@@ -0,0 +1,13 @@
+module Hawk
+  module Breadcrumbs
+    def self.install: (Configuration) -> void
+    def self.guard: [A] (Symbol) { () -> A } -> A
+    def self.suppressed?: (Symbol) -> bool
+    def self.client: (Symbol) -> Client?
+    def self.add: (Client, raw_context) -> void
+    private
+    def self.filtered: (Configuration, raw_context) -> payload?
+    def self.framework_filtered: (Configuration, payload) -> payload?
+    def self.enabled?: (Configuration, Symbol) -> bool
+  end
+end

data/sig/hawk/client.rbs

@@ -0,0 +1,41 @@
+module Hawk
+  interface _Delivery
+    def enqueue: (String, String) -> bool
+    def flush: (timeout: Float) -> bool
+    def close: (timeout: Float) -> bool
+  end
+
+  class Client
+    @delivery: _Delivery
+    @store: ScopeStore
+    @closed: bool
+    attr_reader configuration: Configuration
+    attr_reader diagnostics: Diagnostics
+    def self.build: (Configuration) -> Client
+    def initialize: (Configuration, delivery: _Delivery, ?diagnostics: Diagnostics?) -> void
+    def current_scope: () -> Scope
+    def enabled?: () -> bool
+    def using_scope: [A] (Scope) { () -> A } -> A
+    def set_context: (raw_context) -> void
+    def add_breadcrumb: (raw_context) -> void
+    def set_user: (raw_context?) -> void
+    def with_scope: [A] () { (Scope) -> A } -> A
+    def with_boundary: [A] (kind: Symbol, metadata: payload, ?inherit: bool) { () -> A } -> A
+    def capture_exception: (Exception, ?context: raw_context, ?user: raw_context?, ?level: Symbol) -> String?
+    def capture_message: (String, ?context: raw_context, ?user: raw_context?, ?level: Symbol) -> String?
+    def capture: [A] () { () -> A } -> A
+    def report: (Exception, mechanism: String, ?context: payload, ?level: Symbol, ?handled: bool) -> String?
+    def remember_escape: (Exception) -> void
+    def consume_escape: (Exception) -> bool
+    def flush: (?timeout: Float) -> bool
+    def close: (?timeout: Float) -> bool
+
+    private
+
+    def boundary_scope: (Scope, Symbol, payload, bool) -> Scope
+    def dispatch: (?exception: Exception?, ?message: String?, ?context: raw_context, ?user: raw_context?, ?level: Symbol, ?addons: payload) -> String?
+    def eligible?: (Exception?) -> bool
+    def normal_termination?: (Exception) -> bool
+    def expected_request_error?: (Exception) -> bool
+  end
+end

data/sig/hawk/configuration.rbs

@@ -0,0 +1,61 @@
+module Hawk
+  type raw_context = Hash[String | Symbol, top]
+  type payload = Hash[String, json]
+  type payload_hook = ^(payload) -> top
+
+  class Configuration
+    attr_accessor diagnostic_logger: _DiagnosticLogger?
+    attr_accessor token: String?
+    attr_accessor endpoint: String?
+    attr_accessor environment: String
+    attr_accessor enabled_environments: Array[String]?
+    attr_accessor release: String?
+    attr_accessor detect_release: bool
+    attr_accessor sample_rate: Float
+    attr_accessor delivery_mode: Symbol
+    attr_accessor queue_capacity: Integer
+    attr_accessor source_roots: Array[String]
+    attr_accessor send_source: bool
+    attr_accessor connect_timeout: Float
+    attr_accessor read_timeout: Float
+    attr_accessor write_timeout: Float
+    attr_accessor flush_timeout: Float
+    attr_accessor limit_cooldown: Float
+    attr_accessor context: raw_context
+    attr_accessor user: raw_context?
+    attr_accessor ignored_exceptions: Array[String]
+    attr_accessor filter_parameters: Array[String | Regexp]
+    attr_accessor integrations: Hash[Symbol, bool]
+    attr_accessor global_errors: bool
+    attr_accessor before_send: payload_hook?
+    attr_accessor before_breadcrumb: payload_hook?
+    attr_accessor framework_filter: payload_hook?
+    attr_accessor diagnostic_callback: (^(Hash[Symbol, Integer]) -> void)?
+    attr_accessor propagate_job_context: bool
+    attr_accessor include_request_body: bool
+    attr_accessor include_job_arguments: bool
+    attr_accessor include_headers: bool
+    attr_accessor include_cookies: bool
+    attr_accessor breadcrumbs_logger: bool
+    attr_accessor breadcrumbs_http: bool
+    attr_accessor breadcrumbs_rails: bool
+    attr_accessor logger_error_level: Integer?
+
+    def initialize: () -> void
+    def validate!: () -> void
+    def enabled?: () -> bool
+    def collector_uri: () -> URI::Generic
+    def integration_enabled?: (Symbol) -> bool
+
+    private
+
+    def allowed_uri?: (URI::Generic) -> bool
+    def initialize_identity: () -> void
+    def initialize_delivery: () -> void
+    def initialize_privacy: () -> void
+    def initialize_hooks: () -> void
+    def validate_delivery: () -> void
+    def valid_number?: (top) -> bool
+    def validate_callbacks: () -> void
+  end
+end

data/sig/hawk/delayed_job.rbs

@@ -0,0 +1,24 @@
+module Hawk
+  interface _DelayedJob
+    def id: () -> Integer?
+    def queue: () -> String?
+    def attempts: () -> Integer
+    def error: () -> Exception?
+  end
+
+  interface _DelayedLifecycle
+    def around: (Symbol) { (top, _DelayedJob) -> top } -> void
+    def after: (Symbol) { (top, _DelayedJob) -> top } -> void
+  end
+
+  module DelayedJob
+    def self.install: () -> void
+    def self.supported_version?: () -> bool
+    def self.client: () -> Client?
+    def self.run: [A] (_DelayedJob) { () -> A } -> A
+    def self.report: (_DelayedJob) -> void
+    AROUND: ^(top, _DelayedJob) ?{ () -> top } -> top
+    class Plugin
+    end
+  end
+end

data/sig/hawk/delivery.rbs

@@ -0,0 +1,27 @@
+module Hawk
+  class Delivery
+    @configuration: Configuration
+    @transport: _Transport
+    @diagnostics: Diagnostics
+    @mutex: Thread::Mutex
+    @condition: Thread::ConditionVariable
+    @queue: Array[String]
+    @pending: Integer
+    @worker: Thread?
+    @pid: Integer
+    @closed: bool
+    def initialize: (Configuration, transport: _Transport, diagnostics: Diagnostics) -> void
+    def enqueue: (String, String) -> bool
+    def flush: (timeout: Float) -> bool
+    def close: (timeout: Float) -> bool
+
+    private
+
+    def reset: () -> void
+    def monotonic: () -> Float
+    def accept: (String) -> bool
+    def next_event: () -> String?
+    def work: () -> void
+    def deliver: (String) -> void
+  end
+end

data/sig/hawk/diagnostics.rbs

@@ -0,0 +1,24 @@
+module Hawk
+  interface _DiagnosticLogger
+    def warn: (String) -> top
+  end
+  type diagnostic_hook = ^(Hash[Symbol, Integer]) -> void
+
+  class Diagnostics
+    @logger: _DiagnosticLogger?
+    @callback: (^(Hash[Symbol, Integer]) -> void)?
+    @pid: Integer
+    @mutex: Thread::Mutex
+    @counts: Hash[Symbol, Integer]
+    @notifying: bool
+    def initialize: (?diagnostic_hook?, ?logger: _DiagnosticLogger?) -> void
+    def increment: (Symbol) -> void
+    def snapshot: () -> Hash[Symbol, Integer]
+
+    private
+
+    def notify: () -> void
+    def emit: () -> void
+    def reset: () -> void
+  end
+end

data/sig/hawk/event.rbs

@@ -0,0 +1,24 @@
+module Hawk
+  class Event
+    @addons: payload
+    @configuration: Configuration
+    @payload: payload
+    @filtered_paths: Array[Array[String]]
+    def initialize: (configuration: Configuration, id: String, ?exception: Exception?, ?message: String?, ?context: raw_context, ?user: raw_context?, ?breadcrumbs: Array[payload], ?addons: payload, ?level: Symbol, ?filtered_paths: Array[Array[String]]) -> void
+    def encode: () -> String?
+
+    private
+
+    def filtered_payload: () -> payload?
+    def title: (Exception) -> String
+    def metadata: (String, Symbol) -> payload
+    def attach_exception: (Exception) -> void
+    def causes: (Exception) -> Array[payload]
+    def valid_payload?: (payload) -> bool
+    def envelope: (payload) -> String
+    def bounded_envelope: (payload) -> String?
+    def trim: (payload, Symbol) -> void
+    def trim_sources: (payload) -> void
+    def keep_first: (payload, String, ?newest: bool) -> void
+  end
+end

data/sig/hawk/filter.rbs

@@ -0,0 +1,13 @@
+module Hawk
+  class Filter
+    SENSITIVE: Regexp
+    @patterns: Array[Regexp]
+    def initialize: (Configuration) -> void
+    def call: (json) -> json
+
+    private
+
+    def filter: (json) -> json
+    def sensitive?: (String) -> bool
+  end
+end

data/sig/hawk/filtered_fields.rbs

@@ -0,0 +1,11 @@
+module Hawk
+  class FilteredFields
+    @entries: Array[[Array[String], String, json]]
+    def initialize: (payload, Array[Array[String]], ?containers_only: bool) -> void
+    def restore: (payload) { (String, json) -> json } -> payload
+    private
+    def extract: (payload, Array[String], bool) -> void
+    def container?: (json) -> bool
+    def parent_at: (payload, Array[String]) -> payload?
+  end
+end

data/sig/hawk/framework_filter.rbs

@@ -0,0 +1,5 @@
+module Hawk
+  module FrameworkFilter
+    def self.call: (Configuration, payload, ?Array[Array[String]]) -> payload?
+  end
+end

data/sig/hawk/hook.rbs

@@ -0,0 +1,5 @@
+module Hawk
+  module Hook
+    def self.call: [A] () { () -> A } -> A?
+  end
+end

data/sig/hawk/job_context.rbs

@@ -0,0 +1,15 @@
+module Hawk
+  module JobContext
+    def self.dump: (Client) -> payload?
+    def self.load: (top) -> payload?
+    def self.apply: (Client, top) -> void
+    private
+    def self.valid?: (top, Integer, Hash[Symbol, Integer]) -> bool
+    def self.valid_header?: (payload) -> bool
+    def self.object?: (top, ?optional: bool) -> bool
+    def self.valid_scalar?: (top) -> bool
+    def self.valid_key?: (top) -> bool
+    def self.valid_object?: (Hash[top, top], Integer, Hash[Symbol, Integer]) -> bool
+    def self.valid_array?: (Array[top], Integer, Hash[Symbol, Integer]) -> bool
+  end
+end