end_point_blank 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2327b3053463662a656ad3f6d03596e7e21c72beae8c30aa18fc445eff230a5
-  data.tar.gz: 4c80916d52eab6b760ec5ebedf1ee70da4132697e49f37305d106aa5637677d5
+  metadata.gz: 25e18f304c5b420719930533c91b34cc2df76504e5a6d28504491b42c267e2e9
+  data.tar.gz: 99b6acaf7c8dc69e730ebe81a4de17eea39f72ff32e681da08130cdafd2181f2
 SHA512:
-  metadata.gz: 8c13f72a824fa9b0e8d05bbf6a039bae0aec1f9c24fb5226bb23de58cf8f6fe75f99c3089ff95fc7a1989b8dd90bb705d246558fb62f1d8073d10b394ed1b927
-  data.tar.gz: 786fb59740f10dc62c61bdd8ffc014cd72c0fba1c223ff6c9465b840c4c6134720cec8eceb321cd78caee0dd8a4a8ba58f9db0db05ed6cf756eb1fe78239f5ed
+  metadata.gz: 79f945a9dacd76714a5d2a229931858d0346428b9459a6dfa98b0a5a363a1b043ff12c29643cc3c3f0d1679930d9d7056c29d02813a18863594e796ce667ad7d
+  data.tar.gz: 8b61b6a9f38a5ff2e52d5a37d7979ed18fd0d49f06f8ae3ecf4a07bba8683cc7cefc76b17ec68a3e4a32654644a313e2d6e70c24666de9d1f93654720233ecdd

data/HARDENING_REPORT.md

