parse-stack-next 5.0.1 → 5.1.0

data/lib/parse/client.rb

@@ -678,6 +678,12 @@ module Parse
     end
     private :validate_faraday_opts!
 
+    # Hosts considered "loopback" for the cleartext-ws:// guard in
+    # {#configure_live_query}. Mirrors
+    # {Parse::LiveQuery::Client::LOOPBACK_HOSTS} so the explicit-URL
+    # path and the derived-URL path agree on what counts as local.
+    LIVE_QUERY_LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1 [::1] 0.0.0.0].freeze
+
     # Configure LiveQuery with the given options
     # @param opts [Hash] configuration options
     # @option opts [String] :live_query_url WebSocket URL for LiveQuery server (wss://...)
@@ -690,14 +696,74 @@ module Parse
       require_relative "live_query"
 
       live_query_opts = opts[:live_query].is_a?(Hash) ? opts[:live_query] : {}
+      resolved_url = live_query_url || live_query_opts[:url]
+
+      # Refuse explicit `ws://` against a non-loopback host unless
+      # `allow_insecure: true` is also passed in `live_query:`. The
+      # downstream `derive_websocket_url` path already enforces this for
+      # URLs derived from a Parse Server `http://` URL, but an explicit
+      # `live_query: { url: "ws://prod-host" }` or
+      # `live_query_url: "ws://prod-host"` bypassed it — the master key
+      # and any session token would ride the connect frame in cleartext.
+      validate_live_query_url!(resolved_url, allow_insecure: live_query_opts[:allow_insecure])
+
+      # Warn (don't raise) on `live_query: { ... }` keys that are not
+      # `Parse::LiveQuery::Configuration` setters. The block form would
+      # otherwise silently swallow typos like
+      # `live_query: { ssl_min_versoin: :TLSv1_3 }` and leave TLS at the
+      # default, losing the operator's intent. The pre-fix kwargs form
+      # raised `ArgumentError` here; this restores the surface without
+      # making it a hard failure for unknown-but-harmless keys.
+      warn_about_unknown_live_query_keys!(live_query_opts)
+
+      Parse::LiveQuery.configure do |config|
+        config.application_id = @application_id if @application_id
+        config.client_key = @api_key if @api_key
+        config.master_key = @master_key if @master_key
+
+        # Apply hash-form options first so the resolved URL (which honors
+        # top-level `live_query_url:` over `live_query: { url: }`) wins.
+        # Without this, the loop would re-write `config.url` from the
+        # hash and silently invert the documented precedence.
+        live_query_opts.each do |key, value|
+          next if key == :url
+          setter = "#{key}="
+          config.public_send(setter, value) if config.respond_to?(setter)
+        end
+
+        config.url = resolved_url if resolved_url
+      end
+    end
 
-      Parse::LiveQuery.configure(
-        url: live_query_url || live_query_opts[:url],
-        application_id: @application_id,
-        client_key: @api_key,
-        master_key: @master_key,
-        **live_query_opts,
-      )
+    # @api private
+    def validate_live_query_url!(url, allow_insecure:)
+      return unless url.is_a?(String) && url.start_with?("ws://")
+
+      host = URI.parse(url).host.to_s rescue ""
+      return if LIVE_QUERY_LOOPBACK_HOSTS.include?(host)
+      return if allow_insecure
+
+      raise ArgumentError,
+        "[Parse::Client] Refusing explicit insecure LiveQuery URL #{url.inspect}. " \
+        "The connect frame carries the master key and any session token in " \
+        "plaintext on this socket. Use wss:// for routable hosts, or pass " \
+        "`live_query: { allow_insecure: true }` to opt into cleartext for " \
+        "local development on a non-loopback address."
+    end
+
+    # @api private
+    def warn_about_unknown_live_query_keys!(live_query_opts)
+      return unless live_query_opts.is_a?(Hash) && live_query_opts.any?
+
+      probe = Parse::LiveQuery::Configuration.new
+      unknown = live_query_opts.keys.reject { |k| probe.respond_to?("#{k}=") }
+      return if unknown.empty?
+
+      warn "[Parse::Client] Ignoring unknown live_query option(s): " \
+           "#{unknown.inspect}. Valid keys are Parse::LiveQuery::Configuration " \
+           "setters (url, application_id, client_key, master_key, ping_interval, " \
+           "pong_timeout, allow_insecure, ssl_min_version, ssl_max_version, " \
+           "logging_enabled, log_level, ...). Check for typos."
     end
 
     # If set, returns the current retry count for this instance. Otherwise,
