feat: Add LiveQuery query operation

[Corvus400]

Issue

Closes #9086 and resumes #9864.

Approach

This adds one socket request for saved live query rows.

The server uses saved auth and selected fields.

Missing client or query data returns a clear error.

Tasks

Schema, server path, result messages, and tests are done.

Checks

Specs, lint, and build passed.

/claim #9086

Summary by CodeRabbit

• New Features
  • Added websocket query operation to fetch live-subscription results on demand.
  • Supports subscription where constraints (defaults to {}), optional field filtering via keys, and includes installationId, clientId, requestId, and results in responses.
• Bug Fixes
  • Improved handling for missing/unknown clients and subscriptions, and for query failures; ensures consistent error/result behavior.
• Tests
  • Expanded Jasmine coverage for query routing, session-token propagation, field/where filtering, empty-result publishing, and error paths.

[parse-github-assistant]

I will reformat the title to use the proper commit message syntax.

[parse-github-assistant]

🚀 Thanks for opening this pull request! We appreciate your effort in improving the project. Please let us know once your pull request is ready for review.

Tip

• Keep pull requests small. Large PRs will be rejected. Break complex features into smaller, incremental PRs.
• Use Test Driven Development. Write failing tests before implementing functionality. Ensure tests pass.
• Group code into logical blocks. Add a short comment before each block to explain its purpose.
• We offer conceptual guidance. Coding is up to you. PRs must be merge-ready for human review.
• Our review focuses on concept, not quality. PRs with code issues will be rejected. Use an AI agent.
• Human review time is precious. Avoid review ping-pong. Inspect and test your AI-generated code.

Note

Please respond to review comments from AI agents just like you would to comments from a human reviewer. Let the reviewer resolve their own comments, unless they have reviewed and accepted your commit, or agreed with your explanation for why the feedback was incorrect.

Caution

Pull requests must be written using an AI agent with human supervision. Pull requests written entirely by a human will likely be rejected, because of lower code quality, higher review effort and the higher risk of introducing bugs. Please note that AI review comments on this pull request alone do not satisfy this requirement. Our CI and AI review are safeguards, not development tools. If many issues are flagged, rethink your development approach. Invest more effort in planning and design rather than using review cycles to fix low-quality code.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6eb27007-b193-4e03-bf56-4f6ce7010dc1

📥 Commits

Reviewing files that changed from the base of the PR and between 22c066a and 86c7a17.

📒 Files selected for processing (1)

• spec/ParseLiveQueryQuery.spec.js

---

📝 Walkthrough

Walkthrough

Adds LiveQuery WebSocket query support: schema validation, server-side execution from stored subscriptions, client-side result publishing, and tests for success and error paths.

Changes

Live Query Query Operation

Layer / File(s)	Summary
Query Operation Schema Definition src/LiveQuery/RequestSchema.js	The request schema supports op: 'query' with numeric requestId and disallows additional properties.
Client Result Publishing src/LiveQuery/Client.js, spec/Client.spec.js	Client.pushResult publishes result messages with subscription metadata, selected fields, and empty-result handling; tests cover these payloads.
Server Query Execution and Dispatch src/LiveQuery/ParseLiveQueryServer.ts, spec/ParseLiveQueryQuery.spec.js	The server dispatches query frames, validates client and subscription state, executes stored query constraints with authentication and field selection, and returns results or errors; tests cover the related paths.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant WebSocketClient
  participant ParseLiveQueryServer
  participant ParseQuery
  participant Client

  WebSocketClient->>ParseLiveQueryServer: query request with requestId
  ParseLiveQueryServer->>ParseLiveQueryServer: validate client and subscription
  ParseLiveQueryServer->>ParseQuery: apply where and select
  ParseQuery->>ParseQuery: find with sessionToken or useMasterKey
  ParseQuery-->>ParseLiveQueryServer: query results
  ParseLiveQueryServer->>Client: pushResult subscription results
  Client-->>WebSocketClient: result message

Loading

