diff --git a/developing-plugins/grpc-api-reference.md b/developing-plugins/grpc-api-reference.md index 42c4e68..c5d962c 100644 --- a/developing-plugins/grpc-api-reference.md +++ b/developing-plugins/grpc-api-reference.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:39 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 index 50342c8..333097f 100644 --- a/developing-plugins/index.md +++ b/developing-plugins/index.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:39 layout: default title: Developing Plugins nav_order: 4 diff --git a/developing-plugins/plugin-developers-guide.md b/developing-plugins/plugin-developers-guide.md index 76e2876..e5a21b8 100644 --- a/developing-plugins/plugin-developers-guide.md +++ b/developing-plugins/plugin-developers-guide.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:39 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 index 55799f4..9f63ddd 100644 --- a/developing-plugins/sdk-reference.md +++ b/developing-plugins/sdk-reference.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:39 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 index a6ca74a..6d0bb0a 100644 --- a/developing-plugins/template-projects.md +++ b/developing-plugins/template-projects.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:39 layout: default title: Template Projects description: Template projects can be used to quickly get started with developing plugins. diff --git a/generate_last_modified_data.sh b/generate_last_modified_data.sh index 7b5244a..4684da1 100755 --- a/generate_last_modified_data.sh +++ b/generate_last_modified_data.sh @@ -1,32 +1,23 @@ #!/usr/bin/bash # Replace `last_modified_date` timestamp with current time -# https://mademistakes.com/notes/adding-last-modified-timestamps-with-git/#mention-5 +# This script is used to update the `last_modified_date` timestamp in the frontmatter of all Markdown files in the current directory and subdirectories. -for b in $(find ./ -type d \( -path ./vendor -o -path ./node_modules \) -prune -o -name '*.md'); do - if [ -d "${b}" ]; then - continue - fi - - if [ "$b" = "./.vale/write-good/README.md" ] || [ "$b" = "./README.md" ]; then - continue - fi +# Loop through all Markdown files in the current directory and subdirectories +find . -type f -name "*.md" | while read file; do + # Check if the file contains a frontmatter block + if grep -q "^---" "$file"; then + # Get the last modified timestamp of the file + last_modified_timestamp=$(stat -c %Y "$file") - if [ $(cat ${b} | head -n 1 | grep -E '\-\-\-') ]; then - echo "already have meta" - else - cat ${b} | sed '1s/^/---\n---\n/' >tmp - mv tmp ${b} - fi + # Convert the last modified timestamp to UTC datetime in YYYY-MM-DD HH:MM:SS format + last_modified_datetime_utc=$(date -u -d @"$last_modified_timestamp" "+%Y-%m-%d %H:%M:%S") - if grep -q last_modified_date ${b}; then - echo "no change" - else - cat ${b} | sed '1 {/---.*/,/---.*/{0,/---/{s/---/---\nlast_modified_date:/}}}' >tmp - mv tmp ${b} + # Check if last_modified_date exists in the frontmatter, update it if it does + if grep -q "^last_modified_date:" "$file"; then + sed -i "/^last_modified_date:/c\last_modified_date: $last_modified_datetime_utc" "$file" + else + # If last_modified_date does not exist, add it after the first frontmatter delimiter + sed -i "/^---/a last_modified_date: $last_modified_datetime_utc" "$file" + fi fi - - cat ${b} | sed "/---.*/,/---.*/s/^last_modified_date:.*$/last_modified_date: $(git log -1 --pretty="format:%ci" ${b})/" >tmp - mv tmp ${b} done - -rm -rf we work.md diff --git a/getting-started/index.md b/getting-started/index.md index c946454..298a72a 100644 --- a/getting-started/index.md +++ b/getting-started/index.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Getting Started nav_order: 1 diff --git a/getting-started/installation.md b/getting-started/installation.md index 8ec5ed7..cf38cbe 100644 --- a/getting-started/installation.md +++ b/getting-started/installation.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Installation description: How to install GatewayD and its plugins on different platforms and how to build it from source. diff --git a/getting-started/running-gatewayd.md b/getting-started/running-gatewayd.md index 0a5cccc..02e2bbf 100644 --- a/getting-started/running-gatewayd.md +++ b/getting-started/running-gatewayd.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Running GatewayD description: How to run GatewayD and test it with psql @@ -95,20 +95,21 @@ Running GatewayD will produce the following log output, which means that Gateway 5. exposing an HTTP and a gRPC API on ports `18080` and `19090`. ```bash -2023-12-26T16:22:02+03:30 INF configuring client automatic mTLS group=default plugin=gatewayd-plugin-cache -2023-12-26T16:22:03+03:30 INF Starting metrics server via HTTP over Unix domain socket endpoint=/metrics group=default plugin=gatewayd-plugin-cache timestamp=2023-12-26T16:22:03.083+0330 unixDomainSocket=/tmp/gatewayd-plugin-cache.sock -2023-12-26T16:22:03+03:30 INF configuring server automatic mTLS group=default plugin=gatewayd-plugin-cache timestamp=2023-12-26T16:22:03.084+0330 -2023-12-26T16:22:03+03:30 INF Registering plugin hooks group=default name=gatewayd-plugin-cache -2023-12-26T16:22:03+03:30 INF Plugin is ready group=default name=gatewayd-plugin-cache -2023-12-26T16:22:03+03:30 INF Started the metrics merger scheduler group=default metricsMergerPeriod=5s startDelay=2023-12-26T16:22:08+03:30 -2023-12-26T16:22:03+03:30 INF Starting plugin health check scheduler group=default healthCheckPeriod=5s -2023-12-26T16:22:03+03:30 INF Metrics are exposed address=http://localhost:9090/metrics group=default readHeaderTimeout=10s timeout=10s -2023-12-26T16:22:03+03:30 INF There are clients available in the pool count=10 group=default name=default -2023-12-26T16:22:03+03:30 INF Started the client health check scheduler group=default healthCheckPeriod=1m0s startDelay=2023-12-26T16:23:03+03:30 -2023-12-26T16:22:03+03:30 INF GatewayD is listening address=0.0.0.0:15432 group=default -2023-12-26T16:22:03+03:30 INF Started the HTTP API address=localhost:18080 group=default -2023-12-26T16:22:03+03:30 INF Started the gRPC API address=localhost:19090 group=default network=tcp -2023-12-26T16:22:03+03:30 INF GatewayD is running group=default pid=71426 +2024-03-02T13:24:51+01:00 INF Policies are loaded group=default policies=["passthrough","terminate","log"] +2024-03-02T13:24:51+01:00 INF configuring client automatic mTLS group=default plugin=gatewayd-plugin-cache +2024-03-02T13:24:52+01:00 INF Starting metrics server via HTTP over Unix domain socket endpoint=/metrics group=default plugin=gatewayd-plugin-cache timestamp=2024-03-02T13:24:52.427+0100 unixDomainSocket=/tmp/gatewayd-plugin-cache.sock +2024-03-02T13:24:52+01:00 INF configuring server automatic mTLS group=default plugin=gatewayd-plugin-cache timestamp=2024-03-02T13:24:52.427+0100 +2024-03-02T13:24:52+01:00 INF Registering plugin hooks group=default name=gatewayd-plugin-cache +2024-03-02T13:24:52+01:00 INF Plugin is ready group=default name=gatewayd-plugin-cache +2024-03-02T13:24:52+01:00 INF Started the metrics merger scheduler group=default metricsMergerPeriod=5s startDelay=2024-03-02T13:24:57+01:00 +2024-03-02T13:24:52+01:00 INF Starting plugin health check scheduler group=default healthCheckPeriod=5s +2024-03-02T13:24:52+01:00 INF Metrics are exposed address=http://localhost:9090/metrics group=default readHeaderTimeout=10s timeout=10s +2024-03-02T13:24:52+01:00 INF There are clients available in the pool count=10 group=default name=default +2024-03-02T13:24:52+01:00 INF Started the client health check scheduler group=default healthCheckPeriod=1m0s startDelay=2024-03-02T13:25:52+01:00 +2024-03-02T13:24:52+01:00 INF GatewayD is listening address=0.0.0.0:15432 group=default +2024-03-02T13:24:52+01:00 INF Started the HTTP API address=localhost:18080 group=default +2024-03-02T13:24:52+01:00 INF Started the gRPC API address=localhost:19090 group=default network=tcp +2024-03-02T13:24:52+01:00 INF GatewayD is running group=default pid=24658 ``` {: .note } diff --git a/getting-started/welcome.md b/getting-started/welcome.md index d574fd8..95e7459 100644 --- a/getting-started/welcome.md +++ b/getting-started/welcome.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Welcome description: Introduction to GatewayD and its key features diff --git a/miscellaneous/glossary.md b/miscellaneous/glossary.md index 8f7e769..89ad272 100644 --- a/miscellaneous/glossary.md +++ b/miscellaneous/glossary.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Glossary description: Glossary of GatewayD terms diff --git a/miscellaneous/index.md b/miscellaneous/index.md index 95ef0e2..44992d3 100644 --- a/miscellaneous/index.md +++ b/miscellaneous/index.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Miscellaneous nav_order: 6 diff --git a/miscellaneous/telemetry-and-usage-report.md b/miscellaneous/telemetry-and-usage-report.md index 4fb0d1e..6183b02 100644 --- a/miscellaneous/telemetry-and-usage-report.md +++ b/miscellaneous/telemetry-and-usage-report.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 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 index 2a3c328..8d343ef 100644 --- a/plugins/gatewayd-plugin-cache.md +++ b/plugins/gatewayd-plugin-cache.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: gatewayd-plugin-cache description: GatewayD plugin for caching query results in Redis. diff --git a/plugins/gatewayd-plugin-js.md b/plugins/gatewayd-plugin-js.md index b5ca6cd..3e93a08 100644 --- a/plugins/gatewayd-plugin-js.md +++ b/plugins/gatewayd-plugin-js.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: gatewayd-plugin-js description: GatewayD plugin for running JS functions as hooks. diff --git a/plugins/index.md b/plugins/index.md index aa971ff..70add8e 100644 --- a/plugins/index.md +++ b/plugins/index.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Plugins nav_order: 5 diff --git a/using-gatewayd/API.md b/using-gatewayd/API.md index a8d5d41..93c5de5 100644 --- a/using-gatewayd/API.md +++ b/using-gatewayd/API.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 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/Act.md b/using-gatewayd/Act.md new file mode 100644 index 0000000..3c5a51a --- /dev/null +++ b/using-gatewayd/Act.md @@ -0,0 +1,76 @@ +--- +last_modified_date: 2024-03-02 12:35:38 +layout: default +title: Act +description: Act is a policy engine that supports signals, policies and actions. It is used to automate the execution of business rules. +nav_order: 10 +parent: Using GatewayD +--- + +# Act + +Act, a core component of GatewayD, is a policy engine that supports signals, policies and actions. It is used to automate the execution of business rules. The business rules are currently written as expressions in the [Expr](https://github.com/expr-lang/expr) language, with support for external policy engines to come. The expressions are evaluated against the signals received from the plugins and the corresponding actions are executed if the policy expressions evaluate to true (boolean) or any other type recognized by the action. + +Previously, there were only a single signal, policy and action, called the `terminatePolicy`, which were hard-coded into the GatewayD codebase. This made it difficult to extend and customize the behavior of GatewayD. With the new Act, based on [this proposal](https://github.com/gatewayd-io/proposals/issues/5), the signals, policies and actions are pluggable and can be extended to support custom requirements. This opens up a wide range of possibilities for customizing the behavior of GatewayD to suit the needs of different use cases. For example, a policy can be written to check if the request is coming from a specific IP address, and if so, the action can be to terminate the request. + +For more information about configuring policies, see the plugins' [general configuration](/using-gatewayd/plugins-configuration/general-configurations). + +{: .note } +> The Act component is currently under active development and the core functionality is available in the GatewayD and the SDK codebases. The information provided here is based on the proposal and the current state of the development. The documentation will be updated as the development progresses. + +## Signals + +A signal is a message that is sent to the policy engine to trigger the evaluation of the policies. The signals are generated by the plugins and are sent to the policy engine for evaluation. The signals can be of different types, such as `terminate`, `log`, etc., and can contain different types of data, such as the log message and log level, and whether the signal is enabled or not. A signal consists of two fields: + +1. `name`: The name of the signal, such as `terminate`, `log`, etc. +2. `metadata`: The metadata associated with the signal, such as the log message and log level. + +For example, [the `terminate` signal](https://github.com/gatewayd-io/gatewayd-plugin-sdk/blob/d978dc626c5ba7e655f303c6dc51e3335292e4af/act/signal.go#L19-L26) can be sent with the following metadata: + +```yaml +name: terminate +metadata: + terminate: true +``` + + + +## Policies + +A policy is a set of rules that are evaluated against the signals to determine whether the actions should be executed. The policies are written as expressions in the Expr language, with support for external policy engines to come. The expressions are evaluated against the signals received from the plugins and the corresponding actions are executed if the policy expressions evaluate to a type recognized by the action. Policies have the following fields: + +1. `name`: The name of the policy, such as `terminate`, `log`, etc. + +For example, [the policy](https://github.com/gatewayd-io/gatewayd/blob/6ccf9b70be368fb935dbc133bf547eae9f590630/act/builtins.go#L38-L42) that matches the `terminate` signal can be written as: + +```yaml +name: terminate +policy: "Signal.terminate == true && Policy.terminate == 'stop'" +metadata: + terminate: "stop" # Change this to "continue" to continue the execution +``` + +## Actions + +The action can be run in sync or async mode, and it can return a result or an error. The actions are executed if the policy expressions evaluate to true (boolean) or any other type recognized by the action. The actions have the following fields: + +1. `name`: The name of the action, such as `terminate`, `log`, etc. +2. `metadata`: The metadata associated with the action, such as the log message and log level. +3. `sync`: Whether the action should be run in sync or async mode. +4. `terminal`: Whether the action is terminal or not. +5. `run`: The function that is executed when the action is triggered. This is currently written in Go, with support for writing actions in other languages to come. + +For example, [the action](https://github.com/gatewayd-io/gatewayd/blob/6ccf9b70be368fb935dbc133bf547eae9f590630/act/builtins.go#L61-L66) that matches the `terminate` policy can be written as: + +```yaml +name: terminate +metadata: + terminate: "stop" +sync: true +terminal: true +``` + +The terminate function is available [here](https://github.com/gatewayd-io/gatewayd/blob/6ccf9b70be368fb935dbc133bf547eae9f590630/act/builtins.go#L83-L127). + +{: .note } +> Signals, policies and actions must have the same name to be matched and executed. For example, the `terminate` signal will be matched with the `terminate` policy and the `terminate` action will be executed if the policy expression evaluates to true. diff --git a/using-gatewayd/CLI.md b/using-gatewayd/CLI.md index 31669d2..856b0cd 100644 --- a/using-gatewayd/CLI.md +++ b/using-gatewayd/CLI.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 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 index ba05d27..861a2e3 100644 --- a/using-gatewayd/clients.md +++ b/using-gatewayd/clients.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 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 index 3dbeb42..8920717 100644 --- a/using-gatewayd/configuration.md +++ b/using-gatewayd/configuration.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 13:13:53 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Configuration description: GatewayD is fully configurable via various sources, including default values, YAML config files, environment variables, CLI flags and plugins. @@ -126,7 +126,6 @@ This is the complete plugins config file with the default values and an example ```yaml compatibilityPolicy: "strict" -terminationPolicy: "stop" enableMetricsMerger: True metricsMergerPeriod: 5s healthCheckPeriod: 5s @@ -183,17 +182,14 @@ flowchart TD GatewayD allows plugins to update the global configuration at runtime. This is done by calling the `OnConfigLoaded` hook, which is called after the global configuration is loaded. The `OnConfigLoaded` hook is called on startup with the global configuration as a parameter. The plugin can then modify the global configuration and return it. The modified global configuration will be used by GatewayD. -An example of this update can be found in the [Go plugin template](https://github.com/gatewayd-io/plugin-template-go/blob/981b36aa62b4ba059656c6dde08f67a9206c0948/plugin/plugin.go#L54-L129). The following snippet shows how to update the global configuration at runtime: +An example of this update can be found in the [Go plugin template](https://github.com/gatewayd-io/plugin-template-go/blob/8fa91ee1105ff56900bca0d90b01466e63ce2fd1/plugin/plugin.go#L52-L119). The following snippet shows how to update the global configuration at runtime: ```go func (p *Plugin) OnConfigLoaded(ctx context.Context, req *v1.Struct) (*v1.Struct, error) { - if req.Fields == nil { - req.Fields = make(map[string]*v1.Value) - } - + // ... + // Update the global configuration req.Fields["loggers.default.level"] = v1.NewStringValue("debug") req.Fields["loggers.default.noColor"] = v1.NewBoolValue(false) - return req, nil } ``` diff --git a/using-gatewayd/connection-lifecycle.md b/using-gatewayd/connection-lifecycle.md index 2dc68d8..c9c305e 100644 --- a/using-gatewayd/connection-lifecycle.md +++ b/using-gatewayd/connection-lifecycle.md @@ -1,9 +1,9 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Connection Lifecycle description: Connection Lifecycle of GatewayD -nav_order: 10 +nav_order: 11 parent: Using GatewayD --- diff --git a/using-gatewayd/global-configuration/api.md b/using-gatewayd/global-configuration/api.md index 0e85314..f08a3e0 100644 --- a/using-gatewayd/global-configuration/api.md +++ b/using-gatewayd/global-configuration/api.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 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 index 4271590..eb0c705 100644 --- a/using-gatewayd/global-configuration/clients.md +++ b/using-gatewayd/global-configuration/clients.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Clients description: GatewayD client configuration diff --git a/using-gatewayd/global-configuration/index.md b/using-gatewayd/global-configuration/index.md index db0d8b6..892e4f4 100644 --- a/using-gatewayd/global-configuration/index.md +++ b/using-gatewayd/global-configuration/index.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Global Configuration nav_order: 2 diff --git a/using-gatewayd/global-configuration/loggers.md b/using-gatewayd/global-configuration/loggers.md index 1211336..301b594 100644 --- a/using-gatewayd/global-configuration/loggers.md +++ b/using-gatewayd/global-configuration/loggers.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Loggers description: GatewayD logger configuration diff --git a/using-gatewayd/global-configuration/metrics.md b/using-gatewayd/global-configuration/metrics.md index 16cc9bf..be23fa4 100644 --- a/using-gatewayd/global-configuration/metrics.md +++ b/using-gatewayd/global-configuration/metrics.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Metrics description: GatewayD metrics configuration diff --git a/using-gatewayd/global-configuration/pools.md b/using-gatewayd/global-configuration/pools.md index bfc6a94..e7a91d8 100644 --- a/using-gatewayd/global-configuration/pools.md +++ b/using-gatewayd/global-configuration/pools.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Pools description: GatewayD pool configuration diff --git a/using-gatewayd/global-configuration/proxies.md b/using-gatewayd/global-configuration/proxies.md index f21c6e5..a2f9be7 100644 --- a/using-gatewayd/global-configuration/proxies.md +++ b/using-gatewayd/global-configuration/proxies.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Proxies description: GatewayD proxy configuration diff --git a/using-gatewayd/global-configuration/servers.md b/using-gatewayd/global-configuration/servers.md index 3344c2d..d5812e5 100644 --- a/using-gatewayd/global-configuration/servers.md +++ b/using-gatewayd/global-configuration/servers.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Servers description: GatewayD server configuration diff --git a/using-gatewayd/index.md b/using-gatewayd/index.md index 91eebdd..9a582c6 100644 --- a/using-gatewayd/index.md +++ b/using-gatewayd/index.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Using GatewayD nav_order: 2 diff --git a/using-gatewayd/observability.md b/using-gatewayd/observability.md index 91b9e3e..a78fbee 100644 --- a/using-gatewayd/observability.md +++ b/using-gatewayd/observability.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 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 index ea0cbb4..7d40ca1 100644 --- a/using-gatewayd/plugins-configuration/general-configurations.md +++ b/using-gatewayd/plugins-configuration/general-configurations.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 13:13:53 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: General configurations description: General configurations for plugins @@ -12,26 +12,32 @@ grand_parent: Using GatewayD ## Configuration parameters -| Name | Type | Default value | Possible values | Description | -| ------------------- | ------- | ------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| compatibilityPolicy | string | strict | strict, loose | The compatibility policy controls how GatewayD treats plugins' requirements. If a plugin requires a specific version of another plugin, the compatibility policy controls whether to allow or reject the plugin.
- strict (default): the plugin is rejected if it requires a specific version of another plugin and that version is not the one currently loaded.
- loose: the plugin is allowed to run even if it requires a specific version of another plugin and that version is not the one currently loaded. | -| terminationPolicy | string | stop | stop, continue | The termination policy controls how to handle the termination of requests. If a plugin terminates a request, the termination policy controls whether to stop executing the remaining plugins or not. If the termination policy is set to "stop", the remaining plugins are not executed. If the termination policy is set to "continue", the remaining plugins are executed. Warning: if the termination policy is set to "continue", the output of the remaining plugins might be passed down to the next plugin, and the result depends on the what the remaining plugins do.
- stop (default): the remaining plugins are not executed.
- continue: the remaining plugins are executed. | -| enableMetricsMerger | boolean | True | True, False | If enabled, GatewayD will merge the Prometheus metrics of all plugins over Unix domain socket. The metrics are merged and exposed via the GatewayD [metrics](/global-configuration/metrics) endpoint via HTTP. | -| metricsMergerPeriod | string | 5s | Valid duration strings | The metrics merger period controls how often the metrics merger should collect and merge metrics from plugins. | -| healthCheckPeriod | string | 5s | Valid duration strings | The health check period controls how often the health check should be performed. The health check is performed by pinging each plugin. Unhealthy plugins are removed. | -| reloadOnCrash | boolean | True | True, False | If enabled, GatewayD will reload the plugin if it crashes. The crash is detected by the health check. | -| timeout | string | 30s | Valid duration strings | The timeout controls how long to wait for a plugin to respond to a request before timing out. | -| startTimeout | string | 1m | Valid duration strings | The start timeout controls how long to wait for a plugin to start before timing out. | +| Name | Type | Default value | Possible values | Description | +| ------------------- | ------- | ------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| compatibilityPolicy | string | strict | strict, loose | The compatibility policy controls how GatewayD treats plugins' requirements. If a plugin requires a specific version of another plugin, the compatibility policy controls whether to allow or reject the plugin.
- strict (default): the plugin is rejected if it requires a specific version of another plugin and that version is not the one currently loaded.
- loose: the plugin is allowed to run even if it requires a specific version of another plugin and that version is not the one currently loaded. | +| enableMetricsMerger | boolean | True | True, False | If enabled, GatewayD will merge the Prometheus metrics of all plugins over Unix domain socket. The metrics are merged and exposed via the GatewayD [metrics](/global-configuration/metrics) endpoint via HTTP. | +| metricsMergerPeriod | string | 5s | Valid duration strings | The metrics merger period controls how often the metrics merger should collect and merge metrics from plugins. | +| healthCheckPeriod | string | 5s | Valid duration strings | The health check period controls how often the health check should be performed. The health check is performed by pinging each plugin. Unhealthy plugins are removed. | +| reloadOnCrash | boolean | True | True, False | If enabled, GatewayD will reload the plugin if it crashes. The crash is detected by the health check. | +| timeout | string | 30s | Valid duration strings | The timeout controls how long to wait for a plugin to respond to a request before timing out. | +| startTimeout | string | 1m | Valid duration strings | The start timeout controls how long to wait for a plugin to start before timing out. | +| policyTimeout | string | 30s | Valid duration strings | The policy timeout controls how long to wait for a policy to evaluate before timing out. | +| policies | array | [] | An array of objects | The policies are a set of rules that are evaluated against the signals to determine whether the actions should be executed. | ## Example configuration ```yaml compatibilityPolicy: "strict" -terminationPolicy: "stop" enableMetricsMerger: True metricsMergerPeriod: 5s healthCheckPeriod: 5s reloadOnCrash: True timeout: 30s startTimeout: 1m +policyTimeout: 30s +policies: + name: terminate + policy: "Signal.terminate == true && Policy.terminate == 'stop'" + metadata: + terminate: "stop" # Change this to "continue" to continue the execution ``` diff --git a/using-gatewayd/plugins-configuration/index.md b/using-gatewayd/plugins-configuration/index.md index 6264fc5..38ec479 100644 --- a/using-gatewayd/plugins-configuration/index.md +++ b/using-gatewayd/plugins-configuration/index.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 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 index 7da4834..33d3020 100644 --- a/using-gatewayd/plugins-configuration/plugins-configuration.md +++ b/using-gatewayd/plugins-configuration/plugins-configuration.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Plugins configuration description: GatewayD plugins configuration diff --git a/using-gatewayd/pools.md b/using-gatewayd/pools.md index ada84d7..2af842e 100644 --- a/using-gatewayd/pools.md +++ b/using-gatewayd/pools.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 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 index 4517d21..83a2280 100644 --- a/using-gatewayd/protocols.md +++ b/using-gatewayd/protocols.md @@ -1,9 +1,9 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 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. -nav_order: 11 +nav_order: 12 parent: Using GatewayD --- diff --git a/using-gatewayd/proxies.md b/using-gatewayd/proxies.md index c8b73fc..39f60a8 100644 --- a/using-gatewayd/proxies.md +++ b/using-gatewayd/proxies.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 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 index 2b87219..066c08a 100644 --- a/using-gatewayd/servers.md +++ b/using-gatewayd/servers.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Servers description: Server is an object that listens on an address:port pair and accepts connections from database clients. diff --git a/using-plugins/hook-registry.md b/using-plugins/hook-registry.md index 9bbfdb1..5409063 100644 --- a/using-plugins/hook-registry.md +++ b/using-plugins/hook-registry.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Hook registry description: The hook registry is a central place where all hooks are registered and executed. It is used by the plugin registry to register and execute plugin hooks. diff --git a/using-plugins/hooks.md b/using-plugins/hooks.md index 5ddfd7d..4f854f0 100644 --- a/using-plugins/hooks.md +++ b/using-plugins/hooks.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Hooks description: Plugins can be used to modify the connection lifecycle. Each step in the connection lifecycle is represented by one or more plugin hook(s). Plugins can register themselves to be called when a specific hook is triggered. diff --git a/using-plugins/index.md b/using-plugins/index.md index 0937f3f..ecb1256 100644 --- a/using-plugins/index.md +++ b/using-plugins/index.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Using Plugins nav_order: 3 diff --git a/using-plugins/plugin-registry.md b/using-plugins/plugin-registry.md index 6469672..e5a6752 100644 --- a/using-plugins/plugin-registry.md +++ b/using-plugins/plugin-registry.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Plugin registry description: The plugin registry is a central place where all plugins are loaded, configured and executed, and also the main entry point for all plugins. diff --git a/using-plugins/plugin-types.md b/using-plugins/plugin-types.md index ba50d25..49d03d7 100644 --- a/using-plugins/plugin-types.md +++ b/using-plugins/plugin-types.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Plugin types description: > diff --git a/using-plugins/plugins.md b/using-plugins/plugins.md index d899c3c..0e82f3f 100644 --- a/using-plugins/plugins.md +++ b/using-plugins/plugins.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Plugins description: Plugins play a very important role in GatewayD for adding support for different databases. They are the building blocks of GatewayD, and they are responsible for the majority of the functionality of GatewayD. @@ -54,6 +54,15 @@ sequenceDiagram Plugins are loaded in the order in which they appear in the [plugins configuration](/using-gatewayd/plugins-configuration/plugins-configuration). The first plugin in the list will be called first, and the last plugin in the list will be called last. The result of the plugin hooks are merged together. If any of the plugins return an error, the error is returned to GatewayD and further to the client. +## Signals + +A signal is a message that is sent to the policy engine to trigger the evaluation of the policies. The signals are generated by the plugins and are sent to the [policy engine](../using-gatewayd/Act.md) for evaluation. The signals can be of different types, such as `terminate`, `log`, etc., and can contain different types of data, such as the log message and log level, and whether the signal is enabled or not. A signal consists of two fields: + +1. `name`: The name of the signal, such as `terminate`, `log`, etc. +2. `metadata`: The metadata associated with the signal, such as the log message and log level. + +For more information about signals, see the [Act](../using-gatewayd/Act.md) documentation. + ## Policies Certain policies can be applied to plugins. These policies are applied to all plugins, and can be configured in the [general configuration](/using-gatewayd/plugins-configuration/general-configurations) of the plugins configuration file. @@ -65,20 +74,6 @@ The compatibility policy controls how GatewayD treats plugins' requirements. If - `strict` (default): the plugin is rejected if it requires a specific version of another plugin and that version is not the one currently loaded. - `loose`: the plugin is allowed to run even if it requires a specific version of another plugin and that version is not the one currently loaded. -### Acceptance policy - -The acceptance policy controls how new dynamic hooks are handled. If a plugin registers a new hook, the acceptance policy controls whether to accept or reject the new hook. - -- `accept` (default): the new hook is accepted and registered. -- `reject`: the new hook is rejected and not registered. - -### Termination policy - -The termination policy controls how to handle the termination of requests. If a plugin terminates a request, the termination policy controls whether to stop executing the remaining plugins or not. If the termination policy is set to "stop", the remaining plugins are not executed. If the termination policy is set to "continue", the remaining plugins are executed. Warning: if the termination policy is set to "continue", the output of the remaining plugins might be passed down to the next plugin, and the result depends on the what the remaining plugins do. - -- `stop` (default): the remaining plugins are not executed. -- `continue`: the remaining plugins are executed. - ## Health check Plugins are monitored by GatewayD, and if they crash, GatewayD will reload them. The health check is done by sending a ping to the plugin, and if the plugin does not respond within the timeout, GatewayD will reload the plugin. The `healthCheckPeriod` is configurable in the [general configuration](/using-gatewayd/plugins-configuration/general-configurations) of the plugins configuration file. diff --git a/using-plugins/proposals.md b/using-plugins/proposals.md index f32f481..9ae5d16 100644 --- a/using-plugins/proposals.md +++ b/using-plugins/proposals.md @@ -1,5 +1,5 @@ --- -last_modified_date: 2024-02-18 12:58:36 +0100 +last_modified_date: 2024-03-02 12:35:38 layout: default title: Proposals description: GatewayD proposals are used to propose new ideas and features for GatewayD.