From cfd1e5fecd53dd6ca3079f87dd14e865dec75b30 Mon Sep 17 00:00:00 2001 From: Afzal Ansari Date: Fri, 3 Nov 2023 06:15:30 +0000 Subject: [PATCH 01/10] add extension for glee project --- config/edit-page-config.json | 4 ++++ pages/docs/tools/glee/_section.md | 4 ++++ 2 files changed, 8 insertions(+) create mode 100644 pages/docs/tools/glee/_section.md diff --git a/config/edit-page-config.json b/config/edit-page-config.json index a622b600facc..deb663bab5c4 100644 --- a/config/edit-page-config.json +++ b/config/edit-page-config.json @@ -11,6 +11,10 @@ "value":"/tools/cli", "href":"https://github.com/asyncapi/cli/tree/master/docs" }, + { + "value":"/tools/glee", + "href":"https://github.com/asyncapi/glee/tree/master/docs/pages" + }, { "value": "", "href": "https://github.com/asyncapi/website/blob/master/pages" diff --git a/pages/docs/tools/glee/_section.md b/pages/docs/tools/glee/_section.md new file mode 100644 index 000000000000..126965282461 --- /dev/null +++ b/pages/docs/tools/glee/_section.md @@ -0,0 +1,4 @@ +--- +title: Glee +weight: 10 +--- \ No newline at end of file From 5924e16b98650f24620fca1574bca04e871b16e7 Mon Sep 17 00:00:00 2001 From: Afzal Ansari Date: Tue, 21 Nov 2023 15:33:38 +0000 Subject: [PATCH 02/10] tests index page --- pages/docs/tools/glee/index.md | 127 +++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 pages/docs/tools/glee/index.md diff --git a/pages/docs/tools/glee/index.md b/pages/docs/tools/glee/index.md new file mode 100644 index 000000000000..e19a1a066184 --- /dev/null +++ b/pages/docs/tools/glee/index.md @@ -0,0 +1,127 @@ +--- +title: 'Installation guide' +weight: 30 +--- + +## Glee Installation + +Before installing Glee into your project, make sure you have pre-installed NPM, NodeJs and [AsyncAPI CLI](https://github.com/asyncapi/cli) tools on your system. + +### Automatic Installation + +The best way to get started with Glee is by using AsyncAPI CLI, which sets up everything automatically for you. +To create a project, run: + +```sh +asyncapi new glee +``` + +> For more information on how to install the AsynAPI CLI, you can review the [CLI installation guide](https://www.asyncapi.com/docs/tools/cli/installation). + +On installation, you'll find next steps after your project created: + +``` +Your project "project" has been created successfully! + +Next steps: + + cd project + npm install + npm run dev + +Also, you can already open the project in your favorite editor and start tweaking it +``` + +While making twists to your application, you can follow along with our getting started guide on the relevant page. + +### Manual Installation + +To manually create a new app, create a new folder e.g. `myapp` so the folder structure would look like below; + +``` +├─ functions (required) +│ ├─ onHello.js +│ └─ ... +├─ lifecycle (optional) +│ ├─ onConnect.js +│ └─ ... +├─ .env (optional) +├─ asyncapi.(yaml | yml | json) (required) +├─ glee.config.js (optional) +├─ package.json (required) +``` + +Install the required packages inside a new folder: + +```js +npm init -y +npm install @asyncapi/glee +``` + +Open your package.json file and add the following scripts: + +```js +{ + "scripts": { + "docs": "glee docs", + "dev": "glee dev", + "start": "glee start", + } +} +``` + +These scripts refer to the different stages of developing an application. + +- `glee docs`: This script generates documentation for your project using the "Glee" documentation tool. This documentation includes information about your project's APIs, modules, and usage instructions. + +- `glee dev`: This script is used for starting a development server. It launches a local development server, build your project in development mode, or perform other development-related tasks. + +- `glee start`: This script is responsible for starting your project or application. It is used to launch a production-ready server or application instance. + +#### Creating `asyncapi.yaml` file and other required directories + +Create a yaml file that supports capable of receiving a "hello {name}" message with the protocol as `ws` and the channel name as `hello` the hello API will subscribe to. The operationId property is `onHello` that's the name of function and the payload property is type string publishing to that channel. + +```yaml +asyncapi: 2.6.0 +info: + title: Hello, Glee! + version: 0.1.0 + +servers: + websockets: + url: ws://0.0.0.0:3000 + protocol: ws + +channels: + hello: + publish: + operationId: onHello + message: + $ref: '#/components/messages/hello' + subscribe: + message: + $ref: '#/components/messages/hello' + +components: + messages: + hello: + payload: + type: string +``` + +Create an operation function `onHello.js` inside `myapp/functions`: + +```js +export default async function (event) { + return { + reply: [{ + payload: `Hello from Glee! You said: "${event.payload}".` + }] + } +} + +#### Run the Development Server + +- Run `npm run dev` to start the development server. +- Connect to `ws://localhost:3000/hello` and send a WebSocket request with a payload e.g. {"john"} \ No newline at end of file From 99690c8a0d8711c94837446a6c0cdd693d3ca9ec Mon Sep 17 00:00:00 2001 From: Afzal Ansari Date: Tue, 21 Nov 2023 15:50:24 +0000 Subject: [PATCH 03/10] tests intro page --- pages/docs/tools/glee/intro.md | 142 +++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 pages/docs/tools/glee/intro.md diff --git a/pages/docs/tools/glee/intro.md b/pages/docs/tools/glee/intro.md new file mode 100644 index 000000000000..aa1b5f18e633 --- /dev/null +++ b/pages/docs/tools/glee/intro.md @@ -0,0 +1,142 @@ +--- +title: Getting Started +weight: 80 +--- + +## Introduction + +[Glee](https://github.com/asyncapi/glee) is a spec-first framework that helps you build server-side applications. That means it operates on the principle of defining the API specification (AsyncAPI) before diving into the actual implementation of the application logic. It leverages that principle to make you more productive: + +- Glee ensures your code and AsyncAPI definition are on par, eliminating the problem of outdated documentation. By having both the code and the AsyncAPI definition in sync, you can ensure that the API documentation is always up to date, accurate, and reflects the current state of the application. Glee takes care of this automatically for you. +- Glee lets you focus on what matters and handles the rest for you. You only write the code for your business use-case. Glee takes care of performance, scalability, resilience, and everything you need to make your application production-ready. +- Glee validates the schema of the payload that it receives, if it doesn't conform to the schema that is defined in the AsyncAPI document, it throw an error telling user that the server received an invalid payload. + +Now, before you get started with a glee project, let's take a high level view of Application structure what glee resonates with. + +## Application structure + +Glee expects your project to have some files and folders with special names. When you run `asyncapi new glee`, [AsyncAPI CLI](https://github.com/asyncapi/cli) generates a boilerplate application structure by creating a new folder and populating an initial set of files as shown below. You can continue working in this default structure, adding new components, as described throughout the documentation of asyncapi cli. + +``` +├─ functions (required) +│ ├─ onHello.js +│ └─ ... +├─ lifecycle (optional) +│ ├─ onConnect.js +│ └─ ... +├─ .env (optional) +├─ asyncapi.(yaml | yml | json) (required) +├─ glee.config.js (optional) +├─ package.json (required) +``` + +|File/Directory|Description| +|---|---| +|functions|**Required.** This directory contains all the functions that Glee must execute when it receives a message from the server. Each file must export a default async function. +|lifecycle|This directory contains application lifecycle functions. These functions will be executed when certain events happen in the application. E.g., `onConnect`, `onServerReady`, `onDisconnect`, etc. +|.env|The environment variables of your application. **DO NOT PUT SECRETS HERE**. +|asyncapi.(yaml or json or yml)|**Required.** The [AsyncAPI](https://www.asyncapi.com/docs/specifications/latest) file defines your API. Make sure all the `publish` operations have an assigned `operationId` that matches a file name (excluding the extension) in the `functions` directory. +|glee.config.js| The Glee configuration file. +|package.json|**Required.** The Node.js package definition file. Make sure you include `@asyncapi/glee` as a dependency and add two scripts: `dev` and `start`. They should be running `glee dev` and `glee start` respectively. + +To understand the structure in a broader way, please refer to the associated page's links. + +### Let's create a glee project to simplify the app structure + +We will consider a simple WebSocket API using glee to understand its magic. We will create a simple WebSocket server that receives a current time from the client and then send a "good morning", "good evening" or "good night" respectively. + +To setup a project, you should follow our installation page on how to setup glee on your environment. + +We recommend creating a new Glee app using our official CLI which sets up everything automatically. (You don't need to create an empty directory. create-glee-app will make one for you.) To create a project, run: `asyncapi new glee` + +Once the process is completed, you should have a new Glee app ready for development and see these files that were made. + +![glee_structure](/assets/glee_struct.png) + +#### Define our Spec for our API + +Glee being a spec-first framework, development starts with defining your API spec. To know more details into it, you can follow glee template to understand it step by step. For our case we will define our API: + +```yaml +asyncapi: 3.0.0 +info: + title: Greet Bot + version: 0.1.0 +servers: + websockets: + url: ws://0.0.0.0:3000 + protocol: ws +channels: + greet: + publish: + operationId: onGreet + message: + $ref: '#/components/messages/time' + subscribe: + message: + $ref: '#/components/messages/greet' +components: + messages: + time: + payload: + type: object + properties: + currentTime: + type: number + name: + type: string + greet: + payload: + type: string + +``` + +This will be the Specification that defines our API, in our case, it is very simple, as we will be sending a name and the time of the day, and our API will greet us accordingly. + +One thing to note here is the `operationId`, this is needed and is a crucial part of glee, as this is how we will be connecting our business logic with our spec, `operationId` is the name of the function that will be called every time a certain operation occurs. In our case whenever `/greet` channel received a message. + +#### Define our operation function + +Now for our case, we will be adding a file `functions/onGreet.js` and writing up the logic for parsing our time and sending a response. + +```javascript +export default async function (event) { + const { name, time } = event.payload + const t = new Date(time) + const curHr = t.getHours() + let response = '' + if (curHr < 12) { + response = `Good Morning ${name}` + } else if (curHr < 18) { + response = `Good Afternoon ${name}` + } else { + response = `Good Evening ${name}` + } + return { + reply: [ + { + payload: response, + }, + ], + } +} + +``` + +Every file in the functions folder acts as a handler to develop business logic for glee, every file should export an async function that receives an event parameter, where you have access to payload and server details. + +Running and testing your application +We will not execute the application and carry out testing with Postman to ensure that it is functioning as intended. + +Now to run your glee application, just run: + +``` +npm run dev +# or +npm run start +``` +To send a WebSocket request with a payload e.g. `{"name":"john", "time": "1567906535"}` to `ws://localhost:3000/greet`, open Postman and checkout the endpoint: + +![glee_response](/assets/glee_resp.png) + +So, this is how easy it is to build a WebSocket API using Glee. You can also check out the example code [here](https://github.com/Souvikns/greet-bot). \ No newline at end of file From db891698fe861cb5328dd98b2b154329ae6c03aa Mon Sep 17 00:00:00 2001 From: Afzal Ansari Date: Tue, 21 Nov 2023 15:52:01 +0000 Subject: [PATCH 04/10] update to v3 --- pages/docs/tools/glee/index.md | 4 ++-- pages/docs/tools/glee/intro.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/pages/docs/tools/glee/index.md b/pages/docs/tools/glee/index.md index e19a1a066184..807dd0c50e67 100644 --- a/pages/docs/tools/glee/index.md +++ b/pages/docs/tools/glee/index.md @@ -83,14 +83,14 @@ These scripts refer to the different stages of developing an application. Create a yaml file that supports capable of receiving a "hello {name}" message with the protocol as `ws` and the channel name as `hello` the hello API will subscribe to. The operationId property is `onHello` that's the name of function and the payload property is type string publishing to that channel. ```yaml -asyncapi: 2.6.0 +asyncapi: 3.0.0 info: title: Hello, Glee! version: 0.1.0 servers: websockets: - url: ws://0.0.0.0:3000 + host: 0.0.0.0:3000 protocol: ws channels: diff --git a/pages/docs/tools/glee/intro.md b/pages/docs/tools/glee/intro.md index aa1b5f18e633..596356f1a8d0 100644 --- a/pages/docs/tools/glee/intro.md +++ b/pages/docs/tools/glee/intro.md @@ -64,7 +64,7 @@ info: version: 0.1.0 servers: websockets: - url: ws://0.0.0.0:3000 + host: 0.0.0.0:3000 protocol: ws channels: greet: From af5301f65bb9fdc4085564fc146809a82bb71ead Mon Sep 17 00:00:00 2001 From: Afzal Ansari Date: Tue, 21 Nov 2023 16:01:24 +0000 Subject: [PATCH 05/10] fmts the syntax and typos --- pages/docs/tools/glee/index.md | 1 + pages/docs/tools/glee/intro.md | 5 +++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/pages/docs/tools/glee/index.md b/pages/docs/tools/glee/index.md index 807dd0c50e67..d157594f5e7a 100644 --- a/pages/docs/tools/glee/index.md +++ b/pages/docs/tools/glee/index.md @@ -120,6 +120,7 @@ export default async function (event) { }] } } +``` #### Run the Development Server diff --git a/pages/docs/tools/glee/intro.md b/pages/docs/tools/glee/intro.md index 596356f1a8d0..658d580835ad 100644 --- a/pages/docs/tools/glee/intro.md +++ b/pages/docs/tools/glee/intro.md @@ -125,8 +125,9 @@ export default async function (event) { Every file in the functions folder acts as a handler to develop business logic for glee, every file should export an async function that receives an event parameter, where you have access to payload and server details. -Running and testing your application -We will not execute the application and carry out testing with Postman to ensure that it is functioning as intended. +#### Running and testing your application + +We will execute the application and carry out testing with Postman to ensure that it is functioning as intended. Now to run your glee application, just run: From 35ccb312fd7dfa5137060e7ece1fb4644f55313b Mon Sep 17 00:00:00 2001 From: Afzal Ansari Date: Tue, 21 Nov 2023 16:06:04 +0000 Subject: [PATCH 06/10] updates the struct --- pages/docs/tools/glee/index.md | 155 ++++++++++++++------------ pages/docs/tools/glee/installation.md | 128 +++++++++++++++++++++ pages/docs/tools/glee/intro.md | 143 ------------------------ 3 files changed, 213 insertions(+), 213 deletions(-) create mode 100644 pages/docs/tools/glee/installation.md delete mode 100644 pages/docs/tools/glee/intro.md diff --git a/pages/docs/tools/glee/index.md b/pages/docs/tools/glee/index.md index d157594f5e7a..658d580835ad 100644 --- a/pages/docs/tools/glee/index.md +++ b/pages/docs/tools/glee/index.md @@ -1,42 +1,21 @@ --- -title: 'Installation guide' -weight: 30 +title: Getting Started +weight: 80 --- -## Glee Installation +## Introduction -Before installing Glee into your project, make sure you have pre-installed NPM, NodeJs and [AsyncAPI CLI](https://github.com/asyncapi/cli) tools on your system. +[Glee](https://github.com/asyncapi/glee) is a spec-first framework that helps you build server-side applications. That means it operates on the principle of defining the API specification (AsyncAPI) before diving into the actual implementation of the application logic. It leverages that principle to make you more productive: -### Automatic Installation +- Glee ensures your code and AsyncAPI definition are on par, eliminating the problem of outdated documentation. By having both the code and the AsyncAPI definition in sync, you can ensure that the API documentation is always up to date, accurate, and reflects the current state of the application. Glee takes care of this automatically for you. +- Glee lets you focus on what matters and handles the rest for you. You only write the code for your business use-case. Glee takes care of performance, scalability, resilience, and everything you need to make your application production-ready. +- Glee validates the schema of the payload that it receives, if it doesn't conform to the schema that is defined in the AsyncAPI document, it throw an error telling user that the server received an invalid payload. -The best way to get started with Glee is by using AsyncAPI CLI, which sets up everything automatically for you. -To create a project, run: +Now, before you get started with a glee project, let's take a high level view of Application structure what glee resonates with. -```sh -asyncapi new glee -``` - -> For more information on how to install the AsynAPI CLI, you can review the [CLI installation guide](https://www.asyncapi.com/docs/tools/cli/installation). - -On installation, you'll find next steps after your project created: - -``` -Your project "project" has been created successfully! - -Next steps: - - cd project - npm install - npm run dev - -Also, you can already open the project in your favorite editor and start tweaking it -``` - -While making twists to your application, you can follow along with our getting started guide on the relevant page. +## Application structure -### Manual Installation - -To manually create a new app, create a new folder e.g. `myapp` so the folder structure would look like below; +Glee expects your project to have some files and folders with special names. When you run `asyncapi new glee`, [AsyncAPI CLI](https://github.com/asyncapi/cli) generates a boilerplate application structure by creating a new folder and populating an initial set of files as shown below. You can continue working in this default structure, adding new components, as described throughout the documentation of asyncapi cli. ``` ├─ functions (required) @@ -51,78 +30,114 @@ To manually create a new app, create a new folder e.g. `myapp` so the folder str ├─ package.json (required) ``` -Install the required packages inside a new folder: +|File/Directory|Description| +|---|---| +|functions|**Required.** This directory contains all the functions that Glee must execute when it receives a message from the server. Each file must export a default async function. +|lifecycle|This directory contains application lifecycle functions. These functions will be executed when certain events happen in the application. E.g., `onConnect`, `onServerReady`, `onDisconnect`, etc. +|.env|The environment variables of your application. **DO NOT PUT SECRETS HERE**. +|asyncapi.(yaml or json or yml)|**Required.** The [AsyncAPI](https://www.asyncapi.com/docs/specifications/latest) file defines your API. Make sure all the `publish` operations have an assigned `operationId` that matches a file name (excluding the extension) in the `functions` directory. +|glee.config.js| The Glee configuration file. +|package.json|**Required.** The Node.js package definition file. Make sure you include `@asyncapi/glee` as a dependency and add two scripts: `dev` and `start`. They should be running `glee dev` and `glee start` respectively. -```js -npm init -y -npm install @asyncapi/glee -``` +To understand the structure in a broader way, please refer to the associated page's links. -Open your package.json file and add the following scripts: +### Let's create a glee project to simplify the app structure -```js -{ - "scripts": { - "docs": "glee docs", - "dev": "glee dev", - "start": "glee start", - } -} -``` +We will consider a simple WebSocket API using glee to understand its magic. We will create a simple WebSocket server that receives a current time from the client and then send a "good morning", "good evening" or "good night" respectively. -These scripts refer to the different stages of developing an application. +To setup a project, you should follow our installation page on how to setup glee on your environment. -- `glee docs`: This script generates documentation for your project using the "Glee" documentation tool. This documentation includes information about your project's APIs, modules, and usage instructions. +We recommend creating a new Glee app using our official CLI which sets up everything automatically. (You don't need to create an empty directory. create-glee-app will make one for you.) To create a project, run: `asyncapi new glee` -- `glee dev`: This script is used for starting a development server. It launches a local development server, build your project in development mode, or perform other development-related tasks. +Once the process is completed, you should have a new Glee app ready for development and see these files that were made. -- `glee start`: This script is responsible for starting your project or application. It is used to launch a production-ready server or application instance. +![glee_structure](/assets/glee_struct.png) -#### Creating `asyncapi.yaml` file and other required directories +#### Define our Spec for our API -Create a yaml file that supports capable of receiving a "hello {name}" message with the protocol as `ws` and the channel name as `hello` the hello API will subscribe to. The operationId property is `onHello` that's the name of function and the payload property is type string publishing to that channel. +Glee being a spec-first framework, development starts with defining your API spec. To know more details into it, you can follow glee template to understand it step by step. For our case we will define our API: ```yaml asyncapi: 3.0.0 info: - title: Hello, Glee! + title: Greet Bot version: 0.1.0 - servers: websockets: host: 0.0.0.0:3000 protocol: ws - channels: - hello: + greet: publish: - operationId: onHello + operationId: onGreet message: - $ref: '#/components/messages/hello' + $ref: '#/components/messages/time' subscribe: message: - $ref: '#/components/messages/hello' - + $ref: '#/components/messages/greet' components: messages: - hello: + time: + payload: + type: object + properties: + currentTime: + type: number + name: + type: string + greet: payload: type: string + ``` -Create an operation function `onHello.js` inside `myapp/functions`: +This will be the Specification that defines our API, in our case, it is very simple, as we will be sending a name and the time of the day, and our API will greet us accordingly. -```js -export default async function (event) { +One thing to note here is the `operationId`, this is needed and is a crucial part of glee, as this is how we will be connecting our business logic with our spec, `operationId` is the name of the function that will be called every time a certain operation occurs. In our case whenever `/greet` channel received a message. + +#### Define our operation function + +Now for our case, we will be adding a file `functions/onGreet.js` and writing up the logic for parsing our time and sending a response. + +```javascript +export default async function (event) { + const { name, time } = event.payload + const t = new Date(time) + const curHr = t.getHours() + let response = '' + if (curHr < 12) { + response = `Good Morning ${name}` + } else if (curHr < 18) { + response = `Good Afternoon ${name}` + } else { + response = `Good Evening ${name}` + } return { - reply: [{ - payload: `Hello from Glee! You said: "${event.payload}".` - }] + reply: [ + { + payload: response, + }, + ], } } + +``` + +Every file in the functions folder acts as a handler to develop business logic for glee, every file should export an async function that receives an event parameter, where you have access to payload and server details. + +#### Running and testing your application + +We will execute the application and carry out testing with Postman to ensure that it is functioning as intended. + +Now to run your glee application, just run: + +``` +npm run dev +# or +npm run start ``` +To send a WebSocket request with a payload e.g. `{"name":"john", "time": "1567906535"}` to `ws://localhost:3000/greet`, open Postman and checkout the endpoint: -#### Run the Development Server +![glee_response](/assets/glee_resp.png) -- Run `npm run dev` to start the development server. -- Connect to `ws://localhost:3000/hello` and send a WebSocket request with a payload e.g. {"john"} \ No newline at end of file +So, this is how easy it is to build a WebSocket API using Glee. You can also check out the example code [here](https://github.com/Souvikns/greet-bot). \ No newline at end of file diff --git a/pages/docs/tools/glee/installation.md b/pages/docs/tools/glee/installation.md new file mode 100644 index 000000000000..d157594f5e7a --- /dev/null +++ b/pages/docs/tools/glee/installation.md @@ -0,0 +1,128 @@ +--- +title: 'Installation guide' +weight: 30 +--- + +## Glee Installation + +Before installing Glee into your project, make sure you have pre-installed NPM, NodeJs and [AsyncAPI CLI](https://github.com/asyncapi/cli) tools on your system. + +### Automatic Installation + +The best way to get started with Glee is by using AsyncAPI CLI, which sets up everything automatically for you. +To create a project, run: + +```sh +asyncapi new glee +``` + +> For more information on how to install the AsynAPI CLI, you can review the [CLI installation guide](https://www.asyncapi.com/docs/tools/cli/installation). + +On installation, you'll find next steps after your project created: + +``` +Your project "project" has been created successfully! + +Next steps: + + cd project + npm install + npm run dev + +Also, you can already open the project in your favorite editor and start tweaking it +``` + +While making twists to your application, you can follow along with our getting started guide on the relevant page. + +### Manual Installation + +To manually create a new app, create a new folder e.g. `myapp` so the folder structure would look like below; + +``` +├─ functions (required) +│ ├─ onHello.js +│ └─ ... +├─ lifecycle (optional) +│ ├─ onConnect.js +│ └─ ... +├─ .env (optional) +├─ asyncapi.(yaml | yml | json) (required) +├─ glee.config.js (optional) +├─ package.json (required) +``` + +Install the required packages inside a new folder: + +```js +npm init -y +npm install @asyncapi/glee +``` + +Open your package.json file and add the following scripts: + +```js +{ + "scripts": { + "docs": "glee docs", + "dev": "glee dev", + "start": "glee start", + } +} +``` + +These scripts refer to the different stages of developing an application. + +- `glee docs`: This script generates documentation for your project using the "Glee" documentation tool. This documentation includes information about your project's APIs, modules, and usage instructions. + +- `glee dev`: This script is used for starting a development server. It launches a local development server, build your project in development mode, or perform other development-related tasks. + +- `glee start`: This script is responsible for starting your project or application. It is used to launch a production-ready server or application instance. + +#### Creating `asyncapi.yaml` file and other required directories + +Create a yaml file that supports capable of receiving a "hello {name}" message with the protocol as `ws` and the channel name as `hello` the hello API will subscribe to. The operationId property is `onHello` that's the name of function and the payload property is type string publishing to that channel. + +```yaml +asyncapi: 3.0.0 +info: + title: Hello, Glee! + version: 0.1.0 + +servers: + websockets: + host: 0.0.0.0:3000 + protocol: ws + +channels: + hello: + publish: + operationId: onHello + message: + $ref: '#/components/messages/hello' + subscribe: + message: + $ref: '#/components/messages/hello' + +components: + messages: + hello: + payload: + type: string +``` + +Create an operation function `onHello.js` inside `myapp/functions`: + +```js +export default async function (event) { + return { + reply: [{ + payload: `Hello from Glee! You said: "${event.payload}".` + }] + } +} +``` + +#### Run the Development Server + +- Run `npm run dev` to start the development server. +- Connect to `ws://localhost:3000/hello` and send a WebSocket request with a payload e.g. {"john"} \ No newline at end of file diff --git a/pages/docs/tools/glee/intro.md b/pages/docs/tools/glee/intro.md deleted file mode 100644 index 658d580835ad..000000000000 --- a/pages/docs/tools/glee/intro.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Getting Started -weight: 80 ---- - -## Introduction - -[Glee](https://github.com/asyncapi/glee) is a spec-first framework that helps you build server-side applications. That means it operates on the principle of defining the API specification (AsyncAPI) before diving into the actual implementation of the application logic. It leverages that principle to make you more productive: - -- Glee ensures your code and AsyncAPI definition are on par, eliminating the problem of outdated documentation. By having both the code and the AsyncAPI definition in sync, you can ensure that the API documentation is always up to date, accurate, and reflects the current state of the application. Glee takes care of this automatically for you. -- Glee lets you focus on what matters and handles the rest for you. You only write the code for your business use-case. Glee takes care of performance, scalability, resilience, and everything you need to make your application production-ready. -- Glee validates the schema of the payload that it receives, if it doesn't conform to the schema that is defined in the AsyncAPI document, it throw an error telling user that the server received an invalid payload. - -Now, before you get started with a glee project, let's take a high level view of Application structure what glee resonates with. - -## Application structure - -Glee expects your project to have some files and folders with special names. When you run `asyncapi new glee`, [AsyncAPI CLI](https://github.com/asyncapi/cli) generates a boilerplate application structure by creating a new folder and populating an initial set of files as shown below. You can continue working in this default structure, adding new components, as described throughout the documentation of asyncapi cli. - -``` -├─ functions (required) -│ ├─ onHello.js -│ └─ ... -├─ lifecycle (optional) -│ ├─ onConnect.js -│ └─ ... -├─ .env (optional) -├─ asyncapi.(yaml | yml | json) (required) -├─ glee.config.js (optional) -├─ package.json (required) -``` - -|File/Directory|Description| -|---|---| -|functions|**Required.** This directory contains all the functions that Glee must execute when it receives a message from the server. Each file must export a default async function. -|lifecycle|This directory contains application lifecycle functions. These functions will be executed when certain events happen in the application. E.g., `onConnect`, `onServerReady`, `onDisconnect`, etc. -|.env|The environment variables of your application. **DO NOT PUT SECRETS HERE**. -|asyncapi.(yaml or json or yml)|**Required.** The [AsyncAPI](https://www.asyncapi.com/docs/specifications/latest) file defines your API. Make sure all the `publish` operations have an assigned `operationId` that matches a file name (excluding the extension) in the `functions` directory. -|glee.config.js| The Glee configuration file. -|package.json|**Required.** The Node.js package definition file. Make sure you include `@asyncapi/glee` as a dependency and add two scripts: `dev` and `start`. They should be running `glee dev` and `glee start` respectively. - -To understand the structure in a broader way, please refer to the associated page's links. - -### Let's create a glee project to simplify the app structure - -We will consider a simple WebSocket API using glee to understand its magic. We will create a simple WebSocket server that receives a current time from the client and then send a "good morning", "good evening" or "good night" respectively. - -To setup a project, you should follow our installation page on how to setup glee on your environment. - -We recommend creating a new Glee app using our official CLI which sets up everything automatically. (You don't need to create an empty directory. create-glee-app will make one for you.) To create a project, run: `asyncapi new glee` - -Once the process is completed, you should have a new Glee app ready for development and see these files that were made. - -![glee_structure](/assets/glee_struct.png) - -#### Define our Spec for our API - -Glee being a spec-first framework, development starts with defining your API spec. To know more details into it, you can follow glee template to understand it step by step. For our case we will define our API: - -```yaml -asyncapi: 3.0.0 -info: - title: Greet Bot - version: 0.1.0 -servers: - websockets: - host: 0.0.0.0:3000 - protocol: ws -channels: - greet: - publish: - operationId: onGreet - message: - $ref: '#/components/messages/time' - subscribe: - message: - $ref: '#/components/messages/greet' -components: - messages: - time: - payload: - type: object - properties: - currentTime: - type: number - name: - type: string - greet: - payload: - type: string - -``` - -This will be the Specification that defines our API, in our case, it is very simple, as we will be sending a name and the time of the day, and our API will greet us accordingly. - -One thing to note here is the `operationId`, this is needed and is a crucial part of glee, as this is how we will be connecting our business logic with our spec, `operationId` is the name of the function that will be called every time a certain operation occurs. In our case whenever `/greet` channel received a message. - -#### Define our operation function - -Now for our case, we will be adding a file `functions/onGreet.js` and writing up the logic for parsing our time and sending a response. - -```javascript -export default async function (event) { - const { name, time } = event.payload - const t = new Date(time) - const curHr = t.getHours() - let response = '' - if (curHr < 12) { - response = `Good Morning ${name}` - } else if (curHr < 18) { - response = `Good Afternoon ${name}` - } else { - response = `Good Evening ${name}` - } - return { - reply: [ - { - payload: response, - }, - ], - } -} - -``` - -Every file in the functions folder acts as a handler to develop business logic for glee, every file should export an async function that receives an event parameter, where you have access to payload and server details. - -#### Running and testing your application - -We will execute the application and carry out testing with Postman to ensure that it is functioning as intended. - -Now to run your glee application, just run: - -``` -npm run dev -# or -npm run start -``` -To send a WebSocket request with a payload e.g. `{"name":"john", "time": "1567906535"}` to `ws://localhost:3000/greet`, open Postman and checkout the endpoint: - -![glee_response](/assets/glee_resp.png) - -So, this is how easy it is to build a WebSocket API using Glee. You can also check out the example code [here](https://github.com/Souvikns/greet-bot). \ No newline at end of file From fbf9bd27f10dd9d83180c7e976021ef7bff3feb5 Mon Sep 17 00:00:00 2001 From: Afzal Ansari Date: Sat, 25 Nov 2023 17:40:14 +0000 Subject: [PATCH 07/10] adds glee temp page --- pages/docs/tools/glee/glee-template.md | 89 ++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 pages/docs/tools/glee/glee-template.md diff --git a/pages/docs/tools/glee/glee-template.md b/pages/docs/tools/glee/glee-template.md new file mode 100644 index 000000000000..efa9dcc57c87 --- /dev/null +++ b/pages/docs/tools/glee/glee-template.md @@ -0,0 +1,89 @@ +--- +title: "Create AsyncAPI Glee template" +weight: 170 +--- +This tutorial teaches you how to create a simple glee template. You'll use the AsyncAPI Glee template you develop to generate Javascript code. Additionally, you'll create a template code with a reusable component to reuse the custom functionality you create and test your code using an WS server. + + +{`asyncapi: '3.0.0' +info: + title: Hello, Glee! + version: '0.1.0' + +servers: + websockets: + url: ws://0.0.0.0:3000 + protocol: ws + +channels: + hello: + publish: + operationId: onHello + message: + $ref: '#/components/messages/hello' + subscribe: + message: + $ref: '#/components/messages/hello' + +components: + messages: + hello: + payload: + type: string`} + + +Let's break it down into pieces: + + +{`info: + title: Hello, Glee! + version: '0.1.0'`} + + +The `info` section provides general information about the API, including its title and version. + +Moving on, let's talk about the `servers` section. + + +{`servers: + mosquitto: + url: ws://0.0.0.0:3000 + protocol: ws`} + + +The servers section defines the different servers where the API can be accessed. In this case, there is a single server named "websockets" that uses the WebSocket protocol (`ws`) and listens on the address `ws://0.0.0.0:3000`. + +Now lets move on to the `channels` section. This section is used to describe the event names your API will be publishing and/or subscribing to. + + +{`channels: + hello: + publish: + operationId: onHello + message: + $ref: '#/components/messages/hello' + subscribe: + message: + $ref: '#/components/messages/hello'`} + + +The channels section defines the communication channels available in the API. In this case, there's a channel named "hello". This channel supports both publishing and subscribing. + +The `publish` section specifies that the operation with ID onHello is used for publishing to the `hello` channel. The message structure is referenced from the hello message component. +The `subscribe` section indicates that messages received on the `hello` channel should follow the structure defined in the hello message component. + +Next is the `payload` property under `hello` message component which is used to understand how the event should look like when publishing to that channel: + + +{`components: + messages: + hello: + payload: + type: string`} + + +The components section contains reusable elements, in this case, a definition for the "hello" message. It specifies that the payload of the "hello" message should be of type string. + +## Summary + +In this tutorial, you learned how to create an AsyncAPI specification document via a simple example with a glee template. \ No newline at end of file From b4294f7031aabc4f53362458d1424f1d1de91447 Mon Sep 17 00:00:00 2001 From: Afzal Ansari Date: Sat, 25 Nov 2023 17:47:47 +0000 Subject: [PATCH 08/10] fixes the syntax err --- pages/docs/tools/glee/glee-template.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/pages/docs/tools/glee/glee-template.md b/pages/docs/tools/glee/glee-template.md index efa9dcc57c87..d37b9122b444 100644 --- a/pages/docs/tools/glee/glee-template.md +++ b/pages/docs/tools/glee/glee-template.md @@ -9,12 +9,10 @@ This tutorial teaches you how to create a simple glee template. You'll use the A info: title: Hello, Glee! version: '0.1.0' - servers: websockets: url: ws://0.0.0.0:3000 protocol: ws - channels: hello: publish: @@ -24,7 +22,6 @@ channels: subscribe: message: $ref: '#/components/messages/hello' - components: messages: hello: From 6d8a5de43f989bdeca02ff3c35793ea58a47c498 Mon Sep 17 00:00:00 2001 From: Afzal Ansari Date: Mon, 4 Dec 2023 21:44:25 +0530 Subject: [PATCH 09/10] Undo edit-page-config.json --- config/edit-page-config.json | 4 ---- 1 file changed, 4 deletions(-) diff --git a/config/edit-page-config.json b/config/edit-page-config.json index deb663bab5c4..a622b600facc 100644 --- a/config/edit-page-config.json +++ b/config/edit-page-config.json @@ -11,10 +11,6 @@ "value":"/tools/cli", "href":"https://github.com/asyncapi/cli/tree/master/docs" }, - { - "value":"/tools/glee", - "href":"https://github.com/asyncapi/glee/tree/master/docs/pages" - }, { "value": "", "href": "https://github.com/asyncapi/website/blob/master/pages" From 34e1aed53a6bfb62a6c35861c54bd9e5e9d3b644 Mon Sep 17 00:00:00 2001 From: Afzal Ansari Date: Mon, 4 Dec 2023 23:01:23 +0530 Subject: [PATCH 10/10] Delete pages/docs/tools/glee/_section.md --- pages/docs/tools/glee/_section.md | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 pages/docs/tools/glee/_section.md diff --git a/pages/docs/tools/glee/_section.md b/pages/docs/tools/glee/_section.md deleted file mode 100644 index 126965282461..000000000000 --- a/pages/docs/tools/glee/_section.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Glee -weight: 10 ---- \ No newline at end of file