@hono/node-server 2.1.1

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 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

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:ce463a8c56174c99c5e92fd8fec9f403807ecba0dd768757ae002d5be16935ca","contract":["serve starts an HTTP server and dispatches standard web Fetch requests","createAdaptorServer instantiates an unbound Node.js http.Server instance","getRequestListener adapts a web standard Fetch handler into a Node.js request listener","getConnInfo retrieves connection information including remote address and port","serveStatic middleware serves static files from the filesystem"],"goal":"verify pkg:npm/%40hono/node-server@2.1.1","kind":"HOW","packages":["pkg:npm/%40hono/node-server@2.1.1"],"schemaVersion":1},"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","verifierAdapter":"node-typescript@1"}

import { serve, createAdaptorServer, getRequestListener } from '@hono/node-server';
import { getConnInfo } from '@hono/node-server/conninfo';
import { serveStatic } from '@hono/node-server/serve-static';

/**
 * Starts an HTTP server using @hono/node-server serve.
 * @param {Function} fetchHandler - The Fetch API request handler.
 * @param {Object} [options={}] - Server options.
 * @param {Function} [onListen] - Callback invoked when server starts listening.
 * @returns {import('node:http').Server} Active Node.js HTTP server.
 */
export function startServer(fetchHandler, options = {}, onListen) {
  return serve(
    {
      fetch: fetchHandler,
      port: options.port !== undefined ? options.port : 0,
      hostname: options.hostname || '127.0.0.1',
      ...options,
    },
    onListen
  );
}

/**
 * Creates an unlistening http.Server instance configured with a fetch handler.
 * @param {Function} fetchHandler - The Fetch API request handler.
 * @returns {import('node:http').Server} Unbound Node.js HTTP server.
 */
export function createServerAdaptor(fetchHandler) {
  return createAdaptorServer({
    fetch: fetchHandler,
  });
}

/**
 * Converts a Fetch API handler into a Node.js (req, res) request listener.
 * @param {Function} fetchHandler - The Fetch API request handler.
 * @returns {Function} Node.js request listener callback.
 */
export function createListener(fetchHandler) {
  return getRequestListener(fetchHandler);
}

export { serve, createAdaptorServer, getRequestListener, getConnInfo, serveStatic };

{
  "name": "verify-hono-node-server",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "verify-hono-node-server",
      "version": "1.0.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.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": "verify-hono-node-server",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "description": "Clean-room verification sample for @hono/node-server",
  "main": "index.mjs",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@hono/node-server": "2.1.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40hono/node-server@2.1.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40hono/node-server@2.1.1"
  ]
}

import assert from 'node:assert/strict';
import http from 'node:http';
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { Hono } from 'hono';
import {
  serve,
  createAdaptorServer,
  getRequestListener,
  getConnInfo,
  serveStatic,
  startServer,
  createServerAdaptor,
  createListener,
} from '../index.mjs';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

