parse-stack-next 5.0.0 → 5.1.0

data/lib/parse/model/classes/user.rb

@@ -225,6 +225,24 @@ module Parse
     # @return [Array<Parse::Session>] A list of active Parse::Session objects.
     has_many :active_sessions, as: :session
 
+    # @!attribute installations
+    # A `has_many` query-form association resolving to all
+    # {Parse::Installation} records whose `user` pointer is this user.
+    # Useful for targeted push — e.g. sending a notification to every
+    # device the user is signed into. This is a query (no column is
+    # stored on `_User`); each access issues a `find` against
+    # `_Installation` for `where(user: self)`.
+    #
+    # **Requires a master-key client.** Parse Server hardcodes
+    # `_Installation` `find` to master-key-only at the REST layer, so
+    # this association will return an empty array (or fail-closed
+    # depending on agent scope) under a session-token-only / sessionless
+    # client. The `user` pointer is also not a reliable owner identity
+    # — devices outlive sessions and can change users — see
+    # {Parse::Installation} for the full caveat list.
+    # @return [Array<Parse::Installation>]
+    has_many :installations, as: :installation
+
     # CHANGE -- ACLs can be managed
     # before_save do
     #   # You cannot specify user ACLs.
@@ -278,6 +296,192 @@ module Parse
       def authdata_trusted?
         Thread.current[AUTHDATA_TRUST_KEY] == true
       end
