parse-stack-next 4.5.0

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

@@ -0,0 +1,174 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  module Core
+    # Model-declarative Atlas Search index DSL. Mixed into Parse::Object
+    # so subclasses can declare the Atlas Search indexes they expect to
+    # exist on their collection. Declarations are inert at load time —
+    # they only land on Atlas when {Parse::Schema::SearchIndexMigrator}
+    # reads them and `apply_search_indexes!` is invoked through the
+    # writer connection.
+    #
+    # Parallels {Parse::Core::Indexing} (the regular `mongo_index` DSL)
+    # but with three meaningful differences:
+    #
+    #   - **Multi-per-class.** A single model can declare several search
+    #     indexes (one for full-text, one for autocomplete, one for
+    #     vector search), each with a unique name.
+    #   - **Definition is opaque.** The DSL doesn't introspect field
+    #     references — Atlas owns the mapping schema. The DSL validates
+    #     name shape and Hash-non-emptiness only; everything else is
+    #     forwarded to Atlas verbatim.
+    #   - **Async build.** Mutations don't return a "READY" guarantee
+    #     — the migrator's rake task is fire-and-forget by default,
+    #     `WAIT=true` opts into polling via
+    #     {Parse::AtlasSearch::IndexManager.wait_for_ready}.
+    #
+    # SECURITY POSTURE — purely declarative. No network I/O at
+    # declaration time, no class introspection. The validation rules
+    # below surface typos as load-time errors instead of runtime
+    # surprises during `rake parse:mongo:search_indexes:apply` in prod.
+    #
+    # @example Declaring search indexes
+    #   class Song < Parse::Object
+    #     property :title, :string
+    #     property :artist, :string
+    #
+    #     mongo_search_index "song_search", {
+    #       mappings: { dynamic: false, fields: {
+    #         title:  { type: "string", analyzer: "lucene.standard" },
+    #         artist: { type: "string" },
+    #       } },
+    #     }
+    #     mongo_search_index "song_autocomplete", {
+    #       mappings: { fields: {
+    #         title: { type: "autocomplete", tokenization: "edgeGram" },
+    #       } },
+    #     }
+    #   end
+    module SearchIndexing
+      # Atlas Search index name shape. Same regex used at the
+      # {Parse::MongoDB.create_search_index} layer.
+      INDEX_NAME_PATTERN = /\A[A-Za-z][A-Za-z0-9_-]{0,63}\z/.freeze
+
+      # Allowed `type:` values for `mongo_search_index`. `search` is the
+      # default and covers the conventional text-search / autocomplete /
+      # faceted-search use cases; `vectorSearch` is for vector similarity
+      # indexes. Atlas rejects any other value at command time, but we
+      # check at declaration time so the typo doesn't survive to prod.
+      ALLOWED_INDEX_TYPES = %w[search vectorSearch].freeze
+
+      # Storage for declared search indexes. Each entry is a frozen Hash
+      # with keys `:name`, `:definition`, `:type`.
+      # @return [Array<Hash>]
+      def mongo_search_index_declarations
+        @mongo_search_index_declarations ||= []
+      end
+
+      # Declare an Atlas Search index for this model's collection.
+      #
+      # @param name [String] the search index name. Must match
+      #   {INDEX_NAME_PATTERN}.
+      # @param definition [Hash] the search index definition (mappings,
+      #   analyzers, etc.). Forwarded verbatim to Atlas after
+      #   string-keyed normalization at apply time. Must be a non-empty
+      #   Hash.
+      # @param type [String] one of {ALLOWED_INDEX_TYPES}. Default
+      #   `"search"`.
+      # @return [Hash] the registered declaration (frozen)
+      # @raise [ArgumentError] when validation fails, or when a
+      #   declaration with the same name was already registered on this
+      #   class with a different definition or type (idempotent
+      #   redeclaration with identical content returns the existing
+      #   entry).
+      def mongo_search_index(name, definition, type: "search")
+        name_str = name.to_s
+        unless name_str.match?(INDEX_NAME_PATTERN)
+          raise ArgumentError,
+                "#{self}.mongo_search_index name #{name.inspect} must match #{INDEX_NAME_PATTERN.inspect}"
+        end
+        unless definition.is_a?(Hash) && !definition.empty?
+          raise ArgumentError,
+                "#{self}.mongo_search_index #{name_str.inspect} requires a non-empty Hash definition; got #{definition.inspect}"
+        end
+        type_str = type.to_s
+        unless ALLOWED_INDEX_TYPES.include?(type_str)
+          raise ArgumentError,
+                "#{self}.mongo_search_index #{name_str.inspect} type=#{type.inspect} must be one of #{ALLOWED_INDEX_TYPES.inspect}"
+        end
+
+        declaration = {
+          name:       name_str,
+          definition: deep_freeze(definition),
+          type:       type_str,
+        }.freeze
+
+        existing = mongo_search_index_declarations.find { |d| d[:name] == name_str }
+        if existing
+          # Idempotent redeclaration with identical content — common in
+          # autoloading / class-reopening setups. Re-declarations that
+          # disagree on definition or type fail loudly so the operator
+          # notices the conflict at class load instead of at apply time.
+          if existing[:definition] == declaration[:definition] && existing[:type] == declaration[:type]
+            return existing
+          end
+          raise ArgumentError,
+                "#{self}.mongo_search_index #{name_str.inspect} re-declared with a different " \
+                "definition or type. Each name may have one declaration per class. " \
+                "Use a unique name for the new index, or update the existing declaration in place."
+        end
+
+        mongo_search_index_declarations << declaration
+        declaration
+      end
+
+      # Dry-run reconciliation between declared search indexes and what
+      # exists on Atlas. Delegates to {Parse::Schema::SearchIndexMigrator}.
+      # @return [Hash] see {Parse::Schema::SearchIndexMigrator#plan}
+      def search_indexes_plan
+        Parse::Schema::SearchIndexMigrator.new(self).plan
+      end
+
+      # Apply declared search-index changes via the writer connection.
+      #
+      # @param update [Boolean] when true, drift-detected indexes are
+      #   updated via `updateSearchIndex`. When false (default), drift
+      #   is reported and the index is left untouched (operator must
+      #   either re-declare to match or explicitly opt-in to update).
+      # @param drop [Boolean] when true, orphan search indexes (those
+      #   on the collection but not declared) are dropped.
+      # @param wait [Boolean] when true, block on
+      #   {Parse::AtlasSearch::IndexManager.wait_for_ready} after every
+      #   create / update to confirm the build completed before
+      #   returning.
+      # @param timeout [Integer] wait timeout in seconds (when `wait:
+      #   true`). Default 600.
+      # @return [Hash] see {Parse::Schema::SearchIndexMigrator#apply!}
+      def apply_search_indexes!(update: false, drop: false, wait: false, timeout: 600)
+        Parse::Schema::SearchIndexMigrator.new(self).apply!(
+          update: update, drop: drop, wait: wait, timeout: timeout,
+        )
+      end
+
+      private
+
+      # Recursive deep-freeze so a stored declaration can't be mutated
+      # post-registration by code that holds a reference to the original
+      # `definition` Hash.
+      def deep_freeze(value)
+        case value
+        when Hash
+          value.each { |_, v| deep_freeze(v) }
+          value.freeze
+        when Array
+          value.each { |v| deep_freeze(v) }
+          value.freeze
+        else
+          value.freeze if value.respond_to?(:freeze) && !value.frozen? rescue value
+          value
+        end
+      end
+    end
+  end
+end

