Merge pull request #2

Badge caching, HTTP semantics, and dev server fixes

Author: amery

AGENTS.md

@@ -70,37 +70,70 @@ go: github.com/kagal-dev/example
 Self-hosted SVG version badges rendered by `badge-maker` with
 pre-computed logo data URIs (extracted from `simple-icons` at
 development time, inlined as base64 constants to avoid bundling the
-full icon library into the Nitro server). The shared rendering logic
-lives in `server/utils/badge.ts` (Nitro auto-imports it).
+full icon library into the Nitro server). The `BadgeHandler` class
+in `server/utils/badge.ts` handles method dispatch, input
+validation, cache headers, SVG rendering, and cache management —
+each endpoint provides only its identity and fetch callback.
 
 ### Endpoints
 
-- `/api/badge/go/{module}` — fetches version from
+- `GET /api/badge/go/{module}` — fetches version from
   `proxy.golang.org/{module}/@latest`. Validates the path
   matches a Go module pattern (domain with dot in first segment).
-- `/api/badge/npm/{package}` — fetches version from
+- `GET /api/badge/npm/{package}` — fetches version from
   `registry.npmjs.org/{package}/latest`. Validates the name
   matches npm naming rules (`@scope/name` or `name`).
-
-Both endpoints return `image/svg+xml` with cache headers (1 hour
-for successful responses, 60 seconds for errors). Unknown packages
-render a grey "unknown" badge instead of erroring.
+- `DELETE` on either endpoint busts the version cache
+  and purges the CF edge cache (current PoP), so a freshly
+  published version is picked up on the next GET.
+- Other methods return `405` with an `Allow` header.
+
+Successful responses carry split `Cache-Control` (`max-age=3600`
+for browsers, `s-maxage=300` for the CF edge), a weak `ETag`
+from the version string (conditional requests return `304`),
+and `Last-Modified` from the upstream timestamp. Unknown packages render a
+grey "unknown" badge with a 60-second TTL.
+
+### Caching
+
+Version lookups are cached in Cloudflare KV via Nitro's
+`useStorage('versions')` (`server/utils/version-cache.ts`).
+Each entry has a per-key TTL: 1 hour for successful lookups,
+60 seconds for errors — failed entries auto-expire, preventing
+unbounded growth from bogus package names. The KV namespace
+binding (`VERSIONS_KV`) is configured in `wrangler.toml` and
+mounted in `nuxt.config.ts`; local dev uses a memory driver.
+
+Concurrent requests for the same key at the TTL boundary are
+coalesced via an in-flight promise map — only one upstream
+fetch runs, and only the originating caller writes to KV.
+
+KV operations degrade gracefully: read failures fall through
+to an upstream fetch, write failures are logged but the badge
+is still returned.
+
+Logging uses `consola` with tagged instances (`badge:go`,
+`badge:npm`, `version-cache`).
 
 ### Components
 
 - `BadgeVersion` — generic badge `<img>` wrapper with loading
   skeleton, error fallback (shows alt text), and SSR hydration
   handling (`onMounted` checks `complete` + `naturalWidth`).
+- `BadgeVersionGo` — MDC wrapper (`:badge-version-go{mod="..."}`).
+  Optional `dir` prop for subpackages sharing a parent `go.mod` —
+  badge fetches the parent module version, link points to the
+  subpackage on pkg.go.dev.
+- `BadgeVersionNpm` — MDC wrapper (`:badge-version-npm{pkg="..."}`).
 - Icons use `@nuxt/icon` with `<Icon name="simple-icons:github" />`
   instead of hand-rolled SVG components.
 
 ## Content DB in development
 
-After adding or removing content files, run `pnpm generate`
-before `pnpm dev`. The cloudflare preset serves the client-side
-SQL dump from Nitro build storage, which only `generate` (or
-`build`) populates. Without this step, SSR works but client-side
-navigation will 404.
+`pnpm dev` runs `nuxt cleanup` before starting the dev server,
+removing stale client-side SQL dumps that would otherwise cause
+SPA 404s. The dev server regenerates the content database on
+startup, so no separate `pnpm generate` step is needed.
 
 ## Dev server management
 

README.md

