resteze 0.4.0 → 1.0.0

data/lib/resteze/response.rb

@@ -1,5 +1,7 @@
 module Resteze
   class Response
+    include Resteze::ApiModule
+
     OK = 200
     attr_accessor :data, :http_body, :http_headers, :http_status, :request_id
 
@@ -15,15 +17,37 @@ module Resteze
           status: response.http_status,
           headers: response.http_headers
         )
+
+        error = body_error(response)
+        raise error if error
       end
     end
 
+    # Override in MyApi::Response for APIs that report failures inside a
+    # successful HTTP response. Receives the parsed Response after the
+    # status-based middleware has accepted it; return an exception to raise
+    # it, or nil to accept the response.
+    #
+    #   module MyApi
+    #     class Response
+    #       def self.body_error(response)
+    #         data = response.data
+    #         return unless data.is_a?(Hash) && data[:errors].present?
+    #
+    #         ApiError.from_response(response, data[:message])
+    #       end
+    #     end
+    #   end
+    def self.body_error(_response)
+      nil
+    end
+
     def self.batch_response?(headers)
       headers["Content-Type".freeze].to_s.include?("boundary=batchresponse".freeze)
     end
 
     def self.parse_body(body, status: nil, headers: {})
-      return body if unparsable_body?(status:, headers:)
+      return body if body.blank? || unparsable_body?(status:, headers:)
 
       type = mime_type(headers)&.symbol || :json
       case type
@@ -45,8 +69,20 @@ module Resteze
       Mime::LOOKUP[mime_type] || Mime::Type.lookup_by_extension(:json)
     end
 
+    # Exactly 200 OK. Use #success? for the whole 2xx range.
     def ok?
       http_status == OK
     end
+
+    # Any 2xx status, matching Faraday::Response#success?.
+    def success?
+      (200..299).cover?(http_status)
+    end
+
+    # Whatever the module's RateLimiter makes of this response (see
+    # Resteze::RateLimiter#rate_limit), or nil.
+    def rate_limit
+      @rate_limit ||= api_module.try(:rate_limiter)&.rate_limit(self)
+    end
   end
 end

data/lib/resteze/result.rb

@@ -0,0 +1,18 @@
+module Resteze
+  # The default return value of a custom action: a loose, dot-accessible view
+  # of the parsed response body, with the Response it came from attached.
+  class Result < Hashie::Mash
+    include Resteze::ApiModule
+
+    disable_warnings
+
+    attr_reader :http_response
+
+    def self.from_response(response)
+      data = response.data
+      new(data.is_a?(Hash) ? data : {}).tap do |result|
+        result.instance_variable_set(:@http_response, response)
+      end
+    end
+  end
+end

data/lib/resteze/save.rb

@@ -6,24 +6,40 @@ module Resteze
       resp = request(
         save_method,
         save_resource_path,
-        params: as_save_json,
+        params: save_params,
         headers: save_headers
       )
       process_save_response(resp)
     end
 
     def save_method
-      persisted? ? :put : :post
+      save_action.http_method
     end
 
+    # While :create / :update keep their REST defaults, an instance-level
+    # resource_path override is honored exactly as in 0.4.0.
     def save_resource_path
-      persisted? ? resource_path : self.class.resource_path
+      action = save_action
+      if action.rest_default?
+        persisted? ? resource_path : self.class.resource_path
+      else
+        persisted? ? action.path_for(id) : action.path_for
+      end
     end
 
     def as_save_json
       as_json
     end
 
+    # The body sent by #save: as_save_json, plus the id param when the
+    # :update action carries the id as a param rather than in the path.
+    def save_params
+      params = as_save_json
+      return params unless persisted? && save_action.id == :param
+
+      { save_action.id_param.to_s => id }.merge(params)
+    end
+
     def save_headers
       respond_to?(:retrieve_headers) ? retrieve_headers : {}
     end
@@ -31,5 +47,11 @@ module Resteze
     def process_save_response(response)
       merge_from(response.data)
     end
+
+    private
+
+    def save_action
+      self.class.action_for(persisted? ? :update : :create)
+    end
   end
 end

data/lib/resteze/synchronized_state.rb

@@ -0,0 +1,29 @@
+module Resteze
+  # A mutex-guarded state hash for objects shared by every thread in a
+  # process, such as a module's RateLimiter and Authenticator. Including
+  # classes call `initialize_state` from their constructor and keep all
+  # mutable state in the hash rather than in instance variables.
+  module SynchronizedState
+    def initialize_state
+      @state_mutex = Mutex.new
+      @state       = {}
+    end
+
+    # A deep-copied snapshot of the state.
+    def state
+      synchronize(&:deep_dup)
+    end
+
+    def update_state(**values)
+      synchronize { |state| state.merge!(values) }
+    end
+
+    # Yields the live state hash under the lock. Re-entrant, so `state` and
+    # `update_state` may be called inside the block.
+    def synchronize
+      return yield(@state) if @state_mutex.owned?
+
+      @state_mutex.synchronize { yield(@state) }
+    end
+  end
+end

