Cache-Pot supports publish/subscribe messaging, letting you decouple producers from consumers through named channels. When you subscribe to a channel, your connection enters a special subscriber mode and receives messages pushed by any client that publishes to that channel. A slow subscriber that fills its output buffer will have messages dropped rather than blocking publishers — fan-out is non-blocking by design.
While a connection has active subscriptions, use a separate connection for regular data commands including PUBLISH. Call UNSUBSCRIBE / PUNSUBSCRIBE (or RESET) to release all subscriptions and return the connection to normal command mode.
SUBSCRIBE
Subscribes to one or more channels. After this command your connection enters subscriber mode. For each channel you subscribe to, Cache-Pot sends a confirmation reply: ["subscribe", channel, subscription_count].
Syntax: SUBSCRIBE channel [channel ...]
# Terminal 1: subscribe and wait for messages
SUBSCRIBE notifications alerts
# Cache-Pot confirms each subscription:
# 1) "subscribe"
# 2) "notifications"
# 3) (integer) 1
# 1) "subscribe"
# 2) "alerts"
# 3) (integer) 2
["subscribe", channel_name, total_subscription_count].
UNSUBSCRIBE
Unsubscribes from one or more channels. Omit channel names to unsubscribe from all channels at once. Cache-Pot sends a confirmation reply for each channel unsubscribed. When your total subscription count (channels + patterns) drops to zero, the connection leaves subscriber mode.
Syntax: UNSUBSCRIBE [channel ...]
# Unsubscribe from a specific channel
UNSUBSCRIBE notifications
# Unsubscribe from all channels
UNSUBSCRIBE
["unsubscribe", channel_name, total_subscription_count].
PSUBSCRIBE
Subscribes to one or more glob patterns. You will receive messages from any channel whose name matches a subscribed pattern. Patterns use the same syntax as KEYS: * matches any sequence, ? matches any single character, [...] matches a character class.
Messages delivered through a pattern subscription arrive as 4-element pmessage replies: ["pmessage", pattern, channel, message].
Syntax: PSUBSCRIBE pattern [pattern ...]
# Subscribe to all user-related channels
PSUBSCRIBE user:*
# Confirmation:
# 1) "psubscribe"
# 2) "user:*"
# 3) (integer) 1
# When a message arrives on user:42:
# 1) "pmessage"
# 2) "user:*"
# 3) "user:42"
# 4) "hello"
["psubscribe", pattern, total_subscription_count].
PUNSUBSCRIBE
Unsubscribes from one or more patterns. Omit patterns to unsubscribe from all active pattern subscriptions at once.
Syntax: PUNSUBSCRIBE [pattern ...]
PUNSUBSCRIBE user:*
# Confirmation:
# 1) "punsubscribe"
# 2) "user:*"
# 3) (integer) 0
["punsubscribe", pattern, total_subscription_count].
PUBLISH
Publishes message to channel. All clients currently subscribed to that channel (via SUBSCRIBE) or to a matching pattern (via PSUBSCRIBE) receive the message immediately.
Syntax: PUBLISH channel message
# Terminal 2: publish a message
PUBLISH notifications "new message"
# (integer) 1 (one subscriber received it)
PUBLISH channel_with_no_subs "hello"
# (integer) 0
Workflow example
Here is a minimal two-terminal pub/sub flow:
# Terminal 1: subscriber
SUBSCRIBE notifications
# Waiting for messages...
# Terminal 2: publisher (separate connection)
PUBLISH notifications "deployment complete"
# (integer) 1
# Terminal 1 now receives:
# 1) "message"
# 2) "notifications"
# 3) "deployment complete"
Pattern subscription example
# Terminal 1: subscribe to all user channels
PSUBSCRIBE user:*
# Waiting for messages...
# Terminal 2: publish to a specific user channel
PUBLISH user:42 "your order shipped"
# (integer) 1
# Terminal 1 receives a pmessage:
# 1) "pmessage"
# 2) "user:*" <- the matched pattern
# 3) "user:42" <- the actual channel
# 4) "your order shipped"
Use pattern subscriptions (PSUBSCRIBE) when you want a single subscriber to receive events from a whole family of channels — for example orders:* to monitor all order lifecycle events regardless of order ID.
If your application both publishes and subscribes, use two separate connections: one dedicated to subscriptions, and one for publishing and all other data commands. This keeps your command flow clean and avoids interleaving pub/sub confirmations with regular replies.
