parse-stack-next 5.0.1 → 5.1.0

data/lib/parse/query.rb

@@ -2966,9 +2966,26 @@ module Parse
     # @param fields [Array<String>] specific fields to watch for changes (nil = all fields)
     # @param session_token [String] session token for ACL-aware subscriptions
     # @param client [Parse::LiveQuery::Client] custom LiveQuery client (optional)
+    # @param use_master_key [Boolean] an intent assertion, NOT a
+    #   per-subscription elevation. Parse Server resolves `masterKey`
+    #   once, at connect time, from the LiveQuery connect frame; the
+    #   subscribe frame never carries it. This flag therefore only has
+    #   effect when the underlying client is itself an admin connection
+    #   (`Parse::LiveQuery::Client.new(use_master_key: true)` with a
+    #   master key), in which case the entire socket is already elevated
+    #   and ALL its subscriptions bypass ACL/CLP. On a non-admin
+    #   connection `use_master_key: true` does not elevate the
+    #   subscription and emits a security warning. A single socket cannot
+    #   mix scoped and admin subscriptions — use separate connections for
+    #   end-user (session-token-scoped) versus administrative
+    #   (master-key-scoped) work.
+    # @yield [subscription] runs the block with the freshly-constructed
+    #   {Parse::LiveQuery::Subscription} BEFORE the subscribe frame is
+    #   sent so caller-registered callbacks are wired before any server
+    #   events can arrive. Optional.
     # @return [Parse::LiveQuery::Subscription] the subscription object
     # @see Parse::LiveQuery::Subscription
-    def subscribe(fields: nil, session_token: nil, client: nil)
+    def subscribe(fields: nil, session_token: nil, client: nil, use_master_key: false, &block)
       require_relative "live_query"
 
       lq_client = client || Parse::LiveQuery.client
@@ -2977,6 +2994,8 @@ module Parse
         where: compile_where,
         fields: fields,
         session_token: session_token || @session_token,
+        use_master_key: use_master_key,
+        &block
       )
     end
 
@@ -5420,6 +5439,17 @@ module Parse
   # Helper class for executing arbitrary MongoDB aggregation pipelines.
   # Provides a consistent interface with results, raw, and result_pointers methods.
   class Aggregation
+    # @return [Array<Hash>] the MongoDB aggregation pipeline stages this
+    #   Aggregation will execute. Useful for previewing the routed pipeline
+    #   before {#execute!}, for snapshot-based regression tests, and for
+    #   debugging the REST-vs-mongo-direct translation.
+    attr_reader :pipeline
+
+    # @return [Boolean] whether {#execute!} will route through
+    #   {Parse::MongoDB.aggregate} instead of Parse Server's REST
+    #   `/aggregate` endpoint.
+    attr_reader :mongo_direct
+
     # @param query [Parse::Query] the base query object
     # @param pipeline [Array<Hash>] the MongoDB aggregation pipeline stages
     # @param verbose [Boolean, nil] whether to print verbose output (nil means use query's setting)

data/lib/parse/stack/version.rb

@@ -6,6 +6,6 @@ module Parse
   # The Parse Server SDK for Ruby
   module Stack
     # The current version.
-    VERSION = "5.0.1"
+    VERSION = "5.1.0"
   end
 end

data/lib/parse/stack.rb

@@ -154,6 +154,81 @@ module Parse
     Fiber[SESSION_TOKEN_STATE_KEY]
   end
 
+  # @!visibility private
+  CACHE_TENANT_STATE_KEY = :__parse_cache_tenant__
+
+  # Set an ambient cache-tenant scope for the duration of the block.
+  # When set, the {Parse::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.
+  #
+  # @example 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
+  #
+  # @example compose with `with_session`
+  #   Parse.with_cache_tenant(tenant_id) do
+  #     Parse.with_session(user) do
+  #       Post.all
+  #     end
+  #   end
+  #
+  # @param scope [String, Symbol, nil] tenant identifier. `nil` clears
+  #   the ambient scope for the duration of the block (useful to opt
+  #   out within a larger tenant-scoped section). Must be ASCII
+  #   `[A-Za-z0-9_-]+` — colon and other key-segment-delimiter chars
+  #   are refused with `ArgumentError`, since the middleware composes
+  #   the tenant into the cache key as `T:<tenant>:…` and a tenant
+  #   containing `:` would collapse the segmentation (e.g.
+  #   `with_cache_tenant("a:T:b")` would produce keys
+  #   indistinguishable from `with_cache_tenant("a")` nested under
+  #   `with_cache_tenant("b")`, breaking SCAN-delete isolation).
+  # @yield runs the block with the ambient tenant scope in place
+  # @return [Object] the block's return value
+  # @raise [ArgumentError] when `scope` contains characters outside
+  #   `[A-Za-z0-9_-]` or exceeds 256 bytes.
+  CACHE_TENANT_PATTERN = /\A[A-Za-z0-9_\-]{1,256}\z/.freeze
+  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
+
+  # The ambient cache-tenant scope set by {.with_cache_tenant} for the
+  # current fiber, or `nil` when not inside such a block.
+  # @return [String, nil]
+  def self.current_cache_tenant
+    Fiber[CACHE_TENANT_STATE_KEY]
+  end
+
   # The {Parse::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.
@@ -336,9 +411,31 @@ module Parse
   # so the network-egress surface (an outbound WebSocket to the LiveQuery
   # server) is opened only when the operator explicitly turns it on, not
   # as a side effect of requiring the file.
