parse-stack-next 4.5.0 → 5.0.1

data/lib/parse/embeddings.rb

@@ -0,0 +1,225 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "monitor"
+
+module Parse
+  # Pluggable embedding-provider registry for `:vector` properties and
+  # the upcoming `find_similar(text:)` / `Parse::Retrieval.retrieve`
+  # surfaces.
+  #
+  # Text-only providers shipped:
+  #
+  # * {Fixture}   — deterministic, zero-network. Auto-registered as
+  #   `:fixture` so tests can call `Parse::Embeddings.provider(:fixture)`
+  #   with no setup.
+  # * {OpenAI}    — text-embedding-3-{small,large} and ada-002.
+  # * {Cohere}    — embed-{english,multilingual}-v3.0 and `*-light-v3.0`.
+  #   Distinguishes `:search_query` / `:search_document` at the wire.
+  # * {Voyage}    — voyage-4 family (incl. open-weight `voyage-4-nano`),
+  #   voyage-3 family, voyage-code-3, voyage-finance-2, voyage-law-2.
+  #   Distinguishes input types.
+  # * {Jina}      — jina-embeddings-v3/v4/v5 (text + omni-text mode),
+  #   jina-code-embeddings-{0.5b,1.5b}. Matryoshka via `dimensions:`.
+  # * {Qwen}      — qwen3-embedding-{0.6b,4b,8b} via Alibaba Cloud
+  #   DashScope compatible-mode. All Matryoshka. The same checkpoints
+  #   are open-weight on Hugging Face (Apache 2.0) for self-hosting
+  #   behind {LocalHTTP}.
+  # * {LocalHTTP} — generic OpenAI-compatible client for Ollama,
+  #   LM Studio, vLLM, etc. Configure-time SSRF gate; requires
+  #   `allow_private_endpoint: true` to talk to localhost.
+  #
+  # Image / multimodal embedding (`embed_image`) is a forthcoming
+  # feature — the {Provider#embed_image} hook is defined but only the
+  # multimodal-capable providers will override it.
+  #
+  # == Registration
+  #
+  # Two equivalent forms. {.register} is the canonical one-liner and
+  # what every example in the gem uses; {.configure} is the block form
+  # for registering several providers at once or for Rails-style
+  # initializers. Both end up at the same {ProviderRegistry}, so pick
+  # whichever reads better in context.
+  #
+  # @example canonical: register one provider
+  #   Parse::Embeddings.register(:openai,
+  #     Parse::Embeddings::OpenAI.new(api_key: ENV.fetch("OPENAI_API_KEY")))
+  #
+  # @example block form for several providers
+  #   Parse::Embeddings.configure do |c|
+  #     c.providers[:openai] = Parse::Embeddings::OpenAI.new(api_key: ENV.fetch("OPENAI_API_KEY"))
+  #     c.providers[:openai_large] = Parse::Embeddings::OpenAI.new(
+  #       api_key: ENV.fetch("OPENAI_API_KEY"), model: "text-embedding-3-large")
+  #   end
+  #
+  # @example lookup
+  #   Parse::Embeddings.provider(:openai)   # => the registered instance
+  #   Parse::Embeddings.provider(:fixture)  # => default Fixture, zero-config
+  module Embeddings
+    # Common superclass for every embeddings-layer exception. Concrete
+    # providers (OpenAI, Cohere, Voyage, …) should raise subclasses of
+    # this so retry middleware and caller `rescue` chains have a single
+    # target. Inherits from {StandardError}, not {Parse::Error}, because
+    # embedding providers are external HTTP boundaries — their failures
+    # are distinct from Parse Server protocol errors.
+    class Error < StandardError; end
+
+    # Raised when a provider returns a response that doesn't satisfy the
+    # contract (wrong length, NaN, ±Inf, non-Array, wrong-width vector,
+    # non-Float/Integer elements). See {Provider#validate_response!}.
+    class InvalidResponseError < Error; end
+
+    # Raised when {Embeddings.provider} is called with an unknown name
+    # and no built-in default exists for that key. Remains an
+    # {ArgumentError} (not an {Error}) so config-time mistakes are
+    # distinguishable from runtime provider failures.
+    class ProviderNotRegistered < ArgumentError; end
+  end
+end
+
+# Provider must load before OpenAI (which references it as superclass)
+# and before ProviderRegistry below (which type-checks against it).
+require_relative "embeddings/provider"
+
+module Parse
+  module Embeddings
+    # Hash subclass that enforces {Provider} membership at assignment
+    # time. Without this, `configuration.providers[:openai] = "anything"`
+    # would silently bypass {Embeddings.register}'s type-check and let a
+    # duck-typed object skip {Provider#validate_response!} — defeating
+    # the whole boundary contract.
+    class ProviderRegistry < Hash
+      def []=(name, provider)
+        unless provider.is_a?(Provider)
+          raise ArgumentError,
+                "Parse::Embeddings::ProviderRegistry: #{name.inspect} expects a " \
+                "Parse::Embeddings::Provider instance (got #{provider.class})."
+        end
+        super(name.to_sym, provider)
+      end
+      alias_method :store, :[]=
+    end
+
+    # Configuration container yielded to {Embeddings.configure}.
+    class Configuration
+      # @return [ProviderRegistry] type-checked provider registry.
+      attr_reader :providers
+
+      def initialize
+        @providers = ProviderRegistry.new
+      end
+    end
+
+    # Monitor guarding {Embeddings.configuration} memoization and
+    # {Embeddings.register} writes. MRI's GVL would normally absorb
+    # the race on `@configuration ||= ...`, but JRuby and TruffleRuby
+    # can produce two `Configuration` instances when two threads race
+    # at boot (and lose any provider written to the loser). A Monitor
+    # (rather than a Mutex) is used so that `register` — which holds
+    # the lock and then calls `configuration` — can re-enter without
+    # deadlocking on the first-touch allocation path.
+    CONFIG_MUTEX = Monitor.new
+
+    class << self
+      # Block form for registering multiple providers at once. Prefer
+      # the one-liner {.register} when adding a single provider; this
+      # form pays off when an initializer needs to set several or to
+      # mutate the registry conditionally.
+      #
+      # @yieldparam config [Configuration]
+      # @return [Configuration]
+      def configure
+        yield configuration if block_given?
+        configuration
+      end
+
+      # @return [Configuration] the singleton configuration object.
+      def configuration
+        # Double-checked memoization. The fast path is a single ivar
+        # read; the slow path enters the mutex only when the
+        # configuration is unallocated.
+        @configuration || CONFIG_MUTEX.synchronize { @configuration ||= Configuration.new }
+      end
+
+      # Canonical one-liner: register a single provider under `name`.
+      # Overwrites any previous registration. Use {.configure} for
+      # multi-provider blocks.
+      #
+      # @param name [Symbol, String]
+      # @param provider [Provider]
+      # @return [Provider] the registered provider.
+      def register(name, provider)
+        unless provider.is_a?(Provider)
+          raise ArgumentError,
+                "Parse::Embeddings.register: #{name.inspect} expects a Parse::Embeddings::Provider " \
+                "instance (got #{provider.class})."
+        end
+        CONFIG_MUTEX.synchronize do
+          configuration.providers[name.to_sym] = provider
+        end
+      end
+
+      # Look up a registered provider.
+      #
+      # **Zero-config fallback:** `:fixture` returns a default
+      # {Fixture} instance (64-dim, deterministic) when nothing is
+      # registered. Every other name raises {ProviderNotRegistered}.
+      # Tests can rely on `provider(:fixture)` working out of the box;
+      # production code must register what it uses.
+      #
+      # @param name [Symbol, String]
+      # @return [Provider]
+      # @raise [ProviderNotRegistered] when the name is unknown.
+      def provider(name)
+        # Avoid blindly `to_sym`-ing the caller's input. An LLM tool or
+        # webhook handler that pipes its `name:` argument through here
+        # would otherwise let a remote caller grow the symbol table at
+        # will. Ruby 3.2+ GCs symbols so the practical impact is small,
+        # but a string-matched lookup costs nothing and closes the gap.
+        if name.is_a?(Symbol)
+          return configuration.providers[name] if configuration.providers.key?(name)
+          key_string = name.to_s
+        else
+          key_string = name.to_s
+          found = configuration.providers.keys.find { |k| k.to_s == key_string }
+          return configuration.providers[found] if found
+        end
+        if key_string == "fixture"
+          CONFIG_MUTEX.synchronize do
+            return configuration.providers[:fixture] ||= Fixture.new
+          end
+        end
+        raise ProviderNotRegistered,
+              "Parse::Embeddings.provider(#{name.inspect}): no provider registered. " \
+              "Register one via Parse::Embeddings.register(#{name.inspect}, …)."
+      end
+
+      # Names of currently-registered providers (does NOT include the
+      # implicit `:fixture` fallback unless it's been instantiated).
+      #
+      # @return [Array<Symbol>]
+      def registered_provider_names
+        configuration.providers.keys
+      end
+
+      # Reset the entire registry — intended for test teardown only.
+      # Production code should never call this; use {.register} to
+      # override a single provider.
+      #
+      # @return [void]
+      def reset!
+        CONFIG_MUTEX.synchronize { @configuration = nil }
+      end
+    end
+  end
+end
+
+# Concrete providers — loaded after Error / Provider / ProviderRegistry
+# so their class bodies can reference those constants.
+require_relative "embeddings/fixture"
+require_relative "embeddings/openai"
+require_relative "embeddings/cohere"
+require_relative "embeddings/voyage"
+require_relative "embeddings/jina"
+require_relative "embeddings/qwen"
+require_relative "embeddings/local_http"

