devbench 0.7.0 → 0.8.1

data/lib/devbench/session.rb

@@ -12,9 +12,11 @@ module Devbench
   # trace propagation mints one and injects it into HTML responses.
   #
   # This must agree byte for byte with the Go SDK, because a token minted by a
-  # Rails app is verified by ingest. Divergence produces a request that succeeds
-  # locally and is rejected in production, with nothing to say why —
-  # testdata/session_vectors.json is what holds the two together.
+  # Rails app is verified by ingest, which uses the Go SDK's VerifySession.
+  # Divergence produces a request that succeeds locally and is rejected in
+  # production, with nothing to say why. Both SDKs are held to the shared
+  # vectors in testdata/session_vectors.json (#181, #563): test/session_test.rb
+  # here, sdk/server/go/session_kat_test.go there.
   module Session
     HEADER = 'x-adt-session'
     META_NAME = 'adt-session'
@@ -25,6 +27,7 @@ module Devbench
     # rarely — a short TTL would expire mid-session and force a refresh endpoint,
     # which is more surface in the customer's app for no security gain.
     DEFAULT_TTL = 3600
+    # Bytes, not characters, as in the Go SDK.
     MAX_SUBJECT = 128
 
     class Expired < StandardError; end
@@ -38,7 +41,7 @@ module Devbench
       raise ArgumentError, 'secret is required' if secret.nil? || secret.strip.empty?
       raise ArgumentError, 'tenant is required' if tenant.nil? || tenant.strip.empty?
 
-      subject = subject.to_s[0, MAX_SUBJECT]
+      subject = truncate_subject(subject.to_s)
       ttl = DEFAULT_TTL if ttl.nil? || ttl <= 0
 
       # The payload is pipe-delimited, so a pipe in a field would let a crafted
@@ -47,7 +50,9 @@ module Devbench
         raise ArgumentError, "tenant and subject must not contain '|'"
       end
 
-      payload = "#{tenant}|#{Time.now.to_i + ttl}|#{subject}"
+      # Bytes throughout: the signature covers the base64 of these exact bytes,
+      # whatever encoding the caller's strings carry.
+      payload = [tenant.b, (Time.now.to_i + ttl).to_s, subject.b].join('|')
       encoded = b64(payload)
 
       "#{PREFIX}.#{encoded}.#{sign(secret, encoded)}"
@@ -58,7 +63,9 @@ module Devbench
       raise Invalid if secret.nil? || secret.strip.empty?
       raise Invalid unless token.is_a?(String)
 
-      parts = token.strip.split('.')
+      # -1 keeps trailing empty fields, as Go's strings.Split does: without
+      # it "adts1.<payload>.<sig>." is three parts here and four in ingest.
+      parts = token.strip.split('.', -1)
       raise Invalid unless parts.length == 3 && parts[0] == PREFIX
 
       # Constant time: a signature check that leaks timing can be brute-forced
@@ -81,6 +88,22 @@ module Devbench
       Token.new(fields[0], fields[2], Time.at(expires))
     end
 
+    # At most MAX_SUBJECT bytes without splitting a UTF-8 character: backs off
+    # over at most three continuation bytes, exactly as the Go SDK's
+    # truncateSubject does, so a long subject mints the same token in both.
+    def self.truncate_subject(subject)
+      bytes = subject.b
+      return subject if bytes.bytesize <= MAX_SUBJECT
+
+      cut = MAX_SUBJECT
+      3.times do
+        break if cut.zero? || (bytes.getbyte(cut) & 0xC0) != 0x80
+
+        cut -= 1
+      end
+      bytes.byteslice(0, cut).force_encoding(subject.encoding)
+    end
+
     def self.sign(secret, encoded_payload)
       b64(OpenSSL::HMAC.digest('SHA256', secret, encoded_payload))
     end
@@ -90,10 +113,16 @@ module Devbench
       Base64.urlsafe_encode64(bytes, padding: false)
     end
 
+    # Decodes as Go's base64.RawURLEncoding does, and refuses what it refuses:
+    # padding (=), the standard alphabet's + and /, whitespace, and a length
+    # that leaves one character over. (Base64.urlsafe_decode64 accepts the
+    # first two, so a padded payload verified here but not in ingest, #563.)
+    # Like Go, non-zero bits left over in the last character are ignored.
     def self.unb64(text)
