hono 4.13.7: RETAINED_304_HEADERS

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify hono.RETAINED_304_HEADERS in pkg:npm/hono@4.13.7
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/hono@4.13.7
Demonstrate these symbols/APIs:
  - hono.RETAINED_304_HEADERS

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:9fd0b213e5fa6016b9632dcdc495ee7e7f90eea12c8ecb6cb0ec132a84765062","contract":["RETAINED_304_HEADERS contains standard HTTP 304 response headers (cache-control, content-location, date, etag, expires, vary)","etag middleware preserves default RETAINED_304_HEADERS and strips other response headers on 304 Not Modified","etag middleware preserves additional custom headers on 304 responses when options.retainedHeaders extends RETAINED_304_HEADERS","etag middleware strips default headers on 304 responses when options.retainedHeaders is explicitly restricted"],"goal":"verify hono.RETAINED_304_HEADERS in pkg:npm/hono@4.13.7","kind":"HOW","packages":["pkg:npm/hono@4.13.7"],"schemaVersion":1,"symbols":["hono.RETAINED_304_HEADERS"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/hono@4.13.7"],"schemaVersion":1,"subject":"pkg:npm/hono@4.13.7","symbols":["hono.RETAINED_304_HEADERS"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-hono-retained-304-headers",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-hono-retained-304-headers",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "hono": "4.13.7"
      }
    },
    "node_modules/hono": {
      "version": "4.13.7",
      "resolved": "https://registry.npmjs.org/hono/-/hono-4.13.7.tgz",
      "integrity": "sha512-c8/gF9ac8Y78/agExVocyLevgR+JlpNB444Py0FSX8pJoPdYUfUzRcXtYEYGwt6l19qIlVZPN5Mfsw9jFShmQQ==",
      "license": "MIT",
      "engines": {
        "node": ">=16.9.0"
      }
    }
  }
}