@@ -11,6 +11,7 @@ open-source projects, live at <https://awesome-apptly.com>.
 | Framework | [Nuxt 4](https://nuxt.com) + [Nuxt Content 3](https://content.nuxt.com) |
 | Hosting | [Cloudflare Workers](https://developers.cloudflare.com/workers/) (`cloudflare-module` preset) |
 | Database | [Cloudflare D1](https://developers.cloudflare.com/d1/) (content database) |
+| Cache | [Cloudflare KV](https://developers.cloudflare.com/kv/) (version cache) |
 | Styling | [Tailwind CSS 4](https://tailwindcss.com) + `@tailwindcss/typography` |
 | Icons | [`@nuxt/icon`](https://nuxt.com/modules/icon) + `@iconify-json/simple-icons` |
 | Badges | [`badge-maker`](https://github.com/badges/shields/tree/master/badge-maker) (self-hosted SVG badges, logos inlined as base64) |
@@ -62,15 +63,12 @@ file updates the Zod enum automatically (derived via `readdirSync`).
 
 ```sh
 pnpm install
-pnpm generate         # seed the client-side content DB (see below)
-pnpm dev              # local dev server
+pnpm dev              # runs nuxt cleanup + dev server
 ```
 
-**Content DB caveat:** the cloudflare preset's content handler
-serves the SQL dump from Nitro build storage. `pnpm generate`
-(or `pnpm build`) populates that storage. Without it, client-side
-navigation will 404 because the browser's WASM SQLite has no data.
-Re-run `pnpm generate` whenever content files are added or removed.
+`pnpm dev` runs `nuxt cleanup` before starting the dev server,
+removing stale client-side SQL dumps that would cause SPA 404s.
+The dev server regenerates the content database on startup.
 
 ## Build and deploy
 

app/components/badge-version-go.vue

@@ -1,12 +1,14 @@
 <script setup lang="ts">
 const props = defineProps<{
   mod: string
+  dir?: string
 }>();
 
+const pkg = computed(() => props.dir ? `${props.mod}/${props.dir}` : props.mod);
 const source = computed(() => `/api/badge/go/${props.mod}`);
-const href = computed(() => `https://pkg.go.dev/${props.mod}`);
-const alt = computed(() => `Go version for ${props.mod}`);
-const title = computed(() => `Go module ${props.mod}`);
+const href = computed(() => `https://pkg.go.dev/${pkg.value}`);
+const alt = computed(() => `Go version for ${pkg.value}`);
+const title = computed(() => `Go module ${pkg.value}`);
 </script>
 
 <template>

app/components/badge-version.vue

@@ -34,6 +34,7 @@ watch(() => props.src, () => {
     :title="title"
     target="_blank"
     rel="noopener"
+    class="inline-flex items-center leading-none"
   >
     <span
       v-if="!loaded && !error"
@@ -50,14 +51,19 @@ watch(() => props.src, () => {
       ref="badge"
       :src="src"
       :alt="alt"
-      class="h-5"
+      class="badge-version-img"
       @load="loaded = true"
       @error="error = true"
     >
   </a>
 </template>
 
 <style scoped>
+.badge-version-img {
+  height: 20px;
+  margin: 0;
+}
+
 .badge-version-skeleton {
   display: inline-block;
   width: 72px;

nuxt.config.ts

@@ -25,16 +25,36 @@ export default defineNuxtConfig({
       routes: ['/'],
       crawlLinks: true,
     },
+    storage: {
+      versions: {
+        driver: 'cloudflare-kv-binding',
+        binding: 'VERSIONS_KV',
+      },
+    },
+    devStorage: {
+      versions: {
+        driver: 'memory',
+      },
+    },
   },
   vite: {
     plugins: [tailwindcss()],
-    optimizeDeps: {
-      include: [],
-    },
     build: {
       sourcemap: isDevelopment,
     },
   },
+  hooks: {
+    'vite:extendConfig'(config) {
+      // @nuxtjs/mdc pushes remark/rehype entries into optimizeDeps.include
+      // after config merges, but they're unresolvable (server-only deps).
+      const include = config.optimizeDeps?.include;
+      if (include) {
+        config.optimizeDeps!.include = include.filter(
+          (entry: string) => !entry.includes('@nuxtjs/mdc >'),
+        );
+      }
+    },
+  },
   eslint: {
     config: {
       stylistic: true,

package.json

@@ -12,7 +12,7 @@
     "check": "run-s generate lint:check typecheck",
     "clean": "rimraf .output .nuxt .wrangler node_modules",
     "deploy": "wrangler deploy",
-    "dev": "nuxt dev --dotenv .env.local",
+    "dev": "nuxt cleanup && nuxt dev --dotenv .env.local",
     "generate": "nuxt generate",
     "lint": "eslint . --fix",
     "lint:check": "eslint .",
@@ -24,6 +24,7 @@
     "@nuxt/content": "^3.12.0",
     "@nuxt/icon": "^2.2.1",
     "badge-maker": "^5.0.2",
+    "consola": "^3.4.2",
     "nuxt": "^4.4.2",
     "nuxt-studio": "~1.4"
   },

pnpm-lock.yaml

@@ -1,21 +1,27 @@
 import { logos } from '#badge-logos';
 
-const COLOR = '007D9C';
-
 // Go module paths: domain.tld/path — first segment must contain a dot
 const GO_MODULE_RE = /^[a-z0-9][\w.-]*\.[a-z]{2,}(\/[\w.~-]+)*$/i;
 
-export default defineEventHandler(async (event) => {
-  const pkg = getRouterParam(event, 'package');
-  if (!pkg || !GO_MODULE_RE.test(pkg)) {
-    return renderBadgeError(event, { logo: logos.go, idSuffix: 'go' });
-  }
+// Go proxy requires uppercase letters encoded as !lowercase
+const escapeModulePath = (path: string) =>
+  path.replaceAll(/[A-Z]/g, (c) => `!${c.toLowerCase()}`);
+
+const badge = new BadgeHandler({
+  logo: logos.go,
+  idSuffix: 'go',
+  color: '007D9C',
+  pattern: GO_MODULE_RE,
 
-  const proxyUrl = `https://proxy.golang.org/${pkg}/@latest`;
-  const info = await $fetch<{ Version: string }>(proxyUrl).catch((error) => {
-    console.warn(`[badge/go] failed to fetch ${pkg}:`, error);
-    return undefined;
-  });
+  async fetch(modulePath, logger) {
+    const proxyUrl = `https://proxy.golang.org/${escapeModulePath(modulePath)}/@latest`;
+    const info = await $fetch<{ Version: string; Time: string }>(proxyUrl).catch((error) => {
+      logger.warn(`failed to fetch ${modulePath}:`, error);
+      return undefined;
+    });
 
-  return renderBadge(event, { logo: logos.go, idSuffix: 'go', color: COLOR, version: info?.Version });
+    return { version: info?.Version, lastModified: parseDate(info?.Time) };
+  },
 });
+
+export default badge.eventHandler;

server/api/badge/go/[...package].ts

@@ -1,21 +1,26 @@
 import { logos } from '#badge-logos';
 
-const COLOR = 'CB3837';
-
 // npm package names: @scope/name or name
 const NPM_PACKAGE_RE = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
 
-export default defineEventHandler(async (event) => {
-  const pkg = getRouterParam(event, 'package');
-  if (!pkg || !NPM_PACKAGE_RE.test(pkg)) {
-    return renderBadgeError(event, { logo: logos.npm, idSuffix: 'npm' });
-  }
+const badge = new BadgeHandler({
+  logo: logos.npm,
+  idSuffix: 'npm',
+  color: 'CB3837',
+  pattern: NPM_PACKAGE_RE,
 
-  const registryUrl = `https://registry.npmjs.org/${pkg}/latest`;
-  const info = await $fetch<{ version: string }>(registryUrl).catch((error) => {
-    console.warn(`[badge/npm] failed to fetch ${pkg}:`, error);
-    return undefined;
-  });
+  async fetch(pkg, logger) {
+    const registryUrl = `https://registry.npmjs.org/${pkg}/latest`;
+    const response = await $fetch.raw<{ version: string }>(registryUrl).catch((error) => {
+      logger.warn(`failed to fetch ${pkg}:`, error);
+      return undefined;
+    });
 
-  return renderBadge(event, { logo: logos.npm, idSuffix: 'npm', color: COLOR, version: info?.version });
+    return {
+      version: response?._data?.version,
+      lastModified: parseDate(response?.headers.get('last-modified') || undefined),
+    };
+  },
 });
+
+export default badge.eventHandler;