data/lib/parse/graphql/scalars.rb

@@ -0,0 +1,53 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Shared GraphQL types for Parse-native shapes (File, GeoPoint) and a
+# JSON scalar fallback for `:array` / `:object` columns that have no
+# declared element type.
+#
+# Object types are preferred over scalars wherever the shape is
+# stable and small: graphql-ruby's own Scalars guide explicitly warns
+# that JSON scalars "completely lose all GraphQL type safety". File and
+# GeoPoint both qualify — fixed two-field shapes that may grow
+# additively (e.g. `content_type`, `size`) without a breaking change.
+#
+# Loaded only when the `graphql` gem is available — guarded by
+# `Parse::GraphQL.available?` in `lib/parse/graphql.rb`.
+
+module Parse
+  module GraphQL
+    module Types
+      class ParseFile < ::GraphQL::Schema::Object
+        graphql_name "ParseFile"
+        description "A Parse File reference (URL + filename)."
+        field :url, String, null: false
+        field :name, String, null: true
+      end
+
+      class ParseGeoPoint < ::GraphQL::Schema::Object
+        graphql_name "ParseGeoPoint"
+        description "A Parse GeoPoint (latitude/longitude in degrees, WGS84)."
+        field :latitude, Float, null: false
+        field :longitude, Float, null: false
+      end
+
+      # Fallback for `:array` / `:object` columns with no element type.
+      # Emits a warning at codegen time when used so authors know to
+      # narrow the type if possible. Subscribers needing typed list
+      # elements should declare `belongs_to` / `has_many` instead of
+      # a raw `property :foo, :array`.
+      class JSON < ::GraphQL::Schema::Scalar
+        graphql_name "JSON"
+        description "Arbitrary JSON value (object, array, scalar, or null)."
+
+        def self.coerce_input(value, _ctx)
+          value
+        end
+
+        def self.coerce_result(value, _ctx)
+          value
+        end
+      end
+    end
+  end
+end

