devbench 0.6.0 → 0.8.0

data/lib/devbench/request_signals.rb

@@ -0,0 +1,359 @@
+# frozen_string_literal: true
+
+require_relative 'fingerprint'
+
+module Devbench
+  # Request signals (docs/server-sdk/failed-and-slow-requests.md, "Capability
+  # 2b — Failed and slow requests"; DECISIONS #171): what a request does
+  # without raising.
+  #
+  #   * failed: the application answered 500–599 and no exception was
+  #     reported during the request;
+  #   * slow: it answered 100–499, not streaming, after more than 3,000 ms;
+  #   * rate_limit_spike: one route's 429s in one unix minute met the spike
+  #     rule (at least ten, and at least 10% of that route's requests).
+  #
+  # A port of the backend's internal/reqsignal (and the Go SDK's copy,
+  # sdk/server/go/reqsignal.go). A port can drift, and a drifted port reports
+  # a different set of problems by language, so it is held to the shared
+  # vectors (testdata/request_signal_vectors.json) every implementation must
+  # reproduce. Change nothing here without changing those in lockstep.
+  #
+  # Devbench::Middleware observes; this module classifies, builds and keeps
+  # the per-process spike detector. Nothing here raises into the
+  # application.
+  module RequestSignals
+    # The thresholds: constants, not configuration. Tenant-configurable
+    # thresholds are a later issue (DECISIONS #171), and every SDK must apply
+    # the same numbers or the same app reports differently by language.
+    SLOW_THRESHOLD_MS = 3000
+    SPIKE_WINDOW_SECONDS = 60
+    SPIKE_MIN_COUNT = 10
+    SPIKE_MIN_PERCENT = 10
+    MAX_ROUTES_PER_WINDOW = 512
+    MAX_ROUTE_CHARS = 255
+
+    # A request matched to no route pattern: one literal, never the raw path
+    # (a path carries ids and slugs).
+    UNKNOWN_ROUTE = '*'
+    # Any method outside the standard set, so a client sending invented
+    # methods cannot mint fingerprints.
+    OTHER_METHOD = 'OTHER'
+    METHODS = %w[GET HEAD POST PUT PATCH DELETE OPTIONS TRACE CONNECT].freeze
+
+    # The `signal` field of the `request` control message.
+    FAILED = 'failed'
+    SLOW = 'slow'
+    RATE_LIMIT_SPIKE = 'rate_limit_spike'
+
+    # Everything the direct transport needs to count a request signal: the
+    # count's kind, the fingerprint's type and message, the template text
+    # kept for evidence, and the raw exemplar (scrubbed at egress).
+    Built = Struct.new(:kind, :type, :message, :text, :exemplar)
+
+    # One (method, route) whose window met the spike rule. `window` is the
+    # window's start, unix seconds.
+    Spike = Struct.new(:method, :route, :window, :count, :total)
+
+    # The clock the middleware reads: monotonic milliseconds for a request's
+    # duration, wall milliseconds for the spike window. Replaceable only so
+    # tests can pin a duration to the millisecond.
+    module SystemClock
+      def self.monotonic_ms
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+      end
+
+      def self.wall_ms
+        Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+      end
+    end
+
+    # The 429 spike rule for one process's requests. Thread-safe: every
+    # request's thread observes, the flush thread ticks.
+    #
+    # One window is open at a time. An observation in a later window closes
+    # the open one first; one in an earlier window (a clock step back) counts
+    # in the open window. Memory is bounded by MAX_ROUTES_PER_WINDOW, and
+    # nothing is kept past the open window. A forked child starts empty: the
+    # parent reports what it saw.
+    class SpikeDetector
+      Tally = Struct.new(:count, :total)
+
+      def initialize
+        @lock = Mutex.new
+        reset
+      end
+
+      # Records one finished request at t_ms (unix milliseconds) and returns
+      # the spikes of any window it closed.
+      def observe(t_ms, method, route, status)
+        w = RequestSignals.window_of(t_ms)
+        key = [RequestSignals.normalize_method(method), RequestSignals.normalize_route(route)].freeze
+
+        @lock.synchronize do
+          check_fork
+          closed = []
+          if @window.nil?
+            start(w)
+          elsif w > @window
+            closed = evaluate
+            start(w)
+          end
+
+          tally = @routes[key]
+          if tally.nil?
+            return closed if @routes.size >= MAX_ROUTES_PER_WINDOW
+
+            tally = @routes[key] = Tally.new(0, 0)
+          end
+          tally.total += 1
+          tally.count += 1 if status == 429
+          closed
+        end
+      end
+
+      # Closes the open window if now_ms is past it (at each flush) and
+      # returns its spikes.
+      def tick(now_ms)
+        @lock.synchronize do
+          check_fork
+          return [] if @window.nil? || RequestSignals.window_of(now_ms) <= @window
+
+          out = evaluate
+          reset
+          out
+        end
+      end
+
+      # Evaluates the open window as it stands (process exit, a new
+      # configuration) and closes it.
+      def finish
+        @lock.synchronize do
+          check_fork
+          return [] if @window.nil?
+
+          out = evaluate
+          reset
+          out
+        end
+      end
+
+      private
+
+      def reset
+        @pid = Process.pid
+        @window = nil
+        @routes = {}
+      end
+
+      def check_fork
+        reset unless @pid == Process.pid
+      end
+
+      def start(window)
+        @window = window
+        @routes = {}
+      end
+
+      # The open window's spikes, sorted by method then route (byte order,
+      # as Go's string comparison). Caller holds @lock.
+      def evaluate
+        @routes.filter_map do |(method, route), tally|
+          next unless RequestSignals.spike?(tally.count, tally.total)
+
+          Spike.new(method, route, @window * SPIKE_WINDOW_SECONDS, tally.count, tally.total)
+        end.sort_by { |s| [s.method.b, s.route.b] }
+      end
+    end
+
+    class << self
+      attr_writer :clock
+
+      def clock
+        @clock || SystemClock
+      end
+
+      # The process's spike detector, in both transports.
+      def detector
+        @detector ||= SpikeDetector.new
+      end
+
+      # The signal one finished request produces: FAILED, SLOW or nil. At
+      # most one per request. 429s are not classified here; they feed the
+      # spike detector.
+      def classify(status:, duration_ms:, exception_reported:, streaming:)
+        return nil if status < 100 || status > 599
+        # A 5xx after a reported exception: the exception is the report.
+        return (exception_reported ? nil : FAILED) if status >= 500
+        return nil if streaming || status == 101
+
+        duration_ms > SLOW_THRESHOLD_MS ? SLOW : nil
+      end
+
+      # Uppercased and trimmed; anything outside the standard set is OTHER.
+      def normalize_method(method)
+        m = Fingerprint.trim(utf8(method)).upcase
+        METHODS.include?(m) ? m : OTHER_METHOD
+      end
+
+      # Trimmed and bounded to MAX_ROUTE_CHARS code points; empty is
+      # UNKNOWN_ROUTE.
+      def normalize_route(route)
+        r = Fingerprint.trim(utf8(route))
+        return UNKNOWN_ROUTE if r.empty?
+
+        r.length > MAX_ROUTE_CHARS ? r[0, MAX_ROUTE_CHARS] : r
+      end
+
+      # Fingerprint inputs, template text and exemplar for a request signal,
+      # as the sidecar builds them from the `request` control message. Nil
+      # for a signal/status pair a sensor must refuse.
+      def build(signal:, method:, route:, status:, duration_ms: 0, count: 0, total: 0)
+        status = status.to_i
+        message = "#{normalize_method(method)} #{normalize_route(route)}"
+        case signal
+        when FAILED
+          return nil unless status.between?(500, 599)
+
+          type = "http_#{status}"
+          new_built('error', type, message, "#{type}: #{message} in #{non_negative(duration_ms)} ms")
+        when SLOW
+          return nil unless status.between?(100, 499)
+
+          type = 'slow_request'
+          new_built('degradation', type, message,
+                    "#{type}: #{message} in #{non_negative(duration_ms)} ms (status #{status})")
+        when RATE_LIMIT_SPIKE
+          type = 'http_429_spike'
+          new_built('error', type, message,
+                    "#{type}: #{message} #{non_negative(count)} of #{non_negative(total)} " \
+                    'requests answered 429 in one minute')
+        end
+      end
+
+      # The rule, in integer arithmetic: at least SPIKE_MIN_COUNT 429s, and
+      # at least SPIKE_MIN_PERCENT of the route's requests in the window.
+      def spike?(count, total)
+        count >= SPIKE_MIN_COUNT && count * 100 >= total * SPIKE_MIN_PERCENT
+      end
+
+      # Floors toward negative infinity (Ruby's integer division does), so a
+      # pre-1970 clock still maps to one window per minute.
+      def window_of(t_ms)
+        t_ms.to_i / (SPIKE_WINDOW_SECONDS * 1000)
+      end
+
+      # ---- Reporting (called by Devbench::Middleware and the flushes)
+
+      # Classifies a finished request, reports its signal, and feeds the spike
+      # detector. Called inside the request's scope, so a signal carries its
+      # trace and user. Never raises.
+      def observe(status:, method:, route:, duration_ms:, streaming:, exception_reported:, finished_ms:)
+        return nil unless status.is_a?(Integer)
+
+        method = normalize_method(method)
+        route = normalize_route(route)
+        signal = classify(status: status, duration_ms: duration_ms,
+                          exception_reported: exception_reported, streaming: streaming)
+        emit(request_payload(signal, method, route, status, duration_ms)) unless signal.nil?
+        return nil unless status.between?(100, 599)
+
+        install_exit_hook
+        report_spikes(detector.observe(finished_ms, method, route, status))
+        start_flusher if status == 429
+        nil
+      rescue StandardError, SystemStackError
+        nil
+      end
+
+      # Closes the spike window if the clock has left it (at a flush) and
+      # reports its spikes to `transport`.
+      def tick!(transport = nil)
+        report_spikes(detector.tick(clock.wall_ms), transport)
+      rescue StandardError, SystemStackError
+        nil
+      end
+
+      # Evaluates the open window as it stands and reports its spikes (process
+      # exit, a replaced configuration). Returns how many were reported.
+      def finish!(transport = nil)
+        report_spikes(detector.finish, transport)
+      rescue StandardError, SystemStackError
+        0
+      end
+
+      # The `request` control message for a spike: an aggregate of many
+      # requests, so no trace and no user.
+      def spike_payload(spike)
+        { v: PROTOCOL_VERSION, kind: 'request', signal: RATE_LIMIT_SPIKE, method: spike.method,
+          route: spike.route, status: 429, count: spike.count, total: spike.total }
+      end
+
+      private
+
+      def new_built(kind, type, message, exemplar)
+        Built.new(kind, type, message, "#{type} at #{message}", exemplar)
+      end
+
+      def non_negative(n)
+        n = n.to_i
+        n.negative? ? 0 : n
+      end
+
+      def utf8(text)
+        text.to_s.encode('UTF-8', invalid: :replace, undef: :replace).scrub
+      end
+
+      def request_payload(signal, method, route, status, duration_ms)
+        {
+          v: PROTOCOL_VERSION, kind: 'request', signal: signal, method: method, route: route,
+          status: status, duration_ms: non_negative(duration_ms),
+          trace: safely { Current.trace&.to_s }, user: safely { Current.user }
+        }.compact
+      end
+
+      def report_spikes(spikes, transport = nil)
+        spikes.each { |s| emit(spike_payload(s), transport) }
+        spikes.length
+      end
+
+      def emit(payload, transport = nil)
+        (transport || Devbench.transport).deliver(payload)
+      rescue StandardError, SystemStackError
+        nil
+      end
+
+      # Direct mode: a process whose only traffic is a burst of 429s has
+      # counted nothing, so its flush thread may not be running; without it
+      # the spike would wait for the next request or the process's exit.
+      def start_flusher
+        transport = Devbench.transport
+        transport.start if transport.respond_to?(:start)
+      rescue StandardError, SystemStackError
+        nil
+      end
+
+      # The open window is evaluated at process exit, in either transport:
+      # the spikes are delivered, then direct mode flushes them (bounded, as
+      # the transport's own exit flush is). Inherited by forked children,
+      # which report their own window.
+      def install_exit_hook
+        return if @exit_hook_installed
+
+        @exit_hook_installed = true
+        at_exit do
+          reported = finish!
+          Devbench.transport.flush!(timeout: DirectTransport::EXIT_TIMEOUT) if reported.positive?
+        rescue StandardError, SystemStackError
+          nil
+        end
+      end
+
+      def safely
+        yield
+      rescue StandardError, SystemStackError
+        nil
+      end
+    end
+  end
+end