@@ -1026,11 +1092,12 @@ module Parse
   # @return (see Parse::Client.setup)
   # @see Parse::Client.setup
   def self.setup(opts = {}, &block)
-    if block_given?
-      Parse::Client.new(opts, &block)
-    else
-      Parse::Client.new(opts)
-    end
+    # Delegate to Parse::Client.setup so repeated Parse.setup calls overwrite
+    # the registered :default client. Going through Parse::Client.new instead
+    # would hit the `@clients[:default] ||= self` guard inside #initialize and
+    # silently keep the first-registered client, while Parse::Client.setup
+    # uses `=` and replaces it. Both entry points must behave identically.
+    Parse::Client.setup(opts, &block)
   end
 
   # @!visibility private

data/lib/parse/embeddings/cohere.rb

@@ -14,9 +14,13 @@ module Parse
     #
     # * **v4** — `embed-v4.0` (1536 native, Matryoshka {256, 512, 1024,
     #   1536}, 128k-token context). Unified text + image model at the
-    #   network boundary; this provider exposes the text-input path
-    #   only — image inputs will land in v5.1 alongside the
-    #   {Provider#embed_image} hook.
+    #   network boundary. The text path uses Cohere's `/v1/embed`
+    #   endpoint; the image path ({#embed_image}, v5.1+) uses the
+    #   `/v2/embed` multimodal endpoint with OpenAI-style
+    #   `{ type: "image_url", image_url: { url: ... } }` content rows.
+    #   Text vectors stored today share the vector space with the
+    #   eventual image vectors (no re-embed required when adding
+    #   image-side data).
     # * **v3** — `embed-english-v3.0`, `embed-multilingual-v3.0` (both
     #   1024-dim), `embed-english-light-v3.0`,
     #   `embed-multilingual-light-v3.0` (both 384-dim). Text-only.
@@ -94,6 +98,10 @@ module Parse
       # models reject the field with a 400.
       MATRYOSHKA_MODELS = %w[embed-v4.0].freeze
 
+      # Models that accept image inputs via the `/v2/embed` multimodal
+      # endpoint. Currently only `embed-v4.0` — v3 is text-only.
+      MULTIMODAL_MODELS = %w[embed-v4.0].freeze
+
       # Allowed Matryoshka widths per model (Cohere quantizes the
       # available truncations rather than accepting any integer ≤
       # native). Empty allowlist = any integer ≤ native is fine, but
@@ -246,6 +254,105 @@ module Parse
         end
       end
 
