woods 1.2.0 → 1.3.0

data/lib/woods/storage/metadata_store.rb

@@ -1,8 +1,16 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'time'
 
 module Woods
+  # Same conditional-define pattern used elsewhere in the gem so this
+  # file can be required in isolation (e.g. by specs that bypass the
+  # full lib/woods.rb load) without tripping NameError on the friendly
+  # missing-sqlite3 raise below.
+  class Error < StandardError; end unless defined?(Woods::Error)
+  class ConfigurationError < Error; end unless defined?(Woods::ConfigurationError)
+
   module Storage
     # MetadataStore provides an interface for storing and querying unit metadata.
     #
@@ -85,6 +93,119 @@ module Woods
         end
       end
 
+      # Pure-Ruby metadata store backed by a hash. No external dependencies,
+      # no persistence — vectors and metadata both live in the building
+      # process and die with it. Suitable for hosts that don't bundle the
+      # `sqlite3` gem (e.g., MySQL- or Postgres-only Rails apps), and for
+      # short-lived processes that rebuild the index per run.
+      #
+      # @example
+      #   store = InMemory.new
+      #   store.store("User", { type: "model", namespace: "Admin" })
+      #   store.find("User")  # => { "type" => "model", "namespace" => "Admin" }
+      #
+      class InMemory
+        include Interface
+
+        def initialize
+          @data = {}
+        end
+
+        # @see Interface#store
+        def store(id, metadata)
+          @data[id] = stringify_keys(metadata).merge('updated_at' => Time.now.iso8601)
+        end
+
+        # @see Interface#find
+        def find(id)
+          record = @data[id]
+          return nil unless record
+
+          record.except('updated_at')
+        end
+
+        # @see Interface#find_batch
+        def find_batch(ids)
+          ids.each_with_object({}) do |id, result|
+            data = find(id)
+            result[id] = data if data
+          end
+        end
+
+        # @see Interface#find_by_type
+        def find_by_type(type)
+          target = type.to_s
+          @data.each_with_object([]) do |(id, record), out|
+            next unless record['type'].to_s == target
+
+            out << record.except('updated_at').merge('id' => id)
+          end
+        end
+
+        # @see Interface#search
+        def search(query, fields: nil)
+          needle = query.to_s
+          @data.each_with_object([]) do |(id, record), out|
+            haystacks = fields ? fields.map { |f| record[f.to_s] } : [JSON.generate(record)]
+            next unless haystacks.compact.any? { |h| h.to_s.include?(needle) }
+
+            out << record.except('updated_at').merge('id' => id)
+          end
+        end
+
+        # @see Interface#delete
+        def delete(id)
+          @data.delete(id)
+        end
+
+        # @see Interface#count
+        def count
+          @data.size
+        end
+
+        # Iterate over every stored entry, yielding +(id, metadata)+ pairs.
+        #
+        # Persistence seam for {Snapshotter::Metadata}. Yields the raw internal
+        # hash (including +updated_at+) so the Snapshotter can reconstruct state
+        # faithfully on load.
+        #
+        # @yield [id, metadata] id is a String; metadata is a Hash with string keys
+        # @return [Enumerator] when no block given
+        def each_entry(&block)
+          return enum_for(:each_entry) unless block
+
+          @data.each(&block)
+        end
+
+        # Hydrate the store from a pre-serialized dump.
+        #
+        # Dual of {#each_entry} — Snapshotter feeds the deserialized dump contents
+        # through this method to restore the store in a new process.
+        #
+        # @param entries [Enumerable<Array(String, Hash)>] Pairs of +[id, metadata]+
+        # @return [void]
+        def bulk_load(entries)
+          entries.each { |id, meta| @data[id] = meta }
+        end
+
+        # Drop every stored entry. Used by the MCP +reload+ tool to pick up a
+        # fresh embed run without restarting the process. Safe on an empty store.
+        def clear!
+          @data = {}
+        end
+
+        private
+
+        # Match the SQLite adapter's string-key contract regardless of how
+        # the caller serialises the input hash. Without this, find/search
+        # consumers that expect string keys (the SQLite path round-trips
+        # through JSON, which always returns strings) would break under
+        # symbol-keyed test fixtures.
+        def stringify_keys(hash)
+          hash.each_with_object({}) { |(k, v), out| out[k.to_s] = v }
+        end
+      end
+
       # SQLite-backed metadata store using the JSON1 extension.
       #
       # Stores unit metadata as JSON in a single table with type indexing
@@ -100,7 +221,14 @@ module Woods
 
         # @param db_path [String] Path to the SQLite database file, or ":memory:" for in-memory
         def initialize(db_path = ':memory:')
