Forem: ambergristle

Rate Limiting Hono Apps: An Introduction

ambergristle — Thu, 22 May 2025 04:57:38 +0000

Rate limiting is essential for most production applications. At a minimum, it prevents floods of traffic from crashing services, and it mitigates an app’s vulnerability to a variety of attacks. Adding and effectively configuring rate limiting is no simple task though. There are many rate limiting tools and strategies to choose from, and it’s difficult to find resources that concretely explain how to use rate limiting to improve an app’s security and resilience.

This is the first article in a series that will bring together the theory and practice of rate limiting, using contextualized real-world examples. In each article, I’ll demonstrate how to add different rate limiters to a Hono app, and discuss the technical and business requirements they fulfill.

I’ll begin with hono-rate-limiter, a low-lift solution that addresses many common rate limiting needs. While fairly simple to use, it will help illustrate key rate limiting concepts that will remain relevant throughout the series:

Appropriately identifying clients
Configuring the allowed request rate
Performantly tracking client requests
Communicating limits and handling rejected requests

In the next article, I’ll do a deeper dive into rate limiting algorithms and design, using the Upstash rate limiter to create custom rate limiting middleware. Finally, I’ll walk through how to roll your own rate limiting solution, shifting focus from high-level strategies and patterns to more specific implementation concerns.

First though, I’ll briefly introduce the “whats” and “whys” of rate limiting to provide some context for the following discussion of hono-rate-limiter implementations. This article won’t be especially technical, but it will help to have a basic familiarity with Hono apps, as well as the business and engineering requirements that affect backend development.

What is rate limiting anyway?

Simply put, rate limiters control how often a resource can be accessed, and by whom. To accomplish this, most limiters use some kind of identifier (e.g., user ID or client IP) to track requests from a given source, and an algorithm to determine if and when requests from each source should be allowed.

The specifics vary by algorithm and implementation, but most limiters are defined by:

A limit on how many requests can be made within a defined window of time
The cost of each request counted against the limit
How often a client’s limit is refilled or reset, allowing additional requests

Client consumption is measured in tokens (or as the sum of request timestamps), typically persisted in some kind of database. Each time the client makes a request, the rate limiting algorithm is used to determine whether the number of recent requests exceeds the limit. Excessive requests are usually rejected, with a Retry-After header specifying when the client can try again.

Why rate limit at all?

Rate limiting refers to a broad variety of policies and implementations with equally-diverse goals. It is most commonly deployed to manage service usage and capacity, but it also plays a vital role in auth workflows. Naturally, where and how this limiting is implemented depends greatly on the abuse vectors it guards against.

Resource Exhaustion

An app’s ability to process requests is essentially finite. If too many requests come in at once, an unprotected system could crash, or auto-scale to the tune of tens of thousands of dollars.

Floods of traffic may reflect an innocent spike in engagement—thousands of users flocking to buy tickets—or a Denial of Service (DoS) attack intended to block legitimate requests or bring down the server. In either case, rate limiting is used to cap processed requests at a manageable (and affordable) level.

Resource Exploitation

Even if an app can process all the traffic it’s receiving, it may not be serving clients equally or fairly. Especially in the case of paid services—where users expect a defined level of access—it’s vital to constrain how often clients can access resources.

Without account-based rate limits, a minority of users can hog the app’s capacity—e.g., through high-volume scraping, causing other users’ requests to lag or fail. Users can also exceed the consumption rate they’re paying for, leading to a “hidden” loss of revenue.

Note that “capacity” doesn’t refer only to how many requests a service can handle. Both malicious and innocent request patterns can over-consume other app resources, like the availability of merchandise on a digital marketplace (aka Inventory Denial).

Account Hijacking

Not all vulnerabilities are a matter of capacity. Rate limiting in auth workflows is primarily deployed against Brute Force and Credential Stuffing attacks. Brute force attacks attempt to gain access to a system by repeatedly guessing a user’s password, while credential stuffing blindly plugs known credentials into different services, seeking instances of their reuse.

Hono Rate Limiter

The easiest way to mitigate these risks in Hono apps is with hono-rate-limiter. Built to satisfy basic rate limiting needs in the Hono ecosystem, hono-rate-limiter is a port of the popular express-rate-limiter. While much of the API and core logic are the same, the library leverages Hono’s type system to share limiter results with downstream logic. It also includes Cloudflare-specific tooling to support development with the workerd runtime.

Like many Hono tools, hono-rate-limiter exports middleware that can be added app-wide, or to a single route or handler. This flexibility is especially important in the context of rate limiting, where multiple limiters may be layered to address different requirements. A data endpoint, for example, might need one rate limit to prevent resource exhaustion and another to enforce account-specific limits by subscription tier.

Window + Limit

As their name suggests, rate limiters constrain the number of requests allowed within a given period. This is typically expressed as a max or limit of requests, paired with a time interval that represents how often a client’s available requests are either reset or refilled. These are the primary levers used to configure and tune a rate limiter’s behavior, and each rate limiting algorithm leverages them differently to balance performance and accuracy.

Calculating client request rates

Fixed Window algorithms—like the one used by hono-rate-limiter, divide time into fixed-length windows (measured in milliseconds), and maintain a counter tracking the number of requests made in each. Setting the limit to 100 and windowMs to 60k, for example, allows 100 requests every minute. Requests that exceed the window limit are rejected until windowMs has elapsed, at which point the counter is reset.

import { Hono } from 'hono';
import { rateLimiter } from 'hono-rate-limiter';

const app = new Hono()
  .use(
    rateLimiter({
      windowMs: 60 * 1000,
      limit: 100,
      // ...
    }),
  );

Fixed Window limitations

The Fixed Window algorithm is the simplest and most performant, but it has a few key drawbacks. Since it uses fixed windows in time, the algorithm is too rigid to support occasional traffic bursts, even when they’re within the allowed long-term average.

It is also vulnerable to abuse at the window transition. By maxing out requests just before the current window expires, and just after the next begins, malicious clients can momentarily double the limit for a burst of requests.

In the next article, I’ll introduce more flexible and accurate options. Their increased efficacy comes at the cost of logical complexity and performance though, so for many use-cases the Fixed Window algorithm’s strengths outweigh its weaknesses.

Calibrating rate limits

The appropriate configuration for a rate limiter depends largely on the problem it’s meant to solve. Each use-case has distinct priorities and constraints, and effective rate limits are the product of balancing one against the other.

Limiters enforcing tiered API access balance resource costs against subscription prices, while those protecting auth routes prioritize security while allowing for some user error. Likewise, limiters preventing resource exhaustion should reflect average consumption relative to capacity.

When first adding a rate limiter, it’s best to choose a more conservative limit in order to ensure that all users have fair access and that service isn’t disrupted. This initial configuration can then be tuned over time to better reflect actual request patterns.

Sophisticated rate limiters may use dynamic limits to account for fluctuations throughout the day, or to handle traffic spikes related to planned events like a promotion or content release. In most cases though, using server metrics to regularly tune static rate limits is good enough.

Uniquely identifying clients

Both the standard and Cloudflare-specific middleware require a keyGenerator, which takes Hono Context as an argument and must return a string key. This key is used to distinguish between records in the limiter store, so for most use-cases it should be unique to each client.

While many rate limiting examples use the client IP for convenience, this isn’t recommended for production apps. IP addresses aren’t guaranteed to be unique, and bad actors can easily spoof IPs or obscure them with a VPN.

A user or account ID is the best option for most use-cases, since their uniqueness makes it easier to apply rate limits fairly and accurately. This is essential for premium APIs and other subscription services, which promise customers a defined level of access for each payment tier.

When to rate limit by IP

Rate limiters protecting pre-login or unprotected routes are a notable exception. Uniquely identifying clients is more difficult in these cases, but also less relevant to the limiters’ role, which is focused on security and capacity management more-so than regulating individual client usage.

In auth workflows, rate limiters make attempts to gain unauthorized access to the system logistically challenging or prohibitively expensive. Since users only need to submit their credentials once, any IPs that exceed a reasonable rate limit are suspicious, and may even be blocked after repeated violations.

Managing service capacity is a more generalized requirement, but is likewise decoupled from individual client usage. Rate limiting can be used to prevent apps from over-consuming downstream APIs, including third-party services. It can also ensure that resource use doesn’t exceed server capacity, or unexpectedly trigger expensive auto-scaling.

Safeguarding user privacy

Since rate limiting databases maintain a record of API usage by key, it’s also vital to consider user privacy when limiting by IP, or other personally-identifiable data. This also includes identifiers like geolocation and device fingerprints, which will be covered in greater detail later in the series.

Storing personally-identifiable data makes users vulnerable to doxxing, targeted cyber attacks, and government overreach. It can also make apps liable to laws like the EU’s GDPR or California’s CCPA, which are designed to protect users by regulating the collection and storage of personal data. Fortunately, there are a few simple steps we can take to protect users and their privacy:

When collecting or storing identifying data is necessary, clearly communicate to users what data is used and why.
Obscure identifying data like IPs with one-way hashes (e.g., HMAC), and regularly clear stale records from the limiter database.

As with every engineering problem, ethical rate limiting is a matter of compromise. We can’t safeguard both the application and its users without dealing with at least some identifying data. This shouldn’t be seen as an excuse to cut corners though, but rather as a challenge to better understand rate limiting tools and how to deploy them responsibly.

Generating keys from request data