-      Base64.urlsafe_decode64(text)
-    rescue ArgumentError
-      nil
+      return nil unless text.match?(/\A[A-Za-z0-9_-]*\z/) && text.length % 4 != 1
+
+      std = text.tr('-_', '+/')
+      (std + ('=' * ((4 - (std.length % 4)) % 4))).unpack1('m')
     end
   end
 end

data/lib/devbench/sidecar_transport.rb

@@ -5,7 +5,7 @@ require 'socket'
 
 module Devbench
   # Sidecar mode: each report is one line of JSON on the local sidecar's
-  # unix socket (docs/SERVER_SDK_SPEC.md, "Control socket — v1"). Used when no
+  # unix socket (docs/server-sdk/control-socket.md, "Control socket — v1"). Used when no
   # DSN is set; unchanged from 0.4.
   #
   # Never blocks for long: this runs inside rescue blocks and exception

data/lib/devbench/sidekiq_hooks.rb

@@ -5,7 +5,7 @@ require_relative 'current'
 require_relative 'reporter'
 
 module Devbench
-  # Native Sidekiq jobs (docs/SERVER_SDK_SPEC.md, Capability 2, `job`).
+  # Native Sidekiq jobs (docs/server-sdk/unhandled-failures.md, Capability 2, `job`).
   #
   # A class that includes Sidekiq::Job never touches ActiveJob, so the
   # perform.active_job hook sees none of its failures. This is the

data/lib/devbench/trace.rb

@@ -3,7 +3,7 @@
 module Devbench
   # The correlation id that ties a user action together across every service.
   #
-  # Wire form (docs/SERVER_SDK_SPEC.md): v1/<session>/<intent>/<hop>
+  # Wire form (docs/server-sdk/trace-propagation.md): v1/<session>/<intent>/<hop>
   #
   # This must agree exactly with the Go SDK and the sidecar's extraction regex.
   # A trace the browser writes and Rails mangles is worse than no trace: the

data/lib/devbench/transport.rb

@@ -4,8 +4,9 @@ require_relative 'config'
 require_relative 'sidecar_transport'
 require_relative 'direct'
 require_relative 'logs'
+require_relative 'request_signals'
 
-# Configuration and transport selection (docs/SERVER_SDK_SPEC.md,
+# Configuration and transport selection (docs/server-sdk/transports.md,
 # "Transports: direct (default) or sidecar (optional)").
 #
 # Exactly one transport per process, decided at the first report:
@@ -124,15 +125,18 @@ module Devbench
     # seconds. A no-op in sidecar mode. Returns true when nothing is left
     # unsent. Never raises.
     def flush!(timeout: 5)
+      # Closes a 429 spike window the clock has left, in either transport
+      # (sidecar mode has no flush thread of its own to do it).
+      RequestSignals.tick!
       transport.flush!(timeout: timeout) ? true : false
     rescue StandardError, SystemStackError
       false
     end
 
-    # Sends one synthetic exception straight to Dev Bench and prints the
-    # result, so an operator can check the DSN without waiting for a flush
-    # (`rake devbench:test` under Rails). Returns true when ingest accepted
-    # it. Never raises.
+    # Asks ingest whether the DSN's key is valid (`POST /v1/check`) and prints
+    # the answer, so an operator can check the DSN without waiting for a
+    # flush (`rake devbench:test` under Rails). Creates nothing: no event,
+    # no issue. Returns true when ingest accepted the key. Never raises.
     def test!(io: $stdout)
       cfg = config
       unless cfg.enabled?
@@ -190,6 +194,10 @@ module Devbench
     private
 
     def reset_transport!
+      # A replaced configuration ends the 429 spike window, as process exit
+      # does: evaluated as it stands and reported under the transport that
+      # saw its requests, before that transport's last flush.
+      RequestSignals.finish!(@transport)
       old = TRANSPORT_LOCK.synchronize do
         previous = @transport
         @transport = nil

data/lib/devbench/version.rb

@@ -1,10 +1,22 @@
 # frozen_string_literal: true
 
 module Devbench