+      # @return [Array<Symbol>] `[:text, :image]` for `embed-v4.0`,
+      #   `[:text]` for v3 models.
+      def modalities
+        MULTIMODAL_MODELS.include?(@model) ? %i[text image] : [:text]
+      end
+
+      # Embed a batch of image URLs through Cohere's `/v2/embed`
+      # multimodal endpoint. v5.1 ships URL-only — the provider
+      # receives a public URL and issues its own fetch. The SDK does
+      # NOT download the image; it validates the URL through
+      # {Parse::Embeddings.validate_image_url!} (sentinel-gated egress
+      # opt-in, CIDR / port / host allowlist) and forwards the
+      # canonicalized URL string in the `{ type: "image_url",
+      # image_url: { url: ... } }` content row.
+      #
+      # **Multimodal model required.** Cohere's v3 models do not accept
+      # image inputs; calling `embed_image` on a v3-configured provider
+      # raises {BadRequestError} before any network call.
+      #
+      # **Wire shape differs from {Voyage#embed_image}.** Voyage uses
+      # `{ type: "image_url", image_url: "<url>" }` (flat String); Cohere
+      # v2 uses `{ type: "image_url", image_url: { url: "<url>" } }`
+      # (nested object), matching the OpenAI chat-completions content
+      # convention. The high-level SDK contract is identical — callers
+      # pass an `Array<String>` of URLs.
+      #
+      # @param sources [Array<String>] image URLs. Each must satisfy
+      #   {Parse::Embeddings.validate_image_url!}; failing entries
+      #   abort the whole batch (no partial forwarding).
+      # @param input_type [Symbol] one of {INPUT_TYPE_WIRE_VALUES}'s
+      #   keys; mapped to Cohere's `input_type` field. Defaults to
+      #   `:search_document`.
+      # @param allow_insecure [Boolean] forwarded to the URL validator;
+      #   permit `http://` for local-dev CDN proxies.
+      # @return [Array<Array<Float>>] vectors aligned 1:1 with `sources`.
+      def embed_image(sources, input_type: :search_document, allow_insecure: false)
+        unless MULTIMODAL_MODELS.include?(@model)
+          raise BadRequestError,
+                "Parse::Embeddings::Cohere#embed_image: model #{@model.inspect} does not " \
+                "accept image inputs. Configure the provider with a multimodal model " \
+                "(supported: #{MULTIMODAL_MODELS.inspect})."
+        end
+        unless sources.is_a?(Array)
+          raise ArgumentError,
+                "Parse::Embeddings::Cohere#embed_image expects Array of image URLs " \
+                "(got #{sources.class})."
+        end
+        return [] if sources.empty?
+
+        wire_input_type = INPUT_TYPE_WIRE_VALUES[input_type]
+        unless wire_input_type
+          raise ArgumentError,
+                "Parse::Embeddings::Cohere#embed_image input_type #{input_type.inspect} not in " \
+                "#{INPUT_TYPE_WIRE_VALUES.keys.inspect}."
+        end
+        # Cohere caps `/v2/embed` at the same 96-input per-call limit
+        # as `/v1/embed`. Guard direct-API callers against a silent
+        # 400 — the DSL passes a single URL per directive.
+        if sources.length > @embed_batch_size
+          raise ArgumentError,
+                "Parse::Embeddings::Cohere#embed_image: batch size #{sources.length} exceeds " \
+                "the configured cap #{@embed_batch_size} (Cohere per-request max: 96). " \
+                "Split the input and call embed_image once per chunk."
+        end
+
+        # Validate every URL up-front so a malformed entry in slot N
+        # does not slip through after slots 0..N-1 are already in the
+        # wire body. Forward the canonicalized URL the validator
+        # returned — not the caller's raw input.
+        canonical_urls = sources.each_with_index.map do |url, i|
+          unless url.is_a?(String)
+            raise ArgumentError,
+                  "Parse::Embeddings::Cohere#embed_image sources[#{i}] is not a String " \
+                  "(#{url.class}). v5.1 ships URL-only — bytes/IO support is v5.3."
+          end
+          Parse::Embeddings.validate_image_url!(url, allow_insecure: allow_insecure)
+        end
+
+        body = {
+          model: @model,
+          input_type: wire_input_type,
+          embedding_types: ["float"],
+          inputs: canonical_urls.map { |u|
+            { content: [{ type: "image_url", image_url: { url: u } }] }
+          },
+        }
+
+        instrument_embed(sources.length, input_type, modality: :image) do |emit_payload|
+          payload = post_embeddings(body, path: v2_embed_path)
+          if payload.is_a?(Hash) && payload["meta"].is_a?(Hash) &&
+             payload["meta"]["billed_units"].is_a?(Hash)
+            tt = payload["meta"]["billed_units"]["input_tokens"]
+            emit_payload[:total_tokens] = tt if tt.is_a?(Integer) && tt >= 0
+          end
+          vectors = extract_vectors!(payload, sources.length)
+          validate_response!(sources.length, vectors)
+        end
+      end
+
       def inspect_attrs
         super.merge(base: safe_base_host, retries: @max_retries)
       end
@@ -272,12 +379,42 @@ module Parse
         conn
       end
 
-      def post_embeddings(body)
+      # @api private
+      # Compute the v2/embed path relative to the configured base_url's
+      # path component. For the default base `https://api.cohere.com/v1`
+      # this produces `/v2/embed`; for a custom-proxy base like
+      # `https://corp-proxy.example.com/cohere/v1` it produces
+      # `/cohere/v2/embed` — so the operator's proxy / egress-logging
+      # / API-key custody layer is NOT silently bypassed by image
+      # embedding calls. The substitution targets the trailing `/v1`
+      # segment specifically; bases without that segment fall back to
+      # appending `/v2/embed` to the host root with a warning so the
+      # caller sees the asymmetry rather than discovering it via a
+      # 404 from a misrouted request.
+      def v2_embed_path
+        uri = URI.parse(@base_url)
+        path = uri.path.to_s
+        if path =~ %r{/v1/?\z}i
+          # Replace `/v1` (with optional trailing slash) with `/v2/embed`.
+          path.sub(%r{/v1/?\z}i, "/v2/embed")
+        else
+          warn "[Parse::Embeddings::Cohere] base_url path #{path.inspect} does not end " \
+               "in `/v1` — embed_image will POST to host-root `/v2/embed`, which may " \
+               "bypass a configured proxy path. Configure base_url to end with `/v1`."
+          "/v2/embed"
+        end
+      end
+
+      # `path:` accepts either a Faraday-relative segment (default
+      # `"embed"`, which resolves under the configured `/v1/` base) or
+      # an absolute path (`"/v2/embed"`) for endpoints outside the
+      # configured base — used by {#embed_image} to reach `/v2/embed`.
+      def post_embeddings(body, path: "embed")
         attempts = 0
         loop do
           attempts += 1
           begin