data/lib/devbench/scrub.rb

@@ -25,6 +25,25 @@ module Devbench
     end
     private_class_method :go_re
 
+    # The card and phone rules (#186; internal/scrub/numbers.go, the
+    # `numbers` vectors): a candidate regex plus checks on the whole
+    # candidate, run in the gsub block. A rejected candidate is left as
+    # written and matching carries on after it; it is never retried shorter.
+    # No lookaround in the candidates (the Go SDK is RE2), so every SDK finds
+    # the same ones.
+    CARD = '<redacted:card>'
+    PHONE = '<redacted:phone>'
+    CARD_CANDIDATE = go_re('\b(?:\d[ \-]*?){13,19}\b')
+    # Group 1 is the character before the number (or the start of the text):
+    # a phone number is not glued to a letter, digit, `_` or `-`, which keeps
+    # a UUID's tail and `ord_123456789` out. Group 2 is the candidate.
+    PHONE_CANDIDATE = /(\A|[^A-Za-z0-9_\-])(\+?\d[\d\t\n\f\r ().\-]{7,}\d)/
+    ISO_DATE_PREFIX = /\A\d{4}-\d{2}-\d{2}(?:\z|\D)/
+    DECIMAL = /\A\d+\.\d+\z/
+    WORD_BYTE = /\A[A-Za-z0-9_]/
+    # E.164 caps a phone number at 15 digits; anything longer is an id.
+    PHONE_DIGITS = (7..15)
+
     # Ordered most-specific first, and the order is load-bearing: see the
     # comments on internal/scrub's rules (a credential containing an email,
     # a phone pattern eating an SSN).
