@hono/node-server 2.1.1: serve

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/node-server.serve in pkg:npm/%40hono/node-server@2.1.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40hono/node-server@2.1.1
Demonstrate these symbols/APIs:
  - @hono/node-server.serve
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:112e71475f4cdca12cd7b5c5ddb243b4ec001578a3b1d37dd353897ce479d7b6","constraints":{"executionContext":"node"},"contract":["@hono/node-server exports serve function","serve starts an HTTP server and returns an http.Server instance","serve invokes listeningListener with server AddressInfo including port and address","serve handles HTTP GET requests and returns web-standard Response with status, headers, and body","serve handles HTTP POST requests with JSON payload and request headers","serve supports custom createServer option","serve HTTP server closes cleanly"],"goal":"verify @hono/node-server.serve in pkg:npm/%40hono/node-server@2.1.1","kind":"HOW","packages":["pkg:npm/%40hono/node-server@2.1.1"],"schemaVersion":1,"symbols":["@hono/node-server.serve"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40hono/node-server@2.1.1"],"schemaVersion":1,"subject":"pkg:npm/%40hono/node-server@2.1.1","symbols":["@hono/node-server.serve"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-hono-node-server-serve",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-hono-node-server-serve",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@hono/node-server": "2.1.1"
      }
    },
    "node_modules/@hono/node-server": {
      "version": "2.1.1",
      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-2.1.1.tgz",
      "integrity": "sha512-ELuehkj5VCBdgEw9zs+ivkKwyzzUCSQuE96YmiPvn1ECBoZCczbFXJLeEGMTYjphP6gydh4pHMqEYPVMYUVgQg==",
      "license": "MIT",
      "engines": {
        "node": ">=20"
      },
      "peerDependencies": {
        "hono": "^4"
      }
    },
    "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",
      "peer": true,
      "engines": {
        "node": ">=16.9.0"
      }
    }
  }
}

{
  "name": "sample-hono-node-server-serve",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "description": "verify @hono/node-server.serve in pkg:npm/%40hono/node-server@2.1.1",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@hono/node-server": "2.1.1"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify @hono/node-server.serve in pkg:npm/%40hono/node-server@2.1.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40hono/node-server@2.1.1"
  ],
  "symbols": [
    "@hono/node-server.serve"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

import assert from 'node:assert/strict';
import http from 'node:http';
import { serve } from '@hono/node-server';

// 1. @hono/node-server exports serve function
assert.strictEqual(typeof serve, 'function', '@hono/node-server must export serve function');

// 2. serve starts an HTTP server and returns an http.Server instance
// 3. serve invokes listeningListener with server AddressInfo including port and address
let listenerCalled = false;
let serverInfo = null;

const server = serve(
  {
    fetch: async (request) => {
      const url = new URL(request.url);

      if (url.pathname === '/hello' && request.method === 'GET') {
        return new Response('Hello from @hono/node-server.serve!', {
          status: 200,
          headers: {
            'content-type': 'text/plain; charset=utf-8',
            'x-custom-test': 'ok',
          },
        });
      }

      if (url.pathname === '/echo-json' && request.method === 'POST') {
        const body = await request.json();
        const customHeader = request.headers.get('x-client-header') || '';
        return new Response(JSON.stringify({ received: body, customHeader }), {
          status: 201,
          headers: { 'content-type': 'application/json' },
        });
      }

      return new Response('Not Found', { status: 404 });
    },
    port: 0,
    hostname: '127.0.0.1',
  },
  (info) => {
    listenerCalled = true;
    serverInfo = info;
  }
);

assert.ok(server instanceof http.Server, 'serve must return an http.Server instance');

await new Promise((resolve) => {
  if (server.listening && listenerCalled) {
    resolve();
  } else {
    server.once('listening', resolve);
  }
});

assert.strictEqual(listenerCalled, true, 'listeningListener callback should be invoked');
assert.ok(serverInfo, 'serverInfo should be provided to listeningListener');
assert.strictEqual(typeof serverInfo.port, 'number', 'port must be number');
assert.ok(serverInfo.port > 0, 'port must be > 0');
assert.strictEqual(serverInfo.address, '127.0.0.1', 'address must be 127.0.0.1');

const baseUrl = `http://127.0.0.1:${serverInfo.port}`;

// 4. serve handles HTTP GET requests and returns web-standard Response with status, headers, and body
const getRes = await fetch(`${baseUrl}/hello`);
assert.strictEqual(getRes.status, 200, 'GET status should be 200');
assert.strictEqual(getRes.headers.get('content-type'), 'text/plain; charset=utf-8');
assert.strictEqual(getRes.headers.get('x-custom-test'), 'ok');
const getText = await getRes.text();
assert.strictEqual(getText, 'Hello from @hono/node-server.serve!');

// 5. serve handles HTTP POST requests with JSON payload and request headers
const postPayload = { library: '@hono/node-server', version: '2.1.1' };
const postRes = await fetch(`${baseUrl}/echo-json`, {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'x-client-header': 'test-val-xyz',
  },
  body: JSON.stringify(postPayload),
});
assert.strictEqual(postRes.status, 201, 'POST status should be 201');
assert.strictEqual(postRes.headers.get('content-type'), 'application/json');
const postData = await postRes.json();
assert.deepStrictEqual(postData, {
  received: postPayload,
  customHeader: 'test-val-xyz',
});

// 6. serve HTTP server closes cleanly
await new Promise((resolve, reject) => {
  server.close((err) => (err ? reject(err) : resolve()));
});
assert.strictEqual(server.listening, false, 'server should not be listening after close');

// 7. serve supports custom createServer option
let customCreateServerCalled = false;
const customServer = serve({
  fetch: () => new Response('custom server response'),
  port: 0,
  hostname: '127.0.0.1',
  createServer: (...args) => {
    customCreateServerCalled = true;
    return http.createServer(...args);
  },
});

await new Promise((resolve) => {
  if (customServer.listening) resolve();
  else customServer.once('listening', resolve);
});

assert.strictEqual(customCreateServerCalled, true, 'custom createServer must be called');

const customAddr = customServer.address();
const customRes = await fetch(`http://127.0.0.1:${customAddr.port}/`);
assert.strictEqual(customRes.status, 200);
assert.strictEqual(await customRes.text(), 'custom server response');

await new Promise((resolve, reject) => {
  customServer.close((err) => (err ? reject(err) : resolve()));
});
assert.strictEqual(customServer.listening, false, 'customServer should not be listening after close');

console.log('All @hono/node-server.serve contract tests passed.');