---

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Engage In Review Feedback	❓ Inconclusive	Iterative follow-up commits exist, but the repo has no review-thread evidence; I can't verify any comment discussion or retraction.	Provide PR review comments or discussion logs showing the feedback was discussed and either implemented or explicitly retracted.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title uses the required feat: prefix and accurately summarizes LiveQuery query support.
Description check	✅ Passed	The PR description includes the required Issue, Approach, and Tasks sections with relevant details.
Linked Issues check	✅ Passed	The changes implement LiveQuery query execution, result delivery, and error handling requested in #9086.
Out of Scope Changes check	✅ Passed	All listed changes support LiveQuery query support, and no unrelated functionality appears added.
Security Check	✅ Passed	PASS: The new query path is bound to an existing client subscription and reuses server-side auth/query state; I found no new unsanitized input or auth-bypass pattern.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Corvus400]

This is ready for review.

This PR resumes #9864.

It keeps the server change focused.

The JS SDK side appears released in parse-community/Parse-SDK-JS#2114.

Local checks passed.

See the PR body for the commands.

[Corvus400]

Maintainers, could you approve the pending workflows for this fork PR?

The latest ci and ci-performance pull_request runs for head 1bd62e9265bc7b5a511a7fb9290faded21135761 are stuck with conclusion action_required and no jobs created:

• ci: https://github.com/parse-community/parse-server/actions/runs/26719259474
• ci-performance: https://github.com/parse-community/parse-server/actions/runs/26719259482

I also see the Snyk status failing with You have used your limit of private tests, which appears to be an org-side status rather than a change failure.

The branch is currently behind alpha; I can update it if you prefer.

[mtrezza]

CI started

[Corvus400]

Maintainers, could you approve the pending workflows for the updated fork PR?

I pushed d2d0a58 to address the LiveQuery query CI failures. The new pull_request runs for head d2d0a58 are stuck with conclusion action_required and no jobs created:

• ci: https://github.com/parse-community/parse-server/actions/runs/28987859283
• ci-performance: https://github.com/parse-community/parse-server/actions/runs/28987859280

Local verification passed:

• npm run test -- spec/ParseLiveQueryQuery.spec.js
• npm run test -- spec/Client.spec.js spec/ParseLiveQueryQuery.spec.js
• npm run lint
• npm run build
• npm run coverage:mongodb (4418 specs, 0 failures, 97 pending)

[codecov]

Codecov Report

❌ Patch coverage is 67.92453% with 17 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.59%. Comparing base (2625489) to head (d2d0a58).
⚠️ Report is 1 commits behind head on alpha.

Files with missing lines	Patch %	Lines
src/LiveQuery/ParseLiveQueryServer.ts	61.36%	15 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##            alpha   #10470      +/-   ##
==========================================
- Coverage   92.68%   92.59%   -0.09%     
==========================================
  Files         193      193              
  Lines       16986    17039      +53     
  Branches      248      257       +9     
==========================================
+ Hits        15743    15777      +34     
- Misses       1222     1239      +17     
- Partials       21       23       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

🧹 Nitpick comments (1)

spec/ParseLiveQueryQuery.spec.js (1)

218-240: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick win

Consider adding a test for the useMasterKey fallback path.

The implementation in _handleQuery has an else if (client.hasMasterKey) branch that sets findOptions.useMasterKey = true when no session token is available. Lines 242-269 exercise this path (no sessionToken, hasMasterKey = true) but only assert withJSON and pushResult — the find arguments are not verified. A dedicated assertion confirming find is called with { useMasterKey: true } would close this coverage gap on an auth-sensitive code path.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@spec/ParseLiveQueryQuery.spec.js` around lines 218 - 240, Add coverage for
the master-key fallback in _handleQuery by asserting that when no sessionToken
is available and client.hasMasterKey is true, Parse.Query.prototype.find is
called with { useMasterKey: true }, alongside the existing withJSON and
pushResult assertions.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@spec/ParseLiveQueryQuery.spec.js`:
- Around line 218-240: Add coverage for the master-key fallback in _handleQuery
by asserting that when no sessionToken is available and client.hasMasterKey is
true, Parse.Query.prototype.find is called with { useMasterKey: true },
alongside the existing withJSON and pushResult assertions.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ccad89d9-1f4c-4d10-9299-2e2e0cba3e53

📥 Commits

Reviewing files that changed from the base of the PR and between d2d0a58 and 22c066a.

📒 Files selected for processing (1)

• spec/ParseLiveQueryQuery.spec.js