@timber-js/app 0.1.44 → 0.1.45

package/dist/server/compress.d.ts

@@ -6,14 +6,19 @@
 export declare const COMPRESSIBLE_TYPES: Set<string>;
 /**
  * Parse Accept-Encoding and return the best supported encoding.
- * Prefers brotli (br) over gzip. Returns null if no supported encoding.
+ * Returns 'gzip' if the client accepts it, null otherwise.
  *
- * We always prefer brotli regardless of quality values because:
- * 1. Brotli achieves better compression ratios than gzip
- * 2. All modern browsers that send br in Accept-Encoding support it well
- * 3. Respecting q-values for br vs gzip adds complexity with no real benefit
+ * Brotli (br) is intentionally not handled at the application level.
+ * At the streaming-friendly quality levels (0–4), brotli's compression
+ * ratio advantage over gzip is marginal, and node:zlib's brotli transform
+ * buffers output internally — turning smooth streaming responses into
+ * large infrequent bursts. Brotli's real wins come from offline/static
+ * compression at higher quality levels (5–11), which CDNs and reverse
+ * proxies (Cloudflare, nginx, Caddy) apply on cached responses.
+ *
+ * See design/25-production-deployments.md.
  */
-export declare function negotiateEncoding(acceptEncoding: string): 'br' | 'gzip' | null;
+export declare function negotiateEncoding(acceptEncoding: string): 'gzip' | null;
 /**
  * Determine if a response should be compressed.
  *

package/dist/server/compress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compress.d.ts","sourceRoot":"","sources":["../../src/server/compress.ts"],"names":[],"mappings":"AAaA;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,aAc7B,CAAC;AASH;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAU9E;AAID;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAmB1D;AAID;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAmC/E"}
+{"version":3,"file":"compress.d.ts","sourceRoot":"","sources":["../../src/server/compress.ts"],"names":[],"mappings":"AAYA;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,aAc7B,CAAC;AASH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASvE;AAID;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAmB1D;AAID;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAiC/E"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.1.44",
+  "version": "0.1.45",
   "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/adapters/compress-module.ts

@@ -4,7 +4,9 @@
 // written to the build output during adapter buildOutput(). It's imported
 // by the Nitro entry and preview server at runtime.
 //
-// Uses CompressionStream (Web API) for gzip and node:zlib for brotli.
+// Uses CompressionStream (Web API) for gzip. Brotli is left to CDNs/reverse
+// proxies — at streaming quality levels its ratio advantage is marginal and
+// node:zlib buffers output internally, breaking streaming.
 // Cloudflare Workers don't need this — the edge auto-compresses.
 //
 // See design/25-production-deployments.md.
@@ -20,10 +22,9 @@
 export function generateCompressModule(): string {
   return `// Generated by @timber-js/app — response compression for self-hosted deployments.
 // Do not edit — this file is regenerated on each build.
-// Uses CompressionStream (Web API) for gzip, node:zlib for brotli.
-
-import { createBrotliCompress, constants as zlibConstants } from 'node:zlib';
-import { Readable } from 'node:stream';
+// Uses CompressionStream (Web API) for gzip. Brotli is left to CDNs/reverse
+// proxies — at streaming quality levels its ratio advantage is marginal and
+// node:zlib buffers output internally, breaking streaming.
 
 const COMPRESSIBLE_TYPES = new Set([
   'text/html', 'text/css', 'text/plain', 'text/xml', 'text/javascript',
@@ -37,7 +38,10 @@ const NO_COMPRESS_STATUSES = new Set([204, 304]);
 function negotiateEncoding(acceptEncoding) {
   if (!acceptEncoding) return null;
   const tokens = acceptEncoding.split(',').map(s => s.split(';')[0].trim().toLowerCase());
-  if (tokens.includes('br')) return 'br';
+  // Brotli (br) is intentionally not handled at the application level.
+  // At streaming-friendly quality levels (0-4), brotli's ratio advantage over
+  // gzip is marginal, and node:zlib's brotli transform buffers output internally.
+  // CDNs/reverse proxies apply brotli at higher quality levels on cached responses.
   if (tokens.includes('gzip')) return 'gzip';
   return null;
 }
@@ -57,36 +61,12 @@ function compressWithGzip(body) {
   return body.pipeThrough(new CompressionStream('gzip'));
 }
 
-function compressWithBrotli(body) {
-  const brotli = createBrotliCompress({
-    params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 4 },
-  });
-  const reader = body.getReader();
-  const pump = async () => {
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) { brotli.end(); return; }
-        if (!brotli.write(value)) {
-          await new Promise(resolve => brotli.once('drain', resolve));
-        }
-      }
-    } catch (err) {
-      brotli.destroy(err instanceof Error ? err : new Error(String(err)));
-    }
-  };
-  pump();
-  return Readable.toWeb(brotli);
-}
-
 export function compressResponse(request, response) {
   if (!shouldCompress(response)) return response;
   const acceptEncoding = request.headers.get('Accept-Encoding') || '';
   const encoding = negotiateEncoding(acceptEncoding);
   if (!encoding) return response;
-  const compressedBody = encoding === 'br'
-    ? compressWithBrotli(response.body)
-    : compressWithGzip(response.body);
+  const compressedBody = compressWithGzip(response.body);
   const headers = new Headers(response.headers);
   headers.set('Content-Encoding', encoding);
   headers.delete('Content-Length');

package/src/server/compress.ts

@@ -1,14 +1,13 @@
 // Response compression for self-hosted deployments (dev server, Nitro preview).
 //
-// Uses CompressionStream (Web Platform API) for gzip and node:zlib for
-// brotli (CompressionStream doesn't support brotli). Cloudflare Workers
-// auto-compress at the edge — this module is only used on Node.js/Bun.
+// Uses CompressionStream (Web Platform API) for gzip. Brotli is intentionally
+// left to CDNs and reverse proxies — at streaming-friendly quality levels its
+// ratio advantage is marginal, and node:zlib's brotli transform buffers output
+// internally, breaking streaming. Cloudflare Workers auto-compress at the edge —
+// this module is only used on Node.js/Bun.
 //
 // See design/25-production-deployments.md.
 
-import { createBrotliCompress, constants as zlibConstants } from 'node:zlib';
-import { Readable } from 'node:stream';
-
 // ─── Constants ────────────────────────────────────────────────────────────
 
 /**
@@ -41,21 +40,25 @@ const NO_COMPRESS_STATUSES = new Set([204, 304]);
 
 /**
  * Parse Accept-Encoding and return the best supported encoding.
- * Prefers brotli (br) over gzip. Returns null if no supported encoding.
+ * Returns 'gzip' if the client accepts it, null otherwise.
+ *
+ * Brotli (br) is intentionally not handled at the application level.
+ * At the streaming-friendly quality levels (0–4), brotli's compression
+ * ratio advantage over gzip is marginal, and node:zlib's brotli transform
+ * buffers output internally — turning smooth streaming responses into
+ * large infrequent bursts. Brotli's real wins come from offline/static
+ * compression at higher quality levels (5–11), which CDNs and reverse
+ * proxies (Cloudflare, nginx, Caddy) apply on cached responses.
  *
- * We always prefer brotli regardless of quality values because:
- * 1. Brotli achieves better compression ratios than gzip
- * 2. All modern browsers that send br in Accept-Encoding support it well
- * 3. Respecting q-values for br vs gzip adds complexity with no real benefit
+ * See design/25-production-deployments.md.
  */
