rest-easy 1.1.2 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec1e2b4f51ad07119add9f89dd2075a765fa2fc258766294aa7b05c1bc4e2951
-  data.tar.gz: 350b2381fd3e0dd4cde1815000684c474238ed5c5f8d438611a8fb5de9e381b8
+  metadata.gz: c5f42d44a6677ffb6553237d5be80fc7247a6501946069ee1034b0811a4b6219
+  data.tar.gz: 858f63be66e21f33873ea74467eb411215d213c921acab98c489d6db03734fdd
 SHA512:
-  metadata.gz: 358c1e91aca70417fc86738b71078bf931da0a562f3ea102875e25d6c32e117c0663337770b39bfc0bf978022dec0eafea220cf27c83e86f9f63f5c3038f6d99
-  data.tar.gz: 0b6d24c285a668c5dde3a90168d542c60b7b8008f20a75d39579c058448e8dd31482f23bda5fa770c25909736b43804cd03a591f7813345a0aabeccc75ad7b26
+  metadata.gz: 5249f3a12786557b868a420b07778c5e8ce17feefc72a8e5e093fcca6c6390caf8113eebd8746c6e3dfb7150b80547c6bdaf38584004f760e2fea6b743c1c060
+  data.tar.gz: 2453b54cb4e35ffb47d60dec50417c9d3869f9a8ae10594ca19c2c9dc5c1462254b5792ecf7d0f7e4d03520d0242e72d9e3728daf92135e20509509eeb95867d

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-05-17
+
+### Added
+
+- **`logger` setting.** When set to a `Logger`-compatible instance, Faraday's built-in logger middleware is attached to the connection and logs HTTP request/response lines and headers. Unset by default — no overhead when not in use. The standard auth-bearing headers (`Authorization`, `Proxy-Authorization`, `Cookie`, `Set-Cookie`) are always filtered to `[FILTERED]`; consumer gems are responsible for redacting domain-specific secrets in non-standard headers or response bodies (see README "Redacting domain-specific secrets").
+- **`log_bodies` setting** (default `false`). Opt-in toggle for logging request/response bodies. Off by default because bodies often carry domain-specific secrets that RestEasy cannot recognize.
+
 ## [1.1.2] - 2026-05-15
 
 ### Changed
@@ -48,7 +55,8 @@
 
 Initial release.
 
-[Unreleased]: https://github.com/accodeing/rest-easy/compare/v1.1.2...HEAD
+[Unreleased]: https://github.com/accodeing/rest-easy/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/accodeing/rest-easy/compare/v1.1.2...v1.2.0
 [1.1.2]: https://github.com/accodeing/rest-easy/compare/v1.1.1...v1.1.2
 [1.1.1]: https://github.com/accodeing/rest-easy/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/accodeing/rest-easy/compare/v1.0.0...v1.1.0

data/README.md

@@ -92,17 +92,100 @@ end
 
 ### Available settings
 
