Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

fix(web): recover cold link preview thumbnails (#569)

Gustavo Yec7e04307e2c5
diff --git a/src/web/src/app/api/community/link-preview/thumbnail/[digest]/route.test.ts b/src/web/src/app/api/community/link-preview/thumbnail/[digest]/route.test.ts
index 1d30b0e21..38304dc66 100644
--- a/src/web/src/app/api/community/link-preview/thumbnail/[digest]/route.test.ts
+++ b/src/web/src/app/api/community/link-preview/thumbnail/[digest]/route.test.ts
@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from "vitest"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
import { NextRequest } from "next/server"
const DIGEST = "a".repeat(64)
@@ -14,6 +14,7 @@ const mockImagesInfo = vi.fn()
const mockImagesInput = vi.fn()
const mockImagesTransform = vi.fn()
const mockImagesOutput = vi.fn()
+const mockLogError = vi.fn()
let includeKv = true
let includeImages = true
@@ -25,6 +26,10 @@ vi.mock("@/lib/rate-limit", () => ({
checkRateLimit: (...args: unknown[]) => mockCheckRateLimit(...args),
}))
+vi.mock("@/lib/logger", () => ({
+ log: { error: (...args: unknown[]) => mockLogError(...args) },
+}))
+
vi.mock("@/lib/middleware/auth", () => ({
withAuth: (handler: (...args: any[]) => unknown) => (req: NextRequest, context?: { params?: Record<string, string> }) => {
const env: Record<string, unknown> = {
@@ -48,6 +53,11 @@ vi.mock("@/lib/middleware/auth", () => ({
import { GET } from "./route"
+afterEach(() => {
+ vi.useRealTimers()
+ vi.unstubAllGlobals()
+})
+
function stream(bytes: Uint8Array, cancel?: () => void): ReadableStream<Uint8Array> {
return new ReadableStream<Uint8Array>({
start(controller) {
@@ -138,6 +148,7 @@ describe("GET /api/community/link-preview/thumbnail/[digest]", () => {
expect(mockR2Get).not.toHaveBeenCalled()
expect(mockCheckRateLimit).not.toHaveBeenCalled()
expect(fetch).not.toHaveBeenCalled()
+ expect(mockLogError).not.toHaveBeenCalled()
})
it.each([
@@ -165,6 +176,28 @@ describe("GET /api/community/link-preview/thumbnail/[digest]", () => {
expect(response.headers.get("cache-control")).toBe("no-store")
expect(mockCheckRateLimit).not.toHaveBeenCalled()
expect(fetch).not.toHaveBeenCalled()
+ expect(mockLogError).toHaveBeenCalledWith("link_preview_thumbnail_failure", expect.objectContaining({
+ stage: "storage",
+ disposition: "transient",
+ }))
+ })
+
+ it.each([
+ [Object.assign(new Error("coded storage error"), { code: "R2_TEMP" }), "storage_r2_temp"],
+ ["unknown storage error", "storage_error"],
+ ])("logs a stable storage code without exposing the raw failure", async (error, errorCode) => {
+ mockR2Get.mockRejectedValueOnce(error)
+
+ const response = await request()
+
+ expect(response.status).toBe(404)
+ expect(mockLogError).toHaveBeenCalledWith("link_preview_thumbnail_failure", expect.objectContaining({
+ stage: "storage",
+ disposition: "transient",
+ errorCode,
+ }))
+ expect(JSON.stringify(mockLogError.mock.calls)).not.toContain("coded storage error")
+ expect(JSON.stringify(mockLogError.mock.calls)).not.toContain("unknown storage error")
})
it("serves a valid R2 WebP hit without rate limiting, network, or Images work", async () => {
@@ -255,6 +288,10 @@ describe("GET /api/community/link-preview/thumbnail/[digest]", () => {
expect(response.headers.get("cache-control")).toBe("no-store")
expect(mockCheckRateLimit).not.toHaveBeenCalled()
expect(fetch).not.toHaveBeenCalled()
+ expect(mockLogError).toHaveBeenCalledWith("link_preview_thumbnail_failure", expect.objectContaining({
+ stage: "storage",
+ disposition: "transient",
+ }))
})
it("honors the five-minute negative cache before rate limiting or outbound work", async () => {
@@ -305,7 +342,9 @@ describe("GET /api/community/link-preview/thumbnail/[digest]", () => {
.mockResolvedValueOnce(manifestObject({ sourceDigest }))
.mockResolvedValueOnce(null)
mockKvGet.mockRejectedValueOnce(new Error("KV read unavailable"))
- vi.mocked(fetch).mockRejectedValueOnce(new Error("origin unavailable"))
+ vi.mocked(fetch).mockResolvedValueOnce(new Response(new Uint8Array([1, 2, 3]), {
+ headers: { "content-type": "image/gif" },
+ }))
mockKvPut.mockRejectedValueOnce(new Error("KV write unavailable"))
const response = await request()
@@ -317,7 +356,34 @@ describe("GET /api/community/link-preview/thumbnail/[digest]", () => {
await expect(backgroundWrite).resolves.toBeUndefined()
})
- it("folds upstream, transform, and R2 write failures into an image-only 404 and negative cache", async () => {
+ it("negative-caches a deterministic rejection while preserving the indistinguishable 404", async () => {
+ mockR2Get
+ .mockResolvedValueOnce(manifestObject({ sourceDigest }))
+ .mockResolvedValueOnce(null)
+ vi.mocked(fetch).mockResolvedValueOnce(new Response(new Uint8Array([1, 2, 3]), {
+ headers: { "content-type": "image/gif" },
+ }))
+
+ const response = await request()
+
+ expect(response.status).toBe(404)
+ expect(response.headers.get("cache-control")).toBe("no-store")
+ expect(mockKvPut).toHaveBeenCalledOnce()
+ expect(mockKvPut).toHaveBeenCalledWith(
+ `link-preview-thumbnail-negative:v1:${DIGEST}:${sourceDigest}`,
+ "1",
+ { expirationTtl: 300 },
+ )
+ expect(mockWaitUntil).toHaveBeenCalledWith(expect.any(Promise))
+ expect(mockLogError).toHaveBeenCalledWith("link_preview_thumbnail_failure", expect.objectContaining({
+ stage: "source",
+ disposition: "deterministic",
+ errorCode: "source_mime",
+ pageDigestPrefix: DIGEST.slice(0, 12),
+ }))
+ })
+
+ it("does not negative-cache source, Images, or R2 transient failures", async () => {
for (const fail of [
() => vi.mocked(fetch).mockRejectedValueOnce(new Error("origin unavailable")),
() => mockImagesInfo.mockRejectedValueOnce(new Error("decode failed")),
@@ -332,17 +398,89 @@ describe("GET /api/community/link-preview/thumbnail/[digest]", () => {
expect(response.status).toBe(404)
expect(response.headers.get("cache-control")).toBe("no-store")
- expect(mockKvPut).toHaveBeenLastCalledWith(
- `link-preview-thumbnail-negative:v1:${DIGEST}:${sourceDigest}`,
- "1",
- { expirationTtl: 300 },
- )
- expect(mockWaitUntil).toHaveBeenLastCalledWith(expect.any(Promise))
+ expect(mockKvPut).not.toHaveBeenCalled()
+ expect(mockWaitUntil).not.toHaveBeenCalled()
vi.mocked(fetch).mockResolvedValue(new Response(new Uint8Array([1, 2, 3]), {
headers: { "content-type": "image/jpeg" },
}))
mockImagesInfo.mockResolvedValue({ format: "image/jpeg", fileSize: 3, width: 1200, height: 630 })
mockR2Put.mockResolvedValue(undefined)
}
+ expect(mockLogError).toHaveBeenNthCalledWith(1, "link_preview_thumbnail_failure", expect.objectContaining({
+ stage: "source",
+ disposition: "transient",
+ }))
+ expect(mockLogError).toHaveBeenNthCalledWith(2, "link_preview_thumbnail_failure", expect.objectContaining({
+ stage: "inspect",
+ disposition: "transient",
+ }))
+ expect(mockLogError).toHaveBeenNthCalledWith(3, "link_preview_thumbnail_failure", expect.objectContaining({
+ stage: "storage",
+ disposition: "transient",
+ }))
+ })
+
+ it("sanitizes an unexpected synchronous storage binding failure without negative caching", async () => {
+ mockR2Get
+ .mockResolvedValueOnce(manifestObject({ sourceDigest }))
+ .mockResolvedValueOnce(null)
+ mockR2Put.mockImplementationOnce(() => {
+ throw "raw synchronous storage failure"
+ })
+
+ const response = await request()
+
+ expect(response.status).toBe(404)
+ expect(response.headers.get("cache-control")).toBe("no-store")
+ expect(mockKvPut).not.toHaveBeenCalled()
+ expect(mockWaitUntil).not.toHaveBeenCalled()
+ expect(mockLogError).toHaveBeenCalledWith("link_preview_thumbnail_failure", expect.objectContaining({
+ stage: "transform",
+ disposition: "transient",
+ errorCode: "transform_unknown",
+ pageDigestPrefix: DIGEST.slice(0, 12),
+ }))
+ expect(JSON.stringify(mockLogError.mock.calls)).not.toContain("raw synchronous storage failure")
+ })
+
+ it("bounds R2 persistence at two seconds and safely observes late rejection", async () => {
+ vi.useFakeTimers()
+ mockR2Get
+ .mockResolvedValueOnce(manifestObject({ sourceDigest }))
+ .mockResolvedValueOnce(null)
+ mockR2Put.mockImplementationOnce(() => new Promise((_resolve, reject) => {
+ setTimeout(() => reject(new Error("late R2 failure")), 3_000)
+ }))
+
+ const result = request()
+ await vi.waitFor(() => expect(mockR2Put).toHaveBeenCalledOnce(), { interval: 1, timeout: 100 })
+ await vi.advanceTimersByTimeAsync(2_000)
+ const response = await result
+
+ expect(response.status).toBe(404)
+ expect(mockKvPut).not.toHaveBeenCalled()
+ expect(mockLogError).toHaveBeenCalledWith("link_preview_thumbnail_failure", expect.objectContaining({
+ stage: "storage",
+ disposition: "transient",
+ errorCode: "storage_timeout",
+ elapsedMs: 2_000,
+ }))
+ await vi.advanceTimersByTimeAsync(1_000)
+ })
+
+ it("logs only sanitized stage evidence", async () => {
+ mockR2Get
+ .mockResolvedValueOnce(manifestObject({ sourceDigest }))
+ .mockResolvedValueOnce(null)
+ vi.mocked(fetch).mockRejectedValueOnce(new Error(`failed ${SOURCE} ${sourceDigest}`))
+
+ await request()
+
+ const serialized = JSON.stringify(mockLogError.mock.calls)
+ expect(serialized).toContain("link_preview_thumbnail_failure")
+ expect(serialized).toContain(DIGEST.slice(0, 12))
+ expect(serialized).not.toContain(SOURCE)
+ expect(serialized).not.toContain(sourceDigest)
+ expect(serialized).not.toContain(`link-preview-thumbnails/v1/${DIGEST}`)
})
})
diff --git a/src/web/src/app/api/community/link-preview/thumbnail/[digest]/route.ts b/src/web/src/app/api/community/link-preview/thumbnail/[digest]/route.ts
index d453917da..402bd2265 100644
--- a/src/web/src/app/api/community/link-preview/thumbnail/[digest]/route.ts
+++ b/src/web/src/app/api/community/link-preview/thumbnail/[digest]/route.ts
@@ -2,10 +2,12 @@ import { NextResponse, type NextRequest } from "next/server"
import { getCloudflareContext } from "@opennextjs/cloudflare"
import { withAuth } from "@/lib/middleware/auth"
import { checkRateLimit } from "@/lib/rate-limit"
+import { log } from "@/lib/logger"
import {
fetchAndTransformLinkPreviewThumbnail,
isFreshLinkPreviewThumbnailObject,
isLinkPreviewThumbnailDigest,
+ LinkPreviewThumbnailFailure,
linkPreviewThumbnailNegativeKey,
linkPreviewThumbnailObjectKey,
linkPreviewThumbnailObjectMetadata,
@@ -14,6 +16,63 @@ import {
const NEGATIVE_TTL_SECONDS = 5 * 60
const PRIVATE_THUMBNAIL_CACHE = "private, max-age=21600, immutable"
+const STORAGE_TIMEOUT_MS = 2_000
+
+function stableStorageCode(error: unknown): string {
+ if (typeof error === "object" && error !== null) {
+ const value = error as { code?: unknown; name?: unknown }
+ if ((typeof value.code === "string" || typeof value.code === "number")
+ && /^[a-zA-Z0-9_.-]{1,64}$/.test(String(value.code))) {
+ return `storage_${String(value.code).toLowerCase()}`
+ }
+ if (typeof value.name === "string" && /^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/.test(value.name)) {
+ return `storage_${value.name.toLowerCase()}`
+ }
+ }
+ return "storage_error"
+}
+
+function storageFailure(error: unknown, startedAt: number): LinkPreviewThumbnailFailure {
+ return new LinkPreviewThumbnailFailure({
+ stage: "storage",
+ disposition: "transient",
+ code: stableStorageCode(error),
+ elapsedMs: Math.max(0, Date.now() - startedAt),
+ message: "thumbnail storage operation failed",
+ })
+}
+
+async function withStorageDeadline<T>(promise: Promise<T>, startedAt: number): Promise<T> {
+ let timer: ReturnType<typeof setTimeout> | undefined
+ const observed = promise.catch((error) => {
+ throw storageFailure(error, startedAt)
+ })
+ observed.catch(() => {})
+ const timeout = new Promise<never>((_resolve, reject) => {
+ timer = setTimeout(() => reject(new LinkPreviewThumbnailFailure({
+ stage: "storage",
+ disposition: "transient",
+ code: "storage_timeout",
+ elapsedMs: Math.max(0, Date.now() - startedAt),
+ message: "thumbnail storage operation timed out",
+ })), STORAGE_TIMEOUT_MS)
+ })
+ try {
+ return await Promise.race([observed, timeout])
+ } finally {
+ if (timer !== undefined) clearTimeout(timer)
+ }
+}
+
+function logThumbnailFailure(pageDigest: string, error: LinkPreviewThumbnailFailure): void {
+ log.error("link_preview_thumbnail_failure", {
+ stage: error.stage,
+ disposition: error.disposition,
+ errorCode: error.code,
+ elapsedMs: error.elapsedMs,
+ pageDigestPrefix: pageDigest.slice(0, 12),
+ })
+}
function notFound(): NextResponse {
return NextResponse.json({ error: "thumbnail not found" }, {
@@ -43,24 +102,28 @@ export const GET = withAuth(async (_req: NextRequest, ctx) => {
if (!isLinkPreviewThumbnailDigest(pageDigest)) return notFound()
let manifest
+ const manifestReadStartedAt = Date.now()
try {
manifest = await readLinkPreviewThumbnailManifest({
bucket: ctx.env.COMMUNITY_MEDIA,
pageDigest,
})
- } catch {
+ } catch (error) {
+ logThumbnailFailure(pageDigest, storageFailure(error, manifestReadStartedAt))
return notFound()
}
if (!manifest) return notFound()
const objectKey = linkPreviewThumbnailObjectKey(pageDigest)
+ const objectReadStartedAt = Date.now()
try {
const cached = await ctx.env.COMMUNITY_MEDIA.get(objectKey)
if (cached && isFreshLinkPreviewThumbnailObject(cached, manifest)) {
return thumbnailResponse(cached.body)
}
await cached?.body.cancel().catch(() => {})
- } catch {
+ } catch (error) {
+ logThumbnailFailure(pageDigest, storageFailure(error, objectReadStartedAt))
return notFound()
}
@@ -79,16 +142,35 @@ export const GET = withAuth(async (_req: NextRequest, ctx) => {
try {
const images = ctx.env.IMAGES
- if (!images) throw new Error("Images binding unavailable")
+ if (!images) {
+ throw new LinkPreviewThumbnailFailure({
+ stage: "transform",
+ disposition: "transient",
+ code: "transform_binding_missing",
+ elapsedMs: 0,
+ message: "Images binding unavailable",
+ })
+ }
const bytes = await fetchAndTransformLinkPreviewThumbnail(manifest.sourceUrl, images)
- await ctx.env.COMMUNITY_MEDIA.put(
+ const storageStartedAt = Date.now()
+ await withStorageDeadline(ctx.env.COMMUNITY_MEDIA.put(
objectKey,
bytes,
linkPreviewThumbnailObjectMetadata(manifest),
- )
+ ), storageStartedAt)
return thumbnailResponse(bytes.slice().buffer as ArrayBuffer)
- } catch {
- if (kv) {
+ } catch (error) {
+ const thumbnailFailure = error instanceof LinkPreviewThumbnailFailure
+ ? error
+ : new LinkPreviewThumbnailFailure({
+ stage: "transform",
+ disposition: "transient",
+ code: "transform_unknown",
+ elapsedMs: 0,
+ message: "thumbnail generation failed",
+ })
+ logThumbnailFailure(pageDigest, thumbnailFailure)
+ if (kv && thumbnailFailure.disposition === "deterministic") {
const write = kv.put(negativeKey, "1", { expirationTtl: NEGATIVE_TTL_SECONDS }).catch(() => {
// A negative-cache outage must not turn an image-only miss into a 500.
})
@@ -100,4 +182,5 @@ export const GET = withAuth(async (_req: NextRequest, ctx) => {
export const LINK_PREVIEW_THUMBNAIL_RESPONSE_HEADERS = {
cacheControl: PRIVATE_THUMBNAIL_CACHE,
+ storageTimeoutMs: STORAGE_TIMEOUT_MS,
} as const
diff --git a/src/web/src/components/community/messages/link-preview-card.test.ts b/src/web/src/components/community/messages/link-preview-card.test.ts
index a1290fe35..273ac916f 100644
--- a/src/web/src/components/community/messages/link-preview-card.test.ts
+++ b/src/web/src/components/community/messages/link-preview-card.test.ts
@@ -1,35 +1,72 @@
import { createElement } from "react"
import { renderToStaticMarkup } from "react-dom/server"
import { act, create, type ReactTestRenderer } from "react-test-renderer"
-import { describe, expect, it } from "vitest"
+import { afterEach, describe, expect, it, vi } from "vitest"
import { tid } from "@/lib/community/testids"
import { LinkPreviewCardView, linkPreviewStaleTime } from "./link-preview-card"
+const THUMBNAIL_URL = `/api/community/link-preview/thumbnail/${"a".repeat(64)}`
+const PREVIEW = {
+ url: "https://github.com/alookai/alook/pull/511",
+ hostname: "github.com",
+ siteName: "GitHub",
+ title: "Pull Request #511",
+ description: "Rooms for people and agents.",
+ thumbnailUrl: THUMBNAIL_URL,
+}
+
+afterEach(() => {
+ vi.useRealTimers()
+})
+
+function renderPreview(preview = PREVIEW): ReactTestRenderer {
+ let renderer!: ReactTestRenderer
+ act(() => {
+ renderer = create(createElement(LinkPreviewCardView, { preview }))
+ })
+ return renderer
+}
+
describe("LinkPreviewCardView", () => {
- it("renders a safe thumbnail in the shared Card as one external link without metadata", () => {
- const html = renderToStaticMarkup(createElement(LinkPreviewCardView, {
- preview: {
- url: "https://github.com/alookai/alook/pull/511",
- hostname: "github.com",
- siteName: "GitHub",
- title: "Pull Request #511",
- description: "Rooms for people and agents.",
- thumbnailUrl: "/api/community/link-preview/thumbnail/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
- },
- }))
+ it("mounts only a layout-free preload until the thumbnail loads, then reveals the existing card", () => {
+ const renderer = renderPreview()
+ const preload = renderer.root.findByType("img")
+
+ expect(preload.props).toMatchObject({
+ "data-testid": tid.linkPreviewThumbnail,
+ src: THUMBNAIL_URL,
+ alt: "",
+ width: 640,
+ height: 360,
+ loading: "eager",
+ decoding: "async",
+ referrerPolicy: "no-referrer",
+ "aria-hidden": "true",
+ })
+ expect(preload.props.className).not.toContain("aspect-video")
+ expect(renderer.root.findAllByType("a")).toHaveLength(0)
+ expect(renderer.root.findAll((node) => node.props["data-testid"] === tid.linkPreviewCard)).toHaveLength(0)
+ expect(renderer.root.findAll((node) => node.props["data-slot"] === "card")).toHaveLength(0)
+
+ act(() => preload.props.onLoad())
- expect(html).toContain('href="https://github.com/alookai/alook/pull/511"')
- expect(html).toContain(`data-testid="${tid.linkPreviewCard}"`)
- expect(html).toContain('target="_blank"')
- expect(html).toContain('rel="noopener noreferrer"')
- expect(html).toContain('aria-label="Open link preview: Pull Request #511"')
- expect(html).toContain('data-slot="card"')
- expect(html).toContain('class="pb-2"')
- expect(html).toContain("w-full max-w-96")
- expect(html).toContain("pointer-events-none absolute top-2 right-2")
- expect(html).toContain('aria-hidden="true"')
- expect(html).not.toContain(">GitHub<")
- expect(html).not.toContain("Rooms for people and agents.")
+ const link = renderer.root.findByType("a")
+ const image = renderer.root.findByType("img")
+ expect(link.props).toMatchObject({
+ href: PREVIEW.url,
+ target: "_blank",
+ rel: "noopener noreferrer",
+ "aria-label": "Open link preview: Pull Request #511",
+ "data-testid": tid.linkPreviewCard,
+ })
+ expect(image.props).toMatchObject({
+ src: THUMBNAIL_URL,
+ loading: "lazy",
+ referrerPolicy: "no-referrer",
+ className: "aspect-video w-full bg-muted object-cover",
+ })
+ expect(renderer.root.findAll((node) => node.props["data-slot"] === "card")).toHaveLength(1)
+ expect(renderer.root.findAll((node) => node.type === "div" && node.props.className === "pb-2")).toHaveLength(1)
})
it("keeps positive previews fresh for 6h but retries negative results after 5m", () => {
@@ -60,40 +97,60 @@ describe("LinkPreviewCardView", () => {
expect(html).toBe("")
})
- it("renders only the same-origin thumbnail path and never the upstream image URL", () => {
- const html = renderToStaticMarkup(createElement(LinkPreviewCardView, {
- preview: {
- url: "https://github.com/alookai/alook/pull/511",
- hostname: "github.com",
- title: "Pull Request #511",
- thumbnailUrl: "/api/community/link-preview/thumbnail/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
- },
- }))
+ it("retries the identical digest URL after one and three seconds, then stops", async () => {
+ vi.useFakeTimers()
+ const renderer = renderPreview()
+ const first = renderer.root.findByType("img")
- expect(html).toContain(`data-testid="${tid.linkPreviewThumbnail}"`)
- expect(html).toContain('src="/api/community/link-preview/thumbnail/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"')
- expect(html).toContain('width="640"')
- expect(html).toContain('height="360"')
- expect(html).not.toContain("avatars.githubusercontent.com")
+ act(() => first.props.onError())
+ await act(() => vi.advanceTimersByTimeAsync(999))
+ expect(renderer.root.findByType("img")).toBe(first)
+ await act(() => vi.advanceTimersByTimeAsync(1))
+ const second = renderer.root.findByType("img")
+ expect(second).not.toBe(first)
+ expect(second.props.src).toBe(THUMBNAIL_URL)
+ expect(second.props.src).not.toContain("?")
+
+ act(() => second.props.onError())
+ await act(() => vi.advanceTimersByTimeAsync(2_999))
+ expect(renderer.root.findByType("img")).toBe(second)
+ await act(() => vi.advanceTimersByTimeAsync(1))
+ const third = renderer.root.findByType("img")
+ expect(third).not.toBe(second)
+ expect(third.props.src).toBe(THUMBNAIL_URL)
+
+ act(() => third.props.onError())
+ expect(renderer.root.findAllByType("img")).toHaveLength(0)
+ expect(renderer.root.findAllByType("a")).toHaveLength(0)
})
- it("removes the whole redundant card after an image load failure", () => {
- let renderer: ReactTestRenderer
+ it("cancels a pending retry on success, URL change, and unmount", async () => {
+ vi.useFakeTimers()
+ const renderer = renderPreview()
+ const first = renderer.root.findByType("img")
+ act(() => first.props.onError())
+ act(() => first.props.onLoad())
+ await act(() => vi.advanceTimersByTimeAsync(5_000))
+ expect(renderer.root.findByType("a").props.href).toBe(PREVIEW.url)
+
+ const nextThumbnailUrl = `/api/community/link-preview/thumbnail/${"b".repeat(64)}`
act(() => {
- renderer = create(createElement(LinkPreviewCardView, { preview: {
- url: "https://example.com/story",
- hostname: "example.com",
- title: "Story",
- thumbnailUrl: "/api/community/link-preview/thumbnail/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
- } }))
+ renderer.update(createElement(LinkPreviewCardView, {
+ preview: { ...PREVIEW, url: "https://example.com/next", thumbnailUrl: nextThumbnailUrl },
+ }))
})
+ const nextPreload = renderer.root.findByType("img")
+ expect(nextPreload.props.src).toBe(nextThumbnailUrl)
+ expect(renderer.root.findAllByType("a")).toHaveLength(0)
+
+ act(() => nextPreload.props.onError())
+ act(() => renderer.unmount())
+ await act(() => vi.advanceTimersByTimeAsync(5_000))
+ })
- const image = renderer!.root.findByType("img")
- act(() => image.props.onError())
- expect(renderer!.root.findAllByType("img")).toHaveLength(0)
- expect(renderer!.root.findAllByType("a")).toHaveLength(0)
- expect(renderer!.root.findAll(
- (node) => node.type === "div" && node.props.className === "pb-2",
- )).toHaveLength(0)
+ it("never places an upstream image URL in the DOM", () => {
+ const renderer = renderPreview()
+ expect(JSON.stringify(renderer.toJSON())).toContain(THUMBNAIL_URL)
+ expect(JSON.stringify(renderer.toJSON())).not.toContain("avatars.githubusercontent.com")
})
})
diff --git a/src/web/src/components/community/messages/link-preview-card.tsx b/src/web/src/components/community/messages/link-preview-card.tsx
index 929690e0a..5c7da79ab 100644
--- a/src/web/src/components/community/messages/link-preview-card.tsx
+++ b/src/web/src/components/community/messages/link-preview-card.tsx
@@ -16,6 +16,7 @@ type LinkPreviewResponse = {
const POSITIVE_STALE_TIME_MS = 6 * 60 * 60 * 1_000
const NEGATIVE_STALE_TIME_MS = 5 * 60 * 1_000
+const THUMBNAIL_RETRY_DELAYS_MS = [1_000, 3_000] as const
export function linkPreviewStaleTime(data: LinkPreviewResponse | undefined): number {
if (data?.staleTimeSeconds === 6 * 60 * 60) return POSITIVE_STALE_TIME_MS
@@ -23,31 +24,61 @@ export function linkPreviewStaleTime(data: LinkPreviewResponse | undefined): num
return data?.preview ? POSITIVE_STALE_TIME_MS : NEGATIVE_STALE_TIME_MS
}
-function LinkPreviewThumbnail({ src, onError }: { src: string; onError?: () => void }) {
+function LinkPreviewCardThumbnail({ preview }: { preview: LinkPreview & { thumbnailUrl: string } }) {
+ const retryTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+ const [attempt, setAttempt] = useState(0)
+ const [loaded, setLoaded] = useState(false)
const [failed, setFailed] = useState(false)
- if (failed) return null
- return (
- <img
- data-testid={tid.linkPreviewThumbnail}
- src={src}
- alt=""
- width={640}
- height={360}
- loading="lazy"
- decoding="async"
- referrerPolicy="no-referrer"
- className="aspect-video w-full bg-muted object-cover"
- onError={() => {
- setFailed(true)
- onError?.()
- }}
- />
- )
-}
-export function LinkPreviewCardView({ preview }: { preview: LinkPreview }) {
- const [failed, setFailed] = useState(false)
- if (!preview.thumbnailUrl || failed) return null
+ const clearRetry = () => {
+ if (retryTimerRef.current === null) return
+ clearTimeout(retryTimerRef.current)
+ retryTimerRef.current = null
+ }
+
+ useEffect(() => () => {
+ if (retryTimerRef.current !== null) clearTimeout(retryTimerRef.current)
+ }, [])
+
+ const handleLoad = () => {
+ clearRetry()
+ setLoaded(true)
+ }
+
+ const handleError = () => {
+ clearRetry()
+ setLoaded(false)
+ const delay = THUMBNAIL_RETRY_DELAYS_MS[attempt]
+ if (delay === undefined) {
+ setFailed(true)
+ return
+ }
+ retryTimerRef.current = setTimeout(() => {
+ retryTimerRef.current = null
+ setAttempt((current) => current + 1)
+ }, delay)
+ }
+
+ if (failed) return null
+ if (!loaded) {
+ return (
+ <img
+ key={attempt}
+ data-testid={tid.linkPreviewThumbnail}
+ src={preview.thumbnailUrl}
+ alt=""
+ width={640}
+ height={360}
+ loading="eager"
+ decoding="async"
+ referrerPolicy="no-referrer"
+ aria-hidden="true"
+ className="pointer-events-none absolute size-px opacity-0"
+ onLoad={handleLoad}
+ onError={handleError}
+ />
+ )
+ }
return (
<div className="pb-2">
@@ -60,7 +91,19 @@ export function LinkPreviewCardView({ preview }: { preview: LinkPreview }) {
aria-label={`Open link preview: ${preview.title}`}
>
<Card className="relative gap-0 py-0 transition-shadow group-hover:ring-foreground/20">
- <LinkPreviewThumbnail src={preview.thumbnailUrl} onError={() => setFailed(true)} />
+ <img
+ data-testid={tid.linkPreviewThumbnail}
+ src={preview.thumbnailUrl}
+ alt=""
+ width={640}
+ height={360}
+ loading="lazy"
+ decoding="async"
+ referrerPolicy="no-referrer"
+ className="aspect-video w-full bg-muted object-cover"
+ onLoad={handleLoad}
+ onError={handleError}
+ />
<span className="pointer-events-none absolute top-2 right-2 flex size-7 items-center justify-center rounded-full bg-background/80 text-foreground shadow-sm backdrop-blur-sm">
<ExternalLink aria-hidden="true" className="size-3.5" />
</span>
@@ -70,6 +113,11 @@ export function LinkPreviewCardView({ preview }: { preview: LinkPreview }) {
)
}
+export function LinkPreviewCardView({ preview }: { preview: LinkPreview }) {
+ if (!preview.thumbnailUrl) return null
+ return <LinkPreviewCardThumbnail key={preview.thumbnailUrl} preview={preview as LinkPreview & { thumbnailUrl: string }} />
+}
+
function LinkPreviewCardImpl({ url }: { url: string }) {
const sentinelRef = useRef<HTMLSpanElement>(null)
const [nearViewport, setNearViewport] = useState(false)
diff --git a/src/web/src/components/community/messages/message-body.test.ts b/src/web/src/components/community/messages/message-body.test.ts
index 16a119330..cb61f9974 100644
--- a/src/web/src/components/community/messages/message-body.test.ts
+++ b/src/web/src/components/community/messages/message-body.test.ts
@@ -83,6 +83,14 @@ describe("MessageBody — link preview spacing", () => {
thumbnailUrl: "/api/community/link-preview/thumbnail/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
})
try {
+ expect(previewSpacing(rendered.renderer)).toHaveLength(0)
+ expect(rendered.renderer.root.findAllByProps({
+ "data-testid": tid.linkPreviewCard,
+ })).toHaveLength(0)
+ const preload = rendered.renderer.root.findByProps({
+ "data-testid": tid.linkPreviewThumbnail,
+ })
+ act(() => preload.props.onLoad())
expect(previewSpacing(rendered.renderer)).toHaveLength(1)
expect(rendered.renderer.root.findAllByProps({
"data-testid": tid.linkPreviewCard,
@@ -100,6 +108,11 @@ describe("MessageBody — link preview spacing", () => {
thumbnailUrl: "/api/community/link-preview/thumbnail/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
})
try {
+ const preload = rendered.renderer.root.findByProps({
+ "data-testid": tid.linkPreviewThumbnail,
+ })
+ act(() => preload.props.onLoad())
+ expect(previewSpacing(rendered.renderer)).toHaveLength(1)
const image = rendered.renderer.root.findByProps({
"data-testid": tid.linkPreviewThumbnail,
})
diff --git a/src/web/src/lib/community/link-preview-thumbnail.test.ts b/src/web/src/lib/community/link-preview-thumbnail.test.ts
index 4771a6df9..b6ab49f94 100644
--- a/src/web/src/lib/community/link-preview-thumbnail.test.ts
+++ b/src/web/src/lib/community/link-preview-thumbnail.test.ts
@@ -1,6 +1,7 @@
import { afterEach, describe, expect, it, vi } from "vitest"
import {
LINK_PREVIEW_THUMBNAIL_LIMITS,
+ LinkPreviewThumbnailFailure,
fetchAndTransformLinkPreviewThumbnail,
isFreshLinkPreviewThumbnailObject,
linkPreviewPageDigest,
@@ -37,6 +38,8 @@ function mockImages(args: {
height?: number
output?: Uint8Array
outputType?: string
+ outputError?: unknown
+ contentTypeError?: unknown
} = {}) {
const transform = vi.fn()
const output = vi.fn()
@@ -47,9 +50,13 @@ function mockImages(args: {
},
output: async (...values: unknown[]) => {
output(...values)
+ if (args.outputError !== undefined) throw args.outputError
const transformed = args.output ?? new Uint8Array([1, 2, 3])
return {
- contentType: () => args.outputType ?? "image/webp",
+ contentType: () => {
+ if (args.contentTypeError !== undefined) throw args.contentTypeError
+ return args.outputType ?? "image/webp"
+ },
image: () => bytesStream(transformed),
response: () => new Response(transformed),
}
@@ -427,12 +434,22 @@ describe("fetchAndTransformLinkPreviewThumbnail", () => {
await expect(fetchAndTransformLinkPreviewThumbnail(
"https://example.com/image",
mockImages({ outputType: "image/png" }).binding,
- )).rejects.toThrow("wrong MIME")
+ )).rejects.toMatchObject({
+ stage: "transform",
+ disposition: "deterministic",
+ code: "transform_mime",
+ message: "thumbnail transform returned wrong MIME",
+ })
await expect(fetchAndTransformLinkPreviewThumbnail(
"https://example.com/image",
mockImages({ output: new Uint8Array(LINK_PREVIEW_THUMBNAIL_LIMITS.maxOutputBytes + 1) }).binding,
- )).rejects.toThrow("too large")
+ )).rejects.toMatchObject({
+ stage: "transform",
+ disposition: "deterministic",
+ code: "transform_size",
+ message: "thumbnail response is too large",
+ })
})
it("rejects decoded image info without raster dimensions", async () => {
@@ -449,7 +466,7 @@ describe("fetchAndTransformLinkPreviewThumbnail", () => {
)).rejects.toThrow("unsupported decoded thumbnail format")
})
- it("applies one three-second budget across a stalled source read", async () => {
+ it("applies the three-second budget across a stalled source read", async () => {
vi.useFakeTimers()
vi.stubGlobal("fetch", vi.fn((_url: string, init?: RequestInit) => Promise.resolve(new Response(
new ReadableStream<Uint8Array>({
@@ -462,11 +479,15 @@ describe("fetchAndTransformLinkPreviewThumbnail", () => {
const result = fetchAndTransformLinkPreviewThumbnail("https://example.com/slow", mockImages().binding)
.catch((error: unknown) => error)
- await vi.advanceTimersByTimeAsync(LINK_PREVIEW_THUMBNAIL_LIMITS.timeoutMs)
- await expect(result).resolves.toMatchObject({ message: expect.stringMatching(/aborted|timed out/) })
+ await vi.advanceTimersByTimeAsync(LINK_PREVIEW_THUMBNAIL_LIMITS.sourceTimeoutMs)
+ await expect(result).resolves.toMatchObject({
+ stage: "source",
+ disposition: "transient",
+ code: "source_timeout",
+ })
})
- it("rejects before reading when the source fetch resolves after the total budget", async () => {
+ it("rejects before reading when source headers resolve after the source budget", async () => {
vi.useFakeTimers()
let resolveFetch!: (response: Response) => void
vi.stubGlobal("fetch", vi.fn(() => new Promise<Response>((resolve) => {
@@ -477,10 +498,165 @@ describe("fetchAndTransformLinkPreviewThumbnail", () => {
"https://example.com/late-headers",
mockImages().binding,
)
- await vi.advanceTimersByTimeAsync(LINK_PREVIEW_THUMBNAIL_LIMITS.timeoutMs)
+ await vi.advanceTimersByTimeAsync(LINK_PREVIEW_THUMBNAIL_LIMITS.sourceTimeoutMs)
resolveFetch(response())
- await expect(result).rejects.toMatchObject({ name: "AbortError" })
+ await expect(result).rejects.toMatchObject({
+ stage: "source",
+ disposition: "transient",
+ code: "source_timeout",
+ })
+ })
+
+ it("clears the source deadline before a valid Images operation uses its own five-second budget", async () => {
+ vi.useFakeTimers()
+ vi.stubGlobal("fetch", vi.fn(() => new Promise<Response>((resolve) => {
+ setTimeout(() => resolve(response()), LINK_PREVIEW_THUMBNAIL_LIMITS.sourceTimeoutMs - 100)
+ })))
+ const images = mockImages()
+ vi.mocked(images.binding.info).mockImplementation(() => new Promise((resolve) => {
+ setTimeout(() => resolve({ format: "image/jpeg", fileSize: 3, width: 1200, height: 630 }), 4_000)
+ }))
+
+ const result = fetchAndTransformLinkPreviewThumbnail("https://example.com/slow-valid", images.binding)
+ await vi.advanceTimersByTimeAsync(LINK_PREVIEW_THUMBNAIL_LIMITS.sourceTimeoutMs - 100)
+ await vi.advanceTimersByTimeAsync(4_000)
+
+ await expect(result).resolves.toEqual(new Uint8Array([1, 2, 3]))
+ })
+
+ it("bounds Images at five seconds and observes a late platform rejection", async () => {
+ vi.useFakeTimers()
+ vi.stubGlobal("fetch", vi.fn().mockResolvedValue(response()))
+ const images = mockImages()
+ vi.mocked(images.binding.info).mockImplementation(() => new Promise((_resolve, reject) => {
+ setTimeout(() => reject(Object.assign(new Error("late"), { code: 9523 })), 6_000)
+ }))
+
+ const result = fetchAndTransformLinkPreviewThumbnail("https://example.com/slow-images", images.binding)
+ .catch((error: unknown) => error)
+ await vi.advanceTimersByTimeAsync(LINK_PREVIEW_THUMBNAIL_LIMITS.imagesTimeoutMs)
+ await expect(result).resolves.toMatchObject({
+ stage: "inspect",
+ disposition: "transient",
+ code: "inspect_timeout",
+ })
+ await vi.advanceTimersByTimeAsync(1_000)
+ })
+
+ it("classifies deterministic input rejection and transient service failures", async () => {
+ vi.stubGlobal("fetch", vi.fn().mockResolvedValue(response(undefined, {
+ headers: { "content-type": "image/gif" },
+ })))
+ await expect(fetchAndTransformLinkPreviewThumbnail(
+ "https://example.com/wrong-mime",
+ mockImages().binding,
+ )).rejects.toMatchObject({
+ stage: "source",
+ disposition: "deterministic",
+ code: "source_mime",
+ } satisfies Partial<LinkPreviewThumbnailFailure>)
+
+ vi.stubGlobal("fetch", vi.fn().mockResolvedValue(response(undefined, { status: 503 })))
+ await expect(fetchAndTransformLinkPreviewThumbnail(
+ "https://example.com/unavailable",
+ mockImages().binding,
+ )).rejects.toMatchObject({
+ stage: "source",
+ disposition: "transient",
+ code: "source_http_503",
+ } satisfies Partial<LinkPreviewThumbnailFailure>)
+
+ vi.stubGlobal("fetch", vi.fn().mockResolvedValue(response(undefined, { status: 429 })))
+ await expect(fetchAndTransformLinkPreviewThumbnail(
+ "https://example.com/rate-limited",
+ mockImages().binding,
+ )).rejects.toMatchObject({
+ stage: "source",
+ disposition: "transient",
+ code: "source_http_429",
+ } satisfies Partial<LinkPreviewThumbnailFailure>)
+
+ vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new DOMException("aborted", "AbortError")))
+ await expect(fetchAndTransformLinkPreviewThumbnail(
+ "https://example.com/aborted",
+ mockImages().binding,
+ )).rejects.toMatchObject({
+ stage: "source",
+ disposition: "transient",
+ code: "source_aborted",
+ } satisfies Partial<LinkPreviewThumbnailFailure>)
+
+ vi.stubGlobal("fetch", vi.fn().mockRejectedValue("unknown"))
+ await expect(fetchAndTransformLinkPreviewThumbnail(
+ "https://example.com/unknown",
+ mockImages().binding,
+ )).rejects.toMatchObject({
+ stage: "source",
+ disposition: "transient",
+ code: "source_error",
+ } satisfies Partial<LinkPreviewThumbnailFailure>)
+
+ vi.stubGlobal("fetch", vi.fn().mockResolvedValue(response()))
+ const images = mockImages()
+ vi.mocked(images.binding.info).mockRejectedValue(Object.assign(new Error("service"), { code: 9523 }))
+ await expect(fetchAndTransformLinkPreviewThumbnail(
+ "https://example.com/images-error",
+ images.binding,
+ )).rejects.toMatchObject({
+ stage: "inspect",
+ disposition: "transient",
+ code: "inspect_9523",
+ } satisfies Partial<LinkPreviewThumbnailFailure>)
+ })
+
+ it("classifies transform rejections, preserves typed failures, and defaults unknown errors to transient", async () => {
+ vi.stubGlobal("fetch", vi.fn().mockImplementation(() => Promise.resolve(response())))
+
+ await expect(fetchAndTransformLinkPreviewThumbnail(
+ "https://example.com/transform-error",
+ mockImages({ outputError: Object.assign(new Error("service"), { code: 9523 }) }).binding,
+ )).rejects.toMatchObject({
+ stage: "transform",
+ disposition: "transient",
+ code: "transform_9523",
+ } satisfies Partial<LinkPreviewThumbnailFailure>)
+
+ const typed = new LinkPreviewThumbnailFailure({
+ stage: "transform",
+ disposition: "transient",
+ code: "transform_typed",
+ elapsedMs: 1,
+ message: "typed",
+ })
+ await expect(fetchAndTransformLinkPreviewThumbnail(
+ "https://example.com/typed-transform-error",
+ mockImages({ outputError: typed }).binding,
+ )).rejects.toBe(typed)
+
+ await expect(fetchAndTransformLinkPreviewThumbnail(
+ "https://example.com/unknown-transform-error",
+ mockImages({ contentTypeError: "unknown" }).binding,
+ )).rejects.toMatchObject({
+ stage: "transform",
+ disposition: "transient",
+ code: "transform_error",
+ } satisfies Partial<LinkPreviewThumbnailFailure>)
+ })
+
+ it("classifies an invalid initial source URL before outbound work", async () => {
+ const fetchMock = vi.fn()
+ vi.stubGlobal("fetch", fetchMock)
+
+ await expect(fetchAndTransformLinkPreviewThumbnail(
+ "http://example.com/image.jpg",
+ mockImages().binding,
+ )).rejects.toMatchObject({
+ stage: "source",
+ disposition: "deterministic",
+ code: "source_url",
+ } satisfies Partial<LinkPreviewThumbnailFailure>)
+ expect(fetchMock).not.toHaveBeenCalled()
})
it("builds exact 24-hour R2 object metadata", () => {
diff --git a/src/web/src/lib/community/link-preview-thumbnail.ts b/src/web/src/lib/community/link-preview-thumbnail.ts
index 1c104c1b8..6f4375840 100644
--- a/src/web/src/lib/community/link-preview-thumbnail.ts
+++ b/src/web/src/lib/community/link-preview-thumbnail.ts
@@ -6,7 +6,8 @@ const MAX_SOURCE_BYTES = 5 * 1024 * 1024
const MAX_OUTPUT_BYTES = 512 * 1024
const MAX_MANIFEST_BYTES = 4 * 1024
const MAX_REDIRECTS = 3
-const TOTAL_TIMEOUT_MS = 3_000
+const SOURCE_TIMEOUT_MS = 3_000
+const IMAGES_TIMEOUT_MS = 5_000
const MAX_DIMENSION = 8_192
const MAX_AREA = 16_000_000
const THUMBNAIL_WIDTH = 640
@@ -25,6 +26,80 @@ export type LinkPreviewThumbnailManifest = {
expiresAt: number
}
+export type LinkPreviewThumbnailFailureStage = "source" | "inspect" | "transform" | "storage"
+export type LinkPreviewThumbnailFailureDisposition = "deterministic" | "transient"
+
+export class LinkPreviewThumbnailFailure extends Error {
+ readonly stage: LinkPreviewThumbnailFailureStage
+ readonly disposition: LinkPreviewThumbnailFailureDisposition
+ readonly code: string
+ readonly elapsedMs: number
+
+ constructor(args: {
+ stage: LinkPreviewThumbnailFailureStage
+ disposition: LinkPreviewThumbnailFailureDisposition
+ code: string
+ elapsedMs: number
+ message: string
+ }) {
+ super(args.message)
+ this.name = "LinkPreviewThumbnailFailure"
+ this.stage = args.stage
+ this.disposition = args.disposition
+ this.code = args.code
+ this.elapsedMs = args.elapsedMs
+ }
+}
+
+function failure(args: {
+ stage: LinkPreviewThumbnailFailureStage
+ disposition: LinkPreviewThumbnailFailureDisposition
+ code: string
+ startedAt: number
+ message: string
+}): LinkPreviewThumbnailFailure {
+ return new LinkPreviewThumbnailFailure({
+ stage: args.stage,
+ disposition: args.disposition,
+ code: args.code,
+ elapsedMs: Math.max(0, Date.now() - args.startedAt),
+ message: args.message,
+ })
+}
+
+function stablePlatformCode(error: unknown, fallback: string): string {
+ if (error instanceof LinkPreviewThumbnailFailure) return error.code
+ if (error instanceof DOMException && error.name === "AbortError") return `${fallback}_aborted`
+ if (typeof error === "object" && error !== null) {
+ const value = error as { code?: unknown; name?: unknown }
+ if ((typeof value.code === "string" || typeof value.code === "number")
+ && /^[a-zA-Z0-9_.-]{1,64}$/.test(String(value.code))) {
+ return `${fallback}_${String(value.code).toLowerCase()}`
+ }
+ if (typeof value.name === "string" && /^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/.test(value.name)) {
+ return `${fallback}_${value.name.toLowerCase()}`
+ }
+ }
+ return `${fallback}_error`
+}
+
+async function withDeadline<T>(
+ promise: Promise<T>,
+ timeoutMs: number,
+ onTimeout: () => LinkPreviewThumbnailFailure,
+): Promise<T> {
+ let timer: ReturnType<typeof setTimeout> | undefined
+ const timeout = new Promise<never>((_resolve, reject) => {
+ timer = setTimeout(() => reject(onTimeout()), timeoutMs)
+ })
+ promise.catch(() => {})
+ try {
+ return await Promise.race([promise, timeout])
+ } finally {
+ if (timer !== undefined) clearTimeout(timer)
+ }
+}
+
function streamFromBytes(bytes: Uint8Array): ReadableStream<Uint8Array> {
return new ReadableStream<Uint8Array>({
start(controller) {
@@ -189,8 +264,23 @@ async function readBoundedBytes(
body: ReadableStream<Uint8Array> | null,
maxBytes: number,
signal: AbortSignal,
+ args: {
+ stage: LinkPreviewThumbnailFailureStage
+ disposition: LinkPreviewThumbnailFailureDisposition
+ missingBodyCode: string
+ sizeCode: string
+ startedAt: number
+ },
): Promise<Uint8Array> {
- if (!body) throw new Error("thumbnail response has no body")
+ if (!body) {
+ throw failure({
+ stage: args.stage,
+ disposition: "transient",
+ code: args.missingBodyCode,
+ startedAt: args.startedAt,
+ message: "thumbnail response has no body",
+ })
+ }
const reader = body.getReader()
const chunks: Uint8Array[] = []
let total = 0
@@ -201,7 +291,13 @@ async function readBoundedBytes(
total += value.byteLength
if (total > maxBytes) {
await reader.cancel().catch(() => {})
- throw new Error("thumbnail response is too large")
+ throw failure({
+ stage: args.stage,
+ disposition: args.disposition,
+ code: args.sizeCode,
+ startedAt: args.startedAt,
+ message: "thumbnail response is too large",
+ })
}
chunks.push(value)
}
@@ -211,7 +307,15 @@ async function readBoundedBytes(
} finally {
reader.releaseLock()
}
- if (total === 0) throw new Error("thumbnail response is empty")
+ if (total === 0) {
+ throw failure({
+ stage: args.stage,
+ disposition: args.disposition,
+ code: args.sizeCode,
+ startedAt: args.startedAt,
+ message: "thumbnail response is empty",
+ })
+ }
const bytes = new Uint8Array(total)
let offset = 0
for (const chunk of chunks) {
@@ -232,6 +336,7 @@ async function fetchThumbnailSource(start: URL, signal: AbortSignal): Promise<{
bytes: Uint8Array
contentType: string
}> {
+ const startedAt = Date.now()
let current = start
for (let redirects = 0; ; redirects += 1) {
const response = await fetch(current.href, {
@@ -247,27 +352,81 @@ async function fetchThumbnailSource(start: URL, signal: AbortSignal): Promise<{
})
if (isRedirect(response.status)) {
await response.body?.cancel().catch(() => {})
- if (redirects === MAX_REDIRECTS) throw new Error("too many thumbnail redirects")
+ if (redirects === MAX_REDIRECTS) {
+ throw failure({
+ stage: "source",
+ disposition: "deterministic",
+ code: "source_redirect_limit",
+ startedAt,
+ message: "too many thumbnail redirects",
+ })
+ }
const location = response.headers.get("location")
- if (!location) throw new Error("invalid thumbnail redirect")
- current = normalizePublicImageUrl(location, current)
+ if (!location) {
+ throw failure({
+ stage: "source",
+ disposition: "deterministic",
+ code: "source_redirect_missing",
+ startedAt,
+ message: "invalid thumbnail redirect",
+ })
+ }
+ try {
+ current = normalizePublicImageUrl(location, current)
+ } catch (error) {
+ throw failure({
+ stage: "source",
+ disposition: "deterministic",
+ code: "source_redirect_rejected",
+ startedAt,
+ message: error instanceof Error ? error.message : "invalid thumbnail redirect",
+ })
+ }
continue
}
if (!response.ok) {
await response.body?.cancel().catch(() => {})
- throw new Error("thumbnail origin rejected request")
+ const deterministic = response.status >= 400
+ && response.status < 500
+ && response.status !== 408
+ && response.status !== 429
+ throw failure({
+ stage: "source",
+ disposition: deterministic ? "deterministic" : "transient",
+ code: `source_http_${response.status}`,
+ startedAt,
+ message: "thumbnail origin rejected request",
+ })
}
const contentType = response.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() ?? ""
if (!ALLOWED_MIME.has(contentType)) {
await response.body?.cancel().catch(() => {})
- throw new Error("unsupported thumbnail MIME")
+ throw failure({
+ stage: "source",
+ disposition: "deterministic",
+ code: "source_mime",
+ startedAt,
+ message: "unsupported thumbnail MIME",
+ })
}
if ((declaredContentLength(response) ?? 0) > MAX_SOURCE_BYTES) {
await response.body?.cancel().catch(() => {})
- throw new Error("thumbnail response is too large")
+ throw failure({
+ stage: "source",
+ disposition: "deterministic",
+ code: "source_size",
+ startedAt,
+ message: "thumbnail response is too large",
+ })
}
return {
- bytes: await readBoundedBytes(response.body, MAX_SOURCE_BYTES, signal),
+ bytes: await readBoundedBytes(response.body, MAX_SOURCE_BYTES, signal, {
+ stage: "source",
+ disposition: "deterministic",
+ missingBodyCode: "source_body_missing",
+ sizeCode: "source_size",
+ startedAt,
+ }),
contentType,
}
}
@@ -323,14 +482,52 @@ async function transformThumbnail(
images: ImagesBinding,
bytes: Uint8Array,
declaredMime: string,
+ activeStage: { current: "inspect" | "transform" },
signal: AbortSignal,
): Promise<Uint8Array> {
- const info = await withAbort(images.info(streamFromBytes(bytes)), signal)
- if (!("width" in info) || !("height" in info)) throw new Error("unsupported decoded thumbnail format")
+ const startedAt = Date.now()
+ let info
+ try {
+ info = await withAbort(images.info(streamFromBytes(bytes)), signal)
+ } catch (error) {
+ if (error instanceof LinkPreviewThumbnailFailure) throw error
+ throw failure({
+ stage: "inspect",
+ disposition: "transient",
+ code: stablePlatformCode(error, "inspect"),
+ startedAt,
+ message: "thumbnail inspection failed",
+ })
+ }
+ if (!("width" in info) || !("height" in info)) {
+ throw failure({
+ stage: "inspect",
+ disposition: "deterministic",
+ code: "inspect_format",
+ startedAt,
+ message: "unsupported decoded thumbnail format",
+ })
+ }
const actualMime = decodedMime(info.format)
- if (!actualMime || actualMime !== declaredMime) throw new Error("thumbnail MIME mismatch")
- if (actualMime === "image/png" && isAnimatedPng(bytes)) throw new Error("animated thumbnail rejected")
- if (actualMime === "image/webp" && isAnimatedWebp(bytes)) throw new Error("animated thumbnail rejected")
+ if (!actualMime || actualMime !== declaredMime) {
+ throw failure({
+ stage: "inspect",
+ disposition: "deterministic",
+ code: "inspect_mime",
+ startedAt,
+ message: "thumbnail MIME mismatch",
+ })
+ }
+ if ((actualMime === "image/png" && isAnimatedPng(bytes))
+ || (actualMime === "image/webp" && isAnimatedWebp(bytes))) {
+ throw failure({
+ stage: "inspect",
+ disposition: "deterministic",
+ code: "inspect_animation",
+ startedAt,
+ message: "animated thumbnail rejected",
+ })
+ }
if (!Number.isSafeInteger(info.width)
|| !Number.isSafeInteger(info.height)
|| info.width <= 0
@@ -338,30 +535,115 @@ async function transformThumbnail(
|| info.width > MAX_DIMENSION
|| info.height > MAX_DIMENSION
|| info.width * info.height > MAX_AREA) {
- throw new Error("thumbnail dimensions exceed limit")
+ throw failure({
+ stage: "inspect",
+ disposition: "deterministic",
+ code: "inspect_dimensions",
+ startedAt,
+ message: "thumbnail dimensions exceed limit",
+ })
}
- const output = await withAbort(images
- .input(streamFromBytes(bytes))
- .transform({ width: THUMBNAIL_WIDTH, height: THUMBNAIL_HEIGHT, fit: "cover" })
- .output({ format: "image/webp", quality: THUMBNAIL_QUALITY, anim: false }), signal)
- if (output.contentType() !== "image/webp") throw new Error("thumbnail transform returned wrong MIME")
- return readBoundedBytes(output.image(), MAX_OUTPUT_BYTES, signal)
+ activeStage.current = "transform"
+ const transformStartedAt = Date.now()
+ let output
+ try {
+ output = await withAbort(images
+ .input(streamFromBytes(bytes))
+ .transform({ width: THUMBNAIL_WIDTH, height: THUMBNAIL_HEIGHT, fit: "cover" })
+ .output({ format: "image/webp", quality: THUMBNAIL_QUALITY, anim: false }), signal)
+ } catch (error) {
+ if (error instanceof LinkPreviewThumbnailFailure) throw error
+ throw failure({
+ stage: "transform",
+ disposition: "transient",
+ code: stablePlatformCode(error, "transform"),
+ startedAt: transformStartedAt,
+ message: "thumbnail transform failed",
+ })
+ }
+ if (output.contentType() !== "image/webp") {
+ throw failure({
+ stage: "transform",
+ disposition: "deterministic",
+ code: "transform_mime",
+ startedAt: transformStartedAt,
+ message: "thumbnail transform returned wrong MIME",
+ })
+ }
+ return readBoundedBytes(output.image(), MAX_OUTPUT_BYTES, signal, {
+ stage: "transform",
+ disposition: "deterministic",
+ missingBodyCode: "transform_body_missing",
+ sizeCode: "transform_size",
+ startedAt: transformStartedAt,
+ })
}
export async function fetchAndTransformLinkPreviewThumbnail(
sourceUrl: string,
images: ImagesBinding,
): Promise<Uint8Array> {
- const source = normalizePublicImageUrl(sourceUrl)
+ const sourceStartedAt = Date.now()
+ let source: URL
+ try {
+ source = normalizePublicImageUrl(sourceUrl)
+ } catch (error) {
+ throw failure({
+ stage: "source",
+ disposition: "deterministic",
+ code: "source_url",
+ startedAt: sourceStartedAt,
+ message: error instanceof Error ? error.message : "invalid thumbnail source",
+ })
+ }
const controller = new AbortController()
- const timer = setTimeout(() => controller.abort(), TOTAL_TIMEOUT_MS)
+ const timer = setTimeout(() => controller.abort(), SOURCE_TIMEOUT_MS)
+ let fetched: { bytes: Uint8Array; contentType: string }
try {
- const fetched = await fetchThumbnailSource(source, controller.signal)
- return await transformThumbnail(images, fetched.bytes, fetched.contentType, controller.signal)
+ fetched = await fetchThumbnailSource(source, controller.signal)
+ } catch (error) {
+ if (error instanceof LinkPreviewThumbnailFailure) throw error
+ const timeout = controller.signal.aborted
+ throw failure({
+ stage: "source",
+ disposition: "transient",
+ code: timeout ? "source_timeout" : stablePlatformCode(error, "source"),
+ startedAt: sourceStartedAt,
+ message: timeout ? "thumbnail request timed out" : "thumbnail source request failed",
+ })
} finally {
clearTimeout(timer)
}
+
+ const imagesStartedAt = Date.now()
+ const imagesController = new AbortController()
+ const activeStage: { current: "inspect" | "transform" } = { current: "inspect" }
+ try {
+ return await withDeadline(
+ transformThumbnail(images, fetched.bytes, fetched.contentType, activeStage, imagesController.signal),
+ IMAGES_TIMEOUT_MS,
+ () => {
+ queueMicrotask(() => imagesController.abort())
+ return failure({
+ stage: activeStage.current,
+ disposition: "transient",
+ code: `${activeStage.current}_timeout`,
+ startedAt: imagesStartedAt,
+ message: "thumbnail Images operation timed out",
+ })
+ },
+ )
+ } catch (error) {
+ if (error instanceof LinkPreviewThumbnailFailure) throw error
+ throw failure({
+ stage: activeStage.current,
+ disposition: "transient",
+ code: stablePlatformCode(error, activeStage.current),
+ startedAt: imagesStartedAt,
+ message: "thumbnail Images operation failed",
+ })
+ }
}
export function linkPreviewThumbnailObjectMetadata(manifest: LinkPreviewThumbnailManifest, now = Date.now()) {
@@ -382,7 +664,8 @@ export const LINK_PREVIEW_THUMBNAIL_LIMITS = {
maxSourceBytes: MAX_SOURCE_BYTES,
maxOutputBytes: MAX_OUTPUT_BYTES,
maxRedirects: MAX_REDIRECTS,
- timeoutMs: TOTAL_TIMEOUT_MS,
+ sourceTimeoutMs: SOURCE_TIMEOUT_MS,
+ imagesTimeoutMs: IMAGES_TIMEOUT_MS,
maxDimension: MAX_DIMENSION,
maxArea: MAX_AREA,
width: THUMBNAIL_WIDTH,