Rate limiting on protected API routes should take place downstream from auth middleware. This avoids wasting resources limiting an unauthorized request, and ensures that the user or account ID is available when hono-rate-limiter is called.

import { Hono } from 'hono';
import { rateLimiter } from 'hono-rate-limiter';

type AppEnv = {
  Variables: {
    accountId: string;
  }
}

const app = new Hono()
  .use(authMiddleware)
  .use(
    rateLimiter<AppEnv>({
      // ...
      keyGenerator: (c) => {
        return c.var.accountId;
      },
    }),
  );

Accessing the ID type-safely in the keyGenerator is a two-step process:

First, the ID must be set in Context. Some Hono auth middleware do this internally, but others—like the built-in Bearer Auth—do not. In these cases, an additional layer of custom middleware is necessary.
Then, the variable must be added to a custom AppEnv type, passed to the rateLimiter middleware as a generic parameter. This type will be applied to the keyGenerator's Context argument, making the value available via c.var or c.get.

Note that this approach is truly type-safe only when the set invocation and AppEnv type are coupled. While this isn’t entirely possible due to Hono’s optimistic approach to type-safety, using factory helpers like createHandlers or createApp can help keep types in sync with the implementation.

Persisting request records

To keep track of client requests, rate limiters rely on some kind of mid-term persistence. Records don’t need to be maintained forever, but a stateless rate limiter would have no way to know how often a client was hitting the backend, so it would have to naively allow (or reject) every request.

Why not use local memory?

Many rate limiting examples or bare-bones implementations simply track client requests locally, often using a Map stored in memory. While this can be helpful during development, or for small apps running in a persisted environment, it isn’t a good solution at scale.

Local memory implementations break down in edge environments—where memory isn’t persisted long-term, and in distributed systems—where multiple app instances must be kept in sync. A local solution also means that the limiter and application logic share memory and compute, making scaling more difficult.

Connecting to remote databases

Remote in-memory databases are the most common solution, as they minimize latency in the rate limit layer. Since some algorithms require multiple database calls, atomicity is another important consideration when choosing a storage solution.

Atomic operations are completed as a single unit, even if they have multiple steps. This prevents race conditions that could result in conflicting limits results. I’ll discuss this topic more in the next article on rate limiting algorithms.

Redis is a popular choice, both because it is extremely performant, and because it makes it easy to run multi-step operations atomically. Other in-memory databases like Memcached or Cloudflare KV can also be used, though they are geared towards caching and don’t offer robust support for atomic operations.

Application architecture is arguably the most important factor though. Modern development patterns like distributed applications and edge functions introduce challenges and constraints that affect not just where data is stored, but also how it’s managed.

Distributed limiting

While a centralized store makes rate limit records available across requests and app instances, it introduces a request-processing bottleneck. A flood of requests from instances around the world can bog down the database, causing even legitimate requests to lag or time-out.

In distributed applications, centralized stores can also introduce significant latency. After reaching the handler, each request must first be diverted to the limiter—possibly in a different region—before returning to the handling server for processing.

In the era of edge functions (and runtimes), it’s no surprise that distributed rate limiters are increasingly popular. This strategy involves colocating a limiter data store with each app instance, thereby substantially reducing latency and avoiding a single point of failure.

Of course, distributed rate limiters bring their own set of challenges. As with any distributed database, updates must be synchronized across instances. This ensures that users can’t bypass the limit simply by changing their “location” with a VPN. Special care must also be taken to mitigate race conditions, especially when using non-unique identifiers like IPs.

Data storage with `hono-rate-limiter`

At the heart of hono-rate-limiter are its stores. These are adapters that implement the Fixed Window algorithm and communicate with the persistence layer. The library includes a Redis store compatible with a most Redis clients, as well as stores for Cloudflare KV databases and Durable Objects. It can also be paired with a half-dozen third-party stores, and developers can build their own to connect with a different database or use an alternative algorithm.

Setting up a store is pretty straightforward, though implementations and configuration options will depend on the store and database selected. In the simplest case, the initialized database client is passed to the store constructor. For more information on specific integrations, please refer to the hono-rate-limiter documentation.

import { RedisStore } from "@hono-rate-limiter/redis";
import { Redis } from "@upstash/redis";
// OR import { Redis } from "@upstash/redis/cloudflare";

const client = new Redis({
  url: "<UPSTASH_REDIS_REST_URL>",
  token: "<UPSTASH_REDIS_REST_TOKEN>",
});

app.use(
  rateLimiter({
    store: new RedisStore({ client }),
    // ...
  }),
);

Note that database options aren’t necessarily compatible with every architecture. Since the Cloudflare Workers runtime doesn’t support TCP connections, connecting with standard Redis databases would require a custom HTTP client. To use Redis with a Worker, an edge-compatible implementation like Upstash Redis is recommended. Connectivity issues aside, this will also make it easier to keep database instances (and rate limits) in sync.

Using the Cloudflare Rate Limit binding

An adapter for Cloudflare’s Rate Limit binding is also available as a standalone middleware. In this case, a store isn’t required, since the binding handles the algorithm and database connection internally. This also results in some important configuration and implementation differences.

The Cloudflare Rate Limit binding requires a window of either 10 or 60 seconds, restricting configurability. Limits are local to each location the Worker runs in, so a client could bypass limits by directing requests to different Worker instances.

import { cloudflareRateLimiter } from "@hono-rate-limiter/cloudflare";

type AppType = {
  Bindings: {
    // `RateLimit` type available globally through @cloudflare/workers-types
    RATE_LIMITER: RateLimit;
  }
}

app.use(
  cloudflareRateLimiter<AppType>({
    rateLimitBinding: (c) => c.env.RATE_LIMITER,
    keyGenerator: generateClientKey,
    // ...
  }),
);

Since the Cloudflare Rate Limit API doesn’t require a hono-rate-limiter store, it’s unclear which rate limit algorithm it uses. Based on this (somewhat dated) article though, it’s seems safe to assume it’s a Sliding Window Counter. In the next article, I'll cover the differences between it and the Fixed Window in detail. For now it's enough to know that the Sliding Window takes the same arguments but offers better accuracy and burst support, making it a better candidate for an enterprise product.

Implementation differences

Though the stores use the same algorithm, there is at least one significant difference in their implementation. When using hono-rate-limiter with Redis, the windowMs option is used to automatically delete windows when they expire, improving limiter performance. This behavior isn’t available when storing rate limit data with Cloudflare products like KV Stores or the Rate Limit binding though. Instead, the rate limiting clients exported by @hono-rate-limiter/cloudflare check whether the tracked window has expired on each request, and manually reset the counter when relevant.

Communicating rate limits

To improve user experience—and to help clients avoid accidentally hitting rate limits—it’s helpful to share rate limit and usage data with clients. In the simplest case, servers return a 429 error when a rate limit is exceeded. This isn’t especially helpful though, regardless of whether the client is an internal front-end, or an end-user. For this reason, both success and error responses often include rate limit information in their headers.

Rate limiters protecting auth logic from attacks are a notable exception. In these cases it is recommended to share as little as possible. Any details about the limit or when it resets make it easier to bypass limits, automate attacks, or avoid detection.

Rate limit headers

Though the standard format for rate limit headers has changed over time, the information shared has remained largely consistent:

Policy: The service’s request limit and window length in seconds.
Limit: How many requests the client is allowed within a given window.
Remaining: The number of allowed requests remaining (limit - consumed).
Reset: When the limit will be reset, in seconds.

By default, hono-rate-limiter uses the Draft 6 standard, setting each value in its own RateLimit-* header, and including only non-zero Reset values. It also supports the Draft 7 standard, which combines all fields except for Policy into a single RateLimit header, and always includes a Reset value. In both cases, a Retry-After header is set on error responses to let clients know when they can try again.

import { Hono } from 'hono';
import { rateLimiter } from 'hono-rate-limiter';

const app = new Hono()
  .use(
    rateLimiter({
      // ...
      standardHeaders: "draft-7", // or "draft-6"
    }),
  );

I’m not aware of any technical motivations for using one or the other, though Draft 7 may be preferable as it’s the most recent (available) standard. Since hono-rate-limiter's implementation of the two standards is essentially the same, the choice may come down to personal preference for the ergonomics of one or the other.

Customizing rate limiters for specific use-cases

Adding rate limiting to a Hono app with hono-rate-limiter is pretty simple, without incurring vendor lock-in or conforming to a prescriptive API. While it may not be sufficient for all use-cases, it’s a solid and easily-extensible starting point. Its greatest limitation may be its use of the Fixed Window algorithm, but this can be addressed with a custom store.

I hope that this has been a helpful introduction to rate limiting in the Hono ecosystem. In the next article I’ll cover rate limiting algorithms in greater depth, addressing their trade-offs and explain how to extend hono-rate-limiter with a custom store. If there’s something I’ve missed, or that you’d like me to cover in greater depth, please leave a comment below!

Seeding and deploying HONC apps

ambergristle — Mon, 24 Mar 2025 16:14:07 +0000

In the first article of this series, we walked through building Placegoose, a simple mock data API using the HONC stack. My goals were pretty simple:

Showcase solutions for common Hono project requirements, like relations and rate limiting
Provide a free mock data API that returns error responses for invalid requests

It’s easy enough to find Hono starter templates with a “Hello World” endpoint, or a basic configuration, but there are fewer resources out there that demonstrate how to integrate non-trivial services and functionality. In the same vein, many popular mock data APIs don’t validate requests or implement rate-limiting, which makes it impossible to test sad paths.

