Add BRP watch_id and bevy/unwatch

[villor]

Objective

BRP supports watching requests by using the +watch-suffix. But it has some limitations:

• There is no way to differentiate one watcher from another, other than by using the client provided params. This makes it hard to deal with any needed state for ongoing watching requests, as well as detecting when a watcher is closed.
• Watching requests can not be closed/canceled manually, which can be problematic when using transports where multiple requests are communicated over a single connection (see Add WebSocket support for RemoteHttpPlugin #16403)

Solution

• Add a server owned watch_id (RemoteWatchingRequestId = u32) used to uniquely identify a specific watcher.
  • Not to be confused with the id field in JSON RPC 2.0, which is a client owned id that may or may not exist and might not be unique.
• Change the +watch-request handling to always send an initial response with the watch_id of that request.

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "watch_id": 1
  }
}

• Update the In-param for the watching request handlers to also include the watch_id.
• Add a bevy/unwatch-method which can be used to close a current watcher (or all watchers).

Testing

• Tested together with Add WebSocket support for RemoteHttpPlugin #16403.
  • ✅ +watch-requests now return their watch_id
  • ✅ bevy/unwatch works for both a specific watch_id, and for all watchers
• I have also used this approach while experimenting with bevy_remote_inspector, where I use the watch_id to detect closed watchers and perform cleanup in a separate system.

---

[alice-i-cecile]

LGTM, but if you have time swapping to a named struct to avoid the complex tuples would be nice.

[cBournhonesque]

Why are we providing the watch_id if they are not used anywhere in the watch systems?
In case they might be used in the future?

[villor]

The idea is to give watch handlers a way to identify which watcher it is handling, giving them a unique key for use with any needed state/cache that needs to be handled on watcher level, rather than method level.

As you’ve noticed it is not used by any of the built in methods, as they are not stateful. But I have encountered the need for watcher state while building some custom methods.

I’m not completely certain this is the best solution though. There are other ways. For example each watcher could have their own SystemState, allowing use of Local instead of managing state using ids and hash maps. Another benefit is cleanup would be automatic.

[cBournhonesque]

We might want to return an error if a watch_id is provided that doesn't exist

[villor]

Thanks! That makes sense.

[cBournhonesque]

We might want to return an error if a watch_id is provided that doesn't exist

[villor]

Since in-engine websocket transport might be off the table, this companion PR may seem unnecessary as well. However I believe this functionality is still useful, for any third-party stream-based transports, as well as a potential future binary TCP transport.

While trying to think about ways to solve the connection limit issue with SSE, I realized one way could be to re-design watchers a bit by using a single SSE endpoint as a stream for all watcher responses. This would ensure any number of watchers can be used even from a web browser.

With the above in mind, as well as the state stuff, I think we should hold off a bit on this PR and try to figure out a better watcher design in general.