devbench 0.7.0 → 0.8.0

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.0'
+
+  # 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.0/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.0
 platform: ruby
 authors:
 - Dev Bench
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-10 00:00:00.000000000 Z
+date: 2026-10-13 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