docs: tutorial for WebSockets with AsyncAPI

pages/docs/tutorials/websocket/_section.md

@@ -0,0 +1,4 @@
+---
+title: 'WebSocket'
+weight: 200
+---

pages/docs/tutorials/websocket/index.md

@@ -0,0 +1,321 @@
+---
+title: Create an AsyncAPI Document for a Slackbot with WebSockets
+description: In this tutorial, you'll learn how to create an AsyncAPI document designed for a Slack application that operates in Socket Mode using the WebSockets protocol.
+weight: 210
+---
+
+## Introduction
+In this tutorial, you will learn how to write an AsyncAPI document designed for a Slack application that operates in Socket Mode. The aim is to help you grasp a real-world application of AsyncAPI with the WebSocket protocol. You will learn how to write AsyncAPI document for a consumer-only application receiving a stream of messages from a WebSocket server. You will also learn why the AsyncAPI bindings feature exist and how to use it.
+
+Consider a scenario where you are in charge of maintaining a highly active Slack workspace. You want an easy way to keep track of the popular messages across all the channels but doing this manually would be a difficult task. To simplify this process, you’re going to build a Slackbot called `Heart-Counter` that actively monitors reactions added to a message and determine its popularity by counting the reactions of the “heart” emoji.
+
+Here’s a visual representation of how `Heart-Counter` should work: 
+
+```mermaid
+sequenceDiagram
+participant Heart-Counter
+participant Slack Server (Socket Mode)
+participant User
+
+
+Heart-Counter ->>Slack Server (Socket Mode): Connect
+Note right of Heart-Counter: Establish WebSocket connection
+
+
+Slack Server (Socket Mode)->> Heart-Counter : Handshake
+Note left of Slack Server (Socket Mode): Establish Socket Mode connection
+
+Slack Server (Socket Mode)->> Heart-Counter : Sends "hello" event
+Note left of Slack Server (Socket Mode): Confirms successful connection
+
+
+
+
+
+User-->>Slack Server (Socket Mode): Adds emoji to a message.
+
+
+Slack Server (Socket Mode)->>Heart-Counter: Sending "reaction_added" payload
+
+
+Note left of Heart-Counter: Event received
+``` 
+
+## Background context
+[WebSocket](https://en.wikipedia.org/wiki/WebSocket) is a communication protocol that enables simultaneous bidirectional data exchange between a client and a server over a single, long-lived connection. Unlike HTTP, which relies on the request-response model, WebSocket is ideal for scenarios where real-time, interactive and low-latency communication is necessary.
+
+
+```mermaid
+sequenceDiagram
+Client -->> Server: Initiate WebSocket Connection
+Server -->> Client: Message 1
+Server -->> Client: Message 2
+Server -->> Client: Message 3
+Server -->> Client: Message 4
+```
+
+In Slack, WebSocket is employed as part of its [Socket Mode](https://api.slack.com/apis/connections/socket) feature to facilitate real-time notifications between Slack's servers and third-party applications or bots. The [Slack Event API](https://api.slack.com/apis/connections/events-api) is a tool that lets you receive real-time notifications of specific events in a Slack workspace such as messages, reactions, and user presence changes.
+
+
+## Define AsyncAPI version, API information, and server
+
+You start your AsyncAPI document by specifying the AsyncAPI version and essential information about your Slack application's API which includes details such as the `title`, `version` and `description`.
+
+The `servers` section allows you to define the protocol and specify information about the URLs your application will use, such as  `host`, `pathname`, `protocol` and `description`.
+
+<Remember>
+The WebSocket URL is generated  by invoking the <a href="https://api.slack.com/methods/apps.connections.open">apps.connections.open</a> method from Slack’s API. You use the authentication tokens obtained during the configuration of your Slackbot to generate this URL.
+</Remember>
+
+<CodeBlock language="yaml">
+{`asyncapi: '3.0.0'
+info:
+  title: Create an AsyncAPI Document for a Slackbot with WebSockets
+  version: '1.0.0'
+  description:  |
+    The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data
+servers:
+  production:
+    host: wss-primary.slack.com
+    pathname: /link
+    protocol: wss
+    description: Slack's server in Socket Mode for real-time communication `}
+</CodeBlock>
+
+## Define messages and schemas
+
+Your AsyncAPI document needs to be very clear on the type of event it is expected to receive. Here's where the `messages` component steps in. Using the `payload` property, you can specify what these events should look like, their structure, and what content they carry.
+
+The `payload` attribute specifies the name, format, and description of all the expected properties. `Heart-Counter` starts the popularity count of a message by validating if the `reaction` property set in the `reaction` schema definition corresponds to "heart".
+
+<CodeBlock language="yaml">
+{`components:
+  messages:
+    reaction:
+      summary: Action triggered when the channel receives a new reaction-added event
+      payload:
+        $ref: '#/components/schemas/reaction'
+    hello:
+      summary: Action triggered when a successful WebSocket connection is established
+      payload:
+        $ref: '#/components/schemas/hello'
+  schemas:
+    hello:
+      type: object
+      properties:
+        type:
+          type: string
+          description: A hello string confirming WebSocket connection
+        connection_info:
+          type: object
+          properties:
+            app_id:
+            type: string
+        num_connections:
+            type: integer
+        debug_info:
+          type: object
+          properties:
+            host:
+              type: string
+            started:
+              type: string
+            build_number:
+              type: integer
+            approximate_connection_time:
+              type: integer
+      reaction:
+        type: object
+        properties:
+          user:
+            type: string
+            description: User ID who performed this event
+          reaction:
+            type: string
+            description: The only reaction that we need is a heart emoji
+          item_user:
+            type: string
+            description: User ID that created the original item that has been reacted to
+          item:
+            type: object
+            properties:
+              channel:
+                type: string
+                description: Channel information of original message
+              ts:
+                type: string
+                description: Timestamp information of original message
+          event_ts:
+            type: string
+            description: Reaction timestamp `}
+</CodeBlock>
+
+## Define channels and  bindings
+
+The `channels` attribute defines a communication channel for the event. The `address` specifies where the channel is tuned in to receive messages while the `messages` property defines a key-value pair where each key corresponds to the event it's set up to handle.
+
+The WebSocket URL generated for `Heart-Counter` includes authentication tokens. This information is represented using `query` parameters. Query parameters are specific to HTTP protocol and also partially to WebSocket that uses HTTP to establish connection between client and server. Since this is protocol-specific information you need to use AsyncAPI feature called `bindings` that enables you to provide protocol-specific information inside AsyncAPI document using the `bindings` attribute. By utilizing the `query` object from the WebSocket binding, you can outline the parameters needed for the connection and the conditions they must meet. 
+
+<CodeBlock language="yaml">
+{`channels:
+  root:
+    address: /
+    messages:
+      hello:
+        $ref: '#/components/messages/hello'
+      reaction:
+        $ref: '#/components/messages/reaction'
+    bindings:
+      ws:
+        query:
+          type: object
+          description: Tokens are produced in the WebSocket URL generated from the [apps.connections.open](https://api.slack.com/methods/apps.connections.open) method from Slack’s API
+          properties:
+            ticket:
+              type: string
+              description: Temporary token generated when connection is initiated
+              const: '13748dac-b866-4ea7-b98e-4fb7895c0a7f'
+            app_id:
+              type: string
+              description: Unique identifier assigned to the Slack app
+              const: 'fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f' `}
+</CodeBlock>
+
+## Define operations 
+The `operation` property, is all about defining specific tasks your application can perform. Essentially, it's how `Heart-Counter` interacts with Slack.
+
+In this example, the `helloListener` operation keeps an eye out for the message sent by the Slack server when a WebSocket connection is successfully established. On the other hand, the `reactionListener` is focused on the `reaction_added` event type.
+
+Your Slack application is designed to be notified of events within your workspace. It does this by subscribing to a specific event type making use of Slack's Event API.  So in this case the `action` property in both the operations is set to `receive` events.
+
+<CodeBlock language="yaml">
+{`operations:
+  helloListener:
+    action: receive
+    channel:
+      $ref: '#/channels/root'
+    messages:
+      - $ref: '#/channels/root/messages/hello'
+  reactionListener:
+    action: receive
+    channel:
+      $ref: '#/channels/root'
+    messages:
+      - $ref: '#/channels/root/messages/reaction' `}
+</CodeBlock>
+
+You've now completed the tutorial! Putting these blocks together gives you your AsyncAPI document all ready to go.
+
+<CodeBlock language="yaml">
+{`asyncapi: '3.0.0'
+info:
+  title: Create an AsyncAPI Document for a Slackbot with WebSockets
+  version: '1.0.0'
+  description:  |
+    The Heart-Counter manages popular messages in a Slack workspace by monitoring message reaction data.
+servers:
+  production:
+    host: wss-primary.slack.com
+    pathname: /link
+    protocol: wss
+    description: Slack's server in Socket Mode for real-time communication
+channels:
+  root:
+    address: /
+    messages:
+      hello:
+        $ref: '#/components/messages/hello'
+      reaction:
+        $ref: '#/components/messages/reaction'
+    bindings:
+      ws:
+        query:
+          type: object
+          description: Tokens are produced in the WebSocket URL generated from the [apps.connections.open](https://api.slack.com/methods/apps.connections.open) method from Slack’s API
+          properties:
+            ticket:
+              type: string
+              description: Temporary token generated when connection is initiated
+              const: '13748dac-b866-4ea7-b98e-4fb7895c0a7f'
+            app_id:
+              type: string
+              description: Unique identifier assigned to the Slack app
+              const: 'fe684dfa62159c6ac646beeac31c8f4ef415e4f39c626c2dbd1530e3a690892f'
+operations:
+  helloListener:
+    action: receive
+    channel:
+      $ref: '#/channels/root'
+    messages:
+      - $ref: '#/channels/root/messages/hello'
+  reactionListener:
+    action: receive
+    channel:
+      $ref: '#/channels/root'
+    messages:
+      - $ref: '#/channels/root/messages/reaction'
+components:
+  messages:
+    reaction:
+      summary: Action triggered when the channel receives a new reaction-added event
+      payload:
+        $ref: '#/components/schemas/reaction'
+    hello:
+      summary: Action triggered when a successful WebSocket connection is established
+      payload:
+        $ref: '#/components/schemas/hello'
+schemas:
+  hello:
+    type: object
+    properties:
+      type:
+        type: string
+        description: A hello string confirming WebSocket connection
+      connection_info:
+        type: object
+        properties:
+          app_id:
+            type: string
+          num_connections:
+            type: integer
+          debug_info:
+            type: object
+            properties:
+              host:
+                type: string
+              started:
+                type: string
+              build_number:
+                type: integer
+              approximate_connection_time:
+                type: integer
+    reaction:
+      type: object
+      properties:
+        user:
+          type: string
+          description: User ID who performed this event
+        reaction:
+          type: string
+          description: The only reaction that we need is a heart emoji
+        item_user:
+          type: string
+          description: User ID that created the original item that has been reacted to
+        item:
+          type: object
+          properties:
+            channel:
+              type: string
+              description: Channel information of original message
+            ts:
+              type: string
+              description: Timestamp information of original message
+        event_ts:
+          type: string
+          description: Reaction timestamp `}
+</CodeBlock>
+
+
+
+## Summary
+In this tutorial, you learned to create an AsyncAPI document for a Slackbot using WebSocket in Socket Mode. You gained practical insights into the functionality of operations, channels, messages, and schemas. Now you're equipped to handle real-world applications that facilitates bidirectional real-time data exchange such as chatbots and live-streaming platforms.