data/lib/resteze/testing/minitest/configuration.rb

@@ -3,10 +3,12 @@ module Resteze
     module Configuration
       extend ActiveSupport::Concern
 
-      # Assert that a config property is supported and can be assigned
+      # Assert that a config property can be assigned and reads back the
+      # assigned value. The original value is restored afterwards.
       def assert_config_property(property, value = nil, subject: nil)
         subject ||= (defined?(@subject) && @subject) || subject()
         original_value = subject.send(property)
+        subject.send("#{property}=", value)
 
         assert_equal value, subject.send(property), "config property #{property} value did not match expectation"
       ensure

data/lib/resteze/testing/minitest/object.rb

@@ -4,6 +4,9 @@ module Resteze
       module Object
         include ActiveSupport::Concern
 
+        ACTION_READERS = { method: :http_method, on: :on, id: :id, id_param: :id_param,
+                           returns: :returns, as: :generated_name }.freeze
+
         private
 
         # rubocop:disable Metrics/AbcSize
@@ -18,6 +21,33 @@ module Resteze
         # rubocop:enable Metrics/AbcSize
         # rubocop:enable Naming/PredicatePrefix
 
+        # Assert that an action is declared, optionally checking its resolved
+        # options. `path:` is compared against the full routed path, using the
+        # id "ID" for member actions.
+        # rubocop:disable-next Naming/PredicatePrefix
+        def has_action(name, **options)
+          action = subject.actions[name.to_sym]
+
+          assert action, "Expected #{subject} to have action: #{name}"
+          assert_action_options(action, options)
+        end
+
+        def assert_action_options(action, options)
+          ACTION_READERS.each do |option, reader|
+            next unless options.key?(option)
+
+            assert_equal options[option], action.public_send(reader),
+                         "Expected #{subject} action #{action.name} to have #{option}: #{options[option].inspect}"
+          end
+          assert_action_path(action, options[:path]) if options.key?(:path)
+        end
+
+        def assert_action_path(action, path)
+          actual = action.member? ? action.path_for("ID") : action.path_for
+
+          assert_equal path, actual, "Expected #{subject} action #{action.name} to route to #{path}"
+        end
+
         def assert_property_transformed(name, transformed: true)
           translation = subject.translations_hash.dig(subject.translations.key(name.to_sym), name.to_sym)
           transformation_defined = translation.is_a?(Proc) || subject.transformation_exists?(name.to_sym)

data/lib/resteze/testing/rspec/configure.rb

@@ -1,10 +1,12 @@
 module Resteze
   module Testing
     module Configuration
-      # Assert that a config property is supported and can be assigned
+      # Assert that a config property can be assigned and reads back the
+      # assigned value. The original value is restored afterwards.
       def assert_config_property(property, value = nil, subject: nil)
         subject ||= (defined?(@subject) && @subject) || self.subject
         original_value = subject.send(property)
+        subject.send("#{property}=", value)
 
         expect(subject.send(property)).to eq(value), "config property #{property} value did not match expectation"
       ensure

data/lib/resteze/testing/rspec/object.rb

@@ -4,8 +4,11 @@ module Resteze
       module Object
         extend RSpec::Matchers
 
+        ACTION_READERS = { method: :http_method, on: :on, id: :id, id_param: :id_param,
+                           returns: :returns, as: :generated_name }.freeze
+
         # rubocop:disable Metrics/AbcSize
-        # rubocop:disable Naming/PredicatePrefix
+        # rubocop:disable-next Naming/PredicatePrefix
         def has_property(name, **options)
           expect(subject.property?(name.to_sym)).to be(true), "Expected #{subject} to have property: #{name}"
           assert_property_default(name, options[:default]) if options.key?(:default)
@@ -13,7 +16,6 @@ module Resteze
           assert_property_transformed(name, transformed: options[:transformed]) if options.key?(:transformed)
           assert_property_required(name, required: options[:required]) if options.key?(:required)
         end
-        # rubocop:enable Naming/PredicatePrefix
 
         def assert_property_transformed(name, transformed: true)
           translation = subject.translations_hash.dig(subject.translations.key(name.to_sym), name.to_sym)
@@ -27,6 +29,34 @@ module Resteze
         end
         # rubocop:enable Metrics/AbcSize
 