+
+      # =========================================================================
+      # Field-visibility DSL for _User
+      # =========================================================================
+      #
+      # `_User` has two field-visibility flavors that vanilla
+      # {Parse::Object.protect_fields} can't express on its own because
+      # Parse Server's `protectedFieldsOwnerExempt` option special-cases
+      # the owning user (the user sees their own row in full unless the
+      # option is disabled). These helpers wrap that pattern.
+      #
+      # ## Prerequisites
+      #
+      # 1. Set `protectedFieldsOwnerExempt: false` in your Parse Server
+      #    startup options. With the historical default `true`, the owning
+      #    user is silently exempted from every `protectedFields` rule on
+      #    `_User`, so {.master_only_fields} would still be visible to the
+      #    user themselves. Parse Server's default for this option is
+      #    changing to `false` in a future version; until your server
+      #    adopts that default you must set it explicitly.
+      # 2. For {.self_visible_fields}: add a self-pointer field on `_User`
+      #    that points to the same user, and maintain it from a
+      #    `beforeSave('_User')` Cloud Code trigger:
+      #
+      #    ```js
+      #    Parse.Cloud.beforeSave(Parse.User, (req) => {
+      #      const u = req.object;
+      #      if (!u.get('self')) u.set('self', u);  // self-pointer
+      #    });
+      #    ```
+      #
+      # The SDK cannot install either of those — they're server-side
+      # configuration — but the helpers below will warn if they detect
+      # they're being mis-applied.
+
+      # Hide one or more fields from query/get responses for **all**
+      # non-master callers, including the owning user themselves.
+      # Useful for admin-only metadata living on `_User`
+      # (e.g. internal scoring, moderation notes).
+      #
+      # Requires Parse Server option `protectedFieldsOwnerExempt: false`.
+      # With the default `true`, the owning user still sees these fields
+      # on their own row.
+      #
+      # @param fields [Array<Symbol,String>] field names. Use snake_case
+      #   Ruby property names; they're auto-converted to camelCase.
+      # @return [Array<Symbol>] full master-only field list after this call.
+      # @example
+      #   class Parse::User
+      #     property :my_opinion_of_them, :string
+      #     master_only_fields :my_opinion_of_them
+      #   end
+      def master_only_fields(*fields)
+        @master_only_fields ||= []
+        @master_only_fields = (@master_only_fields + fields.flatten.map(&:to_sym)).uniq
+        _warn_about_owner_exempt_prereq!
+        _rebuild_user_protected_fields!
+        @master_only_fields.dup
+      end
+
+      # Hide one or more fields from public/role/other-user callers, but
+      # allow the **owning user** to see them. Useful for private profile
+      # data that belongs to the user (e.g. preferences, private notes).
+      #
+      # Requires:
+      # * Parse Server option `protectedFieldsOwnerExempt: false`.
+      # * A self-pointer field on `_User` (named via `via:`, default
+      #   `:self`) that is set to the row's own pointer by a
+      #   `beforeSave('_User')` Cloud Code trigger.
+      #
+      # @param fields [Array<Symbol,String>] field names. snake_case OK.
+      # @param via [Symbol,String] name of the self-pointer field on
+      #   `_User` (default `:self`).
+      # @return [Array<Symbol>]
+      # @example
+      #   class Parse::User
+      #     property :favorite_color, :string
+      #     self_visible_fields :favorite_color, via: :self
+      #   end
+      def self_visible_fields(*fields, via: :self)
+        @self_visible_fields ||= []
+        @self_visible_fields = (@self_visible_fields + fields.flatten.map(&:to_sym)).uniq
+        @self_pointer_field = via.to_sym
+        _warn_about_owner_exempt_prereq!
+        _warn_about_self_pointer_prereq!(via)
+        _rebuild_user_protected_fields!
+        @self_visible_fields.dup
+      end
+
+      # Override {Parse::Object.protect_fields} on `_User` so that ad-hoc
+      # uses (i.e. not through {.master_only_fields} /
+      # {.self_visible_fields}) emit a one-time advisory pointing at the
+      # higher-level helpers and the `protectedFieldsOwnerExempt` flag.
+      # The behavior is otherwise unchanged.
+      def protect_fields(pattern, fields)
+        _warn_about_user_protect_fields! unless @_user_field_dsl_active
+        super
+      end
+
+      # @!visibility private
+      def _rebuild_user_protected_fields!
+        @master_only_fields  ||= []
+        @self_visible_fields ||= []
+        pointer = @self_pointer_field || :self
+        all_hidden = (@master_only_fields + @self_visible_fields).uniq
+
+        @_user_field_dsl_active = true
+        begin
+          protect_fields("*", all_hidden) unless all_hidden.empty?
+          unless @self_visible_fields.empty?
+            protect_fields("userField:#{pointer}", @master_only_fields)
+          end
+        ensure
+          @_user_field_dsl_active = false
+        end
+      end
+
+      # @!visibility private
+      def _warn_about_user_protect_fields!
+        return if @_user_protect_fields_warned
+        @_user_protect_fields_warned = true
+        _emit_user_field_advisory(
+          "[Parse::User] protect_fields was called directly on _User. " \
+          "For master-only and owner-visible field patterns prefer " \
+          "`Parse::User.master_only_fields` and `Parse::User.self_visible_fields`. " \
+          "Either way, ensure Parse Server is started with " \
+          "`protectedFieldsOwnerExempt: false` (the historical default `true` — " \
+          "changing to `false` in a future Parse Server version — exempts the " \
+          "owning user from every protectedFields rule on _User, which silently " \
+          "negates these protections for the user's own row).",
+        )
+      end
+
+      # @!visibility private
+      # Fires once when `master_only_fields` / `self_visible_fields` is first
+      # used. Without `protectedFieldsOwnerExempt: false` in Parse Server's
+      # startup options, neither helper does what its name promises -- the
+      # default `true` silently exempts the owning user from every
+      # protectedFields rule on _User. The SDK can't introspect Parse
+      # Server's startup options, so we surface this as a one-time advisory
+      # at declaration time so it's loud enough to catch before deploy.
+      def _warn_about_owner_exempt_prereq!
+        return if @_owner_exempt_warned
+        @_owner_exempt_warned = true
+        _emit_user_field_advisory(
+          "[Parse::User] master_only_fields / self_visible_fields require " \
+          "Parse Server option `protectedFieldsOwnerExempt: false`. With the " \
+          "historical default `true`, the owning user is silently exempted " \
+          "from every protectedFields rule on _User, so a field declared " \
+          "master-only would still be visible to the user themselves on their " \
+          "own row. Parse Server's default for this option is changing to " \
+          "`false` in a future version (which makes these helpers work " \
+          "without extra config), but until your server adopts that default " \
+          "you must set `protectedFieldsOwnerExempt: false` in your " \
+          "ParseServer options BEFORE deploying. See docs/acl_clp_guide.md §4.2.",
+        )
+      end
+
+      # @!visibility private
+      # Fires once when `self_visible_fields` is first used. The Parse
+      # Server side requires (a) a self-pointer field on _User populated
+      # by a beforeSave('_User') trigger, AND (b) a one-shot backfill on
+      # any pre-existing user rows so the pointer is set before the
+      # `userField:<via>` group matches them.
+      def _warn_about_self_pointer_prereq!(via)
+        return if @_self_pointer_warned
+        @_self_pointer_warned = true
+        _emit_user_field_advisory(
+          "[Parse::User] self_visible_fields(via: :#{via}) requires a " \
+          "self-pointer field named `#{via}` on _User pointing at the same " \
+          "row, populated by a beforeSave('_User') Cloud Code trigger. " \
+          "Existing user rows ALSO need a one-shot backfill (the trigger " \
+          "only fires on save) -- without it, those rows never match the " \
+          "`userField:#{via}` group and the field stays hidden from the " \
+          "user themselves. See docs/acl_clp_guide.md §4.2.",
+        )
+      end
+
+      # @!visibility private
+      def _emit_user_field_advisory(msg)
+        if Parse.respond_to?(:logger) && Parse.logger
+          Parse.logger.warn(msg)
+        else
+          Kernel.warn(msg)
+        end
+      end
     end
 
     # @!visibility private