-            response = @connection.post("embed") do |req|
+            response = @connection.post(path) do |req|
               req.body = body.to_json
             end
           rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
@@ -312,7 +449,7 @@ module Parse
             next
           end
           raise BadRequestError,
-                "Parse::Embeddings::Cohere: #{status} from POST /embed."
+                "Parse::Embeddings::Cohere: #{status} from POST #{path.start_with?('/') ? path : "/#{path}"}."
         end
       end
 

data/lib/parse/embeddings/provider.rb

@@ -41,14 +41,32 @@ module Parse
 
       # @param sources [Array<URI, IO, String>] image sources — URI for
       #   remote, IO for streamed bytes, String for base64. Concrete
-      #   providers document which forms they accept.
+      #   providers document which forms they accept. In v5.1 (URL-only
+      #   path), every source is a raw `String` URL forwarded unchanged
+      #   from the managed path: {Parse::Core::EmbedManaged} deliberately
+      #   does NOT validate before calling the provider (validating there
+      #   would double-resolve every URL). The concrete `embed_image`
+      #   override is therefore responsible for calling
+      #   {Parse::Embeddings.validate_image_url!} (passing `allow_insecure:`
+      #   through) before egress — see the bundled Voyage/Cohere providers,
+      #   which validate internally.
       # @param input_type [Symbol] `:search_query` or `:search_document`,
       #   parallel to {#embed_text}.
+      # @param allow_insecure [Boolean] **contract kwarg** —
+      #   {Parse::Core::EmbedManaged.recompute_embedding!} unconditionally
+      #   forwards this from the directive declaration. Concrete
+      #   `embed_image` overrides MUST either accept `allow_insecure:`
+      #   explicitly (passing it through to
+      #   {Parse::Embeddings.validate_image_url!}) or absorb it via
+      #   `**opts`. Dropping `**opts` from the override signature
+      #   without accepting `allow_insecure:` will raise
+      #   `ArgumentError: unknown keyword: allow_insecure` from the
+      #   managed-embedding save path. Default `false`.
       # @param opts [Hash] provider-specific options (e.g. `dim:` for
       #   Matryoshka-style truncation). Forward-compatible escape hatch.
       # @return [Array<Array<Float>>] vectors aligned 1:1 with `sources`.
       # @raise [NotImplementedError] image embedding is a v5.1+ feature.
-      def embed_image(sources, input_type: :search_document, **opts)
+      def embed_image(sources, input_type: :search_document, allow_insecure: false, **opts)
         raise NotImplementedError, "#{self.class} does not support image embedding"
       end
 

data/lib/parse/embeddings/voyage.rb

@@ -272,6 +272,108 @@ module Parse
         end
       end
 
