end_point_blank 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2327b3053463662a656ad3f6d03596e7e21c72beae8c30aa18fc445eff230a5
-  data.tar.gz: 4c80916d52eab6b760ec5ebedf1ee70da4132697e49f37305d106aa5637677d5
+  metadata.gz: b93be9173755a967ce4c1f1d38205b8803bc175ec1d029f860c6620807553bca
+  data.tar.gz: 74ff753691ea46be3ac391cea6b178673a8fb4cd7e0b6ea2861b9646d138e710
 SHA512:
-  metadata.gz: 8c13f72a824fa9b0e8d05bbf6a039bae0aec1f9c24fb5226bb23de58cf8f6fe75f99c3089ff95fc7a1989b8dd90bb705d246558fb62f1d8073d10b394ed1b927
-  data.tar.gz: 786fb59740f10dc62c61bdd8ffc014cd72c0fba1c223ff6c9465b840c4c6134720cec8eceb321cd78caee0dd8a4a8ba58f9db0db05ed6cf756eb1fe78239f5ed
+  metadata.gz: 4533c807575899944c7626e716585018309a55311d659b0e2b3fa5005b0ab5b825bec2ef89a0b3d9108277ddac28cc985c75c6047ded18542c2d4dceeace66f1
+  data.tar.gz: d7a5148cba59e40aaf3190b8147800e4777882ff08c31e9245ede3f289eff1eedb2c43dfe034587bf52cf2b23518b2d6cdbe4435e90235c71418d433c1d9b16c

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.1"
 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

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.1
 platform: ruby
 authors:
 - Robert A. Lasch
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: excon
@@ -91,6 +91,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- LICENSE
 - README.md
 - Rakefile
 - build.sh
@@ -136,7 +137,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 +158,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.