koa-classic-server 3.0.0 → 3.0.1

package/__tests__/head-method.test.js

@@ -0,0 +1,160 @@
+const Koa = require('koa');
+const koaClassicServer = require('../index.cjs');
+const supertest = require('supertest');
+const path = require('path');
+const fs = require('fs');
+const ejs = require('ejs');
+
+// Regression tests for the HEAD-method HTTP-conformance bug.
+//
+// RFC 9110 §9.3.2: a HEAD response must be identical to the GET response for the
+// same resource, minus the message body — same status code, same headers
+// (notably Content-Type and Content-Length).
+//
+// Before the fix, a route served by the template engine returned 200 on GET but
+// 404 on HEAD whenever the operator's render function did not itself handle HEAD
+// (e.g. it returned early on non-GET requests). The static-file branch already
+// handled HEAD correctly, and directory listings happened to work because Koa
+// strips the string body for HEAD — only the template branch was broken.
+
+const ROOT = path.join(__dirname, 'publicWwwTest');
+
+// Minimal data for the templates exercised here. ejs-templates/index.ejs needs no
+// variables; simple.ejs needs these four. Anything else renders with no locals.
+function templateData(filePath) {
+    if (path.basename(filePath, '.ejs') === 'simple') {
+        return {
+            title: 'Simple EJS Test',
+            heading: 'Hello from EJS',
+            message: 'This is a simple template test',
+            timestamp: '2025-11-18',
+        };
+    }
+    return {};
+}
+
+// A method-AWARE render: it only produces a body on GET. This is a common
+// real-world pattern (operators guard render work behind a GET check) and is
+// exactly what exposed the bug — on HEAD it never set ctx.body, so the status
+// stayed at Koa's default 404. This render is what makes the regression real:
+// with a naive render the test would pass even without the fix, because Koa
+// strips the body of a 200 GET response for HEAD on its own.
+const methodAwareRender = async (ctx, next, filePath) => {
+    if (ctx.method !== 'GET') return;
+    const tpl = await fs.promises.readFile(filePath, 'utf-8');
+    ctx.type = 'text/html';
+    ctx.body = ejs.render(tpl, templateData(filePath));
+};
+
+// A method-AGNOSTIC render: sets the body regardless of method. Proves the fix
+// does not regress renders that already worked.
+const naiveRender = async (ctx, next, filePath) => {
+    const tpl = await fs.promises.readFile(filePath, 'utf-8');
+    ctx.type = 'text/html';
+    ctx.body = ejs.render(tpl, templateData(filePath));
+};
+
+function buildServer(render) {
+    const app = new Koa();
+    app.use(
+        koaClassicServer(ROOT, {
+            method: ['GET', 'HEAD'],
+            index: ['index.html', 'index.ejs'],
+            dirListing: { enabled: true },
+            template: { ext: ['ejs'], render },
+        })
+    );
+    return app.listen();
+}
+
+// Asserts the HEAD response for `urlPath` matches the corresponding GET in status,
+// Content-Type and Content-Length, and that HEAD carries no body.
+async function expectHeadMatchesGet(request, urlPath, expectedStatus) {
+    const get = await request.get(urlPath);
+    const head = await request.head(urlPath);
+
+    expect(get.status).toBe(expectedStatus);
+    expect(head.status).toBe(expectedStatus);
+
+    // Same headers as GET (RFC 9110 §9.3.2)
+    expect(head.headers['content-type']).toBe(get.headers['content-type']);
+    expect(head.headers['content-length']).toBe(get.headers['content-length']);
+    // Content-Length must actually be populated for a body-bearing response
+    expect(head.headers['content-length']).toBeDefined();
+
+    // HEAD must not send a body (supertest surfaces an empty object for HEAD)
+    expect(head.text).toBeFalsy();
+    expect(head.body).toEqual({});
+
+    return { get, head };
+}
+
+describe('HEAD method — template engine routes (method-aware render)', () => {
+    let server;
+    let request;
+    beforeAll(() => { server = buildServer(methodAwareRender); request = supertest(server); });
+    afterAll(() => server.close());
+
+    // The headline bug: a directory whose index is a template (index.ejs as the
+    // index of /ejs-templates/). GET 200, HEAD must also be 200 — not 404.
+    test('HEAD on a directory whose index is a template → 200, matches GET', async () => {
+        const { get } = await expectHeadMatchesGet(request, '/ejs-templates/', 200);
+        // sanity: GET really did render the template
+        expect(get.text).toContain('Test Templates EJS');
+        expect(get.headers['content-type']).toMatch(/text\/html/);
+    });
+
+    test('HEAD on a directly-requested template file → 200, matches GET', async () => {
+        const { get } = await expectHeadMatchesGet(request, '/ejs-templates/simple.ejs', 200);
+        expect(get.text).toContain('Hello from EJS');
+    });
+
+    test('HEAD on a static file → 200, matches GET', async () => {
+        const { head } = await expectHeadMatchesGet(request, '/test.txt', 200);
+        // static branch advertises range support
+        expect(head.headers['accept-ranges']).toBe('bytes');
+    });
+
+    test('HEAD on a listable directory (no index) → 200, matches GET', async () => {
+        const { get } = await expectHeadMatchesGet(request, '/cartella/', 200);
+        expect(get.headers['content-type']).toMatch(/text\/html/);
+    });
+
+    test('HEAD on a non-existent template path → 404, matches GET', async () => {
+        const get = await request.get('/ejs-templates/non-existent.ejs');
+        const head = await request.head('/ejs-templates/non-existent.ejs');
+        expect(get.status).toBe(404);
+        expect(head.status).toBe(404);
+        expect(head.headers['content-type']).toBe(get.headers['content-type']);
+        expect(head.text).toBeFalsy();
+    });
+
+    test('HEAD on a non-existent static path → 404, matches GET', async () => {
+        const get = await request.get('/does-not-exist.txt');
+        const head = await request.head('/does-not-exist.txt');
+        expect(get.status).toBe(404);
+        expect(head.status).toBe(404);
+        expect(head.text).toBeFalsy();
+    });
+});
+
+describe('HEAD method — template engine routes (method-agnostic render, no regression)', () => {
+    let server;
+    let request;
+    beforeAll(() => { server = buildServer(naiveRender); request = supertest(server); });
+    afterAll(() => server.close());
+
+    test('HEAD on template index still matches GET → 200', async () => {
+        await expectHeadMatchesGet(request, '/ejs-templates/', 200);
+    });
+
+    test('HEAD on direct template still matches GET → 200', async () => {
+        await expectHeadMatchesGet(request, '/ejs-templates/simple.ejs', 200);
+    });
+
+    test('HEAD on non-existent template → 404', async () => {
+        const head = await request.head('/ejs-templates/non-existent.ejs');
+        expect(head.status).toBe(404);
+        expect(head.text).toBeFalsy();
+    });
+});

