parse-stack-next 5.0.1 → 5.1.0

data/lib/parse/live_query/subscription.rb

@@ -74,13 +74,26 @@ module Parse
       # @param query [Hash] query constraints (where clause)
       # @param fields [Array<String>, nil] specific fields to watch
       # @param session_token [String, nil] session token for authentication
-      def initialize(client:, class_name:, query: {}, fields: nil, session_token: nil)
+      # @param use_master_key [Boolean] an intent assertion that this
+      #   subscription needs master-key (ACL-bypassing) scope. It does
+      #   NOT put `masterKey` on the subscribe frame: Parse Server has no
+      #   per-subscription master key — `client.hasMasterKey` is fixed
+      #   per connection at connect time, so one subscription on a scoped
+      #   socket can never be selectively elevated. The flag is honored
+      #   only when the parent client is an admin connection (built with
+      #   `use_master_key: true`), where the whole connection is already
+      #   elevated; on a non-admin connection the client warns and the
+      #   subscription stays ACL-scoped. For mixed scoped + admin needs,
+      #   use two separate clients. Defaults to false.
+      def initialize(client:, class_name:, query: {}, fields: nil,
+                     session_token: nil, use_master_key: false)
         @monitor = Monitor.new
         @client = client
         @class_name = class_name
         @query = query
         @fields = fields
         @session_token = session_token
+        @use_master_key = use_master_key == true
         @request_id = generate_request_id
         @state = :pending
         @callbacks = Hash.new { |h, k| h[k] = [] }
@@ -97,6 +110,20 @@ module Parse
         @monitor.synchronize { @state }
       end
 
+      # Redacting inspect — the default `inspect` would expose
+      # `@session_token` (and, via `@client`, the client's master/REST
+      # keys) in any log line, backtrace, error page, or error reporter
+      # that renders the subscription. Reads `@state` directly rather
+      # than through the monitor so a diagnostic inspect never blocks on
+      # the lock.
+      # @return [String]
+      def inspect
+        token = @session_token.nil? || @session_token.empty? ? "nil" : "[REDACTED]"
+        "#<#{self.class.name} request_id=#{@request_id.inspect} " \
+        "class_name=#{@class_name.inspect} state=#{@state.inspect} " \
+        "use_master_key=#{@use_master_key} session_token=#{token}>"
+      end
+
       # Register a callback for a specific event type
       # @param event_type [Symbol] :create, :update, :delete, :enter, :leave, :error, :subscribe, :unsubscribe
       # @yield [object, original] block to call when event occurs
@@ -214,10 +241,26 @@ module Parse
 
         msg[:query][:fields] = fields if fields&.any?
         msg[:sessionToken] = session_token if session_token
+        # The subscribe frame deliberately NEVER carries `masterKey`.
+        # Parse Server's `_handleSubscribe` does not read it — master-key
+        # (ACL-bypass) authorization is resolved once, per connection, in
+        # `_handleConnect` (`client.hasMasterKey`). Emitting it here put a
+        # privileged credential on the wire for ZERO server-side effect.
+        # `use_master_key: true` at the subscription level is an intent
+        # assertion validated by the client (which warns when it cannot
+        # be honored on a non-admin connection); the actual elevation is
+        # the admin connection's connect frame. See
+        # {Parse::LiveQuery::Client#use_master_key}.
 
         msg
       end
 
+      # @return [Boolean] whether this subscription opted into
+      #   per-subscription master-key auth via `use_master_key: true`.
+      def use_master_key?
+        @use_master_key == true
+      end
+
       # Build the unsubscribe message
       # @return [Hash]
       def to_unsubscribe_message
@@ -252,9 +295,19 @@ module Parse
       # @api private
       def fail!(error)
         @monitor.synchronize { @state = :error }