-          require 'sqlite3'
+          begin
+            require 'sqlite3'
+          rescue LoadError
+            raise Woods::ConfigurationError,
+                  'metadata_store: :sqlite requires the sqlite3 gem in your Gemfile. ' \
+                  "Add `gem 'sqlite3'` and re-bundle, or set " \
+                  "`config.metadata_store = :in_memory` if you don't need cross-process persistence."
+          end
           @db = ::SQLite3::Database.new(db_path)
           @db.results_as_hash = true
           create_table

data/lib/woods/storage/pgvector.rb

@@ -56,6 +56,7 @@ module Woods
         # @see Interface#store
         def store(id, vector, metadata = {})
           validate_vector!(vector)
+          validate_dimensions!(vector) if @dimensions
           entry = format_entry(id, vector, metadata)
 
           @connection.execute(<<~SQL)
@@ -71,14 +72,21 @@ module Woods
         # Store multiple vectors in a single multi-row INSERT.
         #
         # @param entries [Array<Hash>] Each entry has :id, :vector, :metadata keys
+        # @raise [ArgumentError] if any entry has a non-numeric or wrong-dimension vector.
+        #   Validation runs BEFORE any INSERT so partial-batch writes can't occur.
         def store_batch(entries)
           return if entries.empty?
 
-          values = entries.map do |entry|
-            validate_vector!(entry[:vector])
-            format_entry(entry[:id], entry[:vector], entry[:metadata] || {})
+          # Pre-validate every vector before any SQL — prevents partial-batch
+          # state when a later entry's dimension doesn't match.
+          entries.each_with_index do |entry, idx|
+            vector = entry[:vector]
+            validate_vector!(vector)
+            validate_dimensions!(vector, index: idx) if @dimensions
           end
 
+          values = entries.map { |entry| format_entry(entry[:id], entry[:vector], entry[:metadata] || {}) }
+
           @connection.execute(<<~SQL)
             INSERT INTO #{TABLE} (id, embedding, metadata, created_at)
             VALUES #{values.join(",\n")}
@@ -98,7 +106,7 @@ module Woods
         # @see Interface#search
         def search(query_vector, limit: 10, filters: {})
           validate_vector!(query_vector)
-          vector_literal = "[#{query_vector.join(',')}]"
+          vector_literal = build_vector_literal(query_vector)
           where_clause = build_where(filters)
 
           sql = <<~SQL
@@ -142,10 +150,29 @@ module Woods
         def format_entry(id, vector, metadata)
           quoted_id = @connection.quote(id)
           quoted_metadata = @connection.quote(JSON.generate(metadata))
-          vector_literal = "[#{vector.join(',')}]"
+          vector_literal = build_vector_literal(vector)
           "(#{quoted_id}, '#{vector_literal}', #{quoted_metadata}::jsonb, CURRENT_TIMESTAMP)"
         end
 
+        # Build the `[x,y,z]` pgvector literal from a validated numeric vector.
+        # Coerces each element through `Float()` first — `Float#to_s` is
+        # guaranteed to produce only digits, `.`, `-`, and `e`, which closes
+        # the theoretical `Numeric`-subclass `#to_s` injection vector even
+        # though {#validate_vector!} already rejects non-Numeric inputs.
+        # `Float()` raises `RangeError` on `Complex` values with an imaginary
+        # part — we surface that as an `ArgumentError` so callers see the
+        # same error shape as the other vector-validation paths instead of
+        # the raw coercion error.
+        def build_vector_literal(vector)
+          coerced = vector.each_with_index.map do |element, i|
+            Float(element).to_s
+          rescue RangeError, TypeError, ArgumentError => e
+            raise ArgumentError,
+                  "Vector element at index #{i} cannot be coerced to Float: #{element.inspect} (#{e.class})"
+          end
+          "[#{coerced.join(',')}]"
+        end
+
         # Convert a database row to a SearchResult.
         #
         # @param row [Hash] Database row with id, distance, metadata
@@ -173,22 +200,57 @@ module Woods
               raise ArgumentError, "Invalid filter key: #{key_s.inspect}"
             end
 