data/lib/parse/graphql/type_generator.rb

@@ -0,0 +1,264 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  module GraphQL
+    # Generates `GraphQL::Schema::Object` subclasses from Parse::Object
+    # subclasses by reading the class-level property and association
+    # registries: `fields`, `field_map`, `references` (belongs_to),
+    # `has_one_associations`, `has_many_associations`, and `relations`.
+    #
+    # v1 scope: type shape only. Default graphql-ruby field resolution
+    # invokes the same-named method on the underlying Ruby object, and
+    # Parse::Object subclasses already expose typed accessors
+    # (`song.album`, `band.fans`, etc.) — so no resolvers are emitted.
+    # Pagination arguments, Loaders, and Relay connections are deferred
+    # until query/mutation passthrough lands (TODO §7).
+    #
+    # Cross-class references (pointers, has_many) require all referenced
+    # model types to be in the registry BEFORE field emission. Use
+    # `generate_all` to codegen a list of models in one call (two-pass:
+    # stub classes first, then add fields), or `generate` with an
+    # explicit `registry:` hash if you want incremental control.
+    class TypeGenerator
+      # Maps Parse property `:type` symbols to graphql-ruby built-ins.
+      # Cross-class references (`:pointer`, `:relation`) are NOT in this
+      # map — they need the target class and are handled per-field.
+      # Nil mappings fall through to the JSON scalar with a warning.
+      SCALAR_TYPE_MAP = {
+        string: ::GraphQL::Types::String,
+        integer: ::GraphQL::Types::Int,
+        float: ::GraphQL::Types::Float,
+        boolean: ::GraphQL::Types::Boolean,
+        date: ::GraphQL::Types::ISO8601DateTime,
+        timezone: ::GraphQL::Types::String,
+        phone: ::GraphQL::Types::String,
+        email: ::GraphQL::Types::String,
+        # Parse Bytes is a `{__type: Bytes, base64: ...}` wrapper, not a
+        # bare string — the accessor returns the wrapped object, so
+        # falling through to the JSON scalar (with a warn) is safer than
+        # ::String.to_s on the hash. Subscribers needing structured byte
+        # access should declare a `:string` property containing the base64.
+        bytes: nil,
+        polygon: nil, # JSON fallback (GeoJSON-shaped, multi-ring)
+        # Parse vector columns are bounded-length Float arrays
+        # (embeddings). Emit as a typed list of Floats, not JSON.
+        vector: [::GraphQL::Types::Float],
+        array: nil,   # JSON fallback (no element type known)
+        object: nil,  # JSON fallback
+      }.freeze
+
+      # Property types that are deliberately omitted. ACL is internal
+      # authz metadata; exposing it via GraphQL would leak authorization
+      # shape into clients. The objectId is exposed under the canonical
+      # `id: ID` field separately.
+      OMITTED_TYPES = %i[acl].freeze
+
+      # Generate types for a list of models in one call. Two-pass:
+      # creates empty stub classes for every model first so cross-class
+      # references resolve regardless of declaration order.
+      #
+      # @param model_classes [Array<Class>] Parse::Object subclasses.
+      # @return [Hash{String => Class}] registry of generated types
+      #   keyed by Parse class name.
+      def self.generate_all(model_classes)
+        registry = {}
+        # Pass 1: stub classes registered by parse_class name.
+        model_classes.each do |model|
+          validate!(model)
+          registry[model.parse_class] = build_stub(model)
+        end
+        # Pass 2: populate fields. Cross-references now resolve.
+        model_classes.each do |model|
+          new(model, registry: registry, _prebuilt: registry[model.parse_class]).populate_fields
+        end
+        detect_name_collisions!(registry)
+        registry
+      end
+
+      # graphql-ruby requires unique `graphql_name` across the schema.
+      # `build_stub` strips underscores so `_User` and `User` collapse
+      # to the same name. Raise a clear error rather than letting
+      # graphql-ruby's `DuplicateNamesError` surface at schema-build
+      # time, which doesn't say which Parse classes collided.
+      def self.detect_name_collisions!(registry)
+        by_gql_name = registry.each_with_object({}) do |(parse_name, type), acc|
+          (acc[type.graphql_name] ||= []) << parse_name
+        end
+        collisions = by_gql_name.select { |_, names| names.size > 1 }
+        return if collisions.empty?
+        details = collisions.map { |gql, parse| "#{gql} ← #{parse.join(', ')}" }.join('; ')
+        raise "Parse::GraphQL::TypeGenerator: graphql_name collisions: #{details}. " \
+              "Parse class names that differ only by underscores collapse to the same " \
+              "GraphQL type name. Rename or generate the conflicting classes separately."
+      end
+
+      # Generate a single type. If the model has belongs_to / has_many
+      # references to other Parse classes, those targets must already be
+      # in the registry — otherwise an error is raised at field-emit
+      # time. Prefer `generate_all` when you have a graph of models.
+      #
+      # @param model_class [Class] a Parse::Object subclass.
+      # @param registry [Hash, nil] shared registry; mutated in place.
+      # @return [Class] anonymous `GraphQL::Schema::Object` subclass.
+      def self.generate(model_class, registry: nil)
+        validate!(model_class)
+        registry ||= {}
+        stub = registry[model_class.parse_class] ||= build_stub(model_class)
+        new(model_class, registry: registry, _prebuilt: stub).populate_fields
+        stub
+      end
+
+      def self.validate!(model_class)
+        unless model_class.is_a?(Class) && model_class < Parse::Object
+          raise ArgumentError,
+                "Parse::GraphQL::TypeGenerator requires a Parse::Object subclass, got #{model_class.inspect}"
+        end
+      end
+
+      def self.build_stub(model_class)
+        type_name = model_class.parse_class.tr("_", "")
+        description_text = "Generated GraphQL type for Parse class #{model_class.parse_class}."
+        Class.new(::GraphQL::Schema::Object) do
+          graphql_name type_name
+          description description_text
+        end
+      end
+
+      def initialize(model_class, registry:, _prebuilt:)
+        @model_class = model_class
+        @registry = registry
+        @klass = _prebuilt
+      end
+
+      def populate_fields
+        emit_scalar_fields
+        emit_belongs_to_fields
+        emit_has_one_fields
+        emit_has_many_fields
+        @klass
+      end
+
+      private
+
+      # Iterate over local accessor names from field_map so we never
+      # register the same field twice (Parse stores both local and
+      # remote names in `fields`).
+      def emit_scalar_fields
+        skip_keys = pointer_field_keys | relation_field_keys | array_assoc_field_keys
+        emitted = {}
+
+        @model_class.field_map.each do |local_key, _remote_field|
+          next if skip_keys.include?(local_key)
+          parse_type = @model_class.fields[local_key]
+          next if parse_type.nil?
+          next if OMITTED_TYPES.include?(parse_type)
+
+          gql_type = scalar_graphql_type(parse_type, local_key)
+          next if gql_type.nil?
+
+          # objectId → expose as canonical `id: ID!` per GraphQL idiom.
+          if local_key == :id
+            next if emitted[:id]
+            @klass.field :id, ::GraphQL::Types::ID, null: false
+            emitted[:id] = true
+          else
+            next if emitted[local_key]
+            @klass.field(local_key, gql_type, null: true)
+            emitted[local_key] = true
+          end
+        end
+      end
+
+      def emit_belongs_to_fields
+        @model_class.references.each do |parse_field, target_class_name|
+          accessor = field_to_accessor(parse_field)
+          target = registry_lookup!(target_class_name)
+          @klass.field(accessor, target, null: true)
+        end
+      end
+
+      def emit_has_one_fields
+        return unless @model_class.respond_to?(:has_one_associations)
+        @model_class.has_one_associations.each do |name, meta|
+          target = registry_lookup!(meta[:target_class])
+          @klass.field(name, target, null: true)
+        end
+      end
+
+      def emit_has_many_fields
+        return unless @model_class.respond_to?(:has_many_associations)
+        @model_class.has_many_associations.each do |name, meta|
+          target = registry_lookup!(meta[:target_class])
+          @klass.field(name, [target], null: true)
+        end
+      end
+
+      # -----------------------------------------------------------------
+      # helpers
+      # -----------------------------------------------------------------
+
+      def scalar_graphql_type(parse_type, field_name)
+        case parse_type
+        when :file then Parse::GraphQL::Types::ParseFile
+        when :geopoint then Parse::GraphQL::Types::ParseGeoPoint
+        when :pointer, :relation
+          nil # handled by emit_belongs_to_fields / emit_has_many_fields
+        else
+          mapped = SCALAR_TYPE_MAP[parse_type]
+          return mapped unless mapped.nil?
+          # nil mapping → JSON fallback. Warn so authors know to narrow.
+          warn "[Parse::GraphQL] #{@model_class.parse_class}.#{field_name}: " \
+               "Parse type #{parse_type.inspect} has no specific GraphQL " \
+               "type; emitting as JSON scalar."
+          Parse::GraphQL::Types::JSON
+        end
+      end
+
+      def registry_lookup!(target_class_name)
+        target = @registry[target_class_name]
+        if target.nil?
+          raise "Parse::GraphQL::TypeGenerator: no generated type found for " \
+                "#{target_class_name.inspect}. Call generate_all with all " \
+                "referenced models, or generate #{target_class_name} first " \
+                "into the shared `registry:` hash."
+        end
+        target
+      end
+
+      def pointer_field_keys
+        return @pointer_field_keys if defined?(@pointer_field_keys)
+        # references stores parse_field => target. Map to local accessors.
+        @pointer_field_keys = @model_class.references.keys.map do |parse_field|
+          field_to_accessor(parse_field)
+        end.to_set
+      end
+
+      def relation_field_keys
+        @relation_field_keys ||= @model_class.relations.keys.map(&:to_sym).to_set
+      end
+
+      # `has_many through: :array` stores the field as `:array` in
+      # `fields` — exclude it from scalar emission so it's not emitted
+      # twice (once as JSON, once as `[Type]`).
+      def array_assoc_field_keys
+        return @array_assoc_field_keys if defined?(@array_assoc_field_keys)
+        keys = []
+        if @model_class.respond_to?(:has_many_associations)
+          @model_class.has_many_associations.each_value do |meta|
+            keys << meta[:field] if meta[:storage] == :array && meta[:field]
+          end
+        end
+        @array_assoc_field_keys = keys.map(&:to_sym).to_set
+      end
+
+      # Reverse field_map: parse_field (remote) → local accessor symbol.
+      def field_to_accessor(parse_field)
+        @model_class.field_map.each do |local, remote|
+          return local if remote.to_sym == parse_field.to_sym
+        end
+        parse_field.to_sym
+      end
+    end
+  end
+end