-        error = SubscriptionError.new(error) if error.is_a?(String)
+        # Promote String errors (which come back from the LiveQuery
+        # server with messages like "Permission denied (code: 101)")
+        # to typed SubscriptionError instances carrying the request_id
+        # and class_name as structured context. The resulting
+        # `e.message` reads `request_id=<n> class=<X> <server message>`,
+        # so a single-line log captures the operational context the
+        # raw server string lacks.
+        if error.is_a?(String)
+          error = SubscriptionError.new(error, request_id: @request_id, class_name: @class_name)
+        end
         Logging.error("Subscription failed",
                       request_id: @request_id,
+                      class_name: @class_name,
                       error: error)
         emit(:error, error)
       end

data/lib/parse/live_query.rb

@@ -57,7 +57,37 @@ module Parse
     # `rescue Parse::Error` will also catch LiveQuery failures.
     class Error < Parse::Error; end
     class ConnectionError < Error; end
-    class SubscriptionError < Error; end
+
+    # Raised when the LiveQuery server rejects a subscribe request.
+    # Carries the originating `request_id` (the client-assigned
+    # sequence number used for op/error correlation on the same socket)
+    # and the `class_name` the subscription targeted. Both are present
+    # on `Subscription#fail!`-constructed instances; standalone
+    # `SubscriptionError.new("...")` callers can omit them and the
+    # `message` is preserved verbatim.
+    #
+    # Mirrors the structure of `Parse::Error::ProtocolError` — the
+    # error string contains the contextual prefix when the fields are
+    # set so `rescue SubscriptionError => e; e.message` carries enough
+    # for a single-line log line without inspecting `e` further.
+    class SubscriptionError < Error
+      # @return [Integer, nil] request id of the failed subscribe
+      attr_reader :request_id
+      # @return [String, nil] Parse class the subscription was targeting
+      attr_reader :class_name
+
+      def initialize(message_or_error, request_id: nil, class_name: nil)
+        @request_id = request_id
+        @class_name = class_name
+        text = message_or_error.respond_to?(:message) ? message_or_error.message : message_or_error.to_s
+        prefix_parts = []
+        prefix_parts << "request_id=#{request_id}" if request_id
+        prefix_parts << "class=#{class_name}" if class_name
+        prefixed = prefix_parts.empty? ? text : "#{prefix_parts.join(' ')} #{text}"
+        super(prefixed)
+      end
+    end
+
     class AuthenticationError < Error; end
 
     # Default LiveQuery events
@@ -163,6 +193,98 @@ module Parse
           master_key: config.master_key,
         }
       end
