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 for an example.

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.	PreParse or PreResponse
config.request	The shape of the request object.	PreParse or PreResponse
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	LifecyclePluginHookV1	true	Definition of a lifecycle plugin hook - version 1.

Example:

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

LifecyclePluginHookV1

Definition of a lifecycle plugin hook - version 1.

One of the following values:

Value	Description
LifecyclePreParsePluginHook	Definition of a lifecycle plugin hook for the pre-parse stage.
LifecyclePreResponsePluginHook	Definition of a lifecycle plugin hook for the pre-response stage.
LifecyclePreRoutePluginHook	Definition of a lifecycle plugin hook for the pre-route stage.

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

LifecyclePreRoutePluginHookConfig

Configuration for a lifecycle plugin hook.

Key	Value	Required	Description
matchPath	string	true	Regex to match the request path
matchMethods	[RequestMethod]	true	Possible HTTP methods for the request
request	LifecyclePreRoutePluginHookConfigRequest	true	Configuration for the request to the lifecycle plugin hook.
response	LifecyclePreRoutePluginHookConfigResponse / null	false	Configuration for the response to the lifecycle plugin hook.

LifecyclePreRoutePluginHookConfigResponse

Configuration for a lifecycle plugin hook response.

Key	Value	Required	Description
headers	LifecyclePluginHookHeadersConfig / null	false	Configuration for the headers in the response from the engine.

LifecyclePreRoutePluginHookConfigRequest

Configuration for a lifecycle plugin hook request.

Key	Value	Required	Description
headers	LifecyclePluginHookHeadersConfig / null	false	Configuration for the headers in the pre-route plugin hook HTTP requests.
method	LifecyclePreRoutePluginHookConfigRequestMethods	true	Configuration for the HTTP method for the pre-route plugin hook HTTP requests.
rawRequest	PreRouteRequestConfig	true	Configuration for the raw request body for the pre-route plugin hook HTTP requests.

PreRouteRequestConfig

Configuration for the raw request body for the pre-route plugin hook HTTP requests.

Key	Value	Required	Description
path	LeafConfig / null	false	Configuration for adding/excluding the request path of the incoming request
method	LeafConfig / null	false	Configuration for adding/excluding the request method of the incoming request
query	LeafConfig / null	false	Configuration for adding/excluding the query params of the incoming request
body	LeafConfig / null	false	Configuration for adding/excluding the body of the incoming request

LifecyclePreRoutePluginHookConfigRequestMethods

Configuration for the method for the pre-route plugin hook HTTP requests.

Value: GET / POST

RequestMethod

Possible HTTP Request Methods for the incoming requests handled by the pre-route plugin hook.

Value: GET / POST / PUT / DELETE / PATCH

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

LifecyclePreResponsePluginHookConfig

Configuration for a lifecycle plugin hook.

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

LifecyclePreResponsePluginHookConfigRequest

Configuration for a lifecycle plugin hook request.

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

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

LifecyclePreParsePluginHookConfig

Configuration for a lifecycle plugin hook.

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

LifecyclePreParsePluginHookConfigRequest

Configuration for a lifecycle plugin hook request.

Key	Value	Required	Description
headers	LifecyclePluginHookHeadersConfig / null	false	Configuration for the headers.
session	LeafConfig / 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	LeafConfig / null	false	Configuration for the query.
variables	LeafConfig / null	false	Configuration for the variables.

LeafConfig

Leaf Configuration.

Key	Value	Required	Description

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