resteze 0.4.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55dfa62b10235fa805a820a3c8a11fc01126141941c3dce30b54b62b484a2e18
-  data.tar.gz: 7b69653ef28303f319cb56b7bf94ff59cf09291aa3a9911d52158b71df026bb2
+  metadata.gz: 7bf2fb41e39a2e7383f9977bca343aaeba1ae30be302ba13acb3c3a63dc85bea
+  data.tar.gz: c88e04e781ea1c857ab040d0873333e13ea810dd91f8add7690e5c0539af7090
 SHA512:
-  metadata.gz: ab516cd48e257b13bd1996e0bfd0f5c91a0fceb60e61c6883034f5ff898c560ce615a899f7759ef927e2a2dbd2652ec4d007eba05c235c0ba653b8b230b0a85c
-  data.tar.gz: df4fd41077a6555453a95d0786a05f378d1f466e78a47913d563605801d53c054741881e7da2c3dfc6923b23563d7fe8701fdd2d8c71aead5d269d74f7075cb1
+  metadata.gz: 3f44dec43d6bd1838ac8962e30f28f175529cac474062659ab90847262f714faaafbce4e6cf5c7cffdc8e1ab085cf12c4aff591bf13ad3d0a6b43639299bac0a
+  data.tar.gz: a0c4429efa6a62b1060e150625c7c1e302ba90d19b471005a7ce42c222ad2e8911be89f208d0e6e581140095351cb3a613669a5c4f2165836e7edbe1aa2ff984

data/.rubocop.yml

@@ -17,6 +17,7 @@ Metrics/ParameterLists:
 Metrics/AbcSize:
   Exclude:
     - lib/resteze/response.rb
+    - test/resteze/authenticator/mtls_test.rb # building a self-signed certificate
 
 Metrics/BlockLength:
   Exclude:
@@ -26,6 +27,7 @@ Metrics/BlockLength:
 Metrics/ClassLength:
   Exclude:
     - lib/resteze/client.rb
+    - lib/resteze/rate_limiter.rb
     - test/**/*
 
 Metrics/MethodLength:

