Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -369,6 +369,7 @@ Presentation-layer note:

- when enabled in Reader settings, clicking any card (including its title) loads a reader view in a right-hand panel instead of opening a new tab
- while the preview request is in flight, the panel keeps the card title and shows a preview skeleton after a short delay; the loaded title and content fade in, and a failed request replaces the skeleton with a readable error message
- transient upstream `429`/`5xx` responses are retried once with jitter; blocked sources, timeouts, unsupported formats, and failed fetches get specific messages
- the visible loading message is visually hidden while the skeleton is shown; the panel remains `aria-busy` and a live region announces the loading state
- `Cmd`/`Ctrl`/`Shift`-clicking a title still opens the article in a new tab
- the panel shows the extracted title, byline, publication date/reading time, rich text with validated inline links/emphasis/inline code, image blocks with captions and intrinsic dimensions, and semantic tables; images load directly from the source with lazy loading and no referrer; `Open source` opens the original page
Expand All @@ -381,6 +382,7 @@ Presentation-layer note:
- the article currently being previewed is highlighted in the feed; the preview header shows the card’s stats/date metadata without repeating the title
- previous/next buttons at the bottom of the panel move through the currently rendered feed or Saved list; when the last rendered card is previewed, Next stays enabled if more pages exist and loads the next page before advancing
- previews are fetched by the Worker via `GET /api/preview?url=…`; only URLs already stored as feed items are accepted, and upstream HTML is never injected into the page
- successful previews are edge-cached for 30 minutes via the Cache API and browser-facing responses are `private, no-store`
- on screens wider than 900px the preview panel is an aside fixed on the right at about 65% of the width and 0.8rem top/bottom insets, with the bookmark, `…`, and Close controls in its header; the page keeps its normal scroll behavior
- at 900px or narrower the borderless panel covers the full viewport and the footer places the bookmark, `…`, and Close after Previous/Next (in both portrait and landscape). Above 900px the aside header holds the bookmark, `…`, and Close. The `…` button opens a settings-style dialog headed by the article title with its source icon/host and a close button, with the actions stacked as full-width rows over the standard backdrop (dismiss with the close button, backdrop, Escape, or by choosing an action). Content respects left/right safe-area insets in iPhone landscape; while the panel covers the viewport the `theme-color` tint matches the panel surface so the status-bar strip blends with it
- on phones, the glass preview header and footer slide away while scrolling down and return when scrolling up; the desktop aside keeps its chrome visible
Expand Down
175 changes: 144 additions & 31 deletions core/preview.ts
Original file line number Diff line number Diff line change
Expand Up @@ -118,20 +118,58 @@ export interface ArticlePreview {
blocks: PreviewBlock[];
}

export type PreviewFailureReason =
| "invalid_url"
| "fetch_failed"
| "timeout"
| "redirect"
| "blocked"
| "rate_limited"
| "upstream_error"
| "unsupported_content_type"
| "too_large"
| "empty_body";

export class PreviewUnavailableError extends Error {
constructor(message: string) {
readonly reason: PreviewFailureReason;
readonly upstreamStatus?: number;

constructor(
message: string,
reason: PreviewFailureReason = "fetch_failed",
upstreamStatus?: number,
) {
super(message);
this.name = "PreviewUnavailableError";
this.reason = reason;
if (upstreamStatus !== undefined) this.upstreamStatus = upstreamStatus;
}
}

function isTimeoutError(error: unknown): boolean {
const name = (error as { name?: unknown } | null)?.name;
return name === "TimeoutError" || name === "AbortError";
}

function isTransientStatus(status: number): boolean {
return status === 429 || (status >= 500 && status <= 599);
}

function sleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms));
}

type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;

export interface FetchArticlePreviewOptions {
userAgent: string;
fetchImpl?: FetchLike;
maxBytes?: number;
timeoutMs?: number;
/** Base delay before retrying a transient upstream response. */
retryDelayMs?: number;
/** Random jitter added to the retry delay. */
retryJitterMs?: number;
}