data/lib/parse/model/date.rb

@@ -0,0 +1,88 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "time"
+require "date"
+require "active_model"
+require "active_support"
+require "active_support/inflector"
+require "active_support/core_ext/object"
+require "active_support/core_ext/date/calculations"
+require "active_support/core_ext/date_time/calculations"
+require "active_support/core_ext/time/calculations"
+require "active_model/serializers/json"
+require_relative "model"
+
+module Parse
+  # This class manages dates in the special JSON format it requires for
+  # properties of type _:date_.
+  class Date < ::DateTime
+    # The default attributes in a Parse Date hash.
+    ATTRIBUTES = { __type: :string, iso: :string }.freeze
+    include ::ActiveModel::Model
+    include ::ActiveModel::Serializers::JSON
+
+    # @return [Parse::Model::TYPE_DATE]
+    def self.parse_class; Parse::Model::TYPE_DATE; end
+    # @return [Parse::Model::TYPE_DATE]
+    def parse_class; self.class.parse_class; end
+
+    alias_method :__type, :parse_class
+
+    # @return [Hash]
+    def attributes
+      ATTRIBUTES
+    end
+
+    # @return [String] the ISO8601 time string including milliseconds
+    def iso
+      # For Rails 8+ compatibility, avoid to_time and use appropriate UTC conversion
+      if respond_to?(:utc)
+        utc.iso8601(3)
+      else
+        # Fallback for Date objects without time zone info
+        to_datetime.utc.iso8601(3)
+      end
+    end
+
+    # @return (see #iso)
+    def to_s(*args)
+      args.empty? ? iso : super(*args)
+    end
+  end
+end
+
+# Adds extensions to Time class to be compatible with {Parse::Date}.
+class Time
+  # @return [Parse::Date] Converts object to Parse::Date
+  def parse_date
+    Parse::Date.parse iso8601(3)
+  end
+end
+
+# Adds extensions to DateTime class to be compatible with {Parse::Date}.
+class DateTime
+  # @return [Parse::Date] Converts object to Parse::Date
+  def parse_date
+    Parse::Date.parse iso8601(3)
+  end
+end
+
+# Adds extensions to ActiveSupport class to be compatible with {Parse::Date}.
+module ActiveSupport
+  # Adds extensions to ActiveSupport::TimeWithZone class to be compatible with {Parse::Date}.
+  class TimeWithZone
+    # @return [Parse::Date] Converts object to Parse::Date
+    def parse_date
+      Parse::Date.parse iso8601(3)
+    end
+  end
+end
+
+# Adds extensions to Date class to be compatible with {Parse::Date}.
+class Date
+  # @return [Parse::Date] Converts object to Parse::Date
+  def parse_date
+    Parse::Date.parse iso8601
+  end
+end