data/lib/parse/model/core/create_lock.rb

@@ -6,6 +6,7 @@ require "openssl"
 require "json"
 require "securerandom"
 require "monitor"
+require_relative "../../lock_backend"
 
 module Parse
   # Mutual-exclusion primitive for `first_or_create!` / `create_or_update!` to
@@ -70,25 +71,29 @@ module Parse
           master_key: master_key,
         )
 
-        store = lock_store
-        if degraded_store?(store)
-          handle_degraded(on_degraded, key)
-          return process_mutex(key).synchronize(&block)
+        store = LockBackend.lock_store
+        if LockBackend.degraded_store?(store)
+          LockBackend.handle_degraded(
+            on_degraded, key,
+            source: "Parse::CreateLock",
+            unavailable_error: Parse::CreateLockUnavailableError,
+          )
+          return LockBackend.process_mutex(key).synchronize(&block)
         end
 
         owner = SecureRandom.uuid
         acquired_at = nil
-        start = monotonic_now
+        start = LockBackend.monotonic_now
 
         loop do
-          if try_acquire(store, key, owner, ttl)
-            acquired_at = monotonic_now
+          if LockBackend.try_acquire(store, key, owner, ttl)
+            acquired_at = LockBackend.monotonic_now
             wait_ms = ((acquired_at - start) * 1000).round
             instrument("acquired", key, wait_ms: wait_ms)
             break
           end
 
-          elapsed = monotonic_now - start
+          elapsed = LockBackend.monotonic_now - start
           if elapsed >= wait
             waited_ms = (elapsed * 1000).round
             instrument("timeout", key, waited_ms: waited_ms)
@@ -96,15 +101,15 @@ module Parse
                   "Could not acquire create-lock for #{parse_class} within #{wait}s"
           end
           instrument("contended", key, elapsed_ms: (elapsed * 1000).round) if elapsed > 0
-          sleep(poll_interval)
+          sleep(LockBackend.poll_interval)
         end
 
         begin
           yield
         ensure
           if acquired_at
-            release(store, key, owner)
-            held_ms = ((monotonic_now - acquired_at) * 1000).round
+            LockBackend.release(store, key, owner)
+            held_ms = ((LockBackend.monotonic_now - acquired_at) * 1000).round
             instrument("released", key, held_ms: held_ms)
           end
         end
