Quickstart

Introduction

For this quickstart, we'll use the allowlist plugin. This adds an allowlist layer on top of your supergraph to restrict access to only specific queries or mutations.

We're using Cloudflare Wrangler

In this example, we're using Cloudflare Wrangler to deploy our plugin as a Cloudflare Worker. However, you can use any other tool or service that hosts HTTPS services you wish. You can get started with Wrangler here.

Step 1. Create a new Worker project

Create a new Cloudflare Worker project using the create-cloudflare command with the allowlist plugin template:

npm create cloudflare@latest allowlist-plugin -- --template https://github.com/hasura/engine-plugin-allowlist

Step 2. Install the dependencies

Navigate to the new directory and install the dependencies.

cd allowlist-plugin
npm install

Also, start the local development server.

npm start

Step 3. Add the plugin configuration

We'll let the engine know about the plugin and to execute it as a pre-parse plugin by creating a new metadata file. In your global subgraph's metadata directory, create a new file named allow-list.hml and add the following configuration.

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: {}

Using environment variables

We've used valueFromEnv so that we can dynamically and securely add values from our environment variables. You can add these values to your root-level .env and then map them in the globals subgraph.yaml file. Alternatively, you can include raw strings here using value instead of valueFromEnv and passing the keys.

Next, update the subgraph.yaml file to include the metadata file and the environment variables.

kind: Subgraph
version: v2
definition:
  name: globals
  ...
  includePaths:
    ...
    - allowlist-plugin.hml
  envMapping:
    ALLOW_LIST_URL:
      fromEnv: ALLOW_LIST_URL
    M_AUTH_KEY:
      fromEnv: M_AUTH_KEY

Finally, we need to add the environment variables to the .env file.

ALLOW_LIST_URL="http://local.hasura.dev:8787"
M_AUTH_KEY="your-strong-m-auth-key"

M-Auth Key

The hasura-m-auth header is a custom header that is used to authenticate the requests to the allowlist plugin. You can use any strong key here to authenticate the plugin. DDN will automatically add this header to the requests to the plugin. Also, make sure to update the src/config.ts file (in step 5) with the same key.

Step 4. Create a new build for local development

Create a new supergraph build.

ddn supergraph build local

Start the console for the local supergraph.

ddn console --local

You can now test the plugin by running queries or mutations that are not in the allowlist. The plugin will restrict access to only the queries or mutations you've defined.

Step 5. Update the plugin config

Update the src/config.ts file with the queries and mutations that you want to allow, using a strong m-auth key.

export const Config = {
  headers: {
    "hasura-m-auth": "your-strong-m-auth-key",
  },
  allowlist: [
    ...,
    "query MyQuery {\n  getAuthorById(author_id: 10) {\n    first_name\n    id\n    last_name\n  }\n}",
  ],
};

Hot reloading

The local wrangler development server will automatically reload the plugin when you make changes to the code.

Step 6. Configure the plugin variables

Setup tracing

To enable tracing for the plugin, you need to update the wrangler.toml file with the required configurations. If you don't want to enable tracing for the plugin, you can skip this step.

In allowlist-plugin directory, update the wrangler.toml file with the required configurations.

...
[vars]
OTEL_EXPORTER_OTLP_ENDPOINT = "https://gateway.otlp.hasura.io:443/v1/traces"
OTEL_EXPORTER_PAT = "<PAT>"

Replace <PAT> with the Personal Access Token (PAT) for the Hasura Cloud account. You can generate this using the ddn auth print-pat command.

Step 7. Deploy the plugin

For your plugin to be reachable by your hosted supergraph, we'll need to deploy using Cloudflare Wrangler. The deploy command included in your plugin's package.json will do this automatically for you and return the hosted service's URL.

Note: Please also update the wrangler.toml with your cloud PAT for the tracing to work.

npm run deploy

This will deploy the plugin to Cloudflare Workers and return the URL of the hosted service. Next, update the .env.cloud file with the URL.

ALLOW_LIST_URL="https://<your-deployed-plugin>.workers.dev"
M_AUTH_KEY="your-strong-m-auth-key"

Step 8. Create a new build

Create a new supergraph build.

ddn supergraph build create

The engine will execute the plugin before each request using the queries or mutations you defined.