errbit-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bf16e360e4211384b9c7064f3981b586810521f44102067186e63b7cba2522ba
+  data.tar.gz: 31ffc9af3350871133ee0e6c92684736b3e56b76021e5d083246de24fd2314e9
+SHA512:
+  metadata.gz: 656b9b99cb0a66d575ebe7825ee5e8d0c995707aebba25dc6ca69c603149be50235d530aea9a4c23ca98f3554717be99ba6aa7d3fb1f4d064abf774e7dd243f6
+  data.tar.gz: 291339ec37a09eb42bf877a50bbede6f3aeaff8bf8621658a3c254c93f9e020d4a4c00f65f85604dd771381d75c88836e08dd1a9991d9e527ce83925c501bb60

data/.rspec

@@ -0,0 +1,4 @@
+--require spec_helper
+--format documentation
+-Ilib
+-Ispec

data/.rubocop.yml

@@ -0,0 +1,20 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 4.0
+  SuggestExtensions: false
+  Exclude:
+    - "bin/*"
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "errbit-ruby.gemspec"

data/.ruby-version

@@ -0,0 +1 @@
+4.0.7

data/AGENTS.md

@@ -0,0 +1 @@
+See [CLAUDE.md](./CLAUDE.md) for agent instructions for this project.

data/CLAUDE.md

