couchbase-orm 3.1.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ece6e35ae742239bedb003f5865293f86164ba2899801d8f9b18efe93266e09
-  data.tar.gz: 85f84fa26a635d3fa319e2c5726eb429b52e576689690e61c50ace5b79333551
+  metadata.gz: 90eb0b8fb472134579071ce58442b518bd42009d3647363116f041eb65b13a85
+  data.tar.gz: 066cad6c6ee614382262d035d8d86e55e8d829f42733d21daddd9a91deb03786
 SHA512:
-  metadata.gz: beea3033581402385e821e1d4512d0a3ae9f76df5ebd571c8907c67a216bf0680a065c1276387160208ca2a49e99310f88b7fd3b2e2147b1b5b1c92e1b4b6fba
-  data.tar.gz: 9dffa58a606270a0a0c7775b91f6af34cceb0c1bca77ac37f5eec94784e217c9e8322beed82b42e33366cae50e32b65175bb4dc1c5ea9290a305bdaa777578fc
+  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/.github/workflows/test.yml

@@ -20,23 +20,15 @@ jobs:
           - ruby: '3.3'
             active-model: '7.2'
             couchbase: '7.2.3'
-          - ruby: '3.2'
-            active-model: '7.2.0'
-            couchbase: '7.1.1'
-          - ruby: '3.2'
-            active-model: '7.1.0'
-            couchbase: '6.6.5'
-          - ruby: '3.1'
-            active-model: '7.1.0'
-            couchbase: '7.1.0'
       fail-fast: false
     runs-on: ubuntu-24.04
     name: ${{ matrix.ruby }} rails-${{ matrix.active-model }}  couchbase-${{ matrix.couchbase }}
     steps:
     - uses: actions/checkout@v3
-    - run: sudo apt-get update && sudo apt-get install libevent-dev libev-dev python3-httplib2
-    - run: wget http://security.ubuntu.com/ubuntu/pool/universe/n/ncurses/libtinfo5_6.3-2ubuntu0.1_amd64.deb
-    - run: sudo apt install ./libtinfo5_6.3-2ubuntu0.1_amd64.deb
+    - run: |
+        sudo apt-get update
+        sudo apt-get install -y libevent-dev libev-dev python3-httplib2
+        sudo apt-get install -y libtinfo5 || sudo apt-get install -y libtinfo6
     - uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby }}

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/couchbase-orm.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |gem|
   gem.summary = 'Couchbase ORM for Rails'
   gem.description = 'A Couchbase ORM for Rails'
 
-  gem.required_ruby_version = '>= 3.1.0'
+  gem.required_ruby_version = '>= 3.3.0'
   gem.require_paths = ['lib']
 
   gem.add_runtime_dependency 'activemodel', ENV['ACTIVE_MODEL_VERSION'] || '>= 7.1'

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/07-sqlpp-queries.md

@@ -147,6 +147,47 @@ docs = N1QLTest.by_custom_rating_values(key: [[1, 2]]).collect { |ob| ob.name }
 
 In the above examples, the `collect` method is used to extract the `name` attribute from each document in the result set.
 
+## 7.8 Prepared Statement Plan Caching
+
+Couchbase Server can cache the query execution plan for a SQL++ query so that subsequent executions skip the planning step. This is controlled by the `adhoc` query option: `adhoc: false` tells the server to prepare and cache the plan on first execution and reuse it on subsequent ones.
+
+### Default behaviour
+
+By default CouchbaseOrm runs queries with `adhoc: true` (the Couchbase SDK default), meaning no plan caching. This preserves the existing behaviour — you opt into plan caching explicitly.
+
+### Enabling caching for a specific call
+
+Pass `adhoc: false` directly to the query method to prepare and cache the plan (useful for frequently repeated queries):
+
+```ruby
+# Cache the plan for this query
+N1QLTest.by_rating(key: 1, adhoc: false)
+
+# Relation query with plan caching
+User.where(country: 'FR').with(adhoc: false).to_a
+```
+
+### Enabling caching for a specific `n1ql` definition
+
+Set `adhoc: false` in the macro options to always cache the plan for that particular query:
+
+```ruby
+n1ql :by_stable_filter, emit_key: [:name], adhoc: false
+```
+
+### Changing the global default
+
+Override the thread-local config to change the default for all queries in the current thread:
+
+```ruby
+# Enable plan caching for all queries in this thread
+CouchbaseOrm::N1ql.config(adhoc: false)
+```
+
+### Override priority
+
+From highest to lowest: **per-call kwarg** > **per-`n1ql`-definition option** > **`N1ql.config`** > **default (`true`)**.
+
 ## 7.7 Indexing for SQL++
 
 To optimize the performance of SQL++ queries, it's important to create appropriate indexes on the fields used in the query conditions. Couchbase Server provides a way to create indexes using the Index service.

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/n1ql.rb

