Improvements to sse, etags, compression

kensnyder · kensnyder · commit 79da15183d7c · 2025-01-13T16:06:16.000-07:00
- `c.sse()` to support multi-line messages
- Accommodate Bun 1.1.43 bugfix to HEAD content-length header
- Avoid etags and compression when body is a stream
- Add `maxSize` option to compression middleware (default 2GB)
- Add LRU cache for file-based mime detection
diff --git a/.github/workflows/workflow.yml b/.github/workflows/workflow.yml
@@ -7,7 +7,7 @@ jobs:
     strategy:
       matrix:
         package: [bunshine, connect-to-fetch]
-        bun-version: [1.1.33, latest]
+        bun-version: [1.1.43, latest]
 
     steps:
       - name: ➡️ Checkout repository
diff --git a/.gitignore b/.gitignore
@@ -4,3 +4,5 @@
 # IDEs
 .idea
 .vscode
+
+vite-examples
diff --git a/packages/bunshine/CHANGELOG.md b/packages/bunshine/CHANGELOG.md
@@ -1,5 +1,13 @@
 # Changelog
 
+## v3.2.3 - Jan 13, 2024
+
+- `c.sse()` to support multi-line messages
+- Accommodate Bun 1.1.43 bugfix to HEAD content-length header
+- Avoid etags and compression when body is a stream
+- Add `maxSize` option to compression middleware (default 2GB)
+- Add LRU cache for file-based mime detection
+
 ## v3.2.2 - Dec 7, 2024
 
 - Fix mime-type on css
diff --git a/packages/bunshine/README.md b/packages/bunshine/README.md
@@ -1524,12 +1524,12 @@ The following decisions are based on scripts in /benchmarks:
   and adds only a tiny overhead.
 - `inner-functions.ts` - Context is a class, not a set of functions in a
   closure, which saves about 3% of time.
-- `compression.ts` - gzip is the default preferred format for the compression
+- `compression-speed.ts` - gzip is the default preferred format for the compression
   middleware. Deflate provides no advantage, and Brotli provides 2-8% additional
   size savings at the cost of 100x as much CPU time as gzip. Brotli takes on
   the order of 100ms to compress 100kb of html, compared to sub-milliseconds
   for gzip.
-- `etags.ts` - etag calculation is very fast. On the order of tens of
+- `etags-speed.ts` - etag calculation is very fast. On the order of tens of
   microseconds for 100kb of html.
 - `lru-matcher.ts` - The default LRU cache size used for the router is 4000.
   Cache sizes of 4000+ are all about 1.4x faster than no cache.
diff --git a/packages/bunshine/benchmarks/compression-speed.ts b/packages/bunshine/benchmarks/compression-speed.ts
@@ -1,6 +1,6 @@
 import { promisify } from 'node:util';
 import { brotliCompress, deflate, gzip } from 'node:zlib';
