fix(webapp): recognize object-store 404 by status code for missing transcripts

Aws4FetchClient download errors now carry the HTTP status, and
isTranscriptNotFound checks status 404 first so an empty reason
phrase no longer surfaces as a 502.

Fixes #4984

Author: mahenoorsalat

.server-changes/fix-transcript-404-empty-reason-phrase.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: fix
+---
+
+Fix missing session transcripts returning a download error instead of a not-found response

apps/webapp/app/services/realtime/transcriptDownload.server.test.ts

@@ -1,4 +1,5 @@
 import { createServer, type Server } from "node:http";
+import { createServer as createTcpServer, type Server as TcpServer } from "node:net";
 import { once } from "node:events";
 import express from "express";
 import { sendRemixResponse } from "@remix-run/express/dist/server";
@@ -114,6 +115,34 @@ test("does not treat permission or service failures as an absent transcript", ()
   ).toBe(false);
   expect(isTranscriptNotFound({ $metadata: { httpStatusCode: 503 } })).toBe(false);
   expect(isTranscriptNotFound({ name: "NoSuchKey" })).toBe(true);
+  expect(isTranscriptNotFound({ status: 404, message: "Failed to download from object store: " })).toBe(
+    true
+  );
+});
+
+test("recognizes a 404 with an empty reason phrase as a missing transcript", async () => {
+  const server: TcpServer = createTcpServer((socket) => {
+    socket.once("data", () => {
+      socket.end("HTTP/1.1 404 \r\nContent-Length: 0\r\nConnection: close\r\n\r\n");
+    });
+  });
+  server.listen(0, "127.0.0.1");
+  await once(server, "listening");
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Expected TCP listener");
+  const baseUrl = `http://127.0.0.1:${address.port}`;
+  try {
+    const client = ObjectStoreClient.create({
+      baseUrl,
+      accessKeyId: "test",
+      secretAccessKey: "test",
+      service: "s3",
+    });
+    await expect(client.getObjectResponse(key)).rejects.toSatisfy(isTranscriptNotFound);
+  } finally {
+    server.close();
+    await once(server, "close");
+  }
 });
 
 minioTest(

apps/webapp/app/services/realtime/transcriptDownload.server.ts

@@ -45,8 +45,16 @@ export function downloadTranscript(
 
 export function isTranscriptNotFound(error: unknown): boolean {
   if (!error || typeof error !== "object") return false;
-  const { name, $metadata } = error as { name?: string; $metadata?: { httpStatusCode?: number } };
+  const { name, $metadata, status } = error as {
+    name?: string;
+    $metadata?: { httpStatusCode?: number };
+    status?: unknown;
+  };
   if (name === "NoSuchKey" || name === "NotFound" || $metadata?.httpStatusCode === 404) return true;
+  // The aws4fetch adapter reports the HTTP status on the error. Check it first:
+  // S3-compatible stores may return an empty reason phrase, so the message alone
+  // cannot distinguish a 404 from other failures.
+  if (status === 404) return true;
   // The aws4fetch adapter currently reports the HTTP status text in its error.
   return (
     error instanceof Error &&

apps/webapp/app/v3/objectStoreClient.server.ts

@@ -58,6 +58,24 @@ export class ObjectVersionChangedError extends Error {
   }
 }
 
+/**
+ * A failed object-store download that preserves the HTTP status code.
+ * Callers must not rely on `statusText`: S3-compatible stores may return an
+ * empty reason phrase (e.g. `HTTP/1.1 404 `), which yields an empty message
+ * suffix and breaks message-based 404 detection.
+ */
+export class ObjectStoreDownloadError extends Error {
+  readonly status: number;
+  readonly statusText: string;
+
+  constructor(message: string, status: number, statusText: string) {
+    super(message);
+    this.name = "ObjectStoreDownloadError";
+    this.status = status;
+    this.statusText = statusText;
+  }
+}
+
 /** `Range` header value for a byte range or a suffix. */
 function rangeHeader(range: { suffixLength: number } | { start: number; end: number }): string {
   return "suffixLength" in range
@@ -120,7 +138,11 @@ class Aws4FetchClient implements IObjectStoreClient {
   async getObject(key: string): Promise<string> {
     const response = await this.awsClient.fetch(this.buildUrl(key));
     if (!response.ok) {
-      throw new Error(`Failed to download from object store: ${response.statusText}`);
+      throw new ObjectStoreDownloadError(
+        `Failed to download from object store: ${response.statusText}`,
+        response.status,
+        response.statusText
+      );
     }
     return response.text();
   }
@@ -135,7 +157,11 @@ class Aws4FetchClient implements IObjectStoreClient {
   async getObjectResponse(key: string): Promise<Response> {
     const response = await this.awsClient.fetch(this.buildUrl(key));
     if (!response.ok) {
-      throw new Error(`Failed to download from object store: ${response.statusText}`);
+      throw new ObjectStoreDownloadError(
+        `Failed to download from object store: ${response.statusText}`,
+        response.status,
+        response.statusText
+      );
     }
     return response;
   }
@@ -155,7 +181,11 @@ class Aws4FetchClient implements IObjectStoreClient {
       throw new ObjectVersionChangedError(key);
     }
     if (!response.ok) {
-      throw new Error(`Failed to download range from object store: ${response.statusText}`);
+      throw new ObjectStoreDownloadError(
+        `Failed to download range from object store: ${response.statusText}`,
+        response.status,
+        response.statusText
+      );
     }
     const bytes = new Uint8Array(await response.arrayBuffer());
     return {