resteze 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4be8c1254251ae0e6d2fb624d9ebbfff5ddc309d903ffe1ded346d816b4a3cf0
-  data.tar.gz: b49908651339547627e4a46b13944d9029ce06bea3a1a189fc63538b7fb54cb2
+  metadata.gz: 55dfa62b10235fa805a820a3c8a11fc01126141941c3dce30b54b62b484a2e18
+  data.tar.gz: 7b69653ef28303f319cb56b7bf94ff59cf09291aa3a9911d52158b71df026bb2
 SHA512:
-  metadata.gz: d318326b40178c6bbcfb949908e37742d56c74c1e366ec4522c217bc5886b21f2884536b94d814f17e1c2ab7262a5820df0b43ed481302f5b6bcc6071af2e64d
-  data.tar.gz: 62db4cc4bc2edf0761b258ef64b7e4edf42faea613099c3ab7091434c0d4fea100bcca33604e910e0943c07a242f807f6165f06d9e94195aba10f9deb6381d47
+  metadata.gz: ab516cd48e257b13bd1996e0bfd0f5c91a0fceb60e61c6883034f5ff898c560ce615a899f7759ef927e2a2dbd2652ec4d007eba05c235c0ba653b8b230b0a85c
+  data.tar.gz: df4fd41077a6555453a95d0786a05f378d1f466e78a47913d563605801d53c054741881e7da2c3dfc6923b23563d7fe8701fdd2d8c71aead5d269d74f7075cb1

data/CLAUDE.md

@@ -0,0 +1,74 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## About
+
+Resteze is a Ruby gem that provides a framework for building REST API client libraries. Consumers `include Resteze` in their own module and get a fully namespaced set of classes (Client, ApiResource, ListObject, Error hierarchy, etc.) that they extend to define resources.
+
+## Commands
+
+```bash
+bundle exec rake          # Run tests + RuboCop (default task)
+bundle exec rake test     # Run tests only
+bundle exec rake rubocop  # Lint only
+bundle exec ruby -Ilib:test test/resteze/client_test.rb  # Run a single test file
+bundle exec guard         # Watch mode: re-runs tests on file changes
+COVERAGE=1 bundle exec rake test  # Run tests with coverage report
+```
+
+## Architecture
+
+### The `include Resteze` pattern
+
+When a module does `include Resteze`, the `included` block in `lib/resteze.rb` fires and sets up a full set of namespaced constants inside the consuming module:
+
+- `MyApi::Object` — base Hashie::Trash subclass for all resource objects
+- `MyApi::Client` — Faraday-based HTTP client (thread-safe via `Thread.current`)
+- `MyApi::ApiResource` — extends Object with `retrieve`, `resource_path`, `refresh`
+- `MyApi::ListObject` — Hashie::Array subclass for paginated list responses
+- `MyApi::Middleware::RaiseError` — Faraday middleware for HTTP error handling
+- `MyApi::List`, `MyApi::Save` — mixins consumers include on specific resources
+- `MyApi::Error` and all subclasses — namespaced error hierarchy
+
+This means each consuming gem gets its own isolated class hierarchy; errors from one API won't be caught by rescue clauses for another.
+
+### `ApiModule` — the ancestry resolver
+
+`Resteze::ApiModule` is mixed into every class in the hierarchy. Its `api_module` class method walks the constant name ancestry (`Widget` → `MyApi::Widget` → `MyApi`) to find the module that `include`d Resteze. This is what allows `MyApi::Widget.request(...)` to automatically use `MyApi::Client` rather than needing any explicit wiring.
+
+### Request flow
+
+```
+MyApi::Widget.retrieve(id)
+  → ApiResource#refresh
+  → Request.request(:get, path)
+  → MyApi::Client.active_client.execute_request(method, path)
+  → Faraday connection (thread-local default_client)
+  → Middleware::RaiseError
+  → Response.from_faraday_response
+  → Object#initialize_from(resp.data)
+```
+
+GET/HEAD/DELETE params become query strings; all other methods send a JSON body.
+
+### Object / property system
+
+`Resteze::Object` extends `Hashie::Trash`, which provides typed `property` declarations with optional transforms, defaults, and translations (key remapping). Unknown keys that don't match a declared property are stored in `@property_bag` rather than raising, allowing forward compatibility with API changes.
+
+`object_key` (default: `nil`) lets a resource unwrap a top-level envelope key from API responses. `list_key` (default: `:data`) tells `ListObject` which key holds the array of items.
+
+### Mixins: List and Save
+
+- **`Resteze::List`** adds a class-level `.list(params:)` that issues a GET to `resource_path` and constructs a `ListObject`.
+- **`Resteze::Save`** adds `#save` which issues POST (new) or PUT (persisted) based on `persisted?` (presence of `id`).
+
+Both are opt-in; include them on a resource class when needed.
+
+### Testing helpers
+
+`lib/resteze/testing/` provides helpers for consumers testing their own gem:
+- `Resteze::Testing::Minitest` — `has_property` assertion helper and `assert_config_property`
+- `Resteze::Testing::RSpec` — equivalent helpers for RSpec
+
+The gem's own tests use **Minitest** with **WebMock** (net connections disabled globally). The test helper defines `AcmeApi` as a reference implementation of a consuming module.

data/README.md

@@ -78,6 +78,37 @@ end
 
 You can define additional resources, customize paths, and add methods as needed. Resteze handles requests, responses, and error management for you, so you can focus on your API's business logic.
 
+### Instrumentation
+
+Resteze fires an `ActiveSupport::Notifications` event for every HTTP request, making it easy to track performance metrics in host applications.
+
+The event name is `request.<api_module_key>`, where the key is derived from your module name (e.g. `MyCoolApi` → `"request.my_cool_api"`).
+
+```ruby
+ActiveSupport::Notifications.subscribe("request.my_cool_api") do |event|
+  event.duration            # elapsed time in milliseconds
+  event.payload[:method]    # :get, :post, :put, etc.
+  event.payload[:path]      # "/widgets/123"
+  event.payload[:status]    # 200, 404, etc.
+  event.payload[:request_id] # value of the Request-Id response header
+  event.payload[:api_module] # "MyCoolApi"
+  event.payload[:exception]  # [ExceptionClass, message] if the request raised
+end
+```
+
+The event fires on every request — including those that raise errors — so you can feed `event.duration` directly into a histogram for p95 and other percentile calculations. Because `ActiveSupport::Notifications` short-circuits when there are no subscribers, there is no overhead when instrumentation is not in use.
+
+To override the event name key for a module:
+
+```ruby
+module MyCoolApi
+  include Resteze
+
+  INSTRUMENTATION_KEY = "cool_api"
+end
+# => subscribes to "request.cool_api"
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/rwx-services/resteze.