Forem: Silviu Glavan

Fully-Typed HTTP Router for AWS Lambda with Middy and Zod

Silviu Glavan — Sun, 12 Oct 2025 04:56:03 +0000

When I needed to add a couple of REST endpoints to a serverless project, I faced the age-old debate: Lambda monolith or individual handlers?

My rule of thumb is to avoid mixing event sources in a single handler. However, for REST APIs where the business logic lives in repository classes and service objects, the API layer is just an interface: basic CRUD with minimal logic. Creating separate Lambdas for each endpoint felt like overkill.

Since I was already using middy in the project, I discovered their http-router: a simple utility that forwards events to handlers based on method and path. It also handles extracting path parameters if you're using a /{proxy+} route in your API Gateway.

This felt like a natural fit, but I wanted more:

minimal boilerplate for the route handlers
parsed and fully typed route event and context
automatic validation of both request and response payloads with Zod
consistent response envelope that I don't have to worry about in the handler

The End Result

Here's what using the router looks like:

// api/src/routes/todos/get-todo.ts
import { z } from "zod";
import { GetCommand } from "@aws-sdk/lib-dynamodb";
import { createRoute, NotFoundError } from "@repo/http-router";
import { Todo, TodoSchema } from "../../models/todo";

export const getTodoRoute = createRoute({
  method: "GET",
  path: "/todos/{id}",
  schemas: {
    params: z.object({ id: z.uuid() }),
    response: TodoSchema,
  },
  handler: async (event, ctx) => {
    const result = await ctx.ddb.send(
      new GetCommand({
        TableName: ctx.env.tableName,
        Key: {
          PK: "TODO",
          SK: `METADATA#${event.params.id}`,
        },
      })
    );

    if (!result.Item) {
      throw new NotFoundError(`Todo with id '${event.params.id}' not found`);
    }

    return result.Item as Todo;
  },
});

// api/src/lambda/execute-request.ts
import middy from "@middy/core";
import httpCors from "@middy/http-cors";
import httpHeaderNormalizer from "@middy/http-header-normalizer";
import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import {
  httpErrorHandler,
  httpRouteContext,
  httpRouterHandler,
  NotFoundError,
} from "@repo/http-router";
import { routes } from "../routes";

if (!process.env.TABLE_NAME) {
  throw new Error("TABLE_NAME not available in env");
}

export const ddbClient = DynamoDBDocumentClient.from(new DynamoDBClient());

export const context = {
  env: {
    tableName: process.env.TABLE_NAME,
  },
  ddb: ddbClient,
};

declare module "@repo/http-router" {
  interface Register {
    context: typeof context;
  }
}

export const handler = middy(
  httpRouterHandler({
    routes,
    notFoundResponse: ({ method, path }) => {
      console.warn("Not found resource", method, path);
      throw new NotFoundError("Not found");
    },
  })
)
  .use(httpRouteContext(context))
  .use(httpHeaderNormalizer())
  .use(httpCors())
  .use(httpErrorHandler());

Throughout the code samples I'll most likely exclude the utilities and types implementation. A full example can be found here: https://github.com/silviuglv/lambda-http-router

As you can see above, the router is contained in a local package called @repo/http-router. This contains the full implementation and re-exports the main @middy/http-router handler as well.

Here's How It Works

The solution has four main components:

createRoute factory - Wraps the route handler with validation and type inference
httpRouteParser middleware - Validates requests/responses and formats the event and context
httpRouteContext middleware - Stashes the user-defined context and adds it to the route handler at runtime
httpErrorHandler middleware - Catches errors and formats consistent error responses

Dependencies:

@middy/core - Main middy package
@middy/http-router - Main handler router, we're building on top of it
aws-lambda - Utility types for Lambda
zod - Schema validation and type inference

1: The Route Factory

This is the main interface you'll use. It takes your handler config and returns a configured route for middy's http-router:

// packages/http-router/src/lib/create-route.ts
import {
  APIGatewayProxyEventV2,
  APIGatewayProxyStructuredResultV2,
  Handler,
} from "aws-lambda";
import middy from "@middy/core";
import { Method, Route } from "@middy/http-router";
import {
  ParamsSchema,
  RouteContext,
  RouteHandler,
  RouteSchemas,
} from "./types";
import { httpRouteParser } from "./route-parser";