-  # Tracks the protocol, not the gem's own churn.
-  #
-  # The wire format this speaks — the trace header, the handled header, the
-  # control-socket message shapes — is what a customer's deployment depends
-  # on. See docs/SERVER_SDK_SPEC.md.
-  VERSION = '0.7.0'
+  # The gem's release version. Each SDK has its own version and release tag;
+  # the Ruby release (tag ruby-vX.Y.Z in the public repo) checks this equals
+  # the tag. The wire format is PROTOCOL_VERSION below.
+  VERSION = '0.8.1'
+
+  # This SDK's name in every flush's `sdk` field: the key
+  # testdata/protocol_vectors.json `sdk.names` gives sdk/server/ruby
+  # (docs/server-sdk/wire-protocol.md, "the SDK's name and version"). The
+  # field's version is VERSION, never a second literal.
+  SDK_NAME = 'ruby'
+
+  # The wire format this speaks: the `v` every payload carries (the flush
+  # body, the evidence bundle, every control-socket message). Not the gem's
+  # release VERSION above: it changes only for a breaking wire change, and
+  # ingest tells formats apart by it. It must equal `current` in
+  # testdata/protocol_vectors.json (docs/server-sdk/protocol-version.md, "Protocol
+  # version"); send it, never a literal.
+  PROTOCOL_VERSION = 1
 end

data/lib/devbench/view_helper.rb

@@ -2,6 +2,8 @@
 
 require 'erb'
 require_relative 'version'
+require_relative 'current'
+require_relative 'widget_identity'
 
 module Devbench
   # The browser sensor's script tag, for the layout's <head>:
@@ -10,7 +12,7 @@ module Devbench
   #
   # renders
   #
-  #   <script src="https://unpkg.com/devbench@0.7.0/dist/devbench.min.js"
+  #   <script src="https://unpkg.com/devbench@0.8.1/dist/devbench.min.js"
   #           data-dsn="https://<public>@<host>" data-release="<release>" defer></script>
   #
   # The DSN is the public part of DEVBENCH_DSN only (Devbench.browser_dsn),
@@ -21,6 +23,14 @@ module Devbench
   # CSP nonce (content_security_policy_nonce_generator), the tag carries it,
   # as Rails' own `javascript_include_tag nonce: true` does.
   #
+  # Chat widget (docs/server-sdk/chat-widget.md, Capability 6): when
+  # DEVBENCH_WIDGET_SECRET is set and Devbench.set_user was called for this
+  # request, the tag also carries data-widget-identity="<token>", the user
+  # (and their role and chat permission) signed at render time. No secret, no
+  # user (a signed-out page) or an identity the signer refuses: no
+  # attribute, so no widget. A page carrying one is per-user; don't serve it
+  # from a shared cache.
+  #
   # Included into ActionView by the Railtie. Never raises.
   module ViewHelper
     CDN = 'https://unpkg.com'
@@ -34,6 +44,8 @@ module Devbench
       return devbench_safe('') if dsn.nil?
 
       attrs = [['src', ViewHelper.src], ['data-dsn', dsn], ['data-release', Devbench.config.resolved_release]]