+  #
+  # The LiveQuery module is autoloaded — `Parse::LiveQuery.configure { … }`
+  # works without an explicit `require 'parse/live_query'`. The autoload
+  # is purely a file-loading convenience; it does NOT open a network
+  # connection. A connection only opens when `Parse.live_query_enabled = true`
+  # AND a `Parse::LiveQuery::Client` is instantiated (typically via
+  # `Klass.subscribe { … }` or `Parse::Client.new(live_query_url: …)`).
+  #
   # @example Enable LiveQuery
   #   Parse.live_query_enabled = true
-  #   require 'parse/live_query'
+  #   # Parse::LiveQuery is autoloaded — no explicit require needed
+  #   Parse::LiveQuery.configure do |c|
+  #     c.url = "wss://parse.example.com"
+  #   end
+  autoload :LiveQuery, "parse/live_query"
+
+  # Public mutual-exclusion primitive (TTL-bounded, Redis-backed with
+  # in-process Mutex fallback). See {Parse::Lock}.
+  autoload :Lock, "parse/lock"
+
+  # Shared low-level lock primitives consumed by both {Parse::Lock}
+  # and {Parse::CreateLock}. `@api private` — application code should
+  # use {Parse::Lock.acquire}.
+  autoload :LockBackend, "parse/lock_backend"
+
   @live_query_enabled = false
 
   # Configuration for cache write-through on fetch operations.

data/parse-stack-next.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
   spec.authors = ["Anthony Persaud", "Henry Spindell", "Adrian Curtin"]
   spec.email = ["adrian+parse-stack@neurosynq.net"]
 
-  spec.summary = %q{Parse Server Ruby Client SDK (parse-stack-next fork)}
-  spec.description = %q{Parse Server Ruby Client. Perform Object-relational mapping between Parse Server and Ruby classes, with authentication, cloud code webhooks, push notifications and more built in. parse-stack-next is a fork of parse-stack with additional features: vector search, Atlas Search, agent ACL scopes, GraphQL, MongoDB-direct pipeline enforcement, and ongoing maintenance.}
+  spec.summary = %q{Parse Server SDK for Ruby — ORM, queries, auth, and MongoDB-direct access}
+  spec.description = %q{Production-grade Ruby client for Parse Server. Map Parse classes to Ruby models with typed properties, associations, and validations; build queries with a chainable DataMapper-style DSL; handle auth, sessions, MFA, cloud code webhooks, and push; introspect and migrate schemas; manage role hierarchies; scope access with per-agent ACL/CLP; generate GraphQL types; run Atlas Search and vector search; and bypass REST for high-throughput reads via the MongoDB-direct pipeline.}
   spec.homepage = "https://github.com/neurosynq/parse-stack-next"
   spec.license = "MIT"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: parse-stack-next
 version: !ruby/object:Gem::Version
-  version: 5.0.1
+  version: 5.1.0
 platform: ruby
 authors:
 - Anthony Persaud
@@ -195,11 +195,12 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-description: 'Parse Server Ruby Client. Perform Object-relational mapping between
-  Parse Server and Ruby classes, with authentication, cloud code webhooks, push notifications
-  and more built in. parse-stack-next is a fork of parse-stack with additional features:
-  vector search, Atlas Search, agent ACL scopes, GraphQL, MongoDB-direct pipeline
-  enforcement, and ongoing maintenance.'
+description: Production-grade Ruby client for Parse Server. Map Parse classes to Ruby
+  models with typed properties, associations, and validations; build queries with
+  a chainable DataMapper-style DSL; handle auth, sessions, MFA, cloud code webhooks,
+  and push; introspect and migrate schemas; manage role hierarchies; scope access
+  with per-agent ACL/CLP; generate GraphQL types; run Atlas Search and vector search;
+  and bypass REST for high-throughput reads via the MongoDB-direct pipeline.
 email:
 - adrian+parse-stack@neurosynq.net
 executables:
@@ -210,6 +211,9 @@ files:
 - ".bundle/config"
 - ".env.sample"
 - ".env.test"
+- ".github/ISSUE_TEMPLATE/bug_report.yml"
+- ".github/ISSUE_TEMPLATE/feature_request.yml"
+- ".github/dependabot.yml"
 - ".github/workflows/codeql.yml"
 - ".github/workflows/docs.yml"
 - ".github/workflows/release.yml"
@@ -218,6 +222,7 @@ files:
 - ".ruby-version"
 - ".solargraph.yml"
 - ".vscode/settings.json"
+- ".yardopts"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
@@ -238,12 +243,15 @@ files:
 - config/parse-config.json
 - docs/TEST_SERVER.md
 - docs/_config.yml
+- docs/acl_clp_guide.md
 - docs/atlas_vector_search_guide.md
 - docs/client_sdk_guide.md
 - docs/mcp_guide.md
 - docs/mongodb_direct_guide.md
 - docs/mongodb_index_optimization_guide.md
 - docs/usage_guide.md
+- docs/yard-template/default/fulldoc/html/css/common.css
+- docs/yard-template/default/fulldoc/html/css/full_list.css
 - examples/transaction_example.rb
 - lib/parse-stack-next.rb
 - lib/parse-stack.rb
@@ -321,6 +329,8 @@ files:
 - lib/parse/live_query/health_monitor.rb
 - lib/parse/live_query/logging.rb
 - lib/parse/live_query/subscription.rb
+- lib/parse/lock.rb
+- lib/parse/lock_backend.rb
 - lib/parse/lookup_rewriter.rb
 - lib/parse/model/acl.rb
 - lib/parse/model/associations/belongs_to.rb
@@ -445,5 +455,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Parse Server Ruby Client SDK (parse-stack-next fork)
+summary: Parse Server SDK for Ruby — ORM, queries, auth, and MongoDB-direct access
 test_files: []