Skip to main content

Framework adapters

GuildGate HTTP adapters map a framework request into RequestEnvelope, translate the action result into an HTTP response, and apply session metadata to the response.

Fastify​

import { fastifyActionHandler } from "@kavtuai/guildgate/fastify";

app.patch(
  "/api/guilds/:guildId/settings",
  fastifyActionHandler(gate, updateSettings, {
    input: (request) => ({
      ...(request.body as object),
      guildId: (request.params as { guildId: string }).guildId,
    }),
  }),
);

Express​

import { expressActionHandler } from "@kavtuai/guildgate/express";

app.patch(
  "/api/guilds/:guildId/settings",
  expressActionHandler(gate, updateSettings, {
    input: (request) => ({
      ...request.body,
      guildId: request.params.guildId,
    }),
  }),
);

Hono​

import { honoActionHandler } from "@kavtuai/guildgate/hono";

app.patch(
  "/api/guilds/:guildId/settings",
  honoActionHandler(gate, updateSettings, {
    input: async (context) => ({
      ...(await context.req.json()),
      guildId: context.req.param("guildId"),
    }),
  }),
);

Proxy and IP information​

Supplying a trustworthy client IP depends on the application's proxy policy. Do not trust every X-Forwarded-For value directly. Configure which proxy is trusted at the Cloudflare, Nginx, or load-balancer boundary.

Origin and cookies​

An adapter must process these metadata fields:

  • replacementSessionToken
  • replacementCsrfToken
  • clearSessionCookie

In 1.1.0, expired or revoked sessions carry cookie-clearing information through Fastify, Express, and Hono responses. Preserve the same behavior in a custom adapter.

Input merging​

When combining route parameters, query, and body fields, define precedence explicitly. Do not let the body override a security-sensitive route identity.

input: (request) => ({
  ...request.body,
  guildId: request.params.guildId,
})

Because guildId is assigned last, a body value cannot replace the route identity.

Error response​

Send the stable code and localized message from ActionExecutionResult.error. Do not expose stack traces, SQL text, Discord tokens, or internal exception objects. Preserve requestId for logs and support records.

Custom adapter checks​

Test these properties for a new framework adapter:

  • method and path are mapped correctly
  • multi-value origin, cookie, and header values are narrowed safely
  • abort signal follows connection closure
  • replacement and clearing cookie metadata is applied
  • an error status is not written twice
  • the domain action is not called again after the response finishes
Last updated on