export function createRoute<
  TPath extends string,
  TSchemas extends RouteSchemas,
  TContext extends RouteContext
>(config: {
  method: Method;
  path: TPath;
  schemas?: TSchemas & {
    params?: ParamsSchema<TPath>;
  };
  handler: RouteHandler<TPath, TSchemas, TContext>;
}): Route<APIGatewayProxyEventV2, APIGatewayProxyStructuredResultV2> {
  return {
    method: config.method,
    path: config.path,
    handler: middy(
      config.handler as unknown as Handler<
        APIGatewayProxyEventV2,
        APIGatewayProxyStructuredResultV2
      >
    ).use(httpRouteParser({ schemas })),
  };
}

This is the simplest module of the implementation. It takes the route definition and maps it to an http-router compliant object, with some middlewares attached to the handler.

The main benefit is in the types: we get automatic inference for the schemas and the path params.

Type inference in action:

createRoute({
  method: "GET",
  path: "/todos/{id}",
  schemas: {
    params: z.object({ id: z.uuid() }),
    response: TodoSchema,
  },
  handler: async (event, ctx) => {
    // (parameter) event: {
    //   body: undefined;
    //   params: {
    //     id: string;
    //   };
    //   query: Record<string, string>;
    //   headers: Record<string, string>;
    // };
    //
    // (parameter) ctx: {
    //   env: {
    //     tableName: string;
    //   };
    //   ddb: DynamoDBDocumentClient;
    //   requestId: string;
    //   _raw: {
    //     event: APIGatewayProxyEventV2;
    //     context: Context;
    //   };
    // };
  },
});

A couple of things to notice:

params.id type can be inferred without a schema, but you can enforce it to a stricter type, like a UUID
You still have access to the full Lambda event and context via ctx._raw

No manual type annotations needed. If you return the wrong shape or reference a non-existent parameter, TypeScript catches it.

2: The Route Parser Middleware

This middleware does the heavy lifting. It parses and transforms requests in the before hook, then validates responses in the after hook:

// packages/http-router/src/lib/route-parser.ts
import { z } from "zod";
import type {
  APIGatewayProxyStructuredResultV2,
  APIGatewayProxyEventV2,
  Context,
} from "aws-lambda";
import type { MiddlewareObj } from "@middy/core";
import { Internal, ParsedContext, RouteEvent, RouteSchemas } from "./types";
import {
  BadRequestError,
  InternalServerError,
  UnsupportedMediaTypeError,
} from "./errors";
import {
  contextCache,
  formatDataResponse,
  INTERNAL_CONTEXT_KEY,
  isRouteEvent,
} from "./utils";

const validateField = (schema: z.ZodType, value: unknown, field: string) => {
  try {
    return schema.parse(value);
  } catch (error) {
    throw new BadRequestError(
      `Invalid request ${field}`,
      error instanceof z.ZodError
        ? z.flattenError(error).fieldErrors
        : undefined
    );
  }
};

export function httpRouteParser<T extends RouteSchemas>(options: {
  schemas?: T;
}): MiddlewareObj<
  APIGatewayProxyEventV2 | RouteEvent<string, T>,
  APIGatewayProxyStructuredResultV2 | Record<string, unknown>,
  Error,
  Context,
  Internal