+
+      # Block until the process receives one of `signals` (default
+      # `INT` and `TERM`), then gracefully shut down the supplied
+      # LiveQuery client and return. Designed for long-running
+      # rake-task-style consumers of LiveQuery (`rake livequery:tail`,
+      # `rake installations:watch`, etc.) where the caller's natural
+      # idiom is "subscribe, then wait forever; on Ctrl-C, clean up."
+      #
+      # **Why a helper:** Signal.trap blocks on MRI / macOS run in a
+      # restricted context — calling `client.unsubscribe` /
+      # `client.close` (which themselves take the client's internal
+      # Monitor) directly from the trap raises `ThreadError: can't be
+      # called from trap context` on the platforms that enforce
+      # `:signal_safe?`. The safe idiom is "set a flag in the trap,
+      # poll from the main thread, perform the shutdown there." This
+      # method bundles that idiom so callers don't have to re-derive
+      # it (and so they don't deploy the unsafe version and hit the
+      # ThreadError in production).
+      #
+      # The supplied block (if any) runs once before the wait loop,
+      # so callers can hand-off subscription setup that should not
+      # race the trap installation:
+      #
+      # @example
+      #   Parse::LiveQuery.run_until_signal! do |client|
+      #     client.subscribe(Post, where: { published: true }) do |sub|
+      #       sub.on(:create) { |obj| puts "new post: #{obj.id}" }
+      #     end
+      #   end
+      #
+      # @param client [Parse::LiveQuery::Client, nil] client to shut
+      #   down on signal. Defaults to `Parse::LiveQuery.client` (the
+      #   process-wide default).
+      # @param signals [Array<Symbol, String>] signal names to trap.
+      #   Defaults to `%i[INT TERM]` — common for SIGINT (Ctrl-C) and
+      #   SIGTERM (orchestrator stop).
+      # @param shutdown_timeout [Float] seconds to allow
+      #   {Parse::LiveQuery::Client#shutdown} to drain pending events.
+      # @param poll_interval [Float] seconds between sentinel checks.
+      #   Lower values reduce shutdown latency; higher values reduce
+      #   wakeup overhead on idle processes. Default 0.25s.
+      # @yieldparam client [Parse::LiveQuery::Client] passed once
+      #   before the wait loop starts. Optional.
+      # @return [void] returns after the client has been shut down.
+      def run_until_signal!(client: nil, signals: %i[INT TERM],
+                            shutdown_timeout: 5.0, poll_interval: 0.25)
+        ensure_enabled!
+        unless signals.is_a?(Array) && !signals.empty?
+          raise ArgumentError,
+                "Parse::LiveQuery.run_until_signal!: signals must be a non-empty Array " \
+                "(got #{signals.inspect}). An empty list would block the poll loop forever " \
+                "with no trap installed."
+        end
+        target = client || self.client
+
+        # Sentinel is a single-element queue rather than an instance
+        # variable so the trap handler does only the absolute minimum
+        # work (one `push`) — no mutex acquisition, no allocation
+        # beyond what `<<` does internally.
+        stop_signal = Queue.new
+        installed = []
+        begin
+          # Yield BEFORE installing traps (so a SIGINT during caller
+          # setup still aborts normally) but INSIDE the begin/ensure so a
+          # raise from the block — including Interrupt — still runs the
+          # shutdown/restore cleanup below rather than leaking the
+          # client's connection and threads.
+          yield(target) if block_given?
+
+          signals.each do |sig|
+            prior = Signal.trap(sig) { stop_signal << sig }
+            installed << [sig, prior]
+          end
+
+          # Block until a signal arrives. Use `Queue#pop` with the
+          # poll loop so trap-context limitations don't matter — we
+          # only ever ENQUEUE from the trap; the dequeue is here on
+          # the main thread.
+          loop do
+            sig = stop_signal.pop(true) rescue nil
+            break if sig
+            sleep poll_interval
+          end
+        ensure
+          # Restore the prior trap handlers so re-running the helper
+          # (e.g. in tests, or in a parent process that traps INT
+          # itself) does not leak our handler.
+          installed.each { |sig, prior| Signal.trap(sig, prior) if prior }
+          # Shutdown from the main thread, not the trap context.
+          target.shutdown(timeout: shutdown_timeout) if target.respond_to?(:shutdown)
+        end
+      end
     end
   end
 end

data/lib/parse/lock.rb