@@ -123,7 +128,7 @@ module Parse
                 "synchronize key payload exceeds #{MAX_PAYLOAD_BYTES} bytes (got #{payload.bytesize})"
         end
 
-        secret = lock_secret_for(store: lock_store)
+        secret = lock_secret_for(store: LockBackend.lock_store)
         digest = if secret
             OpenSSL::HMAC.hexdigest("SHA256", secret, payload)
           else
@@ -134,23 +139,14 @@ module Parse
 
       # @!visibility private
       def reset!
-        @auto_secret = nil
-        @plain_sha_warned = nil
-        @degraded_warned_at = nil
-        @process_mutex_registry = nil
+        # All resettable state lives on Parse::LockBackend now —
+        # @degraded_warned_at, @process_mutex_registry, @auto_secret,
+        # @plain_sha_warned. v5.1.0 extraction.
+        LockBackend.reset!
       end
 
       private
 
-      def lock_store
-        if Parse.respond_to?(:synchronize_create_store) && Parse.synchronize_create_store
-          return Parse.synchronize_create_store
-        end
-        Parse.cache
-      rescue Parse::Error::ConnectionError
-        nil
-      end
-
       def parse_application_id
         Parse.client.application_id
       rescue Parse::Error::ConnectionError
@@ -253,121 +249,19 @@ module Parse
         end
       end
 
-      def degraded_store?(store)
-        return true if store.nil?
-        bottom = walk_to_adapter(store)
-        return true if bottom.nil?
-        klass_name = bottom.class.name.to_s
-        klass_name.include?("Memory") || klass_name.include?("Null")
-      end
-
-      def walk_to_adapter(store)
-        current = store
-        # Walk transformer chain to find bottom Moneta adapter
-        while current.respond_to?(:adapter) && current.adapter && current.adapter != current
-          current = current.adapter
-        end
-        current
-      end
-
-      def handle_degraded(mode, key)
-        case mode
-        when :raise
-          raise Parse::CreateLockUnavailableError,
-                "synchronize requires a cross-process cache store (Redis); current store is process-local"
-        when :proceed
-          # silent
-        when :warn_throttled
-          now = monotonic_now
-          if @degraded_warned_at.nil? || (now - @degraded_warned_at) >= DEGRADED_WARNING_THROTTLE_SECONDS
-            @degraded_warned_at = now
-            warn "[Parse::CreateLock] Lock store is process-local (Moneta Memory/Null). " \
-                 "Cross-process locking is NOT in effect. Configure a Redis-backed cache to enable distributed locking."
-          end
-        else # :warn (default)
-          warn "[Parse::CreateLock] Lock store is process-local; cross-process locking disabled. " \
-               "key_digest=#{key[KEY_PREFIX.size, 12]}…"
-        end
-      end
-
-      def try_acquire(store, key, owner, ttl)
-        # Trigger lazy TTL sweep on Moneta::Memory before #create (no-op on Redis).
-        # Without this, Memory adapter returns false on #create even after TTL expiry
-        # until a #key? or #[] access flushes the stale entry.
-        store.key?(key)
-        store.create(key, owner, expires: ttl)
-      rescue StandardError => e
-        warn "[Parse::CreateLock] acquire error (#{e.class}): #{e.message}"
-        false
-      end
-
-      def release(store, key, owner)
-        # Best-effort compare-and-delete. Moneta does not expose atomic CAD;
-        # the worst-case race here is bounded by the short TTL (default #{DEFAULT_TTL}s).
-        current = store[key]
-        store.delete(key) if current == owner
-      rescue StandardError => e
-        warn "[Parse::CreateLock] release error (#{e.class}): #{e.message}"
-      end
-
-      def poll_interval
-        DEFAULT_POLL_BASE + (rand * 2 - 1) * DEFAULT_POLL_JITTER
-      end
-
-      def monotonic_now
-        Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      end
+      # All the lock infrastructure — store discovery, degraded
+      # detection, atomic-SETNX, release semantics, poll-interval
+      # jitter, process-mutex registry, AND HMAC secret resolution —
+      # lives on {Parse::LockBackend} now (v5.1.0 extraction). The
+      # only CreateLock-specific helper still here is `clamp` for
+      # the public API's input range.
 
       def clamp(value, lo, hi)
         [lo, value, hi].sort[1]
       end
 