Placegoose was meant to be a step up in complexity from the average starter template, without becoming overly-specific. While you’re welcome to test out the API, you may find it more useful to clone the project and adjust the database schema and mock data to fit your needs.

What does production deployment entail?

In this article, we’ll be covering the steps to prepare apps like Placegoose for Cloudflare deployment. Placegoose is a fairly simple data API with statically-served docs, so we won’t be addressing monorepos or use-cases that require SSR or CSR front-ends.

I won’t be getting too technical, but you’ll need to be comfortable with web fundamentals and reading TypeScript, as I won’t be explaining implementation details. It will also help if you’re familiar with Drizzle configuration and database schemas. If you’re new to the HONC stack, I’d recommend giving the previous article a read first!

While many production deployments require a complex multi-stage build process that incorporates advanced features like testing or dependency optimization, we’ll focus on two key steps:

Creating and seeding a remote D1 database
Deploying a Workers project using the Cloudflare CLI

The CLI makes deploying simple apps fairly trivial, but seeding the remote D1 proved to be a little more complicated than anticipated. In this article, we’ll discuss some of the infrastructure constraints you may encounter, and the Cloudflare and Drizzle tooling used to work around them:

Seeding a remote D1 over HTTP using Drizzle’s generic HTTP adapter
Or using Cloudflare’s CLI to apply a locally-generated SQL file to a remote D1

Both solutions rely on locally-run scripts that use pre-generated data. With some adjustments, though, it should be possible to integrate them into a custom build process. Doing so was out of scope for Placegoose, but might be relevant if you regularly spin up demo instances for new clients.

If you have a better solution, or think you see a problem with one of the implementations, please let me know in the comments!

Getting set up with Cloudflare

When deploying Workers that rely on bindings to other Cloudflare services, we must first ensure that these services are live. Otherwise, we’ll get an error like this one:

binding DB of type d1 must have a database that already exists. Use wrangler or the UI to create the database. [code: 10021]

Creating Cloudflare services is simple enough. First, create a Cloudflare account, if you haven’t already, then run the d1 create command to create a new remote D1 database:

wrangler d1 create placegoose-d1

Once the database has been created, the script will log the binding details. You can also find these values in your Cloudflare dashboard. Be sure to update your wrangler.toml file with the logged database_id. You’ll also need to add your account ID, database ID, and Cloudflare API token to your prod.vars file in order to run local migration and seeding scripts.

[[d1_databases]]
binding = "DB"
database_name = "placegoose-d1"
database_id = "<DATABASE-ID-FROM-ABOVE>"
migrations_dir = "drizzle/migrations"

Now that our database is online, we can apply our migrations and begin to interact with it! Drizzle takes care of this for us with the drizzle-kit migrate command:

npm run ENVIRONMENT=production drizzle-kit migrate

By setting the ENVIRONMENT variable to production, we ensure that drizzle.config uses our production configuration (and credentials) for the migration.

If you’re following along, take a moment to inspect the database in your Cloudflare dashboard. You should see all the tables defined in your schema, along with a Drizzle-generated migrations table.

We could jump straight to deploying our app now, but it wouldn’t have any data to show us, so first we’ll seed it with the data we’ve already generated.

Database seeding

Seeding databases is a key component of application development, but it can often seem like a cumbersome afterthought. Especially in a project’s early days, when speed is of the essence, structuring and re-structuring seed data as your database evolves feels thrash-y. Mocking database calls feels much cheaper in comparison, at least when it comes to testing.

Seeding a database is the process of populating it with mock data that conforms to your spec. It’s useful throughout the product lifecycle: during development, testing, and demos.

I’ve worked on projects that mocked database calls, and “seeded” data for demos in the course of UI/UX testing. Setting aside the issues with using test data for demos, this approach quickly ran into scaling problems. In essence, we had traded managing database seeding for managing database mocks, which was no less cumbersome but much more fragile.

Even if it feels like a lot at first, using seed data for development—and especially testing, is a game-changer. Notably, it makes integration tests a lot easier, and in my experience it can be easier to keep in sync with your database schema. In fact, tools like drizzle-seed make this almost an afterthought by automatically generating seed data based on your latest schema.

Seeding Placegoose

When I got started on Placegoose, drizzle-seed had just been released. While intriguing, introducing it felt a bit like scope creep. If nothing else, it didn’t seem like it would support the goose theme I was going for, and solving that problem was definitely out of scope.

To create the seed data, I used a generative AI tool to create arrays of entries, which I saved in local project files. This worked well for Placegoose because the schema was essentially fixed, and there was no real need (or plans) to modify it. For most projects though, re-generating entries each time the schema changes would be cost-prohibitive, especially considering the amount of scrutiny AI-generated content requires.

Determining the right path to insert the data was equally a function of the project’s requirements and constraints. Unlike many projects, which grow and evolve with time, Placegoose is meant to serve as an example, and as a tool that can easily be run (and modified) locally. Seeding the remote database with a local script was the clear answer: it’s a little more transparent, and it can be integrated into an automated build process if needed.

Infrastructure constraints

This is where things get a little more complicated. While Workers run in the workerd runtime—and have access to bindings—any standalone scripts executed locally (or during the remote build ) run in a standard Node process. This means that there’s no way to directly call a remote D1 database via script.

Executing the script in the worker global scope or creating a standalone worker to handle seeding are both options, but they introduce problems of their own. Notably, they would require gating access to the seeding logic, and creating an additional worker would add extra complexity with minimal return.

Fortunately, we can also connect to D1 databases over HTTP. This allows us to pass our D1 credentials in the request, rather than relying on the binding. We can even keep using Drizzle to generate our SQL!

Seeding with Drizzle’s HTTP proxy

Drizzle offers an HTTP proxy driver that allows us to define how database requests are made, without modifying our query implementation.

First though, we need to adjust our drizzle.config so that drizzle-kit uses the HTTP driver when running in a production environment. The config definition is essentially the same: we only need to update the driver and dbCredentials properties, so that drizzle-kit can connect to our remote D1 when applying migrations (or introspecting).

import 'dotenv/config'; // We use dotenv to grab local environment variables
import { config } from "dotenv";
import { defineConfig, type Config } from 'drizzle-kit';

let drizzleConfig: Config;

if (process.env.ENVIRONMENT === 'production') {
    config({ path: './.prod.vars' });

    // Don't forget to update your local .prod.vars file!
    const accountId = process.env.CLOUDFLARE_ACCOUNT_ID;
    const databaseId = process.env.CLOUDFLARE_DATABASE_ID;
    const token = process.env.CLOUDFLARE_D1_TOKEN;

    // Make sure we actually set our credentials
    if (!accountId || !databaseId || !token) {
        console.error(
            `Configuration Failed: Missing Credentials`,
            JSON.stringify({ accountId, databaseId, token }, null, 2),
        );
        process.exit(1);
    }

    drizzleConfig = defineConfig({
      schema: './src/schema.ts',
      out: './migrations',
      dialect: 'sqlite',
      driver: 'd1-http', // Use the HTTP driver
      dbCredentials: {
        accountId,
        databaseId,
        token,
      },
    });

} else { 
    // Local config
}

export default drizzleConfig

Next, we’ll need to update our seed script to use the HTTP driver. This is slightly more involved, but still pretty straightforward.

Implementing the HTTP driver

The driver takes a callback responsible for making a single query, and an optional callback for making batches of requests. In the simplest case, the batch callback is just an iterative implementation of the single-query function we provide.

import { drizzle } from 'drizzle-orm/sqlite-proxy';

// Drizzle driver instance that we can use
// interchangeably with the d1 or libsql drivers
const db = drizzle(
    /**
     * AsyncBatchRemoteCallback
     */
    async (
        sql: string,
        params: any[],
        method: 'run' | 'all' | 'values' | 'get'
    ): Promise<{ rows: any[]; }> => { 
        // Execute a single query over HTTP
    },
    /**
     * AsyncBatchRemoteCallback
     */
    async (
        batch: {
        sql: string;
        params: any[];
        method: 'run' | 'all' | 'values' | 'get';
        }[]
    ): Promise<{ rows: any[]; }> => {
        // Iteratively execute an array of queries over HTTP
    },
    /**
     * Standard Drizzle config, instructs driver to
     * translate between snake and camel case column names
     */
    { casing: 'snake_case', }
);

Since we’re seeding relational data, we’ll want to take advantage of batches (which are executed as transactions), so we’ll need to implement both callbacks. Let’s start with the single-query case though, so we can get to know Cloudflare’s D1 HTTP query resource.

For the most part, Cloudflare’s query API matches the AsyncRemoteCallback function signature. Both accept a sql string, an array of params, and the method, so we can just pass those values through directly.

We’ll also need to specify the accountId, databaseId, and apiToken for our remote D1, as the credentials we set in drizzle.config are only used by drizzle-kit.

Below is a minimal implementation of the single-query callback. The fetch request itself is extremely simple, but it takes a few steps to unpack the response and handle any errors. For more details on response typing, refer to the Cloudflare API docs.

import type { AsyncRemoteCallback } from "drizzle-orm/sqlite-proxy";

type D1HttpQueryResponse = {
  errors?: { code: number; message: string; }[];
    messages?: { code: number; message: string; }[];
    result?: { results: unknown[]; success: boolean; }[];
    success?: boolean;
}

