Introducing plugins for Hasura DDN: An easy, modular framework to customize your API

We are excited to introduce plugins to Hasura Data Delivery Network (DDN), a powerful framework designed to let you easily extend the capabilities of your API with custom logic via HTTP webhooks.

Out of the box, Hasura DDN provisions a fully functioning API over all our data sources, complete with access control, governance, low latency, reliability, and more. However, we understand that all applications have unique demands. Plugins give developers a simple and modular way to customize the API to meet their exact needs easily.

The plugin framework is now available on Hasura DDN. We have also released two plugins for much-requested capabilities: caching and allow lists. Both of these plugins are open source licensed and available for free.

All Hasura DDN users can deploy these plugins or create their own custom plugins. Explore the documentation to learn more, or try it in your existing projects today!

In this post, we’ll look at the new plugin architecture for Hasura DDN and some examples of plugins that have already been implemented.

To understand why and how we build the plugin framework, let’s first look at the lifecycle of an API request in Hasura DDN.  

When a request comes into the Hasura DDN engine, the first thing it does after authentication is parse the request. The engine needs to understand what’s involved in the user’s query to know which backend data sources are involved and what they need to do to construct the response.

For example, imagine Hasura DDN is connected to a PostgreSQL database with an artists table and a MySQL database with an albums table. Now, consider a user requesting a list of all folk artists and their most recent album.

The engine must recognize that this query involves two different data sources. It must first query the source of the albums to determine the most recent release, then use that information to fetch the corresponding data from the artists' source. Then the Hasura DDN engine communicates with the backend’s data connectors to retrieve the necessary information, assemble the response based on the user’s query, and deliver it to the user.

With the new plugin architecture, we are introducing new hooks in the lifecycle of a request – these are points at which a plugin may influence the execution flow. With these hooks, plugins can abort execution early, influence responses, and observe incoming and outgoing traffic.

Today, we’ll review the first two hooks: pre-parsing and pre-response.

Pre-parse plugins

Pre-parse plugins execute before the request is parsed. This means that the engine hasn’t understood the structure of the request, or figured out what’s involved in fulfilling it – at this point, all it knows is there is an incoming query. The plugin receives this query in full, as well as session variables and the user role executing the query.

With this information, the engine can do one of four things according to the status code it returns:

• Continue 204: Allow execution to continue as normal without influence.
• Response 200: Return a response immediately and thus skip the rest of the execution.
• User error 400: Stop execution and return a user error to the client.
• Internal error 500: Stop execution and return a server error to the client.

Currently, a pre-parse plugin cannot modify the contents of the request that comes through, though the response 200 case allows us to handle a request within a plugin however we like.

A pre-parse plugin is suitable for many use cases, such as enforcing an allowed list of API operations, limiting the rate of requests to an API, validating queries according to custom business logic, and checking for previously cached responses to the given operation.

Pre-response plugins

Pre-response plugins execute just before the response is returned to the user. At this point, relevant backend data sources have been queried and the response has been assembled by the engine.

The plugin receives both the original request and the prepared response and allows us to perform tasks such as audit logging, writing to the cache, or even triggering notifications. The plugin cannot modify the response being sent to the user.

With the launch of the plugin system, we’re excited to introduce our first two plugins: allow list and caching. These plugins are open source, free to use, and fully customizable, allowing you to use or modify them to fit your needs.

An allowlist of operations

The allowlist plugin checks whether incoming requests are in the “allowed list” of queries that can be made to a given server. Users can specify which operations should be allowed to continue, and all other operations are discarded before engine execution continues. This allows precise control over, for example, how a user is allowed to mutate the data source, or perhaps prevents users from running costly queries against data sources that charge based on usage.

A whole-request cache

The caching plugin runs on both the pre-parse and pre-response hooks. In the pre-parse stage, the request (including its session variables) is parsed and transformed into a cache key. For any query marked as cacheable, we then look in the cache for a corresponding response and return it to the user if available. Otherwise, we will continue with the execution.

At the pre-response stage, for any cacheable query that isn’t currently cached, we re-generate the cache key and insert the response into the cache. With this plugin, we can eliminate pressure on the data source for common queries, particularly those that require a lot of expensive aggregation operations.

Plugins are standalone HTTP servers that run alongside Hasura DDN and can be implemented in any language capable of hosting an HTTP server. To use a plugin in your Hasura DDN projects, you’ll need to host the plugin and then configure your metadata to use it.

Hosting the plugin

A plugin is a regular HTTP service that can be hosted however you prefer. Many simple plugins can be hosted as serverless applications with services such as Cloudflare Workers, Google Cloud Serverless, and AWS Lambda, though note that specific plugins might have specific requirements for hosting.

For example, if a plugin needs to communicate with a Redis cache, then some serverless platforms may not support non-HTTP communication. See the individual READMEs of different plugins for recommendations on how to host them.

Configuring plugins in metadata

The exact shape and specification of plugin metadata will depend on the individual plugins, but let’s look at a rough template:

kind: LifecyclePluginHook
version: v1
definition:
  name: my plugin name
  url:
    valueFromEnv: PLUGIN_URL
  pre: parse
  config:
    request:
      session: {}
      rawRequest:
        query: {}
    variables: {}

When we declare a plugin in our metadata, the important things we need to declare are where to find the plugin, when to run the plugin, and what to send to the plugin.

In this template, we store the plugin URL in the `PLUGIN_URL` environment variable, declare that we’d like it to run on the pre-parse phase, and that we’d like to send the plugin the session data and variables as well as the raw user request.

We can also configure specific headers for plugins within this structure. Because plugins will be independently hosted services, we suggest that plugins require some sort of passkey known to Hasura DDN but not to the public so the plugin can verify the source of the requests. Different plugins require different configurations, so check out the individual plugin READMEs for more information!

We’ve illustrated several use cases here, and you may have gotten some ideas for other plugins that could be built. If you’re interested in developing your own plugins, see the docs for the complete plugin reference.

In the meantime, keep an eye out for more Hasura developments: We’re not only building more plugins – we’re also adding more event lifecycle hooks enabling even more complex business logic to be built on top of the Hasura platform.

Thanks for reading! We can’t wait to see what you do with the plugin system!

Ready to explore plugins for Hasura DDN? Simply click here to get started!