data/lib/parse/model/email.rb

@@ -0,0 +1,213 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "model"
+
+module Parse
+  # This class provides email validation for Parse properties.
+  # It wraps a string value and provides validation according to RFC 5322.
+  #
+  # When declaring a property of type :email, the framework will automatically add a validation
+  # to ensure the email is either nil or a valid email address format.
+  #
+  # @example
+  #   class Contact < Parse::Object
+  #     property :email, :email
+  #     property :work_email, :email, required: true
+  #   end
+  #
+  #   contact = Contact.new
+  #   contact.email = "user@example.com"
+  #   contact.email.valid?     # => true
+  #   contact.email.local      # => "user"
+  #   contact.email.domain     # => "example.com"
+  #
+  #   contact.email = "invalid"
+  #   contact.email.valid?     # => false
+  #
+  # @version 3.0.0
+  class Email
+    # RFC 5322 compliant email regex (simplified but robust version)
+    # This regex validates most common email formats while avoiding catastrophic backtracking.
+    # For stricter validation, consider using a dedicated email validation library.
+    EMAIL_REGEX = /\A[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*\z/
+
+    # Common disposable email domains (for optional filtering)
+    DISPOSABLE_DOMAINS = %w[
+      mailinator.com guerrillamail.com tempmail.com throwaway.email
+      10minutemail.com fakeinbox.com trashmail.com
+    ].freeze
+
+    # @return [String] the raw input value
+    attr_reader :raw
+
+    # @return [String] the normalized email address (or nil if invalid input)
+    attr_reader :address
+
+    # Creates a new Email instance.
+    #
+    # @overload new(address)
+    #   @param address [String] an email address
+    #   @return [Parse::Email]
+    # @overload new(email)
+    #   @param email [Parse::Email] another Email instance to copy
+    #   @return [Parse::Email]
+    #
+    # @example
+    #   Parse::Email.new("user@example.com")
+    #   Parse::Email.new("  USER@EXAMPLE.COM  ")  # Will normalize
+    def initialize(value)
+      @raw = nil
+      @address = nil
+
+      if value.is_a?(String)
+        @raw = value
+        @address = normalize(value)
+      elsif value.is_a?(Parse::Email)
+        @raw = value.raw
+        @address = value.address
+      elsif value.respond_to?(:to_s) && !value.nil?
+        @raw = value.to_s
+        @address = normalize(@raw)
+      end
+    end
+
+    # Normalize an email address.
+    # - Strips whitespace
+    # - Converts to lowercase
+    #
+    # @param value [String] the email string
+    # @return [String, nil] the normalized email or nil if blank
+    def normalize(value)
+      return nil if value.blank?
+      value.to_s.strip.downcase
+    end
+
+    # @return [String, nil] the normalized email address
+    def to_s
+      @address
+    end
+
+    # @return [String, nil] the email address for JSON serialization
+    def as_json(*args)
+      @address
+    end
+
+    # Check if this email address is valid.
+    #
+    # @return [Boolean] true if the email is valid format
+    #
+    # @example
+    #   Parse::Email.new("user@example.com").valid?  # => true
+    #   Parse::Email.new("invalid").valid?           # => false
+    def valid?
+      return false if @address.blank?
+      EMAIL_REGEX.match?(@address)
+    end
+
+    # Get the local part of the email (before @).
+    #
+    # @return [String, nil] the local part or nil if invalid
+    #
+    # @example
+    #   Parse::Email.new("user@example.com").local  # => "user"
+    def local
+      return nil unless valid?
+      @address.split("@").first
+    end
+
+    # Get the domain part of the email (after @).
+    #
+    # @return [String, nil] the domain or nil if invalid
+    #
+    # @example
+    #   Parse::Email.new("user@example.com").domain  # => "example.com"
+    def domain
+      return nil unless valid?
+      @address.split("@").last
+    end
+
+    # Get the top-level domain (TLD) of the email.
+    #
+    # @return [String, nil] the TLD or nil if invalid
+    #
+    # @example
+    #   Parse::Email.new("user@example.com").tld  # => "com"
+    #   Parse::Email.new("user@example.co.uk").tld  # => "uk"
+    def tld
+      d = domain
+      return nil unless d
+      d.split(".").last
+    end
+
+    # Check if this email is from a disposable email service.
+    # Note: This is a basic check against a small list. For production use,
+    # consider using a dedicated disposable email detection service.
+    #
+    # @return [Boolean] true if the domain is a known disposable email provider
+    #
+    # @example
+    #   Parse::Email.new("user@mailinator.com").disposable?  # => true
+    #   Parse::Email.new("user@gmail.com").disposable?       # => false
+    def disposable?
+      d = domain
+      return false unless d
+      DISPOSABLE_DOMAINS.include?(d)
+    end
+
+    # Format the email with the local part obscured for privacy.
+    #
+    # @return [String, nil] the masked email or nil if invalid
+    #
+    # @example
+    #   Parse::Email.new("username@example.com").masked  # => "u***e@example.com"
+    def masked
+      return nil unless valid?
+      l = local
+      d = domain
+      return nil unless l && d
+
+      if l.length <= 2
+        "#{l[0]}*@#{d}"
+      else
+        "#{l[0]}#{"*" * [l.length - 2, 3].min}#{l[-1]}@#{d}"
+      end
+    end
+
+    # Check equality with another email.
+    #
+    # @param other [Parse::Email, String] the other email
+    # @return [Boolean] true if the emails are equal
+    def ==(other)
+      if other.is_a?(Parse::Email)
+        @address == other.address
+      elsif other.is_a?(String)
+        @address == normalize(other)
+      else
+        false
+      end
+    end
+
+    # @return [Boolean] true if the email is blank/nil
+    def blank?
+      @address.blank?
+    end
+
+    # @return [Boolean] true if the email is present
+    def present?
+      !blank?
+    end
+
+    # Type casting support for Parse properties.
+    # This allows the property system to convert values to Email instances.
+    #
+    # @param value [Object] the value to typecast
+    # @return [Parse::Email, nil] the Email instance or nil
+    # @api private
+    def self.typecast(value)
+      return nil if value.nil?
+      return value if value.is_a?(Parse::Email)
+      Parse::Email.new(value)
+    end
+  end
+end