+        # Assert that an action is declared, optionally checking its resolved
+        # options. `path:` is compared against the full routed path, using the
+        # id "ID" for member actions.
+        # rubocop:disable-next Naming/PredicatePrefix
+        def has_action(name, **options)
+          action = subject.actions[name.to_sym]
+
+          expect(action).not_to be_nil, "Expected #{subject} to have action: #{name}"
+          assert_action_options(action, options)
+        end
+
+        def assert_action_options(action, options)
+          ACTION_READERS.each do |option, reader|
+            next unless options.key?(option)
+
+            expect(action.public_send(reader)).to eq(options[option]),
+                                                  "Expected #{subject} action #{action.name} to have #{option}: " \
+                                                  "#{options[option].inspect}"
+          end
+          assert_action_path(action, options[:path]) if options.key?(:path)
+        end
+
+        def assert_action_path(action, path)
+          actual = action.member? ? action.path_for("ID") : action.path_for
+
+          expect(actual).to eq(path), "Expected #{subject} action #{action.name} to route to #{path}"
+        end
+
         def assert_property_required(name, required: true)
           if required
             expect(subject.required?(name.to_sym)).to be(true), "Expected #{subject} to require property: #{name}"

data/lib/resteze/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Resteze
-  VERSION = "0.4.0"
+  VERSION = "1.0.0"
 end

data/lib/resteze.rb

@@ -10,6 +10,8 @@ require_relative "resteze/version"
 # API Concerns
 require "resteze/api_module"
 require "resteze/request"
+require "resteze/actions/validation"
+require "resteze/actions"
 require "resteze/api_resource"
 require "resteze/list"
 require "resteze/save"
@@ -17,12 +19,21 @@ require "resteze/save"
 # API resource support classes
 require "resteze/object"
 
-# API Classes
-require "resteze/instrumentation"
+# API Classes (each file requires what it needs at load time, so this
+# list stays alphabetical)
+require "resteze/action"
+require "resteze/authenticating"
+require "resteze/authenticator"
 require "resteze/client"
 require "resteze/errors"
+require "resteze/instrumentation"
 require "resteze/list_object"
+require "resteze/rate_limit"
+require "resteze/rate_limiter"
+require "resteze/rate_limiting"
 require "resteze/response"
+require "resteze/result"
+require "resteze/synchronized_state"
 require "resteze/util"
 
 # Middlewares
@@ -59,6 +70,59 @@ module Resteze
     def default_api_key(attribute)
       attribute.to_s
     end
+
+    def default_id_param(klass)
+      :"#{klass.resource_slug.singularize}_id"
+    end
+
+    ACTION_DEFAULT_OPTIONS = %i[method id id_param].freeze
+
+    # Declares API-wide defaults for one named action; resources merge these
+    # beneath their own declarations.
+    def action(name, **options)
+      name = name.to_sym
+      Resteze::Action.validate_options!(name, options)
+      action_declarations[name] = options
+      nil
+    end
+
+    def action_declarations
+      @action_declarations ||= {}
+    end
+
+    # With options, merges them into the API-wide defaults applied to every
+    # action; without options, returns those defaults.
+    def action_defaults(**options)
+      @action_defaults ||= {}
+      return @action_defaults if options.empty?
+
+      Resteze::Action.validate_options!(:defaults, options, allowed: ACTION_DEFAULT_OPTIONS)
+      @action_defaults.merge!(options)
+      nil
+    end
+
+    # Chooses how the API authenticates, without opening the module's
+    # Authenticator: `authenticate_with :api_key, header: "X-Api-Key",
+    # value: -> { MyApi.api_key }`. Call it once per scheme to combine
+    # them. Reopen MyApi::Authenticator only to override its lifecycle.
+    def authenticate_with(name, **)
+      component_class(:Authenticator).strategy(name, **)
+    end
+
+    # Chooses how the client paces itself, without opening the module's
+    # RateLimiter: `rate_limit_with :fixed_window, limit: 100, window: 60`.
+    # Reopen MyApi::RateLimiter to override `retry?` and the rest.
+    def rate_limit_with(name, **)
+      component_class(:RateLimiter).strategy(name, **)
+    end
+
+    private
+
+    def component_class(name)
+      raise ArgumentError, "call this on a module that includes Resteze, after the include" unless include?(Resteze)
+
+      const_get(name, false)
+    end
   end
 
   extend ClassMethods
@@ -70,7 +134,37 @@ module Resteze
                     :read_timeout,
                     :logger,
                     :proxy
