Merge pull request #1560 from Thushani-Jayasekera/dev

Add documentation for WebSocket Endpoints

en/.spelling

@@ -699,6 +699,10 @@ headerName
 fooValue
 authzHeaderValue
 myResourcePath
+WebSocket
+WebSockets
+expose-a-nodejs-websocket-endpoint-via-a-service
+test-websocket-endpoints-via-the-websocket-console
 schemaVersion
 displayName
 basePath

en/docs/develop-components/configure-endpoints-body.md

@@ -7,7 +7,7 @@ Choreo defines endpoints by combining port binding, protocol, endpoint name, net
 | ----- | ----------- |
 | Name | A unique identifier for the endpoint within the service component. |
 | Port | The network port on which the endpoint is accessible. |
-| Type | The endpoint protocol. Supported protocols: REST, GraphQL, gRPC, UDP, and TCP. |
+| Type | The endpoint protocol. Supported protocols: REST, GraphQL, gRPC, WS, UDP, and TCP. |
 | Network Visibility | Determines the level of visibility of an endpoint. Possible values are: <ul><li>Project: Allows components within the same project to access the endpoint.</li><li>Organization: Allows any component within the same organization to access the endpoint but restricts access to components outside the organization.</li><li>Public: Allows any client to access the endpoint, regardless of location or organization.</li></ul> |
 | Schema | Specifies the structure and format of the data exchanged through the endpoint. |
 | Context (HTTP and GraphQL only) | A context path that you add to the endpoint's URL for routing purposes. |

en/docs/develop-components/develop-services/expose-a-nodejs-websocket-endpoint-via-a-service.md

