parse-stack-next 4.5.0

data/lib/parse/live_query.rb

@@ -0,0 +1,163 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "model/core/errors"
+
+module Parse
+  # LiveQuery provides real-time data subscriptions for reactive applications.
+  # It uses WebSockets to receive push notifications when data changes on the server.
+  #
+  # @note EXPERIMENTAL: This feature is not fully implemented. The WebSocket client
+  #   is incomplete. You must explicitly enable this feature before use:
+  #
+  #   Parse.live_query_enabled = true
+  #
+  # @example Basic usage
+  #   # Configure LiveQuery server URL
+  #   Parse.setup(
+  #     application_id: "your_app_id",
+  #     api_key: "your_api_key",
+  #     server_url: "https://your-parse-server.com/parse",
+  #     live_query_url: "wss://your-parse-server.com"
+  #   )
+  #
+  #   # Subscribe to changes on a model
+  #   subscription = Song.subscribe(where: { artist: "Artist Name" })
+  #
+  #   subscription.on(:create) { |song| puts "New song: #{song.title}" }
+  #   subscription.on(:update) { |song, original| puts "Updated: #{song.title}" }
+  #   subscription.on(:delete) { |song| puts "Deleted: #{song.id}" }
+  #   subscription.on(:enter) { |song, original| puts "Entered query: #{song.title}" }
+  #   subscription.on(:leave) { |song, original| puts "Left query: #{song.title}" }
+  #
+  #   # Unsubscribe when done
+  #   subscription.unsubscribe
+  #
+  # @example Using Query directly
+  #   query = Song.query(:plays.gt => 1000)
+  #   subscription = query.subscribe
+  #
+  #   subscription.on_create { |song| puts "New popular song!" }
+  #   subscription.on_update { |song| puts "Song updated!" }
+  #
+  # @example Multiple subscriptions
+  #   client = Parse::LiveQuery.client
+  #
+  #   sub1 = client.subscribe(Song, where: { genre: "rock" })
+  #   sub2 = client.subscribe(Album, where: { year: 2024 })
+  #
+  #   # Close all subscriptions
+  #   client.close
+  #
+  module LiveQuery
+    # Base error class for LiveQuery. Inherits from Parse::Error so that
+    # `rescue Parse::Error` will also catch LiveQuery failures.
+    class Error < Parse::Error; end
+    class ConnectionError < Error; end
+    class SubscriptionError < Error; end
+    class AuthenticationError < Error; end
+
+    # Default LiveQuery events
+    EVENTS = %i[create update delete enter leave].freeze
+
+    # Error raised when LiveQuery is used but not enabled
+    class NotEnabledError < Error
+      def initialize
+        super("LiveQuery is experimental and must be explicitly enabled. Set Parse.live_query_enabled = true")
+      end
+    end
+  end
+end
+
+# Require components after module and error classes are defined
+require_relative "live_query/configuration"
+require_relative "live_query/logging"
+require_relative "live_query/event"
+require_relative "live_query/health_monitor"
+require_relative "live_query/circuit_breaker"
+require_relative "live_query/event_queue"
+require_relative "live_query/subscription"
+require_relative "live_query/client"
+
+module Parse
+  module LiveQuery
+    class << self
+      # @return [Parse::LiveQuery::Client] the default LiveQuery client
+      attr_accessor :default_client
+
+      # Check if LiveQuery feature is enabled
+      # @return [Boolean]
+      def enabled?
+        Parse.live_query_enabled?
+      end
+
+      # Ensure LiveQuery is enabled, raising an error if not
+      # @raise [NotEnabledError] if LiveQuery is not enabled
+      def ensure_enabled!
+        raise NotEnabledError unless enabled?
+      end
+
+      # Get or create the default LiveQuery client.
+      # Uses the configuration from Parse.setup if available.
+      # @return [Parse::LiveQuery::Client]
+      # @raise [NotEnabledError] if LiveQuery is not enabled
+      def client
+        ensure_enabled!
+        @default_client ||= Client.new
+      end
+
+      # Reset the default client (closes connection and clears instance)
+      def reset!
+        @default_client&.close
+        @default_client = nil
+      end
+
+      # Check if LiveQuery is configured and available
+      # @return [Boolean]
+      def available?
+        !!config.url
+      end
+
+      # Get the LiveQuery configuration object
+      # @return [Parse::LiveQuery::Configuration]
+      def config
+        @config ||= Configuration.new
+      end
+
+      # Configure LiveQuery settings using a block
+      # @yield [config] Configuration object
+      # @return [Configuration]
+      #
+      # @example
+      #   Parse::LiveQuery.configure do |config|
+      #     config.url = "wss://your-server.com"
+      #     config.ping_interval = 20.0
+      #     config.logging_enabled = true
+      #   end
+      def configure
+        yield config if block_given?
+
+        # Sync logging settings
+        if config.logging_enabled
+          Logging.enabled = true
+          Logging.log_level = config.log_level
+          Logging.logger = config.logger if config.logger
+        end
+
+        config
+      end
+
+      # Legacy configuration method for backward compatibility
+      # @deprecated Use configure block instead
+      # @return [Hash]
+      def configuration
+        {
+          url: config.url,
+          application_id: config.application_id,
+          client_key: config.client_key,
+          master_key: config.master_key,
+        }
+      end
+    end
+  end
+end

