parse-stack-next 5.5.6 → 5.6.0

data/lib/parse/embeddings/streaming_body.rb

@@ -0,0 +1,170 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "base64"
+
+module Parse
+  module Embeddings
+    # An IO-shaped request body that splices base64-encoded files into
+    # a JSON envelope **without ever holding a whole file in memory**.
+    #
+    # Multimodal endpoints want one JSON document with the media inlined
+    # as a `data:` URI. Building that with `to_json` costs roughly 2.4x
+    # the media size resident (raw bytes + the 1.33x base64 copy + the
+    # serialized JSON String), which is enough to OOM a small dyno on a
+    # single moderate video. This class instead emits the body as a
+    # stream of segments — literal JSON fragments interleaved with
+    # files that are read and encoded {READ_CHUNK} bytes at a time —
+    # so peak memory is bounded by the chunk size regardless of how
+    # large the media is, and nothing is spilled to disk either.
+    #
+    # Faraday's net_http adapter assigns any body responding to `#read`
+    # to `Net::HTTP::Request#body_stream`, which pulls it incrementally.
+    # {#size} is exact, so callers can set `Content-Length` and avoid
+    # chunked transfer encoding (which some API gateways reject).
+    #
+    # Base64 is spliced directly into the JSON string literal with no
+    # escaping: the alphabet (`A-Za-z0-9+/=`) contains no character
+    # that JSON requires escaping, so this is safe by construction.
+    class StreamingBody
+      # Bytes read from a source file per fill. MUST stay a multiple of
+      # 3 so each chunk encodes to a padding-free base64 block and the
+      # concatenation is byte-identical to encoding the whole file at
+      # once. Only the final (short) chunk may carry `=` padding.
+      READ_CHUNK = 57 * 1024
+
+      # Raised when a segment's file changes size between the
+      # {#size} calculation and the actual read, which would desync
+      # `Content-Length` from the emitted body.
+      class SizeMismatch < Parse::Embeddings::Error; end
+
+      # @param segments [Array<String, Hash>] literal Strings are
+      #   emitted verbatim; Hashes of the form
+      #   `{ path: String, size: Integer }` are base64-streamed.
+      def initialize(segments)
+        @segments = segments.map do |seg|
+          case seg
+          when String then seg.dup.force_encoding(Encoding::BINARY)
+          when Hash
+            unless seg[:path].is_a?(String) && seg[:size].is_a?(Integer)
+              raise ArgumentError,
+                    "Parse::Embeddings::StreamingBody: file segment needs :path and :size."
+            end
+            seg
+          else
+            raise ArgumentError,
+                  "Parse::Embeddings::StreamingBody: segment must be a String or " \
+                  "{path:, size:} Hash (got #{seg.class})."
+          end
+        end
+        rewind
+      end
+
+      # Exact byte length of the fully-emitted body. Base64 expands
+      # every 3 input bytes to 4 output bytes, padded up.
+      #
+      # @return [Integer]
+      def size
+        @size ||= @segments.sum do |seg|
+          seg.is_a?(String) ? seg.bytesize : 4 * ((seg[:size] + 2) / 3)
+        end
+      end
+      alias_method :length, :size
+
+      # @param len [Integer, nil] bytes wanted; nil reads to the end
+      #   (which defeats the memory bound — Net::HTTP always passes a
+      #   length, so this is only for completeness).
+      # @param out [String, nil] optional output buffer to fill.
+      # @return [String, nil] nil once exhausted, per IO#read semantics.
+      def read(len = nil, out = nil)
+        fill(len)
+        if @buffer.empty?
+          out&.clear
+          return len.nil? ? "" : nil
+        end
+
+        chunk =
+          if len.nil?
+            b = @buffer
+            @buffer = +""
+            b
+          else
+            @buffer.slice!(0, len)
+          end
+
+        if out
+          out.replace(chunk)
+          out
+        else
+          chunk
+        end
+      end
+
+      # Reset to the start so the body can be replayed (Net::HTTP
+      # rewinds `body_stream` when it retries a request).
+      #
+      # @return [void]
+      def rewind
+        close
+        @buffer = +""
+        @index = 0
+        @io = nil
+        nil
+      end
+
+      # @return [void]
+      def close
+        @io&.close
+        @io = nil
+        nil
+      end
+
+      private
+
+      # Top up @buffer until it holds `len` bytes or the segments run
+      # out. Reads at most one READ_CHUNK per iteration, so peak
+      # memory is READ_CHUNK * 4/3 plus whatever the caller asked for.
+      def fill(len)
+        loop do
+          return if len && @buffer.bytesize >= len
+          return if @index >= @segments.length
+
+          seg = @segments[@index]
+          if seg.is_a?(String)
+            @buffer << seg
+            @index += 1
+            next
+          end
+
+          @io ||= begin
+            f = ::File.open(seg[:path], "rb")
+            actual = f.size
+            if actual != seg[:size]
+              f.close
+              raise SizeMismatch,
+                    "Parse::Embeddings::StreamingBody: #{seg[:path]} is #{actual} bytes but " \
+                    "#{seg[:size]} was declared; the file changed underneath the request."
+            end
+            f
+          end
+
+          data = @io.read(READ_CHUNK)
+          if data.nil? || data.empty?
+            @io.close
+            @io = nil
+            @index += 1
+            next
+          end
+          @buffer << Base64.strict_encode64(data)
+          # A short read means EOF; close now so the padding lands and
+          # the next iteration advances to the following segment.
+          if data.bytesize < READ_CHUNK
+            @io.close
+            @io = nil
+            @index += 1
+          end
+        end
+      end
+    end
+  end
+end

