Skip to main content
Version: v3.x

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: {}
FieldDescriptionReference
nameThe name of the lifecycle plugin hook.LifecyclePluginHookPreParse
urlThe URL to access the plugin.LifecyclePluginHookPreParse
preThe stage of the request lifecycle.LifecyclePluginHookPreParse
configConfiguration for the plugin.PreParse or PreResponse
config.requestThe shape of the request object.PreParse or PreResponse
config.request.headersThe headers that should be included for each request.LifecyclePluginHookHeadersConfig
config.request.rawRequestThe configuration of the raw request, including any queries or variables.RawRequestConfig

Metadata structure

LifecyclePluginHook

Definition of a lifecycle plugin hook.

KeyValueRequiredDescription
kindLifecyclePluginHooktrue
versionv1true
definitionLifecyclePluginHookV1trueDefinition 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:

ValueDescription
LifecyclePreParsePluginHookDefinition of a lifecycle plugin hook for the pre-parse stage.
LifecyclePreResponsePluginHookDefinition of a lifecycle plugin hook for the pre-response stage.

LifecyclePreResponsePluginHook

Definition of a lifecycle plugin hook for the pre-response stage.

KeyValueRequiredDescription
preresponsetrue
namestringtrueThe name of the lifecycle plugin hook.
urlEnvironmentValuetrueThe URL to access the lifecycle plugin hook.
configLifecyclePreResponsePluginHookConfigtrueConfiguration for the lifecycle plugin hook.

LifecyclePreResponsePluginHookConfig

Configuration for a lifecycle plugin hook.

KeyValueRequiredDescription
requestLifecyclePreResponsePluginHookConfigRequesttrueConfiguration for the request to the lifecycle plugin hook.

LifecyclePreResponsePluginHookConfigRequest

Configuration for a lifecycle plugin hook request.

KeyValueRequiredDescription
headersLifecyclePluginHookHeadersConfig / nullfalseConfiguration for the headers.
sessionLeafConfig / nullfalseConfiguration for the session (includes roles and session variables).
rawRequestRawRequestConfigtrueConfiguration for the raw request.
rawResponseLeafConfig / nullfalseConfiguration for the response.

LifecyclePreParsePluginHook

Definition of a lifecycle plugin hook for the pre-parse stage.

KeyValueRequiredDescription
preparsetrue
namestringtrueThe name of the lifecycle plugin hook.
urlEnvironmentValuetrueThe URL to access the lifecycle plugin hook.
configLifecyclePreParsePluginHookConfigtrueConfiguration for the lifecycle plugin hook.

LifecyclePreParsePluginHookConfig

Configuration for a lifecycle plugin hook.

KeyValueRequiredDescription
requestLifecyclePreParsePluginHookConfigRequesttrueConfiguration for the request to the lifecycle plugin hook.

LifecyclePreParsePluginHookConfigRequest

Configuration for a lifecycle plugin hook request.

KeyValueRequiredDescription
headersLifecyclePluginHookHeadersConfig / nullfalseConfiguration for the headers.
sessionLeafConfig / nullfalseConfiguration for the session (includes roles and session variables).
rawRequestRawRequestConfigtrueConfiguration for the raw request.

RawRequestConfig

Configuration for the raw request.

KeyValueRequiredDescription
queryLeafConfig / nullfalseConfiguration for the query.
variablesLeafConfig / nullfalseConfiguration for the variables.

LeafConfig

Leaf Configuration.

KeyValueRequiredDescription

LifecyclePluginHookHeadersConfig

Configuration for a lifecycle plugin hook headers.

KeyValueRequiredDescription
additionalHttpHeaders / nullfalseAdditional headers to be sent with the request.
forward[string]falseHeaders 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.

KeyValueRequiredDescription
<customKey>EnvironmentValuefalse

EnvironmentValue

Either a literal string or a reference to a Hasura secret

Must have exactly one of the following fields:

KeyValueRequiredDescription
valuestringfalse
valueFromEnvstringfalse
Loading...