data/lib/parse/lookup_rewriter.rb

@@ -0,0 +1,445 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "model/model"
+require_relative "model/core/parse_reference"
+require_relative "pipeline_security"
+
+module Parse
+  # Translate "LLM-style" MongoDB `$lookup` stages -- expressed against logical
+  # Parse class names and pretty field names -- into the column-name form that
+  # Parse Server actually uses in MongoDB.
+  #
+  # An LLM trained on standard MongoDB syntax will produce a lookup like:
+  #
+  #   { "$lookup" => { "from" => "Project", "localField" => "project",
+  #                    "foreignField" => "_id", "as" => "project_doc" } }
+  #
+  # That never matches anything, because Parse stores the join column as
+  # `_p_project` (containing the pointer string `"Project$abc123"`) and the
+  # foreign `_id` is just `"abc123"`. When the foreign class declares
+  # `parse_reference`, the column `parseReference` mirrors the pointer-string
+  # form, so the join collapses to a single-field equality:
+  #
+  #   { "$lookup" => { "from" => "Project", "localField" => "_p_project",
+  #                    "foreignField" => "parseReference", "as" => "project_doc" } }
+  #
+  # When the foreign class does NOT declare `parse_reference`, the rewriter
+  # falls back to the `let`/`pipeline`/`$split` form that extracts the objectId
+  # from `_p_*` and matches it against the foreign `_id`.
+  #
+  # == Design
+  #
+  # The rewriter is intentionally a stand-alone helper, not auto-wired into
+  # `Parse::Query#aggregate` or `Parse::MongoDB.aggregate`. Existing SDK code
+  # writes `$lookup` against `_p_*`/`parseReference` directly and silently
+  # rewriting those would corrupt them. The intended consumer is the LLM
+  # tool dispatcher (`Parse::Agent::Tools.aggregate`) where pipelines are
+  # generated by a model that doesn't know Parse's storage layout.
+  #
+  # == What is rewritten
+  #
+  # For each `$lookup` stage with `localField` + `foreignField`:
+  #
+  # 1. **Forward join** (local class has `belongs_to :foo`):
+  #      localField: "foo" -> "_p_foo"
+  #      foreignField: "_id"|"objectId" -> "parseReference" (or $split fallback)
+  #
+  # 2. **Reverse join** (foreign class has `belongs_to` pointing back at us):
+  #      localField: "_id"|"objectId" -> "parseReference" (or $split fallback)
+  #      foreignField: "<pointer_name>" -> "_p_<pointer_name>"
+  #
+  # 3. **System class collection rename** (always applied):
+  #      from: "User" -> "_User"  (also _Role, _Installation, _Session)
+  #
+  # 4. **Sub-pipeline recursion**: `$lookup.pipeline`, `$unionWith.pipeline`,
+  #    and `$facet.*` are recursively rewritten with the foreign class (or
+  #    the original local class for `$facet`) as the new local context.
+  #
+  # == What is NOT rewritten
+  #
+  # - Stages already in `_p_*`/`parseReference` form (idempotency).
+  # - Lookups whose `localField` is neither a known belongs_to nor an identity
+  #   alias matched by a reverse belongs_to.
+  # - Lookups in `let`/`pipeline` form without a `localField`/`foreignField`
+  #   pair (those are constructed deliberately; only the `from` collection is
+  #   renamed and the sub-pipeline is recursed).
+  # - Embedded-pointer-array joins -- by user request, since the array entries
+  #   already carry `__type`/`className` and don't benefit from
+  #   `parseReference`. These fall through naturally because the join field
+  #   isn't a belongs_to on either side.
+  module LookupRewriter
+    module_function
+
+    # Logical-name -> Parse-on-Mongo collection-name aliases for the four
+    # system classes. The LLM will write `from: "User"`; Mongo wants `_User`.
+    SYSTEM_CLASS_MAP = {
+      "User" => Parse::Model::CLASS_USER,
+      "Installation" => Parse::Model::CLASS_INSTALLATION,
+      "Role" => Parse::Model::CLASS_ROLE,
+      "Session" => Parse::Model::CLASS_SESSION,
+    }.freeze
+
+    # Foreign-field values that an LLM might write to mean "the object's
+    # identity". Either is accepted as input; the rewriter substitutes
+    # the appropriate Parse-on-Mongo column.
+    OBJECT_ID_ALIASES = %w[_id objectId].freeze
+
+    # Parse-on-Mongo remote column name for the `parse_reference` DSL.
+    # Matches the default `field_map` entry produced by
+    # `property :parse_reference, :string, field: "parseReference"`.
+    PARSE_REFERENCE_REMOTE = "parseReference"
+
+    # Auto-rewrite a pipeline for one of the gem's three aggregation entry
+    # points (`Parse::Query#aggregate`, `Parse::MongoDB.aggregate`,
+    # `Parse::Agent::Tools.aggregate`). Resolves `class_name` to a
+    # `Parse::Object` subclass and forwards to {.rewrite} with
+    # `fallback: :preserve` -- the auto path only rewrites stages where the
+    # foreign class declares `parse_reference`, so SDK-generated pipelines
+    # (already in `_p_*`/`parseReference` form) and pipelines whose foreign
+    # class lacks `parse_reference` pass through unchanged.
+    #
+    # @param pipeline [Array<Hash>] the caller-supplied pipeline
+    # @param class_name [String, Symbol] the Parse class the aggregation runs against
+    # @param enabled [Boolean, nil] explicit override. `nil` (the default)
+    #   reads `Parse.rewrite_lookups`.
+    # @return [Array<Hash>] rewritten pipeline, or the input unchanged if
+    #   rewriting is disabled or the class can't be resolved.
+    def auto_rewrite(pipeline, class_name:, enabled: nil)
+      return pipeline unless pipeline.is_a?(Array)
+      flag = enabled.nil? ? Parse.rewrite_lookups : enabled
+      return pipeline unless flag
+      klass = Parse::Model.find_class(class_name.to_s) rescue nil
+      return pipeline unless klass
+      rewrite(pipeline, local_class: klass, fallback: :preserve)
+    end
+
+    # Walk a top-level pipeline and return a rewritten copy. Non-Array
+    # inputs are returned untouched.
+    #
+    # @param pipeline [Array<Hash>] aggregation pipeline
+    # @param local_class [Class<Parse::Object>] the class the outer aggregation
+    #   is running against. Used to resolve forward `belongs_to` pointer
+    #   fields and to compute its own `parseReference` for reverse joins.
+    # @param fallback [Symbol] what to do when a lookup is rewriteable in
+    #   shape (matches a `belongs_to`) but the target class lacks
+    #   `parse_reference`:
+    #   - `:split` (default) -- emit the `let`/`pipeline`/`$split` form.
+    #     Always produces a working join.
+    #   - `:preserve` -- leave the stage alone. Use when the caller wants
+    #     the rewriter to act only as an optimization, not as a
+    #     correction. This is the mode used by the gem's auto-wired
+    #     paths so SDK-generated pipelines (which the rewriter shouldn't
+    #     second-guess) survive untouched.
+    # @return [Array<Hash>] a new pipeline with eligible `$lookup` stages
+    #   rewritten. The input is not mutated.
+    def rewrite(pipeline, local_class:, fallback: :split)
+      return pipeline unless pipeline.is_a?(Array)
+      pipeline.map { |stage| rewrite_stage(stage, local_class: local_class, fallback: fallback) }
+    end
+
+    # Rewrite a single stage. Stages that are not `$lookup`/`$unionWith`/
+    # `$facet` are returned unchanged. Sub-pipelines inside those three are
+    # rewritten recursively.
+    def rewrite_stage(stage, local_class:, fallback: :split)
+      return stage unless stage.is_a?(Hash)
+      stage.each_with_object({}) do |(key, value), out|
+        case key.to_s
+        when "$lookup"
+          out[key] = rewrite_lookup(value, local_class: local_class, fallback: fallback)
+        when "$graphLookup"
+          out[key] = rewrite_graph_lookup(value, local_class: local_class)
+        when "$unionWith"
+          out[key] = rewrite_union_with(value, local_class: local_class, fallback: fallback)
+        when "$facet"
+          out[key] = rewrite_facet(value, local_class: local_class, fallback: fallback)
+        else
+          out[key] = value
+        end
+      end
+    end
+
+    # `$graphLookup` doesn't accept a `pipeline:` form, only `from:`,
+    # `startWith:`, `connectFromField:`, `connectToField:`, `as:`, plus a
+    # few options. We rewrite only the collection name (system-class
+    # alias) here. Pointer-style `_p_*`/parseReference equality across the
+    # connect-fields would require knowing both fields are pointer columns
+    # on both sides -- the typical $graphLookup use cases (recursive
+    # hierarchies over the same collection) don't need it. Document this
+    # so callers using $graphLookup against tagged pointer columns supply
+    # the Parse-on-Mongo column names themselves.
+    def rewrite_graph_lookup(spec, local_class:)
+      return spec unless spec.is_a?(Hash)
+      from_logical = read_string(spec, "from")
+      from_collection = canonical_collection_name(from_logical)
+      Parse::PipelineSecurity.assert_collection_allowed!(from_collection)
+      rename_collection_only(spec, from_logical, from_collection)
+    end
+
+    # Rewrite a single `$lookup` spec.
+    def rewrite_lookup(spec, local_class:, fallback: :split)
+      return spec unless spec.is_a?(Hash)
+      from_logical = read_string(spec, "from")
+      from_collection = canonical_collection_name(from_logical)
+      Parse::PipelineSecurity.assert_collection_allowed!(from_collection)
+      target_class = resolve_class(from_logical) || resolve_class(from_collection)
+
+      # let/pipeline shape -- only fix collection name and recurse into the
+      # sub-pipeline using the foreign class as its local context.
+      if has_key?(spec, "pipeline") && !has_key?(spec, "localField")
+        return rewrite_let_pipeline_form(spec, from_logical, from_collection, target_class, fallback)
+      end
+
+      local_field = read_string(spec, "localField")
+      foreign_field = read_string(spec, "foreignField")
+      return rename_collection_only(spec, from_logical, from_collection) unless local_field && foreign_field
+
+      # Already in Parse-on-Mongo form -- leave untouched aside from the
+      # system-class collection rename.
+      if local_field.start_with?("_p_") || foreign_field == PARSE_REFERENCE_REMOTE
+        return rename_collection_only(spec, from_logical, from_collection)
+      end
+
+      forward_field = resolve_forward_pointer(local_class, local_field)
+      if forward_field && OBJECT_ID_ALIASES.include?(foreign_field)
+        if foreign_has_parse_reference?(target_class)
+          return build_forward_rewrite(spec, forward_field, target_class, from_logical, from_collection)
+        elsif fallback == :split
+          return build_forward_rewrite(spec, forward_field, target_class, from_logical, from_collection)
+        else
+          return rename_collection_only(spec, from_logical, from_collection)
+        end
+      end
+
+      reverse_field = resolve_reverse_pointer(target_class, foreign_field, local_class)
+      if reverse_field && OBJECT_ID_ALIASES.include?(local_field)
+        if foreign_has_parse_reference?(local_class)
+          return build_reverse_rewrite(spec, reverse_field, local_class, from_logical, from_collection)
+        elsif fallback == :split
+          return build_reverse_rewrite(spec, reverse_field, local_class, from_logical, from_collection)
+        else
+          return rename_collection_only(spec, from_logical, from_collection)
+        end
+      end
+
+      rename_collection_only(spec, from_logical, from_collection)
+    end
+
+    # ---------------------------------------------------------------------
+    # Forward / reverse builders
+    # ---------------------------------------------------------------------
+
+    # Local: { _p_<field>: "Foreign$abc" }   Foreign: { parseReference: "Foreign$abc" }
+    # When parse_reference is declared on the foreign class -> direct equality.
+    # Otherwise -> let/pipeline with $split extracting the objectId.
+    def build_forward_rewrite(spec, pointer_field, target_class, from_logical, from_collection)
+      mongo_local = "_p_#{pointer_field}"
+      if foreign_has_parse_reference?(target_class)
+        replace_keys(spec,
+                    "from" => from_collection,
+                    "localField" => mongo_local,
+                    "foreignField" => PARSE_REFERENCE_REMOTE)
+      else
+        as_value = read_string(spec, "as")
+        let_var = "rwLookupId_#{pointer_field}"
+        spec_without_pair = drop_keys(spec, %w[localField foreignField pipeline let from])
+        spec_without_pair["from"] = from_collection
+        spec_without_pair["let"] = {
+          let_var => { "$arrayElemAt" => [{ "$split" => ["$#{mongo_local}", { "$literal" => "$" }] }, 1] },
+        }
+        spec_without_pair["pipeline"] = [
+          { "$match" => { "$expr" => { "$eq" => ["$_id", "$$#{let_var}"] } } },
+        ]
+        spec_without_pair["as"] = as_value if as_value
+        spec_without_pair
+      end
+    end
+
+    # Local: { parseReference: "Local$abc" }  Foreign: { _p_<field>: "Local$abc" }
+    # When parse_reference is declared on the LOCAL class -> direct equality.
+    # Otherwise -> let/pipeline with $split on the foreign side.
+    def build_reverse_rewrite(spec, pointer_field, local_class, from_logical, from_collection)
+      mongo_foreign = "_p_#{pointer_field}"
+      if foreign_has_parse_reference?(local_class)
+        replace_keys(spec,
+                    "from" => from_collection,
+                    "localField" => PARSE_REFERENCE_REMOTE,
+                    "foreignField" => mongo_foreign)
+      else
+        as_value = read_string(spec, "as")
+        let_var = "rwReverseId_#{pointer_field}"
+        spec_without_pair = drop_keys(spec, %w[localField foreignField pipeline let from])
+        spec_without_pair["from"] = from_collection
+        spec_without_pair["let"] = { let_var => "$_id" }
+        spec_without_pair["pipeline"] = [
+          { "$match" => { "$expr" => {
+            "$eq" => [
+              { "$arrayElemAt" => [{ "$split" => ["$#{mongo_foreign}", { "$literal" => "$" }] }, 1] },
+              "$$#{let_var}",
+            ],
+          } } },
+        ]
+        spec_without_pair["as"] = as_value if as_value
+        spec_without_pair
+      end
+    end
+
+    # ---------------------------------------------------------------------
+    # Stage helpers
+    # ---------------------------------------------------------------------
+
+    def rewrite_union_with(spec, local_class:, fallback: :split)
+      case spec
+      when Hash
+        from_logical = read_string(spec, "from") || read_string(spec, "coll")
+        from_collection = canonical_collection_name(from_logical)
+        Parse::PipelineSecurity.assert_collection_allowed!(from_collection)
+        target_class = resolve_class(from_logical) || resolve_class(from_collection)
+        out = spec.dup
+        # Either form (from: or coll:) is valid for $unionWith; rename if it's a system class.
+        rename_collection_in_place!(out, from_logical, from_collection)
+        if has_key?(spec, "pipeline") && target_class
+          out[match_original_key(spec, "pipeline")] = rewrite(read_value(spec, "pipeline"), local_class: target_class, fallback: fallback)
+        end
+        out
+      when String
+        canonical = canonical_collection_name(spec) || spec
+        Parse::PipelineSecurity.assert_collection_allowed!(canonical)
+        canonical
+      else
+        spec
+      end
+    end
+
+    def rewrite_facet(spec, local_class:, fallback: :split)
+      return spec unless spec.is_a?(Hash)
+      spec.each_with_object({}) do |(key, sub_pipeline), out|
+        out[key] = rewrite(sub_pipeline, local_class: local_class, fallback: fallback)
+      end
+    end
+
+    def rewrite_let_pipeline_form(spec, from_logical, from_collection, target_class, fallback = :split)
+      out = spec.dup
+      rename_collection_in_place!(out, from_logical, from_collection)
+      if has_key?(spec, "pipeline") && target_class
+        out[match_original_key(spec, "pipeline")] = rewrite(read_value(spec, "pipeline"), local_class: target_class, fallback: fallback)
+      end
+      out
+    end
+
+    # ---------------------------------------------------------------------
+    # Class / field resolution
+    # ---------------------------------------------------------------------
+
+    def resolve_class(name)
+      return nil if name.nil? || name.to_s.empty?
+      # `find_class` already accepts both alias and canonical forms (`User`
+      # and `_User` both resolve `Parse::User`) via its `parse_class == "_#{str}"`
+      # branch, so the SYSTEM_CLASS_MAP rename here is redundant on the
+      # input side -- it's still applied separately to the rewritten `from:`
+      # value via `rename_collection_in_place!`.
+      Parse::Model.find_class(name.to_s)
+    end
+
+    def canonical_collection_name(name)
+      return nil if name.nil?
+      SYSTEM_CLASS_MAP[name.to_s] || name.to_s
+    end
+
+    # Returns the matching pointer field SYMBOL on the local class for the
+    # given logical local-field name, or nil.
+    def resolve_forward_pointer(local_class, local_field)
+      return nil unless local_class && local_class.respond_to?(:references)
+      sym = local_field.to_sym
+      return sym if local_class.references.key?(sym)
+      camel = local_field.to_s.camelize(:lower).to_sym
+      return camel if local_class.references.key?(camel)
+      nil
+    end
+
+    # Returns the matching pointer field SYMBOL on the FOREIGN class for the
+    # given foreign-field name when that pointer points back at local_class,
+    # or nil.
+    def resolve_reverse_pointer(target_class, foreign_field, local_class)
+      return nil unless target_class && target_class.respond_to?(:references)
+      return nil unless local_class.respond_to?(:parse_class)
+      candidates = [foreign_field.to_sym, foreign_field.to_s.camelize(:lower).to_sym].uniq
+      candidates.each do |sym|
+        klass_name = target_class.references[sym]
+        return sym if klass_name && klass_name == local_class.parse_class
+      end
+      nil
+    end
+
+    def foreign_has_parse_reference?(klass)
+      klass.respond_to?(:_parse_reference_fields) && Array(klass._parse_reference_fields).any?
+    end
+
+    # ---------------------------------------------------------------------
+    # Hash key utilities -- preserve original string-vs-symbol key style
+    # ---------------------------------------------------------------------
+
+    def read_string(spec, name)
+      v = read_value(spec, name)
+      v.nil? ? nil : v.to_s
+    end
+
+    def read_value(spec, name)
+      return spec[name] if spec.key?(name)
+      sym = name.to_sym
+      return spec[sym] if spec.key?(sym)
+      str = name.to_s
+      return spec[str] if spec.key?(str)
+      nil
+    end
+
+    def has_key?(spec, name)
+      spec.key?(name) || spec.key?(name.to_sym) || spec.key?(name.to_s)
+    end
+
+    # Find the actual key object (String or Symbol) the spec uses for `name`,
+    # so we can write back without changing the caller's key style. Returns
+    # `name` itself if not present.
+    def match_original_key(spec, name)
+      [name, name.to_sym, name.to_s].each { |k| return k if spec.key?(k) }
+      name
+    end
+
+    def replace_keys(spec, replacements)
+      out = spec.dup
+      replacements.each do |name, value|
+        key = match_original_key(spec, name)
+        out.delete(name)
+        out.delete(name.to_sym)
+        out.delete(name.to_s)
+        out[key] = value
+      end
+      out
+    end
+
+    def drop_keys(spec, names)
+      out = spec.dup
+      names.each do |name|
+        out.delete(name)
+        out.delete(name.to_sym)
+        out.delete(name.to_s)
+      end
+      out
+    end
+
+    def rename_collection_in_place!(out, from_logical, from_collection)
+      return if from_logical.nil? || from_collection.nil? || from_collection == from_logical
+      # Match either `from:` or `coll:` style key, preserving its string/symbol form.
+      %w[from coll].each do |k|
+        next unless out.key?(k) || out.key?(k.to_sym)
+        key = match_original_key(out, k)
+        out[key] = from_collection
+      end
+    end
+
+    def rename_collection_only(spec, from_logical, from_collection)
+      return spec unless from_logical && from_collection && from_collection != from_logical
+      replace_keys(spec, "from" => from_collection)
+    end
+  end
+end