Channels

docs/docs/_sidebar.md

@@ -9,6 +9,7 @@
   - [Install Socket from NPM](/project/install-from-npm)
 - Building your own Sockets
   - [Basics](/building-sockets/basics)
+  - [Real-time channels](/building-sockets/real-time-channels)
   - [Endpoints](/building-sockets/endpoints)
   - [Event Handlers](/building-sockets/event-handlers)
   - [Events](/building-sockets/events)

docs/docs/building-sockets/endpoints.md

@@ -70,22 +70,3 @@ s.get('socket/with_cache', { '__skip_cache': 1 })
 ```
 
 Endpoints with this parameter, will be accessible with an account key only. They are suitable for hiding away Socket settings and configuration options. End users of your app won't have access to them.
-
-## Channels
-
-Real-Time Channels are a way of providing real-time publish/subscribe functionality in Syncano.
-
-In the configuration, they are part of the endpoints section. A user can either subscribe to messages on a certain channel or publish them:
-
-```yaml
-endpoints:
-  # Publish to channel that is built from current user's username automatically by library.
-  publish: |
-      channels.publish("channel.{user}", {message: "Hello!"})
-
-  # Subscriptions to channels are open but can be based on current user (like in this example).
-  subscribe:
-      channel: channel.{user}
-```
-
-Read the Real-Time Channels documentation to learn more about the real-time capabilities of Syncano.

docs/docs/building-sockets/real-time-channels.md

@@ -0,0 +1,120 @@
+# Real-time channels
+
+Channels is a web Socket that gives the posibility to create applications which need to receive realtime data like chat
+
+Listen on Syncano Realtime Channels.
+
+**Methods**
+
+| Name                                                      | Description                                  |
+| --------------------------------------------------------- | -------------------------------------------- |
+| [s.listen](#slistenendpoint-params)                       | Listen on given channel                      |
+
+## `s.listen(endpoint, params?)`
+
+Subscribe to given Syncano endpoint. `s.listen` returns instance of [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket).
+
+```js
+// your-client-side-file.js
+// chat - socket name
+// poll-messages - endpoint name
+s.listen('chat/poll-messages')
+  .addEventListener('message', message => {
+    // Handle message
+  })
+```
+
+**Public channels**
+
+```yml
+# chat/socket.yml
+endpoints:
+  global-messages:
+    channel: global-messages
+  create-message:
+    file: src/create-message.js
+```
+
+```js
+// chat/src/create-message.js
+import Syncano from '@syncano/core'
+
+export default (ctx) => {
+  const {channels} = new Syncano(ctx)
+  const {args} = ctx
+
+  channel.publish(`global-messages`, args.message)
+}
+```
+
+**Room channels**
+
+```yml
+# chat/socket.yml
+endpoints:
+  private-messages:
+    channel: private-messages.{room}
+  create-message:
+    file: src/create-message.js
+```
+
+```js
+// chat/src/create-message.js
+import Syncano from '@syncano/core'
+
+export default (ctx) => {
+  const {channels} = new Syncano(ctx)
+  const {args} = ctx
+
+  channel.publish(`private-messages.${args.room_id}`, message)
+}
+```
+
+```js
+s.listen('chat/private-messages', {room: 1})
+  .addEventListener('message', message => {
+    // Handle message
+  })
+```
+
+**User channels**
+
+First, you have to use special variable `{user}` in your channel name. It'll be used to check if a given user have rights to access endpoint.
+
+```yml
+# notifications/socket.yml
+endpoints:
+  get:
+    channel: notifications.{user}
+  notify:
+    file: src/notify.js
+```
+
+Then you can subscribe to channel by passing socket and endpoint name. User channels require `user_key` to be send in payload.
+
+```js
+s.listen('notifications/get', {user_key: 'USER_KEY'})
+  .addEventListener('message', notification => {
+    // Handle notification
+  })
+```
+
+To publish to the user channel, you have to know its `username`.
+
+> In channel name `notifications.{user}` - `{user}` must always be a `username`, not id or any other property.
+
+```js
+// notifications/src/notify.js
+import Syncano from '@syncano/core'
+
+export default (ctx) => {
+  const {channels, response} = new Syncano(ctx)
+  const {user} = ctx.meta
+
+  if(!meta.user) {
+    return response.json("Unauthorized!", 401)
+  }
+
+  channel.publish(`notifications.${user.username}`, notification)
+}
+```

docs/docs/client-lib-reference/installation.md

@@ -133,30 +133,3 @@ s.setToken()
 ```
 
 ?> Usually you want to store user session in `localStorage` or `sessionStorage`. `setToken` is helpful when you want restore a session for a user without asking for a username and password
-
-## Subscribe to channel endpoint
-
- `s.subscribe(socket-name>/<endpoint-name>, callback)`
-
-You can subscribe to the live updates from the endpoints which are configured to expose real-time channel.
-Callback is fired each time you receive message from endpoint.
-
-```js
-// chat - socket name
-// messages - endpoint name
-s.subscribe('chat/messages', message => {
-  // Handle message
-  console.log(message)
-})
-```
-
-You can also use `once` method to get only first message. After receive messages, connection with channel will be closed.
-
-`s.subscribe.once(socket-name>/<endpoint-name>, callback)`
-
-```js
-s.subscribe.once('chat/messages', message => {
-  // Will be executed only once - after the first message
-  console.log(message)
-})
-```