Skip to content

Commit a138356

Browse files
mostafamostafa
committed
Add JS plugin doc
1 parent 7ea36a7 commit a138356

File tree

2 files changed

+105
-1
lines changed

2 files changed

+105
-1
lines changed

‎plugins/gatewayd-plugin-cache.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ parent: Plugins
99

1010
# gatewayd-plugin-cache
1111

12-
The gatewayd-plugin-cahce is a GatewayD plugin for caching query results in Redis and this is how it works:
12+
The gatewayd-plugin-cache is a GatewayD plugin for caching query results in Redis and this is how it works:
1313

1414
1. The plugin listens for incoming queries from the client(s).
1515
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.

‎plugins/gatewayd-plugin-js.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
last_modified_date: 2023-12-29 10:32:00 +0100
3+
layout: default
4+
title: gatewayd-plugin-js
5+
description: GatewayD plugin for running JS functions as hooks.
6+
nav_order: 2
7+
parent: Plugins
8+
---
9+
10+
# gatewayd-plugin-js
11+
12+
The gatewayd-plugin-js is a GatewayD plugin for running JS functions as hooks and this is how it works:
13+
14+
1. Upon startup, the plugin creates a minimal JavaScript engine ([Goja](https://github.com/dop251/goja)) and registers helper functions for various tasks.
15+
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.
16+
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.
17+
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.
18+
19+
{: .note }
20+
> 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.
21+
>
22+
> ```js
23+
> function onTrafficFromClient(context, request) {
24+
> // Do something with the request object and return it
25+
> return request
26+
> }
27+
> ```
28+
29+
## Features
30+
31+
- Run JS functions as hooks
32+
- Helper functions for common tasks such as parsing incoming queries
33+
- Support for running multiple JS functions as hooks
34+
- Prometheus metrics for monitoring
35+
- Logging
36+
- Configurable via environment variables and command-line arguments
37+
38+
## Installation
39+
40+
It is assumed that you have already installed PostgreSQL and [GatewayD](/getting-started/installation).
41+
42+
{: .note }
43+
> The plugin is compatible with Linux, Windows and macOS.
44+
45+
### Automatic installation
46+
47+
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.
48+
49+
```bash
50+
gatewayd plugin install github.com/gatewayd-io/gatewayd-plugin-js@latest
51+
```
52+
53+
### Manual installation
54+
55+
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.
56+
2. Copy the [configuration](#configuration) to [`gatewayd_plugins.yaml`](/using-gatewayd/plugins-configuration/plugins-configuration).
57+
3. Make sure that the configuration parameters and environment variables are correct, particularly the `localPath`, `checksum` and the `SCRIPT_PATH`.
58+
59+
After installing the plugin using any of the above methods, you can start GatewayD and test the plugin by querying the database via GatewayD.
60+
61+
## Configuration
62+
63+
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).
64+
65+
```yaml
66+
plugins:
67+
- name: gatewayd-plugin-js
68+
enabled: True
69+
localPath: ../gatewayd-plugin-js/gatewayd-plugin-js
70+
args: ["--log-level", "info"]
71+
env:
72+
- MAGIC_COOKIE_KEY=GATEWAYD_PLUGIN
73+
- MAGIC_COOKIE_VALUE=5712b87aa5d7e9f9e9ab643e6603181c5b796015cb1c09d6f5ada882bf2a1872
74+
- SCRIPT_PATH=./scripts/index.js
75+
- SENTRY_DSN=https://439b580ade4a947cf16e5cfedd18f51f@o4504550475038720.ingest.sentry.io/4506475229413376
76+
checksum: d310772152467d9c6ab4ba17fd9dd40d3f724dee4aa014a722e1865d91744a4f
77+
```
78+
79+
### Environment variables
80+
81+
| Name | Description | Default |
82+
| -------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
83+
| `MAGIC_COOKIE_KEY` | The key for the magic cookie. | `GATEWAYD_PLUGIN` |
84+
| `MAGIC_COOKIE_VALUE` | The value for the magic cookie. | `5712b87aa5d7e9f9e9ab643e6603181c5b796015cb1c09d6f5ada882bf2a1872` |
85+
| `SCRIPT_PATH` | The path to the JS file that contains the functions to be executed as hooks. | `./scripts/index.js` |
86+
| `SENTRY_DSN` | Sentry DSN. Set to empty string to disable Sentry. | `https://439b580ade4a947cf16e5cfedd18f51f@o4504550475038720.ingest.sentry.io/4506475229413376` |
87+
88+
### Command-line arguments
89+
90+
| Name | Description | Default |
91+
| ------------- | -------------- | ------- |
92+
| `--log-level` | The log level. | `info` |
93+
94+
## Build for testing
95+
96+
To build the plugin for development and testing, run the following command in the project's root directory after cloning the repository.
97+
98+
```bash
99+
git clone git@github.com:gatewayd-io/gatewayd-plugin-js.git
100+
cd gatewayd-plugin-js
101+
make build-dev
102+
```
103+
104+
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.

0 commit comments

Comments
 (0)