Hooks

Hooks allow you to invoke a composable local or remote function on a targeted node.

Some use cases for the Hooks include:

• Authenticating a user before all operations

• Checking for an authorization token before making a request

Hooks increase processing time. Use them sparingly if processing time is important. Hooks are executed in the order you provide them. However, any blocking hooks execute before non-blocking hooks.

Hook arguments

Hooks are plugins that accept the following arguments:

Copy
"hooks": {
    "beforeAll": {
        "composer": "<Local or Remote file>",
        "blocking": true|false
    }
}
Copied to your clipboard
"hooks": {
    "beforeAll": {
        "composer": "<Local or Remote file>",
        "blocking": true|false
    }
}

• composer (string) - The local or remote file location of the function you want to execute.

  You must add any local scripts to the mesh's files array. Local vs remote functions describes when to use a local or remote function.

  NOTE: Local composer functions are limited to 30 seconds. If blocking is set to true and the function takes longer than 30 seconds, you will receive a Timeout Error. If you repeatedly encounter this error, consider using a remote composer.

• blocking (boolean) - (false by default) Determines if the query waits for a successful return message before continuing the query.

  The blocking argument allows you to stop running hooks for a query that does not receive a successful response.

  If blocking is true and the composer returns an error, all future hook executions are canceled.

  If blocking is false and the composer returns an error, the composer will still be invoked.

Types of hooks

beforeAll

The beforeAll hook allows you to insert a function before the query takes place. This is a good place to add an authentication layer or anything else you want to run before your query.

Copy
"plugins": [
    {
        "hooks": {
            "beforeAll": {
                "composer": "./hooks.js#checkAuthHeader",
                "blocking": true
            }
        }
    }
],
Copied to your clipboard
"plugins": [
    {
        "hooks": {
            "beforeAll": {
                "composer": "./hooks.js#checkAuthHeader",
                "blocking": true
            }
        }
    }
],

Local vs remote functions

local composers are defined within your mesh.json file, whereas remote composers are only referenced within your mesh file. Local and remote composers have different advantages and limitations.

local composers

Use local composers if:

• The entire operation will take less than 30 seconds.

• The composer logic is simple and only requires access to the headers, body, and other context objects.

Avoid using local composers if:

• The entire operation will take more than 30 seconds.

• The composer needs to make network calls.

• The composer has complex or nested loops.

• The function uses restricted constructs, including: alert, debugger, eval, new Function(), process, setInterval, setTimeout, WebAssembly, or window.

Local composers require adding any local scripts to the mesh's files array.

Copy
{
  "meshConfig": {
    "sources": [
      {
        "name": "MagentoMonolithApi",
        "handler": {
          "graphql": {
            "endpoint": "https://venia.magento.com/graphql"
          }
        }
      }
    ],
    "plugins": [
      {
        "hooks": {
          "beforeAll": {
            "composer": "./hooks.js#checkAuthHeader",
            "blocking": true
          }
        }
      }
    ],
    "files": [
      {
        "path": "./hooks.js",
        "content": <FILE CONTENT>
      }
    ]
  }
}
Copied to your clipboard
{
  "meshConfig": {
    "sources": [
      {
        "name": "MagentoMonolithApi",
        "handler": {
          "graphql": {
            "endpoint": "https://venia.magento.com/graphql"
          }
        }
      }
    ],
    "plugins": [
      {
        "hooks": {
          "beforeAll": {
            "composer": "./hooks.js#checkAuthHeader",
            "blocking": true
          }
        }
      }
    ],
    "files": [
      {
        "path": "./hooks.js",
        "content": <FILE CONTENT>
      }
    ]
  }
}

Fetching from remote origins

Local composers also support fetching from remote origins using fetch().

The following example could be used as a beforeAll hook that validates an authorization token against a remote authorization endpoint using fetch().