> {
  return {
    before: async (request) => {
      // Safe guard
      if (isRouteEvent(request.event)) {
        return request.event;
      }

      const { schemas } = options;

      // Stash the raw event and context into internals.
      const __rawEvent = request.event as APIGatewayProxyEventV2;
      const __rawContext = request.context as Context;

      Object.assign(request.internal, { __rawEvent, __rawContext });

      let body: unknown = __rawEvent.body;

      if (typeof __rawEvent.body === "string" && schemas?.body) {
        try {
          body = JSON.parse(__rawEvent.body);
        } catch {
          throw new UnsupportedMediaTypeError("Request body is not valid JSON");
        }
      }

      const parsed = {
        __type: "route",
        body: schemas?.body
          ? validateField(schemas.body, body, "body")
          : undefined,
        params: schemas?.params
          ? validateField(
              schemas.params,
              __rawEvent.pathParameters ?? {},
              "params"
            )
          : undefined,
        query: schemas?.query
          ? validateField(
              schemas.query,
              __rawEvent.queryStringParameters ?? {},
              "query"
            )
          : undefined,
        headers: __rawEvent.headers,
      } as RouteEvent<string, T>;

      const parsedContext: ParsedContext = {
        requestId: __rawContext.awsRequestId,
        _raw: { event: __rawEvent, context: __rawContext },
      };

      const userContext = contextCache.get(INTERNAL_CONTEXT_KEY) ?? {};

      const routeContext = {
        __type: "route",
        ...userContext,
        ...parsedContext,
        // Middy requires this to capture timeout errors.
        getRemainingTimeInMillis: () => {
          return __rawContext.getRemainingTimeInMillis();
        },
      };

      request.event = parsed;
      request.context = routeContext as unknown as Context;
    },

    after: async (request) => {
      const { schemas } = options;

      request.event = request.internal.__rawEvent;
      request.context = request.internal.__rawContext;

      if (request.response?.statusCode) {
        return;
      }

      const requestId = request.context.awsRequestId;

      let data = request.response;

      if (schemas?.response) {
        const result = schemas.response.safeParse(data);

        if (!result.success) {
          throw new InternalServerError("Response validation failed");
        }

        data = result.data;
      }

      request.response = formatDataResponse(
        200,
        data as Record<string, unknown>,
        {
          metadata: { requestId },
        }
      );
    },
  };
}

This could probably be cleaned up a bit, as it's kind of hard to follow what's going on. Here's the gist:

before middleware

This is called first with the event and context in the request object from the main Lambda handler.

The route handler requires different objects, but we don't want to lose the initial ones as other middlewares upstream may need them. So we stash them in the internal object (something middy provides) for the time being.

Here, we also handle incoming event validation based on the route schemas.

after middleware

It runs after the route handler has executed.

It restores the main event and context, parses the response to ensure we're not leaking unwanted data at runtime, and formats it into a consistent envelope.

3: Route Context Middleware

// packages/http-router/src/lib/route-context.ts
import type { MiddlewareObj } from "@middy/core";
import { contextCache, INTERNAL_CONTEXT_KEY } from "./utils";

export function httpRouteContext<T extends Record<string, unknown>>(
  context: T
): MiddlewareObj {
  return {
    before: async () => {
      contextCache.set(INTERNAL_CONTEXT_KEY, context);
    },
  };
}

This is a simple one. It takes the context object provided in the Lambda and adds it to a cache so the router middlewares can access it.

We do this because each route handler starts a new middy instance. This means we lose references to shared data like request.internal.

4: Error Handler

import { MiddlewareObj } from "@middy/core";
import {
  APIGatewayProxyEventV2,
  APIGatewayProxyStructuredResultV2,
} from "aws-lambda";
import { formatErrorResponse } from "./utils";
import { HttpError } from "./errors";

export function httpErrorHandler(): MiddlewareObj<
  APIGatewayProxyEventV2,
  APIGatewayProxyStructuredResultV2
> {
  return {
    onError: async (request) => {
      const error = request.error;
      const requestId = request.context.awsRequestId;

      if (error instanceof HttpError) {
        request.response = formatErrorResponse(
          error.statusCode,
          {
            code: error.code,
            message: error.message,
            details: error.details,
          },
          {
            metadata: { requestId },
          }
        );

        return;
      }

      // Error thrown by @middy/http-router for unsupported methods, eg. `TRACE`
      if (error instanceof Error && error.message === "Method not allowed") {
        request.response = formatErrorResponse(
          405,
          {
            code: "MethodNotAllowed",
            message: error.message,
          },
          { metadata: { requestId } }
        );

        return;
      }

      // You may want to add some loggers here.
      request.response = formatErrorResponse(
        500,
        {
          code: "InternalServerError",
          message: "An unexpected error occurred",
        },
        { metadata: { requestId } }
      );
    },
  };
}

This middleware catches any errors thrown by your handler or parser middleware. If it's one of our HttpError classes (like NotFoundError or BadRequestError), it formats it into the error envelope with the appropriate status code. If it's an unknown error, we log it for debugging but return a generic 500 error to the client—we don't want to leak stack traces or internal details.

Custom error classes:

// packages/http-router/src/lib/errors.ts
export abstract class HttpError extends Error {
  abstract readonly statusCode: number;
  abstract readonly code: string;

  constructor(message: string, public readonly details?: unknown) {
    super(message);
    this.name = this.constructor.name;
  }
}

export class BadRequestError extends HttpError {
  readonly statusCode = 400;
  readonly code = "BadRequest";
}