package/docs/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to koa-classic-server will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.1] - 2026-06-10
+
+### 🐛 Bug Fix
+
+#### Fixed `HEAD` on template-engine routes returning 404 (HTTP conformance, RFC 9110 §9.3.2)
+- **Issue**: When `HEAD` was enabled (`method: ['GET', 'HEAD']`), a `GET` on a route served by the template engine (e.g. `index.ejs` as the index of `/`) returned **200**, but a `HEAD` on the same route returned **404**. The static-file branch already handled `HEAD` correctly, and directory listings worked incidentally, so only the template branch was affected.
+- **Root cause**: `loadFile()` calls `tryRenderTemplate()` before the static-serving branch and returns as soon as it reports the request was handled. `tryRenderTemplate()` invoked the operator's `render` callback with the real `ctx.method` and did nothing `HEAD`-specific. A render that does not itself set a body on non-`GET` requests (a common pattern — operators guard render work behind a `GET` check) therefore left `ctx.status` at Koa's default **404** for `HEAD`, even though `GET` rendered normally.
+- **Impact**: MEDIUM — breaks caches, reverse proxies, link-checkers, and uptime monitors that issue `HEAD`. `HEAD` must be identical to `GET` minus the body (same status code and headers).
+- **Fix**: In `tryRenderTemplate()`, a `HEAD` request now runs the render exactly as a `GET` (the method is presented as `GET` for the duration of the render, then restored) so it resolves, validates, and sets `Content-Type` / status identically. The new `stripBodyForHead()` helper then replaces the rendered body with an empty buffer and restores `Content-Length` to the byte length the `GET` body would have had — sending the correct status and headers with no body. The `GET` path and all public options are unchanged; compatible with Koa 2 and Koa 3.
+- **Code**:
+  - `tryRenderTemplate()` — present `ctx.method` as `GET` for the render, restore to `HEAD` and call `stripBodyForHead()` in `finally`
+  - `stripBodyForHead()` — new helper: empty body + restored `Content-Length`, preserving the status and headers the render produced
+
+### 🧪 Testing
+- Added `__tests__/head-method.test.js` (9 tests) covering, with both a method-aware and a method-agnostic render:
+  - `HEAD` on a directory whose index is a template → **200**, status/`Content-Type`/`Content-Length` match `GET`, empty body
+  - `HEAD` on a directly-requested template file → **200**, matches `GET`
+  - `HEAD` on a static file → **200**, matches `GET` (and still advertises `Accept-Ranges`)
+  - `HEAD` on a listable directory (no index) → **200**, matches `GET`
+  - `HEAD` on a non-existent template/static path → **404**, matches `GET`
+- All 556 tests pass across 21 test suites (zero regressions)
+
+### 📦 Package Changes
+- **Version**: `3.0.0` → `3.0.1`
+- **Semver**: Patch version bump (bug fix only, no API changes)
+
 ## [3.0.0] - 2026-05-13
 
 ### 🆕 New Features