-| Setting                          | Default                    | Description                                       |
-|----------------------------------|----------------------------|---------------------------------------------------|
-| `base_url`                       | `"https://example.com"`    | Base URL for all requests                         |
-| `max_retries`                    | `3`                        | Retry count on request failure                    |
-| `authentication`                 | `Auth::Null.new`           | Authentication strategy                           |
-| `conversions.json_attributes`    | `:PascalCase`              | Naming convention for JSON response/request fields|
-| `conversions.query_parameters`   | `nil` (no transformation)  | Naming convention for query parameter keys        |
+| Setting                          | Default                    | Description                                                                                |
+|----------------------------------|----------------------------|--------------------------------------------------------------------------------------------|
+| `authentication`                 | `Auth::Null.new`           | Authentication strategy                                                                    |
+| `base_url`                       | `"https://example.com"`    | Base URL for all requests                                                                  |
+| `conversions.json_attributes`    | `:PascalCase`              | Naming convention for JSON response/request fields                                         |
+| `conversions.query_parameters`   | `nil` (no transformation)  | Naming convention for query parameter keys                                                 |
+| `log_bodies`                     | `false`                    | When `true`, request/response bodies are logged. Off by default to avoid leaking domain secrets |
+| `logger`                         | `nil`                      | When set, attaches Faraday's logger middleware and writes HTTP request/response details to it |
+| `max_retries`                    | `3`                        | Retry count on request failure                                                             |
+
+### Logging HTTP traffic
+
+Set `logger` to any `Logger`-compatible instance to log HTTP request and response details. The middleware is Faraday's built-in `Faraday::Response::Logger` and is only attached when the setting is non-nil — no overhead when unset.
+
+```ruby
+module Acme
+  extend RestEasy
+
+  configure do |config|
+    config.logger = Logger.new($stdout)
+  end
+end
+```
+
+By default, RestEasy logs request/response **lines and headers only**, with the following standard headers always filtered to `[FILTERED]`:
+
+- `Authorization`
+- `Proxy-Authorization`
+- `Cookie`
+- `Set-Cookie`
+
+Request and response **bodies are not logged by default**, because bodies frequently carry API-specific secrets (OAuth token responses, signed payloads, PII) that RestEasy has no way to recognize.
+
+> **Note:** The Faraday connection is built lazily on the first request and cached for the lifetime of the process. Changes to `logger` or `log_bodies` after the first request take effect only after restart.
+
+#### Logging request/response bodies
+
+If your API's bodies are safe to log — or you've added domain-specific scrubbing (see below) — opt in:
+
+```ruby
+module Acme
+  extend RestEasy
+
+  configure do |config|
+    config.logger     = Logger.new($stdout)
+    config.log_bodies = true
+  end
+end
+```
+
+#### Redacting domain-specific secrets
+
+RestEasy only knows about HTTP-standard auth headers. If your API returns secrets in response bodies (e.g. an access-token endpoint), or uses non-standard headers like `X-Acme-Api-Key`, your consumer gem is responsible for scrubbing them. The simplest pattern is to wrap the `Logger` instance before handing it to RestEasy — sketched here as a `SimpleDelegator`:
+
+```ruby
+# Sketch — wrap the Logger in your gem so it scrubs your
+# domain secrets out of each line before it's written.
+
+class RedactingLogger < SimpleDelegator
+  # ...your scrubbing logic, applied to each log message...
+end
+
+module Acme
+  extend RestEasy
+
+  configure do |config|
+    config.logger     = RedactingLogger.new(Logger.new($stdout))
+    config.log_bodies = true
+  end
+end
+```
+
+#### Exposing a debug switch in your consumer gem
+
+RestEasy does not read any environment variable itself — that decision belongs to the gem that wraps it. If you want consumers of your gem to flip logging on without editing code, expose your own env var and wire it to `config.logger`:
+
+```ruby
+module Acme
+  extend RestEasy
+
+  configure do |config|
+    if ENV["ACME_DEBUG"]
+      config.logger     = RedactingLogger.new(Logger.new($stdout))
+      config.log_bodies = true
+    end
+  end
+end
+```
+
+Now `ACME_DEBUG=1 bundle exec ...` turns on wire logging — with Acme-aware scrubbing — without any code changes in the consuming application.
 
 ### Faraday middleware
 
-Configure the underlying Faraday connection with a `connection` block:
+For middleware beyond the built-in logger, configure the underlying Faraday connection with a `connection` block:
 
 ```ruby
 module Acme

data/lib/rest_easy/settings.rb

@@ -6,14 +6,16 @@ module RestEasy
   class Settings
     extend Dry::Configurable
 
+    setting :attribute_convention # deprecated — propagated to conversions.json_attributes in configure
+    setting :authentication, default: Auth::Null.new, reader: true
     setting :base_url, default: "https://example.com", reader: true
+    setting :log_bodies, default: false, reader: true
+    setting :logger, reader: true
     setting :max_retries, default: 3, reader: true
-    setting :authentication, default: Auth::Null.new, reader: true
-    setting :attribute_convention # deprecated — propagated to conversions.json_attributes in configure
 
     setting :conversions do
-      setting :query_parameters, default: nil, reader: true
       setting :json_attributes, default: Conventions::DEFAULT, reader: true
+      setting :query_parameters, default: nil, reader: true
     end
   end
 end

data/lib/rest_easy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RestEasy
-  VERSION = "1.1.2"
+  VERSION = "1.2.0"
 end

data/lib/rest_easy.rb

@@ -66,6 +66,9 @@ module RestEasy
   # ── Module extension (ClassMethods) ──────────────────────────────────
 
   module ClassMethods
+    STANDARD_AUTH_HEADERS = %w[Authorization Proxy-Authorization Cookie Set-Cookie].freeze
+    private_constant :STANDARD_AUTH_HEADERS
+
     def config
       self::Settings.config
     end
@@ -107,6 +110,16 @@ module RestEasy
       @faraday_connection ||= Faraday.new(url: config.base_url) do |f|
         f.request :json
         f.response :json
+        if config.logger
+          # Faraday's logger emits headers as `Name: "value"` — the filters
+          # depend on that format. If the format changes, redaction silently
+          # breaks; the integration specs catch the common case.
+          f.response :logger, config.logger, bodies: config.log_bodies do |l|
+            STANDARD_AUTH_HEADERS.each do |name|
+              l.filter(/(#{Regexp.escape(name)}:\s*")[^"]+/i, '\1[FILTERED]')
+            end
+          end
+        end
         @connection_block&.call(f)
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rest-easy
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.2.0
 platform: ruby
 authors:
 - Jonas Schubert Erlandsson
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-15 00:00:00.000000000 Z
+date: 2026-05-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-types