data/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.0.0]
+
+The release developed as 0.5.0, renumbered: it is the first stable release, and the error hierarchy change under **Changed** breaks code written against the Faraday-derived classes.
+
+### Added
+
+- `action` routing DSL on `ApiResource`: declare custom collection and member actions, re-route `retrieve`, `list`, `create` and `update`, and set API-wide defaults with module-level `action` / `action_defaults`.
+- `Result`, a loose Mash returned by custom actions by default; `returns:` selects a resource, a list, or any `Object` subclass instead.
+- `retrieve_resource_path`, `save_params` and `id_param` override points.
+- `has_action` assertion helper for Minitest and RSpec.
+- `MyApi::Authenticator`, a per-module subclass of `Resteze::Authenticator` through which a client describes how its API authenticates, with `authenticate_with` (and `rate_limit_with`) module macros so choosing a scheme is one line on the module. The client calls one thread-shared instance (`MyApi.authenticator`) at three points: `connection_options` when the Faraday connection is built, `apply(request)` before every request, and `refresh?(error, attempt)` after a 401 or 403 to send the request once more with a renewed credential. A scheme is a `Resteze::Authenticator::Strategy` subclass; its `DEFAULTS` name the module settings it expects, which `authenticate_with` declares, so an initializer fills them through `configure`. A setting still `nil` at request time raises an `ArgumentError` naming it; `missing_settings` lists the required ones (a strategy's `OPTIONAL` settings are left out) for a boot-time check. `Client#execute_request` gains `query:`, parameters that always go in the query string whatever the method, with resources in it reduced to their ids like `params:`. Credentials are masked in the `DEBUG` log: each strategy names where it put its credential through `sensitive_keys`, the client writes `[REDACTED]` there in the logged copy, and `Authorization` and `Proxy-Authorization` are always masked, including when an overridden `request_headers` adds them.
+- `:api_key` authentication scheme: the module's `api_key` in a header (default `X-Api-Key`) or, with `query:`, in the query string on every request.
+- `:basic` authentication scheme: HTTP Basic from the module's `username` and `password`. A username containing `:` raises an `ArgumentError`, since the server would split it there.
+- `:bearer` authentication scheme: `Authorization: Bearer <api_key>`, with `scheme:` for another prefix and `token:` for another setting or a callable.
+- `:mtls` authentication scheme: a client certificate on the TLS connection from the module's `client_cert` and `client_key` (PEM or path), with the optional `client_key_passphrase` and `ca_file` settings and `verify:`, which logs a warning when turned off.
+- `Response#success?`, true for any 2xx status. `Response#ok?` is unchanged and means exactly 200, so a `201 Created` answers `success?` but not `ok?`.
+- `MyApi::RateLimitError`, raised for a 429, with `#retry_after` read from the `Retry-After` header (delay-seconds or HTTP-date).
+- `Error.from_faraday` builds a namespaced error from a Faraday error, keeping its status, headers, body, parsed `json_body` and response; `Error#header` looks a header up case-insensitively.
+- `Response.body_error` hook for APIs that report failures inside a 2xx body. Override it on `MyApi::Response` to return an error to raise; `Error.from_response` builds one from the parsed response.
+- `MyApi::RateLimiter`, a per-module subclass of `Resteze::RateLimiter` through which a client describes and responds to its API's rate limiting. The client calls one thread-shared instance (`MyApi.rate_limiter`) at fixed points: `before_request`, `track` after every response or error, `retry?` and `retry_after` after a 429, and `rate_limit` when `Response#rate_limit` or `Error#rate_limit` is read. Every method is a no-op by default; Resteze assumes nothing about the mechanics. State lives in a mutex-guarded hash (`state`, `update_state`, `synchronize`) so subclasses need not manage threads.
+- Four built-in strategies, chosen with `strategy` in the module's `RateLimiter`: `:fixed_window` (with optional `headers: true` to follow the API's `X-RateLimit-*` headers, as Braze and JD Power report), `:sliding_window`, `:token_bucket` and `:leaky_bucket`. A strategy makes `before_request` wait until the request fits and `rate_limit` return a `Resteze::RateLimit` of its current view. `on_wait: :raise` raises `RateLimitError` with the wait in `retry_after` instead of sleeping, for callers such as background jobs that reschedule themselves, and applies to retry waits too. `max_wait:` (default one hour) clamps every wait, so a bad `Retry-After` or reset header cannot park a thread indefinitely or crash on a non-finite sleep. Custom algorithms subclass `Resteze::RateLimiter::Strategy`.
+- `RateLimitError#retry_after` reads the HTTP `Retry-After` header (delay-seconds or HTTP-date); `Resteze::RateLimit.from_headers` is a helper for the three-header shape.
+- A `rate_limit.wait.<key>` notification fires whenever the `RateLimiter` makes a request wait, before sending or before a retry, with the wait's `seconds`, `reason`, `attempt` and `on_wait` in the payload and the time actually waited as its duration; under `on_wait: :raise` it carries the exception instead. The `request.<key>` payload gains `rate_limit`, the limiter's view of the quota, when it reports one.
+
+### Changed
+
+- `Response.parse_body` returns a blank body unparsed instead of raising `JSON::ParserError`, so a `200 OK` with an empty body no longer fails.
+- `include Resteze` now defines `MyApi::Result`, so `Result` joins `Object`, `Client`, `Response` and the other reserved constant names inside an API module.
+- The `RaiseError` middleware now maps every Faraday error onto the API module's hierarchy: 401/403 to `AuthenticationError`, 429 to `RateLimitError`, 400 to `InvalidRequestError`, other 4xx and all 5xx to `ApiError`, and connection failures, timeouts and SSL errors to `ApiConnectionError`. Previously only 404, 409 and 422 were namespaced and everything else surfaced as a raw Faraday error that `rescue MyApi::Error` could not catch. The Faraday error is kept as `cause`.
+- **Breaking:** `MyApi::ResourceNotFound`, `MyApi::ConflictError` and `MyApi::UnprocessableEntityError` are now subclasses of `MyApi::Error` like every other error, so `rescue MyApi::Error` catches a 404, 409 or 422. They no longer descend from the Faraday classes; a `rescue Faraday::ResourceNotFound` must become `rescue MyApi::ResourceNotFound`. Their Faraday-style readers (`response_status`, `response_headers`, `response_body`, `response`) still work, and are now available on every `MyApi::Error`.
+
+### Fixed
+
+- `assert_config_property` (Minitest and RSpec) now assigns the given value before asserting it reads back, then restores the original. It previously only compared the current value.
+- The `request.<key>` instrumentation payload now includes `status` and `request_id` when the request raises an error that carries an HTTP response. Previously both were missing for every 4xx and 5xx.
+- `MyApi::ResourceNotFound`, `MyApi::UnprocessableEntityError` and `MyApi::ConflictError` now keep the Faraday response (`e.response`, `e.response_status`, `e.response_body`). The middleware previously dropped it when re-raising under the namespaced class.
+- `MyApi::ApiError`, `ApiConnectionError`, `AuthenticationError` and `InvalidRequestError` are now real subclasses of `MyApi::Error`, defined on the module. `include Resteze` meant to create them but its `const_defined?` guard found the `Resteze::` originals through the included module and skipped every one, so `MyApi::ApiError` was literally `Resteze::ApiError`, shared by every API and not caught by `rescue MyApi::Error`.
+
 ## [0.3.1]
 
 ### Added