@@ -41,9 +60,10 @@ module Devbench
              "(#{WS}*[:=]#{WS}*)(\"[^\"]*\"|'[^']*'|#{NOT_WS}+)", Regexp::IGNORECASE), '\1\2<redacted:secret>'],
       [go_re('\b[^\t\n\f\r <>@]+@[^\t\n\f\r <>@]+\.[A-Za-z]{2,}\b'), '<redacted:email>'],
       [go_re('\b\d{3}-\d{2}-\d{4}\b'), '<redacted:ssn>'],
-      [go_re('\b(?:\d[ \-]*?){13,19}\b'), '<redacted:card>'],
+      # The card and phone rules (#186) judge each candidate in the block.
+      [CARD_CANDIDATE, ->(m) { card?(m[0]) ? CARD : m[0] }],
       [go_re('\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b'), '<redacted:ip>'],
-      [/\+?\d[\d\t\n\f\r ().\-]{7,}\d/, '<redacted:phone>']
+      [PHONE_CANDIDATE, ->(m) { phone?(m[2], m.string[m.end(0)].to_s) ? "#{m[1]}#{PHONE}" : m[0] }]
     ].freeze
 
     # internal/sidecar/trace.go's traceRe.
@@ -75,7 +95,33 @@ module Devbench
     class << self
       # internal/scrub.Text: every shape rule, in order.
       def text(line)