@@ -0,0 +1,342 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "securerandom"
+require "digest"
+require "openssl"
+require_relative "lock_backend"
+
+module Parse
+  # Public mutual-exclusion primitive built on the same Redis-backed
+  # store + in-process Mutex fallback used internally by
+  # `first_or_create!` and `create_or_update!`. Designed for callers
+  # who need a distributed lock outside the find-or-create flow —
+  # bulk-import dedup, cron-job singletons, idempotency keys for
+  # external API integrations, anywhere two processes might race the
+  # same logical operation.
+  #
+  # == Contract
+  #
+  # * **TTL-bounded — mutual exclusion with a DEADLINE, not exactly-once.**
+  #   Every acquisition writes a TTL on the Redis key (1..30s, default
+  #   3s). If the holder crashes or the process is terminated mid-block,
+  #   the lock self-clears after `ttl:` seconds — there is no manual
+  #   recovery step. The block-form API releases on normal return, on
+  #   exception, and on `return`/`break`/`raise` exiting the block (via
+  #   `ensure`). **Critical caveat:** if your critical section runs
+  #   LONGER than `ttl:`, the lease expires WHILE you are still inside
+  #   the block, a second caller can acquire, and two holders then run
+  #   concurrently — the lock provides no signal to the first holder
+  #   that this happened (it logs a `[Parse::Lock]` warning on release if
+  #   it detects its own lease overran). There is no fencing token that
+  #   the protected resource checks, so this primitive does NOT give you
+  #   exactly-once execution. Size `ttl:` comfortably above your
+  #   worst-case section duration, AND make the protected operation
+  #   idempotent so a rare double-execution is harmless. The block
+  #   receives its owner token (`acquire(key) { |token| ... }`) for
+  #   callers who want to build their own fencing against a
+  #   token-checking resource.
+  # * **In-process Mutex fallback when Redis unavailable.** If the
+  #   configured cache is process-local (Moneta `Memory` / `Null`) or
+  #   nil, this falls back to a per-key `Mutex` keyed in this process.
+  #   That guards single-process contention but does NOT serialize
+  #   across processes — operators running multi-worker deployments
+  #   should configure a Redis-backed cache for the locking to
+  #   actually serve its purpose. The fallback emits a one-line warn
+  #   on first use per process (throttle via `on_degraded: :warn_throttled`).
+  # * **Fails closed on acquisition errors.** Errors raised by the
+  #   underlying store during `SETNX`-style acquisition are caught,
+  #   warned, and treated as "lock not acquired" — `acquire` will keep
+  #   polling until the `wait:` budget elapses, then raise
+  #   {Parse::Lock::TimeoutError}. The block is NEVER entered without
+  #   the lock; there is no "best-effort proceed without locking"
+  #   escape hatch.
+  # * **TTL/wait clamps.** `ttl:` is clamped to 1..30s; `wait:` is
+  #   clamped to 0.0..30s. Callers asking for longer windows are
+  #   silently capped (the underlying store cannot reliably hold a
+  #   minutes-long lock under typical Redis maxmemory eviction
+  #   policies; documented in the operator guide).
+  #
+  # == Cooperation with `first_or_create!`
+  #
+  # Both APIs talk to the same store under the same namespace
+  # (`parse-stack:foc:v1:<digest>` for `first_or_create!`,
+  # `parse-stack:lock:v1:<your-key>` for {Parse::Lock}). The prefix
+  # difference ensures the two namespaces cannot collide — a
+  # {Parse::Lock.acquire(key: "billing-cycle-2026-Q4")} cannot block
+  # a `first_or_create!` for the literally-equal-named row.
+  #
+  # @example bulk-import dedup
+  #   Parse::Lock.acquire("import:#{batch_id}", ttl: 10) do
+  #     # Only one worker runs the import for this batch; the rest
+  #     # either get LockTimeoutError or see the already-imported state.
+  #     run_batch_import(batch_id)
+  #   end
+  #
+  # @example cron singleton
+  #   Parse::Lock.acquire("cron:nightly-rollup", ttl: 5, wait: 0) do
+  #     # wait: 0 → either acquire immediately or raise. Other workers
+  #     # discover "someone else has it" without spinning.
+  #     compute_nightly_rollup
+  #   end
+  #
+  # @example external-API idempotency key (idempotent body required)
+  #   Parse::Lock.acquire("stripe-webhook:#{evt_id}", ttl: 30, wait: 0.5) do
+  #     # Serializes concurrent deliveries of the same evt_id so they
+  #     # don't race. This is NOT exactly-once: if processing outruns
+  #     # `ttl:`, a second delivery can acquire and run in parallel.
+  #     # `process_webhook` must be idempotent (e.g. check an
+  #     # already-processed marker keyed by evt_id) so a double run is a
+  #     # no-op, not a double charge.
+  #     process_webhook(evt_id)
+  #   end
+  module Lock
+    KEY_PREFIX = "parse-stack:lock:v1:"
+
+    DEFAULT_TTL  = 3
+    DEFAULT_WAIT = 2.0
+    MAX_TTL      = 30
+    MAX_WAIT     = 30
+
+    # Minimum byte-length for an explicit `secret:` kwarg. 16 bytes
+    # ≈ 128 bits of separation between tenants — short enough not to
+    # burden an operator who already has a real secret, long enough
+    # that a `secret: "a"` misconfiguration is refused at the
+    # boundary rather than silently degrading the lock-pinning
+    # resistance claim. Applies ONLY to the `secret:` kwarg path; the
+    # operator-configured `PARSE_STACK_LOCK_SECRET` path is not
+    # length-checked here (different threat model — that's the
+    # operator's process-boot configuration, not a per-call argument).
+    SECRET_MIN_BYTES = 16
+
+    # Raised when {Parse::Lock.acquire} cannot obtain the lock within
+    # the configured `wait:` budget. Distinct from
+    # `Parse::CreateLockTimeoutError` (the `first_or_create!` /
+    # `create_or_update!` internal) so callers can `rescue` one
+    # without picking up the other — namespacing the error under
+    # `Parse::Lock::` makes the peer-not-base relationship explicit.
+    class TimeoutError < Parse::Error; end
+
+    # Raised when {Parse::Lock.acquire} is asked to use a degraded
+    # (process-local) store with `on_degraded: :raise`. The default
+    # behavior is to fall back to an in-process Mutex with a
+    # warning; this error only fires when the caller explicitly
+    # opts into the strict mode.
+    class UnavailableError < Parse::Error; end
+
+    class << self
+      # Acquire `key`, run the block, release on return. Block-form
+      # only — there is no `try_acquire` returning a token (the
+      # token-based form makes ensure-release the caller's job, and
+      # any caller forgetting `ensure release(token)` leaks the key
+      # for `ttl:` seconds before TTL expiry. Block-form is the safe
+      # default; if you need finer control, build it locally.)
+      #
+      # @param key [String] a stable identifier for the resource being
+      #   guarded. By default hashed via HMAC-SHA256 keyed with the
+      #   operator-configured secret (`PARSE_STACK_LOCK_SECRET` or
+      #   `Parse.synchronize_create_secret`); when no secret is
+      #   configured AND the store is cross-process (Redis), falls
+      #   back to plain SHA-256 with a one-time `[Parse::Lock:SECURITY]`
+      #   warning that names the enumeration + lock-pinning risks and
+      #   the remediation knob. When the store is process-local
+      #   (Memory / Null / nil), an auto-derived per-process secret
+      #   is used regardless — process-local locking already implies
+      #   single-process, so a per-process secret doesn't break
+      #   cross-process equality. Use `secret:` to override per call.
+      #   Must be a non-empty String of at most 1024 bytes — longer
+      #   keys are refused (a runaway-string bug that turned into a
+      #   multi-megabyte key would silently break Redis perf).
+      # @param ttl [Integer] seconds the lock is held before
+      #   self-clearing. Clamped to 1..30. Pick a value comfortably
+      #   longer than your expected critical-section duration; the
+      #   TTL is a crash-recovery floor, not a hard cap on work.
+      # @param wait [Float] seconds to wait for the lock if another
+      #   holder has it. Clamped to 0.0..30. Pass 0 to fail-fast
+      #   (raise LockTimeoutError immediately if contended).
+      # @param on_degraded [Symbol] action when the store is
+      #   process-local: `:warn` (default — one warning per call),
+      #   `:warn_throttled` (one warning per minute), `:proceed`
+      #   (silent), `:raise` (raise Parse::Lock::UnavailableError).
+      #   **Asymmetric-degradation residual risk:** if two processes
+      #   target the same Redis but disagree on degraded-detection
+      #   (e.g. process A has `Parse.synchronize_create_store = nil`
+      #   while process B has it wired to Redis), A takes the
+      #   `auto_secret` branch and B takes the `nil`/plain-SHA branch.
+      #   They derive different store keys for the same raw key and
+      #   silently fail to mutually exclude. The `:warn` mode fires
+      #   only on the degraded process (A); the operator may not
+      #   connect "A logged a degraded warning" with "B is also
+      #   running but with a different effective lock surface."
+      #   Mitigation: set `Parse.synchronize_create_store` uniformly
+      #   across deployment workers, OR pass `on_degraded: :raise`
+      #   so any disagreement surfaces loudly.
+      # @param secret [Symbol, String, nil] HMAC secret selection.
+      #   `:auto` (default) uses {Parse::LockBackend.lock_secret_for}
+      #   — picks up `PARSE_STACK_LOCK_SECRET` /
+      #   `Parse.synchronize_create_secret` when set, auto-derives
+      #   a per-process secret for degraded stores, falls back to
+      #   plain SHA-256 with a security warn for cross-process
+      #   stores without a configured secret. A `String` overrides
+      #   the resolution and uses that secret directly (useful when
+      #   a single flow needs a different keying than the global
+      #   default). `nil` explicitly opts out of HMAC and uses plain
+      #   SHA-256 — no warn, since the opt-out is deliberate.
+      # @yield [owner] runs the block with the lock held. The block
+      #   receives the unique owner token for this acquisition — usable
+      #   as a fencing token by callers whose protected resource can
+      #   reject stale tokens. Most callers ignore it. (On the degraded
+      #   in-process Mutex path a fresh token is still supplied so the
+      #   block signature is stable.)
+      # @return [Object] the block's return value.
+      # @raise [ArgumentError] on invalid `key` / `ttl` / `wait` /
+      #   `on_degraded` / `secret`.
+      # @raise [Parse::Lock::TimeoutError] when `wait` elapses without
+      #   acquisition.
+      # @raise [Parse::Lock::UnavailableError] when `on_degraded: :raise`
+      #   and the store is process-local.
+      def acquire(key, ttl: DEFAULT_TTL, wait: DEFAULT_WAIT,
+                  on_degraded: :warn, secret: :auto, &block)
+        raise ArgumentError, "block required" unless block_given?
+        validated_key = validate_key!(key)
+        validate_on_degraded!(on_degraded)
+        validate_secret!(secret)
+        normalized_ttl  = clamp(Integer(ttl),  1,   MAX_TTL)
+        normalized_wait = clamp(Float(wait),   0.0, MAX_WAIT)
+
+        # Route through Parse::LockBackend — the shared module that
+        # also serves Parse::CreateLock. The KEY_PREFIX
+        # ("parse-stack:lock:v1:") is distinct from CreateLock's
+        # ("parse-stack:foc:v1:") so the two namespaces cannot
+        # collide even on literally-equal-named keys.
+        store = Parse::LockBackend.lock_store
+
+        # Resolve HMAC secret (or nil for plain SHA) per the
+        # `secret:` kwarg semantics above. The `:auto` branch picks
+        # up the operator-configured secret if one exists; the
+        # explicit-String branch overrides it; the explicit-nil
+        # branch opts out without a warn.
+        resolved_secret =
+          case secret
+          when :auto   then Parse::LockBackend.lock_secret_for(store: store, source: "Parse::Lock")
+          when String  then secret
+          when nil     then nil
+          end
+        digest = resolved_secret \
+          ? OpenSSL::HMAC.hexdigest("SHA256", resolved_secret, validated_key) \
+          : Digest::SHA256.hexdigest(validated_key)
+        store_key = "#{KEY_PREFIX}#{digest}"
+
+        if Parse::LockBackend.degraded_store?(store)
+          Parse::LockBackend.handle_degraded(
+            on_degraded, store_key,
+            source: "Parse::Lock",
+            unavailable_error: Parse::Lock::UnavailableError,
+          )
+          # Supply a token so a `{ |token| ... }` block has a stable
+          # signature across the Redis and degraded paths. There is no
+          # cross-process owner here — the Mutex IS the exclusion — so a
+          # fresh UUID is purely for signature parity / local fencing.
+          return Parse::LockBackend.process_mutex(store_key).synchronize do
+            yield SecureRandom.uuid
+          end
+        end
+
+        owner       = SecureRandom.uuid
+        acquired_at = nil
+        start       = Parse::LockBackend.monotonic_now
+
+        loop do
+          if Parse::LockBackend.try_acquire(store, store_key, owner, normalized_ttl)
+            acquired_at = Parse::LockBackend.monotonic_now
+            break
+          end
+          elapsed = Parse::LockBackend.monotonic_now - start
+          if elapsed >= normalized_wait
+            raise Parse::Lock::TimeoutError,
+                  "Parse::Lock.acquire: could not acquire #{key.inspect} within #{normalized_wait}s"
+          end
+          sleep(Parse::LockBackend.poll_interval)
+        end
+
+        begin
+          yield owner
+        ensure
+          if acquired_at
+            # Detect a lease overrun: if the critical section ran longer
+            # than the TTL, our lock already expired and another caller
+            # may have acquired concurrently. The atomic compare-and-
+            # delete release below is a safe no-op in that case (it won't
+            # delete the new holder's key), but mutual exclusion was NOT
+            # guaranteed for the overrun window — warn loudly so the
+            # operator can raise `ttl:` or confirm the body is idempotent.
+            held = Parse::LockBackend.monotonic_now - acquired_at
+            if held > normalized_ttl
+              warn "[Parse::Lock] critical section for #{key.inspect} ran " \
+                   "#{held.round(2)}s, exceeding ttl: #{normalized_ttl}s — the lease " \
+                   "expired mid-block and another caller may have held the lock " \
+                   "concurrently. Mutual exclusion was NOT guaranteed for the overrun " \
+                   "window. Raise ttl: above your worst-case section duration, or make " \
+                   "the protected operation idempotent."
+            end
+            Parse::LockBackend.release(store, store_key, owner)
+          end
+        end
+      end
+
+      # @!visibility private
+      # Reset internal state — intended for test teardown.
+      def reset!
+        Parse::LockBackend.reset!
+      end
+
+      private
+
+      VALID_ON_DEGRADED = %i[warn warn_throttled proceed raise].freeze
+
+      def validate_on_degraded!(value)
+        return if VALID_ON_DEGRADED.include?(value)
+        raise ArgumentError,
+              "Parse::Lock.acquire: on_degraded must be one of " \
+              "#{VALID_ON_DEGRADED.inspect} (got #{value.inspect}). " \
+              "Refusing to silently fall back to :warn on an unknown safety knob — " \
+              "a typo like :riase would otherwise become silent-warn and mask intent."
+      end
+
+      def validate_secret!(value)
+        return if value == :auto || value.nil?
+        unless value.is_a?(String) && !value.empty?
+          raise ArgumentError,
+                "Parse::Lock.acquire: secret must be :auto (use the backend's " \
+                "resolution), nil (opt out to plain SHA-256), or a non-empty String " \
+                "(explicit HMAC key) — got #{value.inspect}."
+        end
+        if value.bytesize < SECRET_MIN_BYTES
+          raise ArgumentError,
+                "Parse::Lock.acquire: explicit `secret:` must be at least " \
+                "#{SECRET_MIN_BYTES} bytes (got #{value.bytesize}). A short HMAC " \
+                "key reduces the separation between tenants sharing one Redis and " \
+                "defeats the lock-pinning resistance the HMAC keying is supposed to " \
+                "provide. Use SecureRandom.hex(32) or a real operator secret."
+        end
+      end
+
+      def validate_key!(key)
+        unless key.is_a?(String) && !key.empty?
+          raise ArgumentError,
+                "Parse::Lock.acquire: key must be a non-empty String (got #{key.class})"
+        end
+        if key.bytesize > 1024
+          raise ArgumentError,
+                "Parse::Lock.acquire: key exceeds 1024 bytes (got #{key.bytesize}). " \
+                "Hash the inputs to a stable digest before passing them in."
+        end
+        key
+      end
+
+      def clamp(value, lo, hi)
+        [lo, value, hi].sort[1]
+      end
+    end
+  end
+end