/**
Expand Down Expand Up @@ -165,34 +203,72 @@ export async function fetchArticlePreview(
): Promise<ArticlePreview> {
const target = normalizePreviewUrl(rawUrl);
if (!target) {
throw new PreviewUnavailableError("article URL is not previewable");
throw new PreviewUnavailableError(
"article URL is not previewable",
"invalid_url",
);
}

const fetchImpl = options.fetchImpl ?? fetch;
let response: Response;
let resolvedUrl: string;
try {
const result = await fetchWithSafeRedirects(fetchImpl, target, {
headers: {
Accept: "text/html, application/xhtml+xml",
"User-Agent": options.userAgent,
},
signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
});
response = result.response;
resolvedUrl = result.url;
} catch (error) {
if (error instanceof PreviewUnavailableError) throw error;
throw new PreviewUnavailableError("could not fetch article");
const timeoutSignal = AbortSignal.timeout(
options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
);
let lastResult: { response: Response; url: string } | null = null;
for (let attempt = 0; attempt < 2; attempt += 1) {
try {
lastResult = await fetchWithSafeRedirects(fetchImpl, target, {
headers: {
Accept: "text/html, application/xhtml+xml",
"User-Agent": options.userAgent,
},
signal: timeoutSignal,
});
} catch (error) {
if (error instanceof PreviewUnavailableError) throw error;
throw new PreviewUnavailableError(
"could not fetch article",
isTimeoutError(error) ? "timeout" : "fetch_failed",
);
}
if (
lastResult.response.ok ||
!isTransientStatus(lastResult.response.status) ||
attempt === 1
) {
break;
}
await lastResult.response.body?.cancel().catch(() => {});
const jitter =
options.retryJitterMs === 0 ? 0 : Math.random() * (options.retryJitterMs ?? 200);
await sleep((options.retryDelayMs ?? 250) + jitter);
}
if (!lastResult) {
throw new PreviewUnavailableError("could not fetch article", "fetch_failed");
}

const response = lastResult.response;
const resolvedUrl = lastResult.url;

if (!response.ok) {
throw new PreviewUnavailableError(`article returned ${response.status}`);
const reason: PreviewFailureReason =
response.status === 401 || response.status === 403
? "blocked"
: response.status === 429
? "rate_limited"
: "upstream_error";
throw new PreviewUnavailableError(
`article returned ${response.status}`,
reason,
response.status,
);
}

const finalUrl = response.url || resolvedUrl;
if (!normalizePreviewUrl(finalUrl)) {
throw new PreviewUnavailableError("article redirected to an unusable URL");
throw new PreviewUnavailableError(
"article redirected to an unusable URL",
"redirect",
);
}

const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
Expand All @@ -201,18 +277,28 @@ export async function fetchArticlePreview(
!contentType.includes("text/html") &&
!contentType.includes("application/xhtml+xml")
) {
throw new PreviewUnavailableError("article is not HTML");
throw new PreviewUnavailableError(
"article is not HTML",
"unsupported_content_type",
);
}

const html = await readBodyLimited(
const { text: html, truncated } = await readBodyLimited(
response,
options.maxBytes ?? DEFAULT_MAX_BYTES,
);
if (html.trim() === "") {
throw new PreviewUnavailableError("article body is empty");
throw new PreviewUnavailableError("article body is empty", "empty_body");
}

return extractArticlePreview(html, finalUrl);
const preview = extractArticlePreview(html, finalUrl);
if (truncated && preview.blocks.length === 0) {
throw new PreviewUnavailableError(
"article body exceeded the preview limit before readable content",
"too_large",
);
}
return preview;
}

export function extractArticlePreview(
Expand Down Expand Up @@ -907,7 +993,10 @@ function pickContentRoot(document: HtmlDocument): HtmlElement | null {
const candidates: HtmlElement[] = [...articles];
const main = document.querySelector("main, [role=main]");
if (main) candidates.push(main);
if (document.body) candidates.push(document.body);
// Truncated documents may not expose a <body> element; fall back to <html>
// so a body cap doesn't turn an extractable prefix into "no content".
const body = document.body ?? document.querySelector("html");
if (body) candidates.push(body);
if (candidates.length === 0) return null;

let best = candidates[0]!;
Expand Down Expand Up @@ -1133,22 +1222,34 @@ async function fetchWithSafeRedirects(
}
if (redirects >= MAX_REDIRECTS) {
await response.body?.cancel().catch(() => {});
throw new PreviewUnavailableError("article redirected too many times");
throw new PreviewUnavailableError(
"article redirected too many times",
"redirect",
);
}

const location = response.headers.get("location");
if (!location) {
throw new PreviewUnavailableError("article redirect is missing a location");
throw new PreviewUnavailableError(
"article redirect is missing a location",
"redirect",
);
}
let nextUrl: string;
try {
nextUrl = new URL(location, currentUrl).toString();
} catch {
throw new PreviewUnavailableError("article redirected to an invalid URL");
throw new PreviewUnavailableError(
"article redirected to an invalid URL",
"redirect",
);
}
const normalized = normalizePreviewUrl(nextUrl);
if (!normalized) {
throw new PreviewUnavailableError("article redirected to an unusable URL");
throw new PreviewUnavailableError(
"article redirected to an unusable URL",
"redirect",
);
}

await response.body?.cancel().catch(() => {});
Expand All @@ -1159,15 +1260,20 @@ async function fetchWithSafeRedirects(
async function readBodyLimited(
response: Response,
maxBytes: number,
): Promise<string> {
): Promise<{ text: string; truncated: boolean }> {
if (!response.body) {
return (await response.text()).slice(0, maxBytes);
const text = await response.text();
return {
text: text.slice(0, maxBytes),
truncated: text.length > maxBytes,
};
}

const reader = response.body.getReader();
const decoder = new TextDecoder();
let bytesRead = 0;
let out = "";
let truncated = false;
try {
while (bytesRead < maxBytes) {
const { done, value } = await reader.read();
Expand All @@ -1176,12 +1282,19 @@ async function readBodyLimited(
const remaining = maxBytes - bytesRead;
const chunk =
value.byteLength > remaining ? value.subarray(0, remaining) : value;
if (value.byteLength > remaining) {
truncated = true;
}
bytesRead += chunk.byteLength;
out += decoder.decode(chunk, { stream: true });
}
if (!truncated && bytesRead >= maxBytes) {
const extra = await reader.read();
truncated = !extra.done;
}
out += decoder.decode();
} finally {
await reader.cancel().catch(() => {});
}
return out;
return { text: out, truncated };
}
2 changes: 1 addition & 1 deletion core/render.ts
Original file line number Diff line number Diff line change
Expand Up @@ -195,7 +195,7 @@ export function renderIndexPage(data: PageData): string {
<link rel="apple-touch-icon" href="/apple-touch-icon.png?v=8" />
<script>${data.themeInitScript}</script>
<style>${data.inlineCss}</style>
<script src="/static/app.js?v=108" defer></script>
<script src="/static/app.js?v=109" defer></script>
</head>
<body data-app-version="${escapeHtml(data.appVersion)}">
<div class="boot-veil" data-boot-veil aria-hidden="true">
Expand Down
76 changes: 75 additions & 1 deletion core/test/preview.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -789,18 +789,92 @@ describe("fetchArticlePreview", () => {

it("caps how much of the response body it reads", async () => {
const marker = "UNIQUE_TRAILING_MARKER";
const html = `<html><body><p>${"a".repeat(400)}</p><p>${marker}</p></body></html>`;
const html = `<html><body><p>Readable opening paragraph that should survive the cap.</p>${" ".repeat(400)}<p>${marker}</p></body></html>`;

const preview = await fetchArticlePreview("https://example.com/long", {
userAgent: "feedreader-test",
maxBytes: 260,
fetchImpl: async () => htmlResponse(html),
});

expect(preview.blocks.length).toBeGreaterThan(0);
expect(
preview.blocks
.map((block) => (block.type === "image" ? block.src : blockText(block)))
.join(" "),
).not.toContain(marker);
});

it("labels blocked upstream responses with a reason", async () => {
await expect(
fetchArticlePreview("https://example.com/blocked", {
userAgent: "feedreader-test",
fetchImpl: async () => new Response("blocked", { status: 403 }),
}),
).rejects.toMatchObject({
reason: "blocked",
upstreamStatus: 403,
});
});

it("retries a transient upstream 503 once", async () => {
let calls = 0;
const preview = await fetchArticlePreview("https://example.com/busy", {
userAgent: "feedreader-test",
retryDelayMs: 0,
retryJitterMs: 0,
fetchImpl: async () => {
calls += 1;
return calls === 1
? new Response("busy", { status: 503 })
: htmlResponse(ARTICLE_HTML);
},
});

expect(calls).toBe(2);
expect(preview.blocks.length).toBeGreaterThan(0);
});

it("reports a persistent upstream 5xx after one retry", async () => {
let calls = 0;
await expect(
fetchArticlePreview("https://example.com/down", {
userAgent: "feedreader-test",
retryDelayMs: 0,
retryJitterMs: 0,
fetchImpl: async () => {
calls += 1;
return new Response("down", { status: 503 });
},
}),
).rejects.toMatchObject({
reason: "upstream_error",
upstreamStatus: 503,
});
expect(calls).toBe(2);
});

it("labels timeouts", async () => {
const timeout = new Error("timed out");
timeout.name = "TimeoutError";
await expect(
fetchArticlePreview("https://example.com/slow", {
userAgent: "feedreader-test",
fetchImpl: async () => {
throw timeout;
},
}),
).rejects.toMatchObject({ reason: "timeout" });
});

it("labels truncated bodies with no readable content", async () => {
const html = `<html><body><div>${"a".repeat(400)}</div></body></html>`;
await expect(
fetchArticlePreview("https://example.com/huge", {
userAgent: "feedreader-test",
maxBytes: 120,
fetchImpl: async () => htmlResponse(html),
}),
).rejects.toMatchObject({ reason: "too_large" });
});
});
Loading
Loading