koa-classic-server 3.0.1 → 3.1.0

package/.github/workflows/npm-publish.yml

@@ -1,98 +0,0 @@
-# This workflow will run tests using node and then publish a package to npm when a release is published
-# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
-
-name: Publish to npm
-
-on:
-  release:
-    types: [published]
-
-# Prevent multiple concurrent publish workflows
-concurrency:
-  group: npm-publish-${{ github.ref }}
-  cancel-in-progress: false
-
-# Set permissions for the workflow
-permissions:
-  contents: read
-  id-token: write  # Required for npm provenance
-
-jobs:
-  build:
-    name: Build and Test
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: 'npm'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Run tests
-        run: npm test --if-present
-
-      - name: Build package
-        run: npm run build --if-present
-
-      - name: Cache build artifacts
-        uses: actions/cache/save@v4
-        with:
-          path: |
-            node_modules
-            dist
-            build
-          key: build-${{ github.sha }}
-
-  publish-npm:
-    name: Publish to npm Registry
-    needs: build
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          registry-url: https://registry.npmjs.org/
-          cache: 'npm'
-
-      - name: Restore build artifacts
-        uses: actions/cache/restore@v4
-        with:
-          path: |
-            node_modules
-            dist
-            build
-          key: build-${{ github.sha }}
-
-      - name: Verify package version matches release tag
-        run: |
-          PACKAGE_VERSION=$(node -p "require('./package.json').version")
-          RELEASE_TAG=${GITHUB_REF#refs/tags/}
-          # Remove 'v' prefix if present in tag
-          RELEASE_VERSION=${RELEASE_TAG#v}
-
-          echo "Package version: $PACKAGE_VERSION"
-          echo "Release version: $RELEASE_VERSION"
-
-          if [ "$PACKAGE_VERSION" != "$RELEASE_VERSION" ]; then
-            echo "Error: Package version ($PACKAGE_VERSION) does not match release tag ($RELEASE_VERSION)"
-            exit 1
-          fi
-
-      - name: Publish to npm with provenance
-        run: npm publish --provenance --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CLAUDE.md

@@ -1,101 +0,0 @@
-# CLAUDE.md
-
-Guidance for AI coding assistants working on **koa-classic-server**.
-
----
-
-## Project orientation
-
-koa-classic-server is a Koa middleware that serves static files from disk over HTTP, with Apache2-like directory listings, optional template-engine integration, and server-side compressed cache. It is a *classic* file server — its primary job is to take an HTTP request and respond with the file at the requested path, or with a directory listing if a directory is requested without an index file.
-
-The project is **not** a framework, not a router, not a CMS. It is intentionally focused.
-
----
-
-## Design philosophy: HTTP file server first
-
-The middleware's primary contract with the operator is:
-
-> **"If a file exists in the served directory, `GET` on its path returns it. If a directory is requested without an index file, the listing shows every visible entry."**
-
-This contract drives every default. The defaults are picked so that:
-
-- Asking for any file under `rootDir` returns it (no silent 404 unless the file truly does not exist).
-- Asking for a directory without an index file returns the listing of that directory.
-- The listing includes every visible entry.
-- No request is silently restricted by some default policy the operator did not ask for.
-
-In short: **the operator's directory is the source of truth. The middleware does not second-guess it.**
-
-### What this implies for defaults
-
-- **Dot-files are visible by default.** Files named `.env`, `.htaccess`, `.well-known/...` are served if requested. If the operator does not want this, they hide them via the `hidden.dotFiles` namespace.
-- **No artificial small-entry limit on directory listings.** If a directory has 5,000 files, the listing shows 5,000 entries. The middleware does NOT decide that "5,000 is too many".
-- **No forced pagination on tiny directories.** Pagination kicks in only when the listing exceeds `dirListing.entriesPerPage`. The default is high enough that most directories render in a single page.
-
-### What counts as a "safety net" (acceptable)
-
-Some defaults are NOT restrictions on the served content — they are guards against catastrophic failure modes of the **process itself**:
-
-| Default | Protects against |
-|---|---|
-| `template.renderTimeout: 30000` | Hung template render blocking the event loop indefinitely |
-| `serverCache.compressedFile.maxSize: 100 MB` | RAM growing unbounded in the compressed-response cache |
-| `dirListing.maxEntries: 100000` | OOM at `readdir()` allocation time on accidentally-huge directories (broken log rotation, mistakenly mounted FS) |
-
-These are deliberate exceptions because they protect the process from itself, not the served content. The distinction:
-
-- A **safety net** prevents the server from crashing.
-- A **restriction** prevents the operator's intent from being respected.
-
-### What restrictions look like (and would NOT be acceptable as defaults)
-
-- Hiding files by name pattern (`.env`, `.git`, `secret*`) without the operator opting in.
-- Refusing to serve files larger than N bytes by default.
-- Auto-disabling listings on "too many" entries.
-- Forcing small-default pagination on the listing UI.
-
-When proposing a new feature, ask: *"does this change the default observable behavior of `GET /path/to/file` or `GET /some/dir/`?"* If yes, it is a restriction — make it opt-in.
-
-> Note: `method: ['GET']` IS technically restrictive (rejects HEAD, POST, etc. by default). It is kept as-is because it has been the v2 default since forever and the migration cost is not worth the philosophical purity. Documented as a known imperfection.
-
----
-
-## Consequences for future changes
-
-- **New options should default to "transparent / pass-through".** A new feature that changes default observable behavior must be defended in the PR description: why is this a safety net and not a restriction?
-
-- **Security hardening lives in documentation, not in defaults.** When you find a hardening opportunity, the first instinct should be to add a row to the *Security Checklist* in `README.md` and `docs/DOCUMENTATION.md`, not to change a default. Defaults serve operators; the checklist guides them when they need to harden.
-
-- **Breaking-change cost is real.** This middleware has v2-era stable options. Renaming or changing default behavior of stable options breaks every operator on upgrade. Justify breaks by **structural necessity**, not by aesthetic preference. Renaming `showDirContents` → `dirListing.enabled` was justified because it was needed to group related listing options under a namespace. Renaming `hideExtension.redirect` → `redirectStatusCode` would be aesthetic only and was therefore declined.
-
-- **Aliases for v2-stable names are acceptable** to soften transitions, with a one-time deprecation warning via `_logger.warn(...)` (see the `showDirContents` alias for the canonical pattern).
-
-- **Throw guards for V3-alpha-only options** are acceptable as hard breaks (no v2 user has them; alpha-testers accept breakage).
-
----
-
-## Key references
-
-- **`README.md`** — user-facing entry point. Contains Security Checklist and Suggested Security Configuration sections.
-- **`docs/DOCUMENTATION.md`** — full API reference and Best Practices guide.
-- **`docs/CHANGELOG.md`** — version history; breaking changes documented under *⚠️ Breaking Changes*.
-- **`docs/security_improvement_for_V3.md`** — audit roadmap for v3 security improvements (implemented + Future Work under `[F-1]`).
-- **`__tests__/`** — 543+ tests asserting behavior contracts. Run with `npm test`.
-
----
-
-## Working conventions
-
-- All defaults are documented in the JSDoc-style block at the top of the factory function in `index.cjs` (~line 480). When you change a default, update that block.
-- Validation errors throw at factory time with a helpful migration hint. See existing throw guards for `cacheMaxAge`, `enableCaching`, `maxDirEntries`, `pageSize`, `compression.minSize`.
-- Tests use `supertest` over a `Koa` app instantiated per `describe` block.
-- The CSP hash for the directory-listing inline CSS is computed once at module load (`_listingCssHash`) — editing the listing CSS automatically refreshes the hash. Tests that asserted the hash must compute it from the actual `<style>` block in the response, not hardcode it.
-- Once-per-process warnings use a module-level boolean flag (see `_showDirContentsDeprecationWarned` for the canonical pattern).
-- Logger calls use `warnPayload(_logger, msg)` so that structured loggers (pino/winston) receive plain text and `console` receives ANSI colors.
-
----
-
-## When in doubt
-
-Re-read the **Design philosophy** section above. If the change you are about to propose would make `GET /some/file` behave differently than the operator placing that file would expect, you are probably violating the philosophy. Either redesign the change as opt-in, or document the rationale explicitly in the PR.

package/__tests__/benchmark-results-baseline-v1.2.0.txt

@@ -1,354 +0,0 @@
-
-> koa-classic-server@1.2.0 test:performance
-> jest __tests__/performance.test.js --runInBand
-
-  console.log
-    
-    📊 Small File (1KB) Benchmark:
-
-      at Object.log (__tests__/performance.test.js:90:21)
-
-  console.log
-       Average: 2.93ms
-
-      at Object.log (__tests__/performance.test.js:91:21)
-
-  console.log
-       Median:  2.54ms
-
-      at Object.log (__tests__/performance.test.js:92:21)
-
-  console.log
-       Min:     1.99ms
-
-      at Object.log (__tests__/performance.test.js:93:21)
-
-  console.log
-       Max:     26.87ms
-
-      at Object.log (__tests__/performance.test.js:94:21)
-
-  console.log
-    
-    📊 Medium File (100KB) Benchmark:
-
-      at Object.log (__tests__/performance.test.js:109:21)
-
-  console.log
-       Average: 3.59ms
-
-      at Object.log (__tests__/performance.test.js:110:21)
-
-  console.log
-       Median:  3.51ms
-
-      at Object.log (__tests__/performance.test.js:111:21)
-
-  console.log
-       Min:     2.46ms
-
-      at Object.log (__tests__/performance.test.js:112:21)
-
-  console.log
-       Max:     8.36ms
-
-      at Object.log (__tests__/performance.test.js:113:21)
-
-  console.log
-    
-    📊 Large File (1MB) Benchmark:
-
-      at Object.log (__tests__/performance.test.js:128:21)
-
-  console.log
-       Average: 9.03ms
-
-      at Object.log (__tests__/performance.test.js:129:21)
-
-  console.log
-       Median:  8.35ms
-
-      at Object.log (__tests__/performance.test.js:130:21)
-
-  console.log
-       Min:     5.46ms
-
-      at Object.log (__tests__/performance.test.js:131:21)
-
-  console.log
-       Max:     13.81ms
-
-      at Object.log (__tests__/performance.test.js:132:21)
-
-  console.log
-    
-    📊 Small Directory (100 files) Benchmark:
-
-      at Object.log (__tests__/performance.test.js:150:21)
-
-  console.log
-       Average: 2.65ms
-
-      at Object.log (__tests__/performance.test.js:151:21)
-
-  console.log
-       Median:  2.54ms
-
-      at Object.log (__tests__/performance.test.js:152:21)
-
-  console.log
-       Min:     2.22ms
-
-      at Object.log (__tests__/performance.test.js:153:21)
-
-  console.log
-       Max:     4.69ms
-
-      at Object.log (__tests__/performance.test.js:154:21)
-
-  console.log
-    
-    📊 Large Directory (1,000 files) Benchmark:
-
-      at Object.log (__tests__/performance.test.js:168:21)
-
-  console.log
-       Average: 9.23ms
-
-      at Object.log (__tests__/performance.test.js:169:21)
-
-  console.log
-       Median:  9.14ms
-
-      at Object.log (__tests__/performance.test.js:170:21)
-
-  console.log
-       Min:     8.26ms
-
-      at Object.log (__tests__/performance.test.js:171:21)
-
-  console.log
-       Max:     11.64ms
-
-      at Object.log (__tests__/performance.test.js:172:21)
-
-  console.log
-       ⚠️  WARNING: This will be MUCH faster after async optimization
-
-      at Object.log (__tests__/performance.test.js:175:21)
-
-  console.log
-    
-    📊 Very Large Directory (10,000 files) Benchmark:
-
-      at Object.log (__tests__/performance.test.js:189:21)
-
-  console.log
-       Average: 102.37ms
-
-      at Object.log (__tests__/performance.test.js:190:21)
-
-  console.log
-       Median:  95.13ms
-
-      at Object.log (__tests__/performance.test.js:191:21)
-
-  console.log
-       Min:     90.91ms
-
-      at Object.log (__tests__/performance.test.js:192:21)
-
-  console.log
-       Max:     120.85ms
-
-      at Object.log (__tests__/performance.test.js:193:21)
-
-  console.log
-       ⚠️  WARNING: Event loop BLOCKED during this operation!
-
-      at Object.log (__tests__/performance.test.js:194:21)
-
-  console.log
-       ⚠️  Expected to drop to ~30.71ms after optimization
-
-      at Object.log (__tests__/performance.test.js:195:21)
-
-  console.log
-    
-    📊 10 Concurrent Small Files:
-
-      at Object.log (__tests__/performance.test.js:212:21)
-
-  console.log
-       Total time: 15.50ms
-
-      at Object.log (__tests__/performance.test.js:213:21)
-
-  console.log
-       Avg per request: 1.55ms
-
-      at Object.log (__tests__/performance.test.js:214:21)
-
-  console.log
-    
-    📊 5 Concurrent Directory Listings (100 files):
-
-      at Object.log (__tests__/performance.test.js:231:21)
-
-  console.log
-       Total time: 11.30ms
-
-      at Object.log (__tests__/performance.test.js:232:21)
-
-  console.log
-       Avg per request: 2.26ms
-
-      at Object.log (__tests__/performance.test.js:233:21)
-
-  console.log
-       ⚠️  With current sync code, these run SEQUENTIALLY
-
-      at Object.log (__tests__/performance.test.js:234:21)
-
-  console.log
-       ⚠️  After async optimization, will run in PARALLEL
-
-      at Object.log (__tests__/performance.test.js:235:21)
-
-  console.log
-    
-    📊 404 Not Found Benchmark:
-
-      at Object.log (__tests__/performance.test.js:252:21)
-
-  console.log
-       Average: 1.26ms
-
-      at Object.log (__tests__/performance.test.js:253:21)
-
-  console.log
-       Median:  1.24ms
-
-      at Object.log (__tests__/performance.test.js:254:21)
-
-  console.log
-       Min:     1.05ms
-
-      at Object.log (__tests__/performance.test.js:255:21)
-
-  console.log
-       Max:     2.17ms
-
-      at Object.log (__tests__/performance.test.js:256:21)
-
-  console.log
-    
-    📊 Memory Usage (10,000 files directory):
-
-      at Object.log (__tests__/performance.test.js:278:21)
-
-  console.log
-       Heap used increase: 1.16 MB
-
-      at Object.log (__tests__/performance.test.js:279:21)
-
-  console.log
-       External increase: 2.57 MB
-
-      at Object.log (__tests__/performance.test.js:280:21)
-
-  console.log
-       Response size: 1.29 MB
-
-      at Object.log (__tests__/performance.test.js:281:21)
-
-  console.log
-       ⚠️  Expected to reduce by ~30-40% after optimization
-
-      at Object.log (__tests__/performance.test.js:282:21)
-
-  console.log
-    
-    ======================================================================
-
-      at Object.log (__tests__/performance.test.js:289:13)
-
-  console.log
-    📋 BASELINE BENCHMARK SUMMARY
-
-      at Object.log (__tests__/performance.test.js:290:13)
-
-  console.log
-    ======================================================================
-
-      at Object.log (__tests__/performance.test.js:291:13)
-
-  console.log
-    
-    These results represent the CURRENT performance (v1.2.0)
-
-      at Object.log (__tests__/performance.test.js:292:13)
-
-  console.log
-    After implementing optimizations, run this test again to see improvements.
-
-      at Object.log (__tests__/performance.test.js:293:13)
-
-  console.log
-    Expected improvements after optimization:
-
-      at Object.log (__tests__/performance.test.js:294:13)
-
-  console.log
-      ✓ Small files:        10-20% faster (async operations)
-
-      at Object.log (__tests__/performance.test.js:295:13)
-
-  console.log
-      ✓ Large directories:  50-70% faster (async + array join)
-
-      at Object.log (__tests__/performance.test.js:296:13)
-
-  console.log
-      ✓ Concurrent requests: 5-10x faster (non-blocking event loop)
-
-      at Object.log (__tests__/performance.test.js:297:13)
-
-  console.log
-      ✓ Memory usage:       30-40% reduction (array join vs concatenation)
-
-      at Object.log (__tests__/performance.test.js:298:13)
-
-  console.log
-      ✓ With HTTP caching:  80-95% faster (304 responses)
-
-      at Object.log (__tests__/performance.test.js:299:13)
-
-  console.log
-    ======================================================================
-
-      at Object.log (__tests__/performance.test.js:300:13)
-
-PASS __tests__/performance.test.js
-  Performance Benchmarks - BASELINE (v1.2.0)
-    File Serving Performance
-      ✓ Benchmark: Small file (1KB) - 100 iterations (318 ms)
-      ✓ Benchmark: Medium file (100KB) - 50 iterations (184 ms)
-      ✓ Benchmark: Large file (1MB) - 20 iterations (183 ms)
-    Directory Listing Performance
-      ✓ Benchmark: Small directory (100 files) - 50 iterations (135 ms)
-      ✓ Benchmark: Large directory (1,000 files) - 20 iterations (188 ms)
-      ✓ Benchmark: Very large directory (10,000 files) - 5 iterations (515 ms)
-    Concurrent Request Performance
-      ✓ Benchmark: 10 concurrent small file requests (18 ms)
-      ✓ Benchmark: 5 concurrent directory listings (100 files each) (14 ms)
-    404 Not Found Performance
-      ✓ Benchmark: Non-existent file - 50 iterations (66 ms)
-    Memory Usage (Informational)
-      ✓ Memory usage during large directory listing (88 ms)
-
-Test Suites: 1 passed, 1 total
-Tests:       10 passed, 10 total
-Snapshots:   0 total
-Time:        3.227 s, estimated 4 s
-Ran all test suites matching /__tests__\/performance.test.js/i.