data/CLAUDE.md

@@ -27,9 +27,12 @@ When a module does `include Resteze`, the `included` block in `lib/resteze.rb` f
 - `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::Result` — Hashie::Mash subclass returned by custom actions that declare no `returns:`
 - `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
+- `MyApi::Authenticator` — per-module `Resteze::Authenticator` subclass; `MyApi.authenticator` is the thread-shared instance. `authenticate_with <name or Strategy class>, **options` on the module (or `strategy` inside the class; combinable) adds a `Resteze::Authenticator::Strategy` subclass; built-in schemes call `Strategy.register(:name, self)` (`lib/resteze/authenticator/`), and a gem can register its own. A strategy's `DEFAULTS` name the module settings it expects, which `authenticate_with` declares. `Resteze::Authenticating` is prepended on `Client` to call `apply(request)` before each request and retry once when `refresh?` says so; `connection_options` feed `Client.default_connection`
+- `MyApi::RateLimiter` — per-module `Resteze::RateLimiter` subclass; `MyApi.rate_limiter` is the thread-shared instance the client consults (`before_request`, `track`, `retry?`, `retry_after`, `rate_limit`). `strategy :fixed_window | :sliding_window | :token_bucket | :leaky_bucket, **options` picks a built-in algorithm (`lib/resteze/rate_limiter/`); `Resteze::RateLimiting` is prepended outermost on `Client` to drive it and retry
 
 This means each consuming gem gets its own isolated class hierarchy; errors from one API won't be caught by rescue clauses for another.
 
@@ -65,6 +68,12 @@ GET/HEAD/DELETE params become query strings; all other methods send a JSON body.
 
 Both are opt-in; include them on a resource class when needed.
 
+### Actions: the routing DSL
+
+`Resteze::Actions` (mixed into `ApiResource`) provides a Rails-style `action` DSL. `action :track, method: :post` on a resource generates `Klass.track(**params)`; `on: :member` generates an instance method plus `Klass.name(id, **params)`. Four names are reserved (`retrieve`, `list`, `create`, `update`): they are pre-registered with REST defaults, never generate methods, and can be re-routed by redeclaring them (`action :retrieve, path: "details", id: :param`).
+
+Resolution is lazy. `Klass.actions` rebuilds a frozen hash of `Resteze::Action` value objects on every call by merging, lowest priority first: `Action::BUILT_IN` → the module's `action_defaults` → the module's `action` declarations → ancestor classes' `declared_actions` → the class's own. `refresh`, `list` and `save` consult the registry for their route (`retrieve_resource_path`, `list_resource_path`, `save_resource_path`, `save_params`) but keep their own bodies. Custom actions return `MyApi::Result` (a `Hashie::Mash`) unless `returns:` names `:self`, `:list` or an `Object` subclass. Declaration-time validation lives in `Resteze::Actions::Validation`. See `docs/ACTIONS.md`.
+
 ### Testing helpers
 
 `lib/resteze/testing/` provides helpers for consumers testing their own gem:

data/README.md

@@ -50,11 +50,16 @@ require 'resteze'
 module MyCoolApi
   include Resteze
 
-  # Configure your API client
+  # Say how the API authenticates: :api_key, :basic, :bearer or :mtls.
+  # Each expects its credential in a conventional setting; :bearer
+  # expects MyCoolApi.api_key, which this line declares.
+  authenticate_with :bearer
+
+  # Configure your API client (an initializer is the usual place)
   configure do |config|
     config.api_base = 'https://api.example.com/'
-    config.api_key = 'your-api-key'
-    config.logger = Logger.new($stdout)
+    config.api_key  = ENV['MY_COOL_API_KEY']
+    config.logger   = Logger.new($stdout)
   end
 
   # Define a resource
@@ -78,6 +83,20 @@ 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.
 
+### Actions
+
+Endpoints that do not fit the REST pattern are declared with the `action` DSL, and the built-in `retrieve`, `list`, `create` and `update` can be re-routed the same way. See [docs/ACTIONS.md](docs/ACTIONS.md).
+
+```ruby
+module MyCoolApi
+  class Widget < ApiResource
+    action :search,   method: :get                 # Widget.search(q: "x") => GET /widgets/search?q=x
+    action :activate, method: :post, on: :member   # widget.activate       => POST /widgets/:id/activate
+    action :retrieve, path: "details", id: :param  # Widget.retrieve(id)   => GET /widgets/details?widget_id=...
+  end
+end
+```
+
 ### Instrumentation
 
 Resteze fires an `ActiveSupport::Notifications` event for every HTTP request, making it easy to track performance metrics in host applications.
@@ -93,10 +112,23 @@ ActiveSupport::Notifications.subscribe("request.my_cool_api") do |event|
   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
+  event.payload[:rate_limit] # { limit:, remaining:, reset: } when the module's RateLimiter reports one
+end
+```
+
+A second event, `rate_limit.<key>` prefixed as `rate_limit.wait.<key>`, fires whenever the module's `RateLimiter` makes a request wait, before sending or before a retry. Its `duration` is the time actually spent waiting; its payload carries `seconds` (the wait asked for), `reason` (`:throttle` or `:retry`), `attempt` for a retry, and `on_wait`. Under `on_wait: :raise` the event still fires and carries the raised exception, so refused requests are visible too:
+
+```ruby
+ActiveSupport::Notifications.subscribe("rate_limit.wait.my_cool_api") do |event|
+  event.duration            # milliseconds actually waited
+  event.payload[:seconds]   # 30.0
+  event.payload[:reason]    # :throttle or :retry
+  event.payload[:attempt]   # 1, 2, … for :retry
+  event.payload[:exception] # set when on_wait: :raise refused the request instead
 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.
+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. When a request raises an error that carries an HTTP response (a `Faraday::Error` or a `Resteze::Error` built with `http_status:`), `status` and `request_id` are populated from that response, so a 404 or 429 is bucketed just like a 200. Connection failures and timeouts have no status and leave those keys unset. 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:
 
@@ -109,6 +141,15 @@ end
 # => subscribes to "request.cool_api"
 ```
 