@@ -0,0 +1,210 @@
+# Hardening report — end_point_blank (Rails/Ruby client lib) — P2 #14
+
+Branch: `harden-timeouts-bounded-queue` (off `master`, not pushed)
+
+## Goal
+
+Bring this lib's reliability posture in line with the Elixir sibling lib,
+which was hardened with per-attempt HTTP timeouts (connect 3s / read 5s)
+and a bounded, drop-oldest background send queue (cap 1000, throttled
+warning on drop).
+
+## Gap 1 — Excon calls with no timeout
+
+### Every `Excon.` call site in the lib (confirmed via `grep -rn "Excon\." lib/`)
+
+| File | Line | Call |
+|---|---|---|
+| `lib/end_point_blank/commands/http.rb` | 23 | `Excon.post` (shared fire-and-forget POST helper, used by `DirectWriter`) |
+| `lib/end_point_blank/commands/generate_access_token.rb` | 20 | `Excon.post` (access-token exchange) |
+| `lib/end_point_blank/commands/endpoint_update.rb` | 30 | `Excon.post` (endpoint/route registration) |
+
+All three are the only `Excon.*` calls in the lib. No other `Excon.new`/etc. exist.
+
+### Fix
+
+Added a single shared constant in `lib/end_point_blank/commands/http.rb`:
+
+```ruby
+CONNECT_TIMEOUT = 3
+READ_TIMEOUT    = 5
+TIMEOUT_OPTIONS = { connect_timeout: CONNECT_TIMEOUT, read_timeout: READ_TIMEOUT }.freeze
+```
+
+- `Http.post` now passes `**TIMEOUT_OPTIONS` directly.
+- `generate_access_token.rb` and `endpoint_update.rb` each `require_relative 'http'`
+  and splat `**EndPointBlank::Commands::Http::TIMEOUT_OPTIONS` into their own
+  `Excon.post` calls, so the values live in exactly one place.
+
+### Timeout error handling
+
+`Excon::Error::Timeout` is a subclass of `Excon::Error` (verified against the
+installed excon 1.5.0 source), so:
+
+- `Http.post`'s existing `rescue Excon::Error => e` already covers timeouts —
+  it retries up to `MAX_ATTEMPTS` (3) then logs and returns `nil`. No caller
+  ever sees an exception.
+- `generate_access_token.rb`'s existing `rescue => e` (StandardError) already
+  covered timeouts too.
+- `endpoint_update.rb` had a **latent bug**: `rescue Excon::Error::Socket,
+  Excon::Error::Connection => e`. `Excon::Error::Connection` **does not
+  exist** in excon 1.5.0 (only `Excon::Error::Socket`, `Excon::Error::Timeout`,
+  etc. are defined under `Excon::Error`). Because Ruby resolves rescue-clause
+  constants lazily, this clause would silently work until an exception was
+  actually raised inside the `begin` block, at which point evaluating
+  `Excon::Error::Connection` would raise `NameError` and crash the caller —
+  i.e. a network blip or a timeout during endpoint registration would have
+  thrown `NameError` instead of being handled gracefully. Fixed by rescuing
+  `Excon::Error` broadly (matching the pattern in `http.rb`), which now also
+  correctly covers `Excon::Error::Timeout`.
+
+### Incidental fix required to exercise the above in tests
+
+`lib/end_point_blank/authorization.rb` calls `Base64.encode64` for the Basic
+auth header path but never `require 'base64'`. On Ruby 3.4 `base64` was
+removed from default gems, so this raised `NameError` / `LoadError` the
+moment that code path executed (which is exactly the path exercised in the
+`endpoint_update` timeout test, since it needs an `Authorization.header` call
+with no cached token). Fixed by adding `require 'base64'` in
+`authorization.rb` and declaring `spec.add_dependency "base64"` in the
+gemspec (ran `bundle install`, updating `Gemfile.lock`). This was a real
+reliability bug independent of this task — any Basic-auth call path in this
+gem on Ruby >= 3.4 without `base64` explicitly in the app's own Gemfile would
+have crashed.
+
+## Gap 2 — unbounded background queue
+
+`lib/end_point_blank/writers/delayed_writer.rb` used a plain `Queue.new`
+(unbounded). During an intake outage, the 2 background drain threads block
+on failed/slow POSTs and the queue grows without bound → OOM risk.
+
+### Fix
+
+`Queue` has no `max` option, so the bound is implemented explicitly:
+
+- `MAX_QUEUE_SIZE = 1000`.
+- `enqueue` (public API, accepts a single payload or an array, unchanged
+  signature) now routes each item through `enqueue_one`, which is guarded by
+  a `Mutex` (`enqueue_mutex`) so the check-then-drop-then-push sequence is
+  atomic across concurrent producer threads (the request/response/log/error
+  writer call paths).
+- If `queue.size >= MAX_QUEUE_SIZE` when a new item arrives, the **oldest**
+  item is dropped first (`pop_additional`, a non-blocking `Queue#pop(true)`,
+  which removes from the front of the FIFO `Queue`), then the new item is
+  pushed. Net effect: queue never exceeds 1000, newest items win.
+- Drop warnings are throttled: `note_drop` tracks a drop counter and only
+  logs (via `log_warning`, which prefers `::Rails.logger.warn` and falls
+  back to `Kernel#warn` when Rails isn't loaded) at most once per
+  `WARN_THROTTLE_SECONDS` (30s), with the message including how many items
+  were dropped since the last warning — so a sustained outage doesn't itself
+  become a logging flood.
+- The existing 2-thread drain model (`start_threads`) is unchanged in
+  structure; internal `@queue` access was switched to a `queue` reader
+  (`@queue ||= Queue.new`) so both the drain threads and the new bounded
+  `enqueue_one` share the same lazily-initialized queue, and so tests can
+  instantiate a bare object that mixes in `DelayedWriter` and drive
+  `enqueue`/`queue` without needing to spin up the background threads.
+
+## Sinatra coverage
+
+Confirmed: `end_point_blank_sinatra/Gemfile` depends on
+`gem 'end_point_blank', path: '../end_point_blank_rails'` and
+`end_point_blank_sinatra/app.rb` does `require 'end_point_blank'`, which is
+this gem's single entry point (`lib/end_point_blank.rb`) that requires every
+file touched here (`commands/http`, `commands/generate_access_token`,
+`commands/endpoint_update`, `writers/delayed_writer`, `authorization`).
+There is no Sinatra-specific fork of any of this code. **Sinatra is
+covered.**
+
+## Tests added (TDD: written first, confirmed red against the pre-fix code, then made green)
+
+- `spec/commands_http_spec.rb` — asserts `Excon.post` is called with
+  `connect_timeout`/`read_timeout` matching the shared constants; asserts a
+  raised `Excon::Error::Timeout` is retried `MAX_ATTEMPTS` times, logged, and
+  returns `nil` without raising.
+- `spec/generate_access_token_spec.rb` — asserts the same timeout options
+  reach `Excon.post` for the access-token exchange; asserts a timeout
+  doesn't raise.
+- `spec/endpoint_update_spec.rb` — asserts the same timeout options reach
+  `Excon.post` for endpoint registration; asserts a timeout doesn't raise
+  and is logged via `Rails.logger.warn` (this is the test that caught both
+  the `Excon::Error::Connection` NameError bug and the missing
+  `require 'base64'`).
+- `spec/delayed_writer_spec.rb` — mixes `DelayedWriter` into a bare test
+  class (without starting background threads, so the queue can be inspected
+  synchronously): asserts the queue never exceeds `MAX_QUEUE_SIZE`, asserts
+  the oldest items are dropped first (FIFO order preserved for survivors),
+  asserts normal FIFO enqueue/dequeue when under the cap, asserts array-form
+  `enqueue` also respects the bound, and asserts `log_warning` is called
+  only **once** across 50 drops (throttling), not once per drop.
+
+All four spec files were confirmed to fail (9 of 11 new examples red) against
+the original code before implementing the fix, then confirmed green after.
+
+## Test evidence
+
+```
+$ bundle exec rspec
+...
+49 examples, 0 failures
+```
+
+Also ran the project's actual CI commands directly:
+
+```
+$ ./build.sh   # bundle install — passes
+$ ./test.sh    # bundle exec rspec — 49 examples, 0 failures
+```
+
+`bundle exec ruby -Ilib -e "require 'end_point_blank'"` loads cleanly and
+`EndPointBlank::Commands::Http::TIMEOUT_OPTIONS` /
+`EndPointBlank::Writers::DelayedWriter::MAX_QUEUE_SIZE` are inspectable at
+the top level, confirming the constants are reachable as documented.
+
+`rubocop` was also run for hygiene (not part of CI — `ci.yml` only runs
+`./test.sh`, i.e. rspec). It reports 46 offenses across the 5 touched files
+vs. 43 pre-existing on the same files before this change — the 3 new ones
+are `Metrics/AbcSize`/`Metrics/MethodLength` on `start_threads`, whose body
+is unchanged except swapping `@queue` for the new `queue` reader method; all
+newly-added methods (`enqueue_one`, `drop_oldest_and_note`, `note_drop`,
+`warn_dropped_items`, `log_warning`) were kept short enough to avoid adding
+further offenses. None of this blocks CI.
+
+## Files changed
+
+- `lib/end_point_blank/commands/http.rb` — shared timeout constants/helper,
+  applied to `Http.post`.
+- `lib/end_point_blank/commands/generate_access_token.rb` — applies shared
+  timeout options to its `Excon.post`.
+- `lib/end_point_blank/commands/endpoint_update.rb` — applies shared timeout
+  options to its `Excon.post`; fixed the broken `Excon::Error::Connection`
+  rescue clause to `rescue Excon::Error` (now also catches `Timeout`).
+- `lib/end_point_blank/writers/delayed_writer.rb` — bounded, drop-oldest,
+  throttled-warning queue.
+- `lib/end_point_blank/authorization.rb` — `require 'base64'` (incidental
+  fix, needed for the Basic-auth path to work at all on Ruby 3.4, and
+  required to exercise the `endpoint_update` timeout test end-to-end).
+- `end_point_blank.gemspec`, `Gemfile.lock` — declare `base64` as an
+  explicit dependency (Ruby 3.4 removed it from default gems).
+- New specs: `spec/commands_http_spec.rb`, `spec/generate_access_token_spec.rb`,
+  `spec/endpoint_update_spec.rb`, `spec/delayed_writer_spec.rb`.
+
+## Concerns / follow-ups (not fixed here, out of scope for P2 #14)
+
+- The queue bound is a soft/approximate guarantee under heavy concurrent
+  enqueue: the mutex only guards the *decision* to drop before push, so with
+  many producer threads racing, the queue could very briefly be examined by
+  more than one thread between the `pop`/`push` pair in rare interleavings
+  is prevented by the mutex — but a concurrent **drain** thread popping at
+  the same moment only ever shrinks the queue, never grows it past the cap.
+  In practice the bound holds exactly given the mutex around all enqueue-side
+  mutation.
+- `note_drop`/`@last_drop_warning_at` state lives on the writer singleton
+  instance (`RequestWriter`, `ResponseWriter`, `ExceptionWriter`,
+  `LogWriter` each get their own independent throttle window since they each
+  `include DelayedWriter` separately) — this is intentional (matches
+  per-queue behavior) but worth knowing if someone expects a single global
+  throttle across all four queues.
+- Rubocop was not run as part of CI before this change and still isn't;
+  pre-existing style debt (43 offenses) was left alone except where it was
+  directly in code I touched and cheap to avoid growing.

data/LICENSE

@@ -0,0 +1,16 @@
+Copyright (c) 2026 EndPointBlank. All rights reserved.
+
+This software and its associated documentation (the "Software") are the
+proprietary and confidential property of EndPointBlank. The Software is licensed,
+not sold, and its use is governed by a separate written agreement between you and
+EndPointBlank. No rights are granted except as expressly set out in that agreement.
+
+Without the prior written permission of EndPointBlank, you may not copy, modify,
+merge, publish, distribute, sublicense, or sell copies of the Software, in whole
+or in part, by any means.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL ENDPOINTBLANK BE
+LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM THE USE OF THE
+SOFTWARE.

data/README.md

@@ -1,28 +1,188 @@
-# EndPointBlankRack
+# EndPointBlank (Ruby)
 
-TODO: Delete this and the text below, and describe your gem
+The Ruby client for [EndPointBlank](https://endpointblank.com): API endpoint tracking, endpoint
+authorization, error/request/response/log reporting, and client-side data masking — with a
+**framework-agnostic core** that runs in plain Ruby or Sinatra, plus a Rails adapter that
+auto-loads (railtie + middleware) when Rails is present.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/end_point_blank_rack`. To experiment with that code, run `bin/console` for an interactive prompt.
+## Capabilities
+
+- **Endpoint tracking** — every request/response passing through the Rack middleware is reported.
+- **Authorization** — outbound calls to other EndPointBlank-protected services are signed
+  (`Basic` client-credential or cached `Bearer` token), and inbound requests can be authorized
+  against the EndPointBlank service before your action runs.
+- **Error, request, response, and log reporting** — background, queued, non-blocking delivery to
+  the EndPointBlank intake API.
+- **Client-side data masking** (`EndPointBlank::Masking` / `masking_rules`) — strip or redact
+  sensitive fields from payloads *before* they leave your process, as defense in depth on top of
+  server-side masking.
+- **Framework-agnostic core** — `EndPointBlank::Middleware::Rack::ReportInteraction` and the
+  writers work directly against Rack env/`::Rack::Request`, so the gem behaves correctly under
+  plain Ruby, Sinatra, or any Rack app. When `::Rails` is defined, a `Railtie` auto-inserts the
+  middleware and wires up `Rails.logger`; nothing extra needs loading.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+This gem is **not yet published on RubyGems.org**. Until it is, install it from git.
+
+Add to your `Gemfile`:
+
+```ruby
+gem "end_point_blank", github: "EndPointBlank/end_point_blank_rails"
+```
+
+(Once released to RubyGems, this collapses to `gem "end_point_blank"`.)
+
+Then:
+
+```sh
+bundle install
+```
+
+## Quick start
+
+```ruby
+EndPointBlank.configure do |config|
+  config.client_id     = "your-client-id"
+  config.client_secret  = "your-client-secret"
+  config.app_name      = "my-service"
+end
+```
+
+That's it for a Rails app — the railtie auto-inserts the reporting middleware, and every request
+processed by your app is tracked. For plain Ruby / Sinatra, see
+[Framework integration](#framework-integration) below to wire up the Rack middleware yourself.
+
+To send your first log line:
+
+```ruby
+EndPointBlank::Writers::LogWriter.info("service started", { pid: Process.pid })
+```
+
+## Configuration
 
-Install the gem and add to the application's Gemfile by executing:
+`EndPointBlank.configure { |c| ... }` yields the `EndPointBlank::Configuration` singleton.
+Every setting listed below can be set explicitly in that block, and most also fall back to an
+`ENDPOINTBLANK_*` environment variable, then to a built-in default.
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+**Precedence: explicit `configure` value > `ENDPOINTBLANK_*` environment variable > default.**
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+| `configure` setting | Env var fallback | Default | Notes |
+|---|---|---|---|
+| `client_id` | `ENDPOINTBLANK_CLIENT_ID` | `nil` | Used to build the `Basic` authorization header. |
+| `client_secret` | `ENDPOINTBLANK_CLIENT_SECRET` | `nil` | Paired with `client_id`. |
+| `base_url` | `ENDPOINTBLANK_BASE_URL` | `https://in.endpointblank.com` | Base for access-token, authorize, and endpoint-update APIs. |
+| `log_base_url` | `ENDPOINTBLANK_LOG_BASE_URL` | `https://log.endpointblank.com` | Base for error/request/response/log reporting APIs. |
+| `app_name` | `ENDPOINTBLANK_APP_NAME` | `Rails.application.name.underscore` if Rails is defined, else `nil` | Identifies your app to EndPointBlank. |
+| `env_name` | `ENDPOINTBLANK_ENV` | `RACK_ENV`, then `APP_ENV`, then `Rails.env` if defined, else `"production"` (resolved per-request by `SessionConfiguration.env_name`, not read directly off `Configuration`) | The environment name reported with each request/response payload. |
+| `logger` | — | A `::Logger.new($stdout, level: ::Logger::INFO)`, or `Rails.logger` under Rails (set by the railtie) | Any object with `.debug`/`.info`/`.warn`/`.error`/`.fatal` works. |
+| `worker_count` | — | `4` | Currently unused by the delayed writer (which always spins up 2 threads); reserved. |
+| `token_ttl` | — | `nil` | Optional TTL (seconds) requested when generating a `Bearer` access token. |
+| `cache_ttl` | — | `300` | TTL (seconds) for the authorization decision cache. |
+| `masking_rules` | — | `[]` | Ordered list of masking rule hashes — see [Data masking](#data-masking). |
+| `mask_hook` | — | `nil` | Optional `->(payload, record_type_string) { payload }` run after `masking_rules`. |
+| `version_finder` | — | `nil` | Optional `->(request) { "1" }` overriding `EndPointBlank::Commands::VersionFinder`'s default header/param/path detection. |
+| `application_version` | — | `nil` | Reserved for reporting your app's own version. |
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+Note: there is also a bare `environment` accessor on `Configuration`, but it is not read by any
+code path in this gem (the real per-request environment name is `env_name`, described above) — do
+not rely on it.
+
+### `configure` block example
+
+```ruby
+EndPointBlank.configure do |config|
+  config.client_id      = "abc123"
+  config.client_secret  = "s3cr3t"
+  config.base_url       = "https://in.endpointblank.com"
+  config.log_base_url   = "https://log.endpointblank.com"
+  config.app_name       = "checkout-service"
+  config.env_name       = "staging"
+  config.logger         = Logger.new($stdout)
+end
+```
+
+### 12-factor / env-var example
+
+With no `configure` block at all (or a partial one), the same values can come entirely from the
+environment:
+
+```sh
+export ENDPOINTBLANK_CLIENT_ID=abc123
+export ENDPOINTBLANK_CLIENT_SECRET=s3cr3t
+export ENDPOINTBLANK_BASE_URL=https://in.endpointblank.com
+export ENDPOINTBLANK_LOG_BASE_URL=https://log.endpointblank.com
+export ENDPOINTBLANK_APP_NAME=checkout-service
+export ENDPOINTBLANK_ENV=staging
+```
 
 ## Usage
 
-### Masking
+### Authorization
+
+`EndPointBlank::Authorization.header(hostname = nil)` builds the outbound `Authorization` header
+used by the gem's own HTTP calls: a cached `Bearer` token for `hostname` when one is available
+(via `EndPointBlank::AccessTokens`), otherwise `Basic` credentials built from `client_id` /
+`client_secret`.
+
+```ruby
+EndPointBlank::Authorization.header               # => "Basic ..."
+EndPointBlank::Authorization.header("api.example.com") # => "Bearer ..." if a token is cached
+```
+
+Under Rails, protect an inbound endpoint by including the `Authorized` concern in a controller —
+it calls `EndPointBlank::Commands::EndpointAuthorize.authorize(request)` before the action, and
+raises `EndPointBlank::UnauthorizedError` (which you can rescue with
+`rescue_from EndPointBlank::UnauthorizedError` in `ApplicationController`) on a non-201 response:
+
+```ruby
+class OrdersController < ApplicationController
+  include EndPointBlank::Rails::Authorized
+end
+```
+
+`EndPointBlank::Commands::EndpointAuthorize.authorize` sends the request's path, HTTP method,
+inbound `Authorization` header, app name, resolved endpoint version, and remote IP to
+`#{base_url}/api/authorize`, and caches a positive (201) result for `cache_ttl` seconds via
+`EndPointBlank::Commands::AuthenticationCache`.
 
-Mask sensitive data **before it leaves your app**. Configure an ordered list of rules; each rule
-targets one field and masks by a JSONPath, a regex, or both. (Server-side intake also masks
-independently, so this is defense in depth.)
+### Error reporting
+
+Exceptions raised while `EndPointBlank::Middleware::Rack::ReportInteraction` is on the stack are
+reported automatically (see [Framework integration](#framework-integration)). To report one
+manually:
+
+```ruby
+begin
+  risky_operation!
+rescue => e
+  EndPointBlank::Writers::ExceptionWriter.write(e)
+  raise
+end
+```
+
+### Request/response/log reporting
+
+Requests and responses are written automatically by the Rack middleware. Application logs are
+sent explicitly:
+
+```ruby
+EndPointBlank::Writers::LogWriter.info("cache warmed", { keys: 42 })
+EndPointBlank::Writers::LogWriter.warn("slow query", { duration_ms: 820 })
+EndPointBlank::Writers::LogWriter.error("payment webhook rejected", { code: "sig_mismatch" })
+EndPointBlank::Writers::LogWriter.fatal("out of workers")
+```
+
+All writers (`RequestWriter`, `ResponseWriter`, `ExceptionWriter`, `LogWriter`) enqueue their
+payload onto a bounded, in-memory queue (`DelayedWriter`, capacity 1000, drop-oldest under
+sustained backpressure) drained by two background threads that POST batches via `excon`. Delivery
+is fire-and-forget and never raises into your request cycle.
+
+### Data masking
+
+Mask sensitive data **client-side, before it leaves your process**. Configure an ordered list of
+rules; each rule targets one field and masks by a JSONPath, a regex, or both. (Server-side intake
+also masks independently, so this is defense in depth.)
 
 ```ruby
 EndPointBlank.configure do |config|
@@ -37,28 +197,109 @@ EndPointBlank.configure do |config|
 end
 ```
 
-Rules are hashes with symbol keys.
+Rules are hashes with symbol (or string) keys.
 
 **Rule fields**
 
-- `target` — exactly one of `"request_body"`, `"request_headers"`, `"path"`, `"response_body"`, `"error_message"`.
+- `target` — exactly one of `"request_body"`, `"request_headers"`, `"path"`, `"response_body"`,
+  `"error_message"`.
 - `path` — an optional JSONPath (supported subset: `$`, `.name`, `['name']`, `[n]`, `.*` / `[*]`,
   and `..name` for recursive descent). Keys are case-sensitive.
-- `regex` — an optional regular expression.
+- `regex` — an optional regular expression source string.
 - `replacement_value` — the replacement string (default `"..."`).
 
-**Semantics — path scopes, regex matches within.** With only a `path`, the selected node is replaced
-entirely. With only a `regex`, every matching string is replaced. With both, the regex is applied
-only within the path-selected node(s). When a `regex` is present, `replacement_value` supports
-backreferences: `$1`, `$2`, … insert capture groups (`$0` the whole match; `$$` for a literal `$`).
-Stacktraces and log messages are never masked.
+**Semantics — path scopes, regex matches within.** With only a `path`, the selected node is
+replaced entirely. With only a `regex`, every matching string leaf is replaced. With both, the
+regex is applied only within the path-selected node(s). When a `regex` is present,
+`replacement_value` supports backreferences: `$1`, `$2`, … insert capture groups (`$0` the whole
+match; `$$` for a literal `$`). Stacktraces and log messages/data are never masked (there is no
+`log` entry in the masking field map).
+
+## Framework integration
+
+### Rails
+
+Nothing to wire up manually. When `::Rails` is defined, `lib/end_point_blank.rb` requires
+`EndPointBlank::Rails::Railtie`, which:
+
+- inserts `EndPointBlank::Middleware::Rack::ReportInteraction` into the middleware stack right
+  after `ActionDispatch::DebugExceptions`, so every request/response is reported and exceptions
+  are captured before Rails' own exception rendering; and
+- sets `Configuration.instance.logger ||= Rails.logger`, so `EndPointBlank.logger` writes through
+  `Rails.logger` unless you've already configured your own.
+
+Optional concerns for controllers:
+
+```ruby
+class ApplicationController < ActionController::Base
+  rescue_from EndPointBlank::UnauthorizedError do |e|
+    render json: { error: e.message }, status: e.status
+  end
+end
+
+class OrdersController < ApplicationController
+  include EndPointBlank::Rails::Authorized   # authorize inbound requests before each action
+  include EndPointBlank::Rails::Versioned
+
+  version ["v1", "v2"], only: [:index]
+end
+```
+
+`app_name` falls back to `Rails.application.name.underscore` automatically, so Rails apps
+typically only need to configure `client_id` / `client_secret` (and `app_name` only to override
+the Rails-derived default).
+
+### Plain Ruby / Sinatra
+
+There's no Rails to auto-load anything, so insert the Rack middleware yourself and set `app_name`
+and `env_name` explicitly (via `configure` or `ENDPOINTBLANK_APP_NAME` / `ENDPOINTBLANK_ENV`,
+since there's no `Rails.application.name` / `Rails.env` to infer them from):
+
+```ruby
+require "sinatra"
+require "end_point_blank"
+
+EndPointBlank.configure do |config|
+  config.client_id     = ENV.fetch("ENDPOINTBLANK_CLIENT_ID")
+  config.client_secret = ENV.fetch("ENDPOINTBLANK_CLIENT_SECRET")
+  config.app_name       = "my-sinatra-app"   # or set ENDPOINTBLANK_APP_NAME and omit this
+  config.env_name       = "production"       # or set ENDPOINTBLANK_ENV / RACK_ENV and omit this
+  config.logger         = Logger.new($stdout)
+end
+
+use EndPointBlank::Middleware::Rack::ReportInteraction
+
+get "/" do
+  "ok"
+end
+```
+
+The middleware calls `EndPointBlank::Rack::EnvStore.set(env)`, reports the request via
+`RequestWriter`, invokes the app, and — in an `ensure` — reports the response via `ResponseWriter`
+and clears the env store, reporting any raised exception via `ExceptionWriter` along the way. It
+reads/writes plain Rack request objects (`::Rack::Request`), so it works identically under any
+Rack-compatible server or framework, not only Sinatra.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```sh
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+`bundle exec rspec` runs the full suite, including specs that assert the framework-agnostic core
+behaves correctly with `::Rails` undefined (`spec/no_rails_spec.rb`,
+`spec/generate_access_token_no_rails_spec.rb`,
+`spec/route_pattern_finder_and_version_finder_no_rails_spec.rb`).
+
+## License
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+No `LICENSE` file or `spec.license` is currently present in this repository. Treat usage as
+proprietary/all-rights-reserved until a license is added, or confirm terms with the repository
+owners.
 
-## Contributing
+## Links
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/end_point_blank_rack.
+- Repository: https://github.com/EndPointBlank/end_point_blank_rails
+- Issues: https://github.com/EndPointBlank/end_point_blank_rails/issues

data/end_point_blank.gemspec

@@ -12,6 +12,7 @@ Gem::Specification.new do |spec|
   spec.description = "EndPointBlank client library for Ruby. A framework-agnostic core runs in plain Ruby / Sinatra, with Rails supported as an auto-loaded adapter. Provides API endpoint tracking, authorization, and error/request/response/log reporting."
   spec.homepage = "https://github.com/EndPointBlank/end_point_blank_rails"
   spec.required_ruby_version = ">= 3.4.2"
+  spec.license = "Nonstandard"
 
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
 

data/lib/end_point_blank/configuration.rb

@@ -13,7 +13,7 @@ module EndPointBlank
 
     attr_writer :client_id, :client_secret, :base_url, :log_base_url, :app_name, :env_name
 
-    attr_accessor :environment, :worker_count, :log_mode,
+    attr_accessor :worker_count, :log_mode,
                   :version_finder, :application_version, :token_ttl, :cache_ttl,
                   :masking_rules, :mask_hook, :logger
 

data/lib/end_point_blank/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EndPointBlank
-  VERSION = "0.2.0"
+  VERSION = "0.2.2"
 end

data/lib/end_point_blank/writers/delayed_writer.rb

@@ -1,4 +1,6 @@
-require 'singleton'
+# frozen_string_literal: true
+
+require "singleton"
 
 module EndPointBlank
   module Writers
@@ -14,6 +16,9 @@ module EndPointBlank
     module DelayedWriter
       MAX_QUEUE_SIZE = 1000
       WARN_THROTTLE_SECONDS = 30
+      # Fallback thread count used when Configuration#worker_count is unset,
+      # preserving the previously-hardcoded pool size.
+      DEFAULT_WORKER_COUNT = 2
 
       def direct_writer
         @direct_writer ||= DirectWriter.new(url)
@@ -23,28 +28,32 @@ module EndPointBlank
         @queue ||= Queue.new
       end
 
+      def worker_count
+        EndPointBlank::Configuration.instance.worker_count || DEFAULT_WORKER_COUNT
+      end
+
       def start_threads
         @threads = []
 
-        2.times do
+        worker_count.times do
           @threads << Thread.new do
             loop do
               payload = queue.pop
               payloads = [payload]
-              while (payload = pop_additional) do
+              while (payload = pop_additional)
                 payloads << payload
               end
 
               payloads.compact!
-              while payloads.any? do
+              while payloads.any?
                 list = payloads[0..5]
                 response = direct_writer.write(list)
                 if response.status < 299
                   on_success(response) if respond_to?(:on_success)
-                else
-                  on_failure(response) if respond_to?(:on_failure)
+                elsif respond_to?(:on_failure)
+                  on_failure(response)
                 end
-                payloads = payloads - list
+                payloads -= list
               end
             end
           end

data/lib/end_point_blank/writers/response_writer.rb

@@ -36,6 +36,7 @@ module EndPointBlank
             body: truncate(normalize_body(body)),
             sent_at: Time.now.utc.iso8601(3),
             route: route,
+            method: request&.request_method,
             data: data,
             source_application_environment_id: source_application_environment_id
         }

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: end_point_blank
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Robert A. Lasch
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: excon
@@ -91,6 +91,8 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- HARDENING_REPORT.md
+- LICENSE
 - README.md
 - Rakefile
 - build.sh
@@ -136,7 +138,8 @@ files:
 - sig/end_point_blank_rack.rbs
 - test.sh
 homepage: https://github.com/EndPointBlank/end_point_blank_rails
-licenses: []
+licenses:
+- Nonstandard
 metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/EndPointBlank/end_point_blank_rails
@@ -156,7 +159,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.7
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Ruby/Rails client for EndPointBlank — endpoint tracking, authorization, and
   error/request/response/log reporting.