data/lib/parse/graphql.rb

@@ -0,0 +1,48 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Parse::GraphQL — schema introspection → graphql-ruby type generation.
+#
+# The `graphql` gem is an OPTIONAL dependency. It is intentionally NOT a
+# runtime dependency of parse-stack: users who never opt into GraphQL
+# codegen should not pay the load cost. Mirror the
+# `Parse::MongoDB.gem_available?` soft-require pattern.
+#
+# Usage:
+#   require "parse/graphql"
+#   raise "install the 'graphql' gem first" unless Parse::GraphQL.available?
+#   SongType = Parse::GraphQL::TypeGenerator.generate(Song)
+#
+# v1 scope: type generation only. Resolvers (query/mutation passthrough,
+# Loaders, Node interface, connections) are intentionally deferred — see
+# TODO.md §7. The generated types work with default graphql-ruby field
+# resolution because Parse::Object subclasses already expose typed
+# accessors (`song.album`, `band.fans`).
+
+module Parse
+  module GraphQL
+    class << self
+      # @return [Boolean] true if the `graphql` gem can be loaded.
+      def available?
+        return @gem_available if defined?(@gem_available)
+        @gem_available = begin
+          require "graphql"
+          true
+        rescue LoadError
+          false
+        end
+      end
+
+      # Force-reset the cached availability flag. Test-only.
+      # @!visibility private
+      def reset!
+        remove_instance_variable(:@gem_available) if defined?(@gem_available)
+      end
+    end
+  end
+end
+
+if Parse::GraphQL.available?
+  require_relative "graphql/scalars"
+  require_relative "graphql/type_generator"
+end

