fractal-ruby 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb85bbae2629a4f35ac315bda48069d46f952a44391422d162e88d05814d6724
-  data.tar.gz: 68f9802f6b2e0db444ce472670269dab8e626d13370adcd47037c362430831ce
+  metadata.gz: 615b951995ae41b5f65de476b803939adbe4f7961cbfb74386a3aaeabe3b553f
+  data.tar.gz: a1f0e0c5ea5d68348b8909ac43671dd9b1e17a0824250adf4060f914adb59920
 SHA512:
-  metadata.gz: a228762b9ee48fe5e87c4d12b4dcda604a0138b57610c9e7ff5cbdcd0f194b001437fc2e4c51ca18824a3ad98c4f5371d18f1d51b5eb77db4729e664a0bf8229
-  data.tar.gz: b43092221f112e42367e98c4f8cebb200ce6369c4f2a598395aab3abeb0474e411fe95177c822e465d9a63a970a4b882ad71b416b5c7465a294cbd5e7b147593
+  metadata.gz: b2d2d7f93927d401c308962682cfc37d0b3f28f50285bce8c0689f412474197ac0776086c6cfe343042c14e4c2da0857271e4dda729aa320b9dfd0dfb8660eff
+  data.tar.gz: 275083871077a6fb4b2c9d0babd6a1849a28c1deccf6fe699feb942222f7a844bfd99ccd341d1730e65b35fe4ef06f269069870e9d1a2d5512c68c89e0427c78

data/CHANGELOG.md

@@ -3,10 +3,16 @@
 All notable changes to the `fractal-ruby` gem. The version lives in `VERSION`;
 `ci/check_version_sync.sh` keeps `lib/fractal/version.rb`, this file and the lockfiles in step.
 