-        RULES.reduce(utf8(line)) { |out, (re, with)| out.gsub(re, with) }
+        RULES.reduce(utf8(line)) do |out, (re, with)|
+          with.is_a?(Proc) ? out.gsub(re) { with.call(Regexp.last_match) } : out.gsub(re, with)
+        end
+      end
+
+      # A card: its digits pass the Luhn check, and it is not a bare 13-digit
+      # run starting with 1 (a millisecond timestamp).
+      def card?(candidate)
+        digits = candidate.delete('^0-9')
+        return false if digits == candidate && timestamp?(digits)
+
+        luhn?(digits)
+      end
+
+      # A phone, judged with the character after it ('' at the end of the
+      # text; one character is all the check reads). Not one when a letter, digit
+      # or `_` follows; it starts with an ISO date; it is a decimal; it has
+      # fewer than 7 or more than 15 digits; or it is a bare 10- or 13-digit
+      # run starting with 1 (a timestamp).
+      def phone?(candidate, after)
+        return false if WORD_BYTE.match?(after)
+        return false if ISO_DATE_PREFIX.match?(candidate) || DECIMAL.match?(candidate)
+
+        digits = candidate.delete('^0-9')
+        return false unless PHONE_DIGITS.cover?(digits.length)
+
+        !(digits == candidate && timestamp?(digits))
       end
 
       # internal/scrub.Prose: runs of two or more capitalised words that are
@@ -153,6 +199,26 @@ module Devbench
 
       private
 
+      # A Unix timestamp in seconds or milliseconds (2001 to 2033).
+      def timestamp?(digits)
+        (digits.length == 10 || digits.length == 13) && digits.start_with?('1')
+      end
+
+      def luhn?(digits)
+        return false if digits.empty?
+
+        sum = 0
+        digits.reverse.each_char.with_index do |c, i|
+          d = c.ord - 48
+          if i.odd?
+            d *= 2
+            d -= 9 if d > 9
+          end
+          sum += d
+        end
+        (sum % 10).zero?
+      end
+
       # Base redaction (template + scrub), the prose heuristic unless the
       # shape is marked 'full', then field and term rules.
       def redact_body(body, rule, policy)

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. There are no shared testdata/ vectors
+  # for session tokens yet: test/session_test.rb pins known-answer tokens the Go
+  # SDK minted, and sdk/server/go/session_kat_test.go pins the same table.
   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)}"
@@ -81,6 +86,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

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,6 +125,9 @@ 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
@@ -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.6.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.6.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