+      identity = devbench_widget_identity
+      attrs << ['data-widget-identity', identity] if identity
       nonce = devbench_nonce
       attrs << ['nonce', nonce] if nonce
       html = attrs.map { |name, value| %(#{name}="#{ERB::Util.html_escape(value)}") }.join(' ')
@@ -44,6 +56,17 @@ module Devbench
 
     private
 
+    # The signed widget identity for this request's user, or nil.
+    def devbench_widget_identity
+      secret = Devbench.config.widget_secret
+      user = Current.widget_user
+      return nil if secret.nil? || secret.to_s.empty? || user.nil?
+
+      WidgetIdentity.sign(secret, email: user[:email], account: user[:account], role: user[:role], chat: user[:chat])
+    rescue StandardError, SystemStackError
+      nil
+    end
+
     # Rails' content_security_policy_nonce: nil unless the app configured a
     # nonce generator.
     def devbench_nonce

data/lib/devbench/widget_identity.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'openssl'
+
+module Devbench
+  # The chat widget's signed identity (docs/server-sdk/chat-widget.md, "Capability 6
+  # — Chat widget").
+  #
+  #   dbw1.<base64url(issued_at \n email \n account \n role \n chat)>.<base64url(HMAC-SHA256)>
+  #
+  # The app's server signs the signed-in user with the tenant's widget secret
+  # (DEVBENCH_WIDGET_SECRET); the browser holds only the token, and the chat
+  # service shows the widget only to a user whose token verifies. Every signer
+  # must reproduce testdata/widget_identity_vectors.json byte for byte, or the
+  # widget works in a unit test and never renders in production.
+  #
+  # Rails apps never call this: devbench_script_tag signs whatever
+  # Devbench.set_user recorded for the request.
+  module WidgetIdentity
+    PREFIX = 'dbw1'
+    # The closed list, in the token's canonical (byte) order. A new one is a
+    # contract change, made in lockstep with the vectors.
+    CAPABILITIES = %w[feature_requests handoff howto report status].freeze
+    MAX = 255
+    # ASCII whitespace only, as the contract names it. String#strip would
+    # also remove a trailing NUL, which must survive the trim to be refused
+    # (Go's signer refuses it): the two would disagree.
+    TRIM = /\A[ \t\n\r\f\v]+|[ \t\n\r\f\v]+\z/
+    # C0 controls and DEL, refused when left in a field after trimming (the
+    # trimmed whitespace is C0 too, and fine at the ends). Identities are
+    # compared and displayed; invisible bytes could make two look alike.
+    CONTROL = /[\x00-\x1f\x7f]/
+    NO_CHAT = 'none'
+
+    # Raised internally for an identity that cannot be signed; never escapes.
+    class Refused < StandardError; end
+
+    # Returns the token, or nil when this identity must not be signed: no
+    # secret, neither email nor account, a control character (U+0000-U+001F,
+    # U+007F) left in a field after trimming, a field over 255 characters,
+    # invalid text, or a chat capability not in CAPABILITIES (exact,
+    # lowercase). Refuses rather than repairs: truncating would sign a
+    # different person. The first refusal in the process is logged, once.
+    #
+    # chat: nil states nothing (the tenant's settings decide); [] means the
+    # user may not chat; otherwise their capabilities, symbols or strings,
+    # in any order, duplicates allowed. Never raises.
+    def self.sign(secret, email: nil, account: nil, role: nil, chat: nil, issued_at: Time.now.to_i)
+      token(secret.to_s, email, account, role, chat, issued_at)
+    rescue Refused => e
+      Devbench.warn_once(:widget_identity, "chat widget identity not signed: #{e.message}; " \
+                                           'no chat widget for that user (further refusals are not logged)')
+      nil
+    rescue StandardError, SystemStackError
+      Devbench.warn_once(:widget_identity, 'chat widget identity not signed: unexpected error; ' \
+                                           'no chat widget for that user (further refusals are not logged)')
+      nil
+    end
+
+    def self.token(secret, email, account, role, chat, issued_at)
+      raise Refused, 'no widget secret (DEVBENCH_WIDGET_SECRET)' if secret.empty?
+
+      email = field(email, 'email')
+      account = field(account, 'account')
+      role = field(role, 'role')
+      # Simple lowercase mapping, as Go's strings.ToLower: Ruby's full
+      # mapping turns U+0130 into two characters where Go makes one. It is
+      # the only code point the two disagree on.
+      email = email.tr("\u0130", 'i').downcase
+      raise Refused, 'neither email nor account' if email.empty? && account.empty?
+
+      ts = Integer(issued_at)
+      raise Refused, 'issued before 1970' if ts.negative?
+
+      raw = [ts.to_s, email, account, role, chat_field(chat)].join("\n")
+      payload = b64(raw.b)
+      "#{PREFIX}.#{payload}.#{b64(OpenSSL::HMAC.digest('SHA256', secret.b, "#{PREFIX}.#{payload}"))}"
+    end
+    private_class_method :token
+
+    # Trimmed, valid UTF-8, no control character, at most MAX characters; else
+    # Refused. nil is "".
+    def self.field(value, name)
+      text = utf8(value, name).gsub(TRIM, '')
+      raise Refused, "control character in #{name}" if text.match?(CONTROL)
+      raise Refused, "#{name} over #{MAX} characters" if text.length > MAX
+
+      text
+    end
+    private_class_method :field
+
+    def self.utf8(value, name)
+      text = value.nil? ? +'' : value.to_s.dup
+      text = text.encoding == Encoding::BINARY ? text.force_encoding(Encoding::UTF_8) : text.encode(Encoding::UTF_8)
+      raise Refused, "#{name} is not valid UTF-8" unless text.valid_encoding?
+
+      text
+    rescue EncodingError
+      raise Refused, "#{name} is not valid UTF-8"
+    end
+    private_class_method :utf8
+
+    # "" not stated, "none" may not chat, else known names de-duplicated,
+    # sorted by bytes, joined by ",".
+    def self.chat_field(chat)
+      return '' if chat.nil?
+      raise Refused, 'chat must be a list of capabilities' unless chat.is_a?(Array)
+
+      names = chat.map do |c|
+        name = c.is_a?(Symbol) || c.is_a?(String) ? c.to_s : nil
+        raise Refused, "unknown chat capability #{c.inspect}" unless CAPABILITIES.include?(name)
+
+        name
+      end
+      names.empty? ? NO_CHAT : names.uniq.sort.join(',')
+    end
+    private_class_method :chat_field
+
+    def self.b64(bytes)
+      Base64.urlsafe_encode64(bytes, padding: false)
+    end
+    private_class_method :b64
+  end
+end

data/lib/devbench.rb

@@ -13,6 +13,8 @@
 #   * reports unhandled exceptions             (Devbench::Middleware, Devbench::Railtie,
 #                                               Devbench::SidekiqHooks,
 #                                               Devbench.capture_exception)
+#   * reports failed (5xx) and slow requests  (Devbench::Middleware,
+#     and 429 spikes                          Devbench::RequestSignals)
 #   * keeps recent log lines per trace         (Devbench::Logs; direct mode)
 #   * renders the browser sensor's tag         (devbench_script_tag)
 #
@@ -23,6 +25,7 @@ require_relative 'devbench/trace'
 require_relative 'devbench/current'
 require_relative 'devbench/backtrace'
 require_relative 'devbench/identity'
+require_relative 'devbench/request_signals'
 require_relative 'devbench/middleware'
 require_relative 'devbench/http'
 require_relative 'devbench/reporter'
@@ -30,7 +33,9 @@ require_relative 'devbench/session'
 require_relative 'devbench/session_middleware'
 require_relative 'devbench/rails_hooks'
 require_relative 'devbench/sidekiq_hooks'
+require_relative 'devbench/active_job_hooks'
 require_relative 'devbench/logs'
+require_relative 'devbench/widget_identity'
 require_relative 'devbench/view_helper'
 
 # The pre-0.5 name. The same module object, not a copy: ADT::Middleware *is*

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: devbench
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Dev Bench
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-10 00:00:00.000000000 Z
+date: 2026-10-15 00:00:00.000000000 Z
 dependencies: []
 description: |
   Reports unhandled exceptions, Rails.error reports, failed ActiveJob and
@@ -27,9 +27,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
 - README.md
 - lib/adt.rb
 - lib/devbench.rb
+- lib/devbench/active_job_hooks.rb
 - lib/devbench/backtrace.rb
 - lib/devbench/config.rb
 - lib/devbench/current.rb
@@ -43,6 +45,7 @@ files:
 - lib/devbench/rails_hooks.rb
 - lib/devbench/railtie.rb
 - lib/devbench/reporter.rb
+- lib/devbench/request_signals.rb
 - lib/devbench/scrub.rb
 - lib/devbench/session.rb
 - lib/devbench/session_middleware.rb
@@ -52,10 +55,11 @@ files:
 - lib/devbench/transport.rb
 - lib/devbench/version.rb
 - lib/devbench/view_helper.rb
+- lib/devbench/widget_identity.rb
 - lib/generators/devbench/devbench_generator.rb
 homepage: https://github.com/pasperry/devbench-sdk
 licenses:
-- LicenseRef-Proprietary
+- MIT
 metadata:
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/pasperry/devbench-sdk