-            "metadata->>'#{key_s}' = #{@connection.quote(value.to_s)}"
+            # Belt-and-suspenders: regex above already rejects any value that
+            # could alter the SQL shape, but we still pass the key through
+            # `@connection.quote` so the quoting story is uniform across the
+            # key and value positions and a future regex-relaxation does not
+            # silently unlock injection.
+            if value.is_a?(Array)
+              # Membership filter. An empty Array would produce `IN ()`
+              # which is a syntax error; emit an always-false predicate
+              # so the query still parses and returns no rows.
+              next 'FALSE' if value.empty?
+
+              quoted = value.map { |v| @connection.quote(v.to_s) }.join(', ')
+              "metadata->>#{@connection.quote(key_s)} IN (#{quoted})"
+            else
+              "metadata->>#{@connection.quote(key_s)} = #{@connection.quote(value.to_s)}"
+            end
           end
           "WHERE #{conditions.join(' AND ')}"
         end
 
-        # Validate that all vector elements are numeric.
+        # Validate that all vector elements are numeric and finite.
+        # Rejecting NaN / Infinity also closes a defense-in-depth gap
+        # around the vector-literal SQL construction — `Float::NAN.to_s`
+        # yields `"NaN"` which pgvector rejects, but other float-like
+        # sentinels can leak through string construction unexpectedly.
         #
         # @param vector [Array] The vector to validate
-        # @raise [ArgumentError] if any element is not numeric
+        # @raise [ArgumentError] if any element is not numeric or is non-finite
         def validate_vector!(vector)
           vector.each_with_index do |element, i|
             unless element.is_a?(Numeric)
               raise ArgumentError, "Vector element at index #{i} is not numeric: #{element.inspect}"
             end
+            if element.is_a?(Float) && !element.finite?
+              raise ArgumentError, "Vector element at index #{i} is not finite: #{element.inspect}"
+            end
           end
         end
+
+        # Assert the provided vector matches the store's configured dimension.
+        #
+        # @param vector [Array<Numeric>]
+        # @param index [Integer, nil] position in the batch, used in the error message
+        # @raise [Woods::Error] on dimension mismatch
+        def validate_dimensions!(vector, index: nil)
+          return if vector.length == @dimensions
+
+          where = index ? " (entry #{index})" : ''
+          raise Woods::Error,
+                "Vector dimension mismatch#{where}: got #{vector.length}, expected #{@dimensions}"
+        end
       end
     end
   end

data/lib/woods/storage/qdrant.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
+require 'ipaddr'
 require 'net/http'
 require 'json'
+require 'socket'
 require 'uri'
 require_relative 'vector_store'
+require_relative '../util/host_guard'
 
 module Woods
   module Storage
@@ -22,20 +25,167 @@ module Woods
       class Qdrant # rubocop:disable Metrics/ClassLength
         include Interface
 
+        # URL schemes allowed for the Qdrant endpoint. `file://`, `gopher://`,
+        # and anything else would let a misconfigured or attacker-controlled
+        # config value turn the adapter into an SSRF vector against the host
+        # running extraction.
+        ALLOWED_SCHEMES = %w[http https].freeze
+
+        # IP ranges that always resolve to loopback, link-local, private, or
+        # CGNAT space and should never be contacted as a vector store unless
+        # the operator explicitly opts in via `allow_private_hosts: true`.
+        #
+        # Covers:
+        # - IPv4 "this network" / wildcard (0.0.0.0/8)
+        # - IPv4 loopback, RFC1918 (10/8, 172.16/12, 192.168/16)
+        # - IPv4 link-local 169.254/16 (AWS / Azure / GCP IMDS)
+        # - IPv4 CGNAT 100.64/10 (common in managed clouds behind NAT)
+        # - IPv6 loopback (::1) and unspecified (::)
+        # - IPv6 ULA fc00::/7 (private IPv6 equivalent of RFC1918)
+        # - IPv6 link-local fe80::/10
+        #
+        # NOTE: IPv4-mapped IPv6 (`::ffff:169.254.169.254`) is handled
+        # separately in {.private_host?} by detecting the `::ffff:` prefix
+        # and extracting the embedded IPv4 portion before range comparison.
+        # A blanket `::ffff:0:0/96` range here would (on some Ruby versions,
+        # including 3.0) match every IPv4 address due to IPAddr's
+        # cross-family auto-mapping in `#include?`.
+        PRIVATE_IP_RANGES = [
+          '0.0.0.0/8',
+          '10.0.0.0/8',
+          '127.0.0.0/8',
+          '169.254.0.0/16',
+          '172.16.0.0/12',
+          '192.168.0.0/16',
+          '100.64.0.0/10',
+          '::/128',
+          '::1/128',
+          'fc00::/7',
+          'fe80::/10'
+        ].map { |cidr| IPAddr.new(cidr) }.freeze
+
+        # Hostnames that always map to loopback regardless of DNS.
+        PRIVATE_HOSTNAMES = %w[localhost localhost. ip6-localhost ip6-loopback].freeze
+
         # @param url [String] Qdrant server URL
         # @param collection [String] Collection name
         # @param api_key [String, nil] Optional API key for authentication
