Enrich policy input

using-gatewayd/Act.md

@@ -1,5 +1,5 @@
 ---
-last_modified_date: 2024-05-31 20:16:38
+last_modified_date: 2024-06-03 22:06:31
 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.
@@ -23,7 +23,7 @@ For more information about configuring policies, see the plugins' [general confi
 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.
+2. `metadata`: The metadata associated with the signal, such as the log message and log level. This can be used to pass additional information to the policy engine for evaluation.
 
 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:
 
@@ -40,6 +40,8 @@ metadata:
 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.
+2. `policy`: The policy expression written in the Expr language.
+3. `metadata`: The metadata associated with the policy, such as the log message and log level. This can be used to pass additional information to the policy engine for evaluation.
 
 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:
 
@@ -50,6 +52,38 @@ metadata:
   terminate: "stop" # Change this to "continue" to continue the execution
 ```
 
+Certain fields are made available to the policy expressions for evaluation. These fields are:
+
+1. `Name`: The name of the signal.
+2. `Signal`: The metadata of the signal that is sent to the policy engine for evaluation.
+3. `Policy`: The policy that is evaluated against the signal. This includes the policy name and metadata.
+4. `Hook`: The plugin hook that is run to generate the signal. This includes the hook name, priority, input parameters and output result.
+
+The `Hook` field is a map that contains the following fields:
+
+| Field           | Description               | Type   | Example                                                                                                                                          |
+| --------------- | ------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Hook.Name`     | The name of the hook.     | string | `HOOK_NAME_ON_TRAFFIC_FROM_CLIENT`                                                                                                               |
+| `Hook.Priority` | The priority of the hook. | string | 1000                                                                                                                                             |
+| `Hook.Params`   | The input parameters.     | map    | `{"server": {"remote": "127.0.0.1:5432", "local": "127.0.0.1:53684"}, "client": {"remote": "127.0.0.1:15432", "local": "127.0.0.1:37502"}, ...}` |
+
+   1. `Hook.Name` (string)
+   2. `Hook.Priority` (string)
+   3. `Hook.Params` (map)
+      1. `Hook.Params.server.remote` (string)
+      2. `Hook.Params.server.local` (string)
+      3. `Hook.Params.client.remote` (string)
+      4. `Hook.Params.client.local` (string)
+      5. `Hook.Params.request` (bytes) (currently not usable in Expr language, but will be available in the future via [helper functions](https://github.com/gatewayd-io/gatewayd/issues/541))
+   4. `Hook.Result` (map) (usually a superset of `Hook.Params`)
+      1. `Hook.Result.server.remote` (string)
+      2. `Hook.Result.server.local` (string)
+      3. `Hook.Result.client.remote` (string)
+      4. `Hook.Result.client.local` (string)
+      5. `Hook.Result.request` (bytes) (currently not usable in Expr language, but will be available in the future via [helper functions](https://github.com/gatewayd-io/gatewayd/issues/541))
+      6. `Hook.Result.response` (bytes) (currently not usable in Expr language, but will be available in the future via [helper functions](https://github.com/gatewayd-io/gatewayd/issues/541))
+      7. Fields parsed by the `postgres.HandleClientMessage` and `postgres.HandleServerMessage` functions, see [`wire.go`](https://github.com/gatewayd-io/gatewayd-plugin-sdk/blob/main/databases/postgres/wire.go).
+
 ## 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: