API proposal: keyspace notifications

[mgravell]

Regular pubsub does not work well with keyspace notifications due to the different routing requirements, and the complexity of understanding the key and event type. A new API is suggested:

+ public enum KeyspaceEvent
+ { 
+     Unknown,
+     All,
+     // see list https://redis.io/docs/latest/develop/pubsub/keyspace-notifications/  
+     Add,
+     // ...
+     ZRem,
+     Expired,
+     // ...
+     TypeChanged // type_changed
+ }
+ public readonly struct KeyspaceNotification(int database, in RedisKey key, KeyspaceEvent @event)
+ {
+     public int Database => database;
+     public RedisKey Key => key;
+     public KeyspaceEvent Event => @event;
+ }
  public readonly struct RedisChannel
  {
+     // if this channel corresponds to a keyspace/keyevent notification: parse out the key, event and database information from the channel and payload
+     public bool IsKeyspaceNotification(in RedisValue value, out KeyspaceNotification notification);
+     // subscribe to keyevent notifications of the given category (or All), i.e. __keyevent@{database}__:{event}
+     public static RedisChannel KeyEventNotification(KeyspaceEvent @event, int? database = null);
+     // subscribe to keyspace notifications for the given key, i.e. __keyspace@{database}__:{key}
+     public static RedisChannel KeySpaceNotification(RedisKey key, int? database = null);
+     // subscribe to keyspace notifications for the given pattern, i.e. __keyspace@{database}__:{pattern}
+     public static RedisChannel KeySpacePatternNotification(RedisKey pattern, int? database = null);
  }
  public readonly struct ChannelMessage
  {
+     public bool IsKeyspaceNotification(out KeyspaceNotification notification) => Channel.IsKeyspaceNotification(Message, out notification);
  }

Note that the int? database in this context refers to single database vs all databases; if the value is -ve, the default database will be applied, but the assumption is that we mean any database. In the case of "any database", or KeySpacePatternNotification, PSUBSCRIBE will be used, otherwise SUBSCRIBE will be used. In the case of cluster, KeyEventNotification and KeySpacePatternNotification require routing to all endpoints. Note that vanilla redis limits cluster to single-database (zero); while this generalization may not hold in all cases (Valkey), SE.Redis does not properly support that scenario.

Internally, additional work will be required for OSS cluster to ensure all primary nodes are covered, including reconnects and topology changes; this changes the existing expectation that a channel has zero or one connected endpoints, so is non-trivial.

[philon-msft]

When subscribing to notifications for all keys in a db, this API allows filtering by KeyspaceEvent type... is there any value in also allowing that filtering when subscribing for a specific key or pattern?

[mgravell]

That isn't a feature offered by the server; we would need to apply it after-the-fact. However, there is some merit here: we could offer a single API with optional key/pattern and type and choose the best strategy based on which options are selected. Might be simpler for the consumer. In the case of both being specified, we'd presumably use a keyspace event and filter the event-type at the client.

[philon-msft]

I like that, as long as we have a good place to store the desired event-type for filtering. Also it feels similar to the simplified/unified way we expose Expirations now

[mgravell]

@philon-msft suggestion - we re-use the struct as our pattern template:

 public static RedisChannel KeyNotification(KeyspaceNotification match)

from which we build the most appropriate __keyevent... or __keyspace... channel, based on whether Database, Key and/or Event are specified.