feat(serve): let a page set its own status, and stop 404ing on a trailing slash

definePageMeta({ status }) is read out of the source before anything runs,
which is no use to a page that is only sometimes an error page. A page
addressed by a dynamic segment cannot know whether the thing exists until it
has looked, so it rendered "no such repository" under a 200 - which tells a
crawler, a cache and an uptime check that the page is fine.

setResponseStatus(code) is the missing half. The render cache now carries the
status with the HTML, so a cached page answers what the first render did;
without that a cached not-found page would have gone back to 200 on its second
request, a bug that only appears once a page is popular enough to be cached.

Separately, a trailing slash named a page nothing could match: /docs/ looked
for docs//index.stx and matched no dynamic route either. It is the same page.

Author: chrisbbreuer

docs/guide/script-types.md

@@ -50,10 +50,42 @@ definePageMeta({
 
 - **Data fetching**: `fetch()`, database queries, file reads
 - **SEO**: `useSeoMeta()`, `definePageMeta()`
+- **The response status**: `setResponseStatus()`, when the page is the only thing that knows it
 - **Variable declarations**: All `const`, `let`, `var`, and `function` declarations are automatically available to `{{ }}` expressions
 - **Use secrets**: API keys, database credentials -- this code never reaches the browser
 - **Import server modules**: Bun APIs, Node.js builtins, server-only npm packages
 
+### Setting the status from the page
+
+`definePageMeta({ status: 404 })` is read out of the source before anything
+runs, which is right for a page that is always an error page. A page addressed
+by a dynamic segment -- a repository, a user, an order -- cannot know whether
+the thing exists until it has looked, so it needs to say so afterwards:
+
+```html
+<!-- views/[owner]/[repository]/index.stx -->
+<script server>
+const repository = await findRepository(params.owner, params.repository)
+
+if (!repository)
+  setResponseStatus(404)
+</script>
+
+@if (repository)
+  <h1>{{ repository.name }}</h1>
+@else
+  <h1>No such repository</h1>
+@endif
+```
+
+Without it the page renders "no such repository" under a 200, which tells a
+crawler, a cache and an uptime check that the page is fine.
+
+The last call wins, so a page can decide late. A status outside the HTTP range
+is ignored rather than thrown: it is not worth failing a page that has already
+rendered. The render cache carries the status with the HTML, so a cached page
+answers what the first render did.
+
 ### What You Cannot Do in `<script server>`
 
 - Access `document`, `window`, `localStorage`, or any browser API

packages/bun-plugin/src/serve.ts

@@ -937,6 +937,14 @@ export async function serve(options: ServeOptions): Promise<void> {
   interface HtmlCacheEntry {
     html: string
     signature: Map<string, number>
+    /**
+     * The status the render settled on, so a cached hit answers what the
+     * uncached render did. A page that calls `setResponseStatus` decides its
+     * status inside a server script the cache fast path skips, so without
+     * this a "not found" page would be served as 200 the moment it was
+     * rendered twice - the kind of bug that only appears under load.
+     */
+    status: number
   }
   const htmlCache = new Map<string, HtmlCacheEntry>()
   // Opt-in because generic server scripts may read external state that no
@@ -1318,6 +1326,24 @@ export async function serve(options: ServeOptions): Promise<void> {
     }
     context.__stxServeContext = full
     ;(globalThis as { __stxServeContext?: ServeRequestContext }).__stxServeContext = full
+
+    // The status, decided while rendering rather than declared in the source.
+    //
+    // `definePageMeta({ status })` is read out of the file before anything
+    // runs, which is right for a page that is always an error page and no use
+    // to a page that only sometimes is. A page addressed by a dynamic segment
+    // - a repository, a user, an order - cannot know whether the thing exists
+    // until it has looked, and until now it had no way to say so: it rendered
+    // "no such repository" under a 200, which tells a crawler, a cache and a
+    // monitor that the page is fine.
+    //
+    // Last call wins, so a page can decide late. Anything outside the HTTP
+    // range is ignored rather than thrown, because a status is not worth
+    // failing a rendered page over.
+    context.setResponseStatus = (status: number): void => {
+      if (Number.isInteger(status) && status >= 100 && status <= 599)
+        full.responseStatus = status
+    }
   }
 
   /** Render cache must vary by locale/host/cookies — same `.stx` file can serve different `t()`/host/cookie-gated output. */
@@ -1754,8 +1780,11 @@ export async function serve(options: ServeOptions): Promise<void> {
     if (ENABLE_HTML_CACHE && !skipCacheHint) {
       const cacheKey = htmlCacheKey(filePath, reqCtx)
       const cachedEntry = htmlCache.get(cacheKey)
-      if (cachedEntry && await templateSignatureFresh(cachedEntry.signature))
+      if (cachedEntry && await templateSignatureFresh(cachedEntry.signature)) {
+        if (reqCtx)
+          reqCtx.responseStatus = cachedEntry.status
         return cachedEntry.html
+      }
     }
 
     // Extract server script bodies for variable extraction, and remove only
@@ -1880,7 +1909,7 @@ export async function serve(options: ServeOptions): Promise<void> {
         && isRenderableCacheCandidate(output)
     ) {
       const signature = await buildTemplateSignature(filePath, dependencies)
-      htmlCache.set(htmlCacheKey(filePath, reqCtx), { html: output, signature })
+      htmlCache.set(htmlCacheKey(filePath, reqCtx), { html: output, signature, status: reqCtx?.responseStatus ?? 200 })
     }
 
     return output
@@ -1897,6 +1926,13 @@ export async function serve(options: ServeOptions): Promise<void> {
     // Normalize the request path
     let normalizedPath = requestPath.startsWith('/') ? requestPath.slice(1) : requestPath
 
+    // A trailing slash names the same page. Without this, `/docs/` looked for
+    // `docs//index.stx` and matched no dynamic regex either, so a link somebody
+    // wrote with a slash on the end, or a browser that added one, 404'd on a
+    // page that plainly exists. The root is already the empty string here, so
+    // there is nothing to strip off it.
+    normalizedPath = normalizedPath.replace(/\/+$/, '')
+
     // Try to find matching file with various strategies
     const possibleFiles: string[] = []
 

packages/bun-plugin/test/serve-response-status.test.ts

@@ -0,0 +1,150 @@
+import { afterAll, beforeAll, describe, expect, it, setDefaultTimeout } from 'bun:test'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+
+/**
+ * A page deciding its own status while it renders.
+ *
+ * `definePageMeta({ status })` is read out of the source before anything runs,
+ * which is right for a page that is always an error page and no use to a page
+ * that is only sometimes one. A page addressed by a dynamic segment - a
+ * repository, a user, an order - cannot know whether the thing exists until it
+ * has looked, and had no way to say so afterwards: it rendered "no such
+ * repository" under a 200, which tells a crawler, a cache and an uptime check
+ * that the page is fine.
+ *
+ * `setResponseStatus(code)` is that missing half, and the render cache carries
+ * the status with the HTML so a second request answers what the first did.
+ */
+
+setDefaultTimeout(60_000)
+
+const PORT = 43_100 + (process.pid % 400)
+const BASE = `http://localhost:${PORT}`
+const SERVE_SRC = path.join(import.meta.dir, '..', 'src', 'serve.ts')
+
+let dir: string
+let proc: ReturnType<typeof Bun.spawn> | null = null
+
+beforeAll(async () => {
+  dir = await mkdtemp(path.join(tmpdir(), 'stx-serve-status-'))
+
+  // The case this exists for: one file, two answers, and only the render knows
+  // which. `known` is a thing that exists; anything else is not.
+  await Bun.write(path.join(dir, 'views', 'thing', '[id].stx'), `<script server>
+const found = id === 'known'
+if (!found)
+  setResponseStatus(404)
+</script>
+<main>{{ found ? 'here it is' : 'no such thing' }}</main>
+`)
+
+  // A static page, to prove the API is not dynamic-route-only.
+  await Bun.write(path.join(dir, 'views', 'gone.stx'), `<script server>
+setResponseStatus(410)
+</script>
+<main>gone</main>
+`)
+
+  // Out of range, and the wrong type. Neither is worth failing a page that has
+  // already rendered, so both are ignored and the page answers 200.
+  await Bun.write(path.join(dir, 'views', 'nonsense.stx'), `<script server>
+setResponseStatus(999)
+setResponseStatus(-1)
+</script>
+<main>still fine</main>
+`)
+
+  // Last call wins, so a page can look, decide, then change its mind.
+  await Bun.write(path.join(dir, 'views', 'reconsidered.stx'), `<script server>
+setResponseStatus(404)
+setResponseStatus(200)
+</script>
+<main>found after all</main>
+`)
+
+  await Bun.write(path.join(dir, 'driver.ts'), `import { serve } from ${JSON.stringify(SERVE_SRC)}
+
+serve({
+  patterns: ['views'],
+  port: ${PORT},
+  renderCache: true,
+})
+`)
+
+  proc = Bun.spawn(['bun', 'driver.ts'], { cwd: dir, stdout: 'pipe', stderr: 'pipe' })
+
+  const deadline = Date.now() + 30_000
+  while (true) {
+    try {
+      await fetch(`${BASE}/definitely-not-a-page`)
+      break
+    }
+    catch {
+      if (Date.now() > deadline)
+        throw new Error('serve() never came up')
+      await Bun.sleep(120)
+    }
+  }
+})
+
+afterAll(async () => {
+  proc?.kill()
+  await rm(dir, { recursive: true, force: true })
+})
+
+describe('setResponseStatus', () => {
+  it('lets one dynamic route answer 200 or 404 depending on what it found', async () => {
+    const found = await fetch(`${BASE}/thing/known`)
+    const missing = await fetch(`${BASE}/thing/anything-else`)
+
+    expect(found.status).toBe(200)
+    expect(await found.text()).toContain('here it is')
+
+    expect(missing.status).toBe(404)
+    expect(await missing.text()).toContain('no such thing')
+  })
+
+  it('works on a static page too', async () => {
+    expect((await fetch(`${BASE}/gone`)).status).toBe(410)
+  })
+
+  it('ignores a status that is not one, rather than failing the page', async () => {
+    const res = await fetch(`${BASE}/nonsense`)
+
+    expect(res.status).toBe(200)
+    expect(await res.text()).toContain('still fine')
+  })
+
+  it('takes the last call, so a page can decide late', async () => {
+    expect((await fetch(`${BASE}/reconsidered`)).status).toBe(200)
+  })
+
+  /**
+   * A slash on the end names the same page. A link written with one, or a
+   * browser that added one, used to 404 on a page that plainly exists.
+   */
+  it('answers the same on a path with a trailing slash', async () => {
+    const withSlash = await fetch(`${BASE}/thing/known/`)
+
+    expect(withSlash.status).toBe(200)
+    expect(await withSlash.text()).toContain('here it is')
+
+    expect((await fetch(`${BASE}/gone/`)).status).toBe(410)
+  })
+
+  /**
+   * The one that would have shipped broken. The cache fast path returns before
+   * any server script runs, so a cached "not found" page would have answered
+   * 200 from its second request onward - a bug that only appears once a page
+   * is popular enough to be cached.
+   */
+  it('keeps the status when the render is served from cache', async () => {
+    for (let attempt = 0; attempt < 3; attempt++)
+      expect((await fetch(`${BASE}/thing/still-missing`)).status).toBe(404)
+
+    for (let attempt = 0; attempt < 3; attempt++)
+      expect((await fetch(`${BASE}/thing/known`)).status).toBe(200)
+  })
+})