Merge remote-tracking branch 'upstream/master' into address-fix

.eslintrc

@@ -18,6 +18,7 @@
       "error",
       "multi-line"
     ],
+    "security/detect-non-literal-fs-filename": "off",
     "@typescript-eslint/no-explicit-any": "off",
     "semi": [
       "warn",

docs/config-file.md → docs/pages/application-structure/env-vars-config.md

@@ -1,8 +1,22 @@
-# Configuring Glee
+---
+title: Environment variables and Configuration file
+weight: 80
+---
+
+# Environment Variables
+
+Glee provides a few environment variables for you to customize the Glee application's behavior according to your specific requirements:
+|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.
 
-## The configuration file
+### The configuration file
 
 Glee's config file is a JavaScript file that exports an async function. Something like this:
 
@@ -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
-
+#### 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
-
+#### 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
-
+#### Websocket Server
 |Field|Description|
 |--|--|
 |ws.server|Websocket server-specific configurations|
@@ -126,27 +131,21 @@ 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
-
+#### 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
-
+#### MQTT
 |Field|Description|
 |---|---|
 |mqtt.auth| MQTT authentication configuration|
 |mqtt.auth.cert| Client certificate
 |mqtt.auth.clientId| MQTT client Id for authentication
 |mqtt.auth.username| username parameter
 |mqtt.auth.password| password parameter
-
-### Kafka
-
+#### 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
-
+#### 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
-
+#### 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: {

docs/functions.md → docs/pages/application-structure/function-lifecycle-events.md

@@ -1,29 +1,28 @@
+---
+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: [{
@@ -37,21 +36,15 @@ export default async function (event) {
 |---|---|---|
 |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 +54,61 @@ channels:
       ...
 ```
 
-Glee maps the `onHello` operation to the `functions/onHello.js` 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.