diff --git a/docs/app-structure.md b/docs/app-structure.md deleted file mode 100644 index 7c9572130..000000000 --- a/docs/app-structure.md +++ /dev/null @@ -1,26 +0,0 @@ -# Application structure - -Glee expects your project to have some files and folders with special names. The best way to get started with Glee is using [AsyncAPI CLI](https://github.com/asyncapi/cli) and running `asyncapi new glee`, which sets up everything automatically for you. - -``` -├─ 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. [Read more about the functions signature](./functions.md). -|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. [Read the full list of lifecycle events](./lifecycle-events.md). -|.env|The environment variables of your application. Read more about the Glee [environment variables](./env-vars.md). **DO NOT PUT SECRETS HERE**. -|asyncapi.(yaml | json | yml)|**Required.** The [AsyncAPI](https://www.asyncapi.com/docs/specifications/latest) file defining 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. [Read more about how to use this file](./config-file.md). -|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. - diff --git a/docs/config-file.md b/docs/env-vars-config.md similarity index 89% rename from docs/config-file.md rename to docs/env-vars-config.md index 713df350a..0a4e1b4e9 100644 --- a/docs/config-file.md +++ b/docs/env-vars-config.md @@ -1,4 +1,18 @@ -# Configuring Glee +--- +title: Environment variables and Configuration file +weight: 80 +--- + +# Environment Variables + +Glee provides a few environment variables for you to customize the experience: +|Variable|Description|Example| +|---|---|---| +|GLEE_SERVER_NAMES|A comma-separated list of the servers to load on startup.|`GLEE_SERVER_NAMES=websockets,mosquitto` +|GLEE_SERVER_CERTS|A comma-separated list of `${serverName}:${pathToCertificateFile}`. These are the certificates to use when establishing the connection to the given server.|`GLEE_SERVER_CERTS=mosquitto:mosquitto.org.crt` +|GLEE_SERVER_VARIABLES|A comma-separated list of `${serverName}:${serverVariable}:${value}`. These are the values to use for each server variable.|`GLEE_SERVER_VARIABLES=websockets:namespace:public` + + Configuring Glee Glee comes with sensible defaults so you don't have to worry about configuration. However, sometimes you may want to change the behavior or customize Glee in different ways. For that purpose, you can use the `glee.config.js` file. @@ -18,11 +32,10 @@ This function must return an object with the following shape: export default async function () { return { glee: {}, - docs: {}, - cluster: {}, kafka: {}, websocket: {}, mqtt: {}, + cluster: {}, http: {} } } @@ -93,30 +106,22 @@ export default async function () { }; } ``` - Inside the return statement, you can specify the following options: - ### Glee Core Configurations - These configurations apply to Glee itself, rather than any specific protocol. - |Field|Default|Description| |--|--|--| |glee.gleeDir|`.glee`|Sets the Glee directory. Your sources will be compiled here.| |glee.lifecycleDir|`lifecycle`|Path to the directory that stores your [lifecycle events](./lifecycle-events.md).| |glee.functionsDir|`functions`| Path to the directory that stores your [functions](./functions.md).| |glee.asyncapiFilePath|`asyncapi.(yaml \| yml \| json)`| Path to your AsyncAPI file. | - ### Generating Documentation - |Field|Description| |--|--| |docs.enabled|This flag enables/disables the docs generation functionality. |docs.folder|The dedicated folder you want your generated docs to reside. |docs.template|The AsyncAPI template you wanna use for generating your documentation. - ### Websocket Server - |Field|Description| |--|--| |ws.server|Websocket server-specific configurations| @@ -126,17 +131,13 @@ These configurations apply to Glee itself, rather than any specific protocol. |ws.server.port| The port to use when binding the WebSocket server. This is useful when your server is behind a proxy and the port exposed for consumption is not the same as the port your application should be bound to. Defaults to the port specified in the selected AsyncAPI server.| |ws.client.auth| Authentication variables for client| |ws.client.auth.token| HTTP Authentication header| - ### Cluster - |Field|Description| |--|--| |cluster.adapter| The Glee cluster adapter to use for communication between instances. Defaults to Redis Pub/Sub ("redis"). Can be a reference to a custom adapter.| |cluster.name|The name of the cluster. Defaults to "cluster".| |cluster.url|The url of the server to be used by the adapter. In case of "redis" adapter, it's the url of the Redis server.| - ### MQTT - |Field|Description| |---|---| |mqtt.auth| MQTT authentication configuration| @@ -144,9 +145,7 @@ These configurations apply to Glee itself, rather than any specific protocol. |mqtt.auth.clientId| MQTT client Id for authentication |mqtt.auth.username| username parameter |mqtt.auth.password| password parameter - ### Kafka - |Field|Description| |---|---| |kafka.auth| Kafka authentication configuration| @@ -156,9 +155,7 @@ These configurations apply to Glee itself, rather than any specific protocol. |kafka.auth.rejectUnauthorized | Boolean flag for accepting the valid SSL certificates |kafka.auth.username| The username to use during authentication. |kafka.auth.password| The password to use during authentication. - ### HTTP Server - |Field|Description| |--|--| |http.server|HTTP server-specific configurations| @@ -169,13 +166,9 @@ These configurations apply to Glee itself, rather than any specific protocol. |http.client.auth.token| HTTP Authentication header| |http.client.query| Query object for the client to send| |http.client.body| Body object for the client to send - - ### Auth Config - Most clients like `ws`,`kafka`, and `mqtt` have auth fields that are used for passing auth parameters. All these configurations can be an object or a function that returns the specific object defined by each protocol. - ```js export default async function() { ws: { diff --git a/docs/env-vars.md b/docs/env-vars.md deleted file mode 100644 index 590d9e5fa..000000000 --- a/docs/env-vars.md +++ /dev/null @@ -1,9 +0,0 @@ -# Environment Variables - -Glee provides a few environment variables for you to customize the experience: - -|Variable|Description|Example| -|---|---|---| -|GLEE_SERVER_NAMES|A comma-separated list of the servers to load on startup.|`GLEE_SERVER_NAMES=websockets,mosquitto` -|GLEE_SERVER_CERTS|A comma-separated list of `${serverName}:${pathToCertificateFile}`. These are the certificates to use when establishing the connection to the given server.|`GLEE_SERVER_CERTS=mosquitto:mosquitto.org.crt` -|GLEE_SERVER_VARIABLES|A comma-separated list of `${serverName}:${serverVariable}:${value}`. These are the values to use for each server variable.|`GLEE_SERVER_VARIABLES=websockets:namespace:public` diff --git a/docs/functions.md b/docs/function-lifecycle-events.md similarity index 53% rename from docs/functions.md rename to docs/function-lifecycle-events.md index 69b86dd23..50b65d74b 100644 --- a/docs/functions.md +++ b/docs/function-lifecycle-events.md @@ -1,29 +1,27 @@ +--- +title: Function and Lifecycle events +weight: 80 +--- + # Functions Glee relies on functions to execute your business logic. Functions are files that export a default async Node.js function: - ```js /* onHello.js */ - export default async function (event) { // Your business logic here... } ``` - Functions take a single argument, which is the event received from a broker or a client, depending which kind of API you're building. The `event` argument has the following shape: - |Attribute|Description| |----|----| |payload|The payload/body of the received event. |headers|The headers/metadata of the received event. |channel|The name of the channel/topic from which the event was read. |serverName|The name of the server/broker from which the event was received. - Functions may return an object to tell Glee what to do next. For instance, the following example greets the user back: - ```js /* onHello.js */ - export default async function (event) { return { reply: [{ @@ -32,26 +30,19 @@ export default async function (event) { } } ``` - |Attribute|Type|Description| |---|---|---| |send|array<[OutboundMessage](#anatomy-of-an-outbound-message)>|A list of outbound messages to send when the processing of the inbound event has finished. All clients subscribed to the given channel/topic will receive the message. |reply|array<[OutboundMessage](#anatomy-of-an-outbound-message)>|A list of outbound messages to send as a reply when the processing of the inbound event has finished. This is useful when the target of your message is the sender of the inbound event. Note, however, that this only works when you're running Glee as a server. For example, using `reply` when receiving a WebSocket message is fine and the reply will exclusively go to the client that sent the message. However, if you're receiving a message from an MQTT broker, `reply` will work exactly the same way as `send` above, and will send the message to all the clients subscribed to the given channel/topic. - - ##### Anatomy of an outbound message - |Attribute|Type|Description| |---|---|---| |payload|string|The payload/body of the message you want to send. |headers|object<string,string>|The headers/metadata of the message you want to send. |channel|string|The channel/topic you want to send the message to. Defaults to `event.channel`, i.e., the same channel as the received event. |server|string|The server/broker you want to send the message to. Defaults to `event.serverName`, i.e., the same server as the received event. - ## How does Glee know which function it should execute? - Glee reads your `asyncapi.yaml` file and searches for all the `publish` operations containing an `operationId` attribute. The `operationId` serves as a mechanism to bind a given operation to a specific function file. For instance, given the folowing AsyncAPI definition: - ```yaml ... channels: @@ -61,4 +52,64 @@ channels: ... ``` -Glee maps the `onHello` operation to the `functions/onHello.js` file. \ No newline at end of file +Glee maps the `onHello` operation to the `functions/onHello.js` file. + +# Lifecycle Events + +Glee lets you bind incoming messages to functions. However, sometimes we need to be proactive and be the first ones to send a message, not necessarily as a reaction to another message. Use cases can be very diverse: from sending a message to announce our client is connected to sending a message every few seconds or minutes. + +To subscribe to a lifecycle event, create a file under the `lifecycle` directory. It must have the following shape: + +```js +export default async function ({ + glee, + serverName, + server, + connection, +}) { + // Your business logic here... +} + +export const lifecycleEvent = 'onConnect' +``` + +Each file in the `lifecycle` directory must export a default async function and the `lifecycleEvent` field, which is the [name of the event](#list-of-events) you want to subscribe to. Optionally, your function can return an object following exactly the same syntax [as described in the functions documentation](functions.md). + +## List of events + +|Event|Description| +|---|---| +|onConnect|A connection with a broker has been established. +|onReconnect|Glee reconnected to a broker. +|onDisconnect|A connection with a broker has been closed. +|onServerReady|Your Glee server is now ready to accept connections. +|onServerConnectionOpen|A client has opened a connection with your Glee server. +|onServerConnectionClose|A client has closed the connection with your Glee server. + +All of them take a single argument which contains information about the event: + +|Attribute|Description +|---|---| +|glee|A reference to the Glee app. +|serverName|The name of the server where the event happened. +|server|The AsyncAPI definition of the server where the event happened. +|connection|The connection where the event happened. + +## Restricting the lifecycle event + +In some cases it's useful to restrict the lifecycle event to a specific server or set of servers. To do that, add a line like the following to your lifecycle file: + +```js +export const servers = ['mosquitto'] +``` + +The above example makes Glee fire the lifecycle event only if it's coming from the `mosquitto` server. + +Additionally, you may want to restrict the lifecycle event by channel/topic. To do that, add a line like the following to your lifecycle file: + +```js +export const channels = ['user/signedup'] +``` + +The above example makes Glee fire the lifecycle event only if the connection has the channel `user/signedup` listed as one of its channels. +Glee maps the `onHello` operation to the `functions/onHello.js` file. diff --git a/docs/lifecycle-events.md b/docs/lifecycle-events.md deleted file mode 100644 index 2192bb8e3..000000000 --- a/docs/lifecycle-events.md +++ /dev/null @@ -1,58 +0,0 @@ -# Lifecycle Events - -Glee lets you bind incoming messages to [functions](./functions.md). However, sometimes we need to be proactive and be the first ones to send a message, not necessarily as a reaction to another message. Use cases can be very diverse: from sending a message to announce our client is connected to sending a message every few seconds or minutes. - -To subscribe to a lifecycle event, create a file under the `lifecycle` directory. It must have the following shape: - -```js -export default async function ({ - glee, - serverName, - server, - connection, -}) { - // Your business logic here... -} - -export const lifecycleEvent = 'onConnect' -``` - -Each file in the `lifecycle` directory must export a default async function and the `lifecycleEvent` field, which is the [name of the event](#list-of-events) you want to subscribe to. Optionally, your function can return an object following exactly the same syntax [as described in the functions documentation](functions.md). - -## List of events - -|Event|Description| -|---|---| -|onConnect|A connection with a broker has been established. -|onReconnect|Glee reconnected to a broker. -|onDisconnect|A connection with a broker has been closed. -|onServerReady|Your Glee server is now ready to accept connections. -|onServerConnectionOpen|A client has opened a connection with your Glee server. -|onServerConnectionClose|A client has closed the connection with your Glee server. - -All of them take a single argument which contains information about the event: - -|Attribute|Description -|---|---| -|glee|A reference to the Glee app. -|serverName|The name of the server where the event happened. -|server|The AsyncAPI definition of the server where the event happened. -|connection|The connection where the event happened. - -## Restricting the lifecycle event - -In some cases it's useful to restrict the lifecycle event to a specific server or set of servers. To do that, add a line like the following to your lifecycle file: - -```js -export const servers = ['mosquitto'] -``` - -The above example makes Glee fire the lifecycle event only if it's coming from the `mosquitto` server. - -Additionally, you may want to restrict the lifecycle event by channel/topic. To do that, add a line like the following to your lifecycle file: - -```js -export const channels = ['user/signedup'] -``` - -The above example makes Glee fire the lifecycle event only if the connection has the channel `user/signedup` listed as one of its channels.