logbrew-sdk 0.1.16 → 0.1.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8075c14ec60f98ac264ce2b20a74fed5ae9227e241d1939693a57301d9f1e99c
-  data.tar.gz: 34c6c4582c281f712a551f2fe4484be80b910b71517c361eadfc7b809393ee48
+  metadata.gz: '050529417548746276ff875602c06b58d1356614727cab8713094be67d46bce9'
+  data.tar.gz: 9ce8b6b4a0873ca92907618d684a161f3a9151fcff19b19bb64efa133613263f
 SHA512:
-  metadata.gz: 4dae9919321d0fda4baf9ddc50bcc2b0f23e17f53300e8fd6bcd733409abc989b093de9a979a10912e891abd97867119cdb21c47ba7dad680e26f7ff2a753789
-  data.tar.gz: ebfabd056b82f15ad40dbe6c46603529f37800b0b32b58510f030c5f46f4e7f116ca3c7800d13835aa3dccbbd65781a6f13c6085820914f722e9a5bd2ad47da6
+  metadata.gz: e840df499c2e6415d03f7fb86c0676b8312f81d52936c0bc8490ec7ce59a21f0ac121d2fc584d1f798dccdc2a1abd48e73abcc557be8a625ffed9663baef8704
+  data.tar.gz: 98e277bf3ffd8ae3296c3179fd8f0ceaa2e501bfd8f5311ea300bc23971989225bb31f63928d8d9c1c90198feca0ba0baeb9615b6a2d31d2e6a4e83cfced48f4

data/README.md

@@ -23,7 +23,7 @@ needed:
 
 ```ruby
 # Gemfile
-gem "logbrew-sdk", "~> 0.1.16"
+gem "logbrew-sdk", "~> 0.1.18"
 ```
 
 ```bash
@@ -145,6 +145,24 @@ rm -f "$HOME/.logbrew/rails-service.ingest"
 unset LOGBREW_PROJECT_ID
 ```
 