export class NotFoundError extends HttpError {
  readonly statusCode = 404;
  readonly code = "NOT_FOUND";
}

export class InternalServerError extends HttpError {
  readonly statusCode = 500;
  readonly code = "INTERNAL_SERVER_ERROR";
}

Each error class defines its HTTP status code and error code. In your handlers, you just throw the appropriate error:

handler = async (event) => {
  const resource = await repos.resources.get(event.params.resourceId);

  if (!resource) {
    throw new NotFoundError("Resource not found");
  }

  return resource;
};

The middleware handles the rest: formatting the response, setting status codes, and ensuring consistency.

Response Format

All responses follow the same structure. Here's what clients receive:

Success:

{
  "success": true,
  "data": {
    "id": "123",
    "title": "Example Resource",
    "status": "active"
  },
  "meta": {
    "requestId": "abc-def-123",
    "timestamp": "2025-10-10T12:00:00.000Z"
  }
}

Error:

{
  "success": false,
  "error": {
    "code": "NotFound",
    "message": "Resource not found"
  },
  "meta": {
    "requestId": "abc-def-123",
    "timestamp": "2025-10-10T12:00:00.000Z"
  }
}

The success boolean makes it easy for clients to handle responses without checking status codes. The requestId is useful for debugging and correlating logs.

Why This Approach?

This solution fits a specific use case: APIs that are primarily interface layers with thin CRUD operations. If your routes share similar concerns (auth, logging, error handling) and you're already using middy and Zod, this approach reduces boilerplate while maintaining type safety.

What's Next

The current implementation covers my routing needs, but here are some ideas I'm considering, like OpenAPI Schema Generation. The Zod schemas contain all the information needed to generate OpenAPI specs. It's a matter of traversing route definitions and mapping Zod types to OpenAPI types.

Try It Yourself

I've published the complete implementation with examples and tests on GitHub: https://github.com/silviuglv/lambda-http-router

Building a GraphQL Transformer for AWS AppSync: Part 2 – Schema Design

Silviu Glavan — Mon, 24 Feb 2025 15:41:57 +0000

I originally intended to write a single post on both schema & table design, but it was getting too long, so I decided to split it into two.

A couple of days ago, I shared my motivation for building a GraphQL Transformer Library for AppSync and what I aim to achieve with it. Since then, I’ve made good progress and wanted to share some decisions regarding schema design.

You can read the full article here, but to setup the context, here are some constrains I had from the beginning:

Global Object IDs and Node Interface support;
GraphQL Connections-based pagination;
Interfaces and Unions support;

Before diving into these practises and their impact on the transformer, let's consider an example schema:

type Author @model {
  id: ID!
  name: String
  posts: Post @hasMany
  tags: Tag @hasMany
}

type Post @model {
  id: ID!
  title: String
  date: String
  content: String
  tags: Tag @hasMany(relation: manyMany)
  author: Author @hasOne
}

type Tag @model {
  name: String
  color: String
}

If you are familiar with GraphQL SDL this should make sense. The @model directive defines objects, while @hasOne and @hasMany define relationships.

Global Object IDs & Node Interface

Both are part of the same specification, which defines a standardized way for clients to access any node in the graph.

Consistent object access enables simple caching and object lookups

In practice, each object must implement a Node interface, and a root field called node that must accept an ID argument and return a Node.

The transformer handles this automatically. Here’s how the schema looks after transformation:

interface Node {
  id: ID!
}

type Post implements Node {
  id: ID!
  title: String
  date: String
  content: String
  tags(
    filter: TagEdgeFilterInput
    first: Int
    after: String
    sort: SortDirection
  ): TagConnection!
  author: Author
  createdAt: AWSDateTime
  updatedAt: AWSDateTime
}

type Tag implements Node {
  id: ID!
  name: String
  color: String
  createdAt: AWSDateTime
  updatedAt: AWSDateTime
}

# ...other types are ommited

type Query {
  node(id: ID!): Node
  # ...other fields are ommited
}

Notice the difference in the Tag type. The reference schema lacked an id field, but the transformed version includes it. This isn't an omission—GraphQL requires all types implementing an interface to define its fields. The transformer ensures compliance by adding any missing fields.

Connections

When listing objects, various implementations exist, but they all share a need for pagination.

