rest-easy 1.3.1 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95a7fdafc540b448187281dfcd184257553fc79cbf93af6236463e9bbcadcfa5
-  data.tar.gz: a5710b3e26d6fb8078d1079359f78dbe0b7a12810411f86652a84997086a0022
+  metadata.gz: a30780e0b38e31f1c183d1ec0a91ea93658a78e67d2415aeb8aef279d03359b7
+  data.tar.gz: 2ed7aafbcaf5e0c6fd463992a65293d1f064c693611f64b9b3256e8e4b518fdf
 SHA512:
-  metadata.gz: 7444dc20090fc6547e1f55516fcb0a9d7d467ecfd6f0a9530c768ae7d6b735fa2ca789bdb7cc222277269fa4494a05c4187b2f3ffd28c74d82636ae09a197848
-  data.tar.gz: 1c7af7dc5042410d6a11483356c41a24dacff39c240fb1cdce1950b859f47c2adb4a6293f93e0257ef5e5b482fb28b000d3660c6f2c705fe9b1925a3837e3837
+  metadata.gz: 3ac9ea37e26b652d5fe590075d7668f70e2cf8b7290b02d7e4dd1f227bf7a7e26ea9e5faa02ed1b84b5706262d90e774db52381ea0ce2d026da40d410ae38c11
+  data.tar.gz: 8f8773d0cbacc6366daade22ceee18ee76de91ee5eb5cd718c392e0abfe1ed3a911658a867dab1bcd1f21b077f2296e0cb5ffbb1aa5597f6fee7e77a7b40b84d

data/CHANGELOG.md

@@ -2,6 +2,91 @@
 
 ## [Unreleased]
 
