From 6cc38f93ce0eaad6c754677419e21de552a4a36f Mon Sep 17 00:00:00 2001 From: Phat Pham Date: Fri, 13 Nov 2026 13:12:17 +0700 Subject: [PATCH 1/6] test: add temporary JS-rendered preview fixture Co-Authored-By: Claude Code --- web-static/browser-test.html | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 web-static/browser-test.html diff --git a/web-static/browser-test.html b/web-static/browser-test.html new file mode 100644 index 0000000..41fe198 --- /dev/null +++ b/web-static/browser-test.html @@ -0,0 +1,16 @@ + + + + + Browser preview test + + +
+ + + From 1d4e1c2c101f6e756e8a41a544ad683ed41abad1 Mon Sep 17 00:00:00 2001 From: Phat Pham Date: Fri, 13 Nov 2026 13:13:15 +0700 Subject: [PATCH 2/6] test: add temporary browser fallback smoke route Co-Authored-By: Claude Code --- platforms/cloudflare/src/index.ts | 41 ++++++++++++++++++++----------- 1 file changed, 27 insertions(+), 14 deletions(-) diff --git a/platforms/cloudflare/src/index.ts b/platforms/cloudflare/src/index.ts index 45c9c80..834e9e7 100644 --- a/platforms/cloudflare/src/index.ts +++ b/platforms/cloudflare/src/index.ts @@ -32,7 +32,7 @@ import { paginate } from "../../../core/sources/listInMemory.ts"; import { D1Repository } from "./repository.ts"; import { CloudflareLlmRanker } from "./llmRanker.ts"; import { CloudflareEmbedder } from "./embedder.ts"; -import { aiPreviewFallback } from "./previewFallback.ts"; +import { createPreviewFallback } from "./previewFallbackChain.ts"; import { loadConfig } from "./config.ts"; import type { Env } from "./env.d.ts"; @@ -125,6 +125,21 @@ export default { if (url.pathname.startsWith("/internal/refresh/")) { return handleInternalRefresh(request, env, repo, sources, url); } + // TEMPORARY: full preview-fallback smoke test; removed before merge. + if (url.pathname === "/debug/browser-fallback") { + const target = normalizePreviewUrl(url.searchParams.get("url") ?? ""); + if (!target) { + return Response.json({ error: "url is required" }, { status: 400 }); + } + const fallback = createPreviewFallback(env, "Browser preview test"); + const preview = await fallback?.({ + kind: "no_content", + url: target, + contentType: "text/html", + html: "", + }); + return Response.json({ preview }); + } return new Response("not found", { status: 404 }); }, @@ -292,17 +307,14 @@ async function handlePreview( if (cached) return clientCacheResponse(cached); try { - // PDFs/Office documents and pages with no readable blocks may still be - // previewable through Workers AI's Markdown conversion. The fallback is - // best-effort: a null result keeps the original failure reason. - const aiFallbackEnabled = - (env.FEEDREADER_AI_PREVIEW_FALLBACK ?? "true").trim().toLowerCase() !== - "false"; + // PDFs/Office documents go through Workers AI Markdown conversion; if an + // HTML page still has no readable blocks, Browser Run can render a + // JavaScript shell. Both are best-effort and preserve the original + // failure when they return null. + const fallback = createPreviewFallback(env, item.title); const preview = await fetchArticlePreview(target, { userAgent: loadConfig(env).userAgent, - ...(aiFallbackEnabled - ? { fallback: (input) => aiPreviewFallback(env, input, item.title) } - : {}), + ...(fallback ? { fallback } : {}), }); const payload = { url: item.url, @@ -384,10 +396,11 @@ async function handlePreview( * `.invalid` is reserved by RFC 2606 for exactly this kind of placeholder * use, so it's guaranteed not to collide with a real host. */ function previewCacheRequest(target: string): Request { - // v10 adds the Workers AI Markdown fallback, so previously cached empty - // previews get another extraction attempt; v9 added paper resource/citation - // sections, v8 added arXiv links, and v7 covered author bylines. - const raw = `preview:v10:${target}`; + // v11 adds the Browser Run fallback, so previously cached empty previews + // get a JavaScript-rendered attempt; v10 added the Workers AI Markdown + // fallback, v9 added paper resource/citation sections, v8 added arXiv + // links, and v7 covered author bylines. + const raw = `preview:v11:${target}`; const url = `https://feedreader-internal.invalid/preview-cache?k=${encodeURIComponent(raw)}`; return new Request(url, { method: "GET" }); } From a1cf6bab4c3d77c5c9f850d7002ab9284f2e6c4c Mon Sep 17 00:00:00 2001 From: Phat Pham Date: Fri, 13 Nov 2026 13:13:51 +0700 Subject: [PATCH 3/6] feat(preview): add Browser Run fallback for JS-rendered pages Run HTML pages that still have no readable blocks after the static extractor and Workers AI conversion through Browser Run's markdown Quick Action. The chain keeps Workers AI first; Browser Run only runs for no_content failures, checks the rendered page status and final URL, and maps the returned Markdown through the same validated block mapper. Browser Run's YAML frontmatter is stripped before mapping. Workers Free limits (10 browser-minutes/day, one Quick Action per 10 seconds) are documented and the fallback is behind FEEDREADER_BROWSER_PREVIEW_FALLBACK. The preview cache key moves to v11. Co-Authored-By: Claude Code --- core/previewMarkdown.ts | 22 +- core/test/previewMarkdown.spec.ts | 49 +++++ .../cloudflare/src/browserPreviewFallback.ts | 191 ++++++++++++++++++ platforms/cloudflare/src/env.d.ts | 5 + platforms/cloudflare/src/previewFallback.ts | 57 +----- .../cloudflare/src/previewFallbackChain.ts | 32 +++ .../cloudflare/src/previewFallbackUtils.ts | 66 ++++++ .../test/browserPreviewFallback.spec.ts | 180 +++++++++++++++++ .../test/previewFallbackChain.spec.ts | 143 +++++++++++++ platforms/cloudflare/wrangler.toml | 10 + 10 files changed, 705 insertions(+), 50 deletions(-) create mode 100644 platforms/cloudflare/src/browserPreviewFallback.ts create mode 100644 platforms/cloudflare/src/previewFallbackChain.ts create mode 100644 platforms/cloudflare/src/previewFallbackUtils.ts create mode 100644 platforms/cloudflare/test/browserPreviewFallback.spec.ts create mode 100644 platforms/cloudflare/test/previewFallbackChain.spec.ts diff --git a/core/previewMarkdown.ts b/core/previewMarkdown.ts index 14a81d8..eadd943 100644 --- a/core/previewMarkdown.ts +++ b/core/previewMarkdown.ts @@ -76,7 +76,10 @@ export function markdownToPreviewBlocks( markdown: string, options: MarkdownPreviewOptions, ): PreviewBlock[] { - const source = stripTrailingJsonLd(markdown.replace(/\r\n?/g, "\n")); + const normalized = stripLeadingFrontmatter( + markdown.replace(/\r\n?/g, "\n"), + ); + const source = stripTrailingJsonLd(normalized); const lines = source.split("\n"); const blocks: PreviewBlock[] = []; const seenImages = new Set(); @@ -627,6 +630,23 @@ function codePoint(fallback: string, value: number): string { return String.fromCodePoint(value); } +/** + * Browser Run prefixes Markdown with YAML frontmatter when the page exposes + * metadata. Strip a leading `---` block only when it contains at least one + * `key:` line, so a document that starts with a horizontal rule is left + * alone. + */ +function stripLeadingFrontmatter(markdown: string): string { + if (!markdown.startsWith("---\n")) return markdown; + const end = markdown.indexOf("\n---", 4); + if (end === -1) return markdown; + const frontmatter = markdown.slice(4, end); + if (!/^[A-Za-z0-9_-]+:/m.test(frontmatter)) return markdown; + const after = markdown.slice(end + 4); + if (after !== "" && !after.startsWith("\n")) return markdown; + return after.replace(/^\n+/, ""); +} + /** * HTML conversion appends the page's JSON-LD at the end of the Markdown. * Remove only a trailing JSON-LD-shaped object/array so a legitimate JSON diff --git a/core/test/previewMarkdown.spec.ts b/core/test/previewMarkdown.spec.ts index b9681a3..1161410 100644 --- a/core/test/previewMarkdown.spec.ts +++ b/core/test/previewMarkdown.spec.ts @@ -303,6 +303,55 @@ A long enough paragraph that should remain in the preview.`; ).toEqual([{ type: "paragraph", text: markdown }]); }); + it("strips YAML frontmatter returned by Browser Run", () => { + const markdown = `--- +title: "TodoMVC: React" +meta: + description: "A TodoMVC written in React." +--- + +### Rendered + +A long enough paragraph rendered after JavaScript executes.`; + + expect( + markdownToPreviewBlocks(markdown, { + pageUrl: "https://example.com/posts/rendered", + }), + ).toEqual([ + { type: "heading", text: "Rendered" }, + { + type: "paragraph", + text: "A long enough paragraph rendered after JavaScript executes.", + }, + ]); + }); + + it("does not treat horizontal rules as frontmatter", () => { + const markdown = `--- + +A long enough paragraph that stays after the first rule. + +--- + +Another long enough paragraph after the second rule.`; + + expect( + markdownToPreviewBlocks(markdown, { + pageUrl: "https://example.com/posts/rules", + }), + ).toEqual([ + { + type: "paragraph", + text: "A long enough paragraph that stays after the first rule.", + }, + { + type: "paragraph", + text: "Another long enough paragraph after the second rule.", + }, + ]); + }); + it("returns no blocks for empty or JSON-LD-only input", () => { expect( markdownToPreviewBlocks("", { diff --git a/platforms/cloudflare/src/browserPreviewFallback.ts b/platforms/cloudflare/src/browserPreviewFallback.ts new file mode 100644 index 0000000..ae90089 --- /dev/null +++ b/platforms/cloudflare/src/browserPreviewFallback.ts @@ -0,0 +1,191 @@ +// Browser Run fallback for the narrow case where an HTML page has no +// readable blocks even after Workers AI conversion: usually a JavaScript +// shell whose content only exists after the page executes. Quick Actions +// render the page in a real browser and return Markdown; the mapper then +// applies the same URL/block validation as the other extractors. +// +// Workers Free includes 10 browser-minutes/day and paces Quick Actions to +// one request per 10 seconds. This adapter runs only on a preview cache miss +// after the static extractor and AI fallback both found nothing; successes +// are cached for 30 minutes by the preview handler. A 429 is logged and +// treated as "no preview" rather than an error. + +import { + estimateReadingMinutes, + normalizePreviewUrl, + type ArticlePreview, + type PreviewFallbackInput, +} from "../../../core/preview.ts"; +import { markdownToPreviewBlocks } from "../../../core/previewMarkdown.ts"; +import type { Env } from "./env.d.ts"; +import { + errorMessage, + hostLabel, + previewTitle, + withTimeout, +} from "./previewFallbackUtils.ts"; + +const BROWSER_TIMEOUT_MS = 9_000; +const BROWSER_GOTO_TIMEOUT_MS = 8_000; +const REJECTED_RESOURCE_TYPES: BrowserRunResourceType[] = [ + "image", + "media", + "font", +]; +// Quick Actions do not support session guardrails. Block literal private +// hosts at the request layer and re-check meta.finalUrl below; the +// stored-item allowlist remains the primary SSRF boundary. +const PRIVATE_HOST_REQUEST_PATTERN = + "/^https?:\\/\\/(?:localhost|127\\.|0\\.|10\\.|192\\.168\\.|169\\.254\\.|172\\.(?:1[6-9]|2[0-9]|3[01])\\.|\\[::1\\]|\\[f[cd])/"; + +export async function browserPreviewFallback( + env: Env, + input: PreviewFallbackInput, + titleHint: string, +): Promise { + if (!isBrowserFallbackEnabled(env.FEEDREADER_BROWSER_PREVIEW_FALLBACK)) { + return null; + } + if (input.kind !== "no_content") return null; + + const startedAt = Date.now(); + try { + const response = await withTimeout( + env.BROWSER.quickAction("markdown", { + url: input.url, + gotoOptions: { + timeout: BROWSER_GOTO_TIMEOUT_MS, + // SPAs finish rendering after the initial DOM load; wait for the + // network to settle, but let bestAttempt return a partial page if + // the site keeps polling and never reaches idle. + waitUntil: "networkidle2", + }, + actionTimeout: BROWSER_GOTO_TIMEOUT_MS, + bestAttempt: true, + rejectResourceTypes: REJECTED_RESOURCE_TYPES, + rejectRequestPattern: [PRIVATE_HOST_REQUEST_PATTERN], + }), + BROWSER_TIMEOUT_MS, + "Browser Run markdown timed out", + ); + + const browserMs = parseHeaderInt(response.headers.get("x-browser-ms-used")); + const payload = (await response.json().catch(() => null)) as + | BrowserRunMarkdownSuccessResponse + | BrowserRunErrorResponse + | null; + + if (!response.ok || payload === null || payload.success !== true) { + const detail = + payload !== null && payload.success === false + ? payload.errors.map((entry) => entry.message).join("; ") + : `HTTP ${response.status}`; + logBrowserFallback(input, startedAt, { + outcome: "error", + status: response.status, + browserMs, + error: detail, + }); + return null; + } + + const pageStatus = payload.meta.status; + if (pageStatus < 200 || pageStatus >= 300) { + logBrowserFallback(input, startedAt, { + outcome: "error", + status: response.status, + pageStatus, + browserMs, + error: `upstream status ${pageStatus}`, + }); + return null; + } + + const finalUrl = normalizePreviewUrl(payload.meta.finalUrl ?? input.url); + if (!finalUrl) { + logBrowserFallback(input, startedAt, { + outcome: "error", + status: response.status, + pageStatus, + browserMs, + error: "unusable final URL", + }); + return null; + } + + const blocks = markdownToPreviewBlocks(payload.result, { + pageUrl: finalUrl, + title: titleHint, + }); + if (blocks.length === 0) { + logBrowserFallback(input, startedAt, { + outcome: "empty", + status: response.status, + pageStatus, + browserMs, + }); + return null; + } + + const readingMinutes = estimateReadingMinutes(blocks); + const preview: ArticlePreview = { + title: previewTitle(titleHint, blocks), + siteName: hostLabel(finalUrl), + blocks, + }; + if (readingMinutes !== undefined) preview.readingMinutes = readingMinutes; + logBrowserFallback(input, startedAt, { + outcome: "ok", + status: response.status, + pageStatus, + browserMs, + blocks: blocks.length, + }); + return preview; + } catch (error) { + logBrowserFallback(input, startedAt, { + outcome: "error", + error: errorMessage(error), + }); + return null; + } +} + +function isBrowserFallbackEnabled(raw: string | undefined): boolean { + return (raw ?? "true").trim().toLowerCase() !== "false"; +} + +function parseHeaderInt(raw: string | null): number | undefined { + if (raw === null) return undefined; + const value = Number.parseInt(raw, 10); + return Number.isFinite(value) ? value : undefined; +} + +function logBrowserFallback( + input: PreviewFallbackInput, + startedAt: number, + result: { + outcome: "ok" | "empty" | "error"; + status?: number; + pageStatus?: number; + browserMs?: number; + blocks?: number; + error?: string; + }, +): void { + const entry: Record = { + event: "preview_browser_fallback", + kind: input.kind, + url: input.url, + outcome: result.outcome, + ms: Date.now() - startedAt, + }; + if (result.status !== undefined) entry.status = result.status; + if (result.pageStatus !== undefined) entry.page_status = result.pageStatus; + if (result.browserMs !== undefined) entry.browser_ms = result.browserMs; + if (result.blocks !== undefined) entry.blocks = result.blocks; + if (result.error !== undefined) entry.error = result.error; + const line = JSON.stringify(entry); + if (result.outcome === "ok") console.log(line); + else console.warn(line); +} diff --git a/platforms/cloudflare/src/env.d.ts b/platforms/cloudflare/src/env.d.ts index 5dee823..eb73eab 100644 --- a/platforms/cloudflare/src/env.d.ts +++ b/platforms/cloudflare/src/env.d.ts @@ -8,6 +8,8 @@ export interface Env { /** Workers AI binding backing the "For You" LlmRanker — see * platforms/cloudflare/src/llmRanker.ts. No secret needed. */ AI: Ai; + /** Browser Run binding backing the JavaScript-rendered preview fallback. */ + BROWSER: BrowserRun; REFRESH_SECRET: string; APP_VERSION?: string; FEEDREADER_ITEMS_PER_SOURCE?: string; @@ -21,4 +23,7 @@ export interface Env { /** Set to "false" to disable the Workers AI toMarkdown fallback for * non-HTML and empty/truncated article previews. */ FEEDREADER_AI_PREVIEW_FALLBACK?: string; + /** Set to "false" to disable the Browser Run fallback for JavaScript- + * rendered HTML previews. */ + FEEDREADER_BROWSER_PREVIEW_FALLBACK?: string; } diff --git a/platforms/cloudflare/src/previewFallback.ts b/platforms/cloudflare/src/previewFallback.ts index 1ae62e9..7968281 100644 --- a/platforms/cloudflare/src/previewFallback.ts +++ b/platforms/cloudflare/src/previewFallback.ts @@ -16,10 +16,14 @@ import { } from "../../../core/preview.ts"; import { markdownToPreviewBlocks } from "../../../core/previewMarkdown.ts"; import type { Env } from "./env.d.ts"; +import { + errorMessage, + hostLabel, + previewTitle, + withTimeout, +} from "./previewFallbackUtils.ts"; const AI_TIMEOUT_MS = 10_000; -const MAX_LOG_ERROR_CHARS = 300; -const TITLE_MAX_CHARS = 200; // toMarkdown also accepts images, but turning a standalone image into an AI // description is not a useful article preview and can consume the Workers AI @@ -96,6 +100,7 @@ export async function aiPreviewFallback( }, }), AI_TIMEOUT_MS, + "AI Markdown conversion timed out", ); if (result.format === "error") { @@ -124,10 +129,7 @@ export async function aiPreviewFallback( const readingMinutes = estimateReadingMinutes(blocks); const preview: ArticlePreview = { - title: - titleHint.trim().slice(0, TITLE_MAX_CHARS) || - firstHeading(blocks) || - "Article preview", + title: previewTitle(titleHint, blocks), siteName: hostLabel(input.url), blocks, }; @@ -194,19 +196,6 @@ function urlExtension(rawUrl: string): string { } } -function firstHeading(blocks: PreviewBlock[]): string { - for (const block of blocks) { - if (block.type !== "heading") continue; - const text = - "segments" in block - ? block.segments.map((segment) => segment.text).join("") - : block.text; - const trimmed = text.trim(); - if (trimmed !== "") return trimmed; - } - return ""; -} - /** * PDF conversion emits a heading for the uploaded filename and for each page * ("Page 1", "Page 2", ...). Neither is article content; drop them so the @@ -244,36 +233,6 @@ function blockPlainText(block: PreviewBlock): string | null { : block.text; } -function hostLabel(rawUrl: string): string { - try { - return new URL(rawUrl).hostname.toLowerCase().replace(/^www\./, ""); - } catch { - return ""; - } -} - -function errorMessage(error: unknown): string { - const message = error instanceof Error ? error.message : String(error); - return message.slice(0, MAX_LOG_ERROR_CHARS); -} - -async function withTimeout(promise: Promise, timeoutMs: number): Promise { - let timer: ReturnType | undefined; - try { - return await Promise.race([ - promise, - new Promise((_, reject) => { - timer = setTimeout( - () => reject(new Error("AI Markdown conversion timed out")), - timeoutMs, - ); - }), - ]); - } finally { - if (timer !== undefined) clearTimeout(timer); - } -} - function logFallback( input: PreviewFallbackInput, mimeType: string, diff --git a/platforms/cloudflare/src/previewFallbackChain.ts b/platforms/cloudflare/src/previewFallbackChain.ts new file mode 100644 index 0000000..df17886 --- /dev/null +++ b/platforms/cloudflare/src/previewFallbackChain.ts @@ -0,0 +1,32 @@ +// Preview fallback order: Workers AI Markdown conversion first (PDFs/Office +// documents and static HTML), then Browser Run for JavaScript-rendered pages +// that still produced no blocks. Core receives one injected fallback. + +import type { PreviewFallback } from "../../../core/preview.ts"; +import { browserPreviewFallback } from "./browserPreviewFallback.ts"; +import type { Env } from "./env.d.ts"; +import { aiPreviewFallback } from "./previewFallback.ts"; + +export function createPreviewFallback( + env: Env, + titleHint: string, +): PreviewFallback | undefined { + const aiEnabled = isEnabled(env.FEEDREADER_AI_PREVIEW_FALLBACK); + const browserEnabled = isEnabled(env.FEEDREADER_BROWSER_PREVIEW_FALLBACK); + if (!aiEnabled && !browserEnabled) return undefined; + + return async (input) => { + if (aiEnabled) { + const aiPreview = await aiPreviewFallback(env, input, titleHint); + if (aiPreview) return aiPreview; + } + if (browserEnabled) { + return browserPreviewFallback(env, input, titleHint); + } + return null; + }; +} + +function isEnabled(raw: string | undefined): boolean { + return (raw ?? "true").trim().toLowerCase() !== "false"; +} diff --git a/platforms/cloudflare/src/previewFallbackUtils.ts b/platforms/cloudflare/src/previewFallbackUtils.ts new file mode 100644 index 0000000..658b5f5 --- /dev/null +++ b/platforms/cloudflare/src/previewFallbackUtils.ts @@ -0,0 +1,66 @@ +// Shared helpers for the platform preview fallbacks (Workers AI Markdown +// conversion and Browser Run). Both adapters return the same PreviewBlock +// shape and need the same title/host derivation and bounded waits. + +import type { PreviewBlock } from "../../../core/preview.ts"; + +export const PREVIEW_TITLE_MAX_CHARS = 200; +const MAX_LOG_ERROR_CHARS = 300; + +export async function withTimeout( + promise: Promise, + timeoutMs: number, + message: string, +): Promise { + let timer: ReturnType | undefined; + try { + return await Promise.race([ + promise, + new Promise((_, reject) => { + timer = setTimeout(() => reject(new Error(message)), timeoutMs); + }), + ]); + } finally { + if (timer !== undefined) clearTimeout(timer); + } +} + +export function errorMessage( + error: unknown, + maxChars = MAX_LOG_ERROR_CHARS, +): string { + const message = error instanceof Error ? error.message : String(error); + return message.slice(0, maxChars); +} + +export function firstHeading(blocks: PreviewBlock[]): string { + for (const block of blocks) { + if (block.type !== "heading") continue; + const text = + "segments" in block + ? block.segments.map((segment) => segment.text).join("") + : block.text; + const trimmed = text.trim(); + if (trimmed !== "") return trimmed; + } + return ""; +} + +export function hostLabel(rawUrl: string): string { + try { + return new URL(rawUrl).hostname.toLowerCase().replace(/^www\./, ""); + } catch { + return ""; + } +} + +export function previewTitle( + titleHint: string, + blocks: PreviewBlock[], +): string { + return ( + titleHint.trim().slice(0, PREVIEW_TITLE_MAX_CHARS) || + firstHeading(blocks) || + "Article preview" + ); +} diff --git a/platforms/cloudflare/test/browserPreviewFallback.spec.ts b/platforms/cloudflare/test/browserPreviewFallback.spec.ts new file mode 100644 index 0000000..68890a5 --- /dev/null +++ b/platforms/cloudflare/test/browserPreviewFallback.spec.ts @@ -0,0 +1,180 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import type { PreviewFallbackInput } from "../../../core/preview.ts"; +import type { Env } from "../src/env.d.ts"; +import { browserPreviewFallback } from "../src/browserPreviewFallback.ts"; + +const HTML_INPUT: PreviewFallbackInput = { + kind: "no_content", + url: "https://example.com/posts/shell", + contentType: "text/html; charset=utf-8", + html: "
", +}; + +function envWith( + flag: string, + quickAction: (action: string, options: unknown) => Promise, +): Env { + return { + FEEDREADER_BROWSER_PREVIEW_FALLBACK: flag, + BROWSER: { quickAction }, + } as unknown as Env; +} + +function successResponse( + result: string, + meta: Record = {}, +): Response { + return Response.json({ + success: true, + result, + meta: { + status: 200, + title: "Example", + finalUrl: "https://example.com/posts/shell", + ...meta, + }, + }); +} + +beforeEach(() => { + vi.spyOn(console, "log").mockImplementation(() => {}); + vi.spyOn(console, "warn").mockImplementation(() => {}); +}); + +afterEach(() => { + vi.restoreAllMocks(); +}); + +describe("browserPreviewFallback", () => { + it("does nothing when the env flag is false", async () => { + const quickAction = vi.fn(async () => successResponse("Unused.")); + const result = await browserPreviewFallback( + envWith("false", quickAction), + HTML_INPUT, + "Stored title", + ); + + expect(result).toBeNull(); + expect(quickAction).not.toHaveBeenCalled(); + }); + + it("only handles no_content HTML failures", async () => { + const quickAction = vi.fn(async () => successResponse("Unused.")); + + for (const kind of ["too_large", "unsupported_content_type"] as const) { + const result = await browserPreviewFallback( + envWith("true", quickAction), + { ...HTML_INPUT, kind }, + "Stored title", + ); + expect(result).toBeNull(); + } + expect(quickAction).not.toHaveBeenCalled(); + }); + + it("maps rendered Markdown to a preview", async () => { + const quickAction = vi.fn(async () => + successResponse(`--- +title: "TodoMVC: React" +--- + +### Rendered + +A long enough paragraph rendered after JavaScript executes.`), + ); + + const result = await browserPreviewFallback( + envWith("true", quickAction), + HTML_INPUT, + "Stored title", + ); + + expect(quickAction).toHaveBeenCalledWith( + "markdown", + expect.objectContaining({ + url: HTML_INPUT.url, + gotoOptions: expect.objectContaining({ + waitUntil: "networkidle2", + }), + bestAttempt: true, + rejectResourceTypes: ["image", "media", "font"], + }), + ); + expect(result).toMatchObject({ + title: "Stored title", + siteName: "example.com", + readingMinutes: 1, + blocks: [ + { type: "heading", text: "Rendered" }, + { + type: "paragraph", + text: "A long enough paragraph rendered after JavaScript executes.", + }, + ], + }); + }); + + it("rejects a final URL that is not public", async () => { + const quickAction = vi.fn(async () => + successResponse("A long enough paragraph from a private redirect.", { + finalUrl: "http://127.0.0.1/internal", + }), + ); + + const result = await browserPreviewFallback( + envWith("true", quickAction), + HTML_INPUT, + "Stored title", + ); + + expect(result).toBeNull(); + }); + + it("returns null on a rate-limit error", async () => { + const quickAction = vi.fn(async () => + Response.json( + { + success: false, + errors: [{ code: 2001, message: "Rate limit exceeded" }], + }, + { status: 429 }, + ), + ); + + const result = await browserPreviewFallback( + envWith("true", quickAction), + HTML_INPUT, + "Stored title", + ); + + expect(result).toBeNull(); + }); + + it("returns null when the rendered page itself is an error", async () => { + const quickAction = vi.fn(async () => + successResponse("Not found. A long enough paragraph of error text.", { + status: 404, + }), + ); + + const result = await browserPreviewFallback( + envWith("true", quickAction), + HTML_INPUT, + "Stored title", + ); + + expect(result).toBeNull(); + }); + + it("returns null when the rendered page has no readable blocks", async () => { + const quickAction = vi.fn(async () => successResponse("tiny")); + + const result = await browserPreviewFallback( + envWith("true", quickAction), + HTML_INPUT, + "Stored title", + ); + + expect(result).toBeNull(); + }); +}); diff --git a/platforms/cloudflare/test/previewFallbackChain.spec.ts b/platforms/cloudflare/test/previewFallbackChain.spec.ts new file mode 100644 index 0000000..402cf10 --- /dev/null +++ b/platforms/cloudflare/test/previewFallbackChain.spec.ts @@ -0,0 +1,143 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import type { PreviewFallbackInput } from "../../../core/preview.ts"; +import type { Env } from "../src/env.d.ts"; +import { createPreviewFallback } from "../src/previewFallbackChain.ts"; + +const HTML_INPUT: PreviewFallbackInput = { + kind: "no_content", + url: "https://example.com/posts/shell", + contentType: "text/html; charset=utf-8", + html: "
", +}; + +function envWith( + flags: { ai: string; browser: string }, + toMarkdown: (...args: unknown[]) => Promise, + quickAction: (...args: unknown[]) => Promise, +): Env { + return { + FEEDREADER_AI_PREVIEW_FALLBACK: flags.ai, + FEEDREADER_BROWSER_PREVIEW_FALLBACK: flags.browser, + AI: { toMarkdown }, + BROWSER: { quickAction }, + } as unknown as Env; +} + +function aiConversion(data: string): Record { + return { + id: "conversion-1", + name: "article.html", + mimeType: "text/html", + format: "markdown", + tokens: 10, + data, + }; +} + +function browserSuccess(result: string): Response { + return Response.json({ + success: true, + result, + meta: { + status: 200, + title: "Example", + finalUrl: "https://example.com/posts/shell", + }, + }); +} + +beforeEach(() => { + vi.spyOn(console, "log").mockImplementation(() => {}); + vi.spyOn(console, "warn").mockImplementation(() => {}); +}); + +afterEach(() => { + vi.restoreAllMocks(); +}); + +describe("createPreviewFallback", () => { + it("uses the AI fallback first", async () => { + const toMarkdown = vi.fn(async () => + aiConversion( + "A long enough paragraph recovered from the AI conversion.", + ), + ); + const quickAction = vi.fn(async () => + browserSuccess("A long enough paragraph rendered by the browser."), + ); + const fallback = createPreviewFallback( + envWith({ ai: "true", browser: "true" }, toMarkdown, quickAction), + "Stored title", + ); + + const result = await fallback?.(HTML_INPUT); + + expect(result?.blocks).toEqual([ + { + type: "paragraph", + text: "A long enough paragraph recovered from the AI conversion.", + }, + ]); + expect(quickAction).not.toHaveBeenCalled(); + }); + + it("falls through to Browser Run when AI returns nothing", async () => { + const toMarkdown = vi.fn(async () => ({ + id: "conversion-1", + name: "article.html", + mimeType: "text/html", + format: "error", + error: "no readable content", + })); + const quickAction = vi.fn(async () => + browserSuccess( + "A long enough paragraph rendered after JavaScript executes.", + ), + ); + const fallback = createPreviewFallback( + envWith({ ai: "true", browser: "true" }, toMarkdown, quickAction), + "Stored title", + ); + + const result = await fallback?.(HTML_INPUT); + + expect(toMarkdown).toHaveBeenCalledTimes(1); + expect(quickAction).toHaveBeenCalledTimes(1); + expect(result?.blocks).toEqual([ + { + type: "paragraph", + text: "A long enough paragraph rendered after JavaScript executes.", + }, + ]); + }); + + it("can use Browser Run without the AI fallback", async () => { + const toMarkdown = vi.fn(async () => aiConversion("Unused AI output.")); + const quickAction = vi.fn(async () => + browserSuccess("A long enough paragraph rendered by the browser."), + ); + const fallback = createPreviewFallback( + envWith({ ai: "false", browser: "true" }, toMarkdown, quickAction), + "Stored title", + ); + + const result = await fallback?.(HTML_INPUT); + + expect(toMarkdown).not.toHaveBeenCalled(); + expect(quickAction).toHaveBeenCalledTimes(1); + expect(result?.blocks).toHaveLength(1); + }); + + it("returns undefined when both fallbacks are disabled", () => { + const fallback = createPreviewFallback( + envWith( + { ai: "false", browser: "false" }, + async () => aiConversion("Unused."), + async () => browserSuccess("Unused."), + ), + "Stored title", + ); + + expect(fallback).toBeUndefined(); + }); +}); diff --git a/platforms/cloudflare/wrangler.toml b/platforms/cloudflare/wrangler.toml index 092e2e7..98589da 100644 --- a/platforms/cloudflare/wrangler.toml +++ b/platforms/cloudflare/wrangler.toml @@ -53,6 +53,12 @@ service = "feedreader" [ai] binding = "AI" +# Browser Run binding for the JavaScript-rendered preview fallback (see +# platforms/cloudflare/src/browserPreviewFallback.ts). Workers Free includes +# 10 browser-minutes/day and one Quick Action request per 10 seconds. +[browser] +binding = "BROWSER" + [vars] APP_VERSION = "dev" FEEDREADER_ITEMS_PER_SOURCE = "20" @@ -73,6 +79,10 @@ FEEDREADER_PERSONALIZE_POLISH_POOL_SIZE = "30" # can't read (PDFs/Office documents, JavaScript shells, truncated bodies). # Set to "false" to disable it without a code change. FEEDREADER_AI_PREVIEW_FALLBACK = "true" +# Browser Run fallback for HTML pages that still have no readable content +# after the static extractor and AI fallback. Runs only on a preview cache +# miss and is cached for 30 minutes. Set to "false" to disable it. +FEEDREADER_BROWSER_PREVIEW_FALLBACK = "true" # REFRESH_SECRET is a secret, not a var — set it with: # wrangler secret put REFRESH_SECRET --config platforms/cloudflare/wrangler.toml From 567d07fae52df291b178124fea2f497cdfebc1f7 Mon Sep 17 00:00:00 2001 From: Phat Pham Date: Fri, 13 Nov 2026 13:16:07 +0700 Subject: [PATCH 4/6] chore(test): remove temporary browser fallback smoke test Co-Authored-By: Claude Code --- platforms/cloudflare/src/index.ts | 15 --------------- web-static/browser-test.html | 16 ---------------- 2 files changed, 31 deletions(-) delete mode 100644 web-static/browser-test.html diff --git a/platforms/cloudflare/src/index.ts b/platforms/cloudflare/src/index.ts index 834e9e7..43a59d0 100644 --- a/platforms/cloudflare/src/index.ts +++ b/platforms/cloudflare/src/index.ts @@ -125,21 +125,6 @@ export default { if (url.pathname.startsWith("/internal/refresh/")) { return handleInternalRefresh(request, env, repo, sources, url); } - // TEMPORARY: full preview-fallback smoke test; removed before merge. - if (url.pathname === "/debug/browser-fallback") { - const target = normalizePreviewUrl(url.searchParams.get("url") ?? ""); - if (!target) { - return Response.json({ error: "url is required" }, { status: 400 }); - } - const fallback = createPreviewFallback(env, "Browser preview test"); - const preview = await fallback?.({ - kind: "no_content", - url: target, - contentType: "text/html", - html: "", - }); - return Response.json({ preview }); - } return new Response("not found", { status: 404 }); }, diff --git a/web-static/browser-test.html b/web-static/browser-test.html deleted file mode 100644 index 41fe198..0000000 --- a/web-static/browser-test.html +++ /dev/null @@ -1,16 +0,0 @@ - - - - - Browser preview test - - -
- - - From 033df0c7121e0a956d5ca26cd633d8fb72f63e46 Mon Sep 17 00:00:00 2001 From: Phat Pham Date: Fri, 13 Nov 2026 13:16:07 +0700 Subject: [PATCH 5/6] docs(preview): document the Browser Run fallback Co-Authored-By: Claude Code --- README.md | 7 +++++-- docs/ARCHITECTURE.md | 5 +++-- docs/DEPLOYMENT.md | 2 +- docs/RUNBOOK.md | 6 ++++-- 4 files changed, 13 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index debfdd4..cbe2e15 100644 --- a/README.md +++ b/README.md @@ -79,7 +79,7 @@ npx lighthouse https://reader.boringcode.dev --view - **Scheduled refresh** every 1 hour on wall-clock boundaries - **Manual refresh** from the header re-fetches the current feed view from backend stored items only; it does **not** re-fetch upstream sources - **Persisted visited-link dimming** for feed card titles across reload/reopen using local storage -- **Optional article preview** (off by default, toggled in Reader settings) that opens a reader view beside the feed on wide screens or full-screen on phones, with inline links/emphasis, image captions, tables, publication date/reading time, a Workers AI Markdown fallback for PDFs, Office documents, and HTML pages with no readable blocks, source-specific Hacker News comments, and an **Open source** button +- **Optional article preview** (off by default, toggled in Reader settings) that opens a reader view beside the feed on wide screens or full-screen on phones, with inline links/emphasis, image captions, tables, publication date/reading time, a Workers AI Markdown fallback for PDFs, Office documents, and HTML pages with no readable blocks, a Browser Run fallback for JavaScript-rendered pages, source-specific Hacker News comments, and an **Open source** button - **Saved articles** with an optional per-card bookmark toggle, a `Saved` filter, and a preview-panel toggle; bookmark controls are disabled by default and can be enabled in Reader settings, with saved items stored locally under `feedreader.bookmarks` - **PWA-ready assets and offline caching** including manifest, service worker, touch icons, cached shell assets, cached `/api/items` responses for previously visited views, a standalone launch veil, and skeleton loading states - **Reconnect list refresh** re-fetches the current view from backend stored items only; it does **not** refresh upstream sources @@ -213,6 +213,8 @@ Bindings configured in `platforms/cloudflare/wrangler.toml`: - `DB` — D1 database binding - `ASSETS` — Workers Static Assets binding for `web-static/` - `SELF` — service binding back to the same Worker for per-source refresh fan-out +- `AI` — Workers AI binding for personalization and the Markdown preview fallback +- `BROWSER` — Browser Run binding for the JavaScript-rendered preview fallback Runtime configuration: @@ -221,6 +223,7 @@ Runtime configuration: | `FEEDREADER_ITEMS_PER_SOURCE` | `20` | Per-source item count used in source dashboard/health contexts | | `FEEDREADER_USER_AGENT` | `feedreader/0.1` | Outbound fetch user agent | | `FEEDREADER_AI_PREVIEW_FALLBACK` | `true` | Workers AI Markdown fallback for PDFs/Office documents and empty previews; `false` disables it | +| `FEEDREADER_BROWSER_PREVIEW_FALLBACK` | `true` | Browser Run fallback for JavaScript-rendered HTML previews; `false` disables it | | `REFRESH_SECRET` | _required secret_ | Shared secret for internal per-source refresh fan-out routes | --- @@ -266,7 +269,7 @@ Returns a reader view for a stored feed item: rich text segments, image blocks w - `url` — required; must exactly match the URL of an item currently stored in D1 -The Worker fetches the article with a 10-second timeout and a 400 KB HTML cap, rejects non-public hosts, and never returns upstream markup. When the built-in extractor finds no readable blocks or the response is a document (PDF/Office), the Worker can convert it through Workers AI's Markdown conversion with a 5 MB cap; set `FEEDREADER_AI_PREVIEW_FALLBACK=false` to disable that fallback. Inline targets and images are restricted to validated public http(s) URLs. Responses are edge-cached for 30 minutes. Returns `404` for unknown URLs and `502` when the upstream page cannot be previewed. +The Worker fetches the article with a 10-second timeout and a 400 KB HTML cap, rejects non-public hosts, and never returns upstream markup. When the built-in extractor finds no readable blocks or the response is a document (PDF/Office), the Worker can convert it through Workers AI's Markdown conversion with a 5 MB cap; if an HTML page still has no readable content, it can render the page through Browser Run. Set `FEEDREADER_AI_PREVIEW_FALLBACK=false` or `FEEDREADER_BROWSER_PREVIEW_FALLBACK=false` to disable either fallback. Inline targets and images are restricted to validated public http(s) URLs. Responses are edge-cached for 30 minutes. Returns `404` for unknown URLs and `502` when the upstream page cannot be previewed. ### `POST /api/refresh` diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index d275a1c..b8b26ae 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -14,6 +14,7 @@ | [`platforms/cloudflare/src/index.ts`](../platforms/cloudflare/src/index.ts) | Worker request router and scheduled entrypoint. | | [`platforms/cloudflare/src/repository.ts`](../platforms/cloudflare/src/repository.ts) | D1-backed `FeedRepository` implementation. | | [`platforms/cloudflare/src/previewFallback.ts`](../platforms/cloudflare/src/previewFallback.ts) | Workers AI `toMarkdown` adapter for document/empty previews. | +| [`platforms/cloudflare/src/browserPreviewFallback.ts`](../platforms/cloudflare/src/browserPreviewFallback.ts) | Browser Run markdown adapter for JavaScript-rendered pages. | | [`platforms/cloudflare/migrations/`](../platforms/cloudflare/migrations) | D1 schema migrations. | | [`web-static/`](../web-static) | Browser assets: CSS, JS, icons, manifest, service worker. | @@ -76,7 +77,7 @@ This keeps refresh logic, rendering, and feed shaping independent of D1-specific ## Caching - `GET /` is cached per URL (including the raw query string) for five minutes through the Cache API. `APP_VERSION` is part of the key and changes on every deploy, so a release invalidates old HTML; local `wrangler dev` keeps `APP_VERSION` at `dev` and skips the home cache so template/CSS edits are never hidden. The browser-facing response is `private, no-store`: the five-minute copy is internal to the Cache API, which keeps Cloudflare's Browser Cache TTL setting from rewriting the client TTL. -- `GET /api/items` is edge-cached until the underlying sources next refresh (the key includes `sync_state.last_success_at`). Successful article previews, including AI-converted ones, are cached for 30 minutes. Both endpoints use the same split as the home page: the Cache API holds the edge copy, while clients receive `private, no-store`, so the CDN/Browser Cache TTL cannot extend the client TTL. +- `GET /api/items` is edge-cached until the underlying sources next refresh (the key includes `sync_state.last_success_at`). Successful article previews, including AI- and Browser Run-converted ones, are cached for 30 minutes. Both endpoints use the same split as the home page: the Cache API holds the edge copy, while clients receive `private, no-store`, so the CDN/Browser Cache TTL cannot extend the client TTL. - `style.css` and `theme-init.js` are read from the `ASSETS` binding once per isolate and inlined into the server-rendered HTML, so first paint has no render-blocking network requests. The files remain the single source of truth and are still served directly for cached shells. - [`web-static/_headers`](../web-static/_headers) marks versioned static assets as immutable for a year; `service-worker.js` keeps `must-revalidate` so updates land. @@ -98,7 +99,7 @@ The optional article preview is served by `GET /api/preview?url=…`. - The requested URL must exactly match a stored `items.url`. This check, not the fetch layer, is what keeps the endpoint from acting as an open proxy; `feedreader.articlePreviewEnabled` only controls the client behavior. - `core/preview.ts` additionally rejects non-http(s) schemes, credentials, non-standard ports, and loopback/private/link-local hosts, and re-checks the final URL after redirects. - Article fetches time out after 10 seconds and read at most 400 KB of HTML (5 MB when a document is handed to the optional fallback). Transient upstream `429`/`5xx` responses are retried once with jitter. `PreviewUnavailableError` carries a structured reason (`blocked`, `rate_limited`, `upstream_error`, `timeout`, `unsupported_content_type`, `too_large`, `empty_body`, `redirect`, `invalid_url`) plus the optional upstream status; the endpoint logs `preview_unavailable`/`preview_empty` events and returns the reason so the client can show a specific message. The extractor removes scripts/navigation/footer noise and returns structured text segments, image blocks, and table blocks only — upstream HTML is never returned or injected. Text renders with `textContent`/DOM nodes; inline anchors are limited to URLs that pass the same public http(s) validation, and image URLs are re-validated before the browser loads them directly with `loading="lazy"` and `referrerpolicy="no-referrer"`. -- If the built-in extractor finds no blocks (`no_content`), truncation left no blocks (`too_large`), or the upstream is a non-HTML document (`unsupported_content_type`), `fetchArticlePreview` may call an injected fallback. Core stays AI-free: the Worker supplies `platforms/cloudflare/src/previewFallback.ts`, which calls `env.AI.toMarkdown`, maps the converted Markdown through `core/previewMarkdown.ts`, and returns the same validated `PreviewBlock` shape. The mapper re-checks every link and image with `normalizePreviewUrl`, strips trailing JSON-LD, and drops PDF filename/page-marker headings. Blocked, timeout, rate-limited, and empty-body failures never reach the fallback. `FEEDREADER_AI_PREVIEW_FALLBACK=false` disables it. +- If the built-in extractor finds no blocks (`no_content`), truncation left no blocks (`too_large`), or the upstream is a non-HTML document (`unsupported_content_type`), `fetchArticlePreview` may call an injected fallback. Core stays platform-free: the Worker supplies a chain (`platforms/cloudflare/src/previewFallbackChain.ts`). Workers AI (`previewFallback.ts`) calls `env.AI.toMarkdown`; Browser Run (`browserPreviewFallback.ts`) calls `env.BROWSER.quickAction("markdown", …)` only for `no_content` after AI fails. Both map the converted Markdown through `core/previewMarkdown.ts`, which re-checks every link and image with `normalizePreviewUrl`, strips YAML frontmatter and trailing JSON-LD, and drops PDF filename/page-marker headings. Browser Run waits for `networkidle2` with 8-second navigation/action and 9-second outer timeouts, rejects images/media/fonts and literal private-host requests, and validates the rendered page status and `meta.finalUrl`. Blocked, timeout, rate-limited, and empty-body failures never reach the fallback. `FEEDREADER_AI_PREVIEW_FALLBACK=false` and `FEEDREADER_BROWSER_PREVIEW_FALLBACK=false` disable each adapter. - Image blocks may include a `figcaption`-derived caption and intrinsic width/height to reserve layout space. Known avatar/profile-image hosts and paths, SVG wordmarks, and common badge hosts are dropped before the image cap so author-list and README chrome doesn't displace article figures. Table blocks carry a header flag and capped rows/cells. The response also includes byline, publication date, and an estimated reading time. For Hugging Face paper URLs the extractor starts at the Abstract section, then appends the paper's resource links and citing model, dataset, space, and collection lists while excluding community comment chrome; GitHub titles drop the site prefix. The preview and card `…` dialogs expose a stored Hacker News comments URL for HN items; other sources omit it. - The client highlights the card matching the open preview and provides previous/next navigation over the currently rendered card list, skipping duplicate or unusable cards. When the last rendered card is previewed, Next remains enabled if another page exists and appends it before advancing. On mobile the open panel pins the body scroll position (and reapplies it after rotation), the glass header/footer auto-hide on scroll down and return on scroll up, and the `theme-color` tint switches to the panel surface while the panel covers the viewport. A left-edge rightward drag follows the finger and reveals the preserved feed position underneath; releasing past a distance/velocity threshold slides the panel away and closes it, while a shorter drag springs back. Vertical edge drags remain native scrolling and the gesture is inactive while the `…` dialog is open. - Card host rows keep the optional bookmark toggle and a more-actions dialog trigger. The dialog exposes Share, the stored Hacker News comments URL when present, and Open source; choosing an action does not open the preview. diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index b38fbd3..0039369 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -64,6 +64,6 @@ The checked-in `wrangler.toml` config does not hardcode a route. Domain attachme - Workers: 100k requests/day, 10ms CPU time per invocation, 50 subrequests per request. - The five-minute home-page cache absorbs most `GET /` traffic, so only cache misses run the feed query and render the HTML. The browser response is `private, no-store`; edge caching is the Worker Cache API, not the CDN, so the zone's Browser Cache TTL setting cannot rewrite the client TTL. Each cold-isolate cache miss also reads `style.css` and `theme-init.js` through the `ASSETS` binding (two local subrequests), then reuses them in memory. - The standalone launch veil and skeleton styles are inlined with the existing HTML/CSS, so they add no extra requests. Bump the shell cache version when the HTML shell or `app.js` changes; see [RUNBOOK.md](RUNBOOK.md#pwa-shell-updates). -- Article previews add one outbound fetch (and one `node-html-parser` parse) per uncached `/api/preview` request. The 400 KB HTML body cap and 30-minute edge cache in `core/preview.ts` bound that cost; transient upstream `429`/`5xx` responses are retried once. PDFs/Office documents and HTML pages with no readable blocks can additionally call Workers AI's `toMarkdown` (5 MB download cap; document text conversion is free and the fallback disables AI image-description conversion). That call runs only on a cache miss and its result is cached for the same 30 minutes; set `FEEDREADER_AI_PREVIEW_FALLBACK=false` to disable it. Browser-facing preview and `/api/items` responses are `private, no-store`; their edge copies live in the Cache API. Watch the CPU-time panel if preview usage is heavy — bursts can hit the Workers Free 10 ms limit, so see [RUNBOOK.md](RUNBOOK.md#article-preview-failures). Richer preview blocks (inline links, captions, tables) increase the cached response payload but not the upstream fetch count; the same byte cap and cache TTL apply. +- Article previews add one outbound fetch (and one `node-html-parser` parse) per uncached `/api/preview` request. The 400 KB HTML body cap and 30-minute edge cache in `core/preview.ts` bound that cost; transient upstream `429`/`5xx` responses are retried once. PDFs/Office documents and HTML pages with no readable blocks can additionally call Workers AI's `toMarkdown` (5 MB download cap; document text conversion is free and the fallback disables AI image-description conversion). That call runs only on a cache miss and its result is cached for the same 30 minutes; set `FEEDREADER_AI_PREVIEW_FALLBACK=false` to disable it. HTML pages that still have no readable content after AI conversion can call Browser Run's `markdown` Quick Action; Workers Free includes 10 browser-minutes/day and paces Quick Actions to one request per 10 seconds. Browser Run runs only on a cache miss, uses no browser sessions (so the concurrent-browser limit does not apply), and its result is cached for 30 minutes; set `FEEDREADER_BROWSER_PREVIEW_FALLBACK=false` to disable it. Browser-facing preview and `/api/items` responses are `private, no-store`; their edge copies live in the Cache API. Watch the CPU-time panel if preview usage is heavy — bursts can hit the Workers Free 10 ms limit, so see [RUNBOOK.md](RUNBOOK.md#article-preview-failures). Richer preview blocks (inline links, captions, tables) increase the cached response payload but not the upstream fetch count; the same byte cap and cache TTL apply. Check the Cloudflare dashboard's D1 usage and Workers CPU-time panels periodically — see [RUNBOOK.md](RUNBOOK.md) for what to do if a source consistently nears the CPU ceiling. diff --git a/docs/RUNBOOK.md b/docs/RUNBOOK.md index 5e9dabd..0fba708 100644 --- a/docs/RUNBOOK.md +++ b/docs/RUNBOOK.md @@ -80,11 +80,13 @@ Use Cloudflare dashboard → Workers & Pages → `feedreader` → Triggers → C - `504 timeout` — the fetch exceeded the 10-second timeout - `502 too_large` — the HTML exceeded the 400 KB cap before readable content, or a document exceeded the 5 MB fallback cap - `502 unsupported_content_type` / `empty_body` / `redirect` / `fetch_failed` — other fetch or extraction failures. `unsupported_content_type` also covers a document the AI fallback could not convert (disabled, timed out, or unsupported by `toMarkdown`). -- `200` with `reason: "no_content"` — the page was fetched and had no readable blocks, and the AI fallback was disabled or returned nothing. +- `200` with `reason: "no_content"` — the page was fetched and had no readable blocks, and neither the AI nor Browser Run fallback produced content. Before returning `unsupported_content_type` for a non-HTML response, `too_large` for a truncated page, or `no_content` for an empty HTML page, `fetchArticlePreview` calls the optional Workers AI `toMarkdown` fallback (`platforms/cloudflare/src/previewFallback.ts`). It downloads at most 5 MB (`DEFAULT_MAX_FALLBACK_BYTES`), races the conversion against a 10-second timeout, strips the filename/page-marker headings from PDF output, and maps the Markdown back into validated preview blocks. Standalone images are skipped; the fallback disables AI image-description conversion. Set `FEEDREADER_AI_PREVIEW_FALLBACK=false` to disable it. Document text conversion is free in Workers AI. -The Worker logs `preview_unavailable` and `preview_empty` events with the URL, reason, and upstream status, plus a `preview_ai_fallback` event for each attempt (`kind`, `outcome` = `ok`/`empty`/`error`, `ms`, `blocks`, `tokens`, and a capped `error`). Successful previews, including AI-converted ones, are edge-cached for 30 minutes via the Cache API; browser-facing responses are `private, no-store`. Transient upstream `429`/`5xx` responses are retried once with jitter. If bursts produce transient `503`s, check Workers Logs/CPU: the extractor runs in the request invocation, and sequential retries succeeding usually points at the Workers Free 10 ms CPU limit rather than a lasting upstream block. Lowering `DEFAULT_MAX_BYTES` in `core/preview.ts` (400 KB today) reduces the parse cost. +If the AI conversion returns nothing for an HTML page, the chain calls Browser Run's `markdown` Quick Action (`platforms/cloudflare/src/browserPreviewFallback.ts`) before returning `no_content`. It is limited to `no_content`; PDFs/Office documents, `too_large`, `blocked`, `timeout`, and rate-limited failures never reach it. Browser Run waits for `networkidle2` with 8-second navigation/action and 9-second outer timeouts, blocks images/media/fonts and literal private-host requests, and validates the rendered page status and final URL. Workers Free includes 10 browser-minutes/day and paces Quick Actions to one request per 10 seconds; a `429` is logged and treated as no preview. Set `FEEDREADER_BROWSER_PREVIEW_FALLBACK=false` to disable it. Browser Run successes are cached for 30 minutes; the preview cache key is `preview:v11`. + +The Worker logs `preview_unavailable` and `preview_empty` events with the URL, reason, and upstream status, plus a `preview_ai_fallback` event for each AI attempt (`kind`, `outcome` = `ok`/`empty`/`error`, `ms`, `blocks`, `tokens`, and a capped `error`) and a `preview_browser_fallback` event for each Browser Run attempt (`outcome`, `status`, `page_status`, `browser_ms`, `blocks`, and a capped `error`). Successful previews, including AI- and Browser Run-converted ones, are edge-cached for 30 minutes via the Cache API; browser-facing responses are `private, no-store`. Transient upstream `429`/`5xx` responses are retried once with jitter. If bursts produce transient `503`s, check Workers Logs/CPU: the extractor runs in the request invocation, and sequential retries succeeding usually points at the Workers Free 10 ms CPU limit rather than a lasting upstream block. Lowering `DEFAULT_MAX_BYTES` in `core/preview.ts` (400 KB today) reduces the parse cost. ## Local SSR smoke procedure From 68c927905ae1c05c28488ee8f273ced505d5dd2a Mon Sep 17 00:00:00 2001 From: Phat Pham Date: Fri, 13 Nov 2026 13:22:12 +0700 Subject: [PATCH 6/6] fix(preview): harden Browser Run URL handling Re-validate the fallback input URL at the adapter boundary and extend the request-level reject pattern to cloud-metadata names and IPv6 private ranges. Validate every reported redirect hop and the rendered final URL before returning any content. The stored-item allowlist and core's safe-redirect fetch remain the primary SSRF boundary; Browser Run egress covers DNS-resolved private addresses, which Workers cannot pin. Add tests for invalid targets, private redirects, and the reject pattern. Co-Authored-By: Claude Code --- .../cloudflare/src/browserPreviewFallback.ts | 64 +++++++++++++++++-- .../test/browserPreviewFallback.spec.ts | 53 ++++++++++++++- 2 files changed, 110 insertions(+), 7 deletions(-) diff --git a/platforms/cloudflare/src/browserPreviewFallback.ts b/platforms/cloudflare/src/browserPreviewFallback.ts index ae90089..76ab78b 100644 --- a/platforms/cloudflare/src/browserPreviewFallback.ts +++ b/platforms/cloudflare/src/browserPreviewFallback.ts @@ -4,6 +4,11 @@ // render the page in a real browser and return Markdown; the mapper then // applies the same URL/block validation as the other extractors. // +// input.url is the final URL validated by core's safe-redirect fetch. This +// adapter re-validates it and rejects literal private-host requests (and +// redirect hops) as defense-in-depth; Browser Run's own egress is the layer +// for DNS-resolved private addresses, which Workers cannot pin. +// // Workers Free includes 10 browser-minutes/day and paces Quick Actions to // one request per 10 seconds. This adapter runs only on a preview cache miss // after the static extractor and AI fallback both found nothing; successes @@ -33,10 +38,11 @@ const REJECTED_RESOURCE_TYPES: BrowserRunResourceType[] = [ "font", ]; // Quick Actions do not support session guardrails. Block literal private -// hosts at the request layer and re-check meta.finalUrl below; the -// stored-item allowlist remains the primary SSRF boundary. +// hosts and cloud-metadata names at the request layer and re-check the +// redirect chain/final URL below; the stored-item allowlist remains the +// primary SSRF boundary. const PRIVATE_HOST_REQUEST_PATTERN = - "/^https?:\\/\\/(?:localhost|127\\.|0\\.|10\\.|192\\.168\\.|169\\.254\\.|172\\.(?:1[6-9]|2[0-9]|3[01])\\.|\\[::1\\]|\\[f[cd])/"; + "/^https?:\\/\\/(?:localhost|127\\.|0\\.|10\\.|192\\.168\\.|169\\.254\\.|172\\.(?:1[6-9]|2[0-9]|3[01])\\.|metadata\\.google\\.internal|metadata\\.goog|instance-data|\\[::1\\]|\\[::ffff:|\\[f[cd]|\\[fe[89ab])/"; export async function browserPreviewFallback( env: Env, @@ -47,12 +53,14 @@ export async function browserPreviewFallback( return null; } if (input.kind !== "no_content") return null; + const target = normalizePreviewUrl(input.url); + if (!target) return null; const startedAt = Date.now(); try { const response = await withTimeout( env.BROWSER.quickAction("markdown", { - url: input.url, + url: target, gotoOptions: { timeout: BROWSER_GOTO_TIMEOUT_MS, // SPAs finish rendering after the initial DOM load; wait for the @@ -101,7 +109,18 @@ export async function browserPreviewFallback( return null; } - const finalUrl = normalizePreviewUrl(payload.meta.finalUrl ?? input.url); + if (!hasOnlyPublicRedirects(payload.meta.redirectChain)) { + logBrowserFallback(input, startedAt, { + outcome: "error", + status: response.status, + pageStatus, + browserMs, + error: "unusable redirect chain", + }); + return null; + } + + const finalUrl = normalizePreviewUrl(payload.meta.finalUrl ?? target); if (!finalUrl) { logBrowserFallback(input, startedAt, { outcome: "error", @@ -155,6 +174,41 @@ function isBrowserFallbackEnabled(raw: string | undefined): boolean { return (raw ?? "true").trim().toLowerCase() !== "false"; } +/** + * Browser Run follows redirects itself. Reject the rendered result if any + * hop's source or Location is not a public http(s) URL; the request-layer + * reject pattern is the corresponding prevention layer. + */ +function hasOnlyPublicRedirects( + hops: BrowserRunRedirectHop[] | undefined, +): boolean { + if (!hops) return true; + for (const hop of hops) { + if (!normalizePreviewUrl(hop.url)) return false; + const location = headerValue(hop.headers, "location"); + if (location === undefined) return false; + let next: string; + try { + next = new URL(location, hop.url).toString(); + } catch { + return false; + } + if (!normalizePreviewUrl(next)) return false; + } + return true; +} + +function headerValue( + headers: Record, + name: string, +): string | undefined { + const target = name.toLowerCase(); + for (const [key, value] of Object.entries(headers)) { + if (key.toLowerCase() === target) return value; + } + return undefined; +} + function parseHeaderInt(raw: string | null): number | undefined { if (raw === null) return undefined; const value = Number.parseInt(raw, 10); diff --git a/platforms/cloudflare/test/browserPreviewFallback.spec.ts b/platforms/cloudflare/test/browserPreviewFallback.spec.ts index 68890a5..35b6541 100644 --- a/platforms/cloudflare/test/browserPreviewFallback.spec.ts +++ b/platforms/cloudflare/test/browserPreviewFallback.spec.ts @@ -58,6 +58,18 @@ describe("browserPreviewFallback", () => { expect(quickAction).not.toHaveBeenCalled(); }); + it("rejects an unusable input URL before calling Browser Run", async () => { + const quickAction = vi.fn(async () => successResponse("Unused.")); + const result = await browserPreviewFallback( + envWith("true", quickAction), + { ...HTML_INPUT, url: "http://127.0.0.1/private" }, + "Stored title", + ); + + expect(result).toBeNull(); + expect(quickAction).not.toHaveBeenCalled(); + }); + it("only handles no_content HTML failures", async () => { const quickAction = vi.fn(async () => successResponse("Unused.")); @@ -73,8 +85,9 @@ describe("browserPreviewFallback", () => { }); it("maps rendered Markdown to a preview", async () => { - const quickAction = vi.fn(async () => - successResponse(`--- + const quickAction = vi.fn( + async (_action: string, _options: unknown) => + successResponse(`--- title: "TodoMVC: React" --- @@ -100,6 +113,20 @@ A long enough paragraph rendered after JavaScript executes.`), rejectResourceTypes: ["image", "media", "font"], }), ); + + const options = quickAction.mock.calls[0]?.[1] as { + rejectRequestPattern?: string[]; + }; + const pattern = options.rejectRequestPattern?.[0]; + expect(pattern).toBeDefined(); + const privateHost = new RegExp( + pattern!.slice(1, pattern!.lastIndexOf("/")), + ); + expect(privateHost.test("http://127.0.0.1/x")).toBe(true); + expect(privateHost.test("http://[::ffff:127.0.0.1]/x")).toBe(true); + expect(privateHost.test("https://metadata.google.internal/")).toBe(true); + expect(privateHost.test("https://example.com/x")).toBe(false); + expect(result).toMatchObject({ title: "Stored title", siteName: "example.com", @@ -130,6 +157,28 @@ A long enough paragraph rendered after JavaScript executes.`), expect(result).toBeNull(); }); + it("rejects a redirect chain that reaches a private host", async () => { + const quickAction = vi.fn(async () => + successResponse("A long enough paragraph after a redirect.", { + redirectChain: [ + { + url: "https://example.com/start", + status: 302, + headers: { location: "http://127.0.0.1/internal" }, + }, + ], + }), + ); + + const result = await browserPreviewFallback( + envWith("true", quickAction), + HTML_INPUT, + "Stored title", + ); + + expect(result).toBeNull(); + }); + it("returns null on a rate-limit error", async () => { const quickAction = vi.fn(async () => Response.json(