-    end
+
+      # One RateLimiter per API module, shared by every thread. Defaults to
+      # an instance of the module's own RateLimiter class; assign another to
+      # replace it (nil restores the default). Whatever is assigned is told
+      # which module it serves, so it raises this module's errors.
+      def rate_limiter
+        @rate_limiter || @component_mutex.synchronize { @rate_limiter ||= adopt(self::RateLimiter.new) }
+      end
+
+      def rate_limiter=(limiter)
+        @rate_limiter = adopt(limiter)
+      end
+
+      # One Authenticator per API module, shared by every thread, with the
+      # same defaults and replacement rules as rate_limiter.
+      def authenticator
+        @authenticator || @component_mutex.synchronize { @authenticator ||= adopt(self::Authenticator.new) }
+      end
+
+      def authenticator=(authenticator)
+        @authenticator = adopt(authenticator)
+      end
+
+      # Tells a shared component which module it serves, so a replacement
+      # of any class raises this module's errors.
+      def adopt(component)
+        component.api_module = self if component.respond_to?(:api_module=)
+        component
+      end
+    end
+    @component_mutex = Mutex.new
 
     configure do |config|
       config.api_base = "http://example.com/"
@@ -84,19 +178,15 @@ module Resteze
     const_set :Object,      Class.new(Resteze::Object)
     const_set :Client,      Class.new(Resteze::Client)
     const_set :Response,    Class.new(Resteze::Response)
+    const_set :Result,      Class.new(Resteze::Result)
     const_set :Error,       Class.new(Resteze::Error)
-
-    Resteze::Error.subclasses.select { |klass| klass.name.start_with?("Resteze::") }.each do |error_class|
-      error_type = error_class.to_s.demodulize
-      const_set error_type, Class.new(error_class) unless const_defined?("#{self}::#{error_type}")
-    end
+    const_set :RateLimiter,   Class.new(Resteze::RateLimiter)
+    const_set :Authenticator, Class.new(Resteze::Authenticator)
+    Resteze::Errors.define(self, self::Error)
 
     # Namespace other exceptions that we want to be able to catch and make sense of
     # without needing lower level implementation details
     const_set :NotImplementedError, Class.new(NotImplementedError)
-    const_set :ResourceNotFound, Class.new(Faraday::ResourceNotFound)
-    const_set :UnprocessableEntityError, Class.new(Faraday::UnprocessableEntityError)
-    const_set :ConflictError, Class.new(Faraday::ConflictError)
 
     # Setup our Magic Constants
     const_set(:ListObject, Class.new(Hashie::Array)).class_eval do

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: resteze
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 1.0.0
 platform: ruby
 authors:
 - JD Hendrickson
 bindir: bin
 cert_chain: []
-date: 2026-06-30 00:00:00.000000000 Z
+date: 2026-11-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -83,14 +83,25 @@ files:
 - Rakefile
 - assets/resteze.png
 - assets/resteze.svg
+- docs/ACTIONS.md
 - docs/ADVANCED_USAGE.md
 - docs/API.md
 - docs/CONFIGURATION.md
 - docs/ERROR_HANDLING.md
 - docs/TESTING.md
 - lib/resteze.rb
+- lib/resteze/action.rb
+- lib/resteze/actions.rb
+- lib/resteze/actions/validation.rb
 - lib/resteze/api_module.rb
 - lib/resteze/api_resource.rb
+- lib/resteze/authenticating.rb
+- lib/resteze/authenticator.rb
+- lib/resteze/authenticator/api_key.rb
+- lib/resteze/authenticator/basic.rb
+- lib/resteze/authenticator/bearer.rb
+- lib/resteze/authenticator/mtls.rb
+- lib/resteze/authenticator/strategy.rb
 - lib/resteze/client.rb
 - lib/resteze/errors.rb
 - lib/resteze/instrumentation.rb
@@ -98,9 +109,19 @@ files:
 - lib/resteze/list_object.rb
 - lib/resteze/middleware/raise_error.rb
 - lib/resteze/object.rb
+- lib/resteze/rate_limit.rb
+- lib/resteze/rate_limiter.rb
+- lib/resteze/rate_limiter/fixed_window.rb
+- lib/resteze/rate_limiter/leaky_bucket.rb
+- lib/resteze/rate_limiter/sliding_window.rb
+- lib/resteze/rate_limiter/strategy.rb
+- lib/resteze/rate_limiter/token_bucket.rb
+- lib/resteze/rate_limiting.rb
 - lib/resteze/request.rb
 - lib/resteze/response.rb
+- lib/resteze/result.rb
 - lib/resteze/save.rb
+- lib/resteze/synchronized_state.rb
 - lib/resteze/testing/minitest.rb
 - lib/resteze/testing/minitest/configuration.rb
 - lib/resteze/testing/minitest/object.rb