Crate grafbase_hooks

Expand description

§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.

Crate grafbase_hooksCopy item path