Crate grafbase_hooks

Grafbase Gateway Hooks

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};

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

• access_log
  Provides a simple access log for the gateway.
• http_client
  A HTTP client module for executing HTTP requests in the host runtime. The functions are blocking from the guest, but are run asynchronously in the host. While the request is being executed, the guest runtime can continue to run other code.

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.
• EdgeDefinition
  Defines an edge in a type
• 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.
• NodeDefinition
  Defines a node
• RequestError
  An error from a GraphQL request.
• SharedContext
  The context as a read-only object.
• 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.