const httpQueryD1: AsyncRemoteCallback = (
  sql: string,
  params: unknown[],
  method: string,
): Promise<{ rows: unknown[][] }> => {
    const url = `https://api.cloudflare.com/client/v4/accounts/${accountId}/d1/database/${databaseId}/query`;

  const response = await fetch(url, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ sql, params, method }),
  });

  if (response.status !== 200) {
      /** HTTP request failed */
  }

    // Based on the Cloudflare docs
    // In practice, the type should be validated at runtime
  const dbResponse: D1HttpQueryResponse = await res.json();
  if (dbResponse.errors.length > 0 || !dbResponse.success) { 
      /** Query failed */ 
    }

    const queryResult = dbResponse?.result?.at(0);
    if (!queryResult?.success) {
        /** Query failed */ 
    }

  // Format row data
  const rows = queryResult.results.map((row) => {
      if (row instanceof Object) {
          return Object.values(row);
      }

      throw new Error('Unexpected Response', {
          cause: dbResponse,
      });
  });

  return { rows };
}

Note that since Cloudflare’s D1 query endpoint returns results as JSON, we’ll need to flatten the values from each row into an array. Since the returned results are inherently unknown, we can use an instanceof check to let TypeScript know that each array element can be unpacked with Object.values. While it might be tempting to save a few lines by casting to any, doing so should be strictly avoided. The cost to your type safety is almost never justified.

With our single-query callback implemented, creating a function to handle batch queries is fairly trivial. We just need to loop over the array of queries, pass the arguments into our single-query function, and push the returned rows into our results array.

const httpBatchQueryD1: AsyncBatchRemoteCallback = async (
    queries: {
        sql: string;
        params: unknown[];
      method: string;
    }[]
): Promise<{ rows: unknown[][] }> => {
    const results = [];

    for (const query of queries) {
      const { sql, params, method } = query;
      const result = await httpQueryD1(sql, params, method);
      results.push(result);
    }

    return results;
};

If we try to run the script though, we run into an error! Cloudflare limits us to 100 bound variables for D1 queries. This means that we can insert no more than 20 rows of 5 columns each at a time (for example), assuming we’re only using variables to insert values.

400 Bad Request
{
    "errors":[{
        "code":7500,
        "message":"too many SQL variables at offset 420: SQLITE_ERROR"
    }],
    "success":false
}

Chunking writes

To work around this limit, we can seed our data in chunks. This is a common pattern for handling large inserts, and shouldn’t pose any problems for an app of this scale. To accomplish this, we can use a simple utility to break our data into appropriately-sized arrays. Remember, the formula for determining maximum chunk size is 100 / column count, so you may need to adjust your chunk size if a table’s column count changes.

// Break data into appropriately-sized chunks
const chunkArray = <T>(array: T[], size: number) => {
  const result: T[][] = [];
  for (let i = 0; i < array.length; i += size) {
    result.push(array.slice(i, i + size));
  }
  return result;
}

Writing relational data with transactions

Ideally we would wrap our writes in a transaction, ensuring they’d succeed or fail together. This is especially important when inserting relational data with inherent interdependencies between tables (and ID values). Unfortunately, there is an open issue with the way Drizzle handles D1 transactions. While they work locally, they fail when writing to a remote D1 over HTTP.

We can achieve the same effect, though, by using Drizzle’s batch method. According to Drizzle’s docs on D1 batches, they “execute and commit sequentially and non-concurrently”, and are fully-fledged SQL transactions.

The batch method effectively accepts an array of operations, but it’s typed as a tuple, so we’ll need to get a little creative when constructing the array. We’ll use a second utility to break our data into chunks, and create insert statements for each.

const chunkInserts = <T extends SQLiteTable>(
    table: T, 
    data: T["$inferInsert"][],
    batchSize: number,
) => {
    const dataChunks = chunkArray(data, batchSize);

  // Initialize the array with the first insert to
  // satisfy the tuple type requirement
  const chunkedInserts: [BatchItem<"sqlite">, ...BatchItem<"sqlite">[]] = [
    db.insert(table).values(dataChunks[0]),
  ];

  // Loop starts at 1 as we've already added 0
  for (let i = 1; i < dataChunks.length; i++) {
      const batchItem = db.insert(table).values(dataChunks[i]);
    chunkedInserts.push(batchItem);
  }

  return chunkedInserts;
}

Seeding with the CLI

Adding batches to the local seed script was minimally invasive, and got the job done. It was good enough for Placegoose, but it left me wondering whether there was a lower-touch solution.

After some digging, I found that Cloudflare’s CLI allows you to push data directly to a remote D1 database, without worrying about batching (or even scripting)!

The first step is to initialize and seed a database locally. Then, export the database to a local SQL file using the wrangler d1 export command:

wrangler d1 export placegoose-d1 --local --output ./seed.sql --no-schema

The --no-schema flag ensures that only seed insert statements will be included in the generated file, since we’ll still use drizzle-kit to push our migrations.

wrangler d1 migrations apply placegoose-d1 --local

The next step is to push the SQL file to our remote D1. To do this, we’ll use the wrangler d1 execute command, pointing to our --output file from the export script:

wrangler d1 execute placegoose-d1 --remote --file ./seed.sql --yes

You don’t need to include the --yes flag. This will automatically approve prompts that come up while the script runs. It may be useful if you choose to incorporate this approach into your build process, but it can have unintended consequences if you’re not sure what prompts will appear.

Debugging schema issues

When I first ran this script, the SQL file was uploaded successfully, but the remote execution failed. I got the following error message referring to a sqlite_sequence table.

🌀 File already uploaded. Processing.

✘ [ERROR] no such table: sqlite_sequence: SQLITE_ERROR

Normally this table is generated for us when we create a table with auto-incrementing columns. I forgot to make the ID columns in the Placegoose schema auto-incrementing though.

const metadata = {
  id: integer({ mode: "number" }).primaryKey({
      autoIncrement: true, // Simple fix
  }),
};

For a number of reasons, the right answer is to update the schema, but to be honest this didn’t occur to me until I had found a different solution:

CREATE TABLE dummy (id INTEGER PRIMARY KEY AUTOINCREMENT);
DROP TABLE dummy;

By adding these lines to the top of the generated SQL file, I got D1 to create a sqlite_sequence table without changing the actual schema. As a mock data API, Placegoose doesn’t actually support inserts, so I could have gotten away with this approach, but as a general rule, ignoring such fundamental problems with your database schema is a recipe for disaster.

Mapping migration tables

A different change to the generated SQL file was necessary though. Drizzle keeps track of migrations in a __drizzle_migrations table, which was added to the remote D1 when we used drizzle-kit to apply migrations.

Wrangler also keeps track of migrations in a d1_migrations table though, and doesn’t have access to Drizzle’s migrations table. Consequently, the generated SQL file includes inserts to a d1_migrationstable that doesn’t exist on the remote. The schemas are the same though, so we just need to update the table name.

// INSERT INTO d1_migrations VALUES(...
INSERT INTO __drizzle_migrations VALUES(1,'0000_little_newton_destine.sql','2025-03-10 11:53:01');

I’m sure there is a more elegant or hands-off way to approach this (let me know if you’ve found it), but my goal in researching this approach was to verify that it was possible, not to fine-tune it.

After updating the database schema and updating the generated SQL file, we can push all the seed data at once. We only have a few hundred records in total, so I’m not sure how this approach scales, but that volume of mock data is sufficient for many projects.

Deploying a Worker

Now that we have some data to display, let’s get our app deployed! As with creating our remote D1, it’s a really simple process. If you’ve been developing locally, you must already have installed Node, and have Wrangler installed in your project, and it was necessary to create a Cloudflare account to create your remote D1.

With the prerequisites out of the way, there’s just one more step: Run the Wrangler deploy command! Note that using the --minify flag can help reduce startup times, and keep the bundle within Cloudflare’s Worker size limits. It can make debugging more difficult though, as minification typically obscures variable and function names.

wrangler deploy --minify src/index.ts

That’s it! Your project is live. It will be exposed at <project-name>.<cloudflare-user>.workers.dev by default, but you can configure a custom domain in your wrangler.toml or Cloudflare dashboard.

If you end up using Placegoose as a starting point for your own mock data API, let me know in the comments! I’d also love to hear if there’s anything you wish I had covered in more detail, or if you’ve discovered a more streamlined approach!

What will you deploy next?

As we’ve seen, deploying a simple backend to Cloudflare is pretty straightforward. We had to work around some infrastructure limits to seed our remote database, but the HONC stack offers a few solutions that meet our needs.

Using Cloudflare’s CLI is a more direct approach and requires less configuration, but you may run into issues seeding larger datasets. Batching chunked writes is a more flexible solution, even though it requires a bit more code up-front.

The optimal solution will depend on your use-case though. No matter which approach (or stack) you choose, you’ll run into some kind of limitations or constraints. To develop effective solutions, you’ll need to experiment with the tools your stack provides, and a clear understanding of your project’s requirements.

The next steps are up to you! You may want to move on to deploying more complex backends, or make use of your mock data API to enhance your development experience. As with every software problem, success ultimately boils down to reading documentation and persistently experimenting with different approaches.

Hacking Hono: The Ins and Outs of Validation Middleware

ambergristle — Mon, 03 Feb 2025 19:10:30 +0000