+## Read Events Back
+
+A successful send shows that LogBrew accepted the request. It does not show
+that you can read the event. After your app sends one event, read it
+back with a project read key:
+
+```bash
+logbrew projects keys create "<project_id>" --kind read \
+  --ingest-key-file "$HOME/.logbrew/setup-check.read" --json
+export LOGBREW_TOKEN="$(< "$HOME/.logbrew/setup-check.read")"
+logbrew read logs --since 1h --json
+logbrew issues --since 1h --json
+```
+
+A read key reads 1 project and cannot send telemetry. Run `unset LOGBREW_TOKEN`
+when you finish. [Read your events back](https://docs.logbrew.co/guides/verify-setup)
+covers key kinds, empty results, and how to revoke the key.
+
 ## Usage
 
 ```ruby
@@ -542,7 +560,7 @@ source code, locals, arguments, or absolute paths. The raw Rails/Rack backtrace
 option is separate and remains off by default. Run
 `make -C examples run-issue-diagnostics` for a complete inspectable payload.
 Rails, Rack, and Sidekiq issue capture reuse this same graph. See the shared
-[exception-chain contract](../../docs/exception-chain-evidence.md).
+[exception-chain contract](../../README.md#exception-chains).
 
 ## Metrics
 
@@ -603,7 +621,7 @@ The helpers return normal `action` attributes, so they work with the existing qu
 
 ## Support Ticket Draft Diagnostics
 
-Use `LogBrew::SupportTicketDraft.create` when a developer or support agent explicitly asks for a local JSON payload for the planned LogBrew support-ticket routes. The helper validates the public source/category contract, normalizes W3C trace IDs, redacts diagnostics, and returns a plain Ruby hash:
+Use `LogBrew::SupportTicketDraft.create` to build the JSON body for a LogBrew support ticket. The helper validates the source and category, normalizes W3C trace IDs, redacts diagnostics, and returns a plain Ruby hash:
 
 ```ruby
 draft = LogBrew::SupportTicketDraft.create(
@@ -624,7 +642,7 @@ draft = LogBrew::SupportTicketDraft.create(
 puts JSON.generate(draft)
 ```
 
-This helper is local-only. It does not send data, open a ticket, call backend support-ticket routes, use account/session API credentials, or infer backend ownership. Diagnostics are bounded to JSON-like values; token-like keys and strings are redacted, HTTP URLs keep only the path, local filesystem paths are replaced, exceptions keep only the class name, and unsupported Ruby objects are omitted.
+The helper sends nothing. To open the ticket, send it to `POST /api/support/tickets` or run `logbrew support create`. See [Report a problem](https://docs.logbrew.co/guides/report-a-problem). Diagnostics are bounded to JSON-like values; token-like keys and strings are redacted, HTTP URLs keep only the path, local filesystem paths are replaced, exceptions keep only the class name, and unsupported Ruby objects are omitted.
 
 ## HTTP Delivery
 
@@ -706,7 +724,9 @@ client.shutdown
 
 The worker starts only after accepted queue work exists, then wakes when the queue reaches `flush_threshold` or `flush_interval` expires. The defaults are 1 second and 100 events, so a single event is readable in about a second while bursts still share one request. Restart-hydrated persistent work wakes it immediately. Automatic and manual sends share the existing serialized flush, immutable failed prefix, accepted-prefix acknowledgement, batch bounds, and persistence format; no second queue or transport path is created.
 
-Retryable network, `408`, and `5xx` failures retain the exact failed body and use capped equal-jitter backoff. Authentication (`401`/`403`), quota (`429`), validation (`400`/`422`), and other non-retryable responses pause automatic sends without dropping queued work. `recover_automatic_delivery` performs one explicit synchronous flush through the owned transport and resumes scheduling only after success. Calling `flush(transport)` directly provides the same explicit recovery boundary. `stop_automatic_delivery` joins the worker without draining or discarding work; a later manual flush remains available.
+Retryable network, `408`, and `5xx` failures retain the exact failed body and use capped equal-jitter backoff. Authentication (`401`/`403`), quota (`429`, described below), validation (`400`/`422`), and other non-retryable responses pause automatic sends without dropping queued work. `recover_automatic_delivery` performs one explicit synchronous flush through the owned transport and resumes scheduling only after success. Calling `flush(transport)` directly provides the same explicit recovery boundary. `stop_automatic_delivery` joins the worker without draining or discarding work; a later manual flush remains available.
+
+A `429` response with `code: "usage_limit_exceeded"` in its JSON body pauses with the `quota` reason, even when it includes `Retry-After`. Any other `429` with a readable `Retry-After` value (delta-seconds or an HTTP date; a past date counts as zero) or with `code: "rate_limited"` starts a timed wait instead: the client waits for the `Retry-After` delay, or its usual retry backoff when the header is missing, kept between 1 second and 1 hour plus up to 10 percent of random jitter, and capped at 1 hour. The failed batch stays first in the queue and is sent again unchanged when the wait ends, without any application call, while new events keep queueing within the usual limits. During the wait `delivery_health` reports the `retrying` state with `retry_delay_ms`, not a pause. A `429` with neither pauses as before. `HttpTransport` reads at most 4 KiB of a `429` body only to find `code` and never keeps or reports it. A custom transport can request the same handling by returning `LogBrew::TransportResponse.new(429, 1, retry_after: seconds, code: code)`. `flush` still raises `transport_error` for any `429`.
 
 `delivery_health` returns an immutable, JSON-serializable `LogBrew::DeliveryHealth` snapshot. Its fixed fields are lifecycle state, queued event/byte counts, dropped count, in-flight state, bounded outcome/failure/flush counters, pause reason, and current retry delay. It never contains event data, event IDs, API keys, endpoints, headers, response bodies, filesystem paths, process or thread IDs, exception messages, or server text.
 
@@ -907,7 +927,7 @@ unhandled request exceptions are not captured twice.
 - Queues default to 1,000 events and 4 MiB of compact serialized event data; `pending_event_bytes`, `dropped_events`, and `on_event_dropped` expose pressure locally. `TransportResponse#attempts` and `#batches` expose request work.
 - `metric(...)` queues explicit, application-owned metric events with name, kind, value, unit, temporality, and low-cardinality metadata validation.
 - `LogBrew::ProductTimeline` builds explicit, application-owned product action and network milestone timeline events with primitive metadata and query/hash-free routes.
-- `LogBrew::SupportTicketDraft.create` builds explicit, local-only support-ticket create payload drafts with redacted diagnostics and no backend route calls.
+- `LogBrew::SupportTicketDraft.create` builds a redacted support-ticket body and sends nothing.
 - `LogBrew::IssueDiagnostics` builds typed exception identity, mechanism/handled state, basename-only structured frames, and bounded ordered breadcrumbs without raw exception internals.
 - `LogBrew::HttpTransport` sends queued batches through Ruby's standard `Net::HTTP` with configurable endpoint, headers, timeout, and app-owned HTTP client support.
 - `LogBrew::RackMiddleware` captures Rack request spans and unhandled app exceptions without requiring Rails or Rack at runtime.

data/lib/logbrew/automatic_delivery.rb

@@ -26,6 +26,8 @@ module LogBrew
     STATES = %w[idle running retrying paused stopped closing closed].freeze
     OUTCOMES = %w[none empty accepted retryable_failure terminal_failure stopped].freeze
     PAUSE_REASONS = %w[authentication quota validation nonretryable].freeze
+    RATE_LIMIT_MIN_WAIT = 1.0
+    RATE_LIMIT_MAX_WAIT = 3600.0
 
     attr_reader :transport
 
@@ -263,7 +265,7 @@ module LogBrew
           @state = "retrying"
           @last_outcome = "retryable_failure"
           @pause_reason = nil
-          @retry_delay = bounded_retry_delay
+          @retry_delay = failure_retry_delay(error)
           @retry_deadline = monotonic_time + @retry_delay
           ensure_worker if @observed_queue_count.positive?
           @condition.signal
@@ -406,7 +408,7 @@ module LogBrew
       @next_interval_deadline = nil
       if retryable_failure?(error)
         @pause_reason = nil
-        @retry_delay = bounded_retry_delay
+        @retry_delay = failure_retry_delay(error)
         @retry_deadline = monotonic_time + @retry_delay
         @state = "retrying"
         @condition.signal
@@ -455,6 +457,15 @@ module LogBrew
       "nonretryable"
     end
 
+    # A rate limit waits for Retry-After, or the usual backoff, kept within 1 s and 1 h plus up to 10% jitter.
+    def failure_retry_delay(error)
+      wait = error.respond_to?(:automatic_rate_limit) ? error.automatic_rate_limit : nil
+      return bounded_retry_delay if wait.nil?
+
+      delay = (wait.is_a?(Numeric) ? wait.to_f : bounded_retry_delay).clamp(RATE_LIMIT_MIN_WAIT, RATE_LIMIT_MAX_WAIT)
+      [delay + (Random.rand * delay * 0.1), RATE_LIMIT_MAX_WAIT].min
+    end
+
     def bounded_retry_delay
       exponent = [[@consecutive_failures - 1, 0].max, 30].min
       cap = [@retry_base_delay * (2**exponent), @retry_max_delay].min

data/lib/logbrew/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LogBrew
-  VERSION = "0.1.16"
+  VERSION = "0.1.18"
 end

data/lib/logbrew.rb

@@ -100,21 +100,31 @@ module LogBrew
   end
 
   class TransportResponse
-    attr_reader :status_code, :attempts, :batches
+    attr_reader :status_code, :attempts, :batches, :retry_after, :code
 
-    def initialize(status_code, attempts, batches = 1)
+    # For a 429, +retry_after+ is the Retry-After delay in seconds and +code+ is the
+    # JSON body's code string; either may be nil.
+    def initialize(status_code, attempts, batches = 1, retry_after: nil, code: nil)
       @status_code = status_code
       @attempts = attempts
       @batches = batches
+      @retry_after = retry_after
+      @code = code
+    end
+
+    # A 429 waits on its own when it has Retry-After or code "rate_limited", unless the usage limit was hit.
+    def timed_rate_limit?
+      status_code == 429 && code != "usage_limit_exceeded" && (!retry_after.nil? || code == "rate_limited")
     end
   end
 
   class DeliveryFailure < SdkError
-    attr_reader :automatic_pause_reason
+    attr_reader :automatic_pause_reason, :automatic_rate_limit
 
-    def initialize(code, message, automatic_retryable: false, automatic_pause_reason: nil)
+    def initialize(code, message, automatic_retryable: false, automatic_pause_reason: nil, automatic_rate_limit: nil)
       @automatic_retryable = automatic_retryable
       @automatic_pause_reason = automatic_pause_reason
+      @automatic_rate_limit = automatic_rate_limit
       super(code, message)
     end
 
@@ -148,7 +158,9 @@ module LogBrew
       raise response if response.is_a?(TransportError)
       raise response if response.is_a?(SdkError)
 
-      status_code = response.is_a?(TransportResponse) ? response.status_code : response.to_i
+      return TransportResponse.new(response.status_code, 1, retry_after: response.retry_after, code: response.code) if response.is_a?(TransportResponse)
+
+      status_code = response.to_i
       TransportResponse.new(status_code.zero? ? 202 : status_code, 1)
     end
   end
@@ -156,6 +168,8 @@ module LogBrew
   class HttpTransport
     DEFAULT_ENDPOINT = "https://api.logbrew.co/v1/events"
     DEFAULT_TIMEOUT = 10
+    MAX_ERROR_BODY_BYTES = 4096
+    MAX_RATE_LIMIT_WAIT = 3600
 
     attr_reader :endpoint, :headers, :timeout, :http_client
 
@@ -176,18 +190,49 @@ module LogBrew
       @headers.each { |name, value| request[name] = value }
       request.body = body
 
-      response = HttpClientTracing.suppress do
-        @http_client ? @http_client.request(request) : request_with_default_client(request)
+      response, error_body = HttpClientTracing.suppress do
+        @http_client ? [@http_client.request(request), nil] : request_with_default_client(request)
       end
-      TransportResponse.new(response.code.to_i, 1)
+      status_code = response.code.to_i
+      return TransportResponse.new(status_code, 1) unless status_code == 429
+
+      TransportResponse.new(
+        status_code,
+        1,
+        retry_after: self.class.parse_retry_after(response.get_fields("retry-after")),
+        code: error_code(error_body || response.body)
+      )
     rescue TransportError
       raise
     rescue IOError, SystemCallError, SocketError, Timeout::Error, EOFError, Net::OpenTimeout, Net::ReadTimeout => error
       raise TransportError.network("http transport failed: #{error.message}")
     end
 
+    # Reads one Retry-After value as seconds: delta-seconds or an HTTP date, where a past date is 0.
+    # Missing, empty, repeated, or unreadable values return nil.
+    def self.parse_retry_after(values, now = Time.now)
+      return nil unless values.is_a?(Array) && values.length == 1
+
+      value = values.first.to_s.strip
+      return [value.to_i, MAX_RATE_LIMIT_WAIT].min if value.match?(/\A\d+\z/)
+
+      (Time.httpdate(value) - now).clamp(0, MAX_RATE_LIMIT_WAIT)
+    rescue ArgumentError
+      nil
+    end
+
     private
 
+    # Finds the JSON code of a 429 body of at most 4 KiB; the body is never kept.
+    def error_code(body)
+      return nil if body.nil? || body.bytesize > MAX_ERROR_BODY_BYTES
+
+      parsed = JSON.parse(body)
+      parsed.is_a?(Hash) && parsed["code"].is_a?(String) ? parsed["code"] : nil
+    rescue JSON::ParserError
+      nil
+    end
+
     def request_path
       path = @endpoint.path.empty? ? "/" : @endpoint.path
       return path if @endpoint.query.nil? || @endpoint.query.empty?
@@ -201,7 +246,26 @@ module LogBrew
       http.open_timeout = @timeout
       http.read_timeout = @timeout
       http.write_timeout = @timeout if http.respond_to?(:write_timeout=)
-      http.start { |client| client.request(request) }
+      http.start do |client|
+        catch(:logbrew_rate_limited) do
+          response = client.request(request) do |received|
+            throw :logbrew_rate_limited, [received, bounded_body(received)] if received.code == "429"
+          end
+          [response, nil]
+        end
+      end
+    end
+
+    # Leaves the request after at most 4 KiB plus one byte, so a larger 429 body is never read.
+    def bounded_body(response)
+      body = +""
+      catch(:logbrew_body_limit) do
+        response.read_body do |chunk|
+          body << chunk
+          throw :logbrew_body_limit if body.bytesize > MAX_ERROR_BODY_BYTES
+        end
+      end
+      body
     end
 
     def validate_endpoint(endpoint)
@@ -1213,6 +1277,15 @@ module LogBrew
             )
           end
 
+          if response.respond_to?(:timed_rate_limit?) && response.timed_rate_limit?
+            raise DeliveryFailure.new(
+              "transport_error",
+              "unexpected transport status 429",
+              automatic_retryable: true,
+              automatic_rate_limit: response.retry_after || :backoff
+            )
+          end
+
           pause_reason = case response.status_code
                          when 429 then "quota"
                          when 400, 422 then "validation"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: logbrew-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.16
+  version: 0.1.18
 platform: ruby
 authors:
 - LogBrew
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-29 00:00:00.000000000 Z
 dependencies: []
 description: Public LogBrew Ruby SDK with typed issue diagnostics, automatic Rails
   request/error capture, and standard-library delivery.