@@ -0,0 +1,79 @@
+# errbit-ruby
+
+A dependency-free Ruby client for reporting exceptions to an Errbit server.
+Plain Ruby — no Rails, no Rack. Targets Ruby >= 4.0.
+
+## Design constraints (do not violate without asking)
+
+- **Zero runtime dependencies.** The gem may only use Ruby's standard
+  library (`net/http`, `json`, `uri`, ...) at runtime. `rspec`, `webmock`,
+  `rubocop`, `rake`, `irb` are development-only (`add_development_dependency`
+  in `errbit-ruby.gemspec`, or plain `gem` lines in the `Gemfile`).
+- **No Rails, no Rack.** Nothing in `lib/` may assume either is loaded.
+- **This is a new, custom API** — not Airbrake- or Sentry-compatible. The
+  wire format is defined in `openapi/errbit-api.yaml` and that file is the
+  source of truth for the request/response shape the client builds and
+  parses. If you change the payload shape in `lib/errbit/error_report.rb`
+  or `lib/errbit/client.rb`, update the OpenAPI spec to match (and vice
+  versa).
+- **Synchronous delivery only.** `Errbit::Client#notify` makes a blocking
+  `Net::HTTP` call on the caller's thread. No background thread/queue.
+- Target Ruby version is 4.0 (`.ruby-version` pins the local dev version to
+  4.0.7 via rbenv; `required_ruby_version` in the gemspec is `>= 4.0`).
+
+## Project layout
+
+- `lib/errbit.rb` — public entry point: `Errbit.configure`, `Errbit.notify`.
+- `lib/errbit/configuration.rb` — `host`, `project_id`, `api_key`, `ignore`
+  list, timeouts.
+- `lib/errbit/backtrace.rb` — parses `exception.backtrace` lines into
+  `{file:, line:, method:}` hashes. Handles both the pre-3.4 backtick/quote
+  format and the 3.4+ single-quote format.
+- `lib/errbit/error_report.rb` — builds the JSON payload from an
+  `Exception`, matching the `ErrorReport` schema in the OpenAPI spec.
+- `lib/errbit/client.rb` — POSTs to
+  `{host}/api/v1/projects/{project_id}/errors/{api_key}` via `Net::HTTP`,
+  returns an `Errbit::Result`.
+- `lib/errbit/result.rb` — outcome object: `success?` / `ignored?` /
+  `failure?`.
+- `lib/errbit/errors.rb` — `Errbit::Error`, `ConfigurationError`,
+  `DeliveryError` (raised only on network failure, never on a well-formed
+  4xx/5xx from the server — those come back as a failed `Result`).
+- `openapi/errbit-api.yaml` — OpenAPI 3.1 spec for the single ingestion
+  endpoint this gem calls. Update alongside any payload/response change.
+
+## Commands
+
+```sh
+bundle install
+bundle exec rspec          # run the test suite (spec/)
+bundle exec rubocop        # lint
+bundle exec rake           # defaults to spec
+bin/console                # IRB session with Errbit pre-configured
+```
+
+Note: a `rubocop --server` daemon can get stuck/orphaned on this machine
+and hang `bundle exec rubocop`. If it hangs, check `ps aux | grep rubocop`
+and confirm with the user before killing anything; `--no-server` may not
+help if the daemon itself is wedged.
+
+## Testing conventions
+
+- RSpec, with WebMock stubbing all HTTP (`WebMock.disable_net_connect!` in
+  `spec/spec_helper.rb` — real network calls in specs are a bug, not a
+  feature).
+- WebMock's `hash_including` body matchers compare against the
+  **JSON-decoded body with string keys**, not symbols — write
+  `hash_including("error" => hash_including("class" => ...))`, not
+  `hash_including(error: hash_including(class: ...))`. Getting this wrong
+  is a common mistake here and fails silently-looking WebMock diffs.
+- Every spec file lives under `spec/`, mirroring `lib/errbit/*` files
+  1:1 (`lib/errbit/client.rb` <-> `spec/errbit/client_spec.rb`).
+
+## Style
+
+- `# frozen_string_literal: true` at the top of every Ruby file.
+- Double-quoted string literals (enforced by `.rubocop.yml`).
+- No comments explaining *what* code does; only *why*, when non-obvious
+  (see the `DeliveryError` note above for an example of the kind of thing
+  worth a comment).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Zubkov
+
+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,92 @@
+# errbit-ruby
+
+A dependency-free Ruby client for reporting exceptions to an Errbit server.
+Plain Ruby only — no Rails, no Rack required. Targets Ruby >= 4.0 and has
+**zero runtime dependencies** (uses only `net/http`, `json`, and `uri` from
+the standard library).
+
+This gem talks to a new, purpose-built error-ingestion API — it is **not**
+compatible with the Airbrake or Sentry APIs. The API is specified in
+[`openapi/errbit-api.yaml`](openapi/errbit-api.yaml).
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "errbit-ruby", require: "errbit"
+```
+
+or install directly:
+
+```sh
+gem install errbit-ruby
+```
+
+## Usage
+
+Configure once, near your application's boot:
+
+```ruby
+require "errbit"
+
+Errbit.configure do |config|
+  config.host       = "https://errbit.example.com"
+  config.project_id = ENV.fetch("ERRBIT_PROJECT_ID")
+  config.api_key    = ENV.fetch("ERRBIT_API_KEY")
+
+  # Optional: exception classes, class-name strings, or regexps to skip.
+  config.ignore = [ArgumentError, /expected, harmless/i]
+end
+```
+
+Then report exceptions where you rescue them:
+
+```ruby
+begin
+  risky_operation
+rescue => e
+  Errbit.notify(e)
+  raise
+end
+```
+
+`Errbit.notify` returns an `Errbit::Result`:
+
+```ruby
+result = Errbit.notify(e)
+
+result.success? # => true/false
+result.ignored?  # => true if the exception matched config.ignore
+result.failure?  # => true on a 4xx/5xx response from the server
+result.id         # => server-assigned id, on success
+result.error      # => server error message, on failure
+```
+
+A report is delivered synchronously over HTTP(S) on the calling thread. A
+network failure (timeout, connection refused, etc.) raises
+`Errbit::DeliveryError`; a well-formed error response from the server
+(400/401/404) does not raise — check `result.failure?` instead.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+```
+
+`bin/console` starts an IRB session with the gem pre-configured against a
+placeholder host for manual experimentation.
+
+## API
+
+See [`openapi/errbit-api.yaml`](openapi/errbit-api.yaml) for the full
+OpenAPI 3.1 definition of the single endpoint this gem calls:
+
+```
+POST /api/v1/projects/{project_id}/errors/{api_key}
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/errbit/backtrace.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Errbit
+  module Backtrace
+    # Matches both backtrace line formats Ruby has used:
+    #   "file.rb:12:in `method'"   (Ruby <= 3.3)
+    #   "file.rb:12:in 'method'"   (Ruby >= 3.4)
+    # and lines with no method info at all: "file.rb:12"
+    LINE_PATTERN = /\A(?<file>.+):(?<line>\d+)(?::in\s+[`'](?<method>.+)')?\z/.freeze
+
+    module_function
+
+    def parse(exception)
+      Array(exception&.backtrace).map { |line| parse_line(line) }
+    end
+
+    def parse_line(line)
+      match = LINE_PATTERN.match(line.to_s)
+      return { file: line.to_s, line: nil, method: nil } unless match
+
+      {
+        file: match[:file],
+        line: match[:line].to_i,
+        method: match[:method]
+      }
+    end
+  end
+end

data/lib/errbit/client.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Errbit
+  class Client
+    NETWORK_ERRORS = [
+      Errno::ECONNREFUSED,
+      Errno::ECONNRESET,
+      Errno::EHOSTUNREACH,
+      SocketError,
+      Timeout::Error,
+      Net::OpenTimeout,
+      Net::ReadTimeout,
+      OpenSSL::SSL::SSLError
+    ].freeze
+
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    def notify(exception)
+      return Result.ignored if configuration.ignored?(exception)
+
+      configuration.validate!
+      deliver(ErrorReport.build(exception))
+    end
+
+    private
+
+    attr_reader :configuration
+
+    def deliver(payload)
+      uri = endpoint_uri
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request["Accept"] = "application/json"
+      request.body = JSON.generate(payload)
+
+      response = http_client(uri).request(request)
+      build_result(response)
+    rescue *NETWORK_ERRORS => e
+      raise DeliveryError, e
+    end
+
+    def http_client(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = configuration.open_timeout
+      http.read_timeout = configuration.read_timeout
+      http
+    end
+
+    def endpoint_uri
+      base = configuration.host.to_s.chomp("/")
+      URI.parse(
+        "#{base}/api/v1/projects/#{escape(configuration.project_id)}/errors/#{escape(configuration.api_key)}"
+      )
+    end
+
+    def escape(value)
+      URI.encode_www_form_component(value.to_s)
+    end
+
+    def build_result(response)
+      body = parse_json(response.body)
+
+      case response
+      when Net::HTTPAccepted
+        Result.success(status_code: response.code.to_i, id: body["id"], created_at: body["created_at"])
+      else
+        Result.failure(status_code: response.code.to_i, error: body["error"] || response.message)
+      end
+    end
+
+    def parse_json(raw)
+      return {} if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      {}
+    end
+  end
+end

data/lib/errbit/configuration.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Errbit
+  class Configuration
+    attr_accessor :host, :project_id, :api_key, :ignore, :open_timeout, :read_timeout
+
+    def initialize
+      @host = nil
+      @project_id = nil
+      @api_key = nil
+      @ignore = []
+      @open_timeout = 2
+      @read_timeout = 2
+    end
+
+    def ignored?(exception)
+      ignore.any? do |pattern|
+        case pattern
+        when Module
+          exception.is_a?(pattern)
+        when Regexp
+          pattern.match?(exception.message.to_s) || pattern.match?(exception.class.name.to_s)
+        else
+          pattern.to_s == exception.class.name
+        end
+      end
+    end
+
+    def validate!
+      missing = %i[host project_id api_key].select { |attr| public_send(attr).nil? || public_send(attr).to_s.empty? }
+      return if missing.empty?
+
+      raise ConfigurationError, "Errbit is missing required configuration: #{missing.join(', ')}"
+    end
+  end
+end

data/lib/errbit/error_report.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Errbit
+  module ErrorReport
+    module_function
+
+    # Builds a payload matching the ErrorReport schema in
+    # openapi/errbit-api.yaml.
+    def build(exception)
+      {
+        error: {
+          class: exception.class.name,
+          message: exception.message.to_s,
+          backtrace: Backtrace.parse(exception)
+        }
+      }
+    end
+  end
+end

data/lib/errbit/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Errbit
+  Error = Class.new(StandardError)
+  ConfigurationError = Class.new(Error)
+
+  # Raised when the exception could not be delivered at all (network
+  # failure, timeout, connection refused, ...). A well-formed HTTP error
+  # response from the server (4xx/5xx) is *not* raised as this error; it is
+  # surfaced via a failed Result instead.
+  class DeliveryError < Error
+    attr_reader :cause_error
+
+    def initialize(cause_error)
+      @cause_error = cause_error
+      super("Failed to deliver error report: #{cause_error.class}: #{cause_error.message}")
+    end
+  end
+end

data/lib/errbit/result.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Errbit
+  # Outcome of a Client#notify call.
+  class Result
+    attr_reader :status, :status_code, :id, :created_at, :error
+
+    def self.ignored
+      new(status: :ignored)
+    end
+
+    def self.success(status_code:, id:, created_at:)
+      new(status: :success, status_code: status_code, id: id, created_at: created_at)
+    end
+
+    def self.failure(status_code:, error:)
+      new(status: :failure, status_code: status_code, error: error)
+    end
+
+    def initialize(status:, status_code: nil, id: nil, created_at: nil, error: nil)
+      @status = status
+      @status_code = status_code
+      @id = id
+      @created_at = created_at
+      @error = error
+    end
+
+    def success?
+      status == :success
+    end
+
+    def ignored?
+      status == :ignored
+    end
+
+    def failure?
+      status == :failure
+    end
+  end
+end

data/lib/errbit/version.rb

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

data/lib/errbit.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "errbit/version"
+require_relative "errbit/errors"
+require_relative "errbit/result"
+require_relative "errbit/backtrace"
+require_relative "errbit/error_report"
+require_relative "errbit/configuration"
+require_relative "errbit/client"
+
+module Errbit
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+      @client = nil
+      configuration
+    end
+
+    def notify(exception)
+      client.notify(exception)
+    end
+
+    # Resets configuration and memoized client. Primarily useful in tests.
+    def reset!
+      @configuration = nil
+      @client = nil
+    end
+
+    private
+
+    def client
+      @client ||= Client.new(configuration)
+    end
+  end
+end

data/openapi/errbit-api.yaml

@@ -0,0 +1,139 @@
+openapi: 3.1.0
+info:
+  title: Errbit Error Ingestion API
+  description: >
+    A minimal API for reporting application exceptions to an Errbit server.
+    This is a new API design, not compatible with the Airbrake or Sentry
+    APIs. v1 covers error ingestion only.
+  version: "1.0.0"
+
+servers:
+  - url: https://errbit.example.com
+    description: Example Errbit server
+
+paths:
+  /api/v1/projects/{project_id}/errors/{api_key}:
+    post:
+      operationId: createError
+      summary: Report an exception
+      description: >
+        Submits a single exception occurrence for a project. Authenticates
+        the request via the project's API key embedded in the URL path.
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+        - $ref: '#/components/parameters/ApiKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ErrorReport'
+      responses:
+        '202':
+          description: Error report accepted.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorAck'
+        '400':
+          description: Malformed request body.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '401':
+          description: Invalid project_id/api_key combination.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: Unknown project_id.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+components:
+  parameters:
+    ProjectId:
+      name: project_id
+      in: path
+      required: true
+      description: Identifier of the project the error belongs to.
+      schema:
+        type: string
+    ApiKey:
+      name: api_key
+      in: path
+      required: true
+      description: Secret API key authorizing writes to this project.
+      schema:
+        type: string
+
+  schemas:
+    BacktraceFrame:
+      type: object
+      properties:
+        file:
+          type: string
+          description: Source file path for this stack frame.
+        line:
+          type: integer
+          description: Line number within the file, if known.
+        method:
+          type: string
+          description: Method or block name the frame was executing in.
+      additionalProperties: false
+
+    ErrorReport:
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          type: object
+          required:
+            - class
+            - message
+          properties:
+            class:
+              type: string
+              description: Fully qualified exception class name.
+              examples:
+                - RuntimeError
+                - "Net::OpenTimeout"
+            message:
+              type: string
+              description: Exception message.
+            backtrace:
+              type: array
+              description: Ordered stack frames, innermost first.
+              items:
+                $ref: '#/components/schemas/BacktraceFrame'
+          additionalProperties: false
+      additionalProperties: false
+
+    ErrorAck:
+      type: object
+      required:
+        - id
+        - created_at
+      properties:
+        id:
+          type: string
+          description: Server-assigned identifier for the stored error occurrence.
+        created_at:
+          type: string
+          format: date-time
+      additionalProperties: false
+
+    ErrorResponse:
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          type: string
+          description: Human-readable error message.
+      additionalProperties: false

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: errbit-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Igor Zubkov
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+description: |
+  A dependency-free Ruby gem that catches and reports exceptions to an
+  Errbit server over its error-ingestion API. No Rails, no Rack required.
+email:
+- igor.zubkov@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- AGENTS.md
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/errbit.rb
+- lib/errbit/backtrace.rb
+- lib/errbit/client.rb
+- lib/errbit/configuration.rb
+- lib/errbit/error_report.rb
+- lib/errbit/errors.rb
+- lib/errbit/result.rb
+- lib/errbit/version.rb
+- openapi/errbit-api.yaml
+homepage: https://github.com/errbit/errbit-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/errbit/errbit-ruby
+  source_code_uri: https://github.com/errbit/errbit-ruby
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.21
+specification_version: 4
+summary: Plain-Ruby client for reporting exceptions to an Errbit server.
+test_files: []