Hono’s type system is one of its greatest strengths. If you don’t take some time to understand the basics though, it can prove to be a frustrating barrier to entry. As a newer framework, and one dedicated to flexibility, Hono’s official documentation mainly covers core concepts and base-cases. Dozens of official and community middleware and templates will steer you towards scalable and maintainable solutions, but the patterns and details are largely left to you.

After working for years with meta-frameworks that seem to have an opinion about everything, this feels like a breath of fresh air. Hono’s middleware and helpers can be used out-of-box to meet many projects’ basic requirements, but it’s also remarkably simple to extend or replicate them to meet your project’s specific needs.

Learning Hono hands-on

Hono’s approach to request validation is an ideal case study. Its core hono/validator implementation is only ~150 lines, half of which are imports and types. The logic itself is really straightforward, and can be trivially extended or modified locally. In fact, Hono’s validator-specific middleware are all built on validator, and its types.

If you want to get the most out of this article—and Hono—you’ll need to be comfortable with TypeScript and generics. You should be familiar with web API and TypeScript basics, but it’s ok if you’re a beginner, or prefer to use TypeScript sparingly: Hono’s types and utilities will do most of the heavy lifting for us.

To get a clear picture of how Hono middleware works, we’ll implement the same validation middleware using three approaches, each peeling back a layer of abstraction:

First with @hono/zod-validator—the out-of-box solution,
Then with hono/validator—if you want to use your own validator, or bake in error processing,
And finally with Hono’s createMiddleware—not recommended for production, but a great way to take a closer look at how Hono works.

Hono’s validator is especially powerful in combination with its RPC client, so we’ll also take a quick look at how route typing plugs into hono/client. We won’t be covering OpenAPI integration—that deserves its own discussion—but most topics we address will be relevant in any middleware or handler.

Low-lift validation with `@hono/zod-validator`

If you’re already using a type-safe schema library, like Zod or TypeBox, and you just want to plug your schema in and go, Hono’s got you covered. You just install the relevant package-specific validation middleware, and it handles most of the boilerplate for you.

I’m a long-time Zod fan, so we’ll start with Hono’s zod-validator, but none of the examples or discussion will delve too deeply into Zod specifics. Instead, we’ll be focusing on what we can learn about Hono’s middleware typing from the package’s internals.

Sharing valid data with Context

The first piece of Hono typing we really need to understand is the Context object. Whether we’re using one of the dozens of official and community middleware—or creating our own—we’ll be working with Context. It exposes the app environment—including any bindings for Cloudflare environments, the Request and Response, and a variety of helpers for reading and writing data. You can read more about those in the Hono Context API docs.

export type Context<
    // We'll get to these type parameters in a moment
    E extends Env = any, 
    P extends string = any, 
    I extends Input = {}
> = {
    // Cloudflare bindings and env variables
    env: E["Bindings"];
    // Augmented Request with optionally-validated data
    get req(): HonoRequest<P, I["out"]>; 
    get res(): Response;
    // ...
}

Crucially, Context allows us to share data between middleware and handlers type-safely. This can be useful in a number of ways, but we’ll start with the c.req.valid method, which allows us to access any request data validated by validator (or middleware like zod-validator that use it internally).

import { Hono } from 'hono';
import { zValidator } from '@hono/zod-validator';
import { z } from 'zod';

// I like to centralize these in a directory like /dtos
// or /schemas, but it really depends on your use-case
const ZSearchQuery = z.object({
    search: z.string(),
});

const app = new Hono()
    .get(
        '/posts',
        // Must be handler-specific for type-safety
        zValidator('query', ZSearchQuery),
        // After going through middleware, Context
        // is passed into the handler
        async (c) => {
            const { search } = c.req.valid('query');
            // We know `search` is a string in this scope, so we
            // can handle the request type-safely from here on
        }
    )

When we pass zValidator a target ('query') and a schema, the schema’s output becomes type-safely available in the handler (or subsequent middleware). Hono supports six validation targets, representing the most common formats for request data.

json
form (multipart/form-data or application/x-www-form-urlencoded)
query
param
header
cookie

For simplicity, here we only validate the query string, but you can validate as many targets as you’d like by chaining multiple validators.

For validated types to be inferred correctly, validation middleware must be added in the handler, like in the example above. Chaining your validator with app.use will result in the following TS error:
“Argument of type string is not assignable to parameter of type never.”

Customizing the error hook

The zod-validator package makes it really easy to enforce type-safety within handlers, but what happens when requests fail validation? By default, zValidator immediately ends the request, returning a 400 with a body containing the full ZodError object.

While convenient in development, it’s not great for production. This is especially true if you have internals that need obscuring (like auth flows), if you want to standardize error responses, or if your app has complex error-handling requirements (like logging or alerts).

Some OAuth flows use validation logic that takes the unparsed body as input (typically in combination with a signature in the headers). In these cases, I’ve found its simplest to verify the request before moving on to validation.

To override this default behavior, zValidator accepts a third hook argument: a callback that exposes the validation result and our good friend Context. If validation fails, you can send a custom response, or throw to an error handler for additional processing.

While it’s great to have this flexibility, responding to errors consistently makes APIs easier to build, troubleshoot, and work with. By abstracting the hook, we can reuse it whenever we validate, ensuring that invalid requests are handled the same way each time.

This gets tedious quickly though, and can be difficult to maintain. To save ourselves the trouble of injecting our error hook each time we call zValidator, we can instead bake it into a custom middleware.

import type { ValidationTargets } from 'hono';
import { zValidator } from '@hono/zod-validator';
import { z } from 'zod';

// Your custom error formatter
import { formatZodError } from '@/lib/zod-error';

export const customZodValidator = <
    // json, form, query, param, header, cookie
  Target extends keyof ValidationTargets,
  Schema extends z.ZodSchema
>(target: Target, schema: Schema) => {

  return zValidator(target, schema, (result, c) => {
      // Early-return (or throw) on error
    if (!result.success) {
        // Error requirements will vary by use-case
      return c.json({
        timestamp: Date.now(),
          message: `invalid ${target}`,
          issues: formatZodError(result.error.issues),
        }, 400);
      }

        // Otherwise return the validated data
    return result.data;
  });
};

As you can see, the implementation is simple enough: zValidator does the heavy lifting both at compile- and at run-time. We only need a few generics to make zValidator aware of the argument types passed to our wrapper—essentially we’re prop-drilling the type—and it will take care of communicating with Hono’s type system.

If you’re not familiar with generics, I strongly recommend reading through the TypeScript Generics docs, or seeking out resources that better fit your learning style. TLDR? They make types dynamic, helping us represent functions like zValidator that return different results depending on argument subtypes.

To allow for one-off routes with distinct error-handling requirements, we could also add an optional override hook. The typing for that is a little more complicated though, so we won’t get into that just yet.

More flexibility with `hono/validator`

First, let’s get a better understanding of how schema output types get from zValidator to our handlers. Behind the curtain, it’s just a Zod-specific wrapper around validator, and Hono offers equivalents for Typebox, Typia, and Valibot.

If you don’t see your favorite validator (or parser) on the list, or want to get creative with your error processing, fret not. It’s fairly trivial to reproduce the essentials yourself. Hono tools are built to be extended, and the source code is refreshingly accessible.

// import { zValidator } from '@hono/zod-validator';
import { validator } from 'hono/validator';

export const customZodValidator = <
  Target extends keyof ValidationTargets,
  Schema extends z.ZodSchema
>(target: Target, schema: Schema) => {

    // return zValidator(target, schema, (result, c) => {
  return validator(target, async (value, c): Promise<z.output<Schema>> => {
      // We have to run validation ourselves
    const result = await schema.safeParseAsync(value);

    if (!result.success) {
      return c.json({
        timestamp: Date.now(),
          message: `invalid ${target}`,
          issues: formatZodError(result.error.issues),
        }, 400);
    }

    return result.data;
  });
};

Changing only three lines, we can update our example to remove the @hono/zod-validator dependency, and decouple our logic from Zod. At this level of abstraction, you’re free to validate request data any way you’d like. You can then retrieve valid data in the handler, using c.req.valid.

How does this actually work though?

When we use validator, the callback’s (non-Response) return type gets added to a type map, using the path, method, and target as keys. To achieve this, validator leverages Hono’s MiddlewareHandler type. Like Context, MiddlewareHandler takes three generic arguments, for Env, path, and Input:

type MiddlewareHandler<
    E extends Env = any, 
    P extends string = string, 
    I extends Input = {}
> = (c: Context<E, P, I>, next: Next) => Promise<Response | void>;

type Context<
    E extends Env = any,
    P extends string = any, // path
    I extends Input = {}
> = {
    /** */
}

type Env = {
    Bindings?: Bindings; // object
    Variables?: Variables; // object
};

type Input = {
    in?: {};
    out?: {};
    outputFormat?: ResponseFormat; // 'json' | 'text' | 'redirect' | string
};

Env and Input are the type parameters you’ll manually work with the most. Env exposes any environment variables (Bindings), along with any values you’ve set in Context in your middleware (Variables), while Input represents any request data validated using hono/validator.

This would be the Input type for our simple search query, for example:

{
    // Used by Hono internals, always same union
    // If you know what they do, let me know in the comments!
    in: {
        query: {
            search: ParsedFormValue | ParsedFormValue[];
        }
        // json: {};
        // form: {};
        // param: {};
        // header: {};
        // cookie: {};
    };
    // Types you'll work with
    out: {
        query: {
            search: string;
        }
    };
}