package/index.cjs

@@ -198,6 +198,28 @@ function sendTemplateError(ctx, status, html, logMsg, err, logger) {
     ctx.body = html;
 }
 
+// Rewrites an already-rendered response into an RFC 9110 §9.3.2 compliant HEAD
+// response: the status and headers produced by the render are preserved, the
+// body is replaced with an empty buffer (so no content is sent), and
+// Content-Length is restored to the byte length the GET body would have had.
+// Reassigning ctx.body to a non-stream value also makes Koa auto-destroy a
+// previous stream body, so no file descriptor leaks. Stream / non-buffer bodies
+// (uncommon for template renders) carry no Content-Length, matching the static
+// streaming-HEAD branch.
+function stripBodyForHead(ctx) {
+    if (ctx.headerSent) return;       // render already flushed — status/headers are locked
+    const body = ctx.body;
+    if (body == null) return;         // render produced no body (redirect, pass-through, ...) — leave status as-is
+    const hasKnownLength = typeof body === 'string' || Buffer.isBuffer(body);
+    const length = hasKnownLength ? Buffer.byteLength(body) : null;
+    ctx.body = Buffer.alloc(0);
+    if (length !== null) {
+        ctx.set('Content-Length', String(length)); // body setter zeroed it — restore the real length
+    } else {
+        ctx.remove('Content-Length');               // unknown length — omit, like static streaming HEAD
+    }
+}
+
 // Attempts to render the requested file through the user's template engine.
 // Returns true if the request was handled (success, timeout, or error response
 // already written), false if no template applies (caller should continue with
@@ -214,6 +236,16 @@ async function tryRenderTemplate(ctx, next, filePath, rawBuffer, templateOpts, l
     const fileExt = path.extname(filePath).slice(1);
     if (!fileExt || !templateOpts.ext.includes(fileExt)) return false;
 
+    // RFC 9110 §9.3.2: HEAD must mirror GET (same status + headers, no body). The
+    // user's render is run exactly as for GET — by presenting ctx.method as GET for
+    // the duration of the render — so it resolves, validates, and sets Content-Type
+    // / status identically; stripBodyForHead() then discards the body and restores
+    // Content-Length. Without this, a render that early-returns on non-GET never
+    // sets ctx.body, leaving ctx.status at Koa's default 404 for HEAD even though
+    // GET returns 200.
+    const isHeadRequest = ctx.method === 'HEAD';
+    if (isHeadRequest) ctx.method = 'GET';
+
     const controller = new AbortController();
     const onClientClose = () => controller.abort();
     ctx.req.on('close', onClientClose);
@@ -255,6 +287,10 @@ async function tryRenderTemplate(ctx, next, filePath, rawBuffer, templateOpts, l
     } finally {
         if (timer) clearTimeout(timer);
         ctx.req.removeListener('close', onClientClose);
+        if (isHeadRequest) {
+            ctx.method = 'HEAD';
+            stripBodyForHead(ctx);
+        }
     }
 
     return true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koa-classic-server",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "High-performance Koa middleware for serving static files with Apache-like directory listing, HTTP caching, template engine support, and comprehensive security fixes",
   "main": "index.cjs",
   "exports": {