-import { runBenchmarks } from './runBenchmarks.ts';
+import { runBenchmarks } from './runBenchmarks';
 
 /*
 Conclusion:
diff --git a/packages/bunshine/benchmarks/etags-speed.ts b/packages/bunshine/benchmarks/etags-speed.ts
@@ -1,5 +1,5 @@
-import { defaultEtagsCalculator } from '../src/middleware/etags/etags.ts';
-import { runBenchmarks } from './runBenchmarks.ts';
+import { defaultEtagsCalculator } from '../src/middleware/etags/etags';
+import { runBenchmarks } from './runBenchmarks';
 
 /*
 Conclusions:
@@ -17,6 +17,7 @@ const html = await fetch('https://www.npmjs.com/package/bunshine').then(res =>
 const t1k = html.slice(1000, 2000);
 const t10k = html.slice(1000, 11000);
 const t100k = html.slice(1000, 101000);
+const t100M = t100k.repeat(1024);
 
 async function getResponse(input: string) {
   return new Response(input, {
@@ -40,6 +41,7 @@ await runBenchmarks(
     'etags 1k': () => computeEtags(t1k),
     'etags 10k': () => computeEtags(t10k),
     'etags 100k': () => computeEtags(t100k),
+    'etags 100M': () => computeEtags(t100M),
   },
   { time: 3000 }
 );
diff --git a/packages/bunshine/bun.lockb b/packages/bunshine/bun.lockb
diff --git a/packages/bunshine/package.json b/packages/bunshine/package.json
@@ -1,10 +1,13 @@
 {
   "name": "bunshine",
-  "version": "3.2.2",
+  "version": "3.2.3",
   "module": "index.ts",
   "type": "module",
   "main": "index.ts",
   "types": "dist/index.d.ts",
+  "engines": {
+    "bun": ">=1.1.33"
+  },
   "scripts": {
     "test-watch": "bun test --watch",
     "coverage": "bun test --coverage",
@@ -49,13 +52,14 @@
     "lru-cache": "^11.0.2"
   },
   "devDependencies": {
-    "@types/bun": "^1.1.14",
+    "@types/bun": "^1.1.16",
+    "@types/node": "^22.10.6",
     "eventsource": "^2.0.2",
-    "prettier": "^3.4.1",
+    "prettier": "^3.4.2",
     "prettier-plugin-organize-imports": "^4.1.0",
     "redos-detector": "^5.1.3",
-    "tinybench": "^3.0.6",
-    "type-fest": "^4.29.0",
-    "typescript": "^5.7.2"
+    "tinybench": "^3.1.0",
+    "type-fest": "^4.32.0",
+    "typescript": "^5.7.3"
   }
 }
diff --git a/packages/bunshine/src/HttpRouter/HttpRouter.spec.ts b/packages/bunshine/src/HttpRouter/HttpRouter.spec.ts
@@ -340,7 +340,7 @@ describe('HttpRouter', () => {
       app.head('/hi', ({ url }) => {
         const name = url.searchParams.get('name');
         return new Response(null, {
-          status: 204,
+          status: 200,
           headers: {
             'Content-length': '0',
             Message: `Hi ${name}`,
@@ -350,7 +350,7 @@ describe('HttpRouter', () => {
       const resp = await fetch(`${server.url}/hi?name=Bob`, {
         method: 'HEAD',
       });
-      expect(resp.status).toBe(204);
+      expect(resp.status).toBe(200);
       expect(resp.headers.get('Message')).toBe('Hi Bob');
     });
     it('should handle POST', async () => {
diff --git a/packages/bunshine/src/middleware/compression/compression.ts b/packages/bunshine/src/middleware/compression/compression.ts
@@ -36,6 +36,8 @@ export function compression(
   return async (context, next) => {
     const resp = await next();
     if (
+      // no compression for streams such as text/stream
+      /stream/i.test(resp.headers.get('Content-Type') || '') ||
       context.request.method === 'HEAD' ||
       !isCompressibleMime(resp.headers.get('Content-Type'))
     ) {
diff --git a/packages/bunshine/src/middleware/etags/etags.spec.ts b/packages/bunshine/src/middleware/etags/etags.spec.ts
@@ -23,7 +23,7 @@ describe('etags middleware', () => {
       },
     });
     const text = await resp.text();
-    expect(resp.status).toBe(304);
+    expect(resp.status).toBe(204);
     expect(resp.headers.get('Etag')).toBe(helloWorldEtag);
     expect(text).toBe('');
   });
@@ -35,7 +35,7 @@ describe('etags middleware', () => {
       },
     });
     const text = await resp.text();
-    expect(resp.status).toBe(304);
+    expect(resp.status).toBe(204);
     expect(resp.headers.get('Etag')).toBe(helloWorldEtag);
     expect(text).toBe('');
   });
@@ -48,9 +48,9 @@ describe('etags middleware', () => {
       },
     });
     const text = await resp.text();
-    expect(resp.status).toBe(200);
+    expect(resp.status).toBe(204);
     expect(resp.headers.get('Etag')).toBe(helloWorldEtag);
-    expect(text).toBe('Hello world');
+    expect(text).toBe('');
   });
   it('should not generate for non-200', async () => {
     app.get('/', c => c.text('Hello world', { status: 404 }));
@@ -73,8 +73,8 @@ describe('etags middleware', () => {
       },
     });
     const text = await resp.text();
-    expect(resp.status).toBe(200);
-    expect(resp.headers.has('Etag')).toBe(false);
-    expect(text).toBe('Hello world');
+    expect(resp.status).toBe(412);
+    expect(resp.headers.has('Etag')).toBe(true);
+    expect(text).toBe('');
   });
 });
diff --git a/packages/bunshine/src/middleware/etags/etags.ts b/packages/bunshine/src/middleware/etags/etags.ts
@@ -9,41 +9,98 @@ export type EtagHashCalculator = (
 
 export type EtagOptions = {
   calculator?: EtagHashCalculator;
+  maxSize?: number;
 };
 
 export function etags({
   calculator = defaultEtagsCalculator,
+  maxSize = 2 * 1024 * 1024 * 1024, // 2GB
 }: EtagOptions = {}): Middleware {
   return async (context: Context, next: NextFunction) => {
     const resp = await next();
-    if (context.request.method !== 'GET' || resp.status !== 200) {
-      // Only use Etags for successful GET requests
+    if (!_shouldGenerateEtag(resp)) {
       return resp;
     }
-    const ifNoneMatch = context.request.headers.get('if-none-match');
     const { buffer, hash } = await calculator(context, resp);
     const etag = `"${hash}"`;
     resp.headers.set('Etag', etag);
-    if (ifNoneMatch && _includesEtag(ifNoneMatch, etag)) {
+    if (_matches(context.request.headers, etag)) {
+      resp.headers.set('Vary', 'Content-Encoding');
+      const status = ['GET', 'HEAD'].includes(context.request.method)
+        ? 204 // No content
+        : 412; // Precondition failed
       return new Response('', {
         headers: resp.headers,
-        status: 304,
-        statusText: '',
+        status,
       });
     }
     return new Response(buffer, {
       headers: resp.headers,
       status: 200,
-      statusText: '',
     });
   };
 }
 
-function _includesEtag(ifNoneMatch: string, etag: string) {
-  const matches = ifNoneMatch.split(',').map(s => s.trim());
+function _matches(headers: Headers, etag: string) {
+  const ifNoneMatch = headers.get('if-none-match');
+  if (ifNoneMatch) {
+    return (
+      !_includesEtag(ifNoneMatch, etag) || !_includesEtag(ifNoneMatch, '*')
+    );
+  }
+  const ifMatch = headers.get('if-match');
+  if (ifMatch) {
+    return _includesEtag(ifMatch, etag) || _includesEtag(ifMatch, '*');
+  }
+  return false;
+}
+
+function _includesEtag(header: string, etag: string) {
+  const matches = header.split(',').map(s => s.trim());
   return matches.includes(etag);
 }
 
+function _shouldGenerateEtag(response: Response) {
+  // Ensure the response object is valid
+  if (!(response instanceof Response)) {
+    return false;
+  }
+
+  // List of status codes where ETags generally make sense
+  // Technically 404 could be included, but the application should use custom logic
+  const validStatusCodes = [200, 201, 203, 204, 206, /*404,*/ 410];
+
+  // Check if the response status code is in the valid list
+  if (!validStatusCodes.includes(response.status)) {
+    return false;
+  }
+
+  // Check if the response is cacheable
+  const cacheControl = response.headers.get('Cache-Control');
+  if (cacheControl && /no-store/i.test(cacheControl)) {
+    return false; // Do not generate ETag for non-cacheable responses
+  }
+
+  // Check if the response method supports ETag generation
+  const method = response.headers.get('X-Request-Method') || 'GET'; // Custom header to track the request method
+  const methodsThatSupportEtag = ['GET', 'HEAD', 'PUT', 'POST', 'PATCH'];
+  if (!methodsThatSupportEtag.includes(method.toUpperCase())) {
+    return false;
+  }
+
+  // Check if the response has a body or meaningful representation
+  const contentLength = response.headers.get('Content-Length');
+  if (
+    response.status === 204 ||
+    (contentLength && parseInt(contentLength, 10) === 0)
+  ) {
+    return false; // No body, no ETag
+  }
+
+  // If all conditions are met, it makes sense to generate an ETag
+  return true;
+}
+
 export async function defaultEtagsCalculator(_: Context, resp: Response) {
   const buffer = await resp.arrayBuffer();
   if (buffer.byteLength === 0) {
diff --git a/packages/bunshine/src/middleware/serveFiles/serveFiles.spec.ts b/packages/bunshine/src/middleware/serveFiles/serveFiles.spec.ts
@@ -46,7 +46,7 @@ describe('serveFiles middleware', () => {
       });
       const text = await resp.text();
       expect(text).toBe('');
-      expect(resp.headers.get('content-length')).toBe('0');
+      expect(resp.headers.get('content-length')).toBe('22'); // Fixed in Bun 1.1.43
       expect(resp.status).toBe(200);
     });
     it('should 404 if file does not exist', async () => {
diff --git a/packages/bunshine/src/responseFactories/file/file-io.ts b/packages/bunshine/src/responseFactories/file/file-io.ts
@@ -1,12 +1,14 @@
 import { BunFile } from 'bun';
 import { fileTypeFromBuffer } from 'file-type';
 import fs from 'fs/promises';
+import { LRUCache } from 'lru-cache';
 import path from 'node:path';
 
 export type FileLike = string | Blob | Uint8Array | ArrayBuffer;
 
 const defaultMimeType = 'application/octet-stream';
 const detectMimeChunkSize = 4100; // from file-type reasonableDetectionSizeInBytes
+const mimeCache = new LRUCache<string, string>({ max: 10_000 });
 
 export function isFileLike(file: any): file is FileLike {
   return (
@@ -35,7 +37,7 @@ export async function getBufferMime(arrayBuffer: ArrayBuffer | Uint8Array) {
 
 export async function getFileMime(
   file: FileLike,
-  maybeBuffer?: ArrayBuffer | Uint8Array
+  maybeEntireFile?: ArrayBuffer | Uint8Array
 ) {
   const filename = getFileBaseName(file);
   if (filename) {
@@ -48,8 +50,8 @@ export async function getFileMime(
   }
   if (typeof file === 'string') {
     return (
-      (maybeBuffer
-        ? await getBufferMime(maybeBuffer)
+      (maybeEntireFile
+        ? await getBufferMime(maybeEntireFile)
         : await getChunkMime(file)) || defaultMimeType
     );
   }
@@ -61,8 +63,14 @@ export async function getFileMime(
 }
 
 export async function getChunkMime(path: string) {
-  const chunk = await readChunk(path, 0, detectMimeChunkSize);
-  return chunk ? getBufferMime(chunk) : null;
+  const lastModified = Bun.file(path).lastModified;
+  const key = `${path}-${lastModified}`;
+  if (!mimeCache.has(key)) {
+    const chunk = await readChunk(path, 0, detectMimeChunkSize);
+    const mime = chunk ? await getBufferMime(chunk) : '';
+    mimeCache.set(key, mime);
+  }
+  return mimeCache.get(key);
 }
 
 export function getFileBaseName(file: FileLike) {
diff --git a/packages/bunshine/src/responseFactories/file/file.spec.ts b/packages/bunshine/src/responseFactories/file/file.spec.ts

-Original file line number
+Diff line change
 # IDEs
 .idea
 .vscode
++
 +vite-examples