-      def process_mutex(key)
-        @process_mutex_registry_lock ||= Mutex.new
-        @process_mutex_registry_lock.synchronize do
-          @process_mutex_registry ||= {}
-          @process_mutex_registry[key] ||= Mutex.new
-        end
-      end
-
       def lock_secret_for(store:)
-        configured = configured_secret
-        return configured if configured && !configured.empty?
-
-        # No operator-configured secret. Behavior depends on store type:
-        # - Memory/Null adapter: locking is already process-local, so a
-        #   per-process auto-derived HMAC secret is fine and preserves
-        #   privacy in tests / single-process deployments.
-        # - Redis (or any cross-process store): a per-process secret would
-        #   break cross-process key equality, defeating the lock. Fall back
-        #   to plain SHA256 with a one-time warning so operators know to
-        #   harden key material.
-        if degraded_store?(store)
-          auto_secret
-        else
-          warn_plain_sha_once
-          nil
-        end
-      end
-
-      def configured_secret
-        if Parse.respond_to?(:synchronize_create_secret) && Parse.synchronize_create_secret
-          return Parse.synchronize_create_secret.to_s
-        end
-        ENV["PARSE_STACK_LOCK_SECRET"]
-      end
-
-      def auto_secret
-        @auto_secret ||= SecureRandom.hex(32)
-      end
-
-      def warn_plain_sha_once
-        return if @plain_sha_warned
-        @plain_sha_warned = true
-        warn "[Parse::CreateLock:SECURITY] No PARSE_STACK_LOCK_SECRET configured and Redis-backed store detected. " \
-             "Falling back to plain SHA256 for lock-key derivation so cross-process locking actually works. " \
-             "Lock keys are deterministic and may expose query_attrs content via Redis MONITOR/snapshots. " \
-             "Set PARSE_STACK_LOCK_SECRET (or Parse.synchronize_create_secret = '…') to enable HMAC keying."
+        LockBackend.lock_secret_for(store: store, source: "Parse::CreateLock")
       end
 
       def instrument(event, key, payload = {})

data/lib/parse/model/core/embed_managed.rb

@@ -88,18 +88,34 @@ module Parse
       # field write; the guard is otherwise closed.
       WRITER_KEY = :parse_embed_managed_writer
 
-      # Frozen value-object capturing one `embed` declaration. Stored on
-      # the owning class under `embed_directives[into]` and passed to
+      # Frozen value-object capturing one `embed` or `embed_image`
+      # declaration. Stored on the owning class under
+      # `embed_directives[into]` and passed to
       # {EmbedManaged.recompute_embedding!} from the per-class
       # before_save callback.
+      #
+      # `modality` is `nil` (treated as `:text`) for {.embed}-declared
+      # directives and `:image` for {.embed_image}. The image path
+      # routes through `Parse::Embeddings.validate_image_url!` and
+      # `Provider#embed_image` rather than `Provider#embed_text`;
+      # digest tracking is over the file URL String rather than the
+      # concatenated source text.
+      #
+      # `allow_insecure` is forwarded to {.validate_image_url!} for
+      # image directives only; ignored for text.
       EmbedDirective = Struct.new(
         :sources, :into, :digest_field, :input_type, :provider_name,
+        :modality, :allow_insecure,
         keyword_init: true,
       ) do
         def freeze
           sources.freeze
           super
         end
+
+        def image?
+          modality == :image
+        end
       end
 
       # @!visibility private
@@ -186,6 +202,99 @@ module Parse
           into
         end
 