Downstream handlers use the out type to determine which targets have been validated, and to appropriately type values returned from c.req.valid. This is essentially Hono’s secret sauce: it uses generics to merge types into a format useable across the request lifecycle.

Using a different validator

All we really need then, is a target and an output type. We can easily update our custom Zod validator to accept a generic parse function (or one from a different library), as long as we make sure validator generically knows the return type.

// Any validation function you provide must
// take unknown data and return data of a known type,
// or produce some kind of error
type ValidationFunction<T, E extends Error = Error> = (data: unknown) => (
    { success: true; data: T; }
    | { success: false; error: E }
);

export const customAgnosticValidator = <
    Target extends keyof ValidationTargets,
    T extends Record<string, any>
>(target: Target, validate: ValidationFunction<T>) => {

  return validator(target, (value, c) => {
    const result = validate(value);

    if (!result.success) {
      return c.json({
        timestamp: Date.now(),
        message: `invalid ${target}`,
        issues: formatError(result.error.issues),
      }, 400);
    }

    return result.data;
  });
};

This approach is ideal if you want to minimize your dependencies, or if you want to use an unsupported validator. Otherwise, the sturdiest (and most cost-effective) solution is to build on top of an existing package-specific Hono validator.

Getting extra with `createMiddleware`

To get an even closer look, let’s take things a step too far, and implement our own version of validator. While you wouldn’t want to do this for your validation layer, it will give us a chance to manually get and set values in Context, which is really a game-changer for things like auth.

To keep typing simple, we’ll take advantage of Hono’s createMiddleware helper. This factory method ensures that your middleware typing can be read by subsequent handlers.

Under the hood, createMiddleware is essentially a type utility. It doesn’t do any logic, but it does hook your middleware into Hono’s type system, which plays a key role in communicating types between middleware, handlers, and the Hono client. It does not allow you to automatically share types between middleware.

Instead of using the Input type though, we’ll use the Env type. There’s no way to set the data that’s available on c.req.valid without using validator (or forking Hono), but Context comes with a getter and setter that we can use to type-safely share our own custom data.

import { createMiddleware } from 'hono/factory';

const overEngineeredAgnosticValidator = <
  Target extends keyof ValidationTargets,
  T extends Record<string, unknown>
>(target: Target, validate: ValidationFunction<T>) => {

  return createMiddleware<{
     Variables: {
      validated: Record<Target, T>
    }
  }>(async (c, next) => {
      // Get and format target data from Request
      // https://github.com/honojs/hono/blob/b2affb84f18746b487a2e02f0b1cd18e2bd8e5f5/src/validator/validator.ts#L72
    const value = await getTargetData(c, target);

    const result = validate(value);

    if (!result.success) {
      return c.json({
        timestamp: Date.now(),
        message: 'Invalid Payload',
        issues: formatError(result.error),
      }, 400);
    }

    const validated = {
        // Get previously-validated data
        // `c.get('validated')` would also work
      ...c.var.validated,
      [target]: result.data,
    };

        // Update the validated data in context
    c.set('validated', validated);

        // Don't forget to await. It's not necessary
        // until it is, and then it's a pain to retrofit
    await next();
  });
};

Since we’re not using validator, we won’t be able to access our data in the handler using c.req.valid. Instead, we’ll use the createMiddleware type generic to specify that we’ll be setting a validated property in Context variables, whose value is our parse result. We could then access our results in the handler like this:

const app = new Hono()
    .get(
        '/posts',
        customValidator('query', ZSearchQuery.parse),
        // Context allows us to grab validated request data
        async (c: Context) => {
            // `c.get('validated').query` would also work
            const { search } = c.var.validated.query;
            // We know `search` is a string in this scope
        }
    );

Querying validated endpoints with Hono RPC

If your app has a front-end, Hono’s RPC client is a popular choice for keeping your types synced across your stack. It brings intellisense and type-safety to your request construction, representing resources as objects nested by path and method.

import { hc } from 'hono/client';

// type AppType = typeof app;
import type { AppType } from '@/server';

// Client uses type map to infer available endpoints
const client = hc<AppType>('BASE_URL');

export const getPosts = async (search: string) => {
    // We can dot-index into the endpoint and method we want
    // and any `json` or `text` return types are inferred 
    return await client.posts.$get({
        // The client will let us know what data is required
        query: { search },
    });
}

There are a few gotchas to usage though, notably that the RPC client only works with json and text responses. If your endpoint doesn’t return either, you can still use the client, but without the benefit of any additional type-safety. Moreover, if an endpoint returns both json and an incompatible method (e.g, c.req.body), none of the responses will be inferred.

Note that unlike a tool like trpc, Hono’s RPC client isn’t linked to code instances, so shortcuts like cmd+click in your code editor won’t take you to the handler.

I haven’t worked with it extensively, so we’ll need to save a more in-depth discussion for another time, but it’s worth getting a sense of how the types inferred from our backend code get used by the client (and how they don’t).

Inferred request and response types

As the client’s behavior suggests, all the (chained) middleware and handler types for an app or route are merged into a type map that’s keyed by endpoint and method, and includes the inferred input and union of output types.

{
    "/posts": {
        $get: {
            // Success response
            // Request data validated with `hono/validator`
            input: {
                query: {
                    search: string;
                };
            };
            // Data returned from handler
            output: { data: Data[]; };
            outputFormat: "json";
            status: 200;
        } | {
            // Error response
            input: {
                query: {
                    search: string;
                };
            };
            output: { message: string; };
            outputFormat: "json";
            status: 400;
        }
    };
}

In this case, we see that our posts endpoint requires a search query value, and returns either a 200 with some data, or a 400 with an error message. Remember that only text or json responses returned from the handler will be included. Responses returned from middleware or helpers like notFound or onError are not included either. This behavior is not supported by Hono’s current type system, but it’s a known issue that may be addressed in the future.

To get around this, you can explicitly set handler types yourself, though that’s not especially ergonomic, and is somewhat counterintuitive. The best solution will depend on your use-case, but using a standardized error response format combined with some custom type checking should easily bridge the gap for now.

Regardless, it will often also be necessary to additionally parse data client-side: complex objects like Date are serialized for HTTP requests, and clients generally don’t deserialize them for you. While this might seem cumbersome, it’s fairly trivial to add a validation layer around Hono’s client (or any TypeScript HTTP client) that transforms values as-needed. That, though, is a tomorrow problem.

It’s middleware all the way down

For now, I hope that I’ve left you feeling excited to take your middleware to the next level, and confident to start exploring the Hono source code if you haven’t already! It’s an amazing feat of engineering, and a great resource throughout the development process.

Hono’s flexibility—which extends from its cross-runtime compatibility to its helper methods—opens the door to a highly composable and type-safe architecture. It’s simple to build on, introducing additional complexity and abstraction only as needed.

This approach radically simplifies workflows—like auth and rate limiting—that often require data to be shared between multiple middleware layers before the request even hits the handler.

I’m currently having a lot of fun building auth into a Hono app using the new Lucia Auth guide, which is an awesome resource if you want to roll your own auth, or just learn more. I’m still ironing out some kinks, but I look forward to publishing an article on Hono auth in the coming months!

Until then, if you need help with Hono or are seeking inspiration for your next project, check out the Hono Discord. I’ve found it to be an incredibly welcoming and supportive community, following the example set by the project authors, maintainers, and contributors.

Building data APIs with HONC

ambergristle — Mon, 09 Dec 2024 17:03:59 +0000

I was really excited when I came across Hono. I think the API is elegant in its simplicity, and I’ve found it—in my admittedly limited experience—to be a sturdy foundation for moderately complicated backends.

In short, Hono is fast, flexible, and honestly fun to work with. Templates will get you started in a dozen different runtimes and frameworks, and there are a multitude of plugins and middleware to facilitate integration with third-party tools.

How do all of these pieces fit together though? While project constraints and implementation details will vary, most data APIs need to satisfy three key requirements:

A way to persist queryable data, typically a database,
To define and regulate how data moves between application layers,
And to safeguard against malicious activity and user error.

When you’re just getting started with a framework, ostensibly simple steps like configuring the database or spinning up a validation layer can become grueling hurdles to adoption. Enter HONC, a stack made for lightweight data APIs on the edge.

HONC stands for Hono, Drizzle ORM, Neon DB, and Cloud(flare). It’s a collection of technologies dedicated to performance and type-safety, developed by Fiberplane as a template for non-trivial Hono APIs.

0 to 60 with the HONC app

HONC is more of a design philosophy than a rigid doctrine. You can use the create-honc-app CLI to download a project with either a Neon, D1, or Supabase DB. Drizzle plays a pivotal role by managing seeding and migrations, and decoupling the stack from the database. As the source of truth for (DB) type definitions, it’s can also be the foundation of your type system and runtime validation.

This gets us from 0 to 60, but what about the 80/20, or at least 70/30? Implementation details like validation layers and rate limiting are too contingent on business requirements to usefully include in a template, but when you pick up a library for the first time, having a robust examples is a game-changer.

Mocking a (moderately) advanced data API

To simulate what happens when a design philosophy collides with project constraints, Fiberplane asked me to build a simple mock-data API called Placegoose (think JSONPlaceholder) using the HONC stack.

Fiberplane is an API testing and debugging tool—like the Inspector panel in your browser—that we’ll be using to inspect requests, logs, and database calls.

