couchbase-orm 3.2.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 253e0ee05a3522f641294d615724214c6b03ebfd189f008544e9a41f0e671916
-  data.tar.gz: 7628e1f89db8f7649dd6795145b238a06af87cb1901e30337670c3f15b87378c
+  metadata.gz: 90eb0b8fb472134579071ce58442b518bd42009d3647363116f041eb65b13a85
+  data.tar.gz: 066cad6c6ee614382262d035d8d86e55e8d829f42733d21daddd9a91deb03786
 SHA512:
-  metadata.gz: af199f51fb0fd808ac4920ca8eb16d50b8d6afa89a23cd311d5e39e92df87f93914368267afd373e7d8d282e50e517b892039008f3a2d234ef5bf1ea2b63bb83
-  data.tar.gz: b0703729ad90b504026467377aecdeaed17434010f044ede50d0645ef1e51d9dadef595c31ad1f1990d7366ba7f4101c934c716f4f8cb2152a70d0f846ad7e88
+  metadata.gz: 2cfd5683e131c28d10499da7c42ab2000688bed5dc5382c9b7a2beab99cb8b142da16b9327966636777ca32c34bee101185c1fb8a8b1862203339b5a27adc24c
+  data.tar.gz: 393a5523c5a5ffb2154b8ac426e199179cebc48356fd32a7170ad6c1eed7a6984a56c4990e3e0601d88710071c22b50b8ad87c41a067b1dc5b4bdd0fec29a281

data/.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+.[0-9]+'
+
+permissions:
+  contents: write
+
+jobs:
+  github-release:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Verify tag is on master
+        run: |
+          git fetch origin master
+          if ! git merge-base --is-ancestor "${{ github.sha }}" origin/master; then
+            echo "::error::Tag ${{ github.ref_name }} (${{ github.sha }}) is not an ancestor of origin/master. Refusing to create a GitHub Release for a commit that hasn't been merged to master."
+            exit 1
+          fi
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "${{ github.ref_name }}" --title "${{ github.ref_name }}" --generate-notes

data/README.md

@@ -195,13 +195,39 @@ Check this couchbase help page to learn more on what's possible with compound ke
 Ex : Compound keys allows to decide the order of the results, and you can reverse it by passing `descending: true`
 
 ```ruby
-    class Comment < CouchbaseOrm::Base19
+    class Comment < CouchbaseOrm::Base
       self.ignored_properties = [:old_name] # ignore old_name property in the model
       self.properties_always_exists_in_document = true # use is null for nil value instead of not valued for performance purpose, only possible if all properties always exists in document
     end
 ```      
 You can specify `properties_always_exists_in_document` to true if all properties always exists in document, this will allow to use `is null` instead of `not valued` for nil value, this will improve performance. 
 