data/lib/parse/live_query/client.rb

@@ -87,14 +87,29 @@ module Parse
       # @return [Integer] frame read timeout in seconds
       attr_reader :frame_read_timeout
 
+      # Sentinel used to distinguish "caller passed nothing" from
+      # "caller explicitly passed nil". The latter must NOT fall through
+      # to the LiveQuery configuration or the parent Parse client value
+      # — that fallthrough was a silent master-key-smuggling bug for
+      # client-mode (no-master) callers. Aliased to the top-level
+      # {Parse::NOT_PROVIDED} so any other SDK code that needs the same
+      # "omitted vs nil" distinction reuses one identity-comparable
+      # constant.
+      NOT_PROVIDED = Parse::NOT_PROVIDED
+      private_constant :NOT_PROVIDED
+
       # Create a new LiveQuery client
       # @param url [String] WebSocket URL (wss://...)
       # @param application_id [String] Parse application ID
       # @param client_key [String] Parse REST API key
-      # @param master_key [String, nil] Parse master key (optional)
+      # @param master_key [String, nil] Parse master key. Pass `nil`
+      #   explicitly to force client-mode (no master key on the
+      #   subscription handshake) even when the parent Parse client has
+      #   one. Omit the argument to fall back to the LiveQuery config
+      #   or the parent Parse client.
       # @param auto_connect [Boolean] connect immediately (default: true)
       # @param auto_reconnect [Boolean] automatically reconnect on disconnect (default: true)