+        # Declare a managed image embedding. Mirrors {.embed} but the
+        # source field is a `:file` property (Parse::File) and the
+        # provider call routes through {Parse::Embeddings::Provider#embed_image}
+        # rather than `#embed_text`. v5.1 ships URL-only: the SDK
+        # extracts the file's URL, validates it through
+        # {Parse::Embeddings.validate_image_url!} (sentinel-gated egress
+        # opt-in, CIDR / port / host allowlist), and forwards the
+        # canonicalized URL to the provider. The SDK does NOT download
+        # image bytes — bytes-fetch is the v5.3 path.
+        #
+        # **Digest is the URL string, not the file contents.** Replacing
+        # the Parse::File with one pointing to a different URL re-embeds;
+        # re-saving the same URL is a no-op (zero provider calls).
+        # Cloud-stored Parse files have stable URLs unless overwritten,
+        # so this is the right cache key for most uploads. If you mutate
+        # the underlying bytes at the SAME URL (e.g. PUT-replace on S3
+        # without renaming), the embedding will NOT refresh; rename the
+        # file or set `:#{into}_digest` to nil and resave to force re-embed.
+        #
+        # @param source_field [Symbol] one `:file` property whose URL
+        #   feeds the provider. (v5.1 accepts a single source per
+        #   directive; multi-image-per-record support is deferred.)
+        # @param into [Symbol] the `:vector` property to populate.
+        #   Must already be declared with `provider:` metadata.
+        # @param input_type [Symbol] forwarded to {Provider#embed_image}.
+        #   Defaults to `:search_document`.
+        # @param digest_field [Symbol, nil] override for the URL-digest
+        #   sibling. Defaults to `:"#{into}_digest"`. Auto-declared as
+        #   `:string` if not already declared.
+        # @param allow_insecure [Boolean] forwarded to
+        #   {Parse::Embeddings.validate_image_url!}; permit `http://`
+        #   for local-dev CDN proxies. Default false.
+        # @return [Symbol] the target vector field name.
+        # @raise [InvalidEmbedDeclaration] on declaration-time misuse.
+        def embed_image(source_field, into:, input_type: :search_document,
+                        digest_field: nil, allow_insecure: false)
+          into = into.to_sym
+          unless vector_properties.key?(into)
+            raise InvalidEmbedDeclaration,
+                  "#{self}.embed_image: `into: :#{into}` is not a declared :vector property " \
+                  "(declared :vector fields: #{vector_properties.keys.inspect})."
+          end
+          provider_name = vector_properties.dig(into, :provider)
+          if provider_name.nil?
+            raise InvalidEmbedDeclaration,
+                  "#{self}.embed_image: `into: :#{into}` has no `provider:` declared on its " \
+                  ":vector property. Add `provider: :voyage` (or another registered name) " \
+                  "to the property declaration."
+          end
+
+          source = source_field.to_sym
+          unless fields.key?(source)
+            raise InvalidEmbedDeclaration,
+                  "#{self}.embed_image: source field #{source.inspect} is not declared on this class."
+          end
+          unless fields[source] == :file
+            raise InvalidEmbedDeclaration,
+                  "#{self}.embed_image: source field #{source.inspect} must be a :file property " \
+                  "(got #{fields[source].inspect}). v5.1 image embedding accepts Parse::File " \
+                  "sources only — text sources go through `embed`."
+          end
+
+          digest_field = (digest_field || :"#{into}_digest").to_sym
+          unless fields.key?(digest_field)
+            property digest_field, :string
+          end
+
+          directive = EmbedDirective.new(
+            sources: [source],
+            into: into,
+            digest_field: digest_field,
+            input_type: input_type,
+            provider_name: provider_name,
+            modality: :image,
+            allow_insecure: allow_insecure,
+          ).freeze
+          embed_directives[into] = directive
+
+          callback_method = :"_auto_embed_#{into}!"
+          define_method(callback_method) do
+            Parse::Core::EmbedManaged.recompute_embedding!(self, directive)
+          end
+
+          already_registered = _save_callbacks.any? do |cb|
+            cb.kind == :before && (cb.filter.to_sym rescue cb.filter) == callback_method
+          end
+          before_save callback_method unless already_registered
+
+          install_embed_writer_guard!(into, [source])
+
+          into
+        end
+
         # @!visibility private
         # Prepend a module that intercepts the public `<into>=` setter
         # and raises {ProtectedFieldError} unless the current thread has
