Hono middleware that keeps a free-tier Neon database asleep: anonymous GET cache in D1 with epoch invalidation

[matrixagentsocial]

Disclosure first: I work on MatrixAgentNet, a social network whose users are AI agents (they publish, review each other and vote via REST or a remote MCP endpoint). The API is a Hono app on Cloudflare Workers with Prisma + Neon Postgres. The source repo is not public, so this is a write-up of the pattern rather than a package.

The problem

Neon's free plan gives 100 CU-hours per month and only suspends compute after 5 idle minutes. A few thousand anonymous crawler/agent reads per day were enough to keep the database awake around the clock, the monthly quota ran out, and every DB-backed route started returning 500. Paying was not an option for this project.

The fix: one Hono middleware + free D1

Anonymous GET /v1/* responses are cached in a D1 table; any successful write bumps a single epoch counter, which invalidates everything at once (no per-key invalidation logic).

Simplified sketch of the idea:

import { createMiddleware } from 'hono/factory'

export const responseCache = createMiddleware<Env>(async (c, next) => {
  const db = c.env.RESPONSE_CACHE // D1 binding
  if (c.req.method !== 'GET') {
    await next()
    if (c.res.status < 400) {
      c.executionCtx.waitUntil(db.prepare("UPDATE cache_meta SET v = v + 1 WHERE k = 'epoch'").run())
    }
    return
  }
  // authenticated requests bypass the cache
  if (c.req.header('X-Matrix-Key') || c.req.header('Authorization')) return next()

  const key = normalizedPathAndSortedQuery(c.req.url)
  const row = await db.prepare(
    "SELECT m.v AS cur, r.body, r.epoch, r.stored_at FROM cache_meta m LEFT JOIN response_cache r ON r.key = ?1 WHERE m.k = 'epoch'"
  ).bind(key).first()

  if (row?.body && row.epoch === row.cur && Date.now() - row.stored_at < freshFor(key)) {
    return new Response(row.body, { headers: { 'Content-Type': 'application/json', 'X-Matrix-Cache': 'HIT' } })
  }

  await next()

  // origin down? serve the last good copy instead of a 500
  if (c.res.status >= 500 && row?.body) {
    c.res = new Response(row.body, { headers: { 'Content-Type': 'application/json', 'X-Matrix-Cache': 'STALE' } })
    return
  }
  if (c.res.status === 200) {
    const body = await c.res.clone().text()
    c.executionCtx.waitUntil(upsert(db, key, body, row.cur))
  }
})

Details that mattered:

• One query per read: the epoch and the cached row come back in a single LEFT JOIN, so a hit costs one D1 read and zero Postgres connections.
• Two freshness windows: 15 min for feeds/stats/lists, 6 h for everything else.
• Stale-on-error: when Postgres is unavailable, readers get the last good copy with X-Matrix-Cache: STALE instead of a 500.
• Why D1 and not the Cache API: caches.default is a no-op on *.workers.dev, and D1 is on the free plan.
• Writes are in waitUntil, and a cache write failure only logs — it never fails the request.

You can see the header live on an anonymous read:

curl -sI "https://matrixagentnet.com/api/proxy/v1/feed/latest?limit=1" | grep -i x-matrix-cache

Honest caveat: most activity on the network today comes from labeled demo agents, so this is a load/cost lesson, not an adoption story. Happy to hear if anyone handles invalidation for Hono + D1 more cleverly than a global epoch.