The connections spec standardizes cursor-based pagination. Instead of diving into the details, let’s look at how the transformation our fields:

type Author implements Node {
  # ... other fields
  tags(
    filter: TagFilterInput
    first: Int
    after: String
    sort: SortDirection
  ): TagConnection!
}

type Post implements Node {
  # ... other fields
  tags(
    filter: TagEdgeFilterInput
    first: Int
    after: String
    sort: SortDirection
  ): TagConnection!
}

type TagEdge {
  cursor: String
  node: Tag
}

type TagConnection {
  edges: [TagEdge!]!
  pageInfo: PageInfo!
}

type PageInfo {
  hasNextPage: Boolean
  hasPreviousPage: Boolean
  startCursor: String
  endCursor: String
}

Let's focus on the TagEdge for a bit. It may seem meaningless since it is just a wrapper around Tag, but it plays a key role in normalizing the differences between how we model one-to-many and many-to-many relationships.

Another benefit is that it can have other fields as well. For example, if declaring a task list where tasks have different orders in various lists, an order field can be added to the edge.

This will become clearer in the next post on table design.

Interfaces and Unions

Since we introduced interfaces earlier, I won’t go into much detail—just know that you can use them. Unions work similarly but don’t require shared fields.

Here’s an example:

type File implements Node {
  id: ID!
  name: String!
  objectKey: String!
  mimeType: String
}

type Note implements Node {
  id: ID!
  name: String
  content: String
}

union Resource = File | Note

type Author implements Node {
  # ... other fields
  resources(
    filter: ResourceEdgeFilterInput
    first: Int
    after: String
    sort: SortDirection
  ): ResourceConnection
}

# ... other objects

From a schema perspective, unions don’t require much explanation. However, their impact on table design will become clearer in the next post.

In this article, I've introduced only the basics of how the transformer works and its core features.

We haven't covered how to define authorization with the @auth directive, attach custom resolvers or data sources, or use utility directives like @readOnly and @writeOnly.

So, stay tuned for more updates and happy coding!

Building a GraphQL Transformer Library for AWS AppSync: Part 1 – Motivation

Silviu Glavan — Sun, 16 Feb 2025 22:00:00 +0000

When it comes to building GraphQL servers, AWS AppSync is my favourite solution. It is a managed, serverless service that makes it easy to build efficient and scalable APIs.

Why AWS AppSync?

I really like AppSync for a few simple reasons:

Managed & Serverless: It handles so much for you, like observability and security.
JavaScript Runtime: I can write my resolvers in JavaScript, which feels much more natural.
Fast Performance: There are no cold starts, so things run quickly.
Advanced Features: Built-in features like caching, DeltaSync, and conflict resolution really help with complex tasks.

But here’s the catch: setting up an API with AppSync means I have to write the GraphQL schema, create resolvers for every operation, and then configure all the AWS resources. Even small changes can turn into a headache.

About Amplify

Another solution that uses AppSync under the hood is Amplify, a toolchain developed by the AWS folks designed to help developers get started with their services. While I like their approach of describing the entire schema via a config file, it does come with a set of design decisions that I don’t fully agree with, most notably:

It creates one DynamoDB table per model;
It uses VTL (Velocity Templating Language) to generate resolvers, which makes it hard to customise;
It generates complex pipelines for each resolver—good luck finding the right one to modify!

Luckily, Amplify is an open-source project, so we can take a look at how they do things.

The AppSync GraphQL Transformer Library

Inspired by the idea of declaring models and relationships with simple directives, and having a code generator take care of the rest, I decided to build my own library for AppSync.

Although I want it to be as extensible as possible, I had to make some design decisions right away. Here’s what I’m aiming for:

DynamoDB Single Table Design: Use a single table as the primary data source.
JS Runtime Resolvers: Generate JavaScript runtime resolvers that are easy to modify or replace with custom implementations.
TypeScript Support: Generate schema types and handle transpiling and bundling of resolver code.
GraphQL Best Practices: Follow best practices, including Connections and Global Object IDs.

I aim to create it as a standalone library, independent of any infrastructure-as-code solution. However, to make it easier to work with, I'm also developing a CDK construct that will provision all the necessary resources for you.

What’s Next?

The project is currently in progress and not yet open source. I plan to have an experimental release ready in a couple of days, and then I’ll make the repository public on Saapless.

Stay tuned for more updates, and happy coding!