-        def initialize(url:, collection:, api_key: nil)
+        # @param dimensions [Integer, nil] Expected vector dimension. When set,
+        #   {#store_batch}/{#store} pre-validate every vector's length before
+        #   sending the HTTP request — Qdrant returns a 400 on mismatch, but
+        #   detecting it client-side avoids wasted network round-trips and
+        #   keeps error shape consistent with the pgvector adapter.
+        # @param allow_private_hosts [Boolean] Explicitly permit a URL whose
+        #   host resolves inside loopback, link-local, or RFC1918 space. Off
+        #   by default to block the common SSRF footgun. Set to true when the
+        #   operator intentionally runs Qdrant on `localhost:6333` or inside
+        #   a private network.
+        def initialize(url:, collection:, api_key: nil, dimensions: nil, allow_private_hosts: false)
+          @uri = self.class.validate_url!(url, allow_private_hosts: allow_private_hosts)
           @url = url
           @collection = collection
           @api_key = api_key
-          @uri = URI(url)
+          @dimensions = dimensions
+        end
+
+        # Validate a Qdrant endpoint URL — scheme in {ALLOWED_SCHEMES} and,
+        # unless opted out, host outside loopback / link-local / RFC1918.
+        # Public so callers can pre-check configuration before constructing.
+        def self.validate_url!(url, allow_private_hosts: false)
+          uri = URI(url)
+          validate_scheme!(uri)
+          validate_host_present!(uri, url)
+          validate_host_visibility!(uri.host.to_s, allow_private_hosts: allow_private_hosts)
+          uri
+        rescue URI::InvalidURIError => e
+          raise ArgumentError, "Qdrant URL is not a valid URI: #{e.message}"
+        end
+
+        def self.validate_scheme!(uri)
+          return if ALLOWED_SCHEMES.include?(uri.scheme)
+
+          raise ArgumentError,
+                "Qdrant URL scheme must be one of #{ALLOWED_SCHEMES.join(', ')}; got #{uri.scheme.inspect}"
+        end
+
+        def self.validate_host_present!(uri, url)
+          return unless uri.host.nil? || uri.host.empty?
+
+          raise ArgumentError, "Qdrant URL must include a host: #{url.inspect}"
+        end
+
+        def self.validate_host_visibility!(host, allow_private_hosts:)
+          return if allow_private_hosts
+
+          # Canonicalize (strip port, trailing dot, IPv6 brackets) via
+          # the shared helper so Qdrant and OriginGuard stay in sync.
+          canonical = Util::HostGuard.canonicalize(host)
+
+          # Non-canonical numeric hosts (hex `0x7f000001`, octal
+          # `0177.0.0.1`, bare integer `2130706433`, short-form `127.1`,
+          # mixed-radix `0x7f.0.0.1`) are accepted by URI and getaddrinfo
+          # but NOT by `IPAddr`, so the private-range check silently
+          # passed them through. Reject any host that looks numeric-but-
+          # not-standard instead of trying to canonicalize every form.
+          if Util::HostGuard.suspicious_numeric_host?(canonical)
+            raise ArgumentError,
+                  "Qdrant URL uses a non-standard numeric host (#{host}). " \
+                  'Hex/octal/integer/short-form IPs are rejected because they ' \
+                  'can disguise loopback or private addresses. Pass the ' \
+                  'dotted-decimal form explicitly.'
+          end
+
+          return unless private_host?(canonical)
+
+          raise ArgumentError,
+                "Qdrant URL targets a private/loopback host (#{host}); " \
+                'pass allow_private_hosts: true to permit. ' \
+                'Note: validation is at config time; DNS resolution happens ' \
+                'per request, so a public hostname that later resolves to a ' \
+                'private IP is NOT caught here — deploy Qdrant on a trusted network.'
+        end
+
+        def self.private_host?(host)
+          return true if PRIVATE_HOSTNAMES.include?(host)
+
+          ip = unmap_ipv4(IPAddr.new(host))
+
+          # Restrict range-check to the SAME address family so IPAddr's
+          # cross-family `include?` can't silently match all IPv4
+          # addresses into an IPv6 range (or vice versa) — a quirk
+          # observed on Ruby 3.0's IPAddr that trapped legitimate public
+          # IPv4 addresses as "IPv4-mapped private" when the range list
+          # contained `::ffff:0:0/96`.
+          PRIVATE_IP_RANGES.any? do |range|
+            range.family == ip.family && range.include?(ip)
+          end
+        rescue IPAddr::InvalidAddressError
+          false
         end
 