-export function negotiateEncoding(acceptEncoding: string): 'br' | 'gzip' | null {
+export function negotiateEncoding(acceptEncoding: string): 'gzip' | null {
   if (!acceptEncoding) return null;
 
   // Parse tokens from the Accept-Encoding header (ignore quality values).
   // e.g. "gzip;q=1.0, br;q=0.8, deflate" → ['gzip', 'br', 'deflate']
   const tokens = acceptEncoding.split(',').map((s) => s.split(';')[0].trim().toLowerCase());
 
-  if (tokens.includes('br')) return 'br';
   if (tokens.includes('gzip')) return 'gzip';
   return null;
 }
@@ -112,10 +115,8 @@ export function compressResponse(request: Request, response: Response): Response
   const encoding = negotiateEncoding(acceptEncoding);
   if (!encoding) return response;
 
-  // Compress the body stream
-  const compressedBody = encoding === 'br'
-    ? compressWithBrotli(response.body!)
-    : compressWithGzip(response.body!);
+  // Compress the body stream with gzip via the Web Platform CompressionStream API.
+  const compressedBody = compressWithGzip(response.body!);
 
   // Build new headers: copy originals, add compression headers, remove Content-Length
   // (compressed size is unknown until streaming completes).
@@ -153,48 +154,3 @@ function compressWithGzip(body: ReadableStream<Uint8Array>): ReadableStream<Uint
   return body.pipeThrough(compressionStream as unknown as TransformStream<Uint8Array, Uint8Array>);
 }
 
-// ─── Brotli (node:zlib) ──────────────────────────────────────────────────
-
-/**
- * Compress a ReadableStream with brotli using node:zlib.
- *
- * CompressionStream doesn't support brotli — it only handles gzip and deflate.
- * We use node:zlib's createBrotliCompress() and bridge between Web streams
- * and Node streams.
- */
-function compressWithBrotli(body: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
-  const brotli = createBrotliCompress({
-    params: {
-      // Quality 4 balances compression ratio and CPU time for streaming.
-      // Default (11) is too slow for real-time responses.
-      [zlibConstants.BROTLI_PARAM_QUALITY]: 4,
-    },
-  });
-
-  // Pipe the Web ReadableStream into the Node brotli transform.
-  const reader = body.getReader();
-
-  // Pump chunks from the Web ReadableStream into the Node transform.
-  const pump = async (): Promise<void> => {
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) {
-          brotli.end();
-          return;
-        }
-        // Write to brotli, wait for drain if buffer is full
-        if (!brotli.write(value)) {
-          await new Promise<void>((resolve) => brotli.once('drain', resolve));
-        }
-      }
-    } catch (err) {
-      brotli.destroy(err instanceof Error ? err : new Error(String(err)));
-    }
-  };
-  // Start pumping (fire and forget — errors propagate via brotli stream)
-  pump();
-
-  // Convert the Node readable (brotli output) to a Web ReadableStream.
-  return Readable.toWeb(brotli) as ReadableStream<Uint8Array>;
-}