{
  "name": "sample-hono-retained-304-headers",
  "version": "1.0.0",
  "private": true,
  "license": "MIT-0",
  "dependencies": {
    "hono": "4.13.7"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify hono.RETAINED_304_HEADERS in pkg:npm/hono@4.13.7",
  "kind": "HOW",
  "packages": [
    "pkg:npm/hono@4.13.7"
  ],
  "symbols": [
    "hono.RETAINED_304_HEADERS"
  ]
}

import { Hono } from 'hono';
import { RETAINED_304_HEADERS, etag } from 'hono/etag';

/**
 * Creates a Hono application with configured etag middleware.
 *
 * @param {object} [options] - Options passed to etag middleware.
 * @returns {Hono}
 */
export function createApp(options) {
  const app = new Hono();
  app.use('*', etag(options));
  return app;
}

export { RETAINED_304_HEADERS, etag, Hono };

import assert from 'node:assert/strict';
import { createApp, RETAINED_304_HEADERS, etag, Hono } from '../src/index.mjs';

async function testAll() {
  // Contract assertion 1: RETAINED_304_HEADERS contains standard HTTP 304 response headers
  {
    assert.ok(Array.isArray(RETAINED_304_HEADERS), 'RETAINED_304_HEADERS must be an array');
    const expectedHeaders = ['cache-control', 'content-location', 'date', 'etag', 'expires', 'vary'];
    assert.equal(RETAINED_304_HEADERS.length, expectedHeaders.length, 'RETAINED_304_HEADERS must have 6 standard headers');
    for (const header of expectedHeaders) {
      assert.ok(
        RETAINED_304_HEADERS.includes(header),
        `RETAINED_304_HEADERS must include ${header}`
      );
    }
  }

  // Contract assertion 2: etag middleware preserves default RETAINED_304_HEADERS and strips other response headers on 304 Not Modified
  {
    const app = createApp();
    app.get('/resource', (c) => {
      c.header('Cache-Control', 'public, max-age=3600');
      c.header('Vary', 'Accept-Encoding');
      c.header('X-Custom-Ephemeral', 'temporary-data');
      return c.text('resource content');
    });

    const initialRes = await app.request('http://localhost/resource');
    assert.equal(initialRes.status, 200, 'Initial request should return 200 OK');
    const etagHeader = initialRes.headers.get('ETag');
    assert.ok(etagHeader, 'Initial response must include an ETag header');
    assert.equal(initialRes.headers.get('Cache-Control'), 'public, max-age=3600');
    assert.equal(initialRes.headers.get('Vary'), 'Accept-Encoding');
    assert.equal(initialRes.headers.get('X-Custom-Ephemeral'), 'temporary-data');

    const conditionalRes = await app.request('http://localhost/resource', {
      headers: { 'If-None-Match': etagHeader }
    });
    assert.equal(conditionalRes.status, 304, 'Conditional request should return 304 Not Modified');
    assert.equal(conditionalRes.headers.get('ETag'), etagHeader, 'ETag must be retained');
    assert.equal(conditionalRes.headers.get('Cache-Control'), 'public, max-age=3600', 'Cache-Control in RETAINED_304_HEADERS must be retained');
    assert.equal(conditionalRes.headers.get('Vary'), 'Accept-Encoding', 'Vary in RETAINED_304_HEADERS must be retained');
    assert.equal(conditionalRes.headers.get('X-Custom-Ephemeral'), null, 'Headers not in RETAINED_304_HEADERS must be stripped');
  }

  // Contract assertion 3: etag middleware preserves additional custom headers on 304 responses when options.retainedHeaders extends RETAINED_304_HEADERS
  {
    const app = createApp({
      retainedHeaders: [...RETAINED_304_HEADERS, 'x-custom-retained']
    });
    app.get('/custom', (c) => {
      c.header('Cache-Control', 'private, no-transform');
      c.header('X-Custom-Retained', 'keep-me');
      c.header('X-Custom-Discarded', 'discard-me');
      return c.text('custom resource');
    });

    const initialRes = await app.request('http://localhost/custom');
    assert.equal(initialRes.status, 200);
    const etagHeader = initialRes.headers.get('ETag');
    assert.ok(etagHeader);

    const conditionalRes = await app.request('http://localhost/custom', {
      headers: { 'If-None-Match': etagHeader }
    });
    assert.equal(conditionalRes.status, 304);
    assert.equal(conditionalRes.headers.get('Cache-Control'), 'private, no-transform', 'Default retained header preserved');
    assert.equal(conditionalRes.headers.get('X-Custom-Retained'), 'keep-me', 'Custom extended header must be retained');
    assert.equal(conditionalRes.headers.get('X-Custom-Discarded'), null, 'Non-retained header must be stripped');
  }

  // Contract assertion 4: etag middleware strips default headers on 304 responses when options.retainedHeaders is explicitly restricted
  {
    const app = createApp({
      retainedHeaders: ['etag']
    });
    app.get('/restricted', (c) => {
      c.header('Cache-Control', 'public, max-age=1800');
      c.header('Vary', 'User-Agent');
      return c.text('restricted resource');
    });

    const initialRes = await app.request('http://localhost/restricted');
    assert.equal(initialRes.status, 200);
    const etagHeader = initialRes.headers.get('ETag');
    assert.ok(etagHeader);

    const conditionalRes = await app.request('http://localhost/restricted', {
      headers: { 'If-None-Match': etagHeader }
    });
    assert.equal(conditionalRes.status, 304);
    assert.equal(conditionalRes.headers.get('ETag'), etagHeader, 'Explicitly retained ETag is preserved');
    assert.equal(conditionalRes.headers.get('Cache-Control'), null, 'Cache-Control stripped when excluded from restricted retainedHeaders');
    assert.equal(conditionalRes.headers.get('Vary'), null, 'Vary stripped when excluded from restricted retainedHeaders');
  }

  console.log('All contract assertions for hono.RETAINED_304_HEADERS passed.');
}

testAll().catch((err) => {
  console.error('Contract test failed:', err);
  process.exit(1);
});