@vesk/adapter 0.2.67 → 0.2.68

package/dist/prod-server.d.ts

@@ -1,10 +1,10 @@
 import { type Server } from 'node:http';
+import type { CompressionConfig, ProdServerOptions } from '@vesk/adapter/src/types';
 export declare function bodyTooLarge(maxBytes: number): Error & {
     status: number;
 };
-export declare function startProdServer(outDir: string, options?: {
-    port?: number;
-    host?: string;
-    maxBodyBytes?: number;
+export declare function startProdServer(outDir: string, options?: ProdServerOptions & {
+    compression?: CompressionConfig | false;
+    healthCheck?: boolean;
 }): Promise<Server>;
 //# sourceMappingURL=prod-server.d.ts.map

package/dist/prod-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prod-server.d.ts","sourceRoot":"","sources":["../src/prod-server.ts"],"names":[],"mappings":"AAEA,OAAO,EAA2D,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAkDjG,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAIzE;AAkGD,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkiBxI"}
+{"version":3,"file":"prod-server.d.ts","sourceRoot":"","sources":["../src/prod-server.ts"],"names":[],"mappings":"AAEA,OAAO,EAA2D,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAajG,OAAO,KAAK,EAAkB,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAuFpG,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAIzE;AA0FD,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG;IAAE,WAAW,CAAC,EAAE,iBAAiB,GAAG,KAAK,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAqlBvK"}

package/dist/prod-server.js

@@ -1,5 +1,5 @@
 import { readFileSync, existsSync, statSync } from 'node:fs';
-import { resolve, extname, dirname, basename } from 'node:path';
+import { resolve, dirname, basename } from 'node:path';
 import { createServer } from 'node:http';
 import { fileURLToPath } from 'node:url';
 import { createRateLimiter, resolveComponentName, safeJsonForScript, getClientProtocol, DEFAULT_MAX_BODY_BYTES } from '@vesk/compiler/src/server-codegen';
@@ -11,6 +11,8 @@ import { resolveWithin, installMdReadHook } from '@vesk/adapter/src/paths';
 import { resolveCssUrls, hasBuiltGlobalCss } from '@vesk/adapter/src/css';
 import { loadVeskConfig } from '@vesk/adapter/src/load-config';
 import { renderDefaultNotFoundPage, renderDefaultErrorPage } from '@vesk/adapter/src/default-pages';
+import { installResponsePipeline } from '@vesk/adapter/src/response-pipeline';
+import { mimeFor } from '@vesk/adapter/src/platform-output';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 async function readBody(req, maxBytes = DEFAULT_MAX_BODY_BYTES) {
     const chunks = [];
@@ -23,15 +25,68 @@ async function readBody(req, maxBytes = DEFAULT_MAX_BODY_BYTES) {
     }
     return Buffer.concat(chunks);
 }
+/** Open-ended content types. Buffering one would hold the response until the
+ *  stream closed — which, for a never-ending event stream, is never. */
+const STREAMING_TYPES = new Set(['text/event-stream', 'application/x-ndjson']);
+/** Above this, a "buffered" body is streamed instead rather than held whole. */
+const DELIVER_BUFFER_LIMIT = 1024 * 1024;
 /**
- * Writes a handler Response to the socket, piping a streaming body
- * chunk-by-chunk (SSE / text streams) instead of buffering everything.
+ * Writes a handler Response to the socket.
+ *
+ * A finite body is delivered as ONE `end(buffer)`, not chunk-by-chunk, and that
+ * is load-bearing: the response pipeline can only tag a body and revalidate it
+ * against `If-None-Match` — and only apply content-encoding — once it can see
+ * the whole body. Streaming a 2 KB JSON body would silently opt every API
+ * response out of both. A response that turns out to exceed the buffer limit,
+ * or that declares an open-ended content type, falls back to streaming so the
+ * memory and time-to-first-byte cost of a genuinely large body is unchanged.
  */
 async function deliverResponse(res, response) {
-    res.writeHead(response.status, Object.fromEntries(response.headers));
+    const headers = Object.fromEntries(response.headers);
     const body = response.body;
-    if (body && typeof body.getReader === 'function') {
-        const reader = body.getReader();
+    if (!body || typeof body.getReader !== 'function') {
+        res.writeHead(response.status, headers);
+        res.end(await response.text());
+        return;
+    }
+    const contentType = String(response.headers.get('content-type') || '').split(';')[0].trim().toLowerCase();
+    const reader = body.getReader();
+    if (STREAMING_TYPES.has(contentType)) {
+        res.writeHead(response.status, headers);
+        pumpRemaining(res, reader);
+        return;
+    }
+    const chunks = [];
+    let size = 0;
+    let overflow = false;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            chunks.push(Buffer.from(value));
+            size += value.byteLength;
+            if (size > DELIVER_BUFFER_LIMIT) {
+                overflow = true;
+                break;
+            }
+        }
+    }
+    catch {
+        /* stream aborted by the client */
+    }
+    res.writeHead(response.status, headers);
+    if (overflow) {
+        for (const chunk of chunks)
+            res.write(chunk);
+        pumpRemaining(res, reader);
+        return;
+    }
+    res.end(Buffer.concat(chunks));
+}
+/** Drain an already-started reader onto the socket, then end it. */
+function pumpRemaining(res, reader) {
+    void (async () => {
         try {
             for (;;) {
                 const { done, value } = await reader.read();
@@ -44,9 +99,7 @@ async function deliverResponse(res, response) {
             /* stream aborted by the client */
         }
         res.end();
-        return;
-    }
-    res.end(await response.text());
+    })();
 }
 export function bodyTooLarge(maxBytes) {
     const err = new Error(`Request body exceeds limit (${maxBytes} bytes)`);
@@ -111,13 +164,6 @@ function makeWebRequest(nodeReq, url, maxBodyBytes = DEFAULT_MAX_BODY_BYTES) {
     webRequest.query = query;
     return webRequest;
 }
-const MIME = {
-    '.svg': 'image/svg+xml', '.css': 'text/css', '.js': 'application/javascript',
-    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
-    '.ico': 'image/x-icon', '.html': 'text/html', '.json': 'application/json',
-    '.webmanifest': 'application/manifest+json',
-    '.woff': 'font/woff', '.woff2': 'font/woff2', '.wasm': 'application/wasm',
-};
 export async function startProdServer(outDir, options) {
     const port = options?.port || 3000;
     const host = options?.host || '127.0.0.1';
@@ -142,11 +188,16 @@ export async function startProdServer(outDir, options) {
     const projectDir = resolve(outDir, '..');
     let securityConfig = {};
     let mdConfig;
+    let compressionConfig = {};
+    let healthCheckEnabled = true;
     try {
         const config = await loadVeskConfig(projectDir);
         if (config) {
             securityConfig = { security: config.security };
             mdConfig = config.md;
+            // `compression: false` disables encoding entirely; an object tunes it.
+            compressionConfig = config.compression === false ? { enabled: false } : (config.compression || {});
+            healthCheckEnabled = config.healthCheck !== false;
         }
     }
     catch (e) {
@@ -154,6 +205,13 @@ export async function startProdServer(outDir, options) {
         // config must never silently disable the app's chosen security policy.
         console.error('vesk start: failed to load vesk.config — falling back to secure defaults:', e instanceof Error ? e.message : e);
     }
+    // Explicit server options win over vesk.config (the CLI passes nothing here,
+    // so this is the programmatic path — how tests and embedders configure it).
+    if (options?.compression !== undefined) {
+        compressionConfig = options.compression === false ? { enabled: false } : options.compression;
+    }
+    if (options?.healthCheck !== undefined)
+        healthCheckEnabled = options.healthCheck !== false;
     if (mdConfig) {
         try {
             const { configureMd } = await import('@vesk/runtime/src/md');
@@ -262,6 +320,23 @@ export async function startProdServer(outDir, options) {
             ? 'https'
             : getClientProtocol({ headers: req.headers }, !!securityConfig?.trustProxy);
         globalThis.__vesk_ssr_base_url = `${proto}://${reqHost}`;
+        // Liveness probe. Deliberately the FIRST thing in the handler, ahead of the
+        // rate limiter, middleware and the pipeline below:
+        //  - a probe that can be answered 429 is indistinguishable from a dead
+        //    server to an orchestrator, which then restarts a healthy pod;
+        //  - it must not be rewritten or authed by user middleware;
+        //  - it must never be encoded or tagged — a load balancer revalidating a
+        //    cached "ok" is testing its own cache, not this process.
+        if (healthCheckEnabled && (url.pathname === '/healthz' || url.pathname === '/_vesk/healthz')) {
+            const probe = JSON.stringify({ status: 'ok', uptime: Math.floor(process.uptime()) });
+            res.writeHead(200, {
+                'Content-Type': 'application/json; charset=utf-8',
+                'Content-Length': String(Buffer.byteLength(probe)),
+                'Cache-Control': 'no-store',
+            });
+            res.end(probe);
+            return;
+        }
         if (rateLimiter) {
             const clientIp = getClientIpFromReq(req);
             if (!rateLimiter.check(clientIp)) {
@@ -327,11 +402,22 @@ export async function startProdServer(outDir, options) {
             }
             return origWriteHead2(statusCode, headers);
         });
+        // Installed LAST so it wraps the two header decorators above: its captured
+        // `writeHead` is their wrapper, so security headers and per-request
+        // overrides are still merged in — once, at flush time. One install covers
+        // every response the handler produces (static files, SSR HTML, API JSON,
+        // middleware short-circuits), so no call site can be missed.
+        installResponsePipeline(res, req, {
+            compress: compressionConfig.enabled !== false,
+            compressThreshold: compressionConfig.threshold,
+            brotliQuality: compressionConfig.brotliQuality,
+            gzipLevel: compressionConfig.gzipLevel,
+            etag: compressionConfig.etag !== false,
+        });
         const publicDir = resolve(staticDir, 'public');
         const rootFile = url.pathname.length > 1 ? resolveWithin(publicDir, url.pathname.slice(1)) : null;
         if (rootFile && existsSync(rootFile) && statSync(rootFile).isFile()) {
-            const ext = extname(rootFile);
-            res.writeHead(200, { 'Content-Type': MIME[ext] || 'application/octet-stream' });
+            res.writeHead(200, { 'Content-Type': mimeFor(rootFile) });
             res.end(readFileSync(rootFile));
             return;
         }
@@ -387,9 +473,8 @@ export async function startProdServer(outDir, options) {
                 return;
             }
             if (existsSync(staticPath) && statSync(staticPath).isFile()) {
-                const ext = extname(staticPath);
                 res.writeHead(200, {
-                    'Content-Type': MIME[ext] || 'application/octet-stream',
+                    'Content-Type': mimeFor(staticPath),
                     // A content-hashed name can never change meaning, so it is immutable
                     // for a year; anything unhashed must be revalidated or a deploy would
                     // serve stale JS forever.
@@ -651,8 +736,19 @@ export async function startProdServer(outDir, options) {
         server.close(() => process.exit(0));
         setTimeout(() => process.exit(0), 3000).unref();
     }
-    process.on('SIGINT', () => shutdown('SIGINT'));
-    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    // Named handlers so they can be detached on close. Without this every
+    // start/stop cycle leaks two process listeners, which is a hard crash
+    // (MaxListenersExceededWarning → throw) once a host restarts the server more
+    // than five times — the shape every test harness and hot-restarting dev
+    // wrapper uses.
+    const onSigint = () => shutdown('SIGINT');
+    const onSigterm = () => shutdown('SIGTERM');
+    process.on('SIGINT', onSigint);
+    process.on('SIGTERM', onSigterm);
+    server.once('close', () => {
+        process.off('SIGINT', onSigint);
+        process.off('SIGTERM', onSigterm);
+    });
     server.listen(port, host, () => {
         console.error(`vesk production server at http://localhost:${port} (listening on ${host})`);
     });

package/dist/response-pipeline.d.ts

@@ -0,0 +1,54 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export type ContentEncoding = 'br' | 'gzip';
+/**
+ * Pick a content coding from `Accept-Encoding`.
+ *
+ * Quality values are honoured because a client is entitled to say "I accept
+ * gzip but not brotli" (`br;q=0`) or "gzip only at half priority". `*` applies
+ * to codings the header does not name. Ties go to brotli: every browser that
+ * sends both lists them equally, and brotli is smaller.
+ */
+export declare function negotiateEncoding(header: string | string[] | undefined): ContentEncoding | null;
+/**
+ * Would compressing this content type actually pay?
+ *
+ * The rule is "text-like, not already compressed". Images, fonts, video and
+ * archives are already compressed — a second pass costs CPU and usually makes
+ * the body *larger*, which is why the size check in `installResponsePipeline`
+ * is kept as a second line of defence rather than the only one.
+ */
+export declare function isCompressibleType(contentType: string | undefined): boolean;
+/**
+ * A validator for these exact bytes.
+ *
+ * sha1 rather than sha256 because this is a cache validator, not a security
+ * primitive (RFC 9110 requires "a function of the representation", and nginx
+ * ships md5 here), and every request hashes its body. Truncated to 20 bytes of
+ * base64 — 27 characters — which is far beyond collision range for a validator.
+ */
+export declare function etagFor(body: Buffer): string;
+/**
+ * `If-None-Match` satisfaction, weak comparison as RFC 9110 §13.1.2 requires
+ * for GET. Weak comparison ignores the `W/` prefix on either side, which is what
+ * makes a `W/"x"` from a proxy match our strong `"x"`.
+ */
+export declare function ifNoneMatchSatisfied(header: string | string[] | undefined, etag: string): boolean;
+export interface ResponsePipelineOptions {
+    /** Set false to disable content-coding negotiation. Default true. */
+    compress?: boolean;
+    /** Smallest body worth compressing, in bytes. Default 1024. */
+    compressThreshold?: number;
+    /** Set false to disable ETag/304. Default true. */
+    etag?: boolean;
+    /** brotli quality 0-11. Default 5 — 11 is several hundred ms per megabyte. */
+    brotliQuality?: number;
+    /** gzip level 1-9. Default 6. */
+    gzipLevel?: number;
+}
+/**
+ * Wrap `res` so every buffered response is tagged with an ETag, revalidated
+ * against `If-None-Match`, and encoded — in that order, because a 304 must be
+ * decided on the *unencoded* bytes.
+ */
+export declare function installResponsePipeline(res: ServerResponse, req: IncomingMessage, options?: ResponsePipelineOptions): void;
+//# sourceMappingURL=response-pipeline.d.ts.map

package/dist/response-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-pipeline.d.ts","sourceRoot":"","sources":["../src/response-pipeline.ts"],"names":[],"mappings":"AAyCA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAKjE,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,MAAM,CAAC;AAE5C;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,eAAe,GAAG,IAAI,CAgC/F;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAwB3E;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAWjG;AAED,MAAM,WAAW,uBAAuB;IACvC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AA8BD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACtC,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,eAAe,EACpB,OAAO,GAAE,uBAA4B,GACnC,IAAI,CA2ON"}

package/dist/response-pipeline.js

@@ -0,0 +1,422 @@
+/**
+ * Transport-level response pipeline: conditional GET (ETag → 304) and
+ * content-encoding negotiation (brotli / gzip).
+ *
+ * Both live in one wrapper because they share the same constraint: the decision
+ * can only be made once the whole body is known. `res.writeHead` sends headers
+ * to the socket immediately, so a wrapper that compressed or tagged at
+ * `writeHead` time would either have to buffer every response in the server (a
+ * second copy of every page) or get the answer wrong for streamed bodies.
+ * Instead this captures `writeHead` and defers it until the body is either
+ * complete (`end`) or discovered to be a stream (`write`).
+ *
+ * Consequences worth knowing:
+ *
+ * - **One install covers every call site.** The prod server writes headers in
+ *   ~15 places; wrapping `res` once means a new one cannot be forgotten. A
+ *   static file, an SSR page, a JSON API body and a middleware short-circuit
+ *   all pass through the same path.
+ * - **The first `write()` opts the response out of everything.** A stream
+ *   (SSE, a chunked `renderPageStream`) cannot be re-encoded after the first
+ *   bytes are out, so `write()` flushes the captured headers verbatim and every
+ *   later `write`/`end` is a passthrough. No `Content-Encoding` is ever
+ *   announced for a body that was not encoded.
+ * - **The wrapper composes with header decorators.** Installing *after* another
+ *   `writeHead` wrapper means this layer's captured reference IS that wrapper,
+ *   so security headers and per-request overrides are still applied — at flush
+ *   time, exactly once.
+ *
+ * Deliberately not here: range requests, `Last-Modified`/`If-Modified-Since`
+ * (the ETag covers the same revalidation need and cannot disagree with itself),
+ * and compression of already-encoded bodies.
+ */
+import { createHash } from 'node:crypto';
+import { brotliCompress, constants as zlibConstants, createBrotliCompress, createGzip, gzip, } from 'node:zlib';
+import { promisify } from 'node:util';
+const brotliCompressAsync = promisify(brotliCompress);
+const gzipAsync = promisify(gzip);
+/**
+ * Pick a content coding from `Accept-Encoding`.
+ *
+ * Quality values are honoured because a client is entitled to say "I accept
+ * gzip but not brotli" (`br;q=0`) or "gzip only at half priority". `*` applies
+ * to codings the header does not name. Ties go to brotli: every browser that
+ * sends both lists them equally, and brotli is smaller.
+ */
+export function negotiateEncoding(header) {
+    if (!header)
+        return null;
+    // `header` is `string | string[]` per Node's typings, but a duplicated
+    // header arrives joined by ", " in practice; both shapes fold to one list.
+    const value = Array.isArray(header) ? header.join(',') : header;
+    const q = {};
+    for (const part of value.split(',')) {
+        const seg = part.trim();
+        if (!seg)
+            continue;
+        const semi = seg.indexOf(';');
+        const token = (semi === -1 ? seg : seg.slice(0, semi)).trim().toLowerCase();
+        if (!token)
+            continue;
+        let weight = 1;
+        if (semi !== -1) {
+            for (const param of seg.slice(semi + 1).split(';')) {
+                const eq = param.indexOf('=');
+                if (eq === -1)
+                    continue;
+                if (param.slice(0, eq).trim().toLowerCase() !== 'q')
+                    continue;
+                const parsed = Number.parseFloat(param.slice(eq + 1).trim());
+                if (Number.isFinite(parsed))
+                    weight = parsed;
+            }
+        }
+        // First occurrence wins, per RFC 9110 — a client cannot raise its own
+        // preference by listing a coding twice.
+        if (!(token in q))
+            q[token] = weight;
+    }
+    const star = q['*'];
+    const br = q['br'] !== undefined ? q['br'] : star;
+    const gz = q['gzip'] !== undefined ? q['gzip'] : star;
+    if (br !== undefined && br > 0 && (gz === undefined || gz <= 0 || br >= gz))
+        return 'br';
+    if (gz !== undefined && gz > 0)
+        return 'gzip';
+    return null;
+}
+/**
+ * Would compressing this content type actually pay?
+ *
+ * The rule is "text-like, not already compressed". Images, fonts, video and
+ * archives are already compressed — a second pass costs CPU and usually makes
+ * the body *larger*, which is why the size check in `installResponsePipeline`
+ * is kept as a second line of defence rather than the only one.
+ */
+export function isCompressibleType(contentType) {
+    if (!contentType)
+        return false;
+    const type = (contentType.split(';')[0] || '').trim().toLowerCase();
+    if (!type)
+        return false;
+    if (type.startsWith('text/'))
+        return true;
+    if (type === 'image/svg+xml' || type === 'image/x-icon' || type === 'image/bmp')
+        return true;
+    if (type.endsWith('+json') || type.endsWith('+xml'))
+        return true;
+    switch (type) {
+        case 'application/javascript':
+        case 'application/x-javascript':
+        case 'application/ecmascript':
+        case 'application/json':
+        case 'application/manifest+json':
+        case 'application/ld+json':
+        case 'application/graphql':
+        case 'application/x-ndjson':
+        case 'application/xml':
+        case 'application/xhtml+xml':
+        case 'application/rss+xml':
+        case 'application/atom+xml':
+            return true;
+        default:
+            return false;
+    }
+}
+/**
+ * A validator for these exact bytes.
+ *
+ * sha1 rather than sha256 because this is a cache validator, not a security
+ * primitive (RFC 9110 requires "a function of the representation", and nginx
+ * ships md5 here), and every request hashes its body. Truncated to 20 bytes of
+ * base64 — 27 characters — which is far beyond collision range for a validator.
+ */
+export function etagFor(body) {
+    return `"${createHash('sha1').update(body).digest('base64').slice(0, 27)}"`;
+}
+/**
+ * `If-None-Match` satisfaction, weak comparison as RFC 9110 §13.1.2 requires
+ * for GET. Weak comparison ignores the `W/` prefix on either side, which is what
+ * makes a `W/"x"` from a proxy match our strong `"x"`.
+ */
+export function ifNoneMatchSatisfied(header, etag) {
+    if (!header)
+        return false;
+    const value = Array.isArray(header) ? header.join(',') : header;
+    const candidates = value.split(',').map(s => s.trim()).filter(Boolean);
+    if (candidates.includes('*'))
+        return true;
+    const strip = (s) => (s.startsWith('W/') ? s.slice(2) : s).trim();
+    const target = strip(etag);
+    for (const candidate of candidates) {
+        if (strip(candidate) === target)
+            return true;
+    }
+    return false;
+}
+function getHeader(headers, name) {
+    const wanted = name.toLowerCase();
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() === wanted) {
+            const v = headers[key];
+            if (v === undefined)
+                return undefined;
+            return Array.isArray(v) ? v.join(', ') : String(v);
+        }
+    }
+    return undefined;
+}
+function hasNoStore(cacheControl) {
+    if (!cacheControl)
+        return false;
+    return cacheControl.split(',').some(part => part.trim().toLowerCase() === 'no-store');
+}
+/** Add `value` to `Vary` without duplicating an entry already there. */
+function withVary(current, value) {
+    if (!current)
+        return value;
+    const existing = current.split(',').map(s => s.trim().toLowerCase());
+    if (existing.includes(value.toLowerCase()))
+        return current;
+    if (existing.includes('*'))
+        return current;
+    return `${current}, ${value}`;
+}
+/**
+ * Wrap `res` so every buffered response is tagged with an ETag, revalidated
+ * against `If-None-Match`, and encoded — in that order, because a 304 must be
+ * decided on the *unencoded* bytes.
+ */
+export function installResponsePipeline(res, req, options = {}) {
+    const compressEnabled = options.compress !== false;
+    const etagEnabled = options.etag !== false;
+    const threshold = options.compressThreshold ?? 1024;
+    const brotliQuality = options.brotliQuality ?? 5;
+    const gzipLevel = options.gzipLevel ?? 6;
+    const realWriteHead = res.writeHead.bind(res);
+    const realWrite = res.write.bind(res);
+    const realEnd = res.end.bind(res);
+    const realFlushHeaders = res.flushHeaders.bind(res);
+    let pendingStatus = 200;
+    let pendingHeaders = {};
+    let flushed = false;
+    let streaming = false;
+    let streamCompressor = null;
+    /** Emit the captured status+headers exactly once, merging in `extra`. */
+    function flush(extra) {
+        if (flushed)
+            return;
+        flushed = true;
+        const headers = {};
+        for (const [key, value] of Object.entries(pendingHeaders)) {
+            if (value !== undefined)
+                headers[key] = value;
+        }
+        for (const [key, value] of Object.entries(extra || {})) {
+            if (value === undefined)
+                delete headers[key];
+            else
+                headers[key] = value;
+        }
+        realWriteHead(pendingStatus, headers);
+    }
+    res.writeHead = ((statusCode, headers) => {
+        if (flushed || streaming)
+            return realWriteHead(statusCode, headers);
+        pendingStatus = statusCode;
+        pendingHeaders = { ...(headers || {}) };
+        return res;
+    });
+    /**
+     * Would this response's bytes differ if the client sent a different
+     * `Accept-Encoding`? If yes it must be announced in `Vary` whether or not
+     * an encoding was actually applied — a cache that stored the identity copy
+     * without seeing `Vary` would then serve it to a client that can decode br.
+     */
+    function encodingIsVariable() {
+        return compressEnabled
+            && !getHeader(pendingHeaders, 'content-encoding')
+            && isCompressibleType(getHeader(pendingHeaders, 'content-type'));
+    }
+    function startStreamCompression(encoding) {
+        const compressor = encoding === 'br'
+            ? createBrotliCompress({ params: { [zlibConstants.BROTLI_PARAM_QUALITY]: brotliQuality } })
+            : createGzip({ level: gzipLevel });
+        // The compressor owns the socket from here: its output is what the client
+        // receives, and its `end` is what actually finishes the response. This is
+        // what lets a *streamed* body still be encoded — buffering it to compute a
+        // validator would defeat the streaming in the first place.
+        compressor.on('data', (chunk) => { realWrite(chunk); });
+        compressor.on('end', () => { realEnd(); });
+        compressor.on('error', () => {
+            // A compressor failure must still produce a complete response object;
+            // the bytes already written are the unencoded prefix, which is why the
+            // socket has to be closed rather than left open.
+            try {
+                realEnd();
+            }
+            catch { /* already finished */ }
+        });
+        streamCompressor = compressor;
+    }
+    res.write = ((chunk, encoding) => {
+        if (!flushed && !streaming) {
+            streaming = true;
+            const vary = withVary(getHeader(pendingHeaders, 'vary'), 'Accept-Encoding');
+            const encodingChosen = encodingIsVariable() ? negotiateEncoding(req.headers['accept-encoding']) : null;
+            if (encodingChosen) {
+                startStreamCompression(encodingChosen);
+                // Content-Length cannot survive: the encoded stream's length is
+                // unknown until it ends, and a wrong one truncates the response.
+                flush({ 'Content-Encoding': encodingChosen, Vary: vary, 'Content-Length': undefined });
+            }
+            else {
+                flush({ Vary: encodingIsVariable() ? vary : undefined });
+            }
+        }
+        if (streamCompressor) {
+            streamCompressor.write(toBuffer(chunk, encoding) || Buffer.alloc(0));
+            return true;
+        }
+        return typeof encoding === 'undefined'
+            ? realWrite(chunk)
+            : realWrite(chunk, encoding);
+    });
+    res.flushHeaders = (() => {
+        if (!flushed) {
+            streaming = true;
+            flush();
+        }
+        realFlushHeaders.call(res);
+    });
+    function toBuffer(chunk, encoding) {
+        if (chunk === undefined || chunk === null)
+            return null;
+        if (Buffer.isBuffer(chunk))
+            return chunk;
+        if (typeof chunk === 'string') {
+            return Buffer.from(chunk, typeof encoding === 'string' ? encoding : 'utf8');
+        }
+        if (chunk instanceof Uint8Array)
+            return Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+        return null;
+    }
+    function finish(body, endArgs) {
+        const method = (req.method || 'GET').toUpperCase();
+        // Nothing to compress, tag or revalidate. Empty bodies include 204 and
+        // 304 responses, which must not carry a Content-Length anyway.
+        if (!body || body.length === 0 || streaming || flushed) {
+            flush();
+            realEnd(...endArgs);
+            return;
+        }
+        const cacheable = method === 'GET' || method === 'HEAD';
+        const existingEtag = getHeader(pendingHeaders, 'etag');
+        // `no-store` means the bytes are not reusable, so a validator would only
+        // produce a 304 that hands the client back a body the server has already
+        // consumed. This is load-bearing for the single-use `/ssr-data.js` and
+        // `/store-init.js` payloads, which are deleted as they are read.
+        const canValidate = cacheable && pendingStatus === 200 && !hasNoStore(getHeader(pendingHeaders, 'cache-control'));
+        if (!canValidate) {
+            maybeCompress(body, endArgs);
+            return;
+        }
+        const etag = existingEtag || (etagEnabled ? etagFor(body) : undefined);
+        if (etag && ifNoneMatchSatisfied(req.headers['if-none-match'], etag)) {
+            // A 304 carries the validator and the caching directives and nothing
+            // else — no body, and no Content-Type/Content-Length describing one.
+            const headers304 = { ETag: etag };
+            const cc = getHeader(pendingHeaders, 'cache-control');
+            if (cc)
+                headers304['Cache-Control'] = cc;
+            headers304.Vary = withVary(getHeader(pendingHeaders, 'vary'), 'Accept-Encoding');
+            flushed = true;
+            realWriteHead(304, headers304);
+            realEnd();
+            return;
+        }
+        if (etag && !existingEtag) {
+            pendingHeaders = { ...pendingHeaders, ETag: etag };
+        }
+        maybeCompress(body, endArgs);
+    }
+    function maybeCompress(body, endArgs) {
+        // Below the threshold the bytes are identical whatever the client asks
+        // for, so no `Vary` is owed — announcing one would fragment caches for
+        // nothing. At or above it, the representation does vary by encoding and
+        // `Vary` is announced whether or not a coding was chosen.
+        if (compressEnabled
+            && body.length < threshold
+            || !encodingIsVariable()) {
+            flush();
+            realEnd(...endArgs);
+            return;
+        }
+        const encoding = negotiateEncoding(req.headers['accept-encoding']);
+        if (!encoding) {
+            flush({ Vary: withVary(getHeader(pendingHeaders, 'vary'), 'Accept-Encoding') });
+            realEnd(...endArgs);
+            return;
+        }
+        const compress = encoding === 'br' ? brotliCompressAsync : gzipAsync;
+        const params = encoding === 'br'
+            ? { params: { [zlibConstants.BROTLI_PARAM_QUALITY]: brotliQuality } }
+            : { level: gzipLevel };
+        void Promise.resolve()
+            .then(() => compress(body, params))
+            .then((encoded) => {
+            // A body that did not get smaller is not worth the encoding: it
+            // costs the client CPU on every fetch for nothing.
+            if (flushed || streaming) {
+                flush();
+                realEnd(...endArgs);
+                return;
+            }
+            if (encoded.length >= body.length) {
+                flush({ Vary: withVary(getHeader(pendingHeaders, 'vary'), 'Accept-Encoding') });
+                realEnd(...endArgs);
+                return;
+            }
+            flush({
+                'Content-Encoding': encoding,
+                Vary: withVary(getHeader(pendingHeaders, 'vary'), 'Accept-Encoding'),
+                'Content-Length': String(encoded.length),
+            });
+            realEnd(encoded);
+        })
+            .catch(() => {
+            // Compression must never be the reason a response is lost.
+            flush({ Vary: withVary(getHeader(pendingHeaders, 'vary'), 'Accept-Encoding') });
+            realEnd(...endArgs);
+        });
+    }
+    res.end = ((chunk, encoding, callback) => {
+        if (streamCompressor) {
+            // Ending the compressor is what ends the response — it flushes its
+            // own buffered tail first, so the client gets a complete stream.
+            if (typeof callback === 'function')
+                res.once('finish', callback);
+            const tail = toBuffer(chunk, encoding);
+            if (tail)
+                streamCompressor.end(tail);
+            else
+                streamCompressor.end();
+            return res;
+        }
+        if (streaming || flushed) {
+            return realEnd(chunk, encoding, callback);
+        }
+        // Node's end() has four shapes — (), (cb), (data), (data, enc),
+        // (data, cb), (data, enc, cb). Forward only the arguments that were
+        // actually supplied: `end(body, undefined, undefined)` is NOT the same
+        // as `end(body)` for a callback-taking overload.
+        const endArgs = chunk === undefined
+            ? (callback === undefined ? [] : [callback])
+            : encoding === undefined
+                ? (callback === undefined ? [chunk] : [chunk, callback])
+                : (callback === undefined ? [chunk, encoding] : [chunk, encoding, callback]);
+        const body = toBuffer(chunk, encoding);
+        finish(body, endArgs);
+        return res;
+    });
+}

package/dist/types.d.ts

@@ -1,2 +1,2 @@
-export type { RouteNode, ApiRouteNode, VeskPlugin, ServerEventContext, VeskEventHandlers, VeskSecurity, VeskCors, VeskRateLimit, VeskSecurityPreset, SecurityConfig, MiddlewareChainItem, MiddlewareExtractResult, AncestorLayout, BuildOptions, DevServerOptions, ProdServerOptions, SsrFunctionOptions, ApiFunctionOptions, ClientBundleOptions, ClientBundleFileEntry, ClientBundleChunkSpec, ClientBundleCache, ChunkEntry, ClientBundleResult, MonolithicBundleParts, Manifest, ManifestRouteEntry, ManifestActionEntry, ManifestPrerenderedEntry, SsgRouteResult, BuildResult, ImageRef, ImageResult, SeoCheckIssue, SeoAuditResult, CombinedPageInfo, Tracked, Resource, UseFetchOptions, UseFetchStreamOptions, VeskRequest, VeskResponse, SetCookieOptions, CookieStore, ServerRequest, SsrDataSink, MdProps, MdConfig, MdHtmlMode, MarkdownOptions, MdHtmlWarning, VeskLeafComponent, VeskPrimitiveComponent, VeskTaggedLeafComponent, VeskComponentRegistry, VeskScope, } from '@vesk/types';
+export type { RouteNode, ApiRouteNode, VeskPlugin, ServerEventContext, VeskEventHandlers, VeskSecurity, VeskCors, VeskRateLimit, VeskSecurityPreset, SecurityConfig, MiddlewareChainItem, MiddlewareExtractResult, AncestorLayout, BuildOptions, DevServerOptions, ProdServerOptions, SsrFunctionOptions, ApiFunctionOptions, ClientBundleOptions, ClientBundleFileEntry, ClientBundleChunkSpec, ClientBundleCache, ChunkEntry, ClientBundleResult, MonolithicBundleParts, Manifest, ManifestRouteEntry, ManifestActionEntry, ManifestPrerenderedEntry, SsgRouteResult, BuildResult, ImageRef, ImageResult, SeoCheckIssue, SeoAuditResult, CombinedPageInfo, Tracked, Resource, UseFetchOptions, UseFetchStreamOptions, VeskRequest, VeskResponse, SetCookieOptions, CookieStore, ServerRequest, SsrDataSink, MdProps, MdConfig, MdHtmlMode, MarkdownOptions, CompressionConfig, MdHtmlWarning, VeskLeafComponent, VeskPrimitiveComponent, VeskTaggedLeafComponent, VeskComponentRegistry, VeskScope, } from '@vesk/types';
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,SAAS,EACT,YAAY,EACZ,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,UAAU,EACV,kBAAkB,EAClB,qBAAqB,EACrB,QAAQ,EACR,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,cAAc,EACd,WAAW,EACX,QAAQ,EACR,WAAW,EACX,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,OAAO,EACP,QAAQ,EACR,eAAe,EACf,qBAAqB,EACrB,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,WAAW,EACX,OAAO,EACP,QAAQ,EACR,UAAU,EACV,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,SAAS,GACV,MAAM,aAAa,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,SAAS,EACT,YAAY,EACZ,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,UAAU,EACV,kBAAkB,EAClB,qBAAqB,EACrB,QAAQ,EACR,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,cAAc,EACd,WAAW,EACX,QAAQ,EACR,WAAW,EACX,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,OAAO,EACP,QAAQ,EACR,eAAe,EACf,qBAAqB,EACrB,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,WAAW,EACX,OAAO,EACP,QAAQ,EACR,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,SAAS,GACV,MAAM,aAAa,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vesk/adapter",
-  "version": "0.2.67",
+  "version": "0.2.68",
   "type": "module",
   "description": "Vesk adapter — builds deployable .vesk/ output for Deno and Node serverless",
   "main": "./dist/index.js",
@@ -23,9 +23,9 @@
     "sharp": "^0.35.3"
   },
   "dependencies": {
-    "@vesk/compiler": "^0.2.67",
-    "@vesk/runtime": "^0.2.67",
-    "@vesk/types": "^0.2.67"
+    "@vesk/compiler": "^0.2.68",
+    "@vesk/runtime": "^0.2.68",
+    "@vesk/types": "^0.2.68"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1",