+## Documentation
+
+- [API](docs/API.md) — core concepts, resource definition, requests and responses
+- [Actions](docs/ACTIONS.md) — the `action` routing DSL for custom and re-routed endpoints
+- [Advanced Usage](docs/ADVANCED_USAGE.md) — lists, saves, pagination, batching and caching patterns
+- [Configuration](docs/CONFIGURATION.md) — module configuration, connections and middleware
+- [Error Handling](docs/ERROR_HANDLING.md) — the namespaced error hierarchy and recovery
+- [Testing](docs/TESTING.md) — Minitest and RSpec helpers, WebMock and VCR
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/rwx-services/resteze.

data/docs/ACTIONS.md

@@ -0,0 +1,329 @@
+# Actions
+
+Resteze assumes a textbook REST surface by default: `GET /widgets`,
+`GET /widgets/:id`, `POST /widgets`, `PUT /widgets/:id`. Many APIs do not look
+like that. Some address endpoints by action name instead of by id in the path
+(`GET /campaigns/list`, `GET /campaigns/details?campaign_id=…`,
+`POST /users/track`), and almost every API has a few endpoints that fit no
+pattern at all.
+
+The `action` DSL, modeled on the Rails routing DSL for custom resource actions,
+covers both. A resource declares the actions it supports; each action resolves to
+an HTTP method, a path and a return type. The built-in `retrieve`, `list`,
+`create` and `update` are ordinary actions with REST defaults, so re-routing one
+uses the same vocabulary as adding a new one.
+
+**A resource that declares nothing behaves exactly as it did before.**
+
+## Table of Contents
+- [Declaring custom actions](#declaring-custom-actions)
+- [Collection and member actions](#collection-and-member-actions)
+- [Re-routing the built-in actions](#re-routing-the-built-in-actions)
+- [API-wide defaults](#api-wide-defaults)
+- [Lookup order](#lookup-order)
+- [Return values](#return-values)
+- [Hooks](#hooks)
+- [Introspection](#introspection)
+- [Testing](#testing)
+- [The escape hatch](#the-escape-hatch)
+
+## Declaring custom actions
+
+```ruby
+module MyApi
+  include Resteze
+
+  class User < ApiResource
+    property :external_id
+
+    action :track,      method: :post
+    action :identify,   method: :post
+    action :export_ids, method: :post, path: "export/ids"
+  end
+end
+
+MyApi::User.track(events: [{ external_id: "u1", name: "rented_movie" }])
+# => POST /users/track with a JSON body
+
+MyApi::User.export_ids(external_ids: ["u1"])
+# => POST /users/export/ids
+```
+
+Each declaration generates a method named after the action. Params are passed as
+keyword arguments and sent the way the client always sends them: GET, HEAD and
+DELETE put them in the query string; everything else sends a JSON body.
+
+| Option | Values | Default | Meaning |
+|---|---|---|---|
+| `method:` | any HTTP verb symbol | required | HTTP method |
+| `on:` | `:collection`, `:member` | `:collection` | Whether the action addresses the collection or one record |
+| `path:` | string | the action name | Segment appended after the resource slug (and after the id for `id: :path`). May contain `/`; each part is URL-escaped. `nil` means no segment |
+| `id:` | `:path`, `:param` | `:path` | Member actions only. Whether the id goes in the path or is sent as a param |
+| `id_param:` | symbol | singular slug + `_id` | Member actions with `id: :param`. The param key that carries the id |
+| `returns:` | `nil`, `:self`, `:list`, an `Object` subclass | `nil` | What the generated method returns; see [Return values](#return-values) |
+| `as:` | symbol | the action name | The Ruby method name to generate; use it when the action name collides with an existing method |
+
+Unknown options raise `ArgumentError` when the class is loaded, as does `id:` on a
+collection action, `returns: :list` on a class that does not include `List`, and
+an action whose method name already exists on the class:
+
+```ruby
+action :send, method: :post               # ArgumentError: Object#send exists; pass as:
+action :send, method: :post, as: :deliver # MyApi::Message.deliver(...)
+action :delete, method: :post, on: :member, as: :destroy
+```
+
+## Collection and member actions
+
+A collection action generates a class method. A member action generates an
+instance method, plus a class method that takes the id first, mirroring
+`retrieve(id)`:
+
+```ruby
+class Campaign < ApiResource
+  property :id
+  property :name
+
+  action :data_series, method: :get                       # collection
+  action :duplicate,   method: :post, on: :member         # member
+end
+
+MyApi::Campaign.data_series(length: 7)    # GET  /campaigns/data_series?length=7
+campaign.duplicate(name: "copy")          # POST /campaigns/abc/duplicate
+MyApi::Campaign.duplicate("abc", name: "copy")   # same request
+```
+
+Where the id goes is controlled by `id:`:
+
+| `id:` | Request |
+|---|---|
+| `:path` (default) | `POST /campaigns/abc/duplicate` |
+| `:param` | `POST /campaigns/duplicate` with `campaign_id: "abc"` merged into the body |
+
+With `id: :param`, the id is merged in under `id_param` (default `campaign_id`
+for the slug `campaigns`). A param you pass with the same key wins. Calling a
+member action on a record with a blank id raises `MyApi::InvalidRequestError`.
+
+## Re-routing the built-in actions
+
+Four names are reserved and pre-registered with REST defaults:
+
+| Name | Method | Scope | Path | Id |
+|---|---|---|---|---|
+| `retrieve` | GET | member | none | `:path` |
+| `list` | GET | collection | none | n/a |
+| `create` | POST | collection | none | n/a |
+| `update` | PUT | member | none | `:path` |
+
+Redeclaring one replaces its route. Options you leave out fall through to the
+next level of the [lookup order](#lookup-order), so changing just the path is one
+line. The existing `retrieve`, `list` and `save` methods keep their behavior and
+only pick up the new route; no new method is generated for a reserved name.
+
+```ruby
+class ContentBlock < ApiResource
+  include List
+  include Save
+
+  property :id
+
+  action :retrieve, path: "info",   id: :param   # GET  /content_blocks/info?content_block_id=…
+  action :list,     path: "list"                 # GET  /content_blocks/list
+  action :create,   path: "create"               # POST /content_blocks/create
+  action :update,   path: "update", method: :post, id: :param
+  # => POST /content_blocks/update with content_block_id in the body
+end
+```
+
+## API-wide defaults
+
+When a whole API follows one convention, declare it once on the module. The same
+`action` call is available there and supplies defaults for every resource;
+`action_defaults` sets the lowest-priority defaults for every action at once.
+
+```ruby
+module MyApi
+  include Resteze
+
+  action_defaults id: :param          # all member actions carry the id as a param
+
+  action :retrieve, path: "details"
+  action :list,     path: "list"
+  action :create,   path: "create"
+  action :update,   path: "update", method: :post
+end
+
+class Campaign < ApiResource
+  include List
+  property :id
+end
+
+MyApi::Campaign.retrieve("abc")   # GET /campaigns/details?campaign_id=abc
+MyApi::Campaign.list              # GET /campaigns/list
+
+class ContentBlock < ApiResource
+  action :retrieve, path: "info"  # the one outlier
+end
+```
+
+`action_defaults` accepts `method:`, `id:` and `id_param:`. A module-level
+declaration of a custom name supplies defaults only; it does not generate a method
+on any resource. A resource that wants the action declares it, with or without
+options:
+
+```ruby
+module MyApi
+  action :export, method: :post
+end
+
+class User < ApiResource
+  action :export      # POST /users/export, method supplied by the module
+end
+```
+
+Routing options (`method:`, `path:`, `id:`, `id_param:`, `returns:`) are resolved
+when an action is used, not when it is declared, so module-level calls made in a
+Rails initializer after resource classes are loaded still take effect. The two
+options that shape the generated method, `on:` and `as:`, are read when the
+resource declares the action, so set them at module level before the resource
+classes load, or on the resource itself.
+
+## Lookup order
+
+An action's options are merged lowest priority first:
+
+1. REST built-in defaults, for the four reserved names.
+2. The module's `action_defaults`.
+3. The module's `action` declaration for that name.
+4. Each ancestor resource class's declaration, farthest first.
+5. The resource's own declaration.
+
+Subclasses inherit every action of their parent and can override individual
+options. The resource slug is still derived per class, so a subclass routes under
+its own slug unless it overrides `resource_slug`.
+
+## Return values
+
+| `returns:` | Result |
+|---|---|
+| omitted | `MyApi::Result`, a loose [Hashie::Mash](https://github.com/hashie/hashie#mash) of the response body |
+| `:self` | one resource built from a Hash body, or an Array of resources from an Array body |
+| `:list` | a `MyApi::ListObject` built with the resource's `list_key` |
+| an `Object` subclass | as `:self`, with that class |
+
+```ruby
+class User < ApiResource
+  action :track, method: :post
+end
+
+result = MyApi::User.track(events: [...])
+result.message                    # => "success"
+result.events_processed           # => 2
+result.http_response.http_status  # => 200
+
+class TrackResult < Object
+  property :message
+  property :events_processed
+end
+
+class User < ApiResource
+  action :track, method: :post, returns: TrackResult
+end
+```
+
+`MyApi::Result` is created by `include Resteze` alongside `Object`, `Client`,
+`Response` and the other namespaced classes, so the name `Result` is reserved
+inside your API module from 1.0.0 on.
+
+`Result` never raises on body shape. A `204 No Content`, an empty body, or a
+non-JSON body with a non-JSON content type yields an empty `Result`; the raw
+parsed body is always at `result.http_response.data`.
+
+`:self` on a member action builds a **new** instance and leaves the receiver
+untouched. Mutating the receiver remains the job of `refresh` and `save`.
+
+When the resource has an `object_key`, a Hash body is treated as an envelope and
+unwrapped the way `refresh` does, while each element of an Array body is treated
+as a bare item the way `ListObject` does.
+
+## Hooks
+
+Generated action methods pass their params and headers through two overridable
+class methods, mirroring `list_params` and `list_headers`:
+
+```ruby
+class User < ApiResource
+  action :track, method: :post
+
+  def self.action_params(name, params)
+    params.merge(api_key: MyApi.api_key)
+  end
+
+  def self.action_headers(name, params)
+    { "X-Request-Source" => "my-app" }
+  end
+end
+```
+
+The built-ins expose their routed paths as overridable methods too:
+
+| Method | Used by |
+|---|---|
+| `retrieve_resource_path` (instance) | `refresh` |
+| `list_resource_path(params)` (class) | `list` |
+| `save_resource_path` (instance) | `save` |
+| `save_params` (instance) | `save`; `as_save_json` plus the id param when `update` uses `id: :param` |
+| `id_param` (class) | the default id param for every member action on the class |
+
+The instance method `resource_path` is unchanged. It still means "this record's
+REST path" (`/campaigns/abc`), so hand-rolled requests built on it keep working
+even when `retrieve` is re-routed.
+
+## Introspection
+
+```ruby
+MyApi::Campaign.actions                 # => { retrieve: #<Resteze::Action>, list: ..., ... }
+MyApi::Campaign.actions.fetch(:retrieve).http_method   # => :get
+MyApi::Campaign.actions.fetch(:retrieve).path_for("abc") # => "/campaigns/details"
+MyApi::Campaign.actions.fetch(:duplicate).to_h
+# => { name: :duplicate, method: :post, on: :member, path: "duplicate", id: :param,
+#      id_param: :campaign_id, returns: nil, as: :duplicate }
+```
+
+`actions` is rebuilt on every call and frozen. `action_for(:retrieve)` resolves a
+single action and is what `refresh`, `list`, `save` and the generated methods use
+internally, so a resource that already defines its own `actions` class method
+keeps working. `action` is always a declaration, never a lookup.
+
+## Testing
+
+The Minitest and RSpec helpers gain `has_action`, which asserts an action is
+declared and checks any options you pass. `path:` is compared against the full
+routed path, using the id `"ID"` for member actions.
+
+```ruby
+describe MyApi::Campaign do
+  include Resteze::Testing::Minitest::Object
+
+  subject { MyApi::Campaign }
+
+  it "routes its actions" do
+    has_action :data_series, method: :get, on: :collection, path: "/campaigns/data_series"
+    has_action :duplicate, method: :post, on: :member, id: :param, path: "/campaigns/duplicate"
+    has_action :retrieve, path: "/campaigns/details"
+  end
+end
+```
+
+## The escape hatch
+
+Anything the DSL does not express is still one `request` call away, exactly as
+before:
+
+```ruby
+class User < ApiResource
+  def update_with_version(version, attributes)
+    request(:patch, resource_path, params: attributes, headers: { "If-Match" => version })
+  end
+end
+```

data/docs/ADVANCED_USAGE.md

@@ -51,34 +51,23 @@ products.resteze_metadata[:per_page]
 
 ### Custom List Methods
 
+Additional list-style endpoints are declared with the `action` DSL (see
+[ACTIONS.md](ACTIONS.md)). `returns: :self` builds resources from an array body;
+`returns: :list` builds a `ListObject` using the resource's `list_key`.
+
 ```ruby
 module MyApi
   class Product < ApiResource
     include List
-    
-    # Override list behavior
-    def self.list(filters = {})
-      response = request(:get, resource_path, params: filters)
-      ListObject.new(response.data).tap do |list|
-        list.set_data(response.data[:products])
-        list.set_metadata(response.data.except(:products))
-      end
-    end
-    
-    # Additional list endpoints
-    def self.featured
-      response = request(:get, "#{resource_path}/featured")
-      response.data.map { |attrs| construct_from(attrs) }
-    end
-    
-    def self.search(query, limit: 10)
-      response = request(
-        :get, 
-        "#{resource_path}/search",
-        params: { q: query, limit: limit }
-      )
-      ListObject.new(response.data)
-    end
+
+    # Product.featured => GET /products/featured, an Array of Product
+    action :featured, method: :get, returns: :self
+
+    # Product.search(q: "lamp", limit: 10) => GET /products/search?q=lamp&limit=10, a ListObject
+    action :search, method: :get, returns: :list
+
+    # An API that lists at /products/list instead of /products
+    action :list, path: "list"
   end
 end
 ```
@@ -260,36 +249,31 @@ end
 
 ### Custom Error Handling
 
+`RaiseError` already maps 401/403 to `MyApi::AuthenticationError` and 429 to `MyApi::RateLimitError`. To add a class for a status the built-in hierarchy does not single out, subclass the nearest built-in error and raise it from a middleware placed before `RaiseError`:
+
 ```ruby
 module MyApi
-  # Define custom errors
-  class RateLimitError < Error; end
-  class AuthenticationError < Error; end
+  # 503 during a maintenance window is worth telling apart from other 5xx
+  class MaintenanceError < ApiError; end
   
-  # Custom middleware for error handling
-  class Middleware::CustomErrorHandler < Faraday::Middleware
+  class Middleware::MaintenanceCheck < Faraday::Middleware
     def on_complete(env)
-      case env[:status]
-      when 429
-        raise RateLimitError.new(
-          "Rate limit exceeded. Retry after #{env[:response_headers]['retry-after']}",
-          http_status: 429,
-          response: env
-        )
-      when 401
-        raise AuthenticationError.new(
-          "Authentication failed",
-          http_status: 401,
-          response: env
-        )
-      end
+      return unless env[:status] == 503 && env[:response_headers]["X-Maintenance"]
+
+      raise MaintenanceError.new(
+        "API is down for maintenance",
+        http_status: 503,
+        http_body: env[:body],
+        http_headers: env[:response_headers]
+      )
     end
   end
   
   class Client < Resteze::Client
     def self.default_connection
-      @default_connection ||= Faraday.new do |conn|
-        conn.use Middleware::CustomErrorHandler
+      Thread.current["#{client_name}_default_connection"] ||= Faraday.new do |conn|
+        conn.use Faraday::Request::UrlEncoded
+        conn.use Middleware::MaintenanceCheck
         conn.use Middleware::RaiseError
         conn.adapter Faraday.default_adapter
       end