+## 0.1.1
+
+- **402 wording:** a `402 free_plan_locked` from the collector (the Free plan is locked and the
+  organization is on it, #555, ADR 0016) is now logged as that, instead of "this plan has no
+  error tracking". Error reporting still stops for the rest of the process on either 402.
+
 ## 0.1.0
 
-First version (#495, ADR 0003). Not yet published to rubygems.org (#497); Fractal's own app uses it
-from the path.
+First version (#495, ADR 0003). Published to rubygems.org on 2026-10-12 (#497); Fractal's own app
+uses it from the path.
 
 - **Errors**, extracted from Fractal's in-repo self-reporter (`lib/self_report/`, #426): a Railtie
   adds an outermost Rack middleware and a `Rails.error` subscriber; events are built from an

data/README.md

@@ -8,7 +8,7 @@ same conformance check.
 Requires Ruby 3.2+ and Rails 7.1+ (ADR 0003). The core (transport, buffers, scrubber, fingerprint,
 `track`) is plain Ruby; the Railtie is the supported entry point for the first release.
 
-> Not published yet (#497). Fractal's own app uses it from the path:
+> Published on rubygems.org as `fractal-ruby`. Fractal's own app uses it from the path:
 > `gem "fractal-ruby", path: "sdks/ruby"`.
 
 ## Setup
@@ -81,6 +81,7 @@ Delivery is **at least once**: a request whose response is lost is retried and s
 | | Default | Override |
 | --- | --- | --- |
 | Player | the scope's user (`Fractal.set_user`, or Warden), else `user_resolver`, else `"anonymous"` inside a request and `"system"` outside one (jobs, rake, boot) | `track(..., player_id:)`, `anonymous_player_id`, `system_player_id` |
+| Account | the same id as the player whenever a user is known; never sent for the `anonymous` and `system` buckets. A game client that calls `set_account_id` with the same id counts as the same player in the dashboard | not separately configurable |
 | Session | a hash of the Rack session id (the raw id is never sent); with no session (jobs, cookie-less APIs), one session per player per UTC day | `track(..., session_token:)`, `Fractal.set_session(token)`, `session_resolver` |
 | End-user address | the request's address (`request.remote_ip`, which honours your trusted proxies) | `track(..., client_ip:)`, `send_client_ip = false` |
 
@@ -137,13 +138,6 @@ tags and skips the push with a warning; re-run it by hand (`workflow_dispatch`)
 set. The key needs the "push rubygem" scope, on an account whose MFA level is "UI and gem signin":
 at "UI and API" every push asks for an OTP that CI cannot give.
 
-**Before the first deploy that advertises the gem.** The Settings quick start and the help article
-(`content/help/{en,es}/sdk-integration/ruby.md`) tell customers to add `gem "fractal-ruby"`, and
-the name is not registered on rubygems.org until the first push. Push 0.1.0 by hand from the
-owning account (or set the secret and dispatch the workflow) before running `bin/deploy`: until
-then the install line fails and the name is free for anyone to claim. Shipping the copy ahead of
-the push was an owner decision (2026-10-12), not an oversight.
-
 `spec/fractal/package_spec.rb` builds the gem the same way and checks what is inside it.
 
 ## License

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/lib/fractal/analytics.rb

@@ -175,6 +175,7 @@ module Fractal
         "player_id" => player,
         "session_token" => session_token.to_s.empty? ? session_for(scope, player) : session_token.to_s
       }
+      event["account_id"] = player if @identity.account?(player)
       ip = client_ip.to_s.empty? ? client_ip_for(scope) : client_ip.to_s
       ip = serialisable_ip(ip) if ip
       event["client_ip"] = ip if ip

data/lib/fractal/error_reporter.rb

@@ -59,8 +59,8 @@ module Fractal
       log(:error, "report failed: #{e.class}")
     end
 
-    # Delivers up to MAX_POSTS_PER_FLUSH batches (one per player: /v1/errors has no per-event
-    # player). Never raises.
+    # Delivers up to MAX_POSTS_PER_FLUSH batches, one per player with the player in the context
+    # (the gem's choice: /v1/errors also takes a per-error player_id). Never raises.
     def flush(deadline: nil)
       reset_after_fork
       unless enabled?
@@ -234,7 +234,7 @@ module Fractal
       when 402
         @mutex.synchronize { @disabled = true }
         discard_buffer
-        log(:warn, "collector answered 402: this plan has no error tracking. Error reporting is off for the rest of this process")
+        log(:warn, "collector answered 402: #{payment_required_reason(response.body)}. Error reporting is off for the rest of this process")
       when 429, 500..599
         failed(entries, requeue: true)
         log(:warn, "collector answered #{response.code}; will retry")
@@ -244,6 +244,19 @@ module Fractal
       end
     end
 
+    # The collector answers 402 for two reasons; the handling is the same, the wording is not.
+    def payment_required_reason(body)
+      json = JSON.parse(body.to_s)
+      code = json["code"] if json.is_a?(Hash)
+      if code == "free_plan_locked"
+        "the Free plan is locked and this organization is on it (ADR 0016); choose a paid plan to send data"
+      else
+        "this plan has no error tracking"
+      end
+    rescue JSON::ParserError
+      "this plan has no error tracking"
+    end
+
     def succeeded(entries, body)
       @breaker.success!
       bump(:sent_events, entries.size)
@@ -268,13 +281,15 @@ module Fractal
 
     def payload(player_id, entries)
       os = Etc.uname
+      context = {
+        player_id: player_id, session_token: "", platform: "server", app_version: @config.app_version.to_s,
+        environment: @config.environment, runtime_version: "ruby #{RUBY_VERSION}", os_name: os[:sysname],
+        os_version: os[:release], sdk_version: Fractal.sdk_version
+      }
+      context[:account_id] = player_id if Identity.new(@config).account?(player_id)
       {
         sent_at: Time.now.utc.iso8601(3),
-        context: {
-          player_id: player_id, session_token: "", platform: "server", app_version: @config.app_version.to_s,
-          environment: @config.environment, runtime_version: "ruby #{RUBY_VERSION}", os_name: os[:sysname],
-          os_version: os[:release], sdk_version: Fractal.sdk_version
-        },
+        context: context,
         errors: entries.map do |entry|
           entry.event.merge("occurrence_count" => entry.count, "timestamp" => entry.first_at.iso8601(3))
         end

data/lib/fractal/event_builder.rb

@@ -68,7 +68,8 @@ module Fractal
       text.scrub("?")
     end
 
-    # environment rides in tags until the collector stores it (#485).
+    # environment is also a tag: the collector stores the error's own environment as a column
+    # since #485 (ADR 0017), and the tag is kept for errors ingested before that.
     def tags(source, controller, job)
       tags = { "environment" => @config.environment, "source" => source.to_s }
       tags["controller_action"] = "#{controller.controller_path}##{controller.action_name}" if controller.respond_to?(:controller_path)

data/lib/fractal/fingerprint.rb

@@ -53,6 +53,50 @@ module Fractal
     RUBY_LINE_PATTERN     = /\A((?:\[(?:gem|ruby|other)\] )?\S+\.rb):\d+(:in )/
     RUBY_ERB_LINE_PATTERN = /\A((?:\[(?:gem|ruby|other)\] )?\S+\.erb):\d+:in .*\z/
 
+    # minidump-stackwalk (rust-minidump) human report: "Thread 3 {name} (crashed) - tid: 7" (an
+    # unnamed thread leaves a double space), then frames
+    # " 0  module!function [file.cc : 58 + 0x3]", " 0  module!function + 0x2c" or " 0  module + 0x429e".
+    # A Rails backend never reports one; the extractor is here so this port matches every shared
+    # vector. Behaviour for Ruby traces is unchanged, so it needs no gem release of its own.
+    STACKWALK_CRASHED_THREAD_PATTERN = /\AThread \d+ .*\(crashed\) - tid:/
+    STACKWALK_FRAME_INDEX_PATTERN    = /\A\d+\s+/
+    STACKWALK_SOURCE_LINE_PATTERN    = / : \d+(?: \+ 0x[0-9a-fA-F]+)?\]\z/
+    STACKWALK_FUNC_OFFSET_PATTERN    = /\A(\S+!.+?) \+ 0x[0-9a-fA-F]+\z/
+
+    # A Rails backend never reports a C# trace either; the extractor is here for the same reason
+    # as the stackwalk one: this port must match every shared vector (the Unity SDK, ADR 0023 §9).
+    # Behaviour for Ruby traces is unchanged, so it needs no gem release of its own.
+    # C# frames come in three shapes (ADR 0023 §9). A shape is STRONG when it ends in a tail that no
+    # other format prints, and only a strong frame makes csharp_frame claim a trace:
+    #   Mono     "at Game.Player.TakeDamage (System.Int32 amount) [0x0001a] in /proj/Player.cs:42"
+    #            (IL2CPP: "[0x00000] in <000...>:0"): the " in <path>:N" tail.
+    #   CoreCLR  "at Game.Player.TakeDamage(Int32 amount) in /src/Player.cs:line 42": the
+    #            " in <path>:line N" tail.
+    #   Unity    "Game.Player.TakeDamage (System.Int32 amount) (at Assets/Player.cs:42)": the
+    #            "(at <path>:N)" tail. Also strong, with no tail: "UnityEngine.Debug:LogError (object)",
+    #            a "Type:Method" frame of the engine itself, which starts every Debug.Log trace.
+    # The same shapes without their tail are WEAK, because other formats print them too: a JVM frame
+    # reads "at pkg.Type.method(SourceFile)", and "word:word (text)" is also a message line or a gin
+    # "path.go:42 (0x14a2b3c)" line. A weak line is a frame only inside a trace that a strong frame claims.
+    # Explicit character classes only (no \s, \w, \d), so Go's RE2 and Onigmo cannot disagree.
+    CSHARP_MONO_FRAME_PATTERN    = /\Aat (?:\(wrapper [a-z-]+\) )?([^ ()]+) ?\(([^()]*)\) (?:(?:\[0x[0-9a-fA-F]+\]|<0x[0-9a-fA-F]+(?: \+ 0x[0-9a-fA-F]+)?>) )?in .+:[0-9]+\z/
+    CSHARP_CORECLR_FRAME_PATTERN = /\Aat ([^ ():]*[.][^ ():]+)\(([^():]*)\)( in .+:line [0-9]+)?\z/
+    CSHARP_UNITY_FRAME_PATTERN   = /\A(?:\(wrapper [a-z-]+\) )?([^ ():]+(?::[^ ():]+)?) ?\(([^()]*)\)( \(at .+:[0-9]+\))?\z/
+
+    # A tail-less "Type:Method (args)" frame under one of these is a strong marker.
+    CSHARP_UNITY_ENGINE_COLON_PREFIXES = %w[UnityEngine. UnityEditor.].freeze
+
+    # What the JVM prints between the parentheses of a frame that has no line number, and the endings
+    # of its bare source file name ("(Foo.java)").
+    CSHARP_JVM_LOCATIONS       = [ "SourceFile", "Native Method", "Unknown Source" ].freeze
+    CSHARP_JVM_SOURCE_SUFFIXES = %w[.java .kt .kts .scala .groovy].freeze
+
+    # Engine, runtime and library namespaces, plus the SDK's own ("Fractal." and its facade class
+    # "FractalSDK."). The trailing "." keeps a game namespace such as "UnityChan." in-app.
+    CSHARP_NOT_IN_APP_PREFIXES = %w[
+      UnityEngine. UnityEditor. Unity. System. Mono. TMPro. Microsoft. Cysharp. Fractal. FractalSDK.
+    ].freeze
+
     module_function
 
     # generate_fingerprint is the SHA256 fingerprint used to group errors,
@@ -126,9 +170,12 @@ module Fractal
     def normalize_top_frame(stack_trace)
       return "" if stack_trace.nil? || stack_trace.empty?
 
-      # ruby_frame precedes js_frame: js_stack_trace? fires on any " at ", which a Ruby 3.3+ eval frame
-      # ("(eval at app/x.rb:3):1:in 'm'") contains. Keep in sync with frameExtractors in Go.
-      %i[godot_frame ruby_frame js_frame go_frame lua_frame].each do |extractor|
+      # stackwalk_frame sits first: a native crash report lists loaded modules and their paths, which
+      # no other detector should get a chance to misread. ruby_frame and csharp_frame precede
+      # js_frame: js_stack_trace? fires on any " at ", which a Ruby 3.3+ eval frame
+      # ("(eval at app/x.rb:3):1:in 'm'") contains and every Mono and .NET frame starts with.
+      # Keep in sync with frameExtractors in Go.
+      %i[stackwalk_frame godot_frame ruby_frame csharp_frame js_frame go_frame lua_frame].each do |extractor|
         frame, matched = send(extractor, stack_trace)
         return frame if matched
       end
@@ -153,6 +200,27 @@ module Fractal
       ""
     end
 
+    # Frame 0 of the crashed thread in a minidump-stackwalk report, without its frame index, source
+    # line or a symbolicated function's "+ 0x" offset. An unsymbolicated "module + 0x..." keeps its
+    # offset: it is all that identifies the frame.
+    def stackwalk_frame(stack_trace)
+      in_crashed = false
+      stack_trace.split("\n").each do |line|
+        trimmed = line.strip
+        unless in_crashed
+          in_crashed = STACKWALK_CRASHED_THREAD_PATTERN.match?(trimmed)
+          next
+        end
+        next unless STACKWALK_FRAME_INDEX_PATTERN.match?(trimmed)
+
+        frame = trimmed.sub(STACKWALK_FRAME_INDEX_PATTERN, "")
+        frame = frame.sub(STACKWALK_SOURCE_LINE_PATTERN, "]")
+        frame = frame.sub(STACKWALK_FUNC_OFFSET_PATTERN, '\\1')
+        return [ frame, true ]
+      end
+      [ "", false ]
+    end
+
     def godot_stack_trace?(stack_trace)
       stack_trace.include?("GDScript backtrace") || stack_trace.include?("res://")
     end
@@ -280,6 +348,64 @@ module Fractal
       [ first, true ]
     end
 
+    # Unity log, Mono and .NET (CoreCLR) traces. Claims a trace only when one line is a strong C#
+    # frame; then the first frame, strong or weak, outside CSHARP_NOT_IN_APP_PREFIXES, else the first
+    # frame, as "Type.Method(args)". A claimed trace with no in-app frame still matches, so it never
+    # reaches js_frame, which would keep the IL offset, the path and the line number. One pass over
+    # the lines, so the cost is linear in the size of the trace.
+    def csharp_frame(stack_trace)
+      first = nil
+      first_in_app = nil
+      claimed = false
+      stack_trace.split("\n").each do |line|
+        frame, strong = csharp_parse_frame(line.strip)
+        next if frame.nil?
+
+        claimed ||= strong
+        first ||= frame
+        first_in_app ||= frame if CSHARP_NOT_IN_APP_PREFIXES.none? { |prefix| frame.start_with?(prefix) }
+        return [ first_in_app, true ] if claimed && first_in_app
+      end
+      claimed ? [ first, true ] : [ "", false ]
+    end
+
+    # One trimmed line as [normalized C# frame, strong], or nil when it is not a frame (a message
+    # line, "Rethrow as X: msg", "--- End of stack trace ... ---", a frame of another language).
+    # strong says whether the line alone proves a C# trace.
+    def csharp_parse_frame(line)
+      if (m = CSHARP_MONO_FRAME_PATTERN.match(line))
+        [ csharp_normalize_frame(m[1], m[2]), true ]
+      elsif (m = CSHARP_CORECLR_FRAME_PATTERN.match(line))
+        # With no tail the parentheses can hold a JVM location in place of an argument list. Such a
+        # line is a Java frame even inside a trace that Mono frames claim (Unity on Android).
+        return nil if m[3].nil? && csharp_jvm_location?(m[2])
+
+        [ csharp_normalize_frame(m[1], m[2]), !m[3].nil? ]
+      elsif (m = CSHARP_UNITY_FRAME_PATTERN.match(line))
+        # Without the "(at path:N)" tail only the "Type:Method" colon marks a Unity frame.
+        return nil if m[3].nil? && !m[1].include?(":")
+
+        strong = !m[3].nil? || CSHARP_UNITY_ENGINE_COLON_PREFIXES.any? { |prefix| m[1].start_with?(prefix) }
+        [ csharp_normalize_frame(m[1], m[2]), strong ]
+      end
+    end
+
+    # "SourceFile" (R8 / ProGuard), "Native Method", "Unknown Source", or a bare source file name.
+    def csharp_jvm_location?(args)
+      return true if CSHARP_JVM_LOCATIONS.include?(args)
+      return false if args.include?(" ") || args.include?(",")
+
+      CSHARP_JVM_SOURCE_SUFFIXES.any? { |suffix| args.end_with?(suffix) }
+    end
+
+    # "Type.Method(args)": Unity's "Type:Method" becomes "Type.Method", no space before "(", one
+    # space after each comma, single spaces inside an argument. The argument list stays: it tells
+    # overloads apart. split(",", -1) keeps a trailing empty argument, as Go's strings.Split does.
+    def csharp_normalize_frame(name, args)
+      parts = args.split(",", -1).map { |part| part.split(/ +/).reject(&:empty?).join(" ") }
+      "#{name.gsub(":", ".")}(#{parts.join(", ")})"
+    end
+
     def strip_line_col(line)
       line.sub(LINE_COL_PATTERN) { $1 }
     end

data/lib/fractal/identity.rb

@@ -17,6 +17,13 @@ module Fractal
       resolve(controller) || bucket(scope: scope, controller: controller)
     end
 
+    # A server has no install, so a known user is sent as the account id as well as the player id,
+    # and a backend and a game client that use the same id count as one player (ADR 0004 §7). The
+    # two buckets are not accounts: nobody is signed in.
+    def account?(player_id)
+      !player_id.empty? && player_id != @config.anonymous_player_id && player_id != @config.system_player_id
+    end
+
     # Who the work belongs to when no user is known: anonymous inside a request, system outside.
     def bucket(scope:, controller: nil)
       controller || scope.request? ? @config.anonymous_player_id : @config.system_player_id

data/lib/fractal/version.rb

@@ -2,5 +2,5 @@
 
 module Fractal
   # Kept in step with sdks/ruby/VERSION by ci/check_version_sync.sh.
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: fractal-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Fractal
 bindir: bin
 cert_chain: []
-date: 2026-10-12 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Reports a Rails app's exceptions to Fractal's /v1/errors and sends server-side
   analytics events to /v1/batch, from a background thread that never slows a request.
@@ -57,7 +57,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Error tracking and analytics for Ruby on Rails backends, reporting to Fractal.
 test_files: []