Copy
module.exports = {
  validateToken: async ({ context }) => {
    const { headers } = context;
    const { authorization } = headers;
    
    if (!authorization) {
      return {
        status: "ERROR",
        message: "Authorization header is missing",
      };
    }
    
    try {
      // Validate the token against a remote authorization service
      const response = await fetch("https://auth.adobe.com/validate", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ token: authorization.replace("Bearer ", "") }),
      });
      
      const result = await response.json();
      
      if (!response.ok || !result.valid) {
        return {
          status: "ERROR",
          message: "Invalid authorization token",
        };
      }
      
      return {
        status: "SUCCESS",
        message: "Token validated successfully",
        data: {
          headers: {
            "x-user-id": result.userId,
          },
        },
      };
    } catch (error) {
      return {
        status: "ERROR",
        message: `Token validation failed: ${error.message}`,
      };
    }
  },
};
Copied to your clipboard
module.exports = {
  validateToken: async ({ context }) => {
    const { headers } = context;
    const { authorization } = headers;
    
    if (!authorization) {
      return {
        status: "ERROR",
        message: "Authorization header is missing",
      };
    }
    
    try {
      // Validate the token against a remote authorization service
      const response = await fetch("https://auth.adobe.com/validate", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ token: authorization.replace("Bearer ", "") }),
      });
      
      const result = await response.json();
      
      if (!response.ok || !result.valid) {
        return {
          status: "ERROR",
          message: "Invalid authorization token",
        };
      }
      
      return {
        status: "SUCCESS",
        message: "Token validated successfully",
        data: {
          headers: {
            "x-user-id": result.userId,
          },
        },
      };
    } catch (error) {
      return {
        status: "ERROR",
        message: `Token validation failed: ${error.message}`,
      };
    }
  },
};

remote composers

If a local composer does not work or causes timeout errors, consider using a remote composer.

remote composers can use the params, context, and document arguments over the network. However, the serialization and deserialization of JSON data means that any complex fields or references will be lost. If the composer depends on complex fields or references, consider using a local composer instead.

Example

Copy
{
  "meshConfig": {
    "sources": [
      {
        "name": "MagentoMonolithApi",
        "handler": {
          "graphql": {
            "endpoint": "https://venia.magento.com/graphql"
          }
        }
      }
    ],
    "plugins": [
      {
        "hooks": {
          "beforeAll": {
            "composer": "<Remote Composer URL>",
            "blocking": true
          }
        }
      }
    ]
  }
}
Copied to your clipboard
{
  "meshConfig": {
    "sources": [
      {
        "name": "MagentoMonolithApi",
        "handler": {
          "graphql": {
            "endpoint": "https://venia.magento.com/graphql"
          }
        }
      }
    ],
    "plugins": [
      {
        "hooks": {
          "beforeAll": {
            "composer": "<Remote Composer URL>",
            "blocking": true
          }
        }
      }
    ]
  }
}

Creating composers

A composer can be a local function or a remote serverless function. Composer signatures differ depending on the hook used and the location of the function.

beforeAll hooks

beforeAll hooks can receive the following fields as objects during runtime:

• context - An object containing information about the request.

  For example, context can contain headers, the body of the request, and the request object.

• document - A GraphQL representation of the query.

If the composer is a remote function, all the arguments are sent in the POST body when calling the function.

Local composer example

This simple composer checks for an authorization header before processing the query.

Copy
module.exports = {
  isAuth: ({context}) => {
    if (!context.headers.authorization) {
      return {
        status: "ERROR",
        message: "Unauthorized",
      };
    }
    return {
      status: "SUCCESS",
      message: "Authorized",
    };
  },
};
Copied to your clipboard
module.exports = {
  isAuth: ({context}) => {
    if (!context.headers.authorization) {
      return {
        status: "ERROR",
        message: "Unauthorized",
      };
    }
    return {
      status: "SUCCESS",
      message: "Authorized",
    };
  },
};

This remote composer fetches your authorization token and inserts it into the x-auth-token header.

Copy
function getToken({ authorization = "", body = "", url = "" }) {
  return `${authorization} - ${body} - ${url}`;
}

module.exports = {
  insertToken: ({ context }) => {
    const { headers, request, body } = context;
    const { authorization } = headers;
    const { url } = request;

    const authToken = getToken({ authorization, url, body });

    return {
      status: "SUCCESS",
      message: "Authorized",
      data: {
        headers: {
          "x-auth-token": authToken,
        },
      },
    };
  },
};
Copied to your clipboard
function getToken({ authorization = "", body = "", url = "" }) {
  return `${authorization} - ${body} - ${url}`;
}

