feat(api): broadcast events to ALL channels #28487

Problem:
`vim.rpcnotify(0)` and `rpcnotify(0)` are documented as follows:

    If {channel} is 0, the event is broadcast to all channels.

But that's not actually true. Channels must call `nvim_subscribe` to
receive "broadcast" events, so it's actually "multicast".

- Assuming there is a use-case for "broadcast", the current model adds
  an extra step for broadcasting: all channels need to "subscribe".
- The presence of `nvim_subscribe` is a source of confusion for users,
  because its name implies something more generally useful than what it
  does.

Presumably the use-case of `nvim_subscribe` is to avoid "noise" on RPC
channels not expected a broadcast notification, and potentially an error
if the channel client reports an unknown event.

Solution:
- Deprecate `nvim_subscribe`/`nvim_unsubscribe`.
  - If applications want to multicast, they can keep their own multicast
    list. Or they can use `nvim_list_chans()` and `nvim_get_chan_info()`
    to enumerate and filter the clients they want to target.
- Always send "broadcast" events to ALL channels. Don't require channels
  to "subscribe" to receive broadcasts. This matches the documented
  behavior of `rpcnotify()`.

1 files changed, 5 insertions, 18 deletions

diff --git a/test/functional/api/server_notifications_spec.lua b/test/functional/api/server_notifications_spec.lua
index b8efbfbd0e..7b4c4e8312 100644
--- a/test/functional/api/server_notifications_spec.lua
+++ b/test/functional/api/server_notifications_spec.lua
@@ -1,7 +1,6 @@
 local t = require('test.testutil')
 local n = require('test.functional.testnvim')()
 
-local assert_log = t.assert_log
 local eq, clear, eval, command, next_msg = t.eq, n.clear, n.eval, n.command, n.next_msg
 local api = n.api
 local exec_lua = n.exec_lua
@@ -34,18 +33,18 @@ describe('notify', function()
     end)
   end)
 
-  describe('passing 0 as the channel id', function()
-    it('sends the notification/args to all subscribed channels', function()
-      api.nvim_subscribe('event2')
+  describe('channel id 0', function()
+    it('broadcasts the notification/args to all channels', function()
       eval('rpcnotify(0, "event1", 1, 2, 3)')
       eval('rpcnotify(0, "event2", 4, 5, 6)')
       eval('rpcnotify(0, "event2", 7, 8, 9)')
+      eq({ 'notification', 'event1', { 1, 2, 3 } }, next_msg())
       eq({ 'notification', 'event2', { 4, 5, 6 } }, next_msg())
       eq({ 'notification', 'event2', { 7, 8, 9 } }, next_msg())
-      api.nvim_unsubscribe('event2')
-      api.nvim_subscribe('event1')
+
       eval('rpcnotify(0, "event2", 10, 11, 12)')
       eval('rpcnotify(0, "event1", 13, 14, 15)')
+      eq({ 'notification', 'event2', { 10, 11, 12 } }, next_msg())
       eq({ 'notification', 'event1', { 13, 14, 15 } }, next_msg())
     end)
 
@@ -78,17 +77,6 @@ describe('notify', function()
     end)
   end)
 
-  it('unsubscribe non-existing event #8745', function()
-    clear { env = {
-      NVIM_LOG_FILE = testlog,
-    } }
-    api.nvim_subscribe('event1')
-    api.nvim_unsubscribe('doesnotexist')
-    assert_log("tried to unsubscribe unknown event 'doesnotexist'", testlog, 10)
-    api.nvim_unsubscribe('event1')
-    assert_alive()
-  end)
-
   it('cancels stale events on channel close', function()
     local catchan = eval("jobstart(['cat'], {'rpc': v:true})")
     local catpath = eval('exepath("cat")')
@@ -97,7 +85,6 @@ describe('notify', function()
       exec_lua(
         [[
       vim.rpcnotify(..., "nvim_call_function", 'chanclose', {..., 'rpc'})
-      vim.rpcnotify(..., "nvim_subscribe", "daily_rant")
       return vim.api.nvim_get_chan_info(...)
     ]],
         catchan