feature: run query via livequery

[dblythy]

Pull Request

• Report security issues confidentially.
• Any contribution is under this license.
• Link this pull request to an issue.

Issue

Closes: #9086

Added LiveQuery query operation to execute queries through existing WebSocket subscriptions, eliminating separate REST API calls for data syncing.

Client SDK Changes Required:

• Add result event type to LiveQuery constants

• Handle result messages in WebSocket handler

• Add query() method to subscription class

• [x] Add tests

Summary by CodeRabbit

• New Features

  • LiveQuery adds an on-demand "query" operation: subscribers can request read results with where filtering and per-subscription field selection; responses honor session-based access and return matched records.

• Bug Fixes

  • Improved error handling and reporting for missing clients, missing subscriptions, and query execution failures.

• Tests

  • Added tests validating query handling, result payloads, field filtering, where constraints, delivery, and related error scenarios.

[parse-github-assistant[bot]]

🚀 Thanks for opening this pull request!

[coderabbitai[bot]]

📝 Walkthrough

Walkthrough

Adds a LiveQuery "query" operation: request schema, server handler to execute find queries and return results, client API to push query results, and tests validating result delivery, field selection, where constraints, and error paths.

Changes

Cohort / File(s)	Summary
Tests: ParseLiveQuery query suite spec/ParseLiveQueryQuery.spec.js	New Jasmine spec exercising LiveQuery query requests: success path with multiple objects, keys-based field filtering, where constraints, missing clientId/subscription error reporting, and helper mocks for clients/subscriptions.
LiveQuery Client: push result API src/LiveQuery/Client.js	Adds pushResult (bound to _pushQueryResult) that builds op: 'result' messages including clientId, installationId, and requestId; maps results through _toJSONWithFields using per-subscription keys and sends via pushResponse.
LiveQuery Server: query op handling src/LiveQuery/ParseLiveQueryServer.ts	Adds routing for op: 'query' and an async _handleQuery method: validates client and subscription, chooses auth (`subscription.sessionToken
Request Schema: query op src/LiveQuery/RequestSchema.js	Adds query operation schema and registers RequestSchema.query with op: 'query' and numeric requestId.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant SDK as LiveQuery Client SDK
  participant WS as WebSocket Server
  participant Srv as ParseLiveQueryServer
  participant Sub as Subscription Registry
  participant DB as Data Store

  rect rgba(230,240,255,0.35)
    note left of SDK: client sends a query tied to a subscriptionId
  end

  SDK->>WS: { op: "query", requestId, id: subscriptionId, where, keys }
  WS->>Srv: route "query" request
  Srv->>Sub: lookup subscription(subscriptionId)
  alt subscription found
    Srv->>Srv: resolve auth (subscription.sessionToken || client.sessionToken || master)
    Srv->>DB: find(className, where, keys)
    DB-->>Srv: results[]
    Srv->>WS: push { op: "result", requestId, clientId, installationId, results }
    WS-->>SDK: deliver "result"
  else subscription missing
    Srv->>WS: push error { op: "error", requestId, ... }
    WS-->>SDK: deliver error
  end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Verify authentication selection and fallback (subscription.sessionToken → client.sessionToken → master key) in src/LiveQuery/ParseLiveQueryServer.ts.
• Confirm _pushQueryResult in src/LiveQuery/Client.js applies per-subscription keys consistently with _toJSONWithFields.
• Inspect new tests in spec/ParseLiveQueryQuery.spec.js for proper mock setup/teardown and correctness of error-case assertions.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title "feature: run query via livequery" accurately and specifically describes the main change in this pull request. It clearly conveys that a new query feature is being added to LiveQuery functionality, which aligns directly with the substantial changes across the request schema, server handler, and client result-pushing mechanism. The title is concise, free of noise, and specific enough for developers scanning history to quickly understand the primary contribution.
Linked Issues Check	✅ Passed	The code changes successfully implement the primary server-side requirements from issue #9086. The implementation enables running queries through LiveQuery subscriptions, adds a new "query" request operation to the schema, implements the server-side handler (_handleQuery in ParseLiveQueryServer), and provides the mechanism for pushing results back to clients (pushResult in Client.js). The comprehensive test suite validates query handling with existing subscriptions, field filtering (keys), and where constraints. The implementation achieves the core objective of enabling initial data sync over WebSocket to eliminate separate REST API calls, and the test coverage confirms the functionality works correctly. Client SDK changes required for complete end-to-end functionality are acknowledged in the PR description as separate work items.
Out of Scope Changes Check	✅ Passed	All code changes in this pull request are directly aligned with the feature objective of adding query support to LiveQuery. The new test file (spec/ParseLiveQueryQuery.spec.js) validates the query feature implementation; the Client.js modifications (pushResult method) enable result delivery through subscriptions; the ParseLiveQueryServer.ts addition (_handleQuery method) implements core query request handling; and the RequestSchema.js changes define the query operation schema. No unrelated refactoring, cleanup, or out-of-scope modifications are present in the changeset.
Description Check	✅ Passed	The pull request description follows the required template structure with all critical sections populated: it includes the issue closure link (#9086), provides a brief but meaningful explanation of the approach (adding a query operation to execute queries through WebSocket subscriptions and eliminating REST API calls), and marks the "Add tests" task as complete. While the approach section is somewhat concise, it conveys the essential intent of the feature. The description also appropriately acknowledges that client SDK changes are required as separate work.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2a7ad486270d7e91b8700eda0698884228e3f6df and 466d789db2977bbc39d77c1587a5e27fd3f3cec8.

📒 Files selected for processing (1)

• spec/ParseLiveQueryQuery.spec.js (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• spec/ParseLiveQueryQuery.spec.js

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (13)

• GitHub Check: PostgreSQL 15, PostGIS 3.3
• GitHub Check: PostgreSQL 16, PostGIS 3.5
• GitHub Check: Redis Cache
• GitHub Check: PostgreSQL 18, PostGIS 3.6
• GitHub Check: PostgreSQL 15, PostGIS 3.5
• GitHub Check: PostgreSQL 17, PostGIS 3.5
• GitHub Check: Node 20
• GitHub Check: PostgreSQL 15, PostGIS 3.4
• GitHub Check: Node 18
• GitHub Check: MongoDB 8, ReplicaSet
• GitHub Check: MongoDB 6, ReplicaSet
• GitHub Check: MongoDB 7, ReplicaSet
• GitHub Check: Docker Build

---

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 and usage tips.}

[parseplatformorg]

:white_check_mark: Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
:white_check_mark:	Open Source Security	0	0	0	0	0 issues

:computer: Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[codecov[bot]]

Codecov Report

:x: Patch coverage is 56.60377% with 23 lines in your changes missing coverage. Please review. :white_check_mark: Project coverage is 84.42%. Comparing base (94cee5b) to head (80cd0ae). :warning: Report is 1 commits behind head on alpha.

Files with missing lines	Patch %	Lines
src/LiveQuery/ParseLiveQueryServer.ts	63.63%	15 Missing and 1 partial :warning:
src/LiveQuery/Client.js	12.50%	7 Missing :warning:

:exclamation: There is a different number of reports uploaded between BASE (94cee5b) and HEAD (80cd0ae). Click for more details.

HEAD has 10 uploads less than BASE

Flag	BASE (94cee5b)	HEAD (80cd0ae)
	13	3

Additional details and impacted files

@@            Coverage Diff             @@
##            alpha    #9864      +/-   ##
==========================================
- Coverage   93.08%   84.42%   -8.66%     
==========================================
  Files         187      187              
  Lines       15275    15328      +53     
  Branches      177      186       +9     
==========================================
- Hits        14219    12941    -1278     
- Misses       1044     2374    +1330     
- Partials       12       13       +1     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

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

[mtrezza]

@messagenius-admin pinging since you may want to take a look at the updates in this PR and provide feedback. @dblythy could you please comment on coderabbit review feedbacks rather than just closing them? Consider it a review like from any other human reviewer. If you make a commit to address a feedback, coderabbit should update and resolve the feedback itself.