@@ -9,6 +9,7 @@ module CouchbaseOrm
         extend ActiveSupport::Concern
         NO_VALUE = :no_value_specified
         DEFAULT_SCAN_CONSISTENCY = :request_plus
+        DEFAULT_ADHOC = true
         # sanitize for injection query
         def self.sanitize(value)
             if value.is_a?(String)
@@ -22,9 +23,10 @@ module CouchbaseOrm
 
         def self.config(new_config = nil)
             Thread.current['__couchbaseorm_n1ql_config__'] = new_config if new_config
-            Thread.current['__couchbaseorm_n1ql_config__'] || {
-                scan_consistency: DEFAULT_SCAN_CONSISTENCY
-            }
+            {
+                scan_consistency: DEFAULT_SCAN_CONSISTENCY,
+                adhoc: DEFAULT_ADHOC
+            }.merge(Thread.current['__couchbaseorm_n1ql_config__'] || {})
         end
 
         module ClassMethods
@@ -57,7 +59,10 @@ module CouchbaseOrm
                 @indexes[name] = method_opts
 
                 singleton_class.__send__(:define_method, name) do |key: NO_VALUE, **opts, &result_modifier|
-                    opts = options.merge(opts).reverse_merge(scan_consistency: CouchbaseOrm::N1ql.config[:scan_consistency])
+                    opts = options.merge(opts).reverse_merge(
+                        scan_consistency: CouchbaseOrm::N1ql.config[:scan_consistency],
+                        adhoc: CouchbaseOrm::N1ql.config[:adhoc]
+                    )
                     values = key == NO_VALUE ? NO_VALUE : convert_values(method_opts[:emit_key], key)
                     current_query = run_query(method_opts[:emit_key], values, query_fn, custom_order: custom_order, **opts.except(:include_docs, :key))
                     if result_modifier

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/relation.rb

@@ -3,7 +3,7 @@ module CouchbaseOrm
         extend ActiveSupport::Concern
 
         class CouchbaseOrm_Relation
-            def initialize(model:, where: where = nil, order: order = nil, limit: limit = nil, _not: _not = false, strict_loading: strict_loading = false)
+            def initialize(model:, where: where = nil, order: order = nil, limit: limit = nil, _not: _not = false, strict_loading: strict_loading = false, query_options: query_options = {})
                 CouchbaseOrm::logger.debug "CouchbaseOrm_Relation init: #{model} where:#{where.inspect} not:#{_not.inspect} order:#{order.inspect} limit: #{limit} strict_loading: #{strict_loading}"
                 @model = model
                 @limit = limit
@@ -12,6 +12,7 @@ module CouchbaseOrm
                 @order = merge_order(**order) if order
                 @where = merge_where(where, _not) if where
                 @strict_loading = strict_loading
+                @query_options = query_options || {}
                 CouchbaseOrm::logger.debug "- #{to_s}"
             end
 
@@ -70,6 +71,10 @@ module CouchbaseOrm
                 !!@strict_loading
             end
 
+            def with(opts = {})
+                CouchbaseOrm_Relation.new(**initializer_arguments.merge(query_options: @query_options.merge(opts)))
+            end
+
             def first
                 n1ql_query, params = self.limit(1).to_n1ql_with_params
                 result = @model.cluster.query(n1ql_query, build_query_options(positional_parameters: params))
@@ -168,7 +173,7 @@ module CouchbaseOrm
             end
 
             def initializer_arguments
-                { model: @model, order: @order, where: @where, limit: @limit, strict_loading: @strict_loading }
+                { model: @model, order: @order, where: @where, limit: @limit, strict_loading: @strict_loading, query_options: @query_options }
             end
 
             def merge_order(*lorder, **horder)
@@ -238,7 +243,7 @@ module CouchbaseOrm
             end
 
             def build_query_options(positional_parameters: [])
-                opts = { scan_consistency: CouchbaseOrm::N1ql.config[:scan_consistency] }
+                opts = CouchbaseOrm::N1ql.config.merge(@query_options)
                 opts[:positional_parameters] = positional_parameters unless positional_parameters.empty?
                 Couchbase::Options::Query.new(**opts)
             end
@@ -261,7 +266,7 @@ module CouchbaseOrm
 
             delegate :ids, :update_all, :delete_all, :count, :empty?, :filter, :reduce, :find_by, to: :all
 
-            delegate :where, :not, :order, :limit, :all, :strict_loading, :strict_loading?, to: :relation
+            delegate :where, :not, :order, :limit, :all, :strict_loading, :strict_loading?, :with, to: :relation
         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.1.0'
+  VERSION = '3.3.0'
 end