Module: Parse

Defined in:
lib/parse/agent.rb,
lib/parse/lock.rb,
lib/parse/query.rb,
lib/parse/stack.rb,
lib/parse/client.rb,
lib/parse/schema.rb,
lib/parse/api/all.rb,
lib/parse/console.rb,
lib/parse/graphql.rb,
lib/parse/mongodb.rb,
lib/parse/api/push.rb,
lib/parse/webhooks.rb,
lib/parse/acl_scope.rb,
lib/parse/api/batch.rb,
lib/parse/api/files.rb,
lib/parse/api/hooks.rb,
lib/parse/api/users.rb,
lib/parse/clp_scope.rb,
lib/parse/model/acl.rb,
lib/parse/model/clp.rb,
lib/parse/api/config.rb,
lib/parse/api/schema.rb,
lib/parse/api/server.rb,
lib/parse/cache/pool.rb,
lib/parse/embeddings.rb,
lib/parse/embeddings.rb,
lib/parse/live_query.rb,
lib/parse/live_query.rb,
lib/parse/model/date.rb,
lib/parse/model/file.rb,
lib/parse/model/push.rb,
lib/parse/agent/tools.rb,
lib/parse/api/objects.rb,
lib/parse/cache/redis.rb,
lib/parse/model/bytes.rb,
lib/parse/model/email.rb,
lib/parse/model/model.rb,
lib/parse/model/phone.rb,
lib/parse/stack/tasks.rb,
lib/parse/agent/errors.rb,
lib/parse/api/sessions.rb,
lib/parse/atlas_search.rb,
lib/parse/client/batch.rb,
lib/parse/lock_backend.rb,
lib/parse/model/object.rb,
lib/parse/model/vector.rb,
lib/parse/query/cursor.rb,
lib/parse/agent/prompts.rb,
lib/parse/api/aggregate.rb,
lib/parse/api/analytics.rb,
lib/parse/model/geojson.rb,
lib/parse/model/pointer.rb,
lib/parse/model/polygon.rb,
lib/parse/stack/railtie.rb,
lib/parse/stack/version.rb,
lib/parse/vector_search.rb,
lib/parse/agent/describe.rb,
lib/parse/client/caching.rb,
lib/parse/client/logging.rb,
lib/parse/client/request.rb,
lib/parse/model/geopoint.rb,
lib/parse/query/ordering.rb,
lib/parse/client/protocol.rb,
lib/parse/client/response.rb,
lib/parse/embeddings/jina.rb,
lib/parse/embeddings/qwen.rb,
lib/parse/graphql/scalars.rb,
lib/parse/lookup_rewriter.rb,
lib/parse/model/time_zone.rb,
lib/parse/query/operation.rb,
lib/parse/retrieval/chunk.rb,
lib/parse/two_factor_auth.rb,
lib/parse/agent/mcp_client.rb,
lib/parse/agent/mcp_server.rb,
lib/parse/api/path_segment.rb,
lib/parse/client/profiling.rb,
lib/parse/embeddings/cache.rb,
lib/parse/live_query/event.rb,
lib/parse/query/constraint.rb,
lib/parse/webhooks/payload.rb,
lib/parse/embeddings/cohere.rb,
lib/parse/embeddings/openai.rb,
lib/parse/embeddings/voyage.rb,
lib/parse/live_query/client.rb,
lib/parse/model/core/errors.rb,
lib/parse/model/core/schema.rb,
lib/parse/model/validations.rb,
lib/parse/pipeline_security.rb,
lib/parse/query/constraints.rb,
lib/parse/retrieval/chunker.rb,
lib/parse/agent/mcp_rack_app.rb,
lib/parse/agent/metadata_dsl.rb,
lib/parse/agent/rate_limiter.rb,
lib/parse/embeddings/fixture.rb,
lib/parse/live_query/logging.rb,
lib/parse/model/classes/role.rb,
lib/parse/model/classes/user.rb,
lib/parse/model/core/actions.rb,
lib/parse/model/core/actions.rb,
lib/parse/model/core/builder.rb,
lib/parse/retrieval/reranker.rb,
lib/parse/agent/approval_gate.rb,
lib/parse/api/cloud_functions.rb,
lib/parse/atlas_search/result.rb,
lib/parse/client/body_builder.rb,
lib/parse/embeddings/provider.rb,
lib/parse/model/core/describe.rb,
lib/parse/model/core/fetching.rb,
lib/parse/model/core/indexing.rb,
lib/parse/model/core/querying.rb,
lib/parse/retrieval/retriever.rb,
lib/parse/agent/mcp_dispatcher.rb,
lib/parse/agent/metadata_audit.rb,
lib/parse/agent/relation_graph.rb,
lib/parse/atlas_search/session.rb,
lib/parse/client/url_redaction.rb,
lib/parse/embeddings/spend_cap.rb,
lib/parse/retrieval/agent_tool.rb,
lib/parse/vector_search/hybrid.rb,
lib/parse/client/authentication.rb,
lib/parse/embeddings/local_http.rb,
lib/parse/model/classes/product.rb,
lib/parse/model/classes/session.rb,
lib/parse/model/core/properties.rb,
lib/parse/schema/index_migrator.rb,
lib/parse/webhooks/registration.rb,
lib/parse/agent/prompt_hardening.rb,
lib/parse/agent/result_formatter.rb,
lib/parse/embeddings/image_fetch.rb,
lib/parse/graphql/type_generator.rb,
lib/parse/live_query/event_queue.rb,
lib/parse/model/classes/audience.rb,
lib/parse/model/core/create_lock.rb,
lib/parse/webhooks/trigger_audit.rb,
lib/parse/agent/mcp_subscriptions.rb,
lib/parse/agent/metadata_registry.rb,
lib/parse/live_query/subscription.rb,
lib/parse/model/core/field_guards.rb,
lib/parse/agent/cancellation_token.rb,
lib/parse/agent/pipeline_validator.rb,
lib/parse/live_query/configuration.rb,
lib/parse/model/classes/job_status.rb,
lib/parse/model/core/embed_managed.rb,
lib/parse/embeddings/batch_embedder.rb,
lib/parse/live_query/health_monitor.rb,
lib/parse/model/classes/push_status.rb,
lib/parse/query/n_plus_one_detector.rb,
lib/parse/retrieval/reranker/cohere.rb,
lib/parse/atlas_search/index_manager.rb,
lib/parse/live_query/circuit_breaker.rb,
lib/parse/model/associations/has_one.rb,
lib/parse/model/classes/installation.rb,
lib/parse/model/classes/job_schedule.rb,
lib/parse/model/core/parse_reference.rb,
lib/parse/model/core/search_indexing.rb,
lib/parse/webhooks/replay_protection.rb,
lib/parse/agent/constraint_translator.rb,
lib/parse/atlas_search/search_builder.rb,
lib/parse/model/associations/has_many.rb,
lib/parse/model/core/vector_searchable.rb,
lib/parse/schema/search_index_migrator.rb,
lib/parse/model/associations/belongs_to.rb,
lib/parse/model/core/pluralized_aliases.rb,
lib/parse/two_factor_auth/user_extension.rb,
lib/parse/model/associations/collection_proxy.rb,
lib/parse/model/core/enhanced_change_tracking.rb,
lib/parse/model/validations/uniqueness_validator.rb,
lib/parse/model/associations/pointer_collection_proxy.rb,
lib/parse/model/associations/relation_collection_proxy.rb

Overview

Note: Do not require "../object" here - this file is loaded from object.rb and adding that require would create a circular dependency.

Defined Under Namespace

Modules: ACLScope, API, Associations, AtlasSearch, CLPScope, Cache, Console, Core, CreateLock, Embeddings, Generated, GeoJSON, GraphQL, LiveQuery, Lock, LockBackend, LookupRewriter, MFA, Middleware, MongoDB, PipelineSecurity, PluralizedAliases, Properties, Protocol, RegexSecurity, Retrieval, Schema, Stack, Validations, VectorSearch Classes: ACL, Agent, Aggregation, AggregationResult, Audience, AutofetchTriggeredError, BatchOperation, Bytes, CLP, Client, CollectionProxy, Constraint, CreateLockInvalidKey, CreateLockTimeoutError, CreateLockUnavailableError, Cursor, DataType, Date, Email, Error, File, GeoPoint, GroupBy, GroupByDate, GroupedResult, Installation, JobSchedule, JobStatus, Model, NPlusOneDetector, NPlusOneQueryError, Object, Operation, Order, Phone, Pointer, PointerCollectionProxy, Polygon, Product, Push, PushStatus, Query, RecordNotSaved, RelationAction, RelationCollectionProxy, Request, Response, Role, Session, SortableGroupBy, SortableGroupByDate, TimeZone, UnfetchedFieldAccessError, User, Vector, Webhooks