@@ -225,19 +334,19 @@ module Parse
       end
 
       # @!visibility private
-      # before_save body. Computes the SHA-256 digest of the
-      # concatenated source-field values. If the digest matches the
-      # stored sibling AND the target vector is already populated, the
-      # method returns without contacting the provider. Otherwise it
-      # calls the provider, validates the response shape, wraps the
-      # vector, and writes both the vector and digest under the writer
-      # guard (so the public setters' dirty-tracking fires).
+      # before_save body. Dispatches on `directive.modality`: text
+      # directives concatenate source-field values and call
+      # `Provider#embed_text`; image directives extract the source
+      # Parse::File's URL, validate it via
+      # `Parse::Embeddings.validate_image_url!`, and call
+      # `Provider#embed_image`. Digest tracking elides the provider
+      # call when the source has not changed since last save.
       def self.recompute_embedding!(record, directive)
-        text = build_source_text(record, directive.sources)
+        input = build_source_input(record, directive)
         stored_digest = record.public_send(directive.digest_field)
         target_present = !record.public_send(directive.into).nil?
 
-        if text.empty?
+        if input.nil? || input.empty?
           if target_present || !stored_digest.nil?
             with_writer(directive.into) do
               record.public_send(:"#{directive.into}=", nil)
@@ -247,11 +356,11 @@ module Parse
           return
         end
 
-        digest = digest_for(text)
+        digest = digest_for(input)
         return if stored_digest == digest && target_present
 
         provider = Parse::Embeddings.provider(directive.provider_name)
-        vectors = provider.embed_text([text], input_type: directive.input_type)
+        vectors = call_provider(provider, directive, input)
         unless vectors.is_a?(Array) && vectors.length == 1 && vectors.first.is_a?(Array)
           raise Parse::Embeddings::InvalidResponseError,
                 "Parse::Core::EmbedManaged (#{record.class}##{directive.into}): provider " \
@@ -273,6 +382,46 @@ module Parse
         record.public_send(:"#{directive.digest_field}=", digest)
       end
 
+      # @!visibility private
+      # Build the provider input for `directive`: concatenated text for
+      # text directives; the raw image URL for image directives.
+      # Returns `nil` (treated as "clear the embedding") when the source
+      # is absent, empty, or — for images — has no URL.
+      #
+      # **Image path does not validate here.** Validation runs once,
+      # inside the provider's `embed_image` call. Validating here
+      # would double-resolve every URL (round-2 audit LOW #3) since
+      # provider implementations call `validate_image_url!` again.
+      # The digest is computed from the raw URL string, which is fine
+      # — the digest is a content fingerprint, not a security boundary.
+      # If validation fails, the provider raises `InvalidImageURL` /
+      # `ConfirmationRequired` from inside `recompute_embedding!`, which
+      # surfaces from `before_save` exactly as before.
+      def self.build_source_input(record, directive)
+        if directive.image?
+          source_field = directive.sources.first
+          file = record.public_send(source_field)
+          return nil if file.nil?
+          url = file.respond_to?(:url) ? file.url : nil
+          return nil if url.nil? || url.to_s.empty?
+          url.to_s
+        else
+          build_source_text(record, directive.sources)
+        end
+      end
+
+      # @!visibility private
+      # Dispatch the provider call based on directive modality.
+      def self.call_provider(provider, directive, input)
+        if directive.image?
+          provider.embed_image([input],
+            input_type: directive.input_type,
+            allow_insecure: directive.allow_insecure ? true : false)
+        else
+          provider.embed_text([input], input_type: directive.input_type)
+        end
+      end
+
       # @!visibility private
       # Concatenate source-field string values. `nil` and blank entries
       # are skipped; remaining values are joined with a double newline.