+      # @return [Array<Symbol>] Voyage's multimodal models support
+      #   `[:text, :image]`; text-only models report `[:text]`.
+      def modalities
+        MULTIMODAL_MODELS.include?(@model) ? %i[text image] : [:text]
+      end
+
+      # Embed a batch of image URLs through Voyage's
+      # `/v1/multimodalembeddings` endpoint. v5.1 ships URL-only — the
+      # provider receives a public URL and issues its own fetch. The
+      # SDK does NOT download the image; it validates the URL through
+      # {Parse::Embeddings.validate_image_url!} (CIDR / port / host
+      # allowlist, sentinel-gated egress opt-in) and forwards the
+      # canonicalized URL string in the `{ type: "image_url",
+      # image_url: ... }` content row.
+      #
+      # **Multimodal model required.** Voyage's text-only models
+      # (`voyage-3`, `voyage-4`, etc.) do not accept image inputs;
+      # calling `embed_image` on a provider configured with one of
+      # those raises {BadRequestError} before any network call.
+      #
+      # **Bytes-fetch path is v5.3.** A future `bytes:` option will
+      # download via {Parse::File.safe_open_url}, MIME-sniff the
+      # leading bytes, optionally EXIF-strip, and forward as
+      # base64. URL-only ships first because it sidesteps EXIF /
+      # MIME-confusion class issues entirely.
+      #
+      # @param sources [Array<String>] image URLs. Each must satisfy
+      #   {Parse::Embeddings.validate_image_url!} — failing entries
+      #   raise the corresponding {Parse::Embeddings::InvalidImageURL}
+      #   / {Parse::Embeddings::ConfirmationRequired} and ABORT the
+      #   whole batch (no partial forwarding).
+      # @param input_type [Symbol] one of {INPUT_TYPE_WIRE_VALUES}'s
+      #   keys; mapped to Voyage's `input_type` field. Defaults to
+      #   `:search_document`.
+      # @param allow_insecure [Boolean] forwarded to the URL
+      #   validator; permit `http://` for local-dev CDN proxies.
+      # @return [Array<Array<Float>>] vectors aligned 1:1 with `sources`.
+      def embed_image(sources, input_type: :search_document, allow_insecure: false)
+        unless MULTIMODAL_MODELS.include?(@model)
+          raise BadRequestError,
+                "Parse::Embeddings::Voyage#embed_image: model #{@model.inspect} does not " \
+                "accept image inputs. Configure the provider with a multimodal model " \
+                "(supported: #{MULTIMODAL_MODELS.inspect})."
+        end
+        unless sources.is_a?(Array)
+          raise ArgumentError,
+                "Parse::Embeddings::Voyage#embed_image expects Array of image URLs " \
+                "(got #{sources.class})."
+        end
+        return [] if sources.empty?
+
+        unless INPUT_TYPE_WIRE_VALUES.key?(input_type)
+          raise ArgumentError,
+                "Parse::Embeddings::Voyage#embed_image input_type #{input_type.inspect} not in " \
+                "#{INPUT_TYPE_WIRE_VALUES.keys.inspect}."
+        end
+        # Voyage caps multimodal requests at the same per-request size
+        # as the text endpoint. The text path goes through
+        # `embed_text_batched` which chunks automatically; the image
+        # path has no chunker yet (every directive is a single URL in
+        # v5.1), so guard the direct-API caller against a silent 400.
+        if sources.length > @embed_batch_size
+          raise ArgumentError,
+                "Parse::Embeddings::Voyage#embed_image: batch size #{sources.length} exceeds " \
+                "the configured cap #{@embed_batch_size} (Voyage per-request max: 128). " \
+                "Split the input and call embed_image once per chunk."
+        end
+
+        # Validate every URL up-front so a malformed entry in slot N
+        # does not get past validation while slots 0..N-1 are already
+        # in the wire body. The validator returns the canonicalized
+        # URL — we forward exactly that, not the caller's raw input.
+        canonical_urls = sources.each_with_index.map do |url, i|
+          unless url.is_a?(String)
+            raise ArgumentError,
+                  "Parse::Embeddings::Voyage#embed_image sources[#{i}] is not a String " \
+                  "(#{url.class}). v5.1 ships URL-only — bytes/IO support is v5.3."
+          end
+          Parse::Embeddings.validate_image_url!(url, allow_insecure: allow_insecure)
+        end
+
+        wire_input_type = INPUT_TYPE_WIRE_VALUES[input_type]
+        body = {
+          inputs: canonical_urls.map { |u|
+            { content: [{ type: "image_url", image_url: u }] }
+          },
+          model: @model,
+          truncation: @truncation,
+        }
+        body[:input_type] = wire_input_type if wire_input_type
+
+        instrument_embed(sources.length, input_type, modality: :image) do |emit_payload|
+          payload = post_embeddings(body, path: "multimodalembeddings")
+          if payload.is_a?(Hash) && payload["usage"].is_a?(Hash)
+            tt = payload["usage"]["total_tokens"]
+            emit_payload[:total_tokens] = tt if tt.is_a?(Integer) && tt >= 0
+          end
+          vectors = extract_vectors!(payload, sources.length)
+          validate_response!(sources.length, vectors)
+        end
+      end
+
       def inspect_attrs
         super.merge(base: safe_base_host, retries: @max_retries)
       end