Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Notes on what *SUBSCRIBE returns (or doesn't return) #2327

Merged
merged 5 commits into from
Feb 23, 2023
Merged

Notes on what *SUBSCRIBE returns (or doesn't return) #2327

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
265cb71
Notes an what *SUBSCRIBE returns (or doesn't return)
zuiderkwast Feb 16, 2023
9f1f0fe
Add @return heading
zuiderkwast Feb 16, 2023
9b70f39
Add return info to *unsubscribe commands too
zuiderkwast Feb 16, 2023
7478fea
Add missing "the" in sentence
zuiderkwast Feb 17, 2023
1978cec
Add note about RESP3
zuiderkwast Feb 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions commands/psubscribe.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,16 @@ Supported glob-style patterns:
* `h[ae]llo` subscribes to `hello` and `hallo,` but not `hillo`

Use `\` to escape special characters if you want to match them verbatim.

Once the client enters the subscribed state it is not supposed to issue any other commands, except for additional `SUBSCRIBE`, `SSUBSCRIBE`, `PSUBSCRIBE`, `UNSUBSCRIBE`, `SUNSUBSCRIBE`, `PUNSUBSCRIBE`, `PING`, `RESET` and `QUIT` commands.
Copy link
Collaborator

@ranshid ranshid Feb 19, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is true only for resp2 right? maybe we should add that fact to the doc.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thx for comment.

The next line (line 12) says "However, if RESP3 is used (see HELLO) it is possible for a client to issue any commands while in subscribed state.". Is this not clear enough? Should we explicitly mention RESP2 in the first sentence?

Since RESP2 is the default protocol, I thought we can mention the differences for RESP3 afterwards like this, but if you have better idea, I'm happy to change.

Btw, RESP3 is not even documented on this website yet. Itamar has a WIP PR #2120 adding the RESP3 protocol spec. Until that is merged, we don't have anywhere to link for more information about RESP3 types (push, etc.) so I think we can update these commands' docs again after the RESP3 PR is merged.

In general, we will need to figure out how we want to document the difference in RESP2 vs RESP3 for each command. For other commands we have no documentation at all for RESP3, such as that HGETALL returns a hash or that SUNION returns a set. IMO we should change this to 'returns a hash' and 'returns a set' and in the protocol spec explain how these are represented in RESP2 and RESP3, rather than explaining this on each command's doc page.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wow to be honest I missed the following line since it does not apear in the published docs (AFAIK) I only stated it since I know currently people are missing that.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, I'll merge this as it is then?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍


For more information, see [Pub/sub](/docs/manual/pubsub/).

@return

When successful, this command doesn't return anything.
Instead, for each pattern, one message with the first element being the string "psubscribe" is pushed as a confirmation that the command succeeded.

## Behavior change history

* `>= 6.2.0`: `RESET` can be called to exit subscribed state.
5 changes: 5 additions & 0 deletions commands/punsubscribe.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,8 @@ When no patterns are specified, the client is unsubscribed from all the
previously subscribed patterns.
In this case, a message for every unsubscribed pattern will be sent to the
client.

@return

When successful, this command doesn't return anything.
Instead, for each pattern, one message with the first element being the string "punsubscribe" is pushed as a confirmation that the command succeeded.
6 changes: 6 additions & 0 deletions commands/ssubscribe.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,12 @@ A client can subscribe to channels across different slots over separate `SSUBSCR

For more information about sharded Pub/Sub, see [Sharded Pub/Sub](/topics/pubsub#sharded-pubsub).

@return

When successful, this command doesn't return anything.
Instead, for each shard channel, one message with the first element being the string "ssubscribe" is pushed as a confirmation that the command succeeded.
Note that this command can also return a -MOVED redirect.

@examples

```
Expand Down
9 changes: 8 additions & 1 deletion commands/subscribe.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,13 @@ Once the client enters the subscribed state it is not supposed to issue any
other commands, except for additional `SUBSCRIBE`, `SSUBSCRIBE`, `PSUBSCRIBE`, `UNSUBSCRIBE`, `SUNSUBSCRIBE`,
`PUNSUBSCRIBE`, `PING`, `RESET` and `QUIT` commands.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we would like to explain that this is only true for resp2?


For more information, see [Pub/sub](/docs/manual/pubsub/).

@return

When successful, this command doesn't return anything.
Instead, for each channel, one message with the first element being the string "subscribe" is pushed as a confirmation that the command succeeded.

## Behavior change history

* `>= 6.2.0`: `RESET` can be called to exit subscribed state.
* `>= 6.2.0`: `RESET` can be called to exit subscribed state.
5 changes: 5 additions & 0 deletions commands/sunsubscribe.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,8 @@ In this case a message for every unsubscribed shard channel will be sent to the
Note: The global channels and shard channels needs to be unsubscribed from separately.

For more information about sharded Pub/Sub, see [Sharded Pub/Sub](/topics/pubsub#sharded-pubsub).

@return

When successful, this command doesn't return anything.
Instead, for each shard channel, one message with the first element being the string "sunsubscribe" is pushed as a confirmation that the command succeeded.
5 changes: 5 additions & 0 deletions commands/unsubscribe.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,8 @@ When no channels are specified, the client is unsubscribed from all the
previously subscribed channels.
In this case, a message for every unsubscribed channel will be sent to the
client.

@return

When successful, this command doesn't return anything.
Instead, for each channel, one message with the first element being the string "unsubscribe" is pushed as a confirmation that the command succeeded.