parse-stack-next 5.2.1 → 5.4.0

data/docs/mongodb_direct_guide.md

@@ -173,6 +173,58 @@ set the same kwargs on the query for chainable composition.
 Related: `first_direct(n)` for the first N rows, `count_direct` for a
 count-only query. Both accept the same auth kwargs.
 
+#### Field projection: `keys` and `exclude_keys`
+
+The two field-selection options behave differently on the direct path
+because MongoDB's `$project` is an allowlist, not a denylist:
+
+- **`keys` (allowlist)** compiles to a `$project` stage in the direct
+  pipeline, so the projection runs server-side in MongoDB — only the
+  named fields (plus the reserved envelope: `_id`, `_created_at`,
+  `_updated_at`, `_acl`) leave the database.
+
+- **`exclude_keys` (denylist)** has no `$project` equivalent, so Parse
+  Stack honors it as a **post-fetch sanitize**: the pipeline is
+  unchanged, and the SDK recursively strips every key with a matching
+  name from the decoded results in Ruby. The fields still travel from
+  MongoDB to the client — this is a result-shaping convenience, not a
+  data-minimization or access-control boundary.
+
+```ruby
+# Allowlist — projected server-side via $project
+Song.query.keys(:title, :artist).results_direct
+
+# Denylist — stripped client-side after fetch
+Song.query.exclude_keys(:internal_notes).results_direct
+```
+
+Two consequences specific to the direct path:
+
+1. **Recursive by name.** `exclude_keys(:name)` removes `name` at every
+   depth, including inside included/nested objects — so a query that
+   includes a pointer also strips the pointed-to object's `name`. This
+   is broader than Parse Server's REST `excludeKeys`, which is
+   path-scoped (top-level or dotted) and would leave the nested field
+   intact. The same query can therefore return different shapes on the
+   REST and direct paths.
+
+2. **Reserved fields are never stripped.** `objectId`, `className`,
+   `__type`, `createdAt`, `updatedAt`, `ACL`, and their Mongo
+   storage-form names (`_id`, `_created_at`, `_updated_at`, `_acl`) are
+   always retained, so excluding one of them is a no-op rather than a
+   way to break object reconstruction.
+
+The sanitize applies to the object/decoded result paths
+(`results_direct`, `first_direct`, and the auto-promoted
+`$inQuery`/`$notInQuery` aggregation). The raw aggregation accessor
+(`aggregate(...).raw`) returns documents untouched.
+
+Because `exclude_keys` here is a projection convenience and not an
+ACL/CLP/`protectedFields` boundary, the security contract in
+[Security](#security) is unaffected — to keep a field from leaving the
+database, use `keys` (allowlist) or `protectedFields`, not
+`exclude_keys`.
+
 ### `Query#aggregate(pipeline, mongo_direct: true)`
 
 ```ruby
@@ -233,9 +285,35 @@ raw = Parse::MongoDB.find(
 ```
 
 Convenience wrapper around `db.find`. Accepts `limit:`, `skip:`, `sort:`,
-`projection:`, `max_time_ms:`. When `:limit` is omitted the call applies
+`projection:`, `hint:`, `max_time_ms:`. When `:limit` is omitted the call applies
 `DEFAULT_FIND_LIMIT = 1000` and warns; pass `limit: 0` to opt out.
 
+### Forcing an index with `hint`
+
+When the query planner picks a sub-optimal index on a large collection,
+`Query#hint` forces a specific one. It applies on **both** paths — the REST body
+(`hint` parameter, Parse Server 7.4.0+) and the mongo-direct path — so a plan you
+diagnosed with `Query#explain` can be corrected without dropping to `mongosh`.
+
+```ruby
+# Diagnose, then force the index, on the mongo-direct path:
+Post.query(:status => "published").order(:created_at.desc).hint("status_1_created_at_-1")
+    .results_direct
+
+# A key pattern works too:
+Post.query(:status => "published").hint({ "status" => 1, "createdAt" => -1 }).count_direct
+```
+
+On the mongo-direct path the hint is forwarded to the driver as the Mongo `hint`
+option: `results_direct` / `count_direct` / `distinct_direct` pass it to
+`Parse::MongoDB.aggregate` (`hint:` → the aggregation `hint` option), and the
+primitives `Parse::MongoDB.aggregate(..., hint:)` and
+`Parse::MongoDB.find(..., hint:)` accept it directly. The index name (a `String`)
+or a key pattern (`Hash`) are both accepted; an unknown index name is rejected by
+MongoDB, which is the intended fail-fast signal that the hint is stale.
+
+`hint` is unset by default (the planner chooses); it is purely an override.
+
 ### Geo queries
 
 Three geo query constraints land in v4.4.0 alongside a direct
@@ -620,6 +698,20 @@ ACL/CLP enforcement if the SDK applies it.
 As of **v4.4.0**, the SDK applies that enforcement on the mongo-direct
 path when the caller supplies a scope. Five layers compose:
 
+> **Atlas index entry points share this enforcement.** The Atlas-index
+> stages (`$vectorSearch`, `$search`, `$rankFusion`) must be stage 0 of
+> their pipeline, so they cannot route through `Parse::MongoDB.aggregate`
+> (which prepends an ACL `$match` at stage 0). `Parse::VectorSearch.search`
+> (`find_similar`), `Parse::AtlasSearch.search`, and
+> `Parse::VectorSearch::Hybrid` (`Class.hybrid_search`, v5.4.0) therefore
+> reproduce the same enforcement chain **inline** — the ACL `_rperm`
+> `$match` is appended AFTER the index stage, and CLP / `protectedFields` /
+> the internal-fields denylist run post-fetch — so the same scope kwargs
+> (`session_token:` / `acl_user:` / `acl_role:` / `master:`) and the same
+> contract apply. Hybrid search fuses two independently-enforced branches,
+> so fused rows are already access-filtered. `$rankFusion` was added to the
+> strict-mode allowlist (Layer 1) in v5.4.0 for the opt-in native path.
+
 ### Layer 1: Pipeline-security denylist (always on)
 
 `Parse::PipelineSecurity` refuses dangerous operators at any depth in

data/docs/usage_guide.md

@@ -83,10 +83,20 @@ Song.query.order(:plays.desc).skip(10).limit(20).results
 # Include related objects
 Song.all(includes: [:album, :comments])
 
-# Select specific fields
+# Select specific fields (allowlist)
 Song.all(keys: [:title, :artist])
+
+# Omit specific fields (denylist)
+Song.query.exclude_keys(:internal_notes).results
 ```
 
+> On the mongo-direct read path, `keys` is projected server-side while
+> `exclude_keys` is applied as a recursive post-fetch sanitize (it strips
+> matching field names at every depth and never removes reserved fields
+> such as `objectId`). See the
+> [Direct MongoDB Integration Guide](mongodb_direct_guide.md) for the
+> exact semantics and how it differs from the REST path.
+
 ## Aggregation
 
 ```ruby

data/docs/webhooks_guide.md

@@ -0,0 +1,418 @@
+# Cloud Code Webhooks Guide
+
+Webhooks are how `parse-stack-next` runs **server-side** trigger logic. They are
+the bridge between Parse Server and your Ruby code: Parse Server calls back into
+a Ruby Rack app on a matching trigger, and your model's ActiveModel callbacks
+(and any webhook blocks) run there.
+
+This is a server-side-only concern. A pure client (or a server with no
+registered webhooks) runs all of its trigger logic locally in ActiveModel and
+nothing inside Parse Server.
+
+## Why register a webhook at all
+
+A `Parse::Object`'s ActiveModel callbacks run in the process that initiates the
+save:
+
+- A **Ruby-initiated** save (this SDK) runs `before_save`, `after_create`, etc.
+  locally, before/after the REST call.
+- A save from a **non-Ruby client** — the JS/Swift SDKs, a raw REST call, or the
+  Parse Dashboard — never touches your Ruby process. That trigger logic is
+  simply skipped server-side.
+
+Registering a webhook closes that gap. Once Parse Server has a `beforeSave`
+webhook for a class, it calls your Ruby app on every save from every client, and
+your callbacks run server-side for all of them.
+
+**The rule:** your ActiveModel logic applies to non-Ruby clients **only if the
+webhook is registered.**
+
+## ActiveModel hooks vs Parse Server triggers
+
+The SDK exposes the full ActiveModel lifecycle on every `Parse::Object`. Parse
+Server, separately, exposes a fixed set of webhook trigger types. They are not
+one-to-one — the SDK maps between them.
+
+### ActiveModel callbacks (Ruby side)
+
+| Callback | Fires |
+|----------|-------|
+| `before_validation` / `after_validation` | around local validation |
+| `before_save` / `after_save` | around every save (create **and** update) |
+| `before_create` / `after_create` | around the first save of a new object |
+| `before_update` / `after_update` | around saves of an existing object |
+| `before_destroy` / `after_destroy` | around delete |
+
+### Parse Server webhook trigger types (server side)
+
+| Trigger | className | Notes |
+|---------|-----------|-------|
+| `beforeSave` / `afterSave` | a class | create **and** update |
+| `beforeDelete` / `afterDelete` | a class | |
+| `beforeFind` / `afterFind` | a class | |
+| `beforeLogin` / `afterLogin` | `_User` | login-side hooks |
+| `afterLogout` | `_Session` | |
+| `beforePasswordResetRequest` | `_User` | |
+| `beforeSave` / `afterSave` / `beforeDelete` / `beforeFind` / `afterFind` | `@File` | file triggers |
+| `beforeConnect` | `@Connect` | LiveQuery connection (connection-global) |
+| `beforeSubscribe` / `afterEvent` | a class | LiveQuery subscription / events |
+
+### How they relate
+
+- **`beforeSave` / `afterSave` carry the create variants.** Parse Server has **no
+  `beforeCreate` / `afterCreate` trigger** — it rejects them. The SDK runs your
+  `before_create` / `after_create` callbacks *inside* the `beforeSave` /
+  `afterSave` handler, gated on whether the object is new. So **registering a
+  `beforeSave` webhook enables both `before_save` and `before_create`**;
+  registering `afterSave` enables both `after_save` and `after_create`.
+
+  Asking for a create webhook fails fast with guidance:
+
+  ```ruby
+  Post.webhook(:after_create) { … }
+  # ArgumentError: There is no after_create webhook. Register `webhook :after_save`
+  # instead — your after_create ActiveModel callbacks run inside the after_save
+  # handler for new objects (registering after_save enables BOTH the after_save
+  # and after_create callbacks).
+  ```
+
+- **Trigger order is honored.** Within the save handler the SDK runs callbacks in
+  ActiveModel order: `before_save` then `before_create` on the way in,
+  `after_create` then `after_save` on the way out.
+
+- **`@File` and `@Connect` are pseudo-classes.** File triggers register against
+  the `@File` className; the connection-global LiveQuery trigger uses `@Connect`.
+  The SDK accepts both for the full register/fetch/delete lifecycle.
+
+- **`beforeFind` / `afterFind` are result-side, not object-side.** Unlike the
+  save/delete triggers, a find payload carries no single `object` — `beforeFind`
+  exposes the incoming `query` (via `payload.query`) and `afterFind` exposes the
+  matched rows (via `payload.objects`). And unlike `afterSave` (whose return
+  value Parse Server ignores), **`afterFind` is result-rewriting**: whatever the
+  handler returns *replaces* the rows sent to the client, so it can filter or
+  redact results. It also adds a webhook round-trip to every matching query, so
+  register it deliberately.
+
+  One non-obvious detail the SDK handles for you: **Parse Server does not put the
+  class name anywhere in the find payload body** — the matched objects omit
+  `className` and there is no top-level one. The SDK derives the class from the
+  webhook URL path (`<endpoint>/<trigger>/<className>`) so your `afterFind` /
+  `beforeFind` block routes correctly and `payload.parse_class` resolves. (If you
+  build a `Payload` yourself in a test, pass the class as the second argument:
+  `Parse::Webhooks::Payload.new(body, "MyClass")`.)
+
+  Because the class is resolved from the route, declared `:vector` columns are
+  stripped from `afterFind` `payload.objects` by default, exactly as they are
+  from `object`/`original`/`update` on the other triggers (a
+  `vector_visibility :public` class keeps them). One consequence to keep in
+  mind: an `afterFind` handler that returns `payload.objects` to pass results
+  through passes the *vector-scrubbed* rows on to the client — which matches the
+  `as_json` default (an `owner_only` class never exposes vectors anyway). Return
+  your own array if you need different columns.
+
+- **Auth triggers (`beforeLogin` / `afterLogin` / `afterLogout` /
+  `beforePasswordResetRequest`) and LiveQuery triggers (`beforeConnect` /
+  `beforeSubscribe` / `afterEvent`) are routed as first-class shapes** — they
+  are not object save/delete triggers, so **none of them run ActiveModel
+  `save` / `create` / `destroy` callbacks**, even the login/logout/reset ones
+  that carry a `_User` or `_Session`.
+
+  Identify them with the matching predicates — `before_login?`, `after_login?`,
+  `after_logout?`, `before_password_reset_request?`, `before_connect?`,
+  `before_subscribe?`, `after_event?` — or the category helpers `auth_trigger?`
+  / `live_query_trigger?`. Useful accessors by shape:
+
+  | Trigger | what the payload carries |
+  |---------|--------------------------|
+  | `beforeLogin` | the user being authenticated as **`payload.parse_object`** (a `_User`). `payload.user` is **`nil`** — auth isn't complete yet. |
+  | `afterLogin` | both `payload.parse_object` and `payload.user` (the now-authenticated user). |
+  | `afterLogout` | the session as `payload.parse_object` (a `_Session`). |
+  | `beforePasswordResetRequest` | the target user as `payload.parse_object`. |
+  | `beforeConnect` | connection-global: no object; the caller token (if any) in `payload.session_token`; counts in `payload.clients` / `payload.subscriptions`. |
+  | `beforeSubscribe` | shaped like `beforeFind` — `payload.query` / `payload.parse_query`; className comes from the route. Caller token in `payload.session_token`. |
+  | `afterEvent` | the event type in `payload.event` (`create` / `enter` / `update` / `leave` / `delete`), plus `payload.object` / `payload.original`. |
+
+  > The login footgun: during `beforeLogin` reach for `payload.parse_object`,
+  > **not** `payload.user` (which is `nil`). For connect/subscribe the live
+  > session token is at the top level of the payload, not nested under a user —
+  > the SDK captures it into `payload.session_token` (so `payload.user_client` /
+  > `payload.user_agent` work) and keeps it out of `as_json` and the request log.
+
+  **Response contract — what you return matters only for the `before*` ones.**
+  Parse Server **ignores the response body for all seven** of these triggers
+  (its webhook response handler resolves `{}` regardless). The *only* way a
+  handler affects the operation is by **rejecting** it, and only the `before*`
+  variants can be rejected (an `after*` trigger fires after the fact):
+
+  ```ruby
+  Parse::Webhooks.route(:before_login, "_User") do |payload|
+    error!("account suspended") if payload.parse_object.suspended?  # denies login
+    # returning false also denies (mapped to the error response); anything else
+    # — including the user object — succeeds as a no-op
+  end
+
+  Parse::Webhooks.route(:after_event, "Post") do |payload|
+    AuditLog.record(payload.event, payload.parse_id)  # observe-only; return value ignored
+  end
+  ```
+
+  Note the asymmetry with `before_save`: Parse Server treats a `{success:false}`
+  body as **allow** (only an `{error}` body rejects). So "return `false` to deny
+  login" only works because the SDK converts that `false` into an error response
+  for you. `error!(message)` is the explicit, message-carrying form.
+
+  **LiveQuery delivery caveat.** `beforeConnect` / `beforeSubscribe` /
+  `afterEvent` fire inside the LiveQuery server. They are delivered to an HTTP
+  webhook **only in a co-located, single-process LiveQuery setup**; with a
+  separate LiveQuery server they are in-process (`Parse.Cloud`) only.
+  `beforeConnect` in particular carries a live client handle that does not
+  serialize over HTTP, so it is effectively in-process-only. Register them when
+  you know your topology supports it.
+
+## Defining and registering webhooks
+
+```ruby
+Parse::Webhooks.key = ENV.fetch("PARSE_WEBHOOK_KEY") # matches Parse Server's webhookKey
+
+class Post < Parse::Object
+  property :title, :string
+
+  before_save  :normalize           # runs server-side once beforeSave is registered
+  after_create :index_for_search    # runs inside the afterSave handler for new posts
+
+  webhook :before_save do           # optional block, in addition to callbacks
+    parse_object                    # return the object (or `false` to halt the save)
+  end
+end
+```
+
+Register with Parse Server (once, at deploy — requires the master key).
+`endpoint` is the public HTTPS URL where the Rack app is reachable:
+
+```ruby
+Parse::Webhooks.register_functions!("https://hooks.example.com/webhooks")
+Parse::Webhooks.register_triggers!("https://hooks.example.com/webhooks")
+```
+
+Mount the Rack app (`config.ru`):
+
+```ruby
+require_relative "app/webhooks"
+run Parse::Webhooks
+```
+
+See [`examples/webhook_server.rb`](../examples/webhook_server.rb) for a complete,
+runnable setup.
+
+## Auditing trigger coverage
+
+The wiring above has three independent moving parts, and a callback runs
+server-side only when all three line up:
+
+1. the model's **ActiveModel callback** (`after_save :send_email`),
+2. a **local webhook route** so the router has a handler to run (the
+   `webhook :after_save` block, or `Parse::Webhooks.route(:after_save, "Post")`),
+3. the **server trigger** registered with Parse Server (`register_triggers!`),
+   so Parse Server actually POSTs to your app.
+
+Declaring the callback alone does nothing for a non-Ruby client — the save
+never touches your Ruby process. It is easy for these three to drift: a new
+`after_save` callback with no block, a `webhook` block you never registered, or
+a stale server trigger pointing at a class whose block was removed.
+
+`Parse::Webhooks.trigger_audit` cross-references all three across every
+registered class and reports the gaps. The server comparison reads the
+master-key-only `hooks/triggers` endpoint, so it needs a master-key client;
+pass `network: false` to audit callbacks against local routes only.
+
+```ruby
+puts Parse::Webhooks.trigger_audit(pretty: true)        # human-readable summary
+report = Parse::Webhooks.trigger_audit                  # Hash report
+Parse::Webhooks.trigger_audit(network: false)           # local-only, no master key
+```
+
+The audit emits four kinds of findings:
+
+- **`callbacks_inert`** — a model has callbacks mapping to a trigger
+  (`after_save` / `after_create` → `afterSave`, etc.) but the local block and/or
+  the server trigger is missing, so they never fire for non-Ruby clients. The
+  `missing:` list says which piece to add. This is the headline gap.
+- **`route_not_registered`** — a local `webhook :X` block exists but the trigger
+  isn't on the server, so Parse Server never calls it. Fix by running
+  `register_triggers!`.
+- **`orphan_server_trigger`** — a server trigger is registered but no local block
+  handles it; every matching operation pays a webhook round-trip that does
+  nothing.
+- **`local_only_callbacks`** — informational: `before_update` / `after_update`
+  and `before_validation` / `after_validation` callbacks have **no** Parse Server
+  trigger that can run them (the webhook router runs only the save and create
+  chains). They fire for Ruby-initiated saves but never for non-Ruby clients,
+  and no registration changes that.
+
+Wire it into CI or a deploy check to fail fast on a coverage gap:
+
+```ruby
+inert = Parse::Webhooks.trigger_audit[:summary][:findings][:callbacks_inert].to_i
+abort "Webhook coverage gaps detected" if inert.positive?
+```
+
+## Returning a value from a handler
+
+A handler block runs with `self` bound to the `Parse::Webhooks::Payload`, so
+inside it you can call `parse_object`, `params`, `error!`, etc. directly. The
+value the handler produces is what Parse Server receives: for `before_save`,
+return the (possibly mutated) `parse_object` to allow the write, or `false` /
+`error!` to reject it.
+
+You can set that value either with an explicit `return` or by letting it be the
+block's last expression — both work:
+
+```ruby
+Parse::Webhooks.route :before_save, :Post do
+  post = parse_object
+
+  return post if post.title.present?   # explicit early return
+  error! "title is required"           # raise to reject the save
+end
+
+# Equivalent, using the last-expression value:
+Parse::Webhooks.route :before_save, :Post do
+  post = parse_object
+  post.title.present? ? post : error!("title is required")
+end
+```
+
+The legacy proc idioms remain valid too — `next value` and `break value` both
+set the result. `return`, like anywhere in Ruby, ends the handler immediately,
+so nothing written after it in the same block runs. To run work *after* the
+response, use [`after_response`](#deferring-work-until-after-the-response)
+rather than writing code after the `return`.
+
+## Deferring work until after the response
+
+`payload.after_response { … }` (alias `defer`) registers a block to run **after**
+the webhook response has been sent to Parse Server — off the critical path of the
+save or function the client is waiting on. The handler still returns its value
+synchronously (that value is the response Parse Server acts on); the deferred
+block runs afterward. Use it for follow-up work that should not add latency:
+search indexing, cache warming, fan-out notifications.
+
+```ruby
+Parse::Webhooks.route :after_save, :Post do
+  post = parse_object
+  after_response { SearchIndex.reindex(post.id) }   # runs after the reply is sent
+  post
+end
+```
+
+How it runs:
+
+- **Under Puma or Unicorn** the block is enqueued on `rack.after_reply` and runs
+  once the response is flushed to the socket, on the same worker thread — so it
+  adds nothing to the client's round-trip.
+- **On a server without `rack.after_reply`** (e.g. WEBrick) it falls back to a
+  detached thread per request with deferred work — there is no pool or cap, so
+  under high request volume those threads can accumulate. Run the webhook app
+  under **Puma or Unicorn in production** (both provide `rack.after_reply`, which
+  runs the work on the existing worker thread with no extra thread spawned); the
+  thread fallback is best treated as a development-server convenience.
+- Multiple `after_response` blocks run in registration order, and each is
+  isolated — one raising affects neither the response nor the others.
+- `self` inside the block is the payload, so `parse_object`, `params`, etc. are
+  available (it closes over the handler's scope).
+
+Things to know before relying on it:
+
+- **Success path only.** Deferred blocks run only when the handler produced a
+  successful response. If a `before_save` rejects the write (`error!`, a raise,
+  or returning `false`), its registered `after_response` blocks do **not** run.
+- **"After the response" is not "after the row commits."** The block runs after
+  the *response* is flushed. For `before_save` that is before Parse Server has
+  committed the write; even for `after_save` the SDK does not guarantee commit
+  ordering relative to the deferred block. Do not rely on the persisted row being
+  readable inside it.
+- **In-process and best-effort.** The work runs in the web worker and does not
+  survive a restart, crash, or deploy. For work that *must* happen — payment
+  capture, irreversible side effects — hand it to a durable job queue
+  (Sidekiq / ActiveJob) instead; `after_response` is for latency-shedding, not
+  durability.
+- **Mounted-app only.** Deferred blocks are drained by the `Parse::Webhooks` Rack
+  app. Invoking a handler directly (`Parse::Webhooks.run_function`, or calling
+  `call_route` in a unit test) does not run them — `after_response` is a no-op
+  there.
+- **Capturing `user_client` / `user_agent` extends the token's lifetime.** A
+  deferred block closes over the payload, so referencing `payload.user_client` /
+  `payload.user_agent` (or `payload.session_token`) keeps the caller's live
+  session token in memory until the block finishes — beyond the synchronous
+  request. That is fine and expected when the deferred work needs to act as the
+  caller; just don't capture them when the work doesn't need the user's
+  authority (use a master-key client instead), so the token isn't pinned longer
+  than necessary.
+
+## Latency: webhooks are synchronous
+
+Every registered webhook adds a **separate, synchronous HTTP round-trip** to the
+client's operation. Parse Server **waits for the webhook to return before
+proceeding** — and it waits even on `afterSave`, despite the afterSave return
+value being a no-op.
+
+This has direct design consequences for `afterSave` (and `afterDelete`):
+
+- **Enqueue, don't execute.** Treat `after_save` as a place to hand work to a
+  background job, not to do long-running logic inline. Anything slow here is
+  added latency on every save, for every client. For in-process follow-up that
+  doesn't need a durable queue, [`after_response`](#deferring-work-until-after-the-response)
+  moves it off the client's round-trip; for anything that *must* happen, use a
+  real job queue.
+- **Avoid saving other objects during an afterSave.** Each cascading save fires
+  its own webhooks, which can fire more — a latency cascade. If you must, do it
+  in a background job, not inline in the handler.
+
+`beforeSave` is necessarily inline (it can mutate or reject the write), so keep
+it lean and deterministic.
+
+## Server-side dedup: two distinct mechanisms
+
+Two different "dedup" systems protect webhook handling. They solve different
+problems — don't conflate them.
+
+### 1. Ruby-initiated dedup (keep logic local, prevent double-runs)
+
+When a save is initiated by **this SDK with the master key**, Parse Stack tags
+the request as trusted-Ruby-initiated (an `_RB_` request-id marker plus the
+master key). It has already run the model's `before_save` / `after_save` /
+`after_create` ActiveModel callbacks **locally**. The webhook therefore does
+**not** re-run those callbacks — that would double-fire side effects (e.g. an
+`after_save :send_email` would send two emails per save).
+
+The intent is to keep trigger logic local when possible and run it exactly once.
+Note that any logic in the **webhook block itself** still runs; only the
+duplicate ActiveModel callback pass is skipped. A spoofed `_RB_` marker without
+the master key does not get this treatment — the callbacks run in the webhook as
+usual.
+
+### 2. Server-initiated replay / freshness protection (inbound)
+
+This protects the webhook endpoint against **replayed inbound POSTs** —
+`lib/parse/webhooks/replay_protection.rb`:
+
+- **Always-on body + request-id dedup.** A bounded LRU records a digest of each
+  `(request_id, body)`; a duplicate seen within `replay_window_seconds` is
+  rejected with `"Webhook replay detected."`. No cooperation from Parse Server is
+  required; this stops in-window replays.
+- **Opt-in HMAC freshness verification.** Set a `signing_secret` and the receiver
+  verifies two headers:
+  - `X-Parse-Webhook-Timestamp` — Unix epoch seconds; requests outside
+    `signing_max_skew_seconds` (default 300) are rejected as stale.
+  - `X-Parse-Webhook-Signature` — hex HMAC-SHA256 of `"#{timestamp}.#{body}"`
+    keyed with the signing secret.
+
+```ruby
+Parse::Webhooks::ReplayProtection.signing_secret = ENV["PARSE_WEBHOOK_SIGNING_SECRET"]
+Parse::Webhooks::ReplayProtection.replay_window_seconds = 120
+Parse::Webhooks::ReplayProtection.signing_max_skew_seconds = 300
+```
+
+This is **inbound** protection and is unrelated to request **idempotency**
+(`X-Parse-Request-Id`), which dedups the SDK's own **outbound** retries on the
+Parse Server side. Different direction, different mechanism.

data/examples/README.md

@@ -0,0 +1,46 @@
+# Examples
+
+Runnable scripts that exercise `parse-stack-next` against a live Parse Server.
+Each file is self-contained and reads its configuration from environment
+variables. Start here:
+
+| Script | Demonstrates | Needs |
+|---|---|---|
+| [`basic_server.rb`](basic_server.rb) | Privileged (master-key) setup: define models, push schema with `auto_upgrade!`, full CRUD + queries with a `belongs_to`. | app id, REST key, **master key** |
+| [`basic_client.rb`](basic_client.rb) | Unprivileged client (no master key): login/signup, `with_session`, and a row-level **ACL enforcement** demo (the owner reads a record; an anonymous caller gets `nil`). | app id, REST key |
+| [`live_query_listener.rb`](live_query_listener.rb) | Interactive LiveQuery console: subscribes scoped to a user's session token and prints create / update / delete events until Ctrl-C — you only "hear" what that user may read. | app id, REST key, LiveQuery URL |
+| [`rag_chatbot.rb`](rag_chatbot.rb) | Retrieval-augmented generation: managed `embed`, `agent_searchable`, `semantic_search` via `Parse::Agent`, plus an OpenAI/Anthropic generation add-in. | app id, REST key, master key, `OPENAI_API_KEY` (+ Atlas) |
+| [`transaction_example.rb`](transaction_example.rb) | Atomic multi-object operations via `Parse::Object.transaction`. | app id, REST key |
+
+## Common setup
+
+All scripts read a Parse connection from the environment:
+
+```bash
+export PARSE_SERVER_URL=http://localhost:1337/parse
+export PARSE_APP_ID=your-app-id
+export PARSE_REST_KEY=your-rest-api-key
+export PARSE_MASTER_KEY=your-master-key   # server-side scripts only
+```
+
+Then run any script with the gem on the load path:
+
+```bash
+ruby -Ilib examples/basic_server.rb
+```
+
+## Suggested order
+
+1. **`basic_server.rb`** — defines and provisions the `Artist`, `Song`, and
+   `Post` classes the other scripts use. Run it first.
+2. **`basic_client.rb`** — see how the same SDK behaves without the master key,
+   and watch Parse Server enforce a row-level ACL.
+3. **`live_query_listener.rb`** — leave it running, then create/update/destroy
+   `Post`s from another terminal (or the dashboard) and watch them stream in.
+4. **`rag_chatbot.rb`** — requires an Atlas-backed server and an embedding key;
+   see [`../docs/atlas_vector_search_guide.md`](../docs/atlas_vector_search_guide.md)
+   for the vector-search setup.
+
+> Each script's header comment lists the exact environment variables and any
+> prerequisites (e.g. `basic_client.rb` needs the `Post` class to already
+> exist, which `basic_server.rb` provisions).