A mock-data API’s functional requirements are robust enough to involve all key aspects of API development, but not so complicated as to be distracting. At a bare minimum, they serve relational data via multiple application layers, but they can be usefully enhanced with features like validation and rate limiting.

To give ourselves some concrete parameters, we settled on a handful of features that most production-ready data APIs must implement:

A database with an ORM or custom adapter layer
Validation and business logic
Error handling and rate limiting
and a lightweight markdown-based frontend for docs

This is the first article in a series that will cover 1) building the app, 2) deploying to production, and 3) rendering a front end. We hope the series has something to offer more- and less-experienced devs alike, but we’ll be focused on patterns, helpers, and gotchas, so we won’t be explaining basic data API or TypeScript patterns.

Getting up and running with HONC

To get started, we’ll download the HONC D1 template and install dependencies. The project doesn’t need any additional configuration to run locally.

npm create honc-app@latest
npm i

In order to connect to a remote DB, you’ll need to update the D1 section in your wrangler.toml (the Cloudflare Worker config file). We’ll cover this in detail in the next article. For now, take a moment to get acquainted with the config, and update the database name and ID to match your project.

[[d1_databases]]
binding = "DB"
database_name = "placegoose-d1"
# Can be anything for local development
# Must be updated when connecting to a remote DB
database_id = "local-placegoose-d1"
migrations_dir = "drizzle/migrations"

The binding value is the key used to access the database from within the app. If you choose to rename it, be sure to keep the Bindings property of AppType in sync for proper intellisense and type propagation.

type AppType = {
    Bindings: {
        // Global type from @cloudflare/workers-types
        DB: D1Database;
    }
};

// Any instances connecting to the DB must be typed
const app = new Hono<AppType>();

If you’re new to (or ambivalent about) TypeScript, don’t worry: Despite this being a fully-integrated TypeScript project, AppType is one of the only types you’ll need to define and manage yourself! In fact, this is it for project setup, so why don’t we take a look at the HONC stack’s lynchpin: Drizzle ORM.

Type-safe database management with Drizzle ORM

As I alluded to earlier, Drizzle does a lot of heavy lifting for us. In any project with a database, we need to manage table schemas and migrations, bridge the gap between JavaScript and SQL syntax, and validate data going into the DB.

That’s a non-trivial task, especially for a small team or solo dev, and demands a lot of discipline to build and maintain. Drizzle offers all of this in a type-safe package that lets us derive types and validation models directly from table definitions.

This schema-first approach is meant to ensure that updates are reflected across the stack, meaning fewer files to update and fewer migration bugs.

Defining a single source of truth

The HONC template comes with a single table definition (db/schema.ts) that demonstrates how to require a column, default a value, and run raw SQL.

By default, Drizzle names columns after the keys in your table definitions. For seamless translation between camel and snake case, take advantage of Drizzle’s automatic case conversion.

We’ll update this file to describe the tables and types we need, in this case Gaggles, Geese (possibly belonging to a gaggle), and Honks (definitely belonging to a goose). This gives us a chance to check out foreign keys (references), and share common column definitions (like primary keys or metadata) between tables.


import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";

const metadata = {
  id: integer({ mode: "number" }).primaryKey(),
};

export const gaggles = sqliteTable("gaggles", {
  ...metadata,
});

export const geese = sqliteTable("geese", {
  ...metadata,
    // Creating a Foreign Key
    gaggleId: integer({ mode: "number" }).references(() => gaggles.id),
});

Tables also directly expose Insert and Select types inferred from the rules you’ve set for columns and keys. Note that the SQL methods and features available (like enums) are syntax-specific.

const metadata = {
    id: integer({ mode: "number" }).primaryKey(),
}

export type GooseSelect = typeof geese.$inferSelect;
export const geese = sqliteTable("geese", {
    ...metadata,
    gaggleId: integer({ mode: "number" }).references(() => gaggles.id),
    name: text().notNull(),
    isMigratory: integer({ mode: "boolean" }).notNull().default(true),
    mood: text({
        enum: ["hangry", "waddling", "stoic", "haughty", "alarmed"],
    }),
});

// type GooseSelect = {
//     id: number;
//     gaggleId: number | null;
//     name: string;
//     isMigratory: boolean;
//     mood: "hangry" | "waddling" | "stoic" | "haughty" | "alarmed" | null;
// }

If deployed effectively, these types will safeguard our data layer from code that tries to insert a malformed row. This doesn’t protect our API from bad data though, and it relies on comprehensive and disciplined typing throughout the app.

To keep compile- and run-time types in sync, we’ll create a validation layer using the drizzle-zod plugin. We’ll explore this in greater detail in the validation section, but first we need to seed our database!

Seeding the database at scale

After I started working on the app, the HONC template was updated to use Drizzle’s new pRNG drizzle-seed library. Drizzle Seed uses your table models to programmatically generate seed data and populate the database.

To create the seed data, available in the repo, I fed the table models to a generative AI tool, making sure to test output at a small scale before dumping results into a json file. This was reasonably effective given that I only needed 500 rows, but obviously fragile, and somewhat tedious.

Placegoose does not currently use drizzle-seed, but this is how I would refine data generation for the Gaggles table. While not exhaustive, the helper functions that Drizzle provides are robust enough to support data like blog posts, contact information, or job listings.

import * as schema from "/src/db/schema.ts";

const db = drizzle(client);

await seed(db, { 
    gaggles: schema.gaggles,
    // ... 
}).refine((f) => ({
    gaggles: {
        count: 10,
        columns: {
        name: f.fullName(),
      territory: f.weightedRandom([
            { weight: 0.5, value: f.city() },
        { weight: 0.5, value: f.default({ defaultValue: null }) },
      ])
    },
  },
  // ...
}));

With our table models and seeding refinements (or seed data) defined, we just need to 1) create a local database, 2) generate and apply the initial migration, and 3) run the seed script. The HONC template includes a package script that chains these operations together, making it as easy as:

npm run db:setup

Managing request data

Now that we have some data in the DB, we can start writing and testing endpoints! Hono’s approach to modular routes will be familiar to anyone that’s worked with Express: Just create a new Hono instance, chain whatever middleware and handling logic you need, and pass the instance as the second argument of Hono.route.

import { Hono, type Context } from "hono";
import { cors } from "hono/cors";
import { instrument } from "@fiberplane/hono-otel";

const app = new Hono();
// Ensure the API is publicly accessible.
// For more, see MDN's docs on CORS.
app.use("*", cors());

const gagglesRoute = new Hono();
// This handler will not be inferred in the gagglesRoute type
gagglesRoute.get("/:id", (c: Context) => {
  return c.text("Not yet implemented", 418);
});

app.route("/gaggles", routes.gaggles);

// Have Fiberplane client inspect traces
export default instrument(app);

Hono recommends chaining methods directly to the constructor call for optimal type inference and RPC behavior. I chose to separate method calls because this project doesn’t benefit from the additional type safety, and I find them easier to read.

Writing all our handlers in the index file would quickly get out of hand though, so we should add a routes directory with a file for each resource, limiting the cognitive load in a given file.

The next steps are to develop the handler logic and validation, filling in routes one endpoint at a time. This is where we’ll start to run into errors, so remember to add a simple catch-all error handler. We’ll cover error processing in more detail later, but we don’t want our app to crash while we work!

app.onError((error, c) => {
    console.error(error);
    return c.text("Something went wrong!", 500);
});

Visualizing the data pipeline with Fibeplane Studio

If you’re following along locally, take a moment to launch your app and the Fiberplane Studio by running npm run dev and npm run fiberplane in separate terminals!

To debug requests that go wrong, and to optimize services that are working as expected, we can use the Fiberplane Studio. By wrapping our app with the instrument method, we give the Fiberplane client access to request traces, which are then displayed in the Studio.

Built specifically for Hono apps, Fiberplane automatically detects new routes and configures request templates with path parameters. As you test (and re-test) services, console logs of all levels will appear in the Logs panel (hotkey G + L), and we can inspect the request Timeline (G + T) to view all traces, including D1 database calls.

Like most mainstream HTTP clients you can “replay” requests, making it a piece of cake to rapidly test defined happy and sad paths after refactoring an endpoint. By integrating logs and more robust traces though, I found that Fiberplane cut down on some of the back-and-forth between my HTTP client and my terminal.

Having this comprehensive insight into the request lifecycle built into my HTTP client was helpful throughout development, but especially when building in more complex features like validation, and when trying to optimize handler performance.

Querying the bound databases

With telemetry set up, we’re ready to start querying and serving data! First, we need to connect to the database by calling the drizzle initializer, which expects a D1 client bound to the app. This is where the Bindings property on AppType comes in. Hono exposes bindings and other environment values through the Context object, whose typing is inherited from its immediate parent.

In the source code I abstract the call in order to reduce repetition, but the following examples will show it inline for clarity. Though tempting, I chose not to use a singleton because there didn’t seem to be much benefit for such a simple service and short-lived service.

The initializer also accepts an optional config argument. Since we’re making use of Drizzle’s auto-casing, we need to specify that the client should expect snake case from the DB.

import { drizzle } from "drizzle-orm/d1";
import { Hono } from "hono";

type AppType = {
    Bindings: {
        // Global type we get from @cloudflare/workers-types
        DB: D1Database;
    }
};

const gagglesApp = new Hono<AppType>();