Constant Summary collapse

NOT_PROVIDED =

Sentinel used by SDK methods that need to distinguish "the caller omitted this kwarg" from "the caller explicitly passed nil" — the latter must NOT fall through to a default that would silently re-introduce a value the caller is trying to suppress (e.g. a master-key or session-token override).

Use as the default value of a keyword argument, then check with value.equal?(Parse::NOT_PROVIDED) to detect omission. Comparison by identity is intentional — == on the sentinel is meaningless.

Examples:

Distinguishing nil-pass from omission

def fetch(master_key: Parse::NOT_PROVIDED)
  resolved = master_key.equal?(Parse::NOT_PROVIDED) ? config.master_key : master_key
  # `fetch(master_key: nil)` here produces `nil`, not the config value
end
Object.new.tap do |o|
  def o.inspect
    "Parse::NOT_PROVIDED"
  end
end.freeze
MASTER_KEY_STATE_KEY =

Fiber-local key consulted by the authentication middleware. A truthy entry suppresses the master-key header for the duration of the block set by without_master_key; a :enabled entry forces the master-key header back on inside a nested with_master_key block.

:__parse_master_key_state__
SESSION_TOKEN_STATE_KEY =

Fiber-local key holding the ambient session token consulted by Client#request when no explicit session_token: was passed. Set by with_session; nested blocks save and restore the previous value on exit.

:__parse_session_token__
CACHE_TENANT_PATTERN =

Set an ambient cache-tenant scope for the duration of the block. When set, the Middleware::Caching middleware composes the tenant into the cache key as <base-namespace>:T:<tenant>:… so a multi-tenant Parse application can share one Redis (or any Moneta- backed cache) without per-tenant configuration plumbing through every Parse::Client.new site. Tenants do not see each other's cached responses; a SCAN-delete over <base-namespace>:T:<tenant>:* evicts exactly one tenant cleanly.

This is purely a key namespacing mechanism — it does NOT enforce any access-control semantics. Tenant isolation at the data layer is the job of agent_tenant_scope (per-class scoping) and ACL/CLP. The tenant cache scope's role is to keep tenant A's session-token- keyed cache entry from being served on tenant B's request even when the URL and session token happen to collide.

Fiber-local — composes safely with async and concurrent web frameworks. The scope is per-fiber, not per-thread, and is restored on block exit even if the block raises.

Examples:

wrap an agent invocation under a tenant

Parse.with_cache_tenant("tenant_abc") do
  agent.run(prompt)   # every Parse request issued inside the
                       # block writes/reads tenant-scoped cache
                       # entries
end

compose with with_session

Parse.with_cache_tenant(tenant_id) do
  Parse.with_session(user) do
    Post.all
  end
end

Yields:

  • runs the block with the ambient tenant scope in place

Returns:

  • (Object) —

    the block's return value

Raises:

  • (ArgumentError) —

    when scope contains characters outside [A-Za-z0-9_-] or exceeds 256 bytes.

/\A[A-Za-z0-9_\-]{1,256}\z/.freeze
CURRENT_USER_STATE_KEY =

Fiber-local key holding the User cached by login for current_user lookup. Kept distinct from the session-token key so block-scoped Parse.with_session(tok) (which has only a token, not a user object) doesn't mis-populate it.

:__parse_current_user__
RAG =

Discoverability alias. "RAG" ages badly as a term; Retrieval is the canonical name.

Retrieval

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.autofetch_raise_on_missing_keys ⇒ Object

Returns the value of attribute autofetch_raise_on_missing_keys.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def autofetch_raise_on_missing_keys
  @autofetch_raise_on_missing_keys
end

.cache_write_on_fetch ⇒ Object

Returns the value of attribute cache_write_on_fetch.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def cache_write_on_fetch
  @cache_write_on_fetch
end

.default_query_cache ⇒ Object

Returns the value of attribute default_query_cache.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def default_query_cache
  @default_query_cache
end

.live_query_enabled ⇒ Object

Returns the value of attribute live_query_enabled.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def live_query_enabled
  @live_query_enabled
end

.logging ⇒ Object

Sets Parse::Middleware::BodyBuilder logging. You may specify :debug for additional verbosity.



19
20
21
 
# File 'lib/parse/client/body_builder.rb', line 19

def self.logging
  Parse::Middleware::BodyBuilder.logging
end

.mcp_remote_api ⇒ Object

Returns the value of attribute mcp_remote_api.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def mcp_remote_api
  @mcp_remote_api
end

.mcp_server_enabled ⇒ Object

Returns the value of attribute mcp_server_enabled.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def mcp_server_enabled
  @mcp_server_enabled
end

.mcp_server_port ⇒ Object

Returns the value of attribute mcp_server_port.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def mcp_server_port
  @mcp_server_port
end

.pluralized_aliases ⇒ Object

Returns the value of attribute pluralized_aliases.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def pluralized_aliases
  @pluralized_aliases
end

.rewrite_lookups ⇒ Object

Returns the value of attribute rewrite_lookups.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def rewrite_lookups
  @rewrite_lookups
end

.serialize_only_fetched_fields ⇒ Object

Returns the value of attribute serialize_only_fetched_fields.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def serialize_only_fetched_fields
  @serialize_only_fetched_fields
end

.strict_pointer_shapes ⇒ Object

Returns the value of attribute strict_pointer_shapes.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def strict_pointer_shapes
  @strict_pointer_shapes
end

.strict_property_redefinition ⇒ Object

Returns the value of attribute strict_property_redefinition.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def strict_property_redefinition
  @strict_property_redefinition
end

.suppress_server_version_warning ⇒ Object

Returns the value of attribute suppress_server_version_warning.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def suppress_server_version_warning
  @suppress_server_version_warning
end

.synchronize_classes ⇒ Object

Returns the value of attribute synchronize_classes.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def synchronize_classes
  @synchronize_classes
end

.synchronize_create_default ⇒ Object

Returns the value of attribute synchronize_create_default.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def synchronize_create_default
  @synchronize_create_default
end

.synchronize_create_options ⇒ Object

Returns the value of attribute synchronize_create_options.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def synchronize_create_options
  @synchronize_create_options
end

.synchronize_create_secret ⇒ Object

Returns the value of attribute synchronize_create_secret.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def synchronize_create_secret
  @synchronize_create_secret
end

.synchronize_create_store ⇒ Object

Returns the value of attribute synchronize_create_store.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def synchronize_create_store
  @synchronize_create_store
end

.validate_query_keys ⇒ Object

Returns the value of attribute validate_query_keys.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def validate_query_keys
  @validate_query_keys
end

.warn_on_query_issues ⇒ Object

Returns the value of attribute warn_on_query_issues.



667
668
669
 
# File 'lib/parse/stack.rb', line 667

def warn_on_query_issues
  @warn_on_query_issues
end

Class Method Details

.auto_generate_models! ⇒ Array

Create all Parse::Object subclasses, including their properties and inferred associations by importing the schema for the remote collections in a Parse application. Uses the default configured client.

Returns:

  • (Array) —

    an array of created Parse::Object subclasses.

See Also:



16
17
18
19
20
 
# File 'lib/parse/model/core/builder.rb', line 16

def self.auto_generate_models!
  Parse.schemas.map do |schema|
    Parse::Model::Builder.build!(schema)
  end
end

.auto_upgrade! ⇒ Object

Perform a non-destructive upgrade of all your Parse schemas in the backend based on the property definitions of your local Object subclasses.



73
74
75
76
77
78
79
 
# File 'lib/parse/model/object.rb', line 73

def self.auto_upgrade!
  klassModels = Parse::Object.descendants
  klassModels.sort_by(&:parse_class).each do |klass|
    yield(klass) if block_given?
    klass.auto_upgrade!
  end
end

.batch(reqs = nil) ⇒ BatchOperation

Create a new batch operation.

Parameters:

Returns:



11
12
13
 
# File 'lib/parse/client/batch.rb', line 11

def self.batch(reqs = nil)
  BatchOperation.new(reqs)
end

.cache ⇒ Moneta::Transformer, Moneta::Expires

The shared cache for the default client connection. This is useful if you want to also utilize the same cache store for other purposes in your application. This should normally be a Moneta unified cache interface.

Returns:

  • (Moneta::Transformer, Moneta::Expires) —

    the cache instance

See Also:



221
222
223
 
# File 'lib/parse/client.rb', line 221

def self.cache
  @shared_cache ||= Parse::Client.client(:default).cache
end

.call_function(name, body = {}, **opts) ⇒ Object

Helper method to call cloud functions and get results.

Parameters:

  • name (String) —

    the name of the cloud code function to call.

  • body (Hash) (defaults to: {}) —

    the set of parameters to pass to the function.

  • opts (Hash) —

    additional options.