+## Schema evolution
+
+`ignored_properties` (above) drops a named, fixed list of legacy keys wherever a document is
+decoded. For the more general case of a rolling/canary deploy - where a document written by a pod
+running newer code can carry an attribute a pod still running older code hasn't declared yet -
+there is `raise_on_unknown_attributes`:
+
+```ruby
+    class Comment < CouchbaseOrm::Base
+      self.raise_on_unknown_attributes = false # tolerate any undeclared document key instead of raising
+    end
+```
+
+With the default (`true`), an undeclared key anywhere in `new`, `assign_attributes`, `find` or
+`reload` raises `ActiveModel::UnknownAttributeError`, same as plain ActiveModel. Set it to `false`
+and undeclared keys are dropped instead, with a warning logged the first time each one is seen on
+a given class. Unlike `ignored_properties`, it is a `class_attribute`, so it is inherited by
+subclasses and can be set once for a whole hierarchy (e.g. on your app's own base class) or
+globally via `CouchbaseOrm::Document.raise_on_unknown_attributes = false`.
+
+Because a dropped key was never assigned to an attribute, it is not written back out either: if
+the model is saved afterwards, the key disappears from the stored document. If you need to
+preserve an unknown key across a load-then-save round trip rather than only tolerate it on load,
+`ignored_properties` won't help with that either - both mechanisms are read-side tolerance, not a
+schemaless passthrough.
+
 WARNING: If a document exists without a property, the query will failed! So you must be sure that all documents have all properties.
 
 

data/RELEASE.md

@@ -34,6 +34,10 @@
   git tag X.Y.Z
   git push origin X.Y.Z
 
+  Pushing the tag automatically triggers the `Release` GitHub Actions workflow, which creates the
+  corresponding GitHub Release (with auto-generated notes) once it confirms the tag's commit is on
+  `master`.
+
   3. Verify Clean State
 
   Ensure your local master branch is clean and up-to-date:
@@ -66,6 +70,8 @@
 
   Post-Release
 
+  - Verify the GitHub Release was created automatically at
+    https://github.com/Couchbase-Ecosystem/couchbase-ruby-orm/releases/tag/X.Y.Z
   - Announce the release if applicable (changelog, team communication, etc.)
   - Update any documentation that references the version number
 

data/docusaurus/docs/tutorial-ruby-couchbase-orm/03-defining-models.md

@@ -236,4 +236,43 @@ Validations are automatically run when saving a document. If any validations fai
 
 By leveraging validations, you can ensure the quality and consistency of your data before it is persisted to Couchbase Server.
 
+## 3.7. Handling Unknown Document Properties
+
+By default, CouchbaseOrm requires every property found on a document to have a matching declared
+attribute: loading a document with an undeclared key raises `ActiveModel::UnknownAttributeError`.
+This is normally what you want, but it becomes a problem during a rolling or canary deploy: a pod
+running newer code can write a document with an attribute that a pod still running older code
+hasn't declared yet, and that older pod will raise the moment it tries to read the document back.
+
+Set `raise_on_unknown_attributes` to `false` on a model to tolerate this instead:
+
+```ruby
+class User < CouchbaseOrm::Base
+  self.raise_on_unknown_attributes = false
+
+  attribute :name, :string
+end
+
+User.find(id) # a document with an extra, undeclared key no longer raises;
+               # the key is simply dropped and a warning is logged.
+```
+
+A few things worth knowing:
+
+- It applies everywhere a document (or a hash) is turned into attributes: `new`, `assign_attributes`,
+  `find`, and `reload`.
+- It is a `class_attribute`, so unlike `ignored_properties` it is **inherited** by subclasses, and it
+  can be set once for a whole hierarchy - for example on your application's own base class - rather
+  than repeated per model. You can also set a global default with
+  `CouchbaseOrm::Document.raise_on_unknown_attributes = false` from a Rails initializer.
+- A key is considered "known" if the model responds to the corresponding writer, not just if it is a
+  declared `attribute` - so a `belongs_to`/`has_and_belongs_to_many` association key (e.g. `parent:`)
+  is never treated as unknown, even though its underlying attribute is actually named `parent_id`.
+- A dropped key is not written back out: since it was never assigned to an attribute, saving the
+  model afterwards omits it from the stored document, the same trade-off `ignored_properties` makes.
+- Unlike `ignored_properties`, which removes a fixed, named list of keys wherever a document is
+  decoded, `raise_on_unknown_attributes` tolerates *any* undeclared key. Use `ignored_properties`
+  when you know exactly which legacy keys you're phasing out; use `raise_on_unknown_attributes` when
+  you want a model to be structurally resilient to future attributes it doesn't know about yet.
+
 With the model definition covered, including attributes, callbacks, and validations, you're ready to start querying and persisting data using CouchbaseOrm. In the next section, we'll explore the querying capabilities of CouchbaseOrm and how to retrieve data from Couchbase Server efficiently.

data/docusaurus/docs/tutorial-ruby-couchbase-orm/09-nested-documents.md

@@ -135,4 +135,23 @@ Nested documents provide a powerful way to model complex data structures and rel
 
 However, it's important to consider the trade-offs when using nested documents. Embedding too much data within a single document can lead to large document sizes and potential performance issues. It's recommended to use nested documents judiciously and to consider the access patterns and data relationships of your application.
 
+## 9.8. Unknown Properties on Nested Documents
+
+`raise_on_unknown_attributes` (see [3.7](./03-defining-models.md#37-handling-unknown-document-properties))
+applies to `CouchbaseOrm::NestedDocument` the same way it does to `CouchbaseOrm::Base`, but the
+setting is per nested class - it is not inherited through composition from the parent document.
+A tolerant parent embedding a strict nested class still raises if that nested document carries an
+undeclared property, and vice versa:
+
+```ruby
+class Part < CouchbaseOrm::NestedDocument
+  self.raise_on_unknown_attributes = false # only Part tolerates unknown properties
+  attribute :name, :string
+end
+
+class Car < CouchbaseOrm::Base
+  attribute :parts, :array, type: Part # Car's own setting (default: true) is unaffected
+end
+```
+
 In the next section, we'll explore enums in CouchbaseOrm and how they can be used to define a fixed set of values for an attribute.

data/docusaurus/docs/tutorial-ruby-couchbase-orm/11-encryption.md

@@ -141,6 +141,17 @@ CouchbaseOrm handles the storage format for encrypted attributes but does not pe
 - All actual encryption/decryption is your application's responsibility
 - Values must be valid Base64-encoded strings
 
+The `encrypted$` unwrapping in step 2 above happens for **any** key with that prefix, whether or
+not it maps to a declared `:encrypted` attribute. This means that if you are retiring an encrypted
+attribute with [`raise_on_unknown_attributes = false`](./03-defining-models.md#37-handling-unknown-document-properties)
+instead of `ignored_properties`, a single rule covers both `legacy_field` and
+`encrypted$legacy_field` in the underlying document - you don't need to list both spellings.
+One case only `ignored_properties` can handle: if an `encrypted$`-prefixed key's value is not a
+`{alg:, ciphertext:}`-shaped hash (e.g. it was left over from a different serialization format),
+unwrapping raises before `raise_on_unknown_attributes` ever gets a chance to filter it - only
+naming the exact key with `ignored_properties`, which strips it before unwrapping is attempted,
+handles that case.
+
 ## 11.4. Considerations and Best Practices
 
 When using encrypted attributes in CouchbaseOrm, consider the following best practices:

data/docusaurus/docs/tutorial-ruby-couchbase-orm/12-logging.md

@@ -46,3 +46,17 @@ D, [2024-05-24T11:48:00.113166 #234447] DEBUG -- : _update_record - replace user
 I, [2024-05-24T11:48:00.115239 #234447]  INFO -- : User user-1-vncZNSYZj updated email to john.doe@example.com
 ```
 
+## 12.2. Unknown Attribute Warnings
+
+When a model has [`raise_on_unknown_attributes`](./03-defining-models.md#37-handling-unknown-document-properties)
+set to `false`, every `assign_attributes` call (from `new`, `find`, `reload`, ...) that drops an
+undeclared key logs at `DEBUG` level. To avoid flooding your logs on high-traffic models, a `WARN`
+is only emitted the first time a given (model class, property name) pair is seen in the process:
+
+```
+D, [...] DEBUG -- : User: ignoring unknown properties ["legacy_field"]
+W, [...]  WARN -- : User: ignoring unknown document properties legacy_field (raise_on_unknown_attributes is false for this class - they will not be persisted if the document is saved)
+```
+
+That warning tracking is capped so it cannot grow unbounded.
+

data/docusaurus/docs/tutorial-ruby-couchbase-orm/13-troubleshooting.md

@@ -16,6 +16,8 @@ Here are some common issues you may encounter while using CouchbaseOrm:
 
 5. **Unexpected Behavior**: If you experience unexpected behavior or results, double-check your code logic, query conditions, and attribute assignments. Ensure that you are using the correct methods, parameters, and data types.
 
+6. **`ActiveModel::UnknownAttributeError` right after a deploy**: This typically happens during a rolling or canary deploy, when a document written by a pod running newer code carries an attribute a pod still running older code hasn't declared yet. See [Handling Unknown Document Properties](./03-defining-models.md#37-handling-unknown-document-properties) for `raise_on_unknown_attributes`, or `ignored_properties` if you're phasing out a specific, known set of legacy keys instead.
+
 ## 15.2. Debugging Tips
 
 When troubleshooting issues with CouchbaseOrm, consider the following debugging tips:

data/lib/couchbase-orm/active_record_compat.rb

@@ -44,12 +44,6 @@ module CouchbaseOrm
       def type_for_attribute(attribute)
         attribute_types[attribute]
       end
-
-      if ActiveModel::VERSION::MAJOR < 6
-        def attribute_names
-          attribute_types.keys
-        end
-      end
     end
 
     def slice(*methods)
@@ -68,25 +62,5 @@ module CouchbaseOrm
       value = send(attr_name)
       value.inspect
     end
-
-    if ActiveModel::VERSION::MAJOR < 6
-      def attribute_names
-        self.class.attribute_names
-      end
-
-      def has_attribute?(attr_name)
-        @attributes.key?(attr_name.to_s)
-      end
-
-      def attribute_present?(attribute)
-        value = send(attribute)
-        !value.nil? && !(value.respond_to?(:empty?) && value.empty?)
-      end
-
-      def _write_attribute(attr_name, value)
-        @attributes.write_from_user(attr_name.to_s, value)
-        value
-      end
-    end
   end
 end

data/lib/couchbase-orm/base.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true, encoding: ASCII-8BIT
 
 
+require 'set'
 require 'active_model'
 require 'active_support/hash_with_indifferent_access'
 require 'couchbase'
@@ -26,6 +27,7 @@ require 'couchbase-orm/json_transcoder'
 require 'couchbase-orm/timestamps'
 require 'couchbase-orm/active_record_compat'
 require 'couchbase-orm/strict_loading'
+require 'couchbase-orm/unknown_attributes'
 require 'couchbase-orm/json_schema/validation'
 require 'couchbase-orm/utilities/properties_always_exists_in_document'
 
@@ -43,6 +45,7 @@ module CouchbaseOrm
         include ActiveRecordCompat
         include StrictLoading
         include Encrypt
+        include UnknownAttributes
 
         extend Enum
         extend IgnoredProperties

data/lib/couchbase-orm/persistence.rb

@@ -157,6 +157,10 @@ module CouchbaseOrm
             hash = hash.with_indifferent_access if hash.is_a?(Hash)
             super(hash.except("type"))
         end
+        # ActiveModel::AttributeAssignment aliases attributes= to its own
+        # assign_attributes at include-time, so without this, `model.attributes = hash`
+        # would bypass the "type" stripping above.
+        alias_method :attributes=, :assign_attributes
 
         # Updates the attributes of the model from the passed-in hash and saves the
         # record. If the object is invalid, the saving will fail and false will be returned.

data/lib/couchbase-orm/proxies/bucket_proxy.rb

@@ -23,14 +23,8 @@ module CouchbaseOrm
             end
         end
     
-        if RUBY_VERSION.to_i >= 3
-            def method_missing(name, *args, **options, &block)
-                @proxyfied.public_send(name, *args, **options, &block)
-            end
-        else
-            def method_missing(name, *args, &block)
-                @proxyfied.public_send(name, *args, &block)
-            end
+        def method_missing(name, *args, **options, &block)
+            @proxyfied.public_send(name, *args, **options, &block)
         end
     end
 end

data/lib/couchbase-orm/types.rb

@@ -5,13 +5,6 @@ require "couchbase-orm/types/array"
 require "couchbase-orm/types/nested"
 require "couchbase-orm/types/encrypted"
 
-if ActiveModel::VERSION::MAJOR < 6
-  # In Rails 5, the type system cannot allow overriding the default types
-  ActiveModel::Type.registry.instance_variable_get(:@registrations).delete_if do |k|
-    k.matches?(:date) || k.matches?(:datetime) || k.matches?(:timestamp)
-  end
-end
-
 ActiveModel::Type.register(:date, CouchbaseOrm::Types::Date)
 ActiveModel::Type.register(:datetime, CouchbaseOrm::Types::DateTime)
 ActiveModel::Type.register(:timestamp, CouchbaseOrm::Types::Timestamp)

data/lib/couchbase-orm/unknown_attributes.rb

@@ -0,0 +1,82 @@
+require 'set'
+require 'active_support/concern'
+
+module CouchbaseOrm
+    # Controls what happens when a document (or a Hash/Parameters passed to
+    # `new`/`assign_attributes`) carries a key that has no corresponding
+    # attribute or writer on the model.
+    #
+    # By default (`raise_on_unknown_attributes = true`) this is unchanged
+    # ActiveModel behaviour: an `ActiveModel::UnknownAttributeError` is
+    # raised. Setting it to `false` on a model (it is inherited, like any
+    # `class_attribute`) makes unknown keys tolerated instead: they are
+    # dropped before assignment and a warning is logged.
+    #
+    # This exists to survive rolling/canary deploys: a document written by a
+    # pod running newer code can carry attributes a pod still running older
+    # code does not know about yet. Without this, reading that document on
+    # the old code raises and the request fails.
+    #
+    # A key is considered "known" using the same test ActiveModel itself uses
+    # to decide whether to raise (`respond_to?(:"#{key}=")`), not attribute
+    # membership - this matters because association writers (`belongs_to`,
+    # `has_and_belongs_to_many`) define a setter (e.g. `parent=`) for a name
+    # that is not itself a declared attribute (the attribute is `parent_id`).
+    # Filtering by attribute name would silently drop those.
+    #
+    # Unknown keys are only ever dropped from the in-memory assignment. If
+    # the model is saved afterwards, `serialized_attributes` only emits
+    # declared attributes, so the unknown key disappears from the stored
+    # document too - the same trade-off `ignored_properties` already makes.
+    module UnknownAttributes
+        extend ActiveSupport::Concern
+
+        # Caps the process-wide memory used to track which (class, key)
+        # warnings have already been emitted. Unknown keys come from
+        # document content, i.e. are not under the application's control,
+        # so this must be bounded. Once the cap is hit, unknown attributes
+        # are still filtered (and still logged at debug level) - only the
+        # warn-once escalation stops.
+        MAX_WARNED = 1_000
+
+        @warned = Set.new
+
+        included do
+            class_attribute :raise_on_unknown_attributes,
+                             instance_accessor: false, instance_predicate: false, default: true
+        end
+
+        # Filters out unknown keys before assignment when
+        # `raise_on_unknown_attributes` is false; otherwise unchanged.
+        def assign_attributes(attributes)
+            return super if self.class.raise_on_unknown_attributes
+            # Garbage input (nil, an Integer, a bare Object...) must still get
+            # ActiveModel's own "you must pass a hash" ArgumentError from
+            # `super`, not a NoMethodError from calling each_pair on it below.
+            return super unless attributes.respond_to?(:each_pair)
+
+            unknown = attributes.each_pair.filter_map { |key, _| key unless respond_to?(:"#{key}=") }
+            return super if unknown.empty?
+
+            UnknownAttributes.report(self.class, unknown)
+            super(attributes.except(*unknown))
+        end
+        alias_method :attributes=, :assign_attributes
+
+        class << self
+            # @api private
+            def report(klass, keys)
+                CouchbaseOrm.logger.debug { "#{klass.name}: ignoring unknown properties #{keys.inspect}" }
+
+                newly_warned = @warned.size >= MAX_WARNED ? [] : keys.select { |key| @warned.add?("#{klass.name}##{key}") }
+                return if newly_warned.empty?
+
+                CouchbaseOrm.logger.warn(
+                    "#{klass.name}: ignoring unknown document properties #{newly_warned.join(', ')} " \
+                    "(raise_on_unknown_attributes is false for this class - " \
+                    "they will not be persisted if the document is saved)"
+                )
+            end
+        end
+    end
+end

data/lib/couchbase-orm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true, encoding: ASCII-8BIT
 
 module CouchbaseOrm
-  VERSION = '3.2.0'
+  VERSION = '3.3.0'
 end

data/spec/base_spec.rb

@@ -22,6 +22,33 @@ class BaseTestWithIgnoredProperties < CouchbaseOrm::Base
     attribute :job, :string
 end
 
+class BaseTestWithUnknownAttributesAllowed < CouchbaseOrm::Base
+    self.raise_on_unknown_attributes = false
+    attribute :name, :string
+    attribute :job, :string
+end
+
+class NestedDocWithUnknownAttributesAllowed < CouchbaseOrm::NestedDocument
+    self.raise_on_unknown_attributes = false
+    attribute :title, :string
+    attribute :value, :integer
+end
+
+class NestedDocWithDefaultBehavior < CouchbaseOrm::NestedDocument
+    attribute :title, :string
+    attribute :value, :integer
+end
+
+class ParentDocWithNestedUnknownAllowed < CouchbaseOrm::Base
+    attribute :name, :string
+    attribute :nested_item, :nested, type: NestedDocWithUnknownAttributesAllowed
+end
+
+class ParentDocWithNestedDefault < CouchbaseOrm::Base
+    attribute :name, :string
+    attribute :nested_item, :nested, type: NestedDocWithDefaultBehavior
+end
+
 class BaseTestWithPropertiesAlwaysExistsInDocument < CouchbaseOrm::Base
     self.properties_always_exists_in_document = true
     attribute :name, :string
@@ -349,6 +376,116 @@ describe CouchbaseOrm::Base do
         end
     end
 
+    describe 'handling unknown attributes' do
+        context 'when raise_on_unknown_attributes is set to false' do
+            it 'returns false when queried' do
+                expect(BaseTestWithUnknownAttributesAllowed.raise_on_unknown_attributes).to be(false)
+            end
+
+            it 'silently ignores unknown attributes in new' do
+                model = BaseTestWithUnknownAttributesAllowed.new(name: 'test', job: 'dev', unknown_attr: 'value')
+                expect(model.name).to eq('test')
+                expect(model.job).to eq('dev')
+                expect(model.respond_to?(:unknown_attr)).to be(false)
+            end
+
+            it 'silently ignores unknown attributes in assign_attributes' do
+                model = BaseTestWithUnknownAttributesAllowed.new(name: 'test')
+                expect {
+                    model.assign_attributes(name: 'updated', job: 'engineer', foo: 'bar', baz: 'qux')
+                }.not_to raise_error
+                expect(model.name).to eq('updated')
+                expect(model.job).to eq('engineer')
+                expect(model.respond_to?(:foo)).to be(false)
+                expect(model.respond_to?(:baz)).to be(false)
+            end
+
+            it 'only stores known attributes' do
+                model = BaseTestWithUnknownAttributesAllowed.new(
+                    name: 'Alice',
+                    job: 'Developer',
+                    unknown_field_1: 'value1',
+                    unknown_field_2: 'value2'
+                )
+                # Only known attributes should be stored
+                expect(model.name).to eq('Alice')
+                expect(model.job).to eq('Developer')
+                expect(model.respond_to?(:unknown_field_1)).to be(false)
+                expect(model.respond_to?(:unknown_field_2)).to be(false)
+            end
+        end
+
+        context 'default behavior (raise_on_unknown_attributes = true)' do
+            it 'returns true by default' do
+                expect(BaseTest.raise_on_unknown_attributes).to be(true)
+            end
+
+            it 'raises ActiveModel::UnknownAttributeError on unknown attributes in new' do
+                expect {
+                    BaseTest.new(name: 'bob', job: 'dev', foo: 'bar')
+                }.to raise_error(ActiveModel::UnknownAttributeError)
+            end
+
+            it 'raises ActiveModel::UnknownAttributeError on unknown attributes in assign_attributes' do
+                model = BaseTest.new(name: 'bob')
+                expect {
+                    model.assign_attributes(job: 'dev', foo: 'bar')
+                }.to raise_error(ActiveModel::UnknownAttributeError)
+            end
+        end
+
+        context 'for NestedDocument classes' do
+            it 'returns false when queried on NestedDocument with raise_on_unknown_attributes = false' do
+                expect(NestedDocWithUnknownAttributesAllowed.raise_on_unknown_attributes).to be(false)
+            end
+
+            it 'returns true by default on NestedDocument' do
+                expect(NestedDocWithDefaultBehavior.raise_on_unknown_attributes).to be(true)
+            end
+
+            it 'silently ignores unknown attributes in NestedDocument when disabled' do
+                nested = NestedDocWithUnknownAttributesAllowed.new(title: 'Test', value: 42, unknown: 'ignored')
+                expect(nested.title).to eq('Test')
+                expect(nested.value).to eq(42)
+                expect(nested.respond_to?(:unknown)).to be(false)
+            end
+
+            it 'raises error for unknown attributes in NestedDocument when enabled' do
+                expect {
+                    NestedDocWithDefaultBehavior.new(title: 'Test', value: 42, unknown: 'error')
+                }.to raise_error(ActiveModel::UnknownAttributeError)
+            end
+
+            it 'silently ignores unknown attributes in nested documents within parent' do
+                parent = ParentDocWithNestedUnknownAllowed.new(name: 'Parent')
+                nested = NestedDocWithUnknownAttributesAllowed.new(title: 'Nested', value: 100, extra: 'ignored')
+                parent.nested_item = nested
+
+                expect(parent.nested_item.title).to eq('Nested')
+                expect(parent.nested_item.value).to eq(100)
+                expect(parent.nested_item.respond_to?(:extra)).to be(false)
+            end
+
+            it 'raises error for unknown attributes in nested documents with default behavior' do
+                parent = ParentDocWithNestedDefault.new(name: 'Parent')
+                expect {
+                    NestedDocWithDefaultBehavior.new(title: 'Nested', value: 100, extra: 'error')
+                }.to raise_error(ActiveModel::UnknownAttributeError)
+            end
+
+            it 'works with assign_attributes on NestedDocument' do
+                nested = NestedDocWithUnknownAttributesAllowed.new(title: 'Initial')
+                expect {
+                    nested.assign_attributes(title: 'Updated', value: 50, unknown_field: 'ignored')
+                }.not_to raise_error
+
+                expect(nested.title).to eq('Updated')
+                expect(nested.value).to eq(50)
+                expect(nested.respond_to?(:unknown_field)).to be(false)
+            end
+        end
+    end
+
     describe '.properties_always_exists_in_document' do
         it 'Uses NOT VALUED when properties_always_exists_in_document = false' do
             where_clause = BaseTest.where(name: nil)

data/spec/couchbase-orm/active_record_compat_spec.rb

@@ -3,6 +3,18 @@ require './lib/couchbase-orm/active_record_compat'
 class Foo
   include CouchbaseOrm::ActiveRecordCompat
 
+  def self.attribute_names
+    %w[id compute_age]
+  end
+
+  def self.attribute_types
+    { 'id' => :string }
+  end
+
+  def attribute_names
+    self.class.attribute_names
+  end
+
   def compute_age
     10 + 32
   end
@@ -21,4 +33,65 @@ describe CouchbaseOrm::ActiveRecordCompat do
       expect(foo.values_at([:compute_age])).to eq([42])
     end
   end
+
+  describe '.primary_key' do
+    it 'is always "id"' do
+      expect(Foo.primary_key).to eq('id')
+    end
+  end
+
+  describe '.base_class?' do
+    it 'is always true' do
+      expect(Foo.base_class?).to be true
+    end
+  end
+
+  describe '.column_names' do
+    it 'delegates to .attribute_names' do
+      expect(Foo.column_names).to eq(%w[id compute_age])
+    end
+  end
+
+  describe '.abstract_class?' do
+    it 'is always false' do
+      expect(Foo.abstract_class?).to be false
+    end
+  end
+
+  describe '.connected?' do
+    it 'is always true' do
+      expect(Foo.connected?).to be true
+    end
+  end
+
+  describe '.table_exists?' do
+    it 'is always true' do
+      expect(Foo.table_exists?).to be true
+    end
+  end
+
+  describe '._reflect_on_association' do
+    it 'is always false' do
+      expect(Foo._reflect_on_association(:anything)).to be false
+    end
+  end
+
+  describe '.type_for_attribute' do
+    it 'delegates to .attribute_types' do
+      expect(Foo.type_for_attribute('id')).to eq(:string)
+    end
+  end
+
+  describe '#_has_attribute?' do
+    it 'checks membership in #attribute_names' do
+      expect(foo._has_attribute?(:compute_age)).to be true
+      expect(foo._has_attribute?(:unknown)).to be false
+    end
+  end
+
+  describe '#attribute_for_inspect' do
+    it 'inspects the value returned by the named method' do
+      expect(foo.attribute_for_inspect(:compute_age)).to eq('42')
+    end
+  end
 end

data/spec/couchbase-orm/changeable_spec.rb

@@ -13,4 +13,41 @@ describe 'CouchbaseOrm::Changeable' do
     doc = Doc.find(doc.id)
     expect(doc.changes).to be_empty
   end
+
+  describe 'per-attribute dirty methods generated by create_dirty_methods' do
+    # `changes_applied` runs the same in-memory bookkeeping create/update
+    # triggers after a save (no DB round trip needed to exercise it).
+    let(:doc) do
+      Doc.new(title: 'initial').tap do |d|
+        d.title = 'Test'
+        d.changes_applied
+      end
+    end
+
+    it 'exposes the change made in the last save' do
+      expect(doc.changed?).to be false # cleared by changes_applied
+      expect(doc.title_change).to be_nil # no change pending right now
+      expect(doc.will_save_change_to_title?).to be false
+      expect(doc.title_previously_was).to eq('initial')
+      expect(doc.title_before_last_save).to be_nil # only set by a real save, not by changes_applied alone
+      expect(doc.title_previously_changed?).to be true
+      expect(doc.title_previous_change).to eq(['initial', 'Test'])
+    end
+
+    it 'exposes the change during the save that triggered it, with an explicit from/to' do
+      expect(doc.saved_change_to_title?(from: 'initial')).to be true
+      expect(doc.saved_change_to_title?(to: 'Test')).to be true
+      expect(doc.saved_change_to_title?(from: 'initial', to: 'Test')).to be true
+      expect(doc.saved_change_to_title?(from: 'nope')).to be false
+    end
+
+    it 'can flag an attribute as about to change, and reset it back' do
+      expect { doc.title_will_change! }.not_to raise_error
+      expect { doc.reset_title! }.not_to raise_error
+    end
+
+    it 'falls back to nil for an attribute that was never saved' do
+      expect(Doc.new.title_previously_was).to be_nil
+    end
+  end
 end

data/spec/proxies/bucket_proxy_spec.rb

@@ -0,0 +1,53 @@
+require 'couchbase-orm/proxies/bucket_proxy'
+require 'couchbase-orm/proxies/n1ql_proxy'
+require 'couchbase-orm/proxies/results_proxy'
+
+RSpec.describe CouchbaseOrm::BucketProxy do
+    let(:proxyfied) { double('bucket') }
+
+    it 'raises when asked to proxy nil' do
+        expect { CouchbaseOrm::BucketProxy.new(nil) }.to raise_error(ArgumentError)
+    end
+
+    it 'delegates unknown methods to the proxyfied object' do
+        allow(proxyfied).to receive(:name).and_return('my_bucket')
+        expect(CouchbaseOrm::BucketProxy.new(proxyfied).name).to eq('my_bucket')
+    end
+
+    it 'delegates unknown methods with args, kwargs and a block' do
+        allow(proxyfied).to receive(:default_collection).with('a', b: 1).and_yield(:yielded)
+        CouchbaseOrm::BucketProxy.new(proxyfied).default_collection('a', b: 1) do |arg|
+            expect(arg).to eq(:yielded)
+        end
+    end
+
+    it 'wraps #n1ql in a N1qlProxy' do
+        allow(proxyfied).to receive(:n1ql).and_return(:the_n1ql)
+        expect(CouchbaseOrm::BucketProxy.new(proxyfied).n1ql).to be_a(CouchbaseOrm::N1qlProxy)
+    end
+
+    describe '#view' do
+        it 'wraps the result in a ResultsProxy and caches it for the same design/view' do
+            allow(proxyfied).to receive(:view).with('design', 'view').and_return([:row1, :row2])
+            proxy = CouchbaseOrm::BucketProxy.new(proxyfied)
+
+            first = proxy.view('design', 'view')
+            second = proxy.view('design', 'view')
+
+            expect(first).to be_a(CouchbaseOrm::ResultsProxy)
+            expect(second).to be(first)
+            expect(proxyfied).to have_received(:view).once
+        end
+
+        it 'requeries when the design/view pair changes' do
+            allow(proxyfied).to receive(:view).with('design', 'view').and_return([:row1])
+            allow(proxyfied).to receive(:view).with('design', 'other').and_return([:row2])
+            proxy = CouchbaseOrm::BucketProxy.new(proxyfied)
+
+            proxy.view('design', 'view')
+            proxy.view('design', 'other')
+
+            expect(proxyfied).to have_received(:view).twice
+        end
+    end
+end

data/spec/type_encrypted_spec.rb

@@ -25,6 +25,16 @@ describe CouchbaseOrm::Types::Encrypted do
     let(:the_secret) { "\x17`\x1F\xEE\el\xE0\x9F<\x94\xFE\x8A.\x1A\x92\xB9\xC3@\x86\x9Cp\xBEl\x86\x0E\x8CJ\tB\x97*U)\x96\x06\xA3\xE9\x84\xA6xW%\xDCT\x8C^\xEA\t\xC7\xD8\xFC\xF1\xD3\xD3\xE2\xEA\x89\xCBuUs\xB3\xFF'W>\xDE\x9CP\xA9\xDE%\xA2\xDE\x11\xFD\b\x9C\xD4\x87J,\x91\x02f\x16R\xDE\x908\x05\x1C\xF9\xDF{\x0F\xB3e\xB2\xB2\x96\xD7\xCC\x16As\xD3I\x02w\xE0\x8FL\xC6S\xEFP\xAC\x15\e^\xC4!\x15\"KF1\x17\x06\xA0N\x00\x18\xBA\x87\xEA?H\xD4<\xB5\xBCV\xB50\fc\xC9F\"\xF0B\eg%\x8E\x88\xD0\x9Bc\xE4\x93\t\x98\xC8\x87\xCB4]\xD9K\xA3\xDF\x13Q\xC0T\xCA\x91;\b\x9Cp\xE0\x7FR h\xDA\xB7\xD5\x869\f\xCA\x80\x802\x19\x19\xDD\x9DO\xAE}\xCA\eX\xA3\xA8\xBE\xE1\xBCW0g\x19@5n\r\xD8\xF3\x05\x7F4\x9CI\x1F3\xC0\xBDQJyG\v\xED!s\xD5\xD0&\xC1\x1A\xBC\x17\xFD\x9Cd\xB5\xAF\xB6U\x8A" }
     let(:base64_secret) { Base64.strict_encode64(the_secret) }
 
+    describe "#serialize" do
+        it "returns nil for a nil value" do
+            expect(CouchbaseOrm::Types::Encrypted.new.serialize(nil)).to be_nil
+        end
+
+        it "returns the value unchanged otherwise (wrapping happens in Encrypt#encode_encrypted_attributes)" do
+            expect(CouchbaseOrm::Types::Encrypted.new.serialize(base64_secret)).to eq(base64_secret)
+        end
+    end
+
     it "prefix attribute on serialization" do
         obj = TypeEncryptedTest.new(secret: base64_secret, secret2: "a secret")
         expect_serialized_secret(obj)
@@ -50,6 +60,16 @@ describe CouchbaseOrm::Types::Encrypted do
         expect(obj.as_json["secret2"]).to eq "a secret"
     end
 
+    it "raises when serializing a non-String value for an encrypted attribute" do
+        obj = TypeEncryptedTest.new(secret: 12345)
+        expect { obj.send(:serialized_attributes) }.to raise_error(/Can not serialize value/)
+    end
+
+    it "raises from #as_json when a non-String value is held by an encrypted attribute" do
+        obj = TypeEncryptedTest.new(secret: 12345)
+        expect { obj.as_json }.to raise_error(/Can not serialize value/)
+    end
+
     it "prefix with custom algo" do
         obj = SpecificAlgoTest.new(secret: base64_secret)
         expect(obj.send(:serialized_attributes)["encrypted$secret"]).to eq({alg:"3DES", ciphertext: base64_secret})

data/spec/type_nested_spec.rb

@@ -18,6 +18,18 @@ class TypeNestedTest < CouchbaseOrm::Base
 end
 
 describe CouchbaseOrm::Types::Nested do
+    describe "#serialize" do
+        it "builds an instance from a raw Hash before serializing it, filtering ignored properties" do
+            # `serialize` is normally called with an already-built NestedDocument
+            # instance (see the specs below); this exercises its Hash branch
+            # directly, using string keys to match the shape a real document
+            # (and thus `ignored_properties`, which stores string names) has.
+            type = CouchbaseOrm::Types::Nested.new(type: SubTypeWithIgnoredProperties)
+            serialized = type.serialize("name" => "Nested", "value" => "Valid", "deprecated_property" => "should be dropped")
+            expect(serialized).to eq("name" => "Nested", "value" => "Valid")
+        end
+    end
+
     it "should be able to store and retrieve a nested object" do
         obj = TypeNestedTest.new
         obj.main = SubTypeTest.new
@@ -255,4 +267,84 @@ describe CouchbaseOrm::Types::Nested do
             expect(parent.nested.value).to eq("Parent Value")
         end
     end
+
+    describe "raise_on_unknown_attributes" do
+        class SubTypeWithUnknownAttributesAllowed < CouchbaseOrm::NestedDocument
+            self.raise_on_unknown_attributes = false
+            attribute :label, :string
+        end
+
+        class SubTypeWithDefaultUnknownAttributes < CouchbaseOrm::NestedDocument
+            attribute :label, :string
+        end
+
+        class ParentWithNestedUnknownAttributesAllowed < CouchbaseOrm::Base
+            self.raise_on_unknown_attributes = false
+            attribute :title, :string
+            attribute :main, :nested, type: SubTypeWithUnknownAttributesAllowed
+            attribute :others, :array, type: SubTypeWithUnknownAttributesAllowed
+        end
+
+        class ParentWithStrictNestedUnknownAttributes < CouchbaseOrm::Base
+            self.raise_on_unknown_attributes = false
+            attribute :title, :string
+            attribute :main, :nested, type: SubTypeWithDefaultUnknownAttributes
+        end
+
+        it "tolerates an unknown key in a nested document assigned as a Hash, via Types::Nested#cast" do
+            # This is the path the actual document-loading code takes; assigning an
+            # already-built NestedDocument *instance* (as opposed to a Hash) never
+            # reaches Types::Nested#cast at all.
+            parent = ParentWithNestedUnknownAttributesAllowed.new(title: "Parent")
+            parent.main = SubTypeWithUnknownAttributesAllowed.new(label: "Main")
+            parent.save!
+
+            doc_id = parent.id
+            raw_doc = ParentWithNestedUnknownAttributesAllowed.bucket.default_collection.get(doc_id).content
+            raw_doc["main"]["legacy"] = "should be ignored"
+            ParentWithNestedUnknownAttributesAllowed.bucket.default_collection.replace(doc_id, raw_doc)
+
+            parent.reload
+            expect(parent.main.label).to eq("Main")
+            expect(parent.main.attributes.keys).not_to include("legacy")
+
+            # Same assertion via `find` - a different code path (the GetResult
+            # branch of Document#initialize) than `reload`.
+            reloaded = ParentWithNestedUnknownAttributesAllowed.find(doc_id)
+            expect(reloaded.main.label).to eq("Main")
+            expect(reloaded.main.attributes.keys).not_to include("legacy")
+        end
+
+        it "tolerates an unknown key in a nested document inside a Types::Array, assigned as Hashes" do
+            parent = ParentWithNestedUnknownAttributesAllowed.new(title: "Parent")
+            parent.others = [
+                SubTypeWithUnknownAttributesAllowed.new(label: "First"),
+                SubTypeWithUnknownAttributesAllowed.new(label: "Second")
+            ]
+            parent.save!
+
+            doc_id = parent.id
+            raw_doc = ParentWithNestedUnknownAttributesAllowed.bucket.default_collection.get(doc_id).content
+            raw_doc["others"][0]["legacy"] = "should be ignored"
+            ParentWithNestedUnknownAttributesAllowed.bucket.default_collection.replace(doc_id, raw_doc)
+
+            parent.reload
+            expect(parent.others.map(&:label)).to eq(["First", "Second"])
+            expect(parent.others[0].attributes.keys).not_to include("legacy")
+            expect(parent.others[1].attributes.keys).not_to include("legacy")
+        end
+
+        it "is per nested class: a tolerant parent does not make a strict nested document tolerant" do
+            parent = ParentWithStrictNestedUnknownAttributes.new(title: "Parent")
+            parent.main = SubTypeWithDefaultUnknownAttributes.new(label: "Main")
+            parent.save!
+
+            doc_id = parent.id
+            raw_doc = ParentWithStrictNestedUnknownAttributes.bucket.default_collection.get(doc_id).content
+            raw_doc["main"]["legacy"] = "should raise"
+            ParentWithStrictNestedUnknownAttributes.bucket.default_collection.replace(doc_id, raw_doc)
+
+            expect { parent.reload }.to raise_error(ActiveModel::UnknownAttributeError)
+        end
+    end
 end

data/spec/unknown_attributes_spec.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true, encoding: ASCII-8BIT
+
+require File.expand_path("../support", __FILE__)
+
+# A minimal stand-in for ActionController::Parameters (each_pair/each/except,
+# no #to_hash). Real Parameters would work too, but pulling in actionpack
+# here would make this spec's outcome depend on whatever version bundler
+# happens to resolve it to; what actually matters is that the filter is
+# guarded by `respond_to?(:each_pair)`, not `is_a?(Hash)`.
+#
+# `each` is required too, not just `each_pair`: ActiveModel::AttributeAssignment's
+# own `_assign_attributes` (which our `super` eventually reaches) iterates via
+# `.each` on ActiveModel < 8.0, and via `.each_pair` on 8.0+.
+class EachPairOnly
+    def initialize(hash)
+        @hash = hash
+    end
+
+    def each_pair(&block)
+        @hash.each_pair(&block)
+    end
+    alias_method :each, :each_pair
+
+    def except(*keys)
+        EachPairOnly.new(@hash.except(*keys))
+    end
+
+    def empty?
+        @hash.empty?
+    end
+end
+
+class UnknownAttrsStrict < CouchbaseOrm::Base
+    attribute :name, :string
+end
+
+class UnknownAttrsTolerant < CouchbaseOrm::Base
+    self.raise_on_unknown_attributes = false
+    attribute :name, :string
+    attribute :secret, :encrypted
+end
+
+class UnknownAttrsTolerantChild < UnknownAttrsTolerant
+end
+
+class UnknownAttrsBoth < CouchbaseOrm::Base
+    self.raise_on_unknown_attributes = false
+    self.ignored_properties = [:legacy_ignored]
+    attribute :name, :string
+end
+
+class UnknownAttrsAssocParent < CouchbaseOrm::Base
+    attribute :name, :string
+end
+
+class UnknownAttrsAssocChild < CouchbaseOrm::Base
+    self.raise_on_unknown_attributes = false
+    attribute :name, :string
+    belongs_to :unknown_attrs_assoc_parent, dependent: :destroy
+end
+
+RSpec.describe "raise_on_unknown_attributes" do
+    # No public reset API on purpose (it would be test-only surface on
+    # production code) - reach into the module's own warn-once tracking
+    # directly so these examples don't depend on run order.
+    before { CouchbaseOrm::UnknownAttributes.instance_variable_get(:@warned).clear }
+
+    describe "defaults" do
+        it "defaults to true" do
+            expect(CouchbaseOrm::Base.raise_on_unknown_attributes).to be true
+            expect(UnknownAttrsStrict.raise_on_unknown_attributes).to be true
+        end
+
+        it "still raises ActiveModel::UnknownAttributeError when true" do
+            expect { UnknownAttrsStrict.new(name: 'bob', nope: 'x') }.to raise_error(ActiveModel::UnknownAttributeError)
+            model = UnknownAttrsStrict.new(name: 'bob')
+            expect { model.assign_attributes(nope: 'x') }.to raise_error(ActiveModel::UnknownAttributeError)
+        end
+    end
+
+    describe "inheritance" do
+        it "is inherited by subclasses, unlike ignored_properties" do
+            expect(UnknownAttrsTolerantChild.raise_on_unknown_attributes).to be false
+        end
+
+        it "does not leak from a subclass back to its parent or to Base" do
+            expect(UnknownAttrsTolerant.raise_on_unknown_attributes).to be false
+            expect(CouchbaseOrm::Base.raise_on_unknown_attributes).to be true
+        end
+    end
+
+    describe "association writers are not treated as unknown attributes" do
+        it "still resolves belongs_to via its writer, not via attribute_names" do
+            parent = UnknownAttrsAssocParent.create!(name: 'parent')
+            child = UnknownAttrsAssocChild.new(name: 'child', unknown_attrs_assoc_parent: parent, really_unknown: 'x')
+
+            expect(child.unknown_attrs_assoc_parent_id).to eq(parent.id)
+            expect(child.respond_to?(:really_unknown)).to be false
+        end
+    end
+
+    describe "given a document with an unknown property" do
+        let(:doc_id) { "unknown_attrs_tolerant_#{SecureRandom.hex}" }
+        let(:document_properties) do
+            {
+                'type' => UnknownAttrsTolerant.design_document,
+                'name' => 'Alice',
+                'server_encrypted_content' => 'not yet known to this code'
+            }
+        end
+
+        before { UnknownAttrsTolerant.bucket.default_collection.upsert doc_id, document_properties }
+        after { UnknownAttrsTolerant.bucket.default_collection.remove doc_id }
+
+        it "does not raise on find (the INC-5405 path) and drops the unknown key" do
+            model = UnknownAttrsTolerant.find(doc_id)
+            expect(model.name).to eq('Alice')
+            expect(model.attributes.keys).not_to include('server_encrypted_content')
+        end
+
+        it "raises on find when raise_on_unknown_attributes is true" do
+            document_properties['type'] = UnknownAttrsStrict.design_document
+            UnknownAttrsStrict.bucket.default_collection.upsert doc_id, document_properties
+            expect { UnknownAttrsStrict.find(doc_id) }.to raise_error(ActiveModel::UnknownAttributeError)
+        end
+
+        it "does not raise on reload" do
+            model = UnknownAttrsTolerant.find(doc_id)
+            expect { model.reload }.not_to raise_error
+            expect(model.attributes.keys).not_to include('server_encrypted_content')
+        end
+
+        it "logs a warning exactly once per (class, key), and debug on every call" do
+            allow(CouchbaseOrm.logger).to receive(:debug).and_call_original
+            expect(CouchbaseOrm.logger).to receive(:warn).once.with(a_string_including('server_encrypted_content'))
+
+            UnknownAttrsTolerant.find(doc_id)
+            UnknownAttrsTolerant.find(doc_id)
+        end
+
+        it "emits no warning at all when raise_on_unknown_attributes is true" do
+            document_properties['type'] = UnknownAttrsStrict.design_document
+            UnknownAttrsStrict.bucket.default_collection.upsert doc_id, document_properties
+            expect(CouchbaseOrm.logger).not_to receive(:warn)
+            expect { UnknownAttrsStrict.find(doc_id) }.to raise_error(ActiveModel::UnknownAttributeError)
+        end
+
+        it "drops the unknown key from the stored document on the next save (same trade-off as ignored_properties)" do
+            model = UnknownAttrsTolerant.find(doc_id)
+            model.name = 'Alice Updated'
+            expect { model.save! }.to change {
+                UnknownAttrsTolerant.bucket.default_collection.get(doc_id).content.keys.sort
+            }.from(%w[name server_encrypted_content type]).to(%w[name type])
+        end
+    end
+
+    describe "interaction with encrypted$-prefixed keys" do
+        it "tolerates an unknown key that only happens to carry the encrypted$ prefix" do
+            doc_id = "unknown_attrs_tolerant_enc_#{SecureRandom.hex}"
+            UnknownAttrsTolerant.bucket.default_collection.upsert doc_id, {
+                'type' => UnknownAttrsTolerant.design_document,
+                'name' => 'Bob',
+                'encrypted$tanker_encrypted_content' => { 'alg' => 'tanker', 'ciphertext' => 'legacy' }
+            }
+
+            model = UnknownAttrsTolerant.find(doc_id)
+            expect(model.name).to eq('Bob')
+            expect(model.attributes.keys).not_to include('tanker_encrypted_content', 'encrypted$tanker_encrypted_content')
+        ensure
+            UnknownAttrsTolerant.bucket.default_collection.remove doc_id
+        end
+    end
+
+    describe "combined with ignored_properties" do
+        let(:doc_id) { "unknown_attrs_both_#{SecureRandom.hex}" }
+
+        before do
+            UnknownAttrsBoth.bucket.default_collection.upsert doc_id, {
+                'type' => UnknownAttrsBoth.design_document,
+                'name' => 'Carol',
+                'legacy_ignored' => 'handled by ignored_properties',
+                'other_unknown' => 'handled by the flag'
+            }
+        end
+        after { UnknownAttrsBoth.bucket.default_collection.remove doc_id }
+
+        it "tolerates both without raising, and only warns about the one the flag handled" do
+            expect(CouchbaseOrm.logger).to receive(:warn).once.with(a_string_including('other_unknown'))
+            model = UnknownAttrsBoth.find(doc_id)
+            expect(model.name).to eq('Carol')
+            expect(model.attributes.keys).not_to include('legacy_ignored', 'other_unknown')
+        end
+    end
+
+    describe "duck-typed, non-Hash input (e.g. ActionController::Parameters)" do
+        it "filters through a respond_to?(:each_pair) object just like a Hash" do
+            # Calling assign_attributes directly (rather than .new) matters here:
+            # Document#initialize's generic branch runs every non-GetResult,
+            # non-CouchbaseOrm::Base argument through Kernel#Hash(), which would
+            # coerce a real permitted ActionController::Parameters (it defines
+            # #to_hash) before assign_attributes ever saw it - masking exactly
+            # the guard this test means to exercise.
+            model = UnknownAttrsTolerant.new(name: 'Dave')
+            model.assign_attributes(EachPairOnly.new(name: 'Dave Updated', nope: 'x'))
+            expect(model.name).to eq('Dave Updated')
+            expect(model.respond_to?(:nope)).to be false
+        end
+
+        it "still raises for a non-Hash, non-each_pair argument, same as before this feature existed" do
+            # Persistence#assign_attributes (unrelated to raise_on_unknown_attributes,
+            # pre-existing on CouchbaseOrm::Base) calls `hash.except("type")`
+            # unconditionally, so on Base this is a NoMethodError rather than the
+            # ArgumentError plain ActiveModel would raise. Either way, it must not
+            # be silently swallowed by the unknown-attributes filter.
+            expect { UnknownAttrsTolerant.new.assign_attributes(Object.new) }.to raise_error(StandardError)
+        end
+    end
+
+    describe "attributes=" do
+        it "goes through the same filtering as assign_attributes" do
+            model = UnknownAttrsTolerant.new(name: 'Eve')
+            model.attributes = { name: 'Eve Updated', nope: 'x' }
+            expect(model.name).to eq('Eve Updated')
+            expect(model.respond_to?(:nope)).to be false
+        end
+    end
+end

data/spec/utilities/ignored_properties_spec.rb

@@ -1,3 +1,4 @@
+require 'couchbase-orm'
 require 'couchbase-orm/utilities/ignored_properties'
 
 class DummyClass
@@ -17,4 +18,20 @@ RSpec.describe CouchbaseOrm::IgnoredProperties do
       expect(DummyClass2.ignored_properties).to be_empty
     end
   end
+
+  describe '#ignored_properties' do
+    # A fresh class per example, so the deprecated-setter test below can't
+    # leak state into (or depend on run order with) any other example.
+    let(:klass) { Class.new { extend CouchbaseOrm::IgnoredProperties } }
+
+    it 'defaults to an empty array' do
+      expect(klass.ignored_properties).to eq([])
+    end
+
+    it 'is deprecated as a setter and warns when called with arguments' do
+      expect(CouchbaseOrm.logger).to receive(:warn).with(a_string_including('deprecated'))
+      klass.ignored_properties(:legacy_property)
+      expect(klass.ignored_properties).to eq(['legacy_property'])
+    end
+  end
 end

metadata

@@ -1,16 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: couchbase-orm
 version: !ruby/object:Gem::Version
-  version: 3.2.0
+  version: 3.3.0
 platform: ruby
 authors:
 - Stephen von Takach
 - Gauthier Monserand
 - Pierre Merlin
 - Julien Burnet-Fauche
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -209,11 +210,13 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 description: A Couchbase ORM for Rails
+email: 
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/deploy.yml"
+- ".github/workflows/release.yml"
 - ".github/workflows/test.yml"
 - ".gitignore"
 - ".rspec"
@@ -297,6 +300,7 @@ files:
 - lib/couchbase-orm/types/encrypted.rb
 - lib/couchbase-orm/types/nested.rb
 - lib/couchbase-orm/types/timestamp.rb
+- lib/couchbase-orm/unknown_attributes.rb
 - lib/couchbase-orm/utilities/ensure_unique.rb
 - lib/couchbase-orm/utilities/enum.rb
 - lib/couchbase-orm/utilities/has_many.rb
@@ -334,6 +338,7 @@ files:
 - spec/json_schema_spec.rb
 - spec/n1ql_spec.rb
 - spec/persistence_spec.rb
+- spec/proxies/bucket_proxy_spec.rb
 - spec/relation_nested_spec.rb
 - spec/relation_spec.rb
 - spec/support.rb
@@ -341,6 +346,7 @@ files:
 - spec/type_encrypted_spec.rb
 - spec/type_nested_spec.rb
 - spec/type_spec.rb
+- spec/unknown_attributes_spec.rb
 - spec/utilities/ignored_properties_spec.rb
 - spec/utilities/properties_always_exists_in_document_spec.rb
 - spec/views_spec.rb
@@ -352,6 +358,7 @@ metadata:
   bug_tracker_uri: https://github.com/Couchbase-Ecosystem/couchbase-ruby-orm/issues
   documentation_uri: https://www.couchbase-ruby-orm.com/
   homepage_uri: https://github.com/Couchbase-Ecosystem/couchbase-ruby-orm
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -366,7 +373,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 3.0.3.1
+signing_key: 
 specification_version: 4
 summary: Couchbase ORM for Rails
 test_files:
@@ -392,6 +400,7 @@ test_files:
 - spec/json_schema_spec.rb
 - spec/n1ql_spec.rb
 - spec/persistence_spec.rb
+- spec/proxies/bucket_proxy_spec.rb
 - spec/relation_nested_spec.rb
 - spec/relation_spec.rb
 - spec/support.rb
@@ -399,6 +408,7 @@ test_files:
 - spec/type_encrypted_spec.rb
 - spec/type_nested_spec.rb
 - spec/type_spec.rb
+- spec/unknown_attributes_spec.rb
 - spec/utilities/ignored_properties_spec.rb
 - spec/utilities/properties_always_exists_in_document_spec.rb
 - spec/views_spec.rb