From c14c57c59d73ad4f62bae909e31142c66b1724bf Mon Sep 17 00:00:00 2001 From: Benoit Date: Tue, 15 Jul 2025 18:13:49 +0000 Subject: [PATCH] add docs for ddn plugins --- docs/plugins/introduction.mdx | 216 +++++++++++++- .../metadata-reference/engine-plugins.mdx | 264 ++++++++++-------- 2 files changed, 353 insertions(+), 127 deletions(-) diff --git a/docs/plugins/introduction.mdx b/docs/plugins/introduction.mdx index c1ca1b645..794fa2354 100644 --- a/docs/plugins/introduction.mdx +++ b/docs/plugins/introduction.mdx @@ -27,11 +27,13 @@ plugin's response. Plugins can be applied at the following steps: -| Execution Step | Description | Example Usage | -| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -| **Pre-Parse** | The first step in the execution pipeline, where custom logic can be applied before the query is parsed and its internal representation is generated. | Add an allowlist layer to restrict access to specific queries and mutations. | -| **Pre-Response** | The final step in the execution pipeline, where custom logic can be added after the query is executed but before the response is sent to the client. | Trigger Slack notifications after a mutation is executed. | -| **Pre-Route** | The first step in the routing pipeline, where custom logic can be applied to the requests on other than pre-defined endpoints. | Add a custom endpoint to DDN. | +| Execution Step | Description | Example Usage | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | +| **Pre-Parse** | The first step in the execution pipeline, where custom logic can be applied before the query is parsed and its internal representation is generated. | Add an allowlist layer to restrict access to specific queries and mutations. | +| **Pre-NDC Request** | Applied before sending requests to data connectors, allowing modification of NDC requests or returning responses directly without calling the data connector. | Transform requests, implement caching by returning cached responses, or add request validation. | +| **Pre-NDC Response** | Applied after receiving responses from data connectors, allowing modification of NDC responses. | Transform or enrich data connector responses, or store responses for caching purposes. | +| **Pre-Response** | The final step in the execution pipeline, where custom logic can be added after the query is executed but before the response is sent to the client. | Trigger Slack notifications after a mutation is executed. | +| **Pre-Route** | The first step in the routing pipeline, where custom logic can be applied to the requests on other than pre-defined endpoints. | Add a custom endpoint to DDN. | ## Architecture @@ -43,8 +45,10 @@ graph RL Client[Client] -->|"Request (/graphql)"| Authentication Authentication --> Query_Parsing_and_Planning["Query parsing and planning"] Query_Parsing_and_Planning --> Execute_Query["Execute query"] - Execute_Query <-->|Fetch Data| Data_Connector["Data connector"] - Execute_Query --> Post_Processing["Post-processing"] + Execute_Query --> Pre_NDC_Request_Hooks["Pre-NDC request hooks"] + Pre_NDC_Request_Hooks -->|Fetch Data| Data_Connector["Data connector"] + Data_Connector --> Pre_NDC_Response_Hooks["Pre-NDC response hooks"] + Pre_NDC_Response_Hooks --> Post_Processing["Post-processing"] Post_Processing --> Pre_Response_Hooks["Pre-response hooks"] Post_Processing -->|Response| Client @@ -404,3 +408,201 @@ In this example, the engine is configured with two `pre-route` plugins. The engi `Pre-route hook 1` or `Pre-route hook 2` based on the path. If the path matches `/v1/api/users/admin`, the engine sends the request to `Pre-route hook 1`. If the path matches `/v1/api/users/*`, the engine sends the request to `Pre-route hook 2`. + +## Pre-NDC Request Plugin + +The `pre-ndc-request` plugin is triggered before sending requests to data connectors. This plugin can either modify the +NDC request or return a response directly, bypassing the data connector call entirely. + +There can only be one `pre-ndc-request` plugin configured per data connector. + +For pre-ndc-request plugin configuration +[click here](reference/metadata-reference/engine-plugins.mdx#lifecyclepluginhook-lifecyclepluginhook-lifecycleprendcrequestpluginhook). + +### Pre-NDC Request Plugin Request + +A sample request that is sent to the `pre-ndc-request` plugin is as follows: + +```json +{ + "session": { + "role": "user", + "variables": { + "x-hasura-role": "user", + "x-hasura-user-id": "123" + } + }, + "ndcRequest": { + "collection": "users", + "query": { + "fields": { + "id": { + "type": "column", + "column": "id" + }, + "name": { + "type": "column", + "column": "name" + } + } + }, + "arguments": {}, + "collection_relationships": {} + }, + "dataConnectorName": "my_connector", + "operationType": "query", + "ndcVersion": "v0.2.x" +} +``` + +:::info Customize the request + +The request sent to the plugin can be customized based on the plugin's +[configuration](reference/metadata-reference/engine-plugins.mdx#lifecyclepluginhook-lifecyclepluginhook-lifecycleprendcrequestpluginhookconfigrequest). + +::: + +### Pre-NDC Request Plugin Response + +The plugin can respond in the following ways: + +| Response Type | HTTP Status Code | Response Body | Description | +| ------------------ | ---------------- | ------------------------ | -------------------------------------------------------------------------- | +| `Continue` | `204` | None | The original request will be used without modification. | +| `Modified Request` | `200` | `{"ndcRequest": {...}}` | A modified request that will replace the original. | +| `Direct Response` | `200` | `{"ndcResponse": {...}}` | A response that will be used instead of calling the data connector. | +| `User Error` | `400` | Error object | The plugin encountered a user error, which will be returned to the client. | +| `Internal Error` | `500` | Error object | Treated as an internal error. | + +### Use Cases + +The `pre-ndc-request` plugin can be used for various functionalities: + +- **Request Transformation**: Modify NDC requests before they reach the data connector. +- **Request Validation**: Validate requests and return errors for invalid operations. +- **Caching**: Return cached responses directly without calling the data connector. +- **Request Logging**: Log all requests for audit purposes while allowing them to proceed. +- **Mock Responses**: Return mock data for testing or development environments. + +### Example Configuration + +```yaml title="Here is an example of a pre-ndc-request plugin configuration in DDN metadata:" +kind: LifecyclePluginHook +version: v1 +definition: + name: my-pre-ndc-request-plugin + url: + valueFromEnv: PRE_NDC_REQUEST_PLUGIN_URL + pre: ndcRequest + connectors: + - my_postgres_connector + config: + request: + headers: + additional: + hasura-m-auth: + value: "your-strong-m-auth-key" + session: {} + ndcRequest: {} +``` + +## Pre-NDC Response Plugin + +The `pre-ndc-response` plugin is triggered after receiving responses from data connectors but before further processing. +This plugin allows modification of NDC responses. + +There can only be one `pre-ndc-response` plugin configured per data connector. + +For pre-ndc-response plugin configuration +[click here](reference/metadata-reference/engine-plugins.mdx#lifecyclepluginhook-lifecyclepluginhook-lifecycleprendcresponsepluginhook). + +### Pre-NDC Response Plugin Request + +A sample request that is sent to the `pre-ndc-response` plugin is as follows: + +```json +{ + "session": { + "role": "user", + "variables": { + "x-hasura-role": "user", + "x-hasura-user-id": "123" + } + }, + "ndcRequest": { + "collection": "users", + "query": { + "fields": { + "id": { + "type": "column", + "column": "id" + } + } + } + }, + "ndcResponse": { + "rows": [ + { + "id": 1 + }, + { + "id": 2 + } + ] + }, + "dataConnectorName": "my_connector", + "operationType": "query", + "ndcVersion": "v0.2.x" +} +``` + +:::info Customize the request + +The request sent to the plugin can be customized based on the plugin's +[configuration](reference/metadata-reference/engine-plugins.mdx#lifecyclepluginhook-lifecyclepluginhook-lifecycleprendcresponsepluginhookconfigrequest). + +::: + +### Pre-NDC Response Plugin Response + +The plugin can respond in the following ways: + +| Response Type | HTTP Status Code | Response Body | Description | +| ------------------- | ---------------- | --------------------- | -------------------------------------------------------------------------- | +| `Continue` | `204` | None | The original response will be used without modification. | +| `Modified Response` | `200` | Modified NDC response | A modified NDC response that will replace the original. | +| `User Error` | `400` | Error object | The plugin encountered a user error, which will be returned to the client. | +| `Internal Error` | `500` | Error object | Treated as an internal error. | + +### Use Cases + +The `pre-ndc-response` plugin can be used for: + +- **Response Transformation**: Modify or enrich data connector responses. +- **Data Filtering**: Filter sensitive data from responses based on user permissions. +- **Response Caching**: Store responses for future caching purposes. +- **Response Logging**: Log responses for audit or analytics purposes. +- **Data Enrichment**: Add additional data to responses from external sources. + +### Example Configuration + +```yaml title="Here is an example of a pre-ndc-response plugin configuration in DDN metadata:" +kind: LifecyclePluginHook +version: v1 +definition: + name: my-pre-ndc-response-plugin + url: + valueFromEnv: PRE_NDC_RESPONSE_PLUGIN_URL + pre: ndcResponse + connectors: + - my_postgres_connector + config: + request: + headers: + additional: + hasura-m-auth: + value: "your-strong-m-auth-key" + session: {} + ndcRequest: {} + ndcResponse: {} +``` diff --git a/docs/reference/metadata-reference/engine-plugins.mdx b/docs/reference/metadata-reference/engine-plugins.mdx index 42479d134..02ba7c13b 100644 --- a/docs/reference/metadata-reference/engine-plugins.mdx +++ b/docs/reference/metadata-reference/engine-plugins.mdx @@ -67,18 +67,17 @@ definition: ## Metadata structure - ### LifecyclePluginHook {#lifecyclepluginhook-lifecyclepluginhook} Definition of a lifecycle plugin hook. -| Key | Value | Required | Description | -|-----|-----|-----|-----| -| `kind` | `LifecyclePluginHook` | true | | -| `version` | `v1` | true | | -| `definition` | [LifecyclePluginHookV1](#lifecyclepluginhook-lifecyclepluginhookv1) | true | Definition of a lifecycle plugin hook - version 1. | +| Key | Value | Required | Description | +| ------------ | ------------------------------------------------------------------- | -------- | -------------------------------------------------- | +| `kind` | `LifecyclePluginHook` | true | | +| `version` | `v1` | true | | +| `definition` | [LifecyclePluginHookV1](#lifecyclepluginhook-lifecyclepluginhookv1) | true | Definition of a lifecycle plugin hook - version 1. | - **Example:** +**Example:** ```yaml kind: LifecyclePluginHook @@ -100,219 +99,244 @@ definition: variables: {} ``` - #### LifecyclePluginHookV1 {#lifecyclepluginhook-lifecyclepluginhookv1} Definition of a lifecycle plugin hook - version 1. - **One of the following values:** -| Value | Description | -|-----|-----| -| [LifecyclePreParsePluginHook](#lifecyclepluginhook-lifecyclepreparsepluginhook) | Definition of a lifecycle plugin hook for the pre-parse stage. | -| [LifecyclePreResponsePluginHook](#lifecyclepluginhook-lifecyclepreresponsepluginhook) | Definition of a lifecycle plugin hook for the pre-response stage. | -| [LifecyclePreRoutePluginHook](#lifecyclepluginhook-lifecyclepreroutepluginhook) | Definition of a lifecycle plugin hook for the pre-route stage. | - - +| Value | Description | +| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| [LifecyclePreParsePluginHook](#lifecyclepluginhook-lifecyclepreparsepluginhook) | Definition of a lifecycle plugin hook for the pre-parse stage. | +| [LifecyclePreResponsePluginHook](#lifecyclepluginhook-lifecyclepreresponsepluginhook) | Definition of a lifecycle plugin hook for the pre-response stage. | +| [LifecyclePreRoutePluginHook](#lifecyclepluginhook-lifecyclepreroutepluginhook) | Definition of a lifecycle plugin hook for the pre-route stage. | +| [LifecyclePreNdcRequestPluginHook](#lifecyclepluginhook-lifecyclepluginhook-lifecycleprendcrequestpluginhook) | Definition of a lifecycle plugin hook for the pre-ndc-request stage. | +| [LifecyclePreNdcResponsePluginHook](#lifecyclepluginhook-lifecyclepluginhook-lifecycleprendcresponsepluginhook) | Definition of a lifecycle plugin hook for the pre-ndc-response stage. | #### LifecyclePreRoutePluginHook {#lifecyclepluginhook-lifecyclepreroutepluginhook} Definition of a lifecycle plugin hook for the pre-route stage. -| Key | Value | Required | Description | -|-----|-----|-----|-----| -| `pre` | `route` | true | | -| `name` | string | true | The name of the lifecycle plugin hook. | -| `url` | [EnvironmentValue](#lifecyclepluginhook-environmentvalue) | true | The URL to access the lifecycle plugin hook. | -| `config` | [LifecyclePreRoutePluginHookConfig](#lifecyclepluginhook-lifecyclepreroutepluginhookconfig) | true | Configuration for the lifecycle plugin hook. | +| Key | Value | Required | Description | +| -------- | ------------------------------------------------------------------------------------------- | -------- | -------------------------------------------- | +| `pre` | `route` | true | | +| `name` | string | true | The name of the lifecycle plugin hook. | +| `url` | [EnvironmentValue](#lifecyclepluginhook-environmentvalue) | true | The URL to access the lifecycle plugin hook. | +| `config` | [LifecyclePreRoutePluginHookConfig](#lifecyclepluginhook-lifecyclepreroutepluginhookconfig) | true | Configuration for the lifecycle plugin hook. | +#### LifecyclePreNdcRequestPluginHook {#lifecyclepluginhook-lifecyclepluginhook-lifecycleprendcrequestpluginhook} +Definition of a lifecycle plugin hook for the pre-ndc-request stage. -#### LifecyclePreRoutePluginHookConfig {#lifecyclepluginhook-lifecyclepreroutepluginhookconfig} +| Key | Value | Required | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `pre` | `ndcRequest` | true | | +| `name` | string | true | The name of the lifecycle plugin hook. | +| `connectors` | [string] | true | A list of data connectors that this plugin hook should be applied to. There can only be one plugin hook of this type per data connector. | +| `url` | [EnvironmentValue](#lifecyclepluginhook-environmentvalue) | true | The URL to access the lifecycle plugin hook. | +| `config` | [LifecyclePreNdcRequestPluginHookConfig](#lifecyclepluginhook-lifecyclepluginhook-lifecycleprendcrequestpluginhookconfig) | true | Configuration for the lifecycle plugin hook. | -Configuration for a lifecycle plugin hook. +#### LifecyclePreNdcResponsePluginHook {#lifecyclepluginhook-lifecyclepluginhook-lifecycleprendcresponsepluginhook} -| Key | Value | Required | Description | -|-----|-----|-----|-----| -| `matchPath` | string | true | Regex to match the request path | -| `matchMethods` | [[RequestMethod](#lifecyclepluginhook-requestmethod)] | true | Possible HTTP methods for the request | -| `request` | [LifecyclePreRoutePluginHookConfigRequest](#lifecyclepluginhook-lifecyclepreroutepluginhookconfigrequest) | true | Configuration for the request to the lifecycle plugin hook. | -| `response` | [LifecyclePreRoutePluginHookConfigResponse](#lifecyclepluginhook-lifecyclepreroutepluginhookconfigresponse) / null | false | Configuration for the response to the lifecycle plugin hook. | +Definition of a lifecycle plugin hook for the pre-ndc-response stage. +| Key | Value | Required | Description | +| ------------ | --------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `pre` | `ndcResponse` | true | | +| `name` | string | true | The name of the lifecycle plugin hook. | +| `connectors` | [string] | true | A list of data connectors that this plugin hook should be applied to. There can only be one plugin hook of this type per data connector. | +| `url` | [EnvironmentValue](#lifecyclepluginhook-environmentvalue) | true | The URL to access the lifecycle plugin hook. | +| `config` | [LifecyclePreNdcResponsePluginHookConfig](#lifecyclepluginhook-lifecyclepluginhook-lifecycleprendcresponsepluginhookconfig) | true | Configuration for the lifecycle plugin hook. | +#### LifecyclePreRoutePluginHookConfig {#lifecyclepluginhook-lifecyclepreroutepluginhookconfig} -#### LifecyclePreRoutePluginHookConfigResponse {#lifecyclepluginhook-lifecyclepreroutepluginhookconfigresponse} +Configuration for a lifecycle plugin hook. -Configuration for a lifecycle plugin hook response. +| Key | Value | Required | Description | +| -------------- | ------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------ | +| `matchPath` | string | true | Regex to match the request path | +| `matchMethods` | [[RequestMethod](#lifecyclepluginhook-requestmethod)] | true | Possible HTTP methods for the request | +| `request` | [LifecyclePreRoutePluginHookConfigRequest](#lifecyclepluginhook-lifecyclepreroutepluginhookconfigrequest) | true | Configuration for the request to the lifecycle plugin hook. | +| `response` | [LifecyclePreRoutePluginHookConfigResponse](#lifecyclepluginhook-lifecyclepreroutepluginhookconfigresponse) / null | false | Configuration for the response to the lifecycle plugin hook. | -| Key | Value | Required | Description | -|-----|-----|-----|-----| -| `headers` | [LifecyclePluginHookHeadersConfig](#lifecyclepluginhook-lifecyclepluginhookheadersconfig) / null | false | Configuration for the headers in the response from the engine. | +#### LifecyclePreRoutePluginHookConfigResponse {#lifecyclepluginhook-lifecyclepreroutepluginhookconfigresponse} +Configuration for a lifecycle plugin hook response. +| Key | Value | Required | Description | +| --------- | ------------------------------------------------------------------------------------------------ | -------- | -------------------------------------------------------------- | +| `headers` | [LifecyclePluginHookHeadersConfig](#lifecyclepluginhook-lifecyclepluginhookheadersconfig) / null | false | Configuration for the headers in the response from the engine. | #### LifecyclePreRoutePluginHookConfigRequest {#lifecyclepluginhook-lifecyclepreroutepluginhookconfigrequest} Configuration for a lifecycle plugin hook request. -| Key | Value | Required | Description | -|-----|-----|-----|-----| -| `headers` | [LifecyclePluginHookHeadersConfig](#lifecyclepluginhook-lifecyclepluginhookheadersconfig) / null | false | Configuration for the headers in the pre-route plugin hook HTTP requests. | -| `method` | [LifecyclePreRoutePluginHookConfigRequestMethods](#lifecyclepluginhook-lifecyclepreroutepluginhookconfigrequestmethods) | true | Configuration for the HTTP method for the pre-route plugin hook HTTP requests. | -| `rawRequest` | [PreRouteRequestConfig](#lifecyclepluginhook-prerouterequestconfig) | true | Configuration for the raw request body for the pre-route plugin hook HTTP requests. | - - +| Key | Value | Required | Description | +| ------------ | ----------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------- | +| `headers` | [LifecyclePluginHookHeadersConfig](#lifecyclepluginhook-lifecyclepluginhookheadersconfig) / null | false | Configuration for the headers in the pre-route plugin hook HTTP requests. | +| `method` | [LifecyclePreRoutePluginHookConfigRequestMethods](#lifecyclepluginhook-lifecyclepreroutepluginhookconfigrequestmethods) | true | Configuration for the HTTP method for the pre-route plugin hook HTTP requests. | +| `rawRequest` | [PreRouteRequestConfig](#lifecyclepluginhook-prerouterequestconfig) | true | Configuration for the raw request body for the pre-route plugin hook HTTP requests. | #### PreRouteRequestConfig {#lifecyclepluginhook-prerouterequestconfig} Configuration for the raw request body for the pre-route plugin hook HTTP requests. -| Key | Value | Required | Description | -|-----|-----|-----|-----| -| `path` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for adding/excluding the request path of the incoming request | -| `method` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for adding/excluding the request method of the incoming request | -| `query` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for adding/excluding the query params of the incoming request | -| `body` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for adding/excluding the body of the incoming request | - - +| Key | Value | Required | Description | +| -------- | ---------------------------------------------------- | -------- | ----------------------------------------------------------------------------- | +| `path` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for adding/excluding the request path of the incoming request | +| `method` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for adding/excluding the request method of the incoming request | +| `query` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for adding/excluding the query params of the incoming request | +| `body` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for adding/excluding the body of the incoming request | #### LifecyclePreRoutePluginHookConfigRequestMethods {#lifecyclepluginhook-lifecyclepreroutepluginhookconfigrequestmethods} Configuration for the method for the pre-route plugin hook HTTP requests. - **Value:** `GET` / `POST` - #### RequestMethod {#lifecyclepluginhook-requestmethod} Possible HTTP Request Methods for the incoming requests handled by the pre-route plugin hook. - **Value:** `GET` / `POST` / `PUT` / `DELETE` / `PATCH` - #### LifecyclePreResponsePluginHook {#lifecyclepluginhook-lifecyclepreresponsepluginhook} Definition of a lifecycle plugin hook for the pre-response stage. -| Key | Value | Required | Description | -|-----|-----|-----|-----| -| `pre` | `response` | true | | -| `name` | string | true | The name of the lifecycle plugin hook. | -| `url` | [EnvironmentValue](#lifecyclepluginhook-environmentvalue) | true | The URL to access the lifecycle plugin hook. | -| `config` | [LifecyclePreResponsePluginHookConfig](#lifecyclepluginhook-lifecyclepreresponsepluginhookconfig) | true | Configuration for the lifecycle plugin hook. | - - +| Key | Value | Required | Description | +| -------- | ------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------- | +| `pre` | `response` | true | | +| `name` | string | true | The name of the lifecycle plugin hook. | +| `url` | [EnvironmentValue](#lifecyclepluginhook-environmentvalue) | true | The URL to access the lifecycle plugin hook. | +| `config` | [LifecyclePreResponsePluginHookConfig](#lifecyclepluginhook-lifecyclepreresponsepluginhookconfig) | true | Configuration for the lifecycle plugin hook. | #### LifecyclePreResponsePluginHookConfig {#lifecyclepluginhook-lifecyclepreresponsepluginhookconfig} Configuration for a lifecycle plugin hook. -| Key | Value | Required | Description | -|-----|-----|-----|-----| -| `request` | [LifecyclePreResponsePluginHookConfigRequest](#lifecyclepluginhook-lifecyclepreresponsepluginhookconfigrequest) | true | Configuration for the request to the lifecycle plugin hook. | - - +| Key | Value | Required | Description | +| --------- | --------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------- | +| `request` | [LifecyclePreResponsePluginHookConfigRequest](#lifecyclepluginhook-lifecyclepreresponsepluginhookconfigrequest) | true | Configuration for the request to the lifecycle plugin hook. | #### LifecyclePreResponsePluginHookConfigRequest {#lifecyclepluginhook-lifecyclepreresponsepluginhookconfigrequest} Configuration for a lifecycle plugin hook request. -| Key | Value | Required | Description | -|-----|-----|-----|-----| -| `headers` | [LifecyclePluginHookHeadersConfig](#lifecyclepluginhook-lifecyclepluginhookheadersconfig) / null | false | Configuration for the headers. | -| `session` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for the session (includes roles and session variables). | -| `rawRequest` | [RawRequestConfig](#lifecyclepluginhook-rawrequestconfig) | true | Configuration for the raw request. | -| `rawResponse` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for the response. | - - +| Key | Value | Required | Description | +| ------------- | ------------------------------------------------------------------------------------------------ | -------- | --------------------------------------------------------------------- | +| `headers` | [LifecyclePluginHookHeadersConfig](#lifecyclepluginhook-lifecyclepluginhookheadersconfig) / null | false | Configuration for the headers. | +| `session` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for the session (includes roles and session variables). | +| `rawRequest` | [RawRequestConfig](#lifecyclepluginhook-rawrequestconfig) | true | Configuration for the raw request. | +| `rawResponse` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for the response. | #### LifecyclePreParsePluginHook {#lifecyclepluginhook-lifecyclepreparsepluginhook} Definition of a lifecycle plugin hook for the pre-parse stage. -| Key | Value | Required | Description | -|-----|-----|-----|-----| -| `pre` | `parse` | true | | -| `name` | string | true | The name of the lifecycle plugin hook. | -| `url` | [EnvironmentValue](#lifecyclepluginhook-environmentvalue) | true | The URL to access the lifecycle plugin hook. | -| `config` | [LifecyclePreParsePluginHookConfig](#lifecyclepluginhook-lifecyclepreparsepluginhookconfig) | true | Configuration for the lifecycle plugin hook. | - - +| Key | Value | Required | Description | +| -------- | ------------------------------------------------------------------------------------------- | -------- | -------------------------------------------- | +| `pre` | `parse` | true | | +| `name` | string | true | The name of the lifecycle plugin hook. | +| `url` | [EnvironmentValue](#lifecyclepluginhook-environmentvalue) | true | The URL to access the lifecycle plugin hook. | +| `config` | [LifecyclePreParsePluginHookConfig](#lifecyclepluginhook-lifecyclepreparsepluginhookconfig) | true | Configuration for the lifecycle plugin hook. | #### LifecyclePreParsePluginHookConfig {#lifecyclepluginhook-lifecyclepreparsepluginhookconfig} Configuration for a lifecycle plugin hook. -| Key | Value | Required | Description | -|-----|-----|-----|-----| -| `request` | [LifecyclePreParsePluginHookConfigRequest](#lifecyclepluginhook-lifecyclepreparsepluginhookconfigrequest) | true | Configuration for the request to the lifecycle plugin hook. | - - +| Key | Value | Required | Description | +| --------- | --------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------- | +| `request` | [LifecyclePreParsePluginHookConfigRequest](#lifecyclepluginhook-lifecyclepreparsepluginhookconfigrequest) | true | Configuration for the request to the lifecycle plugin hook. | #### LifecyclePreParsePluginHookConfigRequest {#lifecyclepluginhook-lifecyclepreparsepluginhookconfigrequest} Configuration for a lifecycle plugin hook request. -| Key | Value | Required | Description | -|-----|-----|-----|-----| -| `headers` | [LifecyclePluginHookHeadersConfig](#lifecyclepluginhook-lifecyclepluginhookheadersconfig) / null | false | Configuration for the headers. | -| `session` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for the session (includes roles and session variables). | -| `rawRequest` | [RawRequestConfig](#lifecyclepluginhook-rawrequestconfig) | true | Configuration for the raw request. | - - +| Key | Value | Required | Description | +| ------------ | ------------------------------------------------------------------------------------------------ | -------- | --------------------------------------------------------------------- | +| `headers` | [LifecyclePluginHookHeadersConfig](#lifecyclepluginhook-lifecyclepluginhookheadersconfig) / null | false | Configuration for the headers. | +| `session` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for the session (includes roles and session variables). | +| `rawRequest` | [RawRequestConfig](#lifecyclepluginhook-rawrequestconfig) | true | Configuration for the raw request. | #### RawRequestConfig {#lifecyclepluginhook-rawrequestconfig} Configuration for the raw request. -| Key | Value | Required | Description | -|-----|-----|-----|-----| -| `query` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for the query. | -| `variables` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for the variables. | - - +| Key | Value | Required | Description | +| ----------- | ---------------------------------------------------- | -------- | -------------------------------- | +| `query` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for the query. | +| `variables` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for the variables. | #### LeafConfig {#lifecyclepluginhook-leafconfig} Leaf Configuration. | Key | Value | Required | Description | -|-----|-----|-----|-----| - - +| --- | ----- | -------- | ----------- | #### LifecyclePluginHookHeadersConfig {#lifecyclepluginhook-lifecyclepluginhookheadersconfig} Configuration for a lifecycle plugin hook headers. -| Key | Value | Required | Description | -|-----|-----|-----|-----| -| `additional` | [HttpHeaders](#lifecyclepluginhook-httpheaders) / null | false | Additional headers to be sent with the request. | -| `forward` | [string] | false | Headers to be forwarded from the incoming request. | +| Key | Value | Required | Description | +| ------------ | ------------------------------------------------------ | -------- | -------------------------------------------------- | +| `additional` | [HttpHeaders](#lifecyclepluginhook-httpheaders) / null | false | Additional headers to be sent with the request. | +| `forward` | [string] | false | Headers to be forwarded from the incoming request. | + +#### HttpHeaders {#lifecyclepluginhook-httpheaders} +Key value map of HTTP headers to be sent with an HTTP request. The key is the header name and the value is a potential +reference to an environment variable. +| Key | Value | Required | Description | +| ------------- | --------------------------------------------------------- | -------- | ----------- | +| `` | [EnvironmentValue](#lifecyclepluginhook-environmentvalue) | false | | -#### HttpHeaders {#lifecyclepluginhook-httpheaders} +#### EnvironmentValue {#lifecyclepluginhook-environmentvalue} -Key value map of HTTP headers to be sent with an HTTP request. The key is the header name and the value is a potential reference to an environment variable. +Either a literal string or a reference to a Hasura secret -| Key | Value | Required | Description | -|-----|-----|-----|-----| -| `` | [EnvironmentValue](#lifecyclepluginhook-environmentvalue) | false | | +**Must have exactly one of the following fields:** +| Key | Value | Required | Description | +| -------------- | ------ | -------- | ----------- | +| `value` | string | false | | +| `valueFromEnv` | string | false | | +#### LifecyclePreNdcRequestPluginHookConfig {#lifecyclepluginhook-lifecyclepluginhook-lifecycleprendcrequestpluginhookconfig} -#### EnvironmentValue {#lifecyclepluginhook-environmentvalue} +Configuration for a lifecycle plugin hook. -Either a literal string or a reference to a Hasura secret +| Key | Value | Required | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------- | +| `request` | [LifecyclePreNdcRequestPluginHookConfigRequest](#lifecyclepluginhook-lifecyclepluginhook-lifecycleprendcrequestpluginhookconfigrequest) | true | Configuration for the request to the lifecycle plugin hook. | +#### LifecyclePreNdcRequestPluginHookConfigRequest {#lifecyclepluginhook-lifecyclepluginhook-lifecycleprendcrequestpluginhookconfigrequest} -**Must have exactly one of the following fields:** +Configuration for a lifecycle plugin hook request. -| Key | Value | Required | Description | -|-----|-----|-----|-----| -| `value` | string | false | | -| `valueFromEnv` | string | false | | +| Key | Value | Required | Description | +| ------------ | ------------------------------------------------------ | -------- | --------------------------------------------------------------------- | +| `headers` | [HttpHeaders](#lifecyclepluginhook-httpheaders) / null | false | Configuration for the headers. | +| `session` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for the session (includes roles and session variables). | +| `ndcRequest` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for the request. | + +#### LifecyclePreNdcResponsePluginHookConfig {#lifecyclepluginhook-lifecyclepluginhook-lifecycleprendcresponsepluginhookconfig} + +Configuration for a lifecycle plugin hook. + +| Key | Value | Required | Description | +| --------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------- | +| `request` | [LifecyclePreNdcResponsePluginHookConfigRequest](#lifecyclepluginhook-lifecyclepluginhook-lifecycleprendcresponsepluginhookconfigrequest) | true | Configuration for the request to the lifecycle plugin hook. | + +#### LifecyclePreNdcResponsePluginHookConfigRequest {#lifecyclepluginhook-lifecyclepluginhook-lifecycleprendcresponsepluginhookconfigrequest} + +Configuration for a lifecycle plugin hook request. + +| Key | Value | Required | Description | +| ------------- | ------------------------------------------------------ | -------- | --------------------------------------------------------------------- | +| `headers` | [HttpHeaders](#lifecyclepluginhook-httpheaders) / null | false | Configuration for the headers. | +| `session` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for the session (includes roles and session variables). | +| `ndcRequest` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for the request. | +| `ndcResponse` | [LeafConfig](#lifecyclepluginhook-leafconfig) / null | false | Configuration for the response. |