// Get all Gaggles
gagglesApp.get("/", async (c) => {
    // We get our DB binding from Context
    const db = drizzle(c.env.DB, {
        // This must be set for Drizzle to automatically
        // translate between snake and camel case
        casing: "snake_case"
    });

    // Drizzle inference tells us is type Gaggle[]
    const gaggles = await db
        .select()
        .from(schema.gaggles);

    return c.json(gaggles);
});

export default gagglesApp;

Drizzle ORM aims to be a lightweight abstraction over SQL, so query construction is fairly intuitive. Statements are represented as chains of keywords, and Drizzle exports operators as flavor-specific helper methods.

Enforcing Drizzle types at run-time

To keep compile- and run-time types in sync, we’ll create a validation layer using the drizzle-zod plugin. It gives us constructors that build Zod schemas from Drizzle table models. As with the types exposed on table models, there is an Insert and a Select option.

import { createInsertSchema } from "drizzle-zod";
import * as schema from "./schema";

// src/db/validation.ts
export const ZGaggleInsert = createInsertSchema(schema.gaggles, {
  name: (schema) => schema.name.min(1),
  territory: (schema) => schema.territory.min(1),
});

Initially I was worried this might be limiting, but Drizzle makes it easy to extend or override field definitions. Zod accepts empty string values by default, so I made use of this feature to require that name fields were at least populated.

Zod is an awesome schema library you can use to keep your types and validation in sync. I won’t be discussing how to use the library here, but I encourage you to check out the docs if you haven’t already!

I chose to export all the Zod schemas from a single file in the db directory, mostly to keep them out of the schema file exports, but also because I’ve found that keeping validators centralized and close to where they’re used—in this case the data layer—helps maintain a clear distinction between different validation layers.

Validating request data

Since the app is meant to serve mock data, a more defined database validation layer wasn’t necessary, but we do want to validate incoming payloads.

The Insert schemas we generated from our tables are fine for the DB, but we don’t want to allow users to specify ID values themselves, as this can quickly get messy. We also want to prevent users from updating which goose honked a honk, because what kind of world would that be! To deal with this, we can create an additional validation layer for request payloads in a new dtos directory. DTOs (Data Transfer Objects) are just logic that regulates how data moves across layers.

export const ZGaggleInsertPayload = ZGaggleInsert.omit({
  id: true,
});

export const ZHonkInsertPayload = ZHonkInsert.omit({
  id: true,
});

export const ZHonkUpdatePayload = ZHonkInsertPayload.omit({
  gooseId: true,
});

Hono’s validator middleware makes it easy to use these schemas (or any logic) to validate request data. Targets include—but aren’t limited to—route parameters, query values, and json (body). The middleware takes the target (e.g., “param”) and a validation callback, and exposes valid results type-safely via the app Context.

// Update Gaggle specified by id
gagglesApp.put(
    "/:id",
  validator("param", (params, c) => {
        const idParam = params.id;

        if (!/^[1-9]\\d*$/.test(value)) {
            throw new HTTPException(400, {
                  message: "ID values must be positive integers",
              });
        }

        return {
            id: Number.parseInt(value);
          };
  }),
  validator("json", (body, c) => {
      // ...
  }),
  async (c) => {
      // 'id' is known to be type "number"
    const { id } = c.req.valid("param");
    // ...
    return c.json(updatedGaggle);
  },
);

Hono provides a Zod-specific validator helper (@hono/zod-validator), which takes care of the validation and error handling boilerplate. I found the library to be a useful reference, but by default it early-returns the response on error—including full Zod error details in the body.

You can override this behavior with a callback, but I opted to build my own solution in order to directly incorporate standardized error processing, and maintain a centralized error handling flow.

/**
 * @returns Validation fn for Hono body validator, responsible
 * for processing payload errors
 */
export function makeBodyValidator<T extends Zod.AnyZodObject>(schema: T) {
    // _output is a utility key on Zod schema types
    // that gives us the type of valid output
  return (body: unknown): T["_output"] => {
    const result = schema.safeParse(body);

    if (result.success) {
      // Return value must be consistent with shape of "body"
      // Available through Context.req.valid
      return result.data;
    }

    throw new HTTPException(400, {
      message: "Invalid Payload",
      cause: result.error,
    });
  };
}

I also wrote a simple function to format Zod error data so that it would be more useful for consumers. In retrospect, I should have called this in the body validator factory, and included the results in a custom error response. I didn’t realize you could inject responses like this at the time though, and I chose not to extend Hono’s HTTPException in the interest of simplicity. Instead, I threw to the global error handler we’ll set up next.

Handling the sad path

Securing vulnerabilities and handling errors are critical components of API development, and we’ve already taken a few important steps: Drizzle lets us keep our type system slim, maintainable, and in sync with runtime validation, preventing typing bugs at compile-time. We then use Hono’s validator middleware to enforce these data contracts at run-time, ensuring our handlers are working with valid data.

Responding to errors gracefully

When something goes wrong though, we need to communicate that to users and system maintainers in a way that’s helpful to each. While a detailed error log is useful to devs, it can be overwhelming to consumers, and can leak sensitive information about users or the system.

We can create a catch-all error handler using the Hono.onError method after all our route definitions. It gives us access to the error data and request context.

app.onError((error, c) => {
  console.error(error);

  // Handle formatted errors thrown by app or hono
  if (error instanceof HTTPException) {
    return c.json(
      {
        message: error.message,
      },
      error.status,
    );
  }

  return c.json(
    {
      message: "Something went wrong",
    },
    500,
  );
});

I typically prefer to centralize error processing because it makes it easy to create a consistent experience. You can create error boundaries wherever you’d like though, both with onError, and the specialized Hono.notFound handler. I’ve found this especially powerful when creating webhooks for multiple third-party services, which might have different error-handling requirements.

Using rate limiting to protect APIs from abuse

Securing our app isn’t just about data integrity though, it’s also about access. Now that our app is ready for consumers, we need to make sure that they all have fair access to the service. Rate limiters track how often users make a request—typically with a low-latency database like Redis—and reject requests if they occur too frequently within a set period.

Controlling how often services are accessed allows us to prevent users from hogging resources (maliciously or not), possibly slowing down and even crashing systems. If your service will be paywalled, some form of rate limiting is also the only way to enforce tiered access.

Since we’re using Cloudflare, we can take advantage of their new Rate Limiting bindings, now in open beta. This product handles both the rate limiting logic and data storage, based the configuration in your wrangler.toml. The calls we anticipate in this app are pretty cheap on the whole, so we can afford to be liberal with the rate limit and period.

# The rate limiting API is in open beta.
[[unsafe.bindings]]
name = "MY_RATE_LIMITER"
type = "ratelimit"
# An identifier you define, that is unique to your Cloudflare account.
# Must be an integer.
namespace_id = "1001"

# Limit: the number of tokens allowed within a given period in a single
# Cloudflare location
# Period: the duration of the period, in seconds. Must be either 10 or 60
simple = { limit = 100, period = 60 }

After configuring it, we would call the binding’s limit method from a custom middleware to determine whether to proceed with a request. Under the hood, the rate limiter will query an in-memory DB with the provided key, and use the results to determine whether the client (represented by the key) is eligible to make additional requests in the current period.

It is recommended that you use a unique key for each user, like an ID, in order to ensure that each user gets the expected number of requests per period.

const { success } = await env.MY_RATE_LIMITER.limit({ key: "USER_ID" })

In order to conform to the HTTP spec, rejected responses must include data (like the retry-after) header. Rather than implement the spec ourselves, we can lean on the rich ecosystem of third-party solutions that is beginning to emerge around Hono.

We’ll be using hono-rate-limiter, which is also compatible with other storage solutions (like Cloudflare KV and Redis). It manages all the rate limiting logic and storage for us, and formats responses to rejected requests appropriately. After installing, we only need to configure access to the binding and a key generation method.

// The Cloudflare rate limiter is distributed as a separate package
import { cloudflareRateLimiter } from "@hono-rate-limiter/cloudflare";

app.use("*", cors());

app.use(
  cloudflareRateLimiter<AppType>({
    rateLimitBinding: (c) => c.env.RATE_LIMITER,
    keyGenerator: (c) => {
      if (c.env.ENVIRONMENT === "production") {
          // IPv4 or IPv6
        return getConnInfo(c).remote.address ?? "";
      }

      return "localhost";
    },
  }),
);

Given the project’s limited scope—and the absence of defined users—we can use the request IP as the store key. Hono’s getConnInfo helper provides easy access to protocol and address info. Since users could legitimately share an IP though, having a unique token for each user (like a user ID) would be critical for a paywalled or heavily-trafficked API.

Building on the HONC stack

As a mock data API, Placegoose didn’t have a clear need for auth, or any kind of user or token management. Nonetheless, these are indispensable components of a secure data API. Hono offers some simple auth middleware, but if you need a more robust solution, or if you’re interested in rolling your own, I highly recommend Lucia Auth, an open source learning resource for session-based auth. They provide great guidelines, and examples for most common frameworks.

There was a lot I couldn’t cover in this article, but I hope that I’ve highlighted how the HONC stack can be used to address key requirements for lightweight data APIs, namely persistence, data integrity, and system security. Its minimal footprint helps it leverage performance on the edge, while its schema-first approach to typing streamlines system stability and maintainability.

Above all, the HONC stack is a strong but flexible framework, into which we can easily integrate important features like validation and rate limiting without losing type safety.

In the next article, I cover deploying Placegoose to production, including how to seed a remote D1. To conclude the series, we’ll discuss using markdown to render API docs with a custom layout.