+## [1.4.1] - 2026-08-18
+
+### Fixed
+
+- **`Meta` no longer claims to implement methods it has no value for.**
+  `Meta#respond_to_missing?` returned `true` for every name, so any caller
+  that asks an object what it can do before calling it got a false yes, then
+  received the `nil` that `method_missing` returns for an unknown key as
+  though it were a real answer. Ruby does this constantly and implicitly —
+  coercion probes when a value is splatted or interpolated, serialisation
+  hooks, and any library that duck-types with `respond_to?` — so the failure
+  surfaced far from `Meta` and looked unrelated to it. Marshalling was the
+  sharpest case: `dump` silently wrote an empty payload and `load` then
+  raised `NoMethodError` from inside `method_missing`, which broke every
+  consumer caching resources in a store that marshals its entries.
+
+  Bare getters are now claimed only for keys the instance actually holds.
+  Setters and predicates are still claimed unconditionally, since writing is
+  how a key comes into existence and an unset predicate is meaningfully
+  `false`; no core Ruby probe uses those two shapes. Library-level
+  duck-typing can, though — ActiveSupport's `acts_like?(:date)` asks for
+  `acts_like_date?`, and `Meta` still answers yes — so the guarantee is
+  narrower than "nothing probes for `=` or `?`", and closing it properly is
+  tracked in #7. Operators are no longer claimed either: the check is
+  anchored to identifier-shaped names, so `<=` is not mistaken for a setter
+  (`method_missing` still is — #6).
+  `Resource::MetaCollector` had the identical defect and is fixed the same
+  way.
+
+  **Upgrading with a warm cache:** entries written by an earlier version are
+  not recoverable. A payload dumped before this fix carries `nil` where the
+  meta state should be, and loading it now raises `TypeError: instance of
+  RestEasy::Meta needs to have method 'marshal_load'` — legible, but still
+  an error. Consumers on a cache that survives deploys (`:file_store`,
+  Redis, Memcached) must flush it or bump the cache key namespace when
+  upgrading. A process-local `:memory_store` clears itself on restart and
+  needs nothing.
+
+  `method_missing` is unchanged: a bare getter for a key that was never set
+  still returns `nil` rather than raising, as the "gem author extensions"
+  example in `docs/model-architecture.md` depends on. `respond_to?`
+  therefore under-reports for those keys; reconciling the two halves
+  requires declaring meta keys up front and is tracked in #7.
+
+## [1.4.0] - 2026-06-26
+
+### Fixed
+
+- **`:required` is now enforced on serialise as well as parse.** Previously
+  the flag raised `MissingAttributeError` only when an API response omitted
+  the field; it was silently ignored when sending (`save`), letting
+  incomplete payloads reach the backend and surface as a generic
+  `RequestError`. The flag now also fires at `serialise` time (and therefore
+  on `save`) when a required attribute is `nil`, before any HTTP request,
+  with the attribute name on the exception (`#attribute_name`). Inbound
+  behavior is unchanged — `parse` still raises on missing required fields.
+  A field is treated as missing whether the API response omits the key
+  entirely or includes it as explicit `null`; both are rejected as
+  incomplete data.
+- **`:required` is now enforced on synthetic attributes (merge / combine /
+  split patterns).** Previously the flag was silently a no-op for any
+  attribute with a multi-parameter parse or serialise block. It now
+  enforces presence on all underlying API or model fields: a merge
+  attribute requires every source API field on parse; a combine attribute
+  requires every named model attribute on serialise; a split attribute
+  requires the underlying API field on parse. `:read_only` continues to
+  skip the serialise-time check.
+
+### Changed
+
+- **The DSL auto-applies `:synthetic` to multi-parameter serialise blocks**
+  (and mapper `serialise` methods), mirroring the existing behavior for
+  multi-parameter parse. Previously only the parse side was tagged,
+  leaving the flag inconsistent with its intent of marking attributes whose
+  storage shape diverges from the standard one-slot layout.
+- **Combine attributes no longer read from their `api_name` on parse.**
+  A combine attribute's API name does not correspond to a real inbound
+  field by design — the value is built from `target_fields` at serialise
+  time. The previous code looked up `api_data[api_name]`, stored it at
+  the model slot, and ran the standard `:required` check, raising
+  spuriously when the field was absent (the documented case). Inbound
+  values for the shadowed API key are now ignored and the model slot is
+  set to `nil`, avoiding the contradiction where `instance.address` could
+  return one value while serialise would overwrite it with another.
+
 ## [1.3.1] - 2026-05-27
 
 ### Fixed
@@ -82,7 +167,9 @@
 
 Initial release.
 
-[Unreleased]: https://github.com/accodeing/rest-easy/compare/v1.3.1...HEAD
+[Unreleased]: https://github.com/accodeing/rest-easy/compare/v1.4.1...HEAD
+[1.4.1]: https://github.com/accodeing/rest-easy/compare/v1.4.0...v1.4.1
+[1.4.0]: https://github.com/accodeing/rest-easy/compare/v1.3.1...v1.4.0
 [1.3.1]: https://github.com/accodeing/rest-easy/compare/v1.3.0...v1.3.1
 [1.3.0]: https://github.com/accodeing/rest-easy/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/accodeing/rest-easy/compare/v1.1.2...v1.2.0

data/README.md

@@ -326,12 +326,12 @@ attr [:tax_url, '@urlTaxReductionList'], String, :read_only
 
 ### Flags
 
-| Flag         | Effect                                                   |
-|--------------|----------------------------------------------------------|
-| `:required`  | Raises `MissingAttributeError` if absent in API response |
-| `:optional`  | Documents that the field may be absent (default)         |
-| `:read_only` | Excluded from serialisation (not sent back to the API)   |
-| `:key`       | Marks the unique identifier for CRUD operations          |
+| Flag         | Effect                                                                 |
+|--------------|------------------------------------------------------------------------|
+| `:required`  | Raises `MissingAttributeError` if missing or explicitly `null` in the API response (on parse) or `nil` at serialise time (`save`, `to_api`). Omitted keys and explicit `null` are treated identically — a required attribute must carry a value. See [Merge](#merge-pattern--many-api-fields-into-one-model-attribute), [Combine](#combine-pattern--many-model-attributes-into-one-api-field), and [Split](#split-pattern--one-api-field-into-many-model-attributes) patterns for how this applies to synthetic attributes. |
+| `:optional`  | Documents that the field may be absent (default)                       |
+| `:read_only` | Excluded from serialisation (not sent back to the API)                 |
+| `:key`       | Marks the unique identifier for CRUD operations                        |
 
 ```ruby
 key :id, Integer, :read_only
@@ -430,6 +430,31 @@ end
 attr :full_name, String, FullNameMapper
 ```
 
+Marking a merge attribute `:required` enforces that **all** underlying API fields are present in the response on parse. If the attribute is also round-trippable (not `:read_only`), the merged model value must additionally be non-`nil` at serialise time.
+
+Note that string-concatenation merges like the `full_name` example above are inherently lossy on the round-trip — splitting `"Hans Erik Nilsson"` back into `FirstName`/`LastName` is ambiguous. Such attributes should normally be `:read_only`. Round-trippable merges work when the model representation preserves the structure (e.g. a tuple, a `Money` value object, or a `Date` built from year/month/day components).
+
+### Combine pattern — many model attributes into one API field
+
+The dual of merge: when the serialise method takes multiple parameters, RestEasy gathers the values from the corresponding model attributes and passes them in. The block returns the single combined API value:
+
+```ruby
+attr :street, String
+attr :city, String
+
+attr :address, String do
+  serialise { |street, city| "#{street}, #{city}" }
+end
+```
+
+The parameter names (`street`, `city`) name model attributes; the framework reads them from the instance and splats them into the block. The block's return value is written under the attribute's API name (`Address`).
+
+This also works with mapper objects whose `serialise` method takes multiple parameters.
+
+Marking a combine attribute `:required` enforces that **all** named model attributes are non-`nil` at serialise time. The parse side does not apply — combine attributes don't read from a single API field on the way in, so users typically populate the underlying model attributes directly.
+
+Combine attributes do not run a `parse` block. If you declare one alongside a multi-parameter `serialise`, RestEasy emits a warning at load time — the parse block would be silently ignored otherwise. If you need to read from an API field on parse, declare a separate attribute for it (or restructure as a merge pattern).
+
 ### Split pattern — one API field into many model attributes
 
 Use a bare block with a parameter to extract from a single API field:
@@ -446,6 +471,10 @@ end
 
 The parameter name (`address`) determines which API field to read from.
 
+Marking a split attribute `:required` enforces that the underlying API field is present on parse — in the example above, the API response must include `Address`.
+
+On serialise, split attributes are emitted under their own api_names (here, `Street` and `City`) rather than being recombined into the original source field. If the API does not accept the parts as independent top-level fields, mark them `:read_only` to keep them out of the outbound payload entirely; alternatively, reconstruct the source field in an `after_serialise` hook.
+
 ### Ignoring fields
 
 Tell RestEasy to silently skip API fields you don't need:

data/lib/rest_easy/attribute.rb

@@ -36,6 +36,20 @@ module RestEasy
       @flags.include?(:synthetic)
     end
 
+    # A combine attribute is built from multiple model fields on serialise
+    # (target_fields), with no inbound source from its own api_name on parse.
+    # See the "Combine pattern" section of the README.
+    def combine?
+      @target_fields.any? && @source_fields.empty?
+    end
+
+    def validate_required!(*values)
+      return unless required?
+      return if values.none?(&:nil?)
+
+      raise RestEasy::MissingAttributeError.new(model_name)
+    end
+
     def coerce(value)
       @type[value]
     rescue Dry::Types::ConstraintError, Dry::Types::CoercionError => e

data/lib/rest_easy/meta.rb

@@ -25,8 +25,46 @@ module RestEasy
       end
     end
 
-    def respond_to_missing?(_name, _include_private = false)
-      true
+    # Accessor shapes `method_missing` synthesises. Anchored, so operators
+    # stay out: `<=` ends with `=`, and claiming it would let `meta <= 5`
+    # read as a setter. `method_missing` itself is still unanchored and
+    # writes `@data[:<]` for that call — see issue #6.
+    #
+    # POSIX classes rather than `[a-zA-Z_]\w*`, because Ruby identifiers are
+    # not ASCII-only: `meta.företag = x` is a valid setter that
+    # `method_missing` stores, so `respond_to?` has to claim it too.
+    ACCESSOR_PATTERN = /\A[[:alpha:]_][[:word:]]*[=?]\z/
+    private_constant :ACCESSOR_PATTERN
+
+    # `method_missing` answers to any name, but this must not, because callers
+    # routinely ask an object what it can do before calling it — Ruby's own
+    # coercion probes (`to_hash` on double-splat, `to_ary`, `to_str`),
+    # serialisation hooks (`marshal_dump`, `init_with`), and any library that
+    # duck-types with `respond_to?`. Claiming those hands the caller the `nil`
+    # that `method_missing` returns for an unknown key as though it were an
+    # answer.
+    #
+    # Bare getters are therefore claimed only for keys actually held. Setters
+    # and predicates are claimed unconditionally: writing is how a key comes
+    # into existence, and an unset predicate is meaningfully `false`. No core
+    # Ruby probe uses those two shapes — though library-level duck-typing can,
+    # and ActiveSupport's `acts_like?(:date)` asking for `acts_like_date?` is
+    # a known false positive. Closing it properly means declaring meta keys
+    # up front, which is a breaking change — see issue #7.
+    #
+    # `@data` is guarded because `respond_to?` must never raise, and Ruby
+    # allocates an instance before initialising it: Psych's `revive` probes
+    # `init_with` on a bare allocation, and so does `Marshal.load` on a
+    # payload written before this fix.
+    #
+    # This under-claims a bare getter for a key that was never set, which
+    # `method_missing` still answers with `nil`. Reconciling the two halves
+    # means declaring meta keys up front, and that is a 2.0 — see issue #7.
+    def respond_to_missing?(name, include_private = false)
+      return true if ACCESSOR_PATTERN.match?(name.to_s)
+      return super unless @data
+
+      @data.key?(name.to_sym) || super
     end
   end
 end

data/lib/rest_easy/resource.rb

@@ -119,8 +119,22 @@ module RestEasy
         end
       end
 
-      def respond_to_missing?(_name, _include_private = false)
-        true
+      # Anchored so operators stay out — see Meta::ACCESSOR_PATTERN and
+      # issue #6. Only the setter shape here; unlike Meta, `method_missing`
+      # above has no predicate form.
+      SETTER_PATTERN = /\A[[:alpha:]_][[:word:]]*=\z/
+      private_constant :SETTER_PATTERN
+
+      # Same reasoning as Meta#respond_to_missing? — a blanket `true` makes
+      # this claim Ruby's implicit protocol methods and hand them the `nil`
+      # from `method_missing`. `@data` is guarded for the same reason too:
+      # `respond_to?` must never raise, and Psych and Marshal both probe a
+      # bare allocation before it is initialised.
+      def respond_to_missing?(name, include_private = false)
+        return true if SETTER_PATTERN.match?(name.to_s)
+        return super unless @data
+
+        @data.key?(name.to_sym) || super
       end
     end
 
@@ -250,6 +264,7 @@ module RestEasy
 
           serialise_params = serialise_block.parameters.select { |ptype, _| ptype == :opt || ptype == :req }
           if serialise_params.length > 1
+            flags << :synthetic unless flags.include?(:synthetic)
             target_fields = serialise_params.map { |_, pname| pname }
           end
         elsif block
@@ -284,9 +299,22 @@ module RestEasy
             if serialise_block
               params = serialise_block.parameters.select { |ptype, _| ptype == :opt || ptype == :req }
               if params.length > 1
+                flags << :synthetic unless flags.include?(:synthetic)
                 target_fields = params.map { |_, pname| pname }
               end
             end
+
+            # Combine pattern (multi-param serialise, no multi-param parse)
+            # has no inbound api_name on parse. If the user also wrote an
+            # explicit `parse` block, it will be silently ignored — warn so
+            # the inconsistency is visible at load time.
+            if target_fields.any? && source_fields.empty? && parse_block
+              warn "RestEasy: :#{attribute_model_name} declares a combine pattern " \
+                   "(serialise from #{target_fields.inspect}) and also defines a parse block. " \
+                   "Combine attributes have no inbound API field to read, so the parse block " \
+                   "will not run. Remove the parse block, or restructure the declaration if you " \
+                   "intended to read from the API."
+            end
           end
         end
 
@@ -591,13 +619,15 @@ module RestEasy
       # Serialise all attributes
       klass.all_attribute_definitions.each do |_model_name, attr_def|
         next if attr_def.read_only?
-        value = @model_attributes[attr_def.model_name]
 
         if attr_def.target_fields.any?
           # Multi-param serialise: gather model values by param names, splat into block
           model_values = attr_def.target_fields.map { |fn| @model_attributes[fn] }
+          attr_def.validate_required!(*model_values)
           result[attr_def.api_name] = attr_def.serialise_value(*model_values)
         elsif attr_def.source_fields.any?
+          value = @model_attributes[attr_def.model_name]
+          attr_def.validate_required!(value)
           serialised = attr_def.serialise_value(value)
           if serialised.is_a?(::Array)
             # Array return: zip with source field API names
@@ -613,6 +643,8 @@ module RestEasy
             result[attr_def.api_name] = serialised
           end
         else
+          value = @model_attributes[attr_def.model_name]
+          attr_def.validate_required!(value)
           result[attr_def.api_name] = attr_def.serialise_value(value)
         end
       end
@@ -683,13 +715,19 @@ module RestEasy
             api_key = convention.serialise(field_name)
             api_data[api_key]
           end
+
+          attr_def.validate_required!(*raw_values)
+
           @model_attributes[model_name] = attr_def.parse_value(*raw_values)
+        elsif attr_def.combine?
+          # Combine pattern: the attribute's api_name does not exist on the
+          # API side by design — the value is built from target_fields at
+          # serialise time. Nothing inbound to read or validate.
+          @model_attributes[model_name] = nil
         else
           raw_value = api_data[attr_def.api_name]
 
-          if raw_value.nil? && attr_def.required?
-            raise MissingAttributeError.new(model_name)
-          end
+          attr_def.validate_required!(raw_value)
 
           if raw_value.nil?
             @model_attributes[model_name] = nil
@@ -717,9 +755,12 @@ module RestEasy
           end
         end
 
-        # Warn about declared attributes missing from the API response
+        # Warn about declared attributes missing from the API response.
+        # Combine attrs have no inbound api_name by design; non-combine
+        # required attrs already raised in the parse loop above.
         klass.all_attribute_definitions.each do |model_name, attr_def|
-          next if attr_def.required? # already raises
+          next if attr_def.combine?
+          next if attr_def.required?
 
           api_keys_to_check = if attr_def.source_fields.any?
                                 attr_def.source_fields.map { |sf| convention.serialise(sf) }

data/lib/rest_easy/version.rb

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

metadata

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