@hono/node-server 2.1.0: 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.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40hono/node-server@2.1.0
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:93627288ed70207e2ff02a6fd38ef467ae3b99c995e9f9f5c61ebb733164087d","constraints":{"executionContext":"node"},"contract":["@hono/node-server.serve creates and starts an HTTP server using a web standard fetch handler and options","@hono/node-server.serve invokes the listening listener callback with server address info","@hono/node-server.serve handles incoming HTTP GET requests and returns web standard Response bodies and headers","@hono/node-server.serve handles incoming HTTP POST requests with request headers and JSON bodies","@hono/node-server.serve returns an http.Server instance that can be closed"],"goal":"verify @hono/node-server.serve in pkg:npm/%40hono/node-server@2.1.0","kind":"HOW","packages":["pkg:npm/%40hono/node-server@2.1.0"],"schemaVersion":1,"symbols":["@hono/node-server.serve"]},"contractCommand":["node","test/contract.js"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","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.0"],"schemaVersion":1,"subject":"pkg:npm/%40hono/node-server@2.1.0","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.0"
      }
    },
    "node_modules/@hono/node-server": {
      "version": "2.1.0",
      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-2.1.0.tgz",
      "integrity": "sha512-XovyyCCnBzW+zKu+z/zq8hwNs4KOR5rEMAOxo2f40Q5xoOI37IMm6MIg2COOUtUApo0i6850MTBKH2u4QLGIqg==",
      "license": "MIT",
      "engines": {
        "node": ">=20"
      },
      "peerDependencies": {
        "hono": "^4"
      }
    },
    "node_modules/hono": {
      "version": "4.13.5",
      "resolved": "https://registry.npmjs.org/hono/-/hono-4.13.5.tgz",
      "integrity": "sha512-O6+/eCYRkzzzy0rPWwKLiGBR1nFuUPZynnwjxN1MBA62NNqbT0wQEzQyK2gSO5yDIDB336sXQleAhOHrzlYyKw==",
      "license": "MIT",
      "peer": true,
      "engines": {
        "node": ">=16.9.0"
      }
    }
  }
}

{
  "name": "sample-hono-node-server-serve",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification sample for @hono/node-server.serve",
  "main": "src/index.js",
  "scripts": {
    "test": "node test/contract.js"
  },
  "dependencies": {
    "@hono/node-server": "2.1.0"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify @hono/node-server.serve in pkg:npm/%40hono/node-server@2.1.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40hono/node-server@2.1.0"
  ],
  "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"
  }
}

const { serve } = require('@hono/node-server');

/**
 * Creates and starts an HTTP server using @hono/node-server.serve with a fetch handler.
 * @param {Function} fetchHandler - Web standard (request: Request) => Response | Promise<Response>
 * @param {Object} [options={}] - Server options (port, hostname, etc.)
 * @param {Function} [onListening] - Callback called when server begins listening
 * @returns {import('node:http').Server}
 */
function createServer(fetchHandler, options = {}, onListening) {
  const serverOptions = {
    fetch: fetchHandler,
    port: options.port ?? 0,
    hostname: options.hostname ?? '127.0.0.1',
    ...options
  };
  return serve(serverOptions, onListening);
}

/**
 * Starts a simple router/handler server and returns a promise resolving to { server, url, close }.
 * @param {Function} fetchHandler
 * @param {number} [port=0]
 * @returns {Promise<{ server: import('node:http').Server, port: number, url: string, close: () => Promise<void> }>}
 */
function startServerAsync(fetchHandler, port = 0) {
  return new Promise((resolve, reject) => {
    try {
      const server = serve({ fetch: fetchHandler, port, hostname: '127.0.0.1' }, (info) => {
        const url = `http://127.0.0.1:${info.port}`;
        resolve({
          server,
          port: info.port,
          url,
          close: () => new Promise((res, rej) => server.close((err) => (err ? rej(err) : res())))
        });
      });
      server.on('error', reject);
    } catch (err) {
      reject(err);
    }
  });
}

module.exports = {
  serve,
  createServer,
  startServerAsync
};

const assert = require('node:assert');
const { serve } = require('@hono/node-server');
const { createServer, startServerAsync } = require('../src/index.js');

async function runContractTests() {
  // 1. @hono/node-server.serve creates and starts an HTTP server using a web standard fetch handler and options
  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!', {
            status: 200,
            headers: { 'content-type': 'text/plain; charset=utf-8' }
          });
        }

        if (url.pathname === '/echo-json' && request.method === 'POST') {
          const body = await request.json();
          const customHeader = request.headers.get('x-test-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;
    }
  );

  // Wait briefly for server to be ready if callback hasn't fired yet
  await new Promise((resolve) => {
    if (listenerCalled) {
      resolve();
    } else {
      server.once('listening', resolve);
    }
  });

  // 2. @hono/node-server.serve invokes the listening listener callback with server address info
  assert.strictEqual(listenerCalled, true, 'listening callback should be invoked');
  assert.ok(serverInfo, 'serverInfo should be defined');
  assert.ok(typeof serverInfo.port === 'number' && serverInfo.port > 0, 'port should be a positive number');
  assert.strictEqual(serverInfo.address, '127.0.0.1', 'address should match configured hostname');

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

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

  // 4. @hono/node-server.serve handles incoming HTTP POST requests with request headers and JSON bodies
  const postPayload = { symbol: '@hono/node-server.serve', active: true };
  const postRes = await fetch(`${baseUrl}/echo-json`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-test-header': 'test-value-123'
    },
    body: JSON.stringify(postPayload)
  });
  assert.strictEqual(postRes.status, 201, 'POST /echo-json should return status 201');
  const postData = await postRes.json();
  assert.deepStrictEqual(postData, { received: postPayload, customHeader: 'test-value-123' }, 'POST should return parsed json');

  // 404 handler check
  const notFoundRes = await fetch(`${baseUrl}/nonexistent`);
  assert.strictEqual(notFoundRes.status, 404, 'Unknown path should return 404');

  // 5. @hono/node-server.serve returns an http.Server instance that can be closed
  await new Promise((resolve, reject) => {
    server.close((err) => (err ? reject(err) : resolve()));
  });

  // 6. Test helper startServerAsync wrapper
  const instance = await startServerAsync((req) => new Response('async helper test'));
  try {
    const res = await fetch(instance.url);
    assert.strictEqual(res.status, 200);
    const txt = await res.text();
    assert.strictEqual(txt, 'async helper test');
  } finally {
    await instance.close();
  }

  console.log('All contract tests passed successfully.');
}

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