123456789_123456789_123456789_123456789_123456789_

Module: Redis::KeyspaceNotifications::Channels

Relationships & Source Files
Defined in: lib/redis/keyspace_notifications/channels.rb

Overview

Builders for keyspace-notification channel names and psubscribe patterns.

All builders return BINARY (ASCII-8BIT) encoded strings so that keys containing arbitrary bytes concatenate safely. The db: argument accepts a non-negative Integer or the literal "*" (database wildcard, for pattern subscriptions). The key+/+event arguments may themselves contain glob characters when the channel is meant to be used with psubscribe.

Examples:

Watch every event on keys under a prefix

redis.psubscribe(Redis::KeyspaceNotifications::Channels.keyspace("user:*", db: 0)) { |on| ... }

Constant Summary

Class Method Summary

Class Method Details

.build(family, db, suffix) (mod_func)

[ GitHub ] 

  


# File 'lib/redis/keyspace_notifications/channels.rb', line 107



def build(family, db, suffix)
  validate_db!(db)
  prefix = "#{FAMILIES.fetch(family)}#{db}__:"
  prefix.b << suffix.b
end


  








  

    .glob_escape(value)  ⇒ String  (mod_func)
  



  

    
Escapes Redis glob metacharacters (*, ?, [, ], \) so a literal
key can be embedded in a psubscribe pattern without matching other keys.

  





  
Parameters:


    
  
  • 
    value
    (String)
  
    • 



Returns:


    
  
  • 
    (String)
—    
    the escaped value (BINARY encoded)
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/keyspace_notifications/channels.rb', line 99



def glob_escape(value)
  # The replacement must be built in BINARY: interpolating a high byte into a
  # UTF-8 literal raises Encoding::CompatibilityError, and keys are arbitrary
  # bytes by contract.
  value.b.gsub(/[*?\[\]\\]/) { |char| "\\".b << char }
end


  








  

    .keyevent(event, db: 0)  ⇒ String  (mod_func)
  



  

    
Channel carrying every key receiving event; the message payload is the key name.

  





  
Parameters:


    
  
  • 
    event
    (String)
—    
    event name (e.g. "expired") or glob pattern
    
  
    • 
  
  • 
    db
    (Integer, String)
—    
    database index or "*"
    
  
    • 



Returns:


    
  
  • 
    (String)
—    
    __keyevent@__: (BINARY encoded)
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/keyspace_notifications/channels.rb', line 41



def keyevent(event, db: 0)
  build(:keyevent, db, event)
end


  








  

    .keyspace(key, db: 0)  ⇒ String  (mod_func)
  



  

    
Channel carrying every event happening to key; the message payload is the event name.

  





  
Parameters:


    
  
  • 
    key
    (String)
—    
    key name or glob pattern
    
  
    • 
  
  • 
    db
    (Integer, String)
—    
    database index or "*"
    
  
    • 



Returns:


    
  
  • 
    (String)
—    
    __keyspace@__: (BINARY encoded)
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/keyspace_notifications/channels.rb', line 32



def keyspace(key, db: 0)
  build(:keyspace, db, key)
end


  








  

    .subkeyevent(event, db: 0)  ⇒ String  (mod_func)
  



  

    
Subkey channel for event; the payload carries the key and the affected subkeys.
Requires Redis 8.8+ with the T flag in notify-keyspace-events.

  





  
Parameters:


    
  
  • 
    event
    (String)
—    
    event name (e.g. "hdel") or glob pattern
    
  
    • 
  
  • 
    db
    (Integer, String)
—    
    database index or "*"
    
  
    • 



Returns:


    
  
  • 
    (String)
—    
    __subkeyevent@__: (BINARY encoded)
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/keyspace_notifications/channels.rb', line 61



def subkeyevent(event, db: 0)
  build(:subkeyevent, db, event)
end


  








  

    .subkeyspace(key, db: 0)  ⇒ String  (mod_func)
  



  

    
Subkey channel for key; the payload carries the event and the affected subkeys.
Requires Redis 8.8+ with the S flag in notify-keyspace-events.

  





  
Parameters:


    
  
  • 
    key
    (String)
—    
    key name or glob pattern
    
  
    • 
  
  • 
    db
    (Integer, String)
—    
    database index or "*"
    
  
    • 



Returns:


    
  
  • 
    (String)
—    
    __subkeyspace@__: (BINARY encoded)
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/keyspace_notifications/channels.rb', line 51



def subkeyspace(key, db: 0)
  build(:subkeyspace, db, key)
end


  








  

    .subkeyspaceevent(event, key, db: 0)  ⇒ String  (mod_func)
  



  

    
Event + key channel; the payload carries the affected subkeys. The key part may be
a glob pattern (e.g. subkeyspaceevent("hset", "user:*") with psubscribe).
Requires Redis 8.8+ with the V flag in notify-keyspace-events.

  





  
Parameters:


    
  
  • 
    event
    (String)
—    
    event name (e.g. "hset") or glob pattern
    
  
    • 
  
  • 
    key
    (String)
—    
    key name or glob pattern
    
  
    • 
  
  • 
    db
    (Integer, String)
—    
    database index or "*"
    
  
    • 



Returns:


    
  
  • 
    (String)
—    
    __subkeyspaceevent@__:| (BINARY encoded)
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/keyspace_notifications/channels.rb', line 89



def subkeyspaceevent(event, key, db: 0)
  channel = build(:subkeyspaceevent, db, event)
  channel << "|" << key.b
end


  








  

    .subkeyspaceitem(key, subkey, db: 0)  ⇒ String  (mod_func)
  



  

    
Exact key + subkey channel; the payload is the event name. The server only emits
this family for keys that contain no newline, so such keys are rejected here.
Requires Redis 8.8+ with the I flag in notify-keyspace-events.

  





  
Parameters:


    
  
  • 
    key
    (String)
—    
    key name (must not contain "\n")
    
  
    • 
  
  • 
    subkey
    (String)
—    
    subkey (e.g. hash field) or glob pattern
    
  
    • 
  
  • 
    db
    (Integer, String)
—    
    database index or "*"
    
  
    • 



Returns:


    
  
  • 
    (String)
—    
    __subkeyspaceitem@__:\n (BINARY encoded)
    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
—    
    when key contains "\n"
    
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/keyspace_notifications/channels.rb', line 74



def subkeyspaceitem(key, subkey, db: 0)
  raise ArgumentError, "subkeyspaceitem keys must not contain \"\\n\"" if key.include?("\n")

  channel = build(:subkeyspaceitem, db, key)
  channel << "\n" << subkey.b
end


  








  

    .validate_db!(db)   (mod_func)
  



  

    
  





  
Raises:


    
  
  • 
    (ArgumentError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/redis/keyspace_notifications/channels.rb', line 114



def validate_db!(db)
  return if db == "*" || (db.is_a?(Integer) && db >= 0)

  raise ArgumentError, "db must be a non-negative Integer or \"*\", got #{db.inspect}"
end