@@ -0,0 +1,122 @@
+# Expose a NodeJS WebSocket Endpoint via a Service
+
+Choreo allows you to create and deploy applications in your preferred programming language, offering a seamless platform for building dynamic and scalable solutions. This guide walks you through the steps to deploy a WebSocket service using the NodeJS buildpack.
+
+WebSockets provide real-time, two-way communication between a client and server over a persistent TCP connection. This makes WebSocket APIs ideal for applications that require real-time updates.
+
+In this guide, you will:
+
+- Build a simple WebSocket service using a sample implementation in NodeJS.
+- Deploy the service in Choreo, allowing any WebSocket client application to establish a connection and exchange real-time messages with your service.
+
+## Prerequisites
+
+- If you are signing in to the Choreo Console for the first time, create an organization as follows:
+
+    1. Go to [https://console.choreo.dev/](https://console.choreo.dev/), and sign in using your preferred method.
+    2. Enter a unique organization name. For example, `Stark Industries`.
+    3. Read and accept the privacy policy and terms of use.
+    4. Click **Create**.
+
+    This creates the organization and opens the **Project Home** page of the default project created for you.
+
+- Fork the [Choreo samples repository](https://github.com/wso2/choreo-samples/), which contains the [sample WebSocket service](https://github.com/wso2/choreo-samples/tree/main/websocket-chat-app) implementation for this guide.
+
+Let's get started!
+
+## Learn the repository file structure
+
+It is important to understand the purpose of the key files in the sample service. The following table provides a brief overview of each file in the NodeJS chat Application.
+
+!!! note
+    The following file paths are relative to the path `<sample-repository-dir>/websocket-chat-app/websocket-chat-service-nodejs`.
+
+|Filepath                        | Description                                                     |
+|--------------------------------|-----------------------------------------------------------------|
+| `server.js`                    | The NodeJS chat service.                                        |
+| `.choreo/component-config.yaml`| The configuration file with endpoint details.                   |
+
+## Step 1: Create a service component 
+
+To create a NodeJS service component, follow these steps:
+
+1. Go to [https://console.choreo.dev/](https://console.choreo.dev/) and sign in. This opens the project home page.
+2. If you already have one or more components in your project, click **+ Create**. Otherwise, proceed to the next step.
+3. Click the **Service** card.
+4. Enter a display name, a unique name, and a description for the service component. You can enter the values given below:
+
+    !!! info
+         In the **Component Name** field, you must specify a name to uniquely identify the component in various contexts. The value is editable only at the time you create the component. You cannot change the name after you create the component.
+
+    | **Field**                 | **Value**               |
+    |---------------------------|-------------------------|
+    | **Component Display Name**| `NodeJS Chat Service`   |
+    | **Component Name**        | `nodejs-chat-service`   |
+    | **Description**           | Manage a chat service   |
+
+5. Click the **GitHub** tab.
+6. To allow Choreo to connect to your GitHub account, click **Authorize with GitHub**. If you have not already connected your GitHub repository to Choreo, enter your GitHub credentials and select the repository you created in the prerequisites section to install the [Choreo GitHub App](https://github.com/marketplace/choreo-apps).
+
+    Alternatively, you can paste the [Choreo samples repository](https://github.com/wso2/choreo-samples) URL in the **Provide Repository URL** field to connect to it without requiring authorization from the [Choreo Apps](https://github.com/marketplace/choreo-apps) GitHub application. However, authorizing the repository with the [Choreo GitHub App](https://github.com/marketplace/choreo-apps) is necessary if you want to enable [**Auto Deploy**](https://wso2.com/choreo/docs/choreo-concepts/ci-cd/#deploy) for the component.
+
+    !!! note
+           The **Choreo GitHub App** requires the following permissions:
+
+           - Read and write access to code and pull requests.
+           - Read access to issues and metadata.
+             
+           You can [revoke access](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-authorized-integrations#reviewing-your-authorized-github-apps) if you do not want Choreo to have access to your GitHub account. However, write access is exclusively utilized for sending pull requests to a user repository. Choreo will not directly push any changes to a repository.
+
+7. Under **Connect Your Repository**, enter the following information:
+
+    | **Field**               | **Value**               |
+    |-------------------------|-------------------------|
+    | **Organization**        | Your GitHub account     |
+    | **GitHub Repository**   | **`choreo-samples`**    |
+    | **Branch**              | **`main`**              |
+
+8. Select **NodeJS** as the buildpack.
+9. Enter the following information:
+
+    | **Field**                      | **Value**                                           |
+    |--------------------------------|-----------------------------------------------------|
+    | **NodeJS Project Directory**   | `websocket-chat-app/websocket-chat-service-nodejs`  |
+
+10. Click **Create**. This creates the component and takes you to the **Overview** page of the component.
+
+You have successfully created a service component that provides a WebSocket API built with NodeJS. The next step is to proceed with building and deploying the service.
+
+## Step 2: Build and deploy
+
+Now that you have connected the source repository, it's time to build and deploy the chat service.
+
+### Step 2.1: Build
+
+To build the service, follow these steps:
+
+1. In the left navigation menu, click **Build**.
+2. On the **Build** page, click **Build Latest**.
+
+    !!! note
+        Building the service component may take a while. You can track the progress via the logs in the **Build Details** pane. Once the build process is complete, the build status changes to **Success**.
+
+### Step 2.2: Deploy
+
+To deploy the service, follow these steps: 
+
+1. In the left navigation menu, click **Deploy**.
+2. On the **Set Up** card, click **Configure & Deploy**.
+3. In the **Configurations** pane that opens, click **Next** to skip the configuration.
+4. Review the **Endpoint Details** and click **Deploy**.
+
+    !!! note
+        Deploying the service component may take a while. Once deployed, the **Development** environment card indicates the **Deployment Status** as **Active**.
+
+Once you have successfully deployed your service, you can [test](../../testing/test-websocket-endpoints-via-the-websocket-console.md), [manage](../../api-management/lifecycle-management.md), and observe it like any other component type in Choreo.
+
+!!! note
+     Some clients, such as certain browsers, may not support adding headers to the WebSocket handshake. In these cases, you can include the access token or API key required for WebSocket API invocation within the `sec-websocket-protocolheader`, along with any specified subprotocols.
+
+     For example: `sec-websocket-protocol: choreo-oauth2-key, {access token}, subprotocols`
+
+     If you are using an API key, replace `choreo-oauth2-key` with `choreo-internal-API-key`.

en/docs/develop-components/develop-services/service-component-overview.md

@@ -4,7 +4,7 @@ Explore how to create, deploy, manage, and observe service components in Choreo.
 
 ## What is a service component?
 
-A service component in Choreo lets you deploy and expose REST, GraphQL, gRPC, UDP, or TCP services. It is a fundamental building block for creating cloud-native applications in Choreo. They provide a simple and effective way to expose functionality as a service to other components within Choreo or to the outside world.
+A service component in Choreo lets you deploy and expose REST, GraphQL, gRPC, UDP, WS or TCP services. It is a fundamental building block for creating cloud-native applications in Choreo. They provide a simple and effective way to expose functionality as a service to other components within Choreo or to the outside world.
 
 Service components encapsulate business logic and provide standardized interfaces, called endpoints, for communicating with other components or systems. You can deploy and scale services independently, which makes them highly flexible and adaptable to changing workloads.
 

en/docs/references/choreo-limitations.md

@@ -8,17 +8,19 @@ Below are key limitations when working with APIs in Choreo:
 
 |Resource                             |  Limit                                                                                      |
 |-------------------------------------|---------------------------------------------------------------------------------------------|
-| Maximum request payload             |  10 MB                                                                                       |
-| URL size                            |  2 KB                                                                                         |
-| Request header                      | <ul><li>Request Headers total: 40 KB</li><li>Max Single Request header: 10 KB</li></ul>       |
-| Total request duration              | <ul><li>Minimum: 10 seconds</li><li>Default: 1 minute</li><li>Maximum: 5 minutes</li></ul>             |
-| Size for API Definition (OpenAPI document)| 10 Mb                                                                                  |
+| Maximum request payload             |  10 MB                                                                                      |
+| URL size                            |  2 KB                                                                                       |
+| Request header                      | <ul><li>Request Headers total: 40 KB</li><li>Max Single Request header: 10 KB</li></ul>     |
+| Total request duration              | <ul><li>Minimum: 10 seconds</li><li>Default: 1 minute</li><li>Maximum: 5 minutes</li></ul>  |
+| Maximum connection duration (WebSocket APIs)  |  15  minutes                                                                      |
+| Connection idle timeout (WebSocket APIs)                            |  5 minutes                                                  |
+| Size for API definition (OpenAPI document)| 10 Mb                                                                                 |
 | Number of APIs for PDP                 | 1000 API deployments                                                                     |
-| Number of APIs per organization (free tier)                 | 5 APIs for free users                                                                    |
-| Number of Developer Portal applications per organization (free tier)  | 10 applications for free users                                                          |
+| Number of APIs per organization (free tier)                 | 5 APIs for free users                                               |
+| Number of Developer Portal applications per organization (free tier)  | 10 applications for free users                            |
 
 
-## Choreo Cloud Data Plane limits
+## Choreo cloud data plane limits
 
 Below are key limitations when working with web applications in the Choreo cloud data plane:
 

en/docs/testing/test-websocket-endpoints-via-the-websocket-console.md

@@ -0,0 +1,36 @@
+# Test WebSocket Endpoints via the WebSocket Console
+
+Choreo provides an integrated WebSocket Console to test publicly exposed WebSocket endpoints of Service components you create and deploy. The WebSocket Console allows you to connect to your service and exchange messages interactively. Choreo secures WebSocket APIs with OAuth2.0 by default, and the console automatically generates test keys for authenticated API testing.
+
+Follow the steps below to test a WebSocket endpoint via the WebSocket Console:
+
+1. Sign in to the [Choreo Console](https://console.choreo.dev/).
+
+2. In the **Component Listing** pane, click on the component you want to test.
+
+3. Click **Test** in the left navigation menu and then click **Console**. This opens the **WebSocket Console** pane.
+
+4. In the **WebSocket Console** pane, select the environment from the drop-down list.
+
+5. Select the required endpoint from the **Endpoint** list.
+
+    !!! note
+        - The **Network Visibility** of an endpoint is set in the **endpoints.yaml** file. You can set it to **Public**, **Organization**, or **Project**.
+        - If you have set the **Network Visibility** of the endpoint to **Public**, proceed to step 7. 
+        - If you have set the **Network Visibility** of the endpoint to **Organization**, it won't be accessible from outside the organization. For testing, Choreo allows you to generate a temporary URL that remains active for 15 minutes. Follow step 6 to generate the URL.
+
+6. If the **Network Visibility** of the endpoint is set to **Organization**, click **Generate URL** to generate a temporary test URL valid for 15 minutes. Otherwise, skip this step. 
+
+    !!! note
+        The temporary test URL is valid for 15 minutes and will expire after that. If you want to manually deactivate it, click **Deactivate URL**.
+
+    ![WebSocket Console](../assets/img/testing/websocket-console.png){.cInlineImage-full}
+
+7. Expand the channel you want to test.
+
+8. Click **Connect** to establish a connection. The connection status will be displayed in the output logs.
+
+9. Send and receive messages to and from the deployed service.
+
+    !!! note
+         The maximum connection duration is 15 minutes. After that, the connection terminates. To reconnect, click **Connect** again.

en/mkdocs.yml

@@ -104,6 +104,7 @@ nav:
           - Expose a UDP Server via a Service: develop-components/develop-services/expose-a-udp-server-via-a-service.md
           - Expose a Ballerina GraphQL Endpoint via a Service: develop-components/develop-services/expose-a-ballerina-graphql-endpoint-via-a-service.md
           - Expose a Prism-Based Mock Server Using an OpenAPI Specification: develop-components/develop-services/expose-a-prism-based-mock-server-using-an-openapi-specification.md
+          - Expose a WebSocket Endpoint via a NodeJS Service: develop-components/develop-services/expose-a-nodejs-websocket-endpoint-via-a-service.md
       - Develop an API Proxy: develop-components/develop-an-api-proxy.md
       - Develop Web Applications: 
           - Build and Deploy a Single-Page Web Application: develop-components/develop-web-applications/build-and-deploy-a-single-page-web-application.md
@@ -168,6 +169,7 @@ nav:
   - Testing: 
       - Test REST Endpoints via the OpenAPI Console: testing/test-rest-endpoints-via-the-openapi-console.md
       - Test GraphQL Endpoints via the GraphQL Console: testing/test-graphql-endpoints-via-the-graphql-console.md
+      - Test WebSocket Endpoints via the WebSocket Console: testing/test-websocket-endpoints-via-the-websocket-console.md
       - Test APIs with cURL: testing/test-apis-with-curl.md
       - Test APIs with Choreo API Chat: testing/test-apis-with-choreo-apichat.md
       - Test Components with Test Runner: testing/test-components-with-test-runner.md