tina4-nodejs 3.13.133 → 3.13.135

package/packages/core/src/aiClient.ts

@@ -185,39 +185,53 @@ export class Ai {
     if (!Array.isArray(content) || content.length === 0) {
       throw new AiConfigError("AI message content must be a string or a non-empty list of parts");
     }
-    for (const part of content) {
-      if (!part || typeof part !== "object" || Array.isArray(part)) {
-        throw new AiConfigError("AI content part must be an object with type and text/source");
-      }
-      const record = part as Record<string, unknown>;
-      const partType = record.type;
-      if (partType === "text") {
-        if (typeof record.text !== "string") {
-          throw new AiConfigError("AI text content part requires a string 'text' field");
-        }
-      } else if (partType === "image") {
-        if (typeof record.source !== "string" || record.source.length === 0) {
-          throw new AiConfigError("AI image content part requires a non-empty string 'source' field");
-        }
-        if (!record.source.startsWith("data:") && !record.source.startsWith("https://")) {
-          throw new AiConfigError("AI image source must be a data: URI or an https:// URL");
-        }
-        if (record.source.startsWith("data:") && !/^data:[^;,\s]+;base64,[A-Za-z0-9+/=]+$/.test(record.source)) {
-          throw new AiConfigError("AI image data URI must be data:<media_type>;base64,<payload>");
-        }
-      } else if (partType === "tool_result") {
-        if (typeof record.tool_use_id !== "string" || record.tool_use_id.length === 0) {
-          throw new AiConfigError("AI tool_result part requires a non-empty string 'tool_use_id'");
-        }
-        if (typeof record.content !== "string") {
-          throw new AiConfigError("AI tool_result part requires a string 'content'");
-        }
-      } else {
-        throw new AiConfigError(`AI content part has unknown type '${String(partType)}'`);
-      }
+    for (const part of content) this.validateContentPart(part);
+  }
+
+  private static validateContentPart(part: unknown): void {
+    if (!part || typeof part !== "object" || Array.isArray(part)) {
+      throw new AiConfigError("AI content part must be an object with type and text/source");
+    }
+    const record = part as Record<string, unknown>;
+    switch (record.type) {
+      case "text":
+        this.validateTextPart(record);
+        return;
+      case "image":
+        this.validateImagePart(record);
+        return;
+      case "tool_result":
+        this.validateToolResultPart(record);
+        return;
+      default:
+        throw new AiConfigError(`AI content part has unknown type '${String(record.type)}'`);
     }
   }
 
+  private static validateTextPart(record: Record<string, unknown>): void {
+    if (typeof record.text !== "string") throw new AiConfigError("AI text content part requires a string 'text' field");
+  }
+
+  private static validateImagePart(record: Record<string, unknown>): void {
+    const source = record.source;
+    if (typeof source !== "string" || source.length === 0) {
+      throw new AiConfigError("AI image content part requires a non-empty string 'source' field");
+    }
+    if (!source.startsWith("data:") && !source.startsWith("https://")) {
+      throw new AiConfigError("AI image source must be a data: URI or an https:// URL");
+    }
+    if (source.startsWith("data:") && !/^data:[^;,\s]+;base64,[A-Za-z0-9+/=]+$/.test(source)) {
+      throw new AiConfigError("AI image data URI must be data:<media_type>;base64,<payload>");
+    }
+  }
+
+  private static validateToolResultPart(record: Record<string, unknown>): void {
+    if (typeof record.tool_use_id !== "string" || record.tool_use_id.length === 0) {
+      throw new AiConfigError("AI tool_result part requires a non-empty string 'tool_use_id'");
+    }
+    if (typeof record.content !== "string") throw new AiConfigError("AI tool_result part requires a string 'content'");
+  }
+
   /**
    * Validate the outbound tool declarations (ADR-0061). Each tool needs a
    * non-empty `name`, a string `description`, and a JSON-Schema-shaped
@@ -566,27 +580,11 @@ export class Ai {
           throw new AiHTTPError(`AI provider returned HTTP ${status}`, status);
         }
         const response = opened.response;
-        const chunks = this.responseChunks(response);
-        const events = parseSseStream(parseLineStream(chunks));
-        const aggregator = new AggregateState(config.provider);
         let done = false;
-        try {
-          for await (const sseEvent of events) {
-            for (const emitted of aggregator.consume(sseEvent)) {
-              yielded = true;
-              yield emitted;
-              if (emitted.type === "done" || emitted.type === "error") { done = true; break; }
-            }
-            if (done) break;
-          }
-        } catch (error) {
-          if (yielded) {
-            yielded = true;
-            yield { type: "error", message: error instanceof AiParseError ? "AI provider returned malformed stream data" : `AI transport failed (${error instanceof Error ? error.name : "Error"})` };
-            opened.cleanup(); opened = null;
-            return;
-          }
-          throw error;
+        for await (const emitted of this.readStream(response, config.provider)) {
+          yielded = true;
+          yield emitted;
+          if (emitted.type === "done" || emitted.type === "error") { done = true; break; }
         }
         opened.cleanup(); opened = null;
         if (done) return;
@@ -611,6 +609,24 @@ export class Ai {
     }
   }
 
+  private static async *readStream(response: IncomingMessage, provider: Config["provider"]): AsyncGenerator<AiEvent> {
+    const events = parseSseStream(parseLineStream(this.responseChunks(response)));
+    const aggregator = new AggregateState(provider);
+    let yielded = false;
+    try {
+      for await (const sseEvent of events) {
+        for (const emitted of aggregator.consume(sseEvent)) {
+          yielded = true;
+          yield emitted;
+          if (emitted.type === "done" || emitted.type === "error") return;
+        }
+      }
+    } catch (error) {
+      if (!yielded) throw error;
+      yield { type: "error", message: error instanceof AiParseError ? "AI provider returned malformed stream data" : `AI transport failed (${error instanceof Error ? error.name : "Error"})` };
+    }
+  }
+
   private static streamError(error: unknown): AiError {
     if (error instanceof AiError) return error;
     if (error instanceof Error && error.name === "AbortError") return new AiTimeoutError("AI total request timeout expired");
@@ -663,132 +679,154 @@ class AggregateState {
     if (!Array.isArray(choices) || choices.length === 0) return;
     const choice = choices[0];
     const delta = (choice.delta ?? {}) as Record<string, unknown>;
-    const content = delta.content;
-    if (typeof content === "string" && content.length > 0) {
-      yield { type: "text_delta", text: content };
-    }
-    const toolCalls = delta.tool_calls as Array<Record<string, unknown>> | undefined;
-    if (Array.isArray(toolCalls)) {
-      for (const call of toolCalls) {
-        const index = typeof call.index === "number" ? String(call.index) : String(this.toolBuffers.size);
-        const idFromCall = typeof call.id === "string" ? call.id : "";
-        const fn = (call.function ?? {}) as Record<string, unknown>;
-        const nameFromCall = typeof fn.name === "string" ? fn.name : "";
-        const argsFragment = typeof fn.arguments === "string" ? fn.arguments : "";
-        const existing = this.toolBuffers.get(index) ?? { id: "", name: "", args: "" };
-        if (idFromCall) existing.id = idFromCall;
-        if (nameFromCall) existing.name = nameFromCall;
-        existing.args += argsFragment;
-        this.toolBuffers.set(index, existing);
-        if (existing.name && existing.args) {
-          try {
-            const parsed = JSON.parse(existing.args) as unknown;
-            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-              this.toolBuffers.delete(index);
-              yield { type: "tool_call", id: existing.id || `call_${index}`, name: existing.name, args: parsed as Record<string, unknown> };
-            }
-          } catch {
-            /* args not complete yet — keep buffering */
-          }
-        }
-      }
-    }
-    if (typeof choice.finish_reason === "string" && choice.finish_reason.length > 0) {
-      this.lastFinishReason = choice.finish_reason;
-    }
-    const usage = payload.usage as Record<string, unknown> | undefined;
-    if (usage && typeof usage === "object") {
-      const promptTokens = Number(usage.prompt_tokens ?? 0);
-      const completionTokens = Number(usage.completion_tokens ?? 0);
-      const totalTokens = Number(usage.total_tokens ?? promptTokens + completionTokens);
-      if (Number.isFinite(promptTokens) && Number.isFinite(completionTokens)) {
-        this.lastUsage = { promptTokens, completionTokens, totalTokens };
-      }
-    }
+    yield* this.consumeOpenAiContent(delta);
+    yield* this.consumeOpenAiTools(delta);
+    this.updateOpenAiFinishReason(choice);
+    this.updateOpenAiUsage(payload);
   }
 
   private *consumeAnthropic(payload: Record<string, unknown>): Iterable<AiEvent> {
-    const type = payload.type;
-    if (type === "content_block_start") {
-      const block = (payload.content_block ?? {}) as Record<string, unknown>;
-      if (block.type === "tool_use") {
-        const index = String(payload.index ?? this.toolBuffers.size);
-        const id = typeof block.id === "string" ? block.id : `call_${index}`;
-        const name = typeof block.name === "string" ? block.name : "";
-        this.toolBuffers.set(index, { id, name, args: "" });
-      }
-      return;
-    }
-    if (type === "content_block_delta") {
-      const index = String(payload.index ?? 0);
-      const delta = (payload.delta ?? {}) as Record<string, unknown>;
-      if (delta.type === "text_delta" && typeof delta.text === "string" && delta.text.length > 0) {
-        yield { type: "text_delta", text: delta.text };
+    switch (payload.type) {
+      case "content_block_start":
+        this.consumeAnthropicBlockStart(payload);
+        return;
+      case "content_block_delta":
+        yield* this.consumeAnthropicBlockDelta(payload);
+        return;
+      case "content_block_stop":
+        yield* this.consumeAnthropicBlockStop(payload);
+        return;
+      case "message_delta":
+        this.consumeAnthropicMessageDelta(payload);
+        return;
+      case "message_stop":
+        yield* this.consumeAnthropicMessageStop();
+        return;
+      case "message_start":
+        this.consumeAnthropicMessageStart(payload);
+        return;
+      case "error":
+        this.consumeAnthropicError(payload);
         return;
-      }
-      if (delta.type === "input_json_delta" && typeof delta.partial_json === "string") {
-        const existing = this.toolBuffers.get(index);
-        if (existing) existing.args += delta.partial_json;
-      }
-      return;
     }
-    if (type === "content_block_stop") {
-      const index = String(payload.index ?? 0);
-      const existing = this.toolBuffers.get(index);
-      if (existing && existing.name) {
+  }
+
+  private *consumeOpenAiContent(delta: Record<string, unknown>): Iterable<AiEvent> {
+    const content = delta.content;
+    if (typeof content === "string" && content.length > 0) yield { type: "text_delta", text: content };
+  }
+
+  private *consumeOpenAiTools(delta: Record<string, unknown>): Iterable<AiEvent> {
+    const toolCalls = delta.tool_calls as Array<Record<string, unknown>> | undefined;
+    if (!Array.isArray(toolCalls)) return;
+    for (const call of toolCalls) yield* this.consumeOpenAiTool(call);
+  }
+
+  private *consumeOpenAiTool(call: Record<string, unknown>): Iterable<AiEvent> {
+    const index = typeof call.index === "number" ? String(call.index) : String(this.toolBuffers.size);
+    const idFromCall = typeof call.id === "string" ? call.id : "";
+    const fn = (call.function ?? {}) as Record<string, unknown>;
+    const nameFromCall = typeof fn.name === "string" ? fn.name : "";
+    const argsFragment = typeof fn.arguments === "string" ? fn.arguments : "";
+    const existing = this.toolBuffers.get(index) ?? { id: "", name: "", args: "" };
+    if (idFromCall) existing.id = idFromCall;
+    if (nameFromCall) existing.name = nameFromCall;
+    existing.args += argsFragment;
+    this.toolBuffers.set(index, existing);
+    if (!existing.name || !existing.args) return;
+    try {
+      const parsed = JSON.parse(existing.args) as unknown;
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
         this.toolBuffers.delete(index);
-        try {
-          const parsed = existing.args ? JSON.parse(existing.args) : {};
-          if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-            yield { type: "tool_call", id: existing.id, name: existing.name, args: parsed as Record<string, unknown> };
-            return;
-          }
-          throw new Error();
-        } catch {
-          throw new AiParseError("AI provider returned malformed tool-call JSON");
-        }
+        yield { type: "tool_call", id: existing.id || `call_${index}`, name: existing.name, args: parsed as Record<string, unknown> };
       }
-      return;
+    } catch {
+      /* args not complete yet — keep buffering */
     }
-    if (type === "message_delta") {
-      const delta = (payload.delta ?? {}) as Record<string, unknown>;
-      if (typeof delta.stop_reason === "string" && delta.stop_reason.length > 0) {
-        this.lastFinishReason = delta.stop_reason;
-      }
-      const usage = (payload.usage ?? {}) as Record<string, unknown>;
-      if (usage.output_tokens !== undefined || usage.input_tokens !== undefined) {
-        const promptTokens = Number(usage.input_tokens ?? this.lastUsage?.promptTokens ?? 0);
-        const completionTokens = Number(usage.output_tokens ?? this.lastUsage?.completionTokens ?? 0);
-        this.lastUsage = { promptTokens, completionTokens, totalTokens: promptTokens + completionTokens };
-      }
+  }
+
+  private updateOpenAiFinishReason(choice: Record<string, unknown>): void {
+    if (typeof choice.finish_reason === "string" && choice.finish_reason.length > 0) this.lastFinishReason = choice.finish_reason;
+  }
+
+  private updateOpenAiUsage(payload: Record<string, unknown>): void {
+    const usage = payload.usage as Record<string, unknown> | undefined;
+    if (!usage || typeof usage !== "object") return;
+    const promptTokens = Number(usage.prompt_tokens ?? 0);
+    const completionTokens = Number(usage.completion_tokens ?? 0);
+    const totalTokens = Number(usage.total_tokens ?? promptTokens + completionTokens);
+    if (Number.isFinite(promptTokens) && Number.isFinite(completionTokens)) this.lastUsage = { promptTokens, completionTokens, totalTokens };
+  }
+
+  private consumeAnthropicBlockStart(payload: Record<string, unknown>): void {
+    const block = (payload.content_block ?? {}) as Record<string, unknown>;
+    if (block.type !== "tool_use") return;
+    const index = String(payload.index ?? this.toolBuffers.size);
+    const id = typeof block.id === "string" ? block.id : `call_${index}`;
+    const name = typeof block.name === "string" ? block.name : "";
+    this.toolBuffers.set(index, { id, name, args: "" });
+  }
+
+  private *consumeAnthropicBlockDelta(payload: Record<string, unknown>): Iterable<AiEvent> {
+    const index = String(payload.index ?? 0);
+    const delta = (payload.delta ?? {}) as Record<string, unknown>;
+    if (delta.type === "text_delta" && typeof delta.text === "string" && delta.text.length > 0) {
+      yield { type: "text_delta", text: delta.text };
       return;
     }
-    if (type === "message_stop") {
-      if (this.doneEmitted) return;
-      this.doneEmitted = true;
-      yield {
-        type: "done",
-        finishReason: this.lastFinishReason ?? "end_turn",
-        ...(this.lastUsage ? { usage: this.lastUsage } : {}),
-      };
-      return;
+    if (delta.type === "input_json_delta" && typeof delta.partial_json === "string") {
+      const existing = this.toolBuffers.get(index);
+      if (existing) existing.args += delta.partial_json;
     }
-    if (type === "message_start") {
-      const message = (payload.message ?? {}) as Record<string, unknown>;
-      const usage = (message.usage ?? {}) as Record<string, unknown>;
-      if (usage.input_tokens !== undefined || usage.output_tokens !== undefined) {
-        const promptTokens = Number(usage.input_tokens ?? 0);
-        const completionTokens = Number(usage.output_tokens ?? 0);
-        this.lastUsage = { promptTokens, completionTokens, totalTokens: promptTokens + completionTokens };
+  }
+
+  private *consumeAnthropicBlockStop(payload: Record<string, unknown>): Iterable<AiEvent> {
+    const index = String(payload.index ?? 0);
+    const existing = this.toolBuffers.get(index);
+    if (!existing || !existing.name) return;
+    this.toolBuffers.delete(index);
+    try {
+      const parsed = existing.args ? JSON.parse(existing.args) : {};
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        yield { type: "tool_call", id: existing.id, name: existing.name, args: parsed as Record<string, unknown> };
+        return;
       }
-      return;
-    }
-    if (type === "error") {
-      const err = (payload.error ?? {}) as Record<string, unknown>;
-      throw new AiParseError(typeof err.message === "string" ? err.message : "AI provider signalled a stream error");
+      throw new Error();
+    } catch {
+      throw new AiParseError("AI provider returned malformed tool-call JSON");
     }
   }
 
+  private consumeAnthropicMessageDelta(payload: Record<string, unknown>): void {
+    const delta = (payload.delta ?? {}) as Record<string, unknown>;
+    if (typeof delta.stop_reason === "string" && delta.stop_reason.length > 0) this.lastFinishReason = delta.stop_reason;
+    const usage = (payload.usage ?? {}) as Record<string, unknown>;
+    if (usage.output_tokens === undefined && usage.input_tokens === undefined) return;
+    const promptTokens = Number(usage.input_tokens ?? this.lastUsage?.promptTokens ?? 0);
+    const completionTokens = Number(usage.output_tokens ?? this.lastUsage?.completionTokens ?? 0);
+    this.lastUsage = { promptTokens, completionTokens, totalTokens: promptTokens + completionTokens };
+  }
+
+  private *consumeAnthropicMessageStop(): Iterable<AiEvent> {
+    if (this.doneEmitted) return;
+    this.doneEmitted = true;
+    yield { type: "done", finishReason: this.lastFinishReason ?? "end_turn", ...(this.lastUsage ? { usage: this.lastUsage } : {}) };
+  }
+
+  private consumeAnthropicMessageStart(payload: Record<string, unknown>): void {
+    const message = (payload.message ?? {}) as Record<string, unknown>;
+    const usage = (message.usage ?? {}) as Record<string, unknown>;
+    if (usage.input_tokens === undefined && usage.output_tokens === undefined) return;
+    const promptTokens = Number(usage.input_tokens ?? 0);
+    const completionTokens = Number(usage.output_tokens ?? 0);
+    this.lastUsage = { promptTokens, completionTokens, totalTokens: promptTokens + completionTokens };
+  }
+
+  private consumeAnthropicError(payload: Record<string, unknown>): void {
+    const err = (payload.error ?? {}) as Record<string, unknown>;
+    throw new AiParseError(typeof err.message === "string" ? err.message : "AI provider signalled a stream error");
+  }
+
   private *flushRemainingToolCalls(): Iterable<AiEvent> {
     for (const [index, buffered] of this.toolBuffers) {
       if (buffered.name && buffered.args) {

package/packages/core/src/devAdmin.ts

@@ -2069,24 +2069,48 @@ function handleGalleryDeploy(router: Router): RouteHandler {
 // Version check — proxy to npm registry to avoid browser CORS errors
 // ---------------------------------------------------------------------------
 
-const handleVersionCheck: RouteHandler = async (_req, res) => {
+/**
+ * Version check — a check that did not happen says so.
+ *
+ * This used to fall back to `latest = current` on any failure, and the toolbar
+ * renders that as a green "You are up to date!" — so a developer several
+ * releases behind, on a machine with no route out, was told the opposite of the
+ * truth, and the toolbar's own "Could not check for updates" branch could never
+ * fire because the failure arrived as a success. `latest` is `null` when the
+ * check could not be made, and `error` says why. The registry URL is
+ * `TINA4_VERSION_CHECK_URL` when set (a mirror, or a test's own server), else
+ * npm. Mirrors Python `tina4_python.dev_admin._api_version_check`.
+ */
+export const handleVersionCheck: RouteHandler = async (_req, res) => {
   const current = TINA4_VERSION;
-  let latest = current;
+  const url =
+    process.env.TINA4_VERSION_CHECK_URL ||
+    "https://registry.npmjs.org/tina4-nodejs/latest";
+  const failed = (why: string) => res.json({ current, latest: null, error: why });
+
+  let data: Record<string, unknown>;
   try {
     const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 5000);
-    const resp = await fetch("https://registry.npmjs.org/tina4-nodejs/latest", {
-      signal: controller.signal,
-    });
-    clearTimeout(timeout);
-    if (resp.ok) {
-      const data = (await resp.json()) as Record<string, unknown>;
-      if (typeof data.version === "string") latest = data.version;
+    const timer = setTimeout(() => controller.abort(), 5000);
+    try {
+      const resp = await fetch(url, {
+        signal: controller.signal,
+        headers: { "User-Agent": `tina4-nodejs/${current}` },
+      });
+      // Reaching the registry is not the same as a 200 with a body.
+      if (!resp.ok) return failed(`npm registry responded ${resp.status}`);
+      data = (await resp.json()) as Record<string, unknown>;
+    } finally {
+      clearTimeout(timer);
     }
-  } catch {
-    // Offline or timeout — return current as latest
+  } catch (exc) {
+    // offline, timeout, DNS, unreadable body
+    return failed(exc instanceof Error && exc.message ? exc.message : String(exc));
   }
-  res.json({ current, latest });
+  // An answer we cannot read a version out of is the same lie by another route.
+  const latest = typeof data.version === "string" ? data.version : "";
+  if (!latest) return failed("npm registry did not report a version");
+  return res.json({ current, latest });
 };
 
 // ---------------------------------------------------------------------------
@@ -3019,7 +3043,7 @@ function toolbarCss(): string {
  * starts when the toolbar's `data-reload` is "1" (reload not suppressed for this
  * request/port). Mirrors PHP DevAdmin::toolbarJs().
  */
-function toolbarJs(): string {
+export function toolbarJs(): string {
   return `(function () {
     var bar = document.getElementById('tina4-dev-toolbar');
     if (!bar) { return; }
@@ -3029,6 +3053,13 @@ function toolbarJs(): string {
         el.className = 't4-ok';
         el.innerHTML = 'Latest: <strong class="t4-ok">v' + latest + '</strong> &mdash; You are up to date!';
     }
+    // A check that did not happen is not a clean bill of health. The server
+    // sends latest: null when it could not reach the registry, and saying so is
+    // the whole point -- "up to date" here would be a guess dressed as a fact.
+    function couldNotCheck(el, why) {
+        el.className = 't4-err';
+        el.textContent = 'Could not check for updates' + (why ? ' (' + why + ')' : '');
+    }
     function checkVersion() {
         if (modal.style.display === 'block') { modal.style.display = 'none'; return; }
         modal.style.display = 'block';
@@ -3037,6 +3068,7 @@ function toolbarJs(): string {
         el.textContent = 'Checking for updates...';
         fetch('/__dev/api/version-check').then(function (r) { return r.json(); }).then(function (d) {
             var latest = d.latest, current = d.current;
+            if (!latest) { couldNotCheck(el, d.error); return; }
             if (latest === current) { upToDate(el, latest); return; }
             var cP = current.split('.').map(Number), lP = latest.split('.').map(Number);
             var isNewer = false, i, c, l;

package/packages/core/src/dispatchPipeline.ts

@@ -206,6 +206,69 @@ function etagMatchesInm(ifNoneMatch: string, etag: string): boolean {
   });
 }
 
+function maybeCompressResponse(body: Buffer, rawReq: IncomingMessage, rawRes: ServerResponse): Buffer {
+  const acceptEncoding = String(rawReq.headers["accept-encoding"] ?? "");
+  const contentTypeHeader = rawRes.getHeader("content-type");
+  const contentType = typeof contentTypeHeader === "string" ? contentTypeHeader : "";
+  const alreadyEncoded = !!rawRes.getHeader("content-encoding");
+  if (alreadyEncoded || body.length <= 1024 || !acceptEncoding.includes("gzip") || !isCompressibleContentType(contentType)) {
+    return body;
+  }
+  const compressed = gzipSync(body, { level: 6 });
+  rawRes.setHeader("Content-Encoding", "gzip");
+  rawRes.setHeader("Vary", "Accept-Encoding");
+  return compressed;
+}
+
+function responseIsNotModified(rawReq: IncomingMessage, rawRes: ServerResponse, etag: string): boolean {
+  const ifNoneMatch = String(rawReq.headers["if-none-match"] ?? "");
+  if (ifNoneMatch) return etagMatchesInm(ifNoneMatch, etag);
+  const lastModifiedHeader = rawRes.getHeader("last-modified");
+  if (typeof lastModifiedHeader !== "string") return false;
+  const ifModifiedSince = String(rawReq.headers["if-modified-since"] ?? "");
+  if (!ifModifiedSince) return false;
+  const modified = Date.parse(lastModifiedHeader);
+  const since = Date.parse(ifModifiedSince);
+  return !Number.isNaN(modified) && !Number.isNaN(since) && modified <= since;
+}
+
+function clearNotModifiedHeaders(rawRes: ServerResponse): void {
+  rawRes.statusCode = 304;
+  rawRes.removeHeader("Content-Type");
+  rawRes.removeHeader("Content-Encoding");
+  rawRes.removeHeader("Vary");
+  rawRes.removeHeader("Content-Length");
+}
+
+function applyResponseValidator(rawReq: IncomingMessage, rawRes: ServerResponse, body: Buffer): boolean {
+  if ((rawRes.statusCode || 200) !== 200 || body.length === 0) return false;
+  let etag = rawRes.getHeader("etag");
+  if (!etag) {
+    etag = `"${createHash("md5").update(body).digest("hex").slice(0, 16)}"`;
+    rawRes.setHeader("ETag", etag);
+  }
+  if (!responseIsNotModified(rawReq, rawRes, String(etag))) return false;
+  clearNotModifiedHeaders(rawRes);
+  return true;
+}
+
+function endBufferedResponse(
+  rawReq: IncomingMessage,
+  rawRes: ServerResponse,
+  body: Buffer,
+  realCb: ((...args: any[]) => void) | undefined,
+  origEnd: (...args: any[]) => any,
+): any {
+  const finalBody = maybeCompressResponse(body, rawReq, rawRes);
+  if (applyResponseValidator(rawReq, rawRes, finalBody)) {
+    return typeof realCb === "function" ? origEnd(realCb) : origEnd();
+  }
+  if (!rawRes.headersSent && (rawRes.statusCode || 200) !== 304) {
+    rawRes.setHeader("Content-Length", finalBody.length);
+  }
+  return typeof realCb === "function" ? origEnd(finalBody, realCb) : origEnd(finalBody);
+}
+
 /**
  * Gzip-compress + attach an ETag, and answer a matching conditional GET with
  * a 304 that PRESERVES whichever validators the 200 would have carried
@@ -276,74 +339,9 @@ export function compressionEtagIntercept(rawReq: IncomingMessage, rawRes: Server
 
     const buf = toBuffer(chunk, typeof encodingOrCb === "string" ? encodingOrCb : undefined);
     if (buf) chunks.push(buf);
-    let body = chunks.length > 0 ? Buffer.concat(chunks) : Buffer.alloc(0);
     const realCb = typeof encodingOrCb === "function" ? encodingOrCb : cb;
-    const statusCode = rawRes.statusCode || 200;
-
-    // Compression: body > 1024 bytes AND Accept-Encoding offers gzip AND the
-    // content type is compressible. Applies to ANY response (matches every
-    // route, not status-gated), same as the Python master.
-    //
-    // REAL BUG (found 2026-08-13, tina4cssServed.test.ts): a static-file
-    // response (static.ts) already gzips itself and sets Content-Encoding
-    // before calling res.raw.end() — but that end() is THIS intercepted one,
-    // so without the guard below it gzipped an already-gzipped body a second
-    // time. The client's one layer of automatic decompression then handed
-    // back a still-gzipped blob instead of the real bytes. Skip compression
-    // here whenever an earlier stage already set Content-Encoding.
-    const acceptEncoding = String(rawReq.headers["accept-encoding"] ?? "");
-    const contentTypeHeader = rawRes.getHeader("content-type");
-    const contentType = typeof contentTypeHeader === "string" ? contentTypeHeader : "";
-    const alreadyEncoded = !!rawRes.getHeader("content-encoding");
-    if (!alreadyEncoded && body.length > 1024 && acceptEncoding.includes("gzip") && isCompressibleContentType(contentType)) {
-      body = gzipSync(body, { level: 6 });
-      rawRes.setHeader("Content-Encoding", "gzip");
-      rawRes.setHeader("Vary", "Accept-Encoding");
-    }
-
-    if (statusCode === 200 && body.length > 0) {
-      // ETag: a strong md5 hash (first 16 hex chars) over the FINAL
-      // (post-compression) body, UNLESS a validator is already set — a
-      // static-file response (static.ts) pins its own weak size+mtime ETag
-      // before this ever runs (CE-DEC-02), so this never overwrites it with
-      // a content hash.
-      let etag = rawRes.getHeader("etag");
-      if (!etag) {
-        etag = `"${createHash("md5").update(body).digest("hex").slice(0, 16)}"`;
-        rawRes.setHeader("ETag", etag);
-      }
-
-      // Conditional GET -> 304, preserving whichever validators are set.
-      // If-None-Match takes precedence over If-Modified-Since (RFC 9110 S13.1.3).
-      const ifNoneMatch = String(rawReq.headers["if-none-match"] ?? "");
-      const lastModifiedHeader = rawRes.getHeader("last-modified");
-      const lastModified = typeof lastModifiedHeader === "string" ? lastModifiedHeader : "";
-      let notModified = false;
-      if (ifNoneMatch) {
-        notModified = etagMatchesInm(ifNoneMatch, String(etag));
-      } else if (lastModified) {
-        const ifModifiedSince = String(rawReq.headers["if-modified-since"] ?? "");
-        if (ifModifiedSince) {
-          const modified = Date.parse(lastModified);
-          const since = Date.parse(ifModifiedSince);
-          notModified = !Number.isNaN(modified) && !Number.isNaN(since) && modified <= since;
-        }
-      }
-
-      if (notModified) {
-        rawRes.statusCode = 304;
-        rawRes.removeHeader("Content-Type");
-        rawRes.removeHeader("Content-Encoding");
-        rawRes.removeHeader("Vary");
-        rawRes.removeHeader("Content-Length");
-        return typeof realCb === "function" ? origEnd(realCb) : origEnd();
-      }
-    }
-
-    if (!rawRes.headersSent && statusCode !== 304) {
-      rawRes.setHeader("Content-Length", body.length);
-    }
-    return typeof realCb === "function" ? origEnd(body, realCb) : origEnd(body);
+    const body = chunks.length > 0 ? Buffer.concat(chunks) : Buffer.alloc(0);
+    return endBufferedResponse(rawReq, rawRes, body, realCb, origEnd);
   }) as typeof rawRes.end;
 }