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. Your hooks library must be compiled with the cargo-component toolchain, which compiles the hooks as a wasm32-wasip1 module, and inserts the needed shims so the module can act as a wasm32-wasip2 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.

The hooks are compiled with the cargo-component subcommand:

cargo component build --release

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"

Re-exports

• pub use hooks::hooks;
• pub use hooks::HookExports;
• pub use hooks::HookImpls;

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
  A structure representing a request that will be sent to a subgraph.
• 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.