Crate grafbase_hooks 

Grafbase Gateway Hooks SDK

This crate provides the necessary types and macros to implement hooks for the Grafbase Gateway. A hook is a function that is called by the gateway at specific points in the request processing.

Build your own hooks by implementing the Hooks trait, add the grafbase_hooks attribute on top of the hooks implementation and register the hooks type to the gateway using the register_hooks macro.

The hooks component is a WASM module that is loaded by the gateway at startup. If you are using Rust version 1.83 or later, you can install the wasm32-wasip2 target with the following command:

rustup target add wasm32-wasip2

For older versions of Rust, you can use the wasm32-wasip1 target, but you must compile your hooks with the cargo-component toolchain, which adds a compatibility layer to the hooks module so it can be loaded by the gateway:

cargo install cargo-component

Usage

Create a new rust library project with cargo:

cargo new --lib my-hooks
cd my-hooks

Add the grafbase-hooks as a dependency:

cargo add grafbase-hooks --features derive

Edit the src/lib.rs file and add the following code:

use grafbase_hooks::{grafbase_hooks, register_hooks, Context, ErrorResponse, Headers, Hooks};

struct MyHooks;

#[grafbase_hooks]
impl Hooks for MyHooks {
    fn new() -> Self
    where
        Self: Sized,
    {
        MyHooks
    }

    fn on_gateway_request(
        &mut self,
        context: Context,
        headers: Headers
    ) -> Result<(), ErrorResponse> {
        if let Some(ref auth_header) = headers.get("authorization") {
           context.set("auth", auth_header);
        }

        Ok(())
    }
}

register_hooks!(MyHooks);

The example above implements the Hooks hook, which will be available in the gateway and will be called for every request.

The grafbase_hooks attribute is used to generate the necessary code for the hooks implementation and the register_hooks macro registers the hooks type to the gateway. The macro must be called in the library crate root.

To compile the hooks with Rust 1.83 or later:

cargo build --target wasm32-wasip2 --release

With older versions of Rust, the hooks are compiled with the cargo-component subcommand:

cargo component build --release

With Rust 1.83 or later, the compiled hooks wasm module is located in the target/wasm32-wasip2/release directory. With older versions of Rust, the compiled hooks wasm module is located in the target/wasm32-wasip1/release directory.

You can configure the gateway to load the hooks in the grafbase.toml configuration file:

[hooks]
location = "path/to/my_hooks.wasm"

Modules

host_io

Host IO modules.

Macros

register_hooks

Registers the hooks type to the gateway. This macro must be called in the library crate root for the local hooks implementation.

Structs

Context

A context object is available in all hooks during the whole request lifecycle. It can be used to store custom data in one hook and make it available in the hooks executed later in the request.

EdgeNodePostExecutionArguments

Arguments passed to the authorize_edge_node_post_execution hook.

EdgePostExecutionArguments

Arguments passed to the authorize_edge_post_execution hook.

EdgePreExecutionArguments

Arguments passed to the authorize_edge_pre_execution hook.

Error

An error response can be used to inject an error to the GraphQL response.

ErrorResponse

An HTTP error response.

ExecutedHttpRequest

Info about an executed HTTP request.

ExecutedOperation

Info about an executed operation.

ExecutedSubgraphRequest

Info about an executed subgraph request.

FieldError

An error returned from a field.

Headers

Provides access to the request headers. Available in a mutable form only in the gateway request hook.

NodePreExecutionArguments

Arguments passed to the authorize_node_pre_execution hook.

ParentEdgePostExecutionArguments

Arguments passed to the authorize_parent_edge_post_execution hook.

RequestError

An error from a GraphQL request.

SharedContext

The context as a read-only object.

SubgraphRequest

GraphQL HTTP request that will be sent to a subgraph. Allows inspecting and modifying the method, url and headers.

SubgraphResponse

Information on a response

Enums

CacheStatus

Cache status of a subgraph call.

GraphqlResponseStatus

A status of a GraphQL operation.

HeaderError

Error thrown when accessing the headers. Headers names or values must not contain any special characters.

LogError

Error variant sent if failing to write to access log.

SubgraphRequestExecutionKind

Subgraph response variant.

Traits

Hooks

Hooks are the main extension point for Grafbase. They allow you to intercept execution in various points of the request lifecycle.

Attribute Macros

grafbase_hooks

Registers the hook implementations to the gateway. This macro must be added to the local implementation of the Hooks trait.