add pub/sub documentation

3.0/docs/jwt/jws.md

@@ -22,7 +22,7 @@ struct AuthorizationToken : Codable {
 
 To send a token to the client, you need to sign it. Signing is done using a "secret". Secrets are a static key that stays the same across server reboots and is usually put inside a configuration file.
 
-Secrets _should_ be randomly generated. Longer secrets are better, there is no limit.
+Secrets _should_ be randomly generated. Longer secrets and less predictable are better, there is no limit.
 
 Once a secret is available in the application you can sign your tokens.
 

3.0/docs/redis/index.md

@@ -12,6 +12,7 @@ Redis works as a key-value store, but allows querying the keys, unlike most data
 
 - [Basics](basics.md)
 - [Custom commands](custom-commands.md)
+- [Pub/Sub](pub-sub.md)
 
 ## With and without Vapor
 

3.0/docs/redis/pub-sub.md

@@ -0,0 +1,58 @@
+# Publish & Subscribe
+
+Redis' Publish and Subscribe model is really useful for notifications.
+
+### Use cases
+
+Pub/sub is used for notifying subscribers of an event.
+A simple and common event for example would be a chat message.
+
+A channel consists of a name and group of listeners. Think of it as being `[String: [Listener]]`.
+When you send a notification to a channel you need to provide a payload.
+Each listener will get a notification consisting of this payload.
+
+Channels must be a string. For chat groups, for example, you could use the database identifier.
+
+### Publishing
+
+You cannot get a list of listeners, but sending a payload will emit the amount of listeners that received the notification.
+Sending (publishing) an event is done like so:
+
+```swift
+// Any redis data
+let notification: RedisData = "My-Notification"
+
+client.publish(notification, to: "my-channel")
+```
+
+If you want access to the listener count:
+
+```swift
+let notifiedCount = client.publish(notification, to: "my-channel") // Future<Int>
+```
+
+### Subscribing
+
+To subscribe for notifications you're rendering an entire Redis Client useless in exchange for listening to events.
+
+A single client can listen to one or more channels, which is provided using a set of unique channel names. The result of subscribing is a `SubscriptionStream`.
+
+```swift
+let notifications = client.subscribe(to: ["some-notification-channel", "other-notification-channel"])
+```
+
+If you try to use the client after subscribing, all operations will fail. These errors are usually emitted through the Future.
+
+This stream will receive messages asynchronously from the point of `draining`. This works like [any other async stream](../async/stream-basics.md)
+
+Notifications consist of the channel and payload.
+
+```swift
+notifications.drain { notification in
+  print(notification.channel)
+
+  let payload = notification.payload
+
+  // TODO: Process the payload
+}
+```