-      def initialize(url: nil, application_id: nil, client_key: nil, master_key: nil,
+      def initialize(url: nil, application_id: nil, client_key: nil, master_key: NOT_PROVIDED,
                      auto_connect: nil, auto_reconnect: nil)
         cfg = config
 
@@ -104,8 +119,11 @@ module Parse
                           parse_client_value(:application_id)
         @client_key = client_key || cfg.client_key ||
                       parse_client_value(:api_key)
-        @master_key = master_key || cfg.master_key ||
-                      parse_client_value(:master_key)
+        @master_key = if master_key.equal?(NOT_PROVIDED)
+            cfg.master_key || parse_client_value(:master_key)
+          else
+            master_key
+          end
 
         @auto_connect = auto_connect.nil? ? cfg.auto_connect : auto_connect
         @auto_reconnect = auto_reconnect.nil? ? cfg.auto_reconnect : auto_reconnect
@@ -787,11 +805,12 @@ module Parse
       # Dispatch event to subscription (called from event queue processor)
       # @param item [Hash] contains :subscription and :event
       def dispatch_event(item)
+        event = nil
         subscription = item[:subscription]
         event = item[:event]
         subscription.handle_event(event)
       rescue => e
-        Logging.error("Event dispatch error", error: e, event_type: event.type)
+        Logging.error("Event dispatch error", error: e, event_type: event&.type)
       end
 
       # Handle server error

data/lib/parse/live_query/subscription.rb

@@ -33,9 +33,22 @@ module Parse
     #   subscription.unsubscribe
     #
     class Subscription
-      # Class-level monitor for request ID generation
-      @@id_monitor = Monitor.new
-      @@request_counter = 0
+      # Class-instance state (rather than @@class_var) for request ID generation.
+      # Held on the Subscription singleton and guarded by a Monitor so concurrent
+      # subscriptions across threads cannot tear the counter. See
+      # Parse::ACLScope's `@no_acl_warned` pattern for the same convention.
+      @id_monitor = Monitor.new
+      @request_counter = 0
+
+      class << self
+        # @!visibility private
+        attr_reader :id_monitor
+
+        # @!visibility private
+        def next_request_id
+          @id_monitor.synchronize { @request_counter += 1 }
+        end
+      end
 
       # @return [Integer] unique request ID for this subscription
       attr_reader :request_id
@@ -285,9 +298,7 @@ module Parse
       # Generate a unique request ID (thread-safe)
       # @return [Integer]
       def generate_request_id
-        @@id_monitor.synchronize do
-          @@request_counter += 1
-        end
+        self.class.next_request_id
       end
     end
   end