+        # IPv4-mapped IPv6 (`::ffff:169.254.169.254`): extract the
+        # embedded IPv4 (low 32 bits) before range comparison so the AWS
+        # IMDS address is caught by 169.254/16 even when disguised as
+        # IPv4-mapped IPv6. Returns the input unchanged for every other
+        # address.
+        def self.unmap_ipv4(ip)
+          return ip unless ip.ipv6?
+          return ip unless ip.to_string.start_with?('0000:0000:0000:0000:0000:ffff:')
+
+          mapped_ipv4 = ip.to_i & 0xffff_ffff
+          return ip unless mapped_ipv4.positive?
+
+          IPAddr.new(mapped_ipv4, Socket::AF_INET)
+        end
+
+        private_class_method :validate_scheme!, :validate_host_present!,
+                             :validate_host_visibility!, :private_host?, :unmap_ipv4
+
         # Create the collection if it doesn't exist.
         #
         # @param dimensions [Integer] Vector dimensionality
         def ensure_collection!(dimensions:)
+          @dimensions ||= dimensions
           body = {
             vectors: {
               size: dimensions,
@@ -52,6 +202,7 @@ module Woods
         # @param metadata [Hash] Optional payload metadata
         # @see Interface#store
         def store(id, vector, metadata = {})
+          validate_dimensions!(vector) if @dimensions
           body = {
             points: [
               {
@@ -72,9 +223,18 @@ module Woods
         # the upstream chunk size.
         #
         # @param entries [Array<Hash>] Each entry has :id, :vector, :metadata keys
+        # @raise [Woods::Error] if any entry's vector doesn't match the configured
+        #   dimension. Validation runs before the HTTP request so partial-batch
+        #   state is impossible on dimension mismatch.
         def store_batch(entries)
           return if entries.empty?
 
+          if @dimensions
+            entries.each_with_index do |entry, idx|
+              validate_dimensions!(entry[:vector], index: idx)
+            end
+          end
+
           body = {
             points: entries.map do |entry|
               { id: entry[:id], vector: entry[:vector], payload: entry[:metadata] || {} }
@@ -130,13 +290,44 @@ module Woods
 
         private
 
+        # Cap interpolated response bodies so misconfigured Qdrant responses
+        # (e.g. proxied HTML error pages) don't unbounded-leak into logs or
+        # re-raised error messages.
+        #
+        # @param body [String, nil]
+        # @return [String]
+        def truncate_response_body(body)
+          return '' if body.nil?
+
+          s = body.to_s
+          s.length > 500 ? "#{s[0, 500]}... [truncated]" : s
+        end
+
+        # Ensure the provided vector matches the store's configured dimension.
+        #
+        # @param vector [Array<Numeric>]
+        # @param index [Integer, nil] position in the batch
+        # @raise [Woods::Error] on dimension mismatch
+        def validate_dimensions!(vector, index: nil)
+          return if vector.respond_to?(:length) && vector.length == @dimensions
+
+          where = index ? " (entry #{index})" : ''
+          got = vector.respond_to?(:length) ? vector.length : vector.class
+          raise Woods::Error,
+                "Vector dimension mismatch#{where}: got #{got}, expected #{@dimensions}"
+        end
+
         # Build a Qdrant filter from metadata key-value pairs.
         #
         # @param filters [Hash] Metadata filters
         # @return [Hash] Qdrant-compatible filter with must conditions
         def build_filter(filters)
           conditions = filters.map do |key, value|
-            { key: key.to_s, match: { value: value } }
+            if value.is_a?(Array)
+              { key: key.to_s, match: { any: value } }
+            else
+              { key: key.to_s, match: { value: value } }
+            end
           end
           { must: conditions }
         end
@@ -153,7 +344,7 @@ module Woods
           response = http_client.request(req)
 
           unless response.is_a?(Net::HTTPSuccess)
-            raise Woods::Error, "Qdrant API error: #{response.code} #{response.body}"
+            raise Woods::Error, "Qdrant API error: #{response.code} #{truncate_response_body(response.body)}"
           end
 
           JSON.parse(response.body)
@@ -162,7 +353,7 @@ module Woods
           @http_client = nil
           response = http_client.request(req)
           unless response.is_a?(Net::HTTPSuccess)
-            raise Woods::Error, "Qdrant API error: #{response.code} #{response.body}"
+            raise Woods::Error, "Qdrant API error: #{response.code} #{truncate_response_body(response.body)}"
           end
 
           JSON.parse(response.body)