Merge pull request #38 from gatewayd-io/js-plugin

mostafa · web-flow · commit b90b6ff03b12 · 2023-12-29T17:43:59.000+01:00
JS plugin doc
diff --git a/.vale/Vocab/accept.txt b/.vale/Vocab/accept.txt
@@ -89,3 +89,5 @@ gatewayd
 frontmatter
 startTimeout
 tls_connections
+Goja
+stringified
diff --git a/developing-plugins/grpc-api-reference.md b/developing-plugins/grpc-api-reference.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: gRPC API Reference
 description: GatewayD exposes a gRPC API that can be used to interact with the GatewayD plugin system. This API can be used by the GatewayD plugins and is available in the GatewayD SDK.
diff --git a/developing-plugins/index.md b/developing-plugins/index.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Developing Plugins
 nav_order: 4
diff --git a/developing-plugins/plugin-developers-guide.md b/developing-plugins/plugin-developers-guide.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Plugin Developers Guide
 description: Plugin developers' guide of GatewayD
diff --git a/developing-plugins/sdk-reference.md b/developing-plugins/sdk-reference.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: SDK Reference
 description: The GatewayD plugin SDK provides a number of interfaces, structs and methods to help you build your plugin.
diff --git a/developing-plugins/template-projects.md b/developing-plugins/template-projects.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Template Projects
 description: Template projects can be used to quickly get started with developing plugins.
diff --git a/getting-started/index.md b/getting-started/index.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Getting Started
 nav_order: 1
diff --git a/getting-started/installation.md b/getting-started/installation.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 20:02:20 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Installation
 description: How to install GatewayD and its plugins on different platforms and how to build it from source.