Options Hash (**opts):

  • :session_token (String) —

    The session token for authenticated requests.

  • :session (Symbol) —

    The client connection to use (alternative to :client).

  • :client (Symbol) —

    The client connection to use.

  • :raw (Boolean) —

    Whether to return the raw response object.

  • :master_key (Boolean) —

    Whether to use the master key for this request.

  • :context (Hash, nil) —

    An optional caller context forwarded as the X-Parse-Cloud-Context header. Parse Server maps it to req.info.context in the function handler and flows it through beforeSave/afterSave triggers.

Returns:

  • (Object) —

    the result data of the response. nil if there was an error.



1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
 
# File 'lib/parse/client.rb', line 1589

def self.call_function(name, body = {}, **opts)
  conn = opts[:session] || opts[:client] || :default

  # Extract request options for the API call
  request_opts = {}
  request_opts[:session_token] = opts[:session_token] if opts[:session_token]
  request_opts[:master_key] = opts[:master_key] if opts[:master_key]

  # Build call kwargs; only forward context: when explicitly supplied so
  # call sites that do not use context produce the same opts hash that
  # existing mock expectations match against.
  call_kwargs = { opts: request_opts }
  call_kwargs[:context] = opts[:context] unless opts[:context].nil?

  response = Parse::Client.client(conn).call_function(name, body, **call_kwargs)
  return response if opts[:raw].present?
  if response.error?
    Parse::Client._safe_warn("CloudCodeError", response, name: name)
    return nil
  end
  _extract_cloud_result(response)
end

.call_function!(name, body = {}, **opts) ⇒ Object

Same as call_function but raises Parse::Error::CloudCodeError when the cloud function returns an error instead of silently returning nil. HTTP-level errors (auth, timeouts, throttling, etc.) still raise their specific Error subclasses as the underlying client does.

Parameters:

  • opts (see Parse.call_function) —

    — :raw has no effect; this method always decodes the result. Use call_function with raw: true if you need the undecoded response.

  • name (String) —

    the name of the cloud code function to call.

  • body (Hash) (defaults to: {}) —

    the set of parameters to pass to the function.

Returns:

  • (Object) —

    the result data of the response.

Raises:



1623
1624
1625
1626
1627
 
# File 'lib/parse/client.rb', line 1623

def self.call_function!(name, body = {}, **opts)
  response = call_function(name, body, **opts.merge(raw: true))
  raise Parse::Error::CloudCodeError.new(name, response) if response.error?
  _extract_cloud_result(response)
end

.call_function_with_session(name, body = {}, session_token, **opts) ⇒ Object

Helper method to call cloud functions with a session token. This is a convenience method that ensures proper session token handling.

Parameters:

  • name (String) —

    the name of the cloud code function to call.

  • body (Hash) (defaults to: {}) —

    the set of parameters to pass to the function.

  • session_token (String) —

    the session token for authenticated requests.

  • opts (Hash) —

    additional options (same as call_function).

Returns:

  • (Object) —

    the result data of the response. nil if there was an error.



1636
1637
1638
1639
 
# File 'lib/parse/client.rb', line 1636

def self.call_function_with_session(name, body = {}, session_token, **opts)
  opts[:session_token] = session_token
  call_function(name, body, **opts)
end

.call_function_with_session!(name, body = {}, session_token, **opts) ⇒ Object

Same as call_function_with_session but raises Parse::Error::CloudCodeError when the cloud function returns an error instead of silently returning nil.

Parameters:

  • name (String) —

    the name of the cloud code function to call.

  • body (Hash) (defaults to: {}) —

    the set of parameters to pass to the function.

  • session_token (String) —

    the session token for authenticated requests.

  • opts (Hash) —

    additional options (same as call_function).

Returns:

  • (Object) —

    the result data of the response.

Raises:



1650
1651
1652
1653
 
# File 'lib/parse/client.rb', line 1650

def self.call_function_with_session!(name, body = {}, session_token, **opts)
  opts[:session_token] = session_token
  call_function!(name, body, **opts)
end

.classify(className) ⇒ Class

Find a corresponding Parse::Object subclass for this string or symbol

Parameters:

  • className (String) —

    The name of the Parse class as string (ex. "_User")

Returns:

  • (Class) —

    The proper subclass matching the className.



15
16
17
 
# File 'lib/parse/model/model.rb', line 15

def self.classify(className)
  Parse::Model.find_class className.to_parse_class
end

.clear_n_plus_one_callbacks! ⇒ Object

Clear N+1 detection callbacks



392
393
394
 
# File 'lib/parse/query/n_plus_one_detector.rb', line 392

def clear_n_plus_one_callbacks!
  NPlusOneDetector.clear_callbacks!
end

.clear_profiles! ⇒ Object

Clear all stored profiles



163
164
165
 
# File 'lib/parse/client/profiling.rb', line 163

def clear_profiles!
  Middleware::Profiling.clear_profiles!
end

.clear_profiling_callbacks! ⇒ Object

Clear all profiling callbacks



180
181
182
 
# File 'lib/parse/client/profiling.rb', line 180

def clear_profiling_callbacks!
  Middleware::Profiling.clear_callbacks!
end

.client(conn = :default) ⇒ Parse::Client

Helper method to get the default Parse client.

Parameters:

  • conn (Symbol) (defaults to: :default) —

    the name of the client connection to use. Defaults to :default

Returns:



177
178
179
 
# File 'lib/parse/client.rb', line 177

def self.client(conn = :default)
  Parse::Client.client(conn)
end

.client_mode ⇒ Object 



373
374
375
 
# File 'lib/parse/stack.rb', line 373

def self.client_mode
  @client_mode == true
end

.client_mode=(value) ⇒ Object 



376
377
378
 
# File 'lib/parse/stack.rb', line 376

def self.client_mode=(value)
  @client_mode = (value == true)
end

.client_mode? ⇒ Boolean

Returns:

  • (Boolean) 


379
380
381
 
# File 'lib/parse/stack.rb', line 379

def self.client_mode?
  client_mode
end

.config(conn = :default) ⇒ Hash

Retrieve the App specific Parse configuration parameters. The configuration for a connection is cached after the first request. Use the bang version to force update from the Parse backend.

Examples:

val = Parse.config["myKey"]
val = Parse.config["myKey"] # cached

Parameters:

  • conn (Symbol) (defaults to: :default) —

    the name of the client connection to use.

Returns:

  • (Hash) —

    the Parse config hash for the session.

See Also:



105
106
107
 
# File 'lib/parse/client.rb', line 105

def self.config(conn = :default)
  Parse::Client.client(conn).config
end

.config!(conn = :default) ⇒ Hash

Force fetch updated Parse configuration

Parameters:

  • conn (Symbol) (defaults to: :default) —

    the name of the client connection to use.

Returns:

  • (Hash) —

    the Parse configuration



146
147
148
 
# File 'lib/parse/client.rb', line 146

def self.config!(conn = :default)
  Parse::Client.client(conn).config!
end

.config_entries(conn = :default, master: false) ⇒ Hash{String=>Hash}

Return every config entry zipped with its masterKeyOnly trait.

Examples:

Parse.config_entries
# => { "fieldA" => { value: "x", master_key_only: false } }
Parse.config_entries(master: true)
# => { "fieldA" => { value: "x", master_key_only: false },
#      "fieldB" => { value: 42,  master_key_only: true  } }

Parameters:

  • conn (Symbol) (defaults to: :default) —

    the name of the client connection to use.

  • master (Boolean) (defaults to: false) —

    when true, include master-key-only entries.

Returns:

  • (Hash{String=>Hash}) —

    map of config key to {value:, master_key_only:}.



160
161
162
 
# File 'lib/parse/client.rb', line 160

def self.config_entries(conn = :default, master: false)
  Parse::Client.client(conn).config_entries(master: master)
end

.configure_logging {|Middleware::Logging| ... } ⇒ Object

Configure Parse logging with a block

Examples:

Parse.configure_logging do |config|
  config.enabled = true
  config.log_level = :debug
  config.logger = Rails.logger
end

Yields:



301
302
303
 
# File 'lib/parse/client/logging.rb', line 301

def configure_logging
  yield Middleware::Logging if block_given?
end

.configure_mcp_remote_api(provider:, api_key:, model: nil, base_url: nil) ⇒ Hash

Configure MCP remote API connection

Parameters:

  • provider (Symbol) —

    the API provider (:openai, :claude, :custom)

  • api_key (String) —

    the API key

  • model (String) (defaults to: nil) —

    the model to use (e.g., 'gpt-4', 'claude-3-opus')

  • base_url (String, nil) (defaults to: nil) —

    optional custom base URL

Returns:

  • (Hash) —

    the configuration hash



905
906
907
908
909
910
911
912
 
# File 'lib/parse/stack.rb', line 905