module.exports = {
  insertToken: ({ context }) => {
    const { headers, request, body } = context;
    const { authorization } = headers;
    const { url } = request;

    const authToken = getToken({ authorization, url, body });

    return {
      status: "SUCCESS",
      message: "Authorized",
      data: {
        headers: {
          "x-auth-token": authToken,
        },
      },
    };
  },
};

Remote composer example

The following example remote composer checks for an authorization header.

Copy
addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));

async function handleRequest(event) {
    try {
        const body = await event.request.json();
        if (!body.context.headers["authorization"]) {
            return new Response({
                status: "SUCCESS",
                message: "Unauthorized"
            }, {
                status: 401
            });
        }
        return new Response({
            status: "SUCCESS",
            message: "Authorized"
        }, {
            status: 200
        });
    } catch (err) {
        return new Response(err, {
            status: 500
        });
    }
}
Copied to your clipboard
addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));

async function handleRequest(event) {
    try {
        const body = await event.request.json();
        if (!body.context.headers["authorization"]) {
            return new Response({
                status: "SUCCESS",
                message: "Unauthorized"
            }, {
                status: 401
            });
        }
        return new Response({
            status: "SUCCESS",
            message: "Authorized"
        }, {
            status: 200
        });
    } catch (err) {
        return new Response(err, {
            status: 500
        });
    }
}

Return signatures

The return signature of a composer is the same for local and remote functions.

Copy
{
  status: "ERROR" | "SUCCESS",
  message: string,
  data?: {
    headers?: {
        [headerName: string]: string
    }
  }
}
Copied to your clipboard
{
  status: "ERROR" | "SUCCESS",
  message: string,
  data?: {
    headers?: {
        [headerName: string]: string
    }
  }
}

onFetch hooks

You can use the onFetch plugin to intercept and modify HTTP requests before they are sent to your GraphQL sources.

The onFetch plugin can assist with the following use cases:

• Authentication: Adding dynamic auth tokens or API keys
• Conditional Headers: Adding headers based on query content or user context
• Request Tracking: Adding correlation IDs or request timestamps
• Request Modification: Transforming request body or parameters
• Logging: Adding custom logging or metrics

The onFetch plugin can also access your execution parameters, such as: root, args, context, and info.

The following example adds a custom header (x-md5-hash) to the request. This could be used to add a hash of the request body to the request headers for security purposes.

Copy
{
  "meshConfig": {
    "sources": [
      {
        "name": "CommerceAPI",
        "handler": {
          "graphql": {
            "endpoint": "https://venia.magento.com/graphql"
          }
        }
      }
    ],
    "plugins": [
      {
        "onFetch": [
          {
            "source": "commerceAPI",
            "handler": "./handleOnFetch.js"
          }
        ]
      }
    ]
  }
}
Copied to your clipboard
{
  "meshConfig": {
    "sources": [
      {
        "name": "CommerceAPI",
        "handler": {
          "graphql": {
            "endpoint": "https://venia.magento.com/graphql"
          }
        }
      }
    ],
    "plugins": [
      {
        "onFetch": [
          {
            "source": "commerceAPI",
            "handler": "./handleOnFetch.js"
          }
        ]
      }
    ]
  }
}

Copy
async function handleOnFetch(data) {
  const { context } = data;
  const { log } = context;

  try {
    data.options.headers["x-md5-hash"] = "test header value";
  } catch (e) {
    log(`Error setting hash header: ${e.message}`);
  }
}

module.exports = {
  default: handleOnFetch,
  __esModule: true,
};
Copied to your clipboard
async function handleOnFetch(data) {
  const { context } = data;
  const { log } = context;

  try {
    data.options.headers["x-md5-hash"] = "test header value";
  } catch (e) {
    log(`Error setting hash header: ${e.message}`);
  }
}

module.exports = {
  default: handleOnFetch,
  __esModule: true,
};

Last updated 6/12/2025

Was this helpful?

Yes

No