async function runContractTests() {
  // Contract 1: serve starts an HTTP server and dispatches standard web Fetch requests
  {
    let listenCalled = false;
    let listenInfo = null;

    const server = startServer(
      async (req) => {
        const url = new URL(req.url);
        if (url.pathname === '/echo' && req.method === 'POST') {
          const body = await req.json();
          return new Response(JSON.stringify({ received: body }), {
            status: 200,
            headers: {
              'Content-Type': 'application/json',
              'X-Custom-Header': 'hono-node-server-2.1.1',
            },
          });
        }
        return new Response('Not Found', { status: 404 });
      },
      { port: 0, hostname: '127.0.0.1' },
      (info) => {
        listenCalled = true;
        listenInfo = info;
      }
    );

    await new Promise((resolve) => server.on('listening', resolve));
    assert.strictEqual(listenCalled, true, 'Listen callback should be called');
    assert.ok(listenInfo && typeof listenInfo.port === 'number', 'Listen info must contain port');

    const port = server.address().port;
    const response = await fetch(`http://127.0.0.1:${port}/echo`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message: 'hello from hono 2.1.1' }),
    });

    assert.strictEqual(response.status, 200);
    assert.strictEqual(response.headers.get('x-custom-header'), 'hono-node-server-2.1.1');
    const data = await response.json();
    assert.deepStrictEqual(data, { received: { message: 'hello from hono 2.1.1' } });

    await new Promise((resolve) => server.close(resolve));
  }

  // Contract 2: createAdaptorServer instantiates an unbound Node.js http.Server instance
  {
    const server = createServerAdaptor((req) => {
      return new Response('adapted-server-ok', { status: 200 });
    });

    assert.ok(server instanceof http.Server, 'Should return an http.Server instance');
    assert.strictEqual(server.listening, false, 'Server should not be listening initially');

    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
    const port = server.address().port;

    const res = await fetch(`http://127.0.0.1:${port}/`);
    assert.strictEqual(res.status, 200);
    const text = await res.text();
    assert.strictEqual(text, 'adapted-server-ok');

    await new Promise((resolve) => server.close(resolve));
  }

  // Contract 3: getRequestListener adapts a web standard Fetch handler into a Node.js request listener
  {
    const handler = (req) => {
      const url = new URL(req.url);
      return new Response(`handled:${url.pathname}`, {
        status: 200,
        headers: { 'X-Handler': 'fetch-listener' },
      });
    };

    const listener = createListener(handler);
    assert.strictEqual(typeof listener, 'function', 'Listener should be a function');

    const server = http.createServer(listener);
    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
    const port = server.address().port;

    const res = await fetch(`http://127.0.0.1:${port}/test-route`);
    assert.strictEqual(res.status, 200);
    assert.strictEqual(res.headers.get('x-handler'), 'fetch-listener');
    const text = await res.text();
    assert.strictEqual(text, 'handled:/test-route');

    await new Promise((resolve) => server.close(resolve));
  }

  // Contract 4: getConnInfo retrieves connection information including remote address and port
  {
    const app = new Hono();
    app.get('/conn-info', (c) => {
      const info = getConnInfo(c);
      return c.json({
        address: info.remote.address,
        addressType: info.remote.addressType,
      });
    });

    const server = serve({
      fetch: app.fetch,
      port: 0,
      hostname: '127.0.0.1',
    });

    await new Promise((resolve) => server.on('listening', resolve));
    const port = server.address().port;

    const res = await fetch(`http://127.0.0.1:${port}/conn-info`);
    assert.strictEqual(res.status, 200);
    const body = await res.json();
    assert.strictEqual(body.address, '127.0.0.1');
    assert.strictEqual(body.addressType, 'IPv4');

    await new Promise((resolve) => server.close(resolve));
  }

  // Contract 5: serveStatic middleware serves static files from the filesystem
  {
    const fixtureDir = path.join(__dirname, 'fixtures');
    fs.mkdirSync(fixtureDir, { recursive: true });
    fs.writeFileSync(path.join(fixtureDir, 'sample.txt'), 'static file content for hono 2.1.1');

    try {
      const app = new Hono();
      app.use(
        '/static/*',
        serveStatic({
          root: path.relative(process.cwd(), fixtureDir),
          rewriteRequestPath: (p) => p.replace(/^\/static/, ''),
        })
      );

      const server = serve({
        fetch: app.fetch,
        port: 0,
        hostname: '127.0.0.1',
      });

      await new Promise((resolve) => server.on('listening', resolve));
      const port = server.address().port;

      const res = await fetch(`http://127.0.0.1:${port}/static/sample.txt`);
      assert.strictEqual(res.status, 200);
      const text = await res.text();
      assert.strictEqual(text, 'static file content for hono 2.1.1');

      await new Promise((resolve) => server.close(resolve));
    } finally {
      fs.rmSync(fixtureDir, { recursive: true, force: true });
    }
  }

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

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