def configure_mcp_remote_api(provider:, api_key:, model: nil, base_url: nil)
  @mcp_remote_api = {
    provider: provider.to_sym,
    api_key: api_key,
    model: model,
    base_url: base_url,
  }
end

.configure_n_plus_one {|NPlusOneDetector| ... } ⇒ Object

Configure N+1 detection thresholds.

Examples:

Configure thresholds

Parse.configure_n_plus_one do |config|
  config.detection_window = 5.0   # 5 seconds
  config.fetch_threshold = 5      # 5 fetches to trigger
  config.cleanup_interval = 120.0 # cleanup every 2 minutes
end

Yields:



417
418
419
 
# File 'lib/parse/query/n_plus_one_detector.rb', line 417

def configure_n_plus_one
  yield NPlusOneDetector if block_given?
end

.connected?(conn = :default, endpoint = nil) ⇒ Boolean

Check that the Parse Server is reachable and responding. By default this probes the credential-less health endpoint, so it returns true whenever the server is up (it does NOT, by itself, validate the application_id or REST key — see Parse::Client#connected? for why a data-class probe is unreliable on a hardened server). Pass an endpoint (e.g. "classes/_User") to additionally exercise the auth stack against a class you know the configured key can read; a bad key then surfaces as an Parse::Error::AuthenticationError at the instance level, which the instance method converts to false. Any other failure is caught by this module-boundary rescue and converted to false.

Parameters:

  • conn (Symbol) (defaults to: :default) —

    the named client connection to probe. Defaults to :default.

  • endpoint (String, nil) (defaults to: nil) —

    optional path to probe instead of the health endpoint, to validate credentials against a readable class.

Returns:

  • (Boolean) —

    true if the server is reachable (and, when an endpoint is given, the credentials are accepted).



209
210
211
212
213
 
# File 'lib/parse/client.rb', line 209

def self.connected?(conn = :default, endpoint = nil)
  client(conn).connected?(endpoint)
rescue StandardError
  false
end

.current_cache_tenant ⇒ String?

The ambient cache-tenant scope set by with_cache_tenant for the current fiber, or nil when not inside such a block.

Returns:



241
242
243
 
# File 'lib/parse/stack.rb', line 241

def self.current_cache_tenant
  Fiber[CACHE_TENANT_STATE_KEY]
end

.current_session_token ⇒ String?

The ambient session token set by with_session for the current fiber, or nil when not inside such a block.

Returns:



166
167
168
 
# File 'lib/parse/stack.rb', line 166

def self.current_session_token
  Fiber[SESSION_TOKEN_STATE_KEY]
end

.current_user ⇒ Parse::User?

The User cached alongside the ambient session set by login, or nil when no imperative login is active. Block-scoped {Parse.with_session} does NOT populate this — only login does.

Returns:



249
250
251
 
# File 'lib/parse/stack.rb', line 249

def self.current_user
  Fiber[CURRENT_USER_STATE_KEY]
end

.live_query_enabled? ⇒ Boolean

Check if LiveQuery feature is enabled

Returns:

  • (Boolean) 


743
744
745
 
# File 'lib/parse/stack.rb', line 743

def live_query_enabled?
  @live_query_enabled == true
end

.log_level ⇒ Symbol

Returns the current log level.

Returns:

  • (Symbol) —

    the current log level



266
267
268
 
# File 'lib/parse/client/logging.rb', line 266

def log_level
  Middleware::Logging.current_log_level
end

.log_level=(value) ⇒ Object

Set the log level for Parse requests

Examples:

Set debug level

Parse.log_level = :debug

Parameters:

  • value (Symbol) —

    one of :info, :debug, :warn



258
259
260
261
262
263
 
# File 'lib/parse/client/logging.rb', line 258

def log_level=(value)
  unless [:info, :debug, :warn].include?(value)
    raise ArgumentError, "Invalid log level: #{value}. Use :info, :debug, or :warn"
  end
  Middleware::Logging.log_level = value
end

.log_max_body_length ⇒ Integer

Returns the maximum body length.

Returns:

  • (Integer) —

    the maximum body length



290
291
292
 
# File 'lib/parse/client/logging.rb', line 290

def log_max_body_length
  Middleware::Logging.current_max_body_length
end

.log_max_body_length=(value) ⇒ Object

Set the maximum body length to log before truncation

Parameters:

  • value (Integer) 


285
286
287
 
# File 'lib/parse/client/logging.rb', line 285

def log_max_body_length=(value)
  Middleware::Logging.max_body_length = value.to_i
end

.logger ⇒ Logger

Returns the current logger.

Returns:

  • (Logger) —

    the current logger



279
280
281
 
# File 'lib/parse/client/logging.rb', line 279

def logger
  Middleware::Logging.current_logger
end

.logger=(value) ⇒ Object

Set a custom logger for Parse requests

Examples:

Use Rails logger

Parse.logger = Rails.logger

Parameters:

  • value (Logger) 


274
275
276
 
# File 'lib/parse/client/logging.rb', line 274

def logger=(value)
  Middleware::Logging.logger = value
end

.logging_enabled ⇒ Boolean

Returns whether logging is enabled.

Returns:

  • (Boolean) —

    whether logging is enabled



250
251
252
 
# File 'lib/parse/client/logging.rb', line 250

def logging_enabled
  Middleware::Logging.enabled
end

.logging_enabled=(value) ⇒ Object

Enable or disable request/response logging

Examples:

Enable logging

Parse.logging_enabled = true

Parameters:

  • value (Boolean) 


245
246
247
 
# File 'lib/parse/client/logging.rb', line 245

def logging_enabled=(value)
  Middleware::Logging.enabled = value
end

.login(username, password, mfa_token: nil) ⇒ Parse::User

Imperative login for REPL / Rake-console use: logs in once, stashes the resulting session token as the ambient for the current fiber, and returns the User. Every subsequent Parse call in the session (the IRB main fiber) is then auth-scoped to that user without the caller threading session_token: or wrapping each statement in with_session.

Intended for interactive use. For scoped work in production code, prefer with_session — it auto-restores prior state on exit, even if the block raises.

Examples:

IRB / rails console

Parse.("alice", "hunter2")
Post.all                # as alice
p = Post.find(id); p.update!(title: "edited")  # as alice
Parse.logout            # clears ambient and revokes the session

with MFA

begin
  Parse.("alice", "hunter2")
rescue Parse::MFA::RequiredError
  code = $stdin.gets.chomp
  Parse.("alice", "hunter2", mfa_token: code)
end

Parameters:

  • username (String) —

    the user's username.

  • password (String) —

    the user's password.

  • mfa_token (String, nil) (defaults to: nil) —

    one-time MFA code (TOTP or recovery code). When given, the credentials are submitted via the MFA endpoint. When the server requires MFA and none is supplied, Parse::MFA::RequiredError is raised so the caller can prompt for the code and retry.

Returns:

Raises:



295
296
297
298
299
300
301
302
303
304
305
306
307
308
 
# File 'lib/parse/stack.rb', line 295

def self.(username, password, mfa_token: nil)
  user = if mfa_token
      Parse::User.(username, password, mfa_token)
    else
      Parse::User.login!(username, password)
    end
  unless user
    raise Parse::Error::AuthenticationError,
          "Parse.login: credentials rejected for #{username.inspect} (server returned no session)."
  end
  Fiber[SESSION_TOKEN_STATE_KEY] = user.session_token
  Fiber[CURRENT_USER_STATE_KEY]  = user
  user
end

.logout(revoke: true) ⇒ Boolean

Imperative logout: clears the ambient session token and cached current user for the current fiber and, by default, revokes the token server-side via POST /parse/logout. Pair with login.

If you set the ambient via session_token= (no server-side session to revoke), pass revoke: false to skip the network call.

Parameters:

  • revoke (Boolean) (defaults to: true) —

    when true (default), call the server-side /logout endpoint to invalidate the token. When false, only clears local fiber state.

Returns:

  • (Boolean) —

    true if the local state was cleared (always); the server-side revoke result is intentionally not surfaced — logout is fire-and-forget in console use.



323
324
325
326
327
328
329
330
331
332
333
334
335
336
 
# File 'lib/parse/stack.rb', line 323

def self.logout(revoke: true)
  token = Fiber[SESSION_TOKEN_STATE_KEY]
  Fiber[SESSION_TOKEN_STATE_KEY] = nil
  Fiber[CURRENT_USER_STATE_KEY]  = nil
  if revoke && token.is_a?(String) && !token.empty?
    begin
      Parse::Client.client.logout(token)
    rescue StandardError
      # Best-effort: a failed revoke shouldn't make `logout` raise in
      # a REPL. The local clear already happened.
    end
  end
  true
end

.master_key_disabled? ⇒ Boolean

Returns true if the current fiber is inside a without_master_key block. Consulted by the authentication middleware in addition to the per-request disable header.

Returns:

  • (Boolean) —

    true if the current fiber is inside a without_master_key block. Consulted by the authentication middleware in addition to the per-request disable header.



98
99
100
 
# File 'lib/parse/stack.rb', line 98

def self.master_key_disabled?
  Fiber[MASTER_KEY_STATE_KEY] == :disabled
end

.master_key_only(conn = :default) ⇒ Hash{String=>Boolean}

Retrieve the masterKeyOnly flag map for the application configuration.

Examples:

Parse.master_key_only["secretKey"] # => true

Parameters:

  • conn (Symbol) (defaults to: :default) —

    the name of the client connection to use.

Returns:

  • (Hash{String=>Boolean}) —

    map of config keys to masterKeyOnly flags, or an empty hash if the server did not return one.



170
171
172
 
# File 'lib/parse/client.rb', line 170

def self.master_key_only(conn = :default)
  Parse::Client.client(conn).master_key_only
end

.mcp_remote_api_configured? ⇒ Boolean

Check if MCP remote API is configured

Returns:

  • (Boolean) 


916
917
918
 
# File 'lib/parse/stack.rb', line 916

def mcp_remote_api_configured?
  @mcp_remote_api.is_a?(Hash) && @mcp_remote_api[:api_key].present?
end

.mcp_server_enabled? ⇒ Boolean

Check if MCP server feature is enabled Requires PARSE_MCP_ENABLED=true in environment AND Parse.mcp_server_enabled = true

Returns:

  • (Boolean) 


894
895
896
897
 
# File 'lib/parse/stack.rb', line 894

def mcp_server_enabled?
  return false unless ENV["PARSE_MCP_ENABLED"] == "true"
  @mcp_server_enabled == true
end

.n_plus_one_detection_window ⇒ Float

Get the N+1 detection window

Returns:

  • (Float) 


429
430
431
 
# File 'lib/parse/query/n_plus_one_detector.rb', line 429

def n_plus_one_detection_window
  NPlusOneDetector.detection_window
end

.n_plus_one_detection_window=(value) ⇒ Object

Set the N+1 detection window (time in seconds to track related fetches)

Parameters:

  • value (Float) 


423
424
425
 
# File 'lib/parse/query/n_plus_one_detector.rb', line 423

def n_plus_one_detection_window=(value)
  NPlusOneDetector.detection_window = value
end

.n_plus_one_fetch_threshold ⇒ Integer

Get the N+1 fetch threshold

Returns:

  • (Integer) 


441
442
443
 
# File 'lib/parse/query/n_plus_one_detector.rb', line 441

def n_plus_one_fetch_threshold
  NPlusOneDetector.fetch_threshold
end

.n_plus_one_fetch_threshold=(value) ⇒ Object

Set the N+1 fetch threshold (minimum fetches to trigger warning)

Parameters:

  • value (Integer) 


435
436
437
 
# File 'lib/parse/query/n_plus_one_detector.rb', line 435

def n_plus_one_fetch_threshold=(value)
  NPlusOneDetector.fetch_threshold = value
end

.n_plus_one_mode ⇒ Symbol

Get the current N+1 detection mode.

Returns:

  • (Symbol) —

    :warn, :raise, or :ignore



352
353
354
 
# File 'lib/parse/query/n_plus_one_detector.rb', line 352

def n_plus_one_mode
  NPlusOneDetector.mode
end

.n_plus_one_mode=(value) ⇒ Object

Set the N+1 detection mode.

Examples:

Different modes

Parse.n_plus_one_mode = :warn   # Log warnings (default when enabled)
Parse.n_plus_one_mode = :raise  # Raise NPlusOneQueryError (for CI/tests)
Parse.n_plus_one_mode = :ignore # Disable detection

Parameters:

  • value (Symbol) —

    :warn, :raise, or :ignore



346
347
348
 
# File 'lib/parse/query/n_plus_one_detector.rb', line 346

def n_plus_one_mode=(value)
  NPlusOneDetector.mode = value
end

.n_plus_one_summary ⇒ Hash

Get N+1 detection summary

Returns:



403
404
405
 
# File 'lib/parse/query/n_plus_one_detector.rb', line 403

def n_plus_one_summary
  NPlusOneDetector.summary
end

.on_n_plus_one {|source_class, association, target_class, count, location| ... } ⇒ Object

Register a callback for N+1 detection events. Useful for custom logging or metrics collection. Callbacks are called regardless of mode (even in :ignore mode).

Examples:

Track N+1 patterns

Parse.on_n_plus_one do |source, assoc, target, count, location|
  MyMetrics.increment("n_plus_one.#{source}.#{assoc}")
end

Yields:

  • (source_class, association, target_class, count, location) 


387
388
389
 
# File 'lib/parse/query/n_plus_one_detector.rb', line 387

def on_n_plus_one(&block)
  NPlusOneDetector.on_n_plus_one(&block)
end

.on_request_complete {|Hash| ... } ⇒ Object

Register a callback for request completion

Yields:

  • (Hash) —

    profile data



175
176
177
 
# File 'lib/parse/client/profiling.rb', line 175

def on_request_complete(&block)
  Middleware::Profiling.on_request_complete(&block)
end

.pluralized_aliases? ⇒ Boolean

Whether automatic pluralized class-name aliases are enabled. Defaults to true; opt out with Parse.pluralized_aliases = false or PARSE_PLURALIZED_ALIASES=false. See pluralized_aliases.

Returns:

  • (Boolean) 


761
762
763
 
# File 'lib/parse/stack.rb', line 761

def pluralized_aliases?
  @pluralized_aliases != false
end

.profiling_enabled ⇒ Boolean

Returns whether profiling is enabled.

Returns:

  • (Boolean) —

    whether profiling is enabled



152
153
154
 
# File 'lib/parse/client/profiling.rb', line 152

def profiling_enabled
  Middleware::Profiling.enabled
end

.profiling_enabled=(value) ⇒ Object

Enable or disable request profiling

Parameters:

  • value (Boolean) 


147
148
149
 
# File 'lib/parse/client/profiling.rb', line 147

def profiling_enabled=(value)
  Middleware::Profiling.enabled = value
end

.profiling_statistics ⇒ Hash

Get profiling statistics

Returns:



169
170
171
 
# File 'lib/parse/client/profiling.rb', line 169

def profiling_statistics
  Middleware::Profiling.statistics
end

.reachable?(conn = :default) ⇒ Boolean

Check that the Parse Server is reachable via the health endpoint. This is a no-credentials liveness probe — it does NOT validate the application_id or REST key. A server with a mistyped app_id still returns true here; use connected? when you also need to validate credentials.

Parameters:

  • conn (Symbol) (defaults to: :default) —

    the named client connection to probe. Defaults to :default.

Returns:

  • (Boolean) —

    true if the server responded with status "ok", false if the server is unreachable or returned an unexpected response.



188
189
190
191
192
 
# File 'lib/parse/client.rb', line 188

def self.reachable?(conn = :default)
  client(conn).reachable?
rescue StandardError
  false
end

.recent_profiles ⇒ Array<Hash>

Get recent profile data

Returns:



158
159
160
 
# File 'lib/parse/client/profiling.rb', line 158

def recent_profiles
  Middleware::Profiling.profiles
end

.registered_classes ⇒ Array

Returns an array of registered Parse::Object subclasses.

Returns:

  • (Array) —

    an array of registered Parse::Object subclasses.



54
55
56
 
# File 'lib/parse/model/object.rb', line 54

def self.registered_classes
  Parse::Object.descendants.map(&:parse_class).uniq
end

.reset_n_plus_one_tracking! ⇒ Object

Reset N+1 detection tracking



397
398
399
 
# File 'lib/parse/query/n_plus_one_detector.rb', line 397

def reset_n_plus_one_tracking!
  NPlusOneDetector.reset!
end

.schema(className) ⇒ Hash

Fetch the schema for a specific collection name.

Parameters:

  • className (String) —

    the name collection

Returns:

  • (Hash) —

    the schema document of this collection.

See Also:

  • Parse::Core::ClassBuilder.build!


67
68
69
 
# File 'lib/parse/model/object.rb', line 67

def self.schema(className)
  client.schema(className).result
end

.schemas ⇒ Array<Hash>

Returns the list of all schemas for this application.

Returns:

  • (Array<Hash>) —

    the list of all schemas for this application.



59
60
61
 
# File 'lib/parse/model/object.rb', line 59

def self.schemas
  client.schemas.results
end

.server_features ⇒ Hash

The coarse features block advertised by GET /serverInfo, delegated to the default client. @see Parse::API::Server#server_features

Returns:

  • (Hash) —

    the advertised features block, or {} if unavailable.



981
982
983
 
# File 'lib/parse/stack.rb', line 981

def server_features
  Parse.client.server_features
end

.server_supports?(feature) ⇒ Boolean

Capability probe against the connected Parse Server, delegated to the default client. Builds on the memoized serverInfo fetch — see Parse::API::Server#server_supports? for the capability table and the fail-open-to-modern semantics.

Parameters:

  • feature (Symbol) —

    a capability key.

Returns:

  • (Boolean) —

    whether the connected server supports the feature.



974
975
976
 
# File 'lib/parse/stack.rb', line 974

def server_supports?(feature)
  Parse.client.server_supports?(feature)
end

.session_token=(token) ⇒ String?

Imperative ambient-token setter, for cases where you already have a session token (e.g. read from a fixture, a test setup, a saved credential) and want to scope subsequent calls without going through the login endpoint. Set to nil to clear the ambient (does not revoke server-side; use logout for that).

Parameters:

Returns:

  • (String, nil) —

    the resolved token now in effect.



345
346
347
348
349
350
351
 
# File 'lib/parse/stack.rb', line 345

def self.session_token=(token)
  resolved = token.respond_to?(:session_token) ? token.session_token : token
  resolved = resolved.to_s if resolved
  Fiber[SESSION_TOKEN_STATE_KEY] = (resolved && !resolved.empty?) ? resolved : nil
  Fiber[CURRENT_USER_STATE_KEY]  = nil
  Fiber[SESSION_TOKEN_STATE_KEY]
end

.set_config(field, value, conn = :default, master_key_only: nil) ⇒ Hash

Set a parameter in the Parse configuration for an application.

Examples:

# update a config with Parse
Parse.set_config "myKey", "someValue"
# mark a single key as master-key-only
Parse.set_config "myKey", "someValue", master_key_only: true

Parameters:

  • field (String) —

    the name configuration variable.

  • value (Object) —

    the value configuration variable. Only Parse types are supported.

  • conn (Symbol) (defaults to: :default) —

    the name of the client connection to use.

  • master_key_only (Boolean, nil) (defaults to: nil) —

    when not nil, sets the masterKeyOnly flag for field to the given boolean value in the same request.

Returns:

  • (Hash) —

    the Parse config hash for the session.



121
122
123
124
 
# File 'lib/parse/client.rb', line 121

def self.set_config(field, value, conn = :default, master_key_only: nil)
  opts = master_key_only.nil? ? {} : { master_key_only: { field.to_s => !!master_key_only } }
  Parse::Client.client(conn).update_config({ field => value }, **opts)
end

.setup(opts = {}) { ... } ⇒ Client

Helper method that users should call to setup the client stack. A block can be passed in order to do additional client configuration. To connect to a Parse server, you will need a minimum of an application_id, an api_key and a server_url. To connect to the server endpoint, you use the setup method below.

Examples:

Parse.setup app_id: "YOUR_APP_ID",
            api_key: "YOUR_REST_API_KEY",
            master_key: "YOUR_MASTER_KEY", # optional
            server_url: 'https://localhost:1337/parse' #default

Parameters:

  • opts (Hash) (defaults to: {}) —

    a set of connection options to configure the client.

Options Hash (opts):

  • :server_url (String) —

    The server url of your Parse Server if you are not using the hosted Parse service. By default it will use ENV if available, otherwise fallback to Parse::Protocol::SERVER_URL.

  • :app_id (String) —

    The Parse application id. Defaults to ENV.

  • :api_key (String) —

    Your Parse REST API Key. Defaults to ENV.

  • :master_key (String) —

    The Parse application master key (optional). If this key is set, it will be sent on every request sent by the client and your models. Defaults to ENV.

  • :session_token (String) —

    An optional session token bound to this client. When set, every request that does not pass an explicit session_token: / use_master_key: true and is not inside a Parse.with_session block sends this token (and suppresses the master key), so the client transparently acts as that user. Precedence is explicit per-call > Parse.with_session ambient > this bound token. Typically paired with master_key: nil to build a user-scoped client (see Parse::Webhooks::Payload#user_client).

  • :logging (Boolean, Symbol) —

    Controls request/response logging.

    • true - Enable logging at :info level
    • :debug - Enable verbose logging with headers and body content
    • :warn - Only log errors and warnings
    • false or nil - Disable logging (default) This configures both the new Parse::Middleware::Logging middleware and the legacy Parse::Middleware::BodyBuilder logging.
  • :logger (Logger) —

    A custom logger instance for request/response logging. Defaults to Logger.new(STDOUT) if not specified.

  • :adapter (Object) —

    The connection adapter. By default it uses :net_http_persistent for connection pooling. Set connection_pooling: false to use the standard Faraday.default_adapter (Net/HTTP) instead.

  • :connection_pooling (Boolean, Hash) —

    Controls HTTP connection pooling. Defaults to true, using the :net_http_persistent adapter for improved performance through connection reuse. Set to false to disable pooling and create a new connection for each request. This option is ignored if :adapter is explicitly specified. Pass a Hash to enable pooling with custom configuration:

    • :pool_size [Integer] - Number of connections per thread (default: 1)
    • :idle_timeout [Integer] - Seconds before closing idle connections (default: 5)
    • :keep_alive [Integer] - HTTP Keep-Alive timeout in seconds @example Custom connection pooling Parse.setup( connection_pooling: { pool_size: 5, idle_timeout: 60, keep_alive: 60 } )
  • :cache (Moneta::Transformer, Moneta::Expires, Parse::Cache::Redis, String) —

    A caching adapter of type Moneta::Transformer or Moneta::Expires that will be used by the caching middleware Parse::Middleware::Caching. You can also pass a redis:// URL string (an internal Moneta-Redis store will be built for you) or a Parse::Cache::Redis wrapper, which adds a connection pool and automatic namespace forwarding. Caching queries and object fetches can help improve the performance of your application, even if it is for a few seconds. Only successful GET object fetches and non-empty result queries will be cached by default. You may set the default expiration time with the expires option. At any point in time you may clear the cache by calling the Parse::Client#clear_cache! method on the client connection. See Moneta.

  • :expires (Integer) —

    Sets the default cache expiration time (in seconds) for successful non-empty GET requests when using the caching middleware. The default value is 3 seconds. If :expires is set to 0, caching will be disabled. You can always clear the current state of the cache using the clear_cache! method on your Parse::Client instance.

  • :cache_namespace (String) —

    Optional prefix applied to every cache key. Useful when two Parse apps share one Redis instance and would otherwise collide on identical paths (e.g. mk:/classes/Song/abc). Keys become <namespace>:<existing-prefix>:<url>, so a SCAN <namespace>:* evicts a whole app cleanly. Defaults to no namespace for backward compatibility — explicit only, never auto-derived from app_id.

  • :faraday (Hash) —

    You may pass a hash of options that will be passed to the Faraday constructor.

  • :live_query_url (String) —

    The WebSocket URL for Parse LiveQuery server (e.g., "wss://your-parse-server.com"). If not specified, falls back to ENV. LiveQuery enables real-time subscriptions to changes in Parse objects. @example Enable LiveQuery Parse.setup( server_url: "https://your-server.com/parse&quot;, application_id: "YOUR_APP_ID", api_key: "YOUR_API_KEY", live_query_url: "wss://your-server.com" )

  • :live_query (Hash) —

    Advanced LiveQuery configuration options. Pass a hash with custom settings for the LiveQuery client.

    • :url [String] - WebSocket URL (alternative to :live_query_url)
    • :auto_reconnect [Boolean] - Auto-reconnect on disconnect (default: true)

Yields:

  • the block for additional configuration with Faraday middleware.

Returns:

  • (Client) —

    a new instance of Client

See Also:



1435
1436
1437
1438
1439
1440
1441
1442
 
# File 'lib/parse/client.rb', line 1435

def self.setup(opts = {}, &block)
  # 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

.slow_query_threshold_ms ⇒ Integer?

Current slow-query threshold in milliseconds, or nil when unconfigured. Resolves the in-process accessor first; falls back to the PARSE_SLOW_QUERY_THRESHOLD_MS ENV. Non-positive values are treated as nil (disabled).

Returns:

  • (Integer, nil) 


688
689
690
691
692
 
# File 'lib/parse/stack.rb', line 688

def slow_query_threshold_ms
  value = @slow_query_threshold_ms
  value = ENV["PARSE_SLOW_QUERY_THRESHOLD_MS"].to_i if value.nil? && ENV["PARSE_SLOW_QUERY_THRESHOLD_MS"]
  value && value > 0 ? value : nil
end

.slow_query_threshold_ms=(value) ⇒ Object

Set the slow-query threshold in milliseconds. When set to a positive integer, lazily attaches the bundled subscriber to parse.mongodb.aggregate and parse.mongodb.find so events exceeding the threshold log a warning to logger. Set to nil (or any non-positive value) to disable; the subscriber stays attached but becomes a cheap pass-through.

Parameters:

  • value (Integer, nil) 


701
702
703
704
705
 
# File 'lib/parse/stack.rb', line 701

def slow_query_threshold_ms=(value)
  @slow_query_threshold_ms = value
  _attach_slow_query_subscriber!
  value
end

.strict_pointer_shapes? ⇒ Boolean

Check if strict pointer-shape validation is enabled. When true, impossible shapes (e.g. bare string $in element against a pointer column whose target class is unknown) raise Parse::Query::PointerShapeError instead of silently returning zero rows. See strict_pointer_shapes=.

Returns:

  • (Boolean) 


753
754
755
 
# File 'lib/parse/stack.rb', line 753

def strict_pointer_shapes?
  @strict_pointer_shapes == true
end

.suppress_server_version_warning? ⇒ Boolean

Check whether the Parse Server version deprecation warning is silenced. Returns true if either the in-process accessor or the PARSE_SUPPRESS_SERVER_VERSION_WARNING ENV is set.

Returns:

  • (Boolean) 


679
680
681
 
# File 'lib/parse/stack.rb', line 679

def suppress_server_version_warning?
  @suppress_server_version_warning == true || ENV["PARSE_SUPPRESS_SERVER_VERSION_WARNING"] == "true"
end

.track_event(name, dimensions: {}, **opts) ⇒ Parse::Response

Send an analytics event to Parse Server's REST /events/<name> endpoint. Thin shortcut around Parse::API::Analytics#send_analytics so callers don't have to reach into Parse.client directly.

Dimensions MUST be passed via the dimensions: keyword. Loose symbol-keyed arguments at the call site would otherwise be absorbed by **opts under Ruby 3's strict keyword separation, and the dimensions would never reach Parse Server — the POST would land with an empty body. Forwarded **opts is reserved for request-layer kwargs (session_token:, use_master_key:, etc.).

Parse Server's default analytics adapter is a no-op — events POSTed to /events are accepted but neither persisted nor queryable through the SDK. Operators who configure a custom analyticsAdapter decide what (if anything) to do with the event and whether to cap dimension count. The legacy parse.com eight-dimension cap does NOT apply to Parse Server out of the box. If you need to read events back, persist them to a regular Parse::Object subclass.

The underlying request is a blocking HTTP POST — wrap in a thread or background job if you don't want it on the request path.

Examples:

Parse.track_event("post_viewed", dimensions: { source: "feed", workspace: "w1" })
Parse.track_event("AppOpened")
Parse.track_event("error", dimensions: { code: "E_RATE_LIMIT" })

Parameters:

  • name (String, Symbol) —

    event name (e.g. "post_viewed", "AppOpened"). Restricted to word characters, hyphens, and dots so the value cannot escape the /events/ path segment.

  • dimensions (Hash) (defaults to: {}) —

    dimension pairs. Values must be JSON-serializable.

  • opts (Hash) —

    forwarded to Parse::Client#request.

Returns:

Raises:

  • (ArgumentError) —

    when name is empty or contains characters outside [\w\-\.].



958
959
960
961
962
963
964
965
966
 
# File 'lib/parse/stack.rb', line 958

def track_event(name, dimensions: {}, **opts)
  event_name = name.to_s
  unless event_name.match?(/\A[\w\-\.]+\z/)
    raise ArgumentError,
          "Parse.track_event: event name must contain only word characters, " \
          "hyphens, or dots (got #{name.inspect})"
  end
  Parse.client.send_analytics(event_name, dimensions, **opts)
end

.trigger_job(name, body = {}, **opts) ⇒ Object

Helper method to trigger cloud jobs and get results.

Parameters:

  • name (String) —

    the name of the cloud code job to trigger.

  • body (Hash) (defaults to: {}) —

    the set of parameters to pass to the job.



1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
 
# File 'lib/parse/client.rb', line 1518

def self.trigger_job(name, body = {}, **opts)
  conn = opts[:session] || opts[:client] || :default

  # Extract request options for the API call
  request_opts = {}
  request_opts[:session_token] = opts[:session_token] if opts[:session_token]
  request_opts[:master_key] = opts[:master_key] if opts[:master_key]

  response = Parse::Client.client(conn).trigger_job(name, body, opts: request_opts)
  return response if opts[:raw].present?
  if response.error?
    Parse::Client._safe_warn("CloudCodeError", response, name: name)
    return nil
  end
  _extract_cloud_result(response)
end

.trigger_job!(name, body = {}, **opts) ⇒ Object

Same as trigger_job but raises Parse::Error::CloudCodeError when the job returns an error instead of silently returning nil. HTTP-level errors (auth, timeouts, throttling, etc.) still raise their specific Error subclasses as the underlying client does.

Parameters:

  • opts (see Parse.trigger_job) —

    — :raw is ignored.

  • name (String) —

    the name of the cloud code job to trigger.

  • body (Hash) (defaults to: {}) —

    the set of parameters to pass to the job.

Returns:

  • (Object) —

    the result data of the response.

Raises:



1544
1545
1546
1547
1548
 
# File 'lib/parse/client.rb', line 1544

def self.trigger_job!(name, body = {}, **opts)
  response = trigger_job(name, body, **opts.merge(raw: true))
  raise Parse::Error::CloudCodeError.new(name, response) if response.error?
  _extract_cloud_result(response)
end

.trigger_job_with_session(name, body = {}, session_token, **opts) ⇒ Object

Helper method to trigger cloud jobs with a session token. This is a convenience method that ensures proper session token handling.

Parameters:

  • name (String) —

    the name of the cloud code job to trigger.

  • body (Hash) (defaults to: {}) —

    the set of parameters to pass to the job.

  • session_token (String) —

    the session token for authenticated requests.

  • opts (Hash) —

    additional options (same as trigger_job).

Returns:

  • (Object) —

    the result data of the response. nil if there was an error.



1557
1558
1559
1560
 
# File 'lib/parse/client.rb', line 1557

def self.trigger_job_with_session(name, body = {}, session_token, **opts)
  opts[:session_token] = session_token
  trigger_job(name, body, **opts)
end

.trigger_job_with_session!(name, body = {}, session_token, **opts) ⇒ Object

Same as trigger_job_with_session but raises Parse::Error::CloudCodeError when the job returns an error instead of silently returning nil.

Parameters:

  • name (String) —

    the name of the cloud code job to trigger.

  • body (Hash) (defaults to: {}) —

    the set of parameters to pass to the job.

  • session_token (String) —

    the session token for authenticated requests.

  • opts (Hash) —

    additional options (same as trigger_job).

Returns:

  • (Object) —

    the result data of the response.

Raises:



1571
1572
1573
1574
 
# File 'lib/parse/client.rb', line 1571

def self.trigger_job_with_session!(name, body = {}, session_token, **opts)
  opts[:session_token] = session_token
  trigger_job!(name, body, **opts)
end

.update_config(params, conn = :default, master_key_only: nil) ⇒ Hash

Set a key value pairs in the Parse configuration for an application.

Examples:

# batch update several
Parse.update_config({fieldEnabled: true, searchMiles: 50})
# also mark some keys as master-key-only
Parse.update_config({fieldEnabled: true}, master_key_only: { fieldEnabled: true })

Parameters:

  • params (Hash) —

    a set of key value pairs to set in the Parse configuration.

  • conn (Symbol) (defaults to: :default) —

    the name of the client connection to use.

  • master_key_only (Hash{String=>Boolean}, nil) (defaults to: nil) —

    optional map of config keys to boolean masterKeyOnly flags. Parse Server merges this with any existing masterKeyOnly settings; unspecified keys keep their current flag.

Returns:

  • (Hash) —

    the Parse config hash for the session.



138
139
140
141
 
# File 'lib/parse/client.rb', line 138

def self.update_config(params, conn = :default, master_key_only: nil)
  opts = master_key_only.nil? ? {} : { master_key_only: master_key_only }
  Parse::Client.client(conn).update_config(params, **opts)
end

.use_shortnames! ⇒ Object

Alias shorter names of core Parse class names. Ex, alias Parse::User to User, Parse::Installation to Installation, etc.



83
84
85
 
# File 'lib/parse/model/object.rb', line 83

def self.use_shortnames!
  require_relative "shortnames"
end

.validate_associations!(classes: nil) ⇒ true

Verify that every association target across the loaded Object subclasses resolves to a known Parse class. Covers belongs_to and property … as: pointer targets (via each class's references), has_many … through: :relation targets (via relations), and the query- and array-backed has_many targets (via has_many_associations) — the bucket where an as: typo otherwise stays latent until the association is first traversed at call time.

This is the deferred companion to the definition-time scalar guard in Parse::Associations::BelongsTo::ClassMethods#belongs_to: at declaration time a forward reference (a target class that is required later) is legal and indistinguishable from a typo, so the cross-class resolution check is run here — after all models are loaded. Intended to run once at boot, in CI, or from a rake task ("during the upgrade").

A target resolves when it is a Parse system class (_User, _Role, _Installation, _Session, …) or a registered Object subclass (via Parse::Model.find_class). Note this checks against loaded Ruby models: if you intentionally point at a server-side class that has no Ruby model, define a stub model for it or exclude it via classes:.

Parameters:

  • classes (Array<Class>, nil) (defaults to: nil) —

    optional subset of Parse::Object subclasses to check; defaults to every loaded subclass.

Returns:

  • (true) —

    when every association target resolves.

Raises:

  • (ArgumentError) —

    if any target is unresolved, listing each offending Class#field -> 'Target'.



832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
 
# File 'lib/parse/stack.rb', line 832

def validate_associations!(classes: nil)
  models = classes || Parse::Object.descendants
  problems = []
  models.each do |klass|
    next unless klass.respond_to?(:parse_class)
    if klass.respond_to?(:references)
      klass.references.each do |field, target|
        next if _association_target_resolvable?(target)
        # `references` is keyed by the remote (camelCase) column; report the
        # declared Ruby accessor so the operator can find the offending line.
        accessor = (klass.respond_to?(:field_map) && klass.field_map.key(field)) || field
        problems << "#{klass}##{accessor} -> #{target.inspect} (no such Parse class)"
      end
    end
    if klass.respond_to?(:relations)
      klass.relations.each do |field, target|
        next if _association_target_resolvable?(target)
        problems << "#{klass}##{field} (relation) -> #{target.inspect} (no such Parse class)"
      end
    end
    if klass.respond_to?(:has_many_associations)
      klass.has_many_associations.each do |accessor, meta|
        # `:relation`-storage has_many is mirrored into `relations` and is
        # already reported above; only the `:query` and `:array` storage
        # targets (which live nowhere else) need checking here. This is the
        # branch where a `has_many … as:` typo hides, since a query-backed
        # has_many resolves its target lazily at call time.
        next if meta[:storage] == :relation
        target = meta[:target_class]
        next if target.nil? || _association_target_resolvable?(target)
        problems << "#{klass}##{accessor} (has_many #{meta[:storage]}) -> " \
                    "#{target.inspect} (no such Parse class)"
      end
    end
  end
  unless problems.empty?
    raise ArgumentError,
          "Unresolved Parse association targets:\n  " + problems.join("\n  ") +
          "\nRequire/define the target class, or fix the `as:`/`class_name:` name."
  end
  true
end

.wait_for(klass, **kwargs, &block) ⇒ Object

See Also:



182
183
184
 
# File 'lib/parse/console.rb', line 182

def wait_for(klass, **kwargs, &block)
  Console.wait_for(klass, **kwargs, &block)
end

.warn_on_n_plus_one ⇒ Boolean Also known as: warn_on_n_plus_one?

Check if N+1 detection is enabled.

Returns:

  • (Boolean) 


370
371
372
 
# File 'lib/parse/query/n_plus_one_detector.rb', line 370

def warn_on_n_plus_one
  NPlusOneDetector.enabled?
end

.warn_on_n_plus_one=(value) ⇒ Object

Enable or disable N+1 query detection. When enabled, warnings are emitted when N+1 patterns are detected. For more control, use #n_plus_one_mode= instead.

Examples:

Enable N+1 detection

Parse.warn_on_n_plus_one = true

Parameters:

  • value (Boolean) —

    true enables :warn mode, false sets :ignore mode



364
365
366
 
# File 'lib/parse/query/n_plus_one_detector.rb', line 364

def warn_on_n_plus_one=(value)
  NPlusOneDetector.enabled = value
end

.watch(klass, **kwargs, &block) ⇒ Object

See Also:



177
178
179
 
# File 'lib/parse/console.rb', line 177

def watch(klass, **kwargs, &block)
  Console.watch(klass, **kwargs, &block)
end

.with_cache_tenant(scope) ⇒ Object 



222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/parse/stack.rb', line 222

def self.with_cache_tenant(scope)
  resolved = scope.nil? ? nil : scope.to_s
  resolved = nil if resolved&.empty?
  if resolved && !CACHE_TENANT_PATTERN.match?(resolved)
    raise ArgumentError,
          "Parse.with_cache_tenant scope must match #{CACHE_TENANT_PATTERN.source} " \
          "(got #{scope.inspect}). Colon and other key-segment-delimiter characters " \
          "are refused — they would collapse the cache-key namespace boundary."
  end
  previous = Fiber[CACHE_TENANT_STATE_KEY]
  Fiber[CACHE_TENANT_STATE_KEY] = resolved
  yield
ensure
  Fiber[CACHE_TENANT_STATE_KEY] = previous
end

.with_master_key { ... } ⇒ Object

Inverse of without_master_key: forces the master key back on for the duration of the block, even if a containing without_master_key had suppressed it. Useful for re-entering an admin-only operation inside a session-scoped block. If no master key is configured on the client, this is a no-op — the helper does not synthesise one.

Yields:

  • runs the block with master-key enabled (if configured)

Returns:

  • (Object) —

    the block's return value



87
88
89
90
91
92
93
 
# File 'lib/parse/stack.rb', line 87

def self.with_master_key
  previous = Fiber[MASTER_KEY_STATE_KEY]
  Fiber[MASTER_KEY_STATE_KEY] = :enabled
  yield
ensure
  Fiber[MASTER_KEY_STATE_KEY] = previous
end

.with_session(token) { ... } ⇒ Object

Run block with an ambient session token set for the current fiber. Inside the block, every Parse request that doesn't explicitly pass session_token: and doesn't explicitly request use_master_key: true will be sent with this token. Equivalent to threading session_token: through every call site, but block-scoped.

The token argument may be a String, a User (its session_token is read), a Session (its session_token is read), or nil. Passing nil clears the ambient inside the block — useful for performing one anonymous call inside an otherwise session-scoped region.

Fiber-local, not thread-local: concurrent fibers (and threads, since each thread starts with its own root fiber) do not share state. Survives Faraday retries — the token lives for the lifetime of the block, not just the first HTTP attempt.

An explicit session_token: kwarg on any call still wins over the ambient. An explicit use_master_key: true skips the ambient and sends the master key (if configured).

Examples:

user = Parse::User.login!("alice", "pw")
Parse.with_session(user) do
  post = Post.find(id)                # scoped to alice
  post.title = "edited"
  post.save                            # subject to ACL/CLP
  Comment.all(post: post)              # scoped to alice
end

Parameters:

Yields:

  • runs the block with the ambient session token in place

Returns:

  • (Object) —

    the block's return value



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/parse/stack.rb', line 140

def self.with_session(token)
  resolved = token.respond_to?(:session_token) ? token.session_token : token
  resolved = resolved.to_s if resolved
  # Capture BEFORE any raise so the `ensure` always restores the real
  # previous ambient (never clobbers an enclosing with_session).
  previous = Fiber[SESSION_TOKEN_STATE_KEY]
  # SEC-02: a present-but-blank (empty or whitespace) token is an unusable
  # credential. The prior behavior stored a whitespace token as the ambient
  # (only an exactly-empty string was treated as absent), and the request
  # layer would then drop it and silently send the master key. Reject blank
  # tokens loudly at the source instead. `nil` still means "no ambient".
  if resolved.is_a?(String) && resolved.strip.empty?
    raise ArgumentError,
      "Parse.with_session was given a blank session token. A present-but-empty " \
      "token is refused so the block cannot silently execute with master-key " \
      "authority — pass a valid session token, or `nil` for no ambient session."
  end
  Fiber[SESSION_TOKEN_STATE_KEY] = resolved
  yield
ensure
  Fiber[SESSION_TOKEN_STATE_KEY] = previous
end

.without_master_key { ... } ⇒ Object

Run block with the master key suppressed for every Parse request originating in the current fiber. Equivalent to setting the X-Disable-Parse-Master-Key header on each request, but block-scoped so callers can wrap a unit of work — e.g. running an action "as if the configured master key were not available" — without threading the header through every intermediate call.

Survives Faraday retries (the per-request header would be stripped on the first attempt and gone by the retry; the fiber-local state lives for the lifetime of the block).

Examples:

Parse.without_master_key do
  song = Song.find(id)         # session-token / API-key auth only
  song.title = "Renamed"
  song.save                    # subject to ACL/CLP
end

Yields:

  • runs the block with master-key disabled

Returns:

  • (Object) —

    the block's return value



71
72
73
74
75
76
77
 
# File 'lib/parse/stack.rb', line 71

def self.without_master_key
  previous = Fiber[MASTER_KEY_STATE_KEY]
  Fiber[MASTER_KEY_STATE_KEY] = :disabled
  yield
ensure
  Fiber[MASTER_KEY_STATE_KEY] = previous
end