Engine Plugins

Introduction

Engine plugins are a way to extend the functionality of the Hasura GraphQL Engine. Engine plugins are executed at various stages of the request lifecycle. Engine plugins can be used to modify the request, response, or to perform custom operations.

How LifeCyclePluginHooks work

Lifecycle plugin hooks are not generated by default when a Hasura project is created. They need to be manually added to the metadata. To see a guide, check out this page.

When you create a LifeCyclePluginHook, you define the configuration for the plugin in your metadata by passing information like the URL of the hosted plugin and its name. The plugin is then executed at the specified stage of the request lifecycle.

After creating a new LifeCyclePluginHook in your metadata, you'll need to create a new build using the CLI.

Examples

An example of a LifecyclePluginHook:

kind: LifecyclePluginHook
version: v1
definition:
  name: cloudflare allowlist
  url:
    valueFromEnv: ALLOW_LIST_URL
  pre: parse
  config:
    request:
      headers:
        additional:
          hasura-m-auth:
            valueFromEnv: M_AUTH_KEY
      session: {}
      rawRequest:
        query: {}
        variables: {}

Field	Description	Reference
name	The name of the lifecycle plugin hook.	LifecyclePluginHookPreParse
url	The URL to access the plugin.	LifecyclePluginHookPreParse
pre	The stage of the request lifecycle.	LifecyclePluginHookPreParse
config	Configuration for the plugin.	LifecyclePluginHookConfig
config.request	The shape of the request object.	LifecyclePluginHookConfigRequest
config.request.headers	The headers that should be included for each request.	LifecyclePluginHookHeadersConfig
config.request.rawRequest	The configuration of the raw request, including any queries or variables.	RawRequestConfig

Metadata structure

LifecyclePluginHook

Definition of a lifecycle plugin hook.

Key	Value	Required	Description
kind	LifecyclePluginHook	true
version	v1	true
definition	LifecyclePluginHookPreParse	true

Example:

kind: LifecyclePluginHook
version: v1
definition:
  pre: parse
  name: test
  url: http://localhost:8080
  config:
    request:
      headers:
        additional:
          hasura-m-auth:
            value: zZkhKqFjqXR4g5MZCsJUZCnhCcoPyZ
      session: {}
      rawRequest:
        query: {}
        variables: {}

LifecyclePluginHookPreParse

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	string	true	The URL to access the lifecycle plugin hook.
config	LifecyclePluginHookConfig	true	Configuration for the lifecycle plugin hook.

LifecyclePluginHookConfig

Configuration for a lifecycle plugin hook.

Key	Value	Required	Description
request	LifecyclePluginHookConfigRequest	true	Configuration for the request to the lifecycle plugin hook.

LifecyclePluginHookConfigRequest

Configuration for a lifecycle plugin hook request.

Key	Value	Required	Description
headers	LifecyclePluginHookHeadersConfig / null	false	Configuration for the headers.
session	{} / null	false	Configuration for the session (includes roles and session variables).
rawRequest	RawRequestConfig	true	Configuration for the raw request.

RawRequestConfig

Configuration for the raw request.

Key	Value	Required	Description
query	{} / null	false	Configuration for the query.
variables	{} / null	false	Configuration for the variables.

LifecyclePluginHookHeadersConfig

Configuration for a lifecycle plugin hook headers.

Key	Value	Required	Description
additional	HttpHeaders / null	false	Additional headers to be sent with the request.
forward	[string]	false	Headers to be forwarded from the incoming request.

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
<customKey>	EnvironmentValue	false

EnvironmentValue

Either a literal string or a reference to a Hasura secret

Must have exactly one of the following fields:

Key	Value	Required	Description
value	string	false
valueFromEnv	string	false