@@ -21,19 +21,28 @@ GatewayD releases are available as standalone binaries for Linux, Windows and ma
 
 Download and extract the archive for your platform, then place the `gatewayd(.exe)` binary in your `PATH` to run it from any location. The [`gatewayd.yaml`](/using-gatewayd/configuration#global-configuration) and [`gatewayd_plugins.yaml`](/using-gatewayd/configuration#plugins-configuration) configuration files are located next to the gatewayd binary in the downloaded archive. These are the default global and plugins configuration files for GatewayD. Extract them to your desired location and use them as a starting point for your configuration.
 
-For Unix-like systems, you can use the following commands to download and extract the archive:
+For Linux-based distributions, you can use the following commands to download and extract the archive:
 
 ```bash
 curl -L https://github.com/gatewayd-io/gatewayd/releases/download/{% github_latest_release gatewayd-io/gatewayd %}/gatewayd-linux-amd64-{% github_latest_release gatewayd-io/gatewayd %}.tar.gz | tar zxvf -
 ```
 
+For macOS, you can use the following commands to download and extract the archive:
+
+```bash
+curl -L https://github.com/gatewayd-io/gatewayd/releases/download/{% github_latest_release gatewayd-io/gatewayd %}/gatewayd-darwin-amd64-{% github_latest_release gatewayd-io/gatewayd %}.tar.gz | tar zxvf -
+```
+
 For Windows, you can use the following commands to download and extract the archive:
 
 ```bash
 curl -L https://github.com/gatewayd-io/gatewayd/releases/download/{% github_latest_release gatewayd-io/gatewayd %}/gatewayd-windows-amd64-{% github_latest_release gatewayd-io/gatewayd %}.zip -o gatewayd-windows-amd64-{% github_latest_release gatewayd-io/gatewayd %}.zip
 unzip gatewayd-windows-amd64-{% github_latest_release gatewayd-io/gatewayd %}.zip -d gatewayd
 ```
 
+{: .note }
+> Note that the above commands download the latest release of GatewayD for `amd64` architecture. To download the latest (or a specific) release of GatewayD for `arm64` architecture, replace `amd64` with `arm64` in the above commands and replace the version number in the URL with the desired version number. It is always recommended to use the latest release of GatewayD and its plugins.
+
 ### APT and RPM packages
 
 Alternatively, GatewayD is available as APT and RPM packages for Linux distributions. These packages include the `gatewayd` binary and the default global and plugins configuration files. The `gatewayd` binary will be installed in `/usr/bin/gatewayd` and the configuration files will be installed in `/etc` as `/etc/gatewayd.yaml` and `/etc/gatewayd_plugins.yaml`.
diff --git a/getting-started/running-gatewayd.md b/getting-started/running-gatewayd.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 22:37:03 +0100
+last_modified_date: 2023-12-27 01:19:35 +0330
 layout: default
 title: Running GatewayD
 description: How to run GatewayD and test it with psql
diff --git a/getting-started/welcome.md b/getting-started/welcome.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Welcome
 description: Introduction to GatewayD and its key features
diff --git a/miscellaneous/glossary.md b/miscellaneous/glossary.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Glossary
 description: Glossary of GatewayD terms
diff --git a/miscellaneous/index.md b/miscellaneous/index.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Miscellaneous
 nav_order: 6
diff --git a/miscellaneous/telemetry-and-usage-report.md b/miscellaneous/telemetry-and-usage-report.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Telemetry and Usage Report
 description: Telemetry and usage report of GatewayD
diff --git a/plugins/gatewayd-plugin-cache.md b/plugins/gatewayd-plugin-cache.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-29 10:51:25 +0100
 layout: default
 title: gatewayd-plugin-cache
 description: GatewayD plugin for caching query results in Redis.
@@ -9,7 +9,7 @@ parent: Plugins
 
 # gatewayd-plugin-cache
 
-The gatewayd-plugin-cahce is a GatewayD plugin for caching query results in Redis and this is how it works:
+The gatewayd-plugin-cache is a GatewayD plugin for caching query results in Redis and this is how it works:
 
 1. The plugin listens for incoming queries from the client(s).
 2. When a new client connects to GatewayD, the plugin detects the client's selected database from the client's startup message. The client's database is cached in Redis.
diff --git a/plugins/gatewayd-plugin-js.md b/plugins/gatewayd-plugin-js.md
@@ -0,0 +1,104 @@
+---
+last_modified_date: 2023-12-29 10:51:25 +0100
+layout: default
+title: gatewayd-plugin-js
+description: GatewayD plugin for running JS functions as hooks.
+nav_order: 2
+parent: Plugins
+---
+
+# gatewayd-plugin-js
+
+The gatewayd-plugin-js is a GatewayD plugin for running JS functions as hooks and this is how it works:
+
+1. Upon startup, the plugin creates a minimal JavaScript engine ([Goja](https://github.com/dop251/goja)) and registers helper functions for various tasks.
+2. Then it loads all JS files in the directory specified by the `SCRIPT_PATH` environment variable. The environment variable must be set to the path of the file that contains the JS functions to be executed as hooks. It can also import other JS files from the same directory.
+3. Based on the existing functions in the JS files, the plugin registers hooks for various events. If a function is not found for a particular event, the plugin does not register a hook for that event.
+4. When an event is triggered and a hook function is called from GatewayD, the plugin executes the corresponding JS function and returns the result to the plugin and eventually to GatewayD.
+
+{: .note }
+> The functions receive a context and a request object as arguments and must return the same or the modified object. The `parseSQL` helper function can be used to parse SQL queries as stringified JSON objects.
+>
+> ```js
+> function onTrafficFromClient(context, request) {
+>   // Do something with the request object and return it
+>   return request
+> }
+> ```
+
+## Features
+
+- Run JS functions as hooks
+- Helper functions for common tasks such as parsing incoming queries
+- Support for running multiple JS functions as hooks
+- Prometheus metrics for monitoring
+- Logging
+- Configurable via environment variables and command-line arguments
+
+## Installation
+
+It is assumed that you have already installed PostgreSQL and [GatewayD](/getting-started/installation).
+
+{: .note }
+> The plugin is compatible with Linux, Windows and macOS.
+
+### Automatic installation
+
+The latest version of the plugin can be installed automatically by running the following command. This command downloads and installs the latest version of the plugin from [GitHub releases](https://github.com/gatewayd-io/gatewayd-plugin-js/releases) to the `plugins` directory in the current directory. The command will then enable the plugin automatically by copying the default [configuration](#configuration) to `gatewayd_plugins.yaml` from the project's GitHub repository.
+
+```bash
+gatewayd plugin install github.com/gatewayd-io/gatewayd-plugin-js@latest
+```
+
+### Manual installation
+
+1. Download and install the latest version of [gatewayd-plugin-js](https://github.com/gatewayd-io/gatewayd-plugin-js/releases/latest) by copying the binary to a directory that is in your `PATH` or accessible to GatewayD.
+2. Copy the [configuration](#configuration) to [`gatewayd_plugins.yaml`](/using-gatewayd/plugins-configuration/plugins-configuration).
+3. Make sure that the configuration parameters and environment variables are correct, particularly the `localPath`, `checksum` and the `SCRIPT_PATH`.
+
+After installing the plugin using any of the above methods, you can start GatewayD and test the plugin by querying the database via GatewayD.
+
+## Configuration
+
+The plugin can be configured via environment variables or command-line arguments. For more information about other configuration parameters, see [plugins configuration](/using-gatewayd/plugins-configuration/plugins-configuration.md).
+
+```yaml
+plugins:
+  - name: gatewayd-plugin-js
+    enabled: True
+    localPath: ../gatewayd-plugin-js/gatewayd-plugin-js
+    args: ["--log-level", "info"]
+    env:
+      - MAGIC_COOKIE_KEY=GATEWAYD_PLUGIN
+      - MAGIC_COOKIE_VALUE=5712b87aa5d7e9f9e9ab643e6603181c5b796015cb1c09d6f5ada882bf2a1872
+      - SCRIPT_PATH=./scripts/index.js
+      - SENTRY_DSN=https://439b580ade4a947cf16e5cfedd18f51f@o4504550475038720.ingest.sentry.io/4506475229413376
+    checksum: d310772152467d9c6ab4ba17fd9dd40d3f724dee4aa014a722e1865d91744a4f
+```
+
+### Environment variables
+
+| Name                 | Description                                                                  | Default                                                                                        |
+| -------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `MAGIC_COOKIE_KEY`   | The key for the magic cookie.                                                | `GATEWAYD_PLUGIN`                                                                              |
+| `MAGIC_COOKIE_VALUE` | The value for the magic cookie.                                              | `5712b87aa5d7e9f9e9ab643e6603181c5b796015cb1c09d6f5ada882bf2a1872`                             |
+| `SCRIPT_PATH`        | The path to the JS file that contains the functions to be executed as hooks. | `./scripts/index.js`                                                                           |
+| `SENTRY_DSN`         | Sentry DSN. Set to empty string to disable Sentry.                           | `https://439b580ade4a947cf16e5cfedd18f51f@o4504550475038720.ingest.sentry.io/4506475229413376` |
+
+### Command-line arguments
+
+| Name          | Description    | Default |
+| ------------- | -------------- | ------- |
+| `--log-level` | The log level. | `info`  |
+
+## Build for testing
+
+To build the plugin for development and testing, run the following command in the project's root directory after cloning the repository.
+
+```bash
+git clone git@github.com:gatewayd-io/gatewayd-plugin-js.git
+cd gatewayd-plugin-js
+make build-dev
+```
+
+Running the above commands clones the repository, changes the current directory and runs the `go mod tidy` and `go build` commands to compile and generate the plugin binary.
diff --git a/plugins/index.md b/plugins/index.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Plugins
 nav_order: 5
diff --git a/using-gatewayd/API.md b/using-gatewayd/API.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: API
 description: GatewayD exposes a gRPC API with an HTTP gateway for querying and managing the `gatewayd` process and its plugins.
diff --git a/using-gatewayd/CLI.md b/using-gatewayd/CLI.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: CLI
 description: GatewayD is a CLI application that runs on Windows, Linux-based distributions and macOS.
diff --git a/using-gatewayd/clients.md b/using-gatewayd/clients.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Clients
 description: Client object is a client that can connect to the database servers over TCP, UDP and Unix Domain Socket.
diff --git a/using-gatewayd/configuration.md b/using-gatewayd/configuration.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Configuration
 description: GatewayD is fully configurable via various sources, including default values, YAML config files, environment variables, CLI flags and plugins.
diff --git a/using-gatewayd/connection-lifecycle.md b/using-gatewayd/connection-lifecycle.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Connection Lifecycle
 description: Connection Lifecycle of GatewayD
diff --git a/using-gatewayd/global-configuration/api.md b/using-gatewayd/global-configuration/api.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: API
 description: GatewayD gRPC API configuration
diff --git a/using-gatewayd/global-configuration/clients.md b/using-gatewayd/global-configuration/clients.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Clients
 description: GatewayD client configuration
diff --git a/using-gatewayd/global-configuration/index.md b/using-gatewayd/global-configuration/index.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Global Configuration
 nav_order: 2
diff --git a/using-gatewayd/global-configuration/loggers.md b/using-gatewayd/global-configuration/loggers.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Loggers
 description: GatewayD logger configuration
diff --git a/using-gatewayd/global-configuration/metrics.md b/using-gatewayd/global-configuration/metrics.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Metrics
 description: GatewayD metrics configuration
diff --git a/using-gatewayd/global-configuration/pools.md b/using-gatewayd/global-configuration/pools.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Pools
 description: GatewayD pool configuration
diff --git a/using-gatewayd/global-configuration/proxies.md b/using-gatewayd/global-configuration/proxies.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Proxies
 description: GatewayD proxy configuration
diff --git a/using-gatewayd/global-configuration/servers.md b/using-gatewayd/global-configuration/servers.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Servers
 description: GatewayD server configuration
diff --git a/using-gatewayd/index.md b/using-gatewayd/index.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Using GatewayD
 nav_order: 2
diff --git a/using-gatewayd/observability.md b/using-gatewayd/observability.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Observability
 description: Observability is a first-class citizen of GatewayD. It generates logs, metrics and traces to make it easier to see what is going on inside.
diff --git a/using-gatewayd/plugins-configuration/general-configurations.md b/using-gatewayd/plugins-configuration/general-configurations.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: General configurations
 description: General configurations for plugins
diff --git a/using-gatewayd/plugins-configuration/index.md b/using-gatewayd/plugins-configuration/index.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Plugins Configuration
 nav_order: 3
diff --git a/using-gatewayd/plugins-configuration/plugins-configuration.md b/using-gatewayd/plugins-configuration/plugins-configuration.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Plugins configuration
 description: GatewayD plugins configuration
diff --git a/using-gatewayd/pools.md b/using-gatewayd/pools.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Pools
 description: GatewayD has a generic internal pool object that is used to manage plugins and connections.
diff --git a/using-gatewayd/protocols.md b/using-gatewayd/protocols.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Protocols
 description: GatewayD is application layer protocol-agnostic. This means that GatewayD *can* practically support any protocol in the application layer, or L7.
diff --git a/using-gatewayd/proxies.md b/using-gatewayd/proxies.md
@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2023-11-19 14:31:13 +0100
+last_modified_date: 2023-12-04 12:41:05 +0100
 layout: default
 title: Proxies
 description: Proxy object is used to create a binding between incoming connections from the database clients to the database servers.
diff --git a/using-gatewayd/servers.md b/using-gatewayd/servers.md
diff --git a/using-plugins/hook-registry.md b/using-plugins/hook-registry.md
diff --git a/using-plugins/hooks.md b/using-plugins/hooks.md
diff --git a/using-plugins/index.md b/using-plugins/index.md
diff --git a/using-plugins/plugin-registry.md b/using-plugins/plugin-registry.md
diff --git a/using-plugins/plugin-types.md b/using-plugins/plugin-types.md
diff --git a/using-plugins/plugins.md b/using-plugins/plugins.md
diff --git a/using-plugins/proposals.md b/using-plugins/proposals.md