data/lib/parse/embeddings/video_source.rb

@@ -0,0 +1,120 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "base64"
+
+module Parse
+  module Embeddings
+    # Value objects and magic-byte verification for video inputs to
+    # multimodal embedding providers.
+    #
+    # This mirrors {ImageFetch} deliberately — same sniff-then-verify
+    # discipline, same refusal to trust a `Content-Type` header — but
+    # it deliberately ships NO byte-holding value object and NO
+    # `fetch!` counterpart. Video payloads are large enough that
+    # holding one in memory can exhaust a small dyno, so both supported
+    # paths avoid it:
+    #
+    # * **local file** — wrap with {Parse::Embeddings::MediaFile.video},
+    #   which reads only the 16-byte header. The bytes are base64-
+    #   streamed into the request by {StreamingBody} at send time.
+    # * **URL** — pass the URL String straight to `embed_video`, which
+    #   validates it through {Parse::Embeddings.validate_image_url!}
+    #   (a generic URL-safety guard despite the name: CIDR screen, port
+    #   and host allowlist, sentinel-gated egress) and lets the
+    #   provider do the fetch. The SDK never downloads the video.
+    module VideoSource
+      # Raised when bytes fail verification — unknown magic, or a
+      # sniffed type outside the allowlist. Carries a `:reason` tag
+      # (`:empty`, `:unknown_magic`, `:type_not_allowed`) matching
+      # {ImageFetch::InvalidImageType}'s convention.
+      class InvalidVideoType < Parse::Embeddings::Error
+        # @return [Symbol] failure-mode tag.
+        attr_reader :reason
+        def initialize(reason, message)
+          @reason = reason
+          super(message)
+        end
+      end
+
+      # MIME types accepted by default. Voyage documents MP4 as the
+      # only supported video container, and the live API rejects WebM
+      # and QuickTime payloads outright — so accepting them here would
+      # only trade a clear local error for an opaque provider 400.
+      # {.sniff_mime} still *recognizes* those containers so the
+      # rejection can name what was actually supplied.
+      DEFAULT_ALLOWED_VIDEO_TYPES = %w[video/mp4].freeze
+
+      # ISO Base Media major brands, split by the MIME type they imply.
+      # An `ftyp` box alone does NOT mean MP4 — QuickTime and the
+      # audio-only profiles share the container — so brands are matched
+      # explicitly and an unknown brand sniffs as nil rather than being
+      # assumed to be MP4.
+      #
+      # `M4A` is deliberately absent: it is Apple's audio-only profile,
+      # and admitting it here would let an audio file pass as video and
+      # be sent to a provider that accepts neither.
+      MP4_BRANDS = %w[isom iso2 iso4 iso5 iso6 mp41 mp42 avc1 dash mmp4 M4V].freeze
+      QUICKTIME_BRANDS = %w[qt].freeze
+
+      module_function
+
+      # Determine a video's MIME type from its leading magic bytes.
+      # Returns nil for anything unrecognized — callers must treat nil
+      # as a refusal and never fall back to extension or header typing.
+      #
+      # @param bytes [String] raw video bytes (at least the first 12).
+      # @return [String, nil] sniffed MIME type, or nil when unknown.
+      def sniff_mime(bytes)
+        return nil unless bytes.is_a?(String) && bytes.bytesize >= 12
+        b = bytes.byteslice(0, 16).force_encoding(Encoding::BINARY)
+
+        # Matroska / WebM share an EBML header; WebM is the profile
+        # every multimodal provider documents, so report it as WebM.
+        return "video/webm" if b.start_with?("\x1A\x45\xDF\xA3".b)
+
+        # ISO Base Media File Format: a size-prefixed `ftyp` box. The
+        # 4-byte major brand at offset 8 separates QuickTime from MP4.
+        # Unknown brands return nil — guessing "MP4" for an arbitrary
+        # ISO-BMFF file sends the provider something it will reject.
+        if b.byteslice(4, 4) == "ftyp".b
+          brand = b.byteslice(8, 4).to_s.strip
+          return "video/quicktime" if QUICKTIME_BRANDS.include?(brand)
+          return "video/mp4" if MP4_BRANDS.include?(brand)
+          return nil
+        end
+
+        nil
+      end
+
+      # Sniff the magic bytes and check the allowlist. Only the leading
+      # bytes are inspected, so callers may pass a short header slice
+      # rather than the whole file — which is what
+      # {Parse::Embeddings::MediaFile.video} does.
+      #
+      # @param bytes [String] leading video bytes (at least 12).
+      # @return [String] the sniffed MIME type.
+      # @raise [InvalidVideoType]
+      def verify!(bytes)
+        if bytes.nil? || bytes.empty?
+          raise InvalidVideoType.new(:empty,
+            "Parse::Embeddings::VideoSource: video payload is empty.")
+        end
+        mime = sniff_mime(bytes)
+        if mime.nil?
+          raise InvalidVideoType.new(:unknown_magic,
+            "Parse::Embeddings::VideoSource: leading bytes match no supported video " \
+            "container (MP4/QuickTime/WebM). The Content-Type header is not consulted — " \
+            "unrecognized content is refused outright.")
+        end
+        allowed = Parse::Embeddings.allowed_video_types
+        unless allowed.include?(mime)
+          raise InvalidVideoType.new(:type_not_allowed,
+            "Parse::Embeddings::VideoSource: sniffed type #{mime.inspect} is not in " \
+            "Parse::Embeddings.allowed_video_types (#{allowed.inspect}).")
+        end
+        mime
+      end
+    end
+  end
+end