lunanting/ai-chatbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request '修复图片下载排队、中转速度和错误反馈' (#28) from codex/image-download-reliability-20261104 into main

Browse Source
This commit is contained in:
WuYongJie 2026-11-04 17:36:17 +08:00
commit 198deca47b
14 changed files with 395 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
app/api/canvas/download-image/route.ts
View File

@ -1,6 +1,9 @@
import { resolveCanvasCdnDownload } from "@/lib/storage/canvas-cdn-download";
import { isRetiredStorageUrl, RETIRED_STORAGE_MESSAGE } from "@/lib/storage/retired-storage";
import { prepareImageArchiveDownload } from "@/lib/storage/image-download-preparation";
import { scheduleImageDownloadPreparation } from "@/lib/storage/image-download-preparation";
import { randomUUID } from "node:crypto";
import { formatDownloadFailure, getDownloadFailure, type DownloadFailure } from "@/lib/canvas/download-error";
import { createLogger } from "@/lib/observability/logger";
import { after, NextRequest, NextResponse } from "next/server";
import { auth } from "@/app/(auth)/auth";
import { getDownloadPreparationQueue, type DownloadPreparationInput } from "@/lib/canvas/download-preparation";
@ -13,6 +16,22 @@ import {
export const runtime = "nodejs";
export const maxDuration = 120;
const logger = createLogger("canvas.download");
function failed(failure: DownloadFailure, requestId: string) {
logger.warn("request_failed", { requestId, code: failure.code, status: failure.status });
return NextResponse.json({ success: false, error: formatDownloadFailure(failure, requestId), failure, requestId }, {
status: failure.status,
headers: { "Cache-Control": "no-store", ...(failure.status === 429 ? { "Retry-After": "3" } : {}) },
});
}
function preparing(requestId: string) {
return NextResponse.json({ delivery: "preparing", retryAfter: 2, requestId,
message: "正在准备原图，完成后将自动开始下载" }, {
status: 202, headers: { "Retry-After": "2", "Cache-Control": "no-store" },
});
}
async function prepareDownload(input: DownloadPreparationInput, signal: AbortSignal) {
// A proxy candidate for the same original must not repeat the same slow
@ -21,22 +40,25 @@ async function prepareDownload(input: DownloadPreparationInput, signal: AbortSig
const source = extractImageProxySourceUrl(url) || url;
return inferOriginalImageUrl(source) || source;
}))];
for (let attempt = 0; attempt < 3; attempt++) {
let lastError: unknown;
for (let attempt = 0; attempt < 2; attempt++) {
signal.throwIfAborted();
for (const url of sources) {
signal.throwIfAborted();
const result = await fetchCanvasDownloadAsset({
file: { url, name: "original" }, index: 0,
requestOrigin: input.requestOrigin, cookie: input.cookie,
includeSequencePrefix: false, timeoutMs: 12_000, retryCount: 1, signal,
includeSequencePrefix: false, timeoutMs: 60_000, retryCount: 1, signal,
});
if (result.ok) return { buffer: result.bytes, contentType: result.contentType };
lastError = result.error;
}
// Each pass resolves the latest archive URL inside fetchCanvasDownloadAsset.
// No AI/model request is involved and a completed source fetch is shared.
if (attempt < 2) await new Promise(resolve => setTimeout(resolve, 1_000));
if (attempt < 1 && getDownloadFailure(lastError).retryable) await new Promise(resolve => setTimeout(resolve, 1_000));
else break;
}
throw new Error("Original image sources unavailable");
throw new Error(String(lastError || "Original image sources unavailable"));
}
function getRequestOrigin(request: NextRequest): string {
@ -76,31 +98,43 @@ function resolveDownloadUrls(body: Record<string, unknown>, origin: string): str
}
export async function POST(request: NextRequest) {
const requestId = randomUUID();
try {
const session = await auth();
if (!session?.user?.id) {
return NextResponse.json({ success: false, error: "未登录" }, { status: 401 });
return failed(getDownloadFailure("未登录"), requestId);
}
const body = (await request.json().catch(() => ({}))) as Record<string, unknown>;
const requestOrigin = getRequestOrigin(request);
const candidates = resolveDownloadUrls(body, requestOrigin);
if (candidates.length && candidates.every(isRetiredStorageUrl)) {
return NextResponse.json({ success: false, error: RETIRED_STORAGE_MESSAGE, code: "storage_retired" }, { status: 410 });
return failed(getDownloadFailure(RETIRED_STORAGE_MESSAGE), requestId);
}
const urls = candidates.filter(url => !isRetiredStorageUrl(url));
const requestedUrls = [...urls];
if (urls.length === 0) {
return NextResponse.json({ success: false, error: "图片地址无效" }, { status: 400 });
return failed(getDownloadFailure("图片地址无效"), requestId);
}
const name = sanitizeCanvasDownloadFileName(String(body.name || ""), "canvas-image");
if (body.preferDirect === true) {
const { task, direct } = await resolveCanvasCdnDownload(urls, `${name}.png`).catch(() => ({ task: null, direct: null }));
const { task, direct, canPrepareDirect } = await resolveCanvasCdnDownload(urls, `${name}.png`).catch((error) => {
logger.warn("cdn_lookup_failed", error, { requestId });
return { task: null, direct: null, canPrepareDirect: false };
});
if (direct) return NextResponse.json(direct, { headers: { "Cache-Control": "no-store" } });
if (task && canPrepareDirect && body.preparation === "async") {
const asset = (task.metadata as { downloadAsset?: { status?: string; failure?: DownloadFailure; retryAt?: string } } | null)?.downloadAsset;
if (asset?.status === "abandoned" || (asset?.status === "failed" && Date.parse(asset.retryAt || "") > Date.now())) {
return failed(asset.failure || getDownloadFailure(null), task.id);
}
scheduleImageDownloadPreparation(task.id);
return preparing(task.id);
}
if (task?.targetUrl) {
if (!urls.includes(task.targetUrl)) urls.unshift(task.targetUrl);
after(() => prepareImageArchiveDownload(task.id));
scheduleImageDownloadPreparation(task.id);
}
}
const cookie = request.headers.get("cookie") || "";
@ -109,13 +143,10 @@ export async function POST(request: NextRequest) {
userId: session.user.id, urls: requestedUrls, requestOrigin, cookie,
});
if (result.status === "preparing") {
return NextResponse.json({ delivery: "preparing", retryAfter: 3,
message: "正在准备原图，完成后将自动下载" }, {
status: 202, headers: { "Retry-After": "3", "Cache-Control": "no-store" },
});
return preparing(result.requestId);
}
if (result.status === "failed") {
return NextResponse.json({ success: false, error: result.error }, { status: 502 });
return failed(result.failure, result.requestId);
}
return new NextResponse(new Uint8Array(result.asset.buffer), { headers: {
"Content-Type": result.asset.contentType,
@ -136,17 +167,14 @@ export async function POST(request: NextRequest) {
includeSequencePrefix: false,
});
if (result.ok) break;
failures.push(`${url}: ${result.error}`);
failures.push(result.error);
}
if (!result?.ok) {
if (failures.length > 0) {
console.warn("[CanvasDownloadImage] All candidates failed:", failures);
logger.warn("all_sources_failed", { requestId, failures });
}
return NextResponse.json(
{ success: false, error: result?.error || "图片源文件暂时不可访问" },
{ status: 502 }
);
return failed(getDownloadFailure(result?.error), requestId);
}
return new NextResponse(result.bytes, {
@ -159,7 +187,7 @@ export async function POST(request: NextRequest) {
},
});
} catch (error) {
console.error("[CanvasDownloadImage] Failed:", error);
return NextResponse.json({ success: false, error: "图片下载失败" }, { status: 500 });
logger.error("download_failed", error, { requestId });
return failed(getDownloadFailure(error), requestId);
}
}

30
lib/canvas/download-error.ts Normal file
View File

@ -0,0 +1,30 @@
export type DownloadFailure = {
code: string;
message: string;
recommendation: string;
status: number;
retryable: boolean;
};
export function getDownloadFailure(error: unknown): DownloadFailure {
const text = error && typeof error === "object" && "message" in error
? `${"name" in error ? error.name : "Error"}: ${error.message}` : String(error || "");
const failure = (code: string, message: string, recommendation: string, status: number, retryable = false) =>
({ code, message, recommendation, status, retryable });
if (/旧存储已停用|storage_retired/.test(text)) return failure("STORAGE_RETIRED", "原图所在的旧存储已停用。", "请重新上传原图；重试下载无法恢复该文件。", 410);
if (/HTTP (?:404|410)|SOURCE_NOT_FOUND/i.test(text)) return failure("SOURCE_NOT_FOUND", "原图链接已失效或源文件已被删除。", "请重新上传原图，或联系管理员核对归档副本；无需重新生成图片。", 404);
if (/HTTP (?:401|403)|SOURCE_FORBIDDEN/i.test(text)) return failure("SOURCE_FORBIDDEN", "图片源站拒绝访问原图。", "请联系管理员检查原图访问权限或链接有效期，并提供下载编号。", 403);
if (/queue.*busy|正在准备的原图较多|DOWNLOAD_BUSY/i.test(text)) return failure("DOWNLOAD_BUSY", "正在准备的下载较多。", "请等待当前下载完成后再试，避免同时重复点击。", 429, true);
if (/TimeoutError|AbortError|timeout|timed out|deadline|超时|HTTP (?:408|504|524)/i.test(text)) return failure("SOURCE_TIMEOUT", "读取原图或准备下载文件超时。", "请稍后再次下载；持续失败时联系管理员并提供下载编号，已归档的原图无需重新生成。", 504, true);
if (/fetch failed|failed to fetch|ECONN|ENOTFOUND|EAI_AGAIN|network|HTTP (?:429|5\d\d)/i.test(text)) return failure("SOURCE_UNAVAILABLE", "暂时无法连接图片源站。", "请稍后重试下载；持续失败时联系管理员检查取图线路，并提供下载编号。", 503, true);
if (/not.*image|error document|不是图片|无法识别图片|empty response|image is empty|Invalid prepared original/i.test(text)) return failure("INVALID_IMAGE", "源地址没有返回可用的图片文件。", "请重新上传可打开的原图；若原图正常，请联系管理员并提供下载编号。", 422);
if (/sharp|pngload|jpegload|unsupported image|无法解析图片|convert|转换/i.test(text)) return failure("IMAGE_CONVERSION_FAILED", "原图无法转换为下载所需的 PNG 文件。", "请保留原图并联系管理员提供下载编号，或重新上传 PNG/JPEG 图片。", 422);
if (/upload|存储桶|保存下载|STORAGE_WRITE_FAILED/i.test(text)) return failure("DOWNLOAD_STORAGE_FAILED", "下载文件保存失败，已归档的原图仍然保留。", "请稍后重试；持续失败时联系管理员检查存储，并提供下载编号。", 503, true);
if (/未登录/.test(text)) return failure("LOGIN_REQUIRED", "登录状态已失效。", "请重新登录后下载，当前图片不会因此删除。", 401);
if (/图片地址无效/.test(text)) return failure("INVALID_IMAGE_URL", "图片地址无效。", "请刷新画布后重新选择图片；仍然失败时请重新上传原图。", 400);
return failure("DOWNLOAD_FAILED", "下载准备未能完成。", "请联系管理员并提供下载编号，以便核对原图、转换和存储的具体错误；无需重新生成。", 500, true);
}
export function formatDownloadFailure(failure: DownloadFailure, requestId?: string) {
return `${failure.message}${failure.recommendation}${requestId ? `\n下载编号：${requestId}` : ""}`;
}

35
lib/canvas/download-preparation.ts
View File

@ -1,6 +1,10 @@
import "server-only";
import { createHash } from "node:crypto";
import { createHash, randomUUID } from "node:crypto";
import { cacheImageBytes, readImageBytes, type ImageBytes } from "@/lib/storage/image-byte-cache";
import { formatDownloadFailure, getDownloadFailure, type DownloadFailure } from "./download-error";
import { createLogger } from "@/lib/observability/logger";
const logger = createLogger("canvas.download");
export type DownloadPreparationInput = {
userId: string;
@ -9,17 +13,18 @@ export type DownloadPreparationInput = {
cookie: string;
};
type Result =
| { status: "preparing" }
| { status: "preparing"; requestId: string }
| { status: "ready"; asset: ImageBytes }
| { status: "failed"; error: string };
| { status: "failed"; error: string; failure: DownloadFailure; requestId: string };
type Job = {
requestId: string;
userId: string;
input: DownloadPreparationInput;
status: "queued" | "running" | "ready" | "failed";
updatedAt: number;
asset?: ImageBytes;
failure?: DownloadFailure;
};
const FAILURE_MESSAGE = "原图暂时无法读取，图片仍保留在画布中，请稍后重试";
const MAX_MEMORY_BYTES = 128 * 1024 * 1024;
// A download is independent of node autosave and of the archive worker's batch.
@ -69,7 +74,7 @@ export function createDownloadPreparationQueue(deps: {
timer = setTimeout(() => {
controller.abort();
reject(new Error("Download preparation deadline"));
}, deps.timeoutMs || 90_000);
}, deps.timeoutMs || 150_000);
}),
]);
if (asset.contentType !== "image/png" || !asset.buffer.length || asset.buffer.length > MAX_MEMORY_BYTES) {
@ -81,8 +86,10 @@ export function createDownloadPreparationQueue(deps: {
const stored = await deps.read(key).catch(() => null);
if (stored?.contentType === "image/png" && stored.buffer.length) job.asset = undefined;
job.status = "ready";
} catch {
} catch (error) {
job.status = "failed";
job.failure = getDownloadFailure(error);
logger.warn("preparation_failed", error, { requestId: job.requestId, code: job.failure.code });
} finally {
if (timer) clearTimeout(timer);
// Do not retain authentication data after a preparation finishes.
@ -105,8 +112,11 @@ export function createDownloadPreparationQueue(deps: {
prune();
const current = jobs.get(key);
if (current?.status === "ready" && current.asset) return { status: "ready", asset: current.asset };
if (current?.status === "failed") return { status: "failed", error: FAILURE_MESSAGE };
if (current && current.status !== "ready") return { status: "preparing" };
if (current?.status === "failed") {
const failure = current.failure || getDownloadFailure(null);
return { status: "failed", error: formatDownloadFailure(failure, current.requestId), failure, requestId: current.requestId };
}
if (current && current.status !== "ready") return { status: "preparing", requestId: current.requestId };
if (jobs.size >= 64) {
for (const [oldKey, job] of jobs) {
if (job.status === "ready" || job.status === "failed") jobs.delete(oldKey);
@ -115,11 +125,14 @@ export function createDownloadPreparationQueue(deps: {
}
if (jobs.size >= 64 || [...jobs.values()].filter(job => job.userId === input.userId &&
(job.status === "queued" || job.status === "running")).length >= 4) {
return { status: "failed", error: "正在准备的原图较多，请等待当前下载完成后再试" };
const requestId = randomUUID();
const failure = getDownloadFailure("DOWNLOAD_BUSY");
return { status: "failed", error: formatDownloadFailure(failure, requestId), failure, requestId };
}
jobs.set(key, { userId: input.userId, input, status: "queued", updatedAt: now() });
const requestId = randomUUID();
jobs.set(key, { requestId, userId: input.userId, input, status: "queued", updatedAt: now() });
deps.schedule(drain);
return { status: "preparing" };
return { status: "preparing", requestId };
},
};
}

7
lib/canvas/photoshop-safe-download.ts
View File

@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
import { isRetiredStorageUrl, RETIRED_STORAGE_MESSAGE } from "@/lib/storage/retired-storage";
import { fetchImageBytes, onceImageBytes } from "@/lib/storage/image-byte-cache";
import { extractImageProxySourceUrl, inferOriginalImageUrl } from "@/lib/image-url";
import { getDownloadFailure } from "./download-error";
type DownloadFileItem = {
url: string;
@ -31,6 +32,7 @@ function sleep(ms: number) {
function normalizeDownloadError(error: unknown): string {
if (error instanceof Error) return error.message || "download failed";
if (error && typeof error === "object" && "message" in error && typeof error.message === "string") return error.message;
if (typeof error === "string") return error;
return "download failed";
}
@ -330,6 +332,7 @@ export async function fetchCanvasDownloadAsset(params: {
try {
const data = await fetchImageBytes(candidateUrl, {
timeoutMs,
signal: params.signal,
headers: buildRemoteFetchHeaders(candidateUrl, params.requestOrigin, params.cookie),
// Authenticated local assets must never share a cache across users.
scope: new URL(candidateUrl).origin === params.requestOrigin && params.cookie
@ -344,11 +347,13 @@ export async function fetchCanvasDownloadAsset(params: {
});
} catch (error) {
params.signal?.throwIfAborted();
lastError = normalizeDownloadError(error);
const message = normalizeDownloadError(error);
if (!lastError || getDownloadFailure(message).retryable || !getDownloadFailure(lastError).retryable) lastError = message;
}
}
// Archiving may have completed during the failed fetch. Resolve aliases
// again before retrying, rather than spending every attempt on the old URL.
if (!getDownloadFailure(lastError).retryable) break;
if (attempt < retryCount) await sleep(350 * attempt);
}

30
lib/client/canvas-image-download.ts
View File

@ -1,5 +1,6 @@
import { buildImageProxyUrl } from "@/lib/image-delivery";
import { inferOriginalImageUrl } from "@/lib/image-url";
import { formatDownloadFailure, getDownloadFailure, type DownloadFailure } from "@/lib/canvas/download-error";
export type CanvasImageDownloadPhase = "preparing" | "downloading" | "saving";
@ -26,6 +27,8 @@ export class CanvasImageDownloadError extends Error {
code: CanvasImageDownloadErrorCode;
retryAfterSeconds?: number;
status?: number;
failure?: DownloadFailure;
requestId?: string;
constructor(
message: string,
@ -33,6 +36,8 @@ export class CanvasImageDownloadError extends Error {
code: CanvasImageDownloadErrorCode;
retryAfterSeconds?: number;
status?: number;
failure?: DownloadFailure;
requestId?: string;
}
) {
super(message);
@ -40,11 +45,14 @@ export class CanvasImageDownloadError extends Error {
this.code = options.code;
this.retryAfterSeconds = options.retryAfterSeconds;
this.status = options.status;
this.failure = options.failure;
this.requestId = options.requestId;
}
}
export function getCanvasImageDownloadErrorMessage(error: unknown) {
if (error instanceof CanvasImageDownloadError) {
if (error.failure) return formatDownloadFailure(error.failure, error.requestId);
if (error.code === "rate_limited") {
return error.retryAfterSeconds
? `图片下载请求过于频繁，请 ${error.retryAfterSeconds} 秒后重试`
@ -54,10 +62,10 @@ export function getCanvasImageDownloadErrorMessage(error: unknown) {
return "原图暂时无法读取，图片仍保留在画布中，请稍后重试";
}
if (error.code === "preparation_timeout") {
return "原图仍在后台准备中，请稍后再次点击下载";
return `原图仍在后台准备中，请稍后再次点击下载${error.requestId ? `\n下载编号：${error.requestId}` : ""}`;
}
}
return error instanceof Error ? error.message : "图片下载失败，请稍后重试";
return formatDownloadFailure(getDownloadFailure(error));
}
type DownloadCanvasImageParams = {
@ -71,6 +79,8 @@ type DownloadCanvasImageParams = {
type DownloadErrorPayload = {
error?: string;
retryAfter?: number;
failure?: DownloadFailure;
requestId?: string;
};
const MAX_RATE_LIMIT_RETRIES = 1;
@ -257,7 +267,8 @@ export async function downloadCanvasImageAsPng({
let preparationPolls = 0;
for (;;) {
signal?.throwIfAborted();
response = await fetch("/api/canvas/download-image", {
try {
response = await fetch("/api/canvas/download-image", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
@ -268,7 +279,12 @@ export async function downloadCanvasImageAsPng({
preparation: "async",
}),
signal,
});
});
} catch (error) {
if (signal?.aborted) throw error;
const failure = getDownloadFailure(error);
throw new CanvasImageDownloadError(failure.message, { code: "request_failed", failure });
}
if (response.status === 202) {
rateLimitRetries = 0;
@ -278,7 +294,7 @@ export async function downloadCanvasImageAsPng({
throw new CanvasImageDownloadError("下载准备状态无效", { code: "request_failed", status: 202 });
}
if (Date.now() >= preparationDeadline || preparationPolls >= 60) {
throw new CanvasImageDownloadError("原图仍在准备中", { code: "preparation_timeout", status: 202 });
throw new CanvasImageDownloadError("原图仍在准备中", { code: "preparation_timeout", status: 202, requestId: preparing.requestId });
}
onProgress?.({ phase: "preparing", message: preparing.message || "正在准备原图，完成后将自动下载" });
const delaySeconds = Math.max(preparationPolls > 5 ? 5 : 1, Math.min(5, Number(preparing.retryAfter) || 3));
@ -299,6 +315,8 @@ export async function downloadCanvasImageAsPng({
code: "rate_limited",
retryAfterSeconds,
status: response.status,
failure: errorPayload?.failure,
requestId: errorPayload?.requestId,
}
);
}
@ -321,6 +339,8 @@ export async function downloadCanvasImageAsPng({
{
code: status === 502 ? "source_unavailable" : "request_failed",
status,
failure: errorPayload?.failure,
requestId: errorPayload?.requestId,
}
);
}

9
lib/jobs/image-archive-job.ts
View File

@ -1,4 +1,4 @@
import { preparePendingImageDownloads } from "@/lib/storage/image-download-preparation";
import { scheduleImageDownloadPreparation } from "@/lib/storage/image-download-preparation";
import "server-only";
import { trackRuntimeWork } from "@/lib/observability/active-work";
@ -32,6 +32,7 @@ export async function runImageArchiveJob() {
console.log(`[ImageArchiveJob] Start image archive job (batchSize=${batchSize})`);
await recoverStaleImageArchiveTasks();
scheduleImageDownloadPreparation();
const storeTasks = await getImageArchiveTasksToStore({ limit: batchSize });
let storeSucceeded = 0;
let storeFailed = 0;
@ -45,6 +46,7 @@ export async function runImageArchiveJob() {
id: task.id,
targetUrl: archived.url,
});
scheduleImageDownloadPreparation(task.id);
storeSucceeded += 1;
console.log("[ImageArchiveJob] stored", {
taskId: task.id,
@ -108,7 +110,6 @@ export async function runImageArchiveJob() {
}
}
const downloadTasks = await preparePendingImageDownloads();
const stats = await getImageArchiveTaskStats();
return {
success: true,
@ -124,8 +125,8 @@ export async function runImageArchiveJob() {
failed: replaceFailed,
},
stats,
downloadTasks,
downloadTasks: 0,
pendingDownloads: await hasPendingImageDownloads(),
};
});
}, { durable: true });
}

13
lib/observability/active-work.ts
View File

@ -3,13 +3,14 @@ import { unlinkSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
const state = globalThis as typeof globalThis & { __aiChatbotActiveWork?: number };
const state = globalThis as typeof globalThis & { __aiChatbotActiveWork?: number; __aiChatbotDurableWork?: number };
const path = join(process.platform === "win32" ? tmpdir() : "/tmp", `ai-chatbot-active-work-${process.pid}.json`);
function update(delta: number) {
function update(delta: number, durable: boolean) {
state.__aiChatbotActiveWork = (state.__aiChatbotActiveWork || 0) + delta;
if (durable) state.__aiChatbotDurableWork = (state.__aiChatbotDurableWork || 0) + delta;
try {
writeFileSync(path, JSON.stringify({ pid: process.pid, active: state.__aiChatbotActiveWork }), { mode: 0o600 });
writeFileSync(path, JSON.stringify({ pid: process.pid, active: state.__aiChatbotActiveWork, durable: state.__aiChatbotDurableWork || 0 }), { mode: 0o600 });
} catch (error) {
try { unlinkSync(path); } catch {}
console.warn("[Active Work] Failed to record running work:", error);
@ -17,7 +18,7 @@ function update(delta: number) {
}
/** Includes generation that continues after the client connection closes. */
export async function trackRuntimeWork<T>(execute: () => T | Promise<T>): Promise<T> {
update(1);
try { return await execute(); } finally { update(-1); }
export async function trackRuntimeWork<T>(execute: () => T | Promise<T>, options: { durable?: boolean } = {}): Promise<T> {
update(1, options.durable === true);
try { return await execute(); } finally { update(-1, options.durable === true); }
}

14
lib/storage/canvas-cdn-download.ts
View File

@ -10,17 +10,21 @@ export async function resolveCanvasCdnDownload(urls: string[], filename: string)
})));
const task = await findImageArchiveDownloadTask(sources, true);
const asset = (task?.metadata as { downloadAsset?: { status?: string; url?: string; contentType?: string; bytes?: number } } | null)?.downloadAsset;
if (asset?.status !== "ready" || !asset.url || asset.contentType !== "image/png") return { task, direct: null };
if (!task) return { task, direct: null, canPrepareDirect: false };
const config = await getDefaultStorageConfig();
if (config?.type !== "qiniu-kodo" || !config.publicUrl || !config.isEnabled) return { task, direct: null };
const url = new URL(asset.url);
if (config?.type !== "qiniu-kodo" || !config.publicUrl || !config.isEnabled) return { task, direct: null, canPrepareDirect: false };
const ready = asset?.status === "ready" && asset.url && asset.contentType === "image/png";
const source = ready ? asset.url : task.targetUrl;
if (!source) return { task, direct: null, canPrepareDirect: false };
const url = new URL(source);
const base = new URL(config.publicUrl);
const origin = process.env.CANVAS_QINIU_ORIGIN_URL;
if (origin && url.origin === new URL(origin).origin) url.host = base.host;
if (base.protocol !== "https:" || url.origin !== base.origin
|| !(url.pathname.startsWith(base.pathname.replace(/\/$/, "") + "/"))) return { task, direct: null };
|| !(url.pathname.startsWith(base.pathname.replace(/\/$/, "") + "/"))) return { task, direct: null, canPrepareDirect: false };
if (!ready) return { task, direct: null, canPrepareDirect: true };
// attname is interpreted by Kodo/CDN as Content-Disposition, including Chinese
// filenames. Keep all processing/auth parameters intact for correct cache keys.
url.searchParams.set("attname", filename);
return { task, direct: { delivery: "cdn", downloadUrl: url.toString(), filename, bytes: asset.bytes || 0 } };
return { task, direct: { delivery: "cdn", downloadUrl: url.toString(), filename, bytes: asset?.bytes || 0 }, canPrepareDirect: true };
}

6
lib/storage/image-byte-cache.ts
View File

@ -81,7 +81,7 @@ function isMediaResponse(data: ImageBytes) {
if (/^<\?xml/i.test(prefix) && !/<svg[\s>]/i.test(prefix)) return false;
return data.buffer.length > 0;
}
export async function fetchImageBytes(url: string, options: { headers?: HeadersInit; timeoutMs?: number; scope?: string } = {}) {
export async function fetchImageBytes(url: string, options: { headers?: HeadersInit; timeoutMs?: number; scope?: string; signal?: AbortSignal } = {}) {
if (isRetiredStorageUrl(url)) throw new Error(`HTTP 410: ${RETIRED_STORAGE_MESSAGE}`);
return onceImageBytes(`source:${options.scope || ""}:${url}`, async () => {
if (url.startsWith("data:")) {
@ -92,7 +92,9 @@ export async function fetchImageBytes(url: string, options: { headers?: HeadersI
const response = await fetch(url, {
headers: options.headers, cache: "no-store", redirect: "follow",
// The deadline covers the body as well as the response headers.
signal: AbortSignal.timeout(options.timeoutMs || 60_000),
signal: options.signal
? AbortSignal.any([options.signal, AbortSignal.timeout(options.timeoutMs || 60_000)])
: AbortSignal.timeout(options.timeoutMs || 60_000),
});
if (!response.ok) { await response.body?.cancel(); throw new Error(`HTTP ${response.status}`); }
const buffer = Buffer.from(await response.arrayBuffer());

62
lib/storage/image-download-preparation.ts
View File

@ -2,14 +2,21 @@ import "server-only";
import { randomUUID } from "node:crypto";
import { fetchImageBytes, cacheImageBytes } from "./image-byte-cache";
import { normalizeCanvasDownloadAsset } from "@/lib/canvas/photoshop-safe-download";
import { claimImageDownloadTask, saveImageDownloadAsset, getImageDownloadTasks } from "./image-archive-db";
import { claimImageDownloadTask, saveImageDownloadAsset, getImageDownloadTasks, hasPendingImageDownloads } from "./image-archive-db";
import { uploadFile } from "./service";
import { getDownloadFailure } from "@/lib/canvas/download-error";
import { createLogger } from "@/lib/observability/logger";
import { trackRuntimeWork } from "@/lib/observability/active-work";
const logger = createLogger("canvas.download");
export async function prepareImageArchiveDownload(id: string) {
const task = await claimImageDownloadTask(id);
if (!task?.targetUrl) return;
let phase: "read" | "convert" | "store" = "read";
try {
const source = await fetchImageBytes(task.targetUrl);
phase = "convert";
const asset = await normalizeCanvasDownloadAsset({
item: { url: task.targetUrl }, index: 0, bytes: source.buffer,
contentType: source.contentType, includeSequencePrefix: false,
@ -17,15 +24,22 @@ export async function prepareImageArchiveDownload(id: string) {
if (!asset.ok) throw new Error(asset.error);
// An already compatible PNG shares the original object; other formats get
// one prepared PNG, without changing the original dimensions or transparency.
phase = "store";
const url = source.buffer.equals(asset.bytes) && asset.contentType === "image/png"
? task.targetUrl
: (await uploadFile(`canvas-download-${randomUUID()}.${asset.filename.split(".").pop() || "png"}`, Uint8Array.from(asset.bytes).buffer)).url;
await saveImageDownloadAsset(id, { status: "ready", url, bytes: asset.bytes.length,
contentType: asset.contentType, preparedAt: new Date().toISOString() });
await cacheImageBytes(`source::${url}`, { buffer: asset.bytes, contentType: asset.contentType });
} catch {
} catch (error) {
const attempts = Number((task.metadata as { downloadAsset?: { attempts?: number } } | null)?.downloadAsset?.attempts || 1);
await saveImageDownloadAsset(id, { status: attempts >= 12 ? "abandoned" : "failed", attempts, retryAt: new Date(Date.now() + 10 * 60_000).toISOString() });
const failure = phase === "store"
? getDownloadFailure("STORAGE_WRITE_FAILED")
: phase === "convert" && getDownloadFailure(error).code === "DOWNLOAD_FAILED"
? getDownloadFailure("图片转换失败") : getDownloadFailure(error);
logger.warn("archive_download_preparation_failed", error, { requestId: id, code: failure.code });
await saveImageDownloadAsset(id, { status: !failure.retryable || attempts >= 12 ? "abandoned" : "failed", attempts,
failure, retryAt: new Date(Date.now() + 60_000).toISOString() });
}
}
export async function preparePendingImageDownloads() {
@ -36,3 +50,45 @@ export async function preparePendingImageDownloads() {
}));
return tasks.length;
}
const state = globalThis as typeof globalThis & {
__imageDownloadWorker?: { running: boolean; scanPending: boolean; priority: Set<string>; retry?: ReturnType<typeof setTimeout> };
};
/** Download preparation runs independently of the archive URL replacement batch. */
export function scheduleImageDownloadPreparation(id?: string) {
const worker = state.__imageDownloadWorker ??= { running: false, scanPending: false, priority: new Set() };
if (id) worker.priority.add(id);
else worker.scanPending = true;
if (worker.running) return;
if (worker.retry) { clearTimeout(worker.retry); worker.retry = undefined; }
worker.running = true;
setImmediate(() => {
void trackRuntimeWork(async () => {
try {
for (;;) {
const priority = [...worker.priority].slice(0, 2);
for (const taskId of priority) worker.priority.delete(taskId);
if (priority.length) {
await Promise.all(priority.map(prepareImageArchiveDownload));
} else if (!worker.scanPending || await preparePendingImageDownloads() === 0) {
break;
}
}
} catch (error) {
logger.error("download_worker_failed", error);
} finally {
worker.running = false;
// Eligible retry times live in the database, including interrupted leases.
if (worker.priority.size) {
scheduleImageDownloadPreparation([...worker.priority][0]);
} else if (worker.scanPending && await hasPendingImageDownloads().catch(() => true)) {
worker.retry = setTimeout(() => scheduleImageDownloadPreparation(), 60_000);
worker.retry.unref?.();
} else {
worker.scanPending = false;
}
}
}, { durable: true });
});
}

5
playwright.helpers.config.ts
View File

@ -3,6 +3,11 @@ import { defineConfig } from "@playwright/test";
export default defineConfig({
testDir: "./tests",
testMatch: [
/routes\/canvas-download-speed\.test\.ts/,
/routes\/canvas-download-recovery\.test\.ts/,
/routes\/canvas-download-rate-limit\.test\.ts/,
/routes\/canvas-zip-download\.test\.ts/,
/routes\/image-archive-flow\.test\.ts/,
/routes\/runtime-active-work\.test\.ts/,
/routes\/canvas-capability-task-recovery\.test\.ts/,
/routes\/canvas-toolbar-capability\.test\.ts/,

157
tests/routes/canvas-download-recovery.test.ts Normal file
View File

@ -0,0 +1,157 @@
import { expect, test } from "@playwright/test";
import { randomUUID } from "node:crypto";
import { serverLoader } from "../helpers/canvas-download-server-loader";
const auth = { auth: async () => ({ user: { id: "owner" } }) };
const request = () => ({
url: "https://app.example/api/canvas/download-image", headers: new Headers(),
json: async () => ({ url: "https://provider.example/original.jpg", preferDirect: true, preparation: "async" }),
});
test("download failures distinguish permanent sources, transport, conversion and storage with actionable advice", () => {
const { getDownloadFailure, formatDownloadFailure } = serverLoader({})("lib/canvas/download-error.ts");
for (const [error, code, status] of [
["HTTP 404", "SOURCE_NOT_FOUND", 404], ["HTTP 403", "SOURCE_FORBIDDEN", 403],
["TimeoutError: slow body", "SOURCE_TIMEOUT", 504], ["fetch failed", "SOURCE_UNAVAILABLE", 503],
["source returned an error document", "INVALID_IMAGE", 422], ["unsupported image format", "IMAGE_CONVERSION_FAILED", 422],
["STORAGE_WRITE_FAILED", "DOWNLOAD_STORAGE_FAILED", 503], ["DOWNLOAD_BUSY", "DOWNLOAD_BUSY", 429],
]) {
const failure = getDownloadFailure(new Error(error as string));
expect(failure).toMatchObject({ code, status });
expect(failure.recommendation).toBeTruthy();
expect(formatDownloadFailure(failure, "feedback-id")).toContain("下载编号：feedback-id");
if (status === 404) expect(failure.recommendation).not.toContain("稍后重试");
}
});
test("failed preparation polls retain the same cause and feedback ID without rerunning the load", async () => {
const { createDownloadPreparationQueue } = serverLoader({})("lib/canvas/download-preparation.ts");
const runs: Array<() => Promise<void>> = [];
let loads = 0;
const queue = createDownloadPreparationQueue({
load: async () => { loads++; throw new Error("HTTP 404 https://source.example/private?token=private"); },
read: async () => null, write: async () => {}, schedule: (run: () => Promise<void>) => runs.push(run),
});
const input = { userId: "owner", urls: ["https://source.example/original"], requestOrigin: "https://app.example", cookie: "session=private" };
const accepted = await queue.request(input);
await runs[0]();
for (let i = 0; i < 3; i++) {
const failed = await queue.request(input);
expect(failed).toMatchObject({ status: "failed", requestId: accepted.requestId, failure: { code: "SOURCE_NOT_FOUND", status: 404 } });
expect(failed.error).not.toContain("token=private");
}
expect(loads).toBe(1);
});
test("download queue saturation returns a retryable 429 instead of a source 502", async () => {
const { createDownloadPreparationQueue } = serverLoader({})("lib/canvas/download-preparation.ts");
const queue = createDownloadPreparationQueue({ load: async () => { throw new Error("not started"); }, read: async () => null, write: async () => {}, schedule() {} });
for (let i = 0; i < 4; i++) await queue.request({ userId: "owner", urls: [`https://source.example/${i}`], requestOrigin: "https://app.example", cookie: "" });
expect(await queue.request({ userId: "owner", urls: ["https://source.example/fifth"], requestOrigin: "https://app.example", cookie: "" }))
.toMatchObject({ status: "failed", failure: { code: "DOWNLOAD_BUSY", status: 429, retryable: true } });
});
test("cold archived downloads wait for CDN preparation and never buffer the file through the app", async () => {
const queued: string[] = [];
let ready = false;
const route = serverLoader({
"@/app/(auth)/auth": auth,
"next/server": { NextResponse: Response, after() {} },
"@/lib/storage/canvas-cdn-download": { resolveCanvasCdnDownload: async () => ({
task: { id: "archive-task", targetUrl: "https://cdn.example/original.jpg", metadata: { downloadAsset: { status: "pending" } } },
canPrepareDirect: true,
direct: ready ? { delivery: "cdn", downloadUrl: "https://cdn.example/prepared.png", filename: "original.png", bytes: 4000000 } : null,
}) },
"@/lib/storage/image-download-preparation": { scheduleImageDownloadPreparation: (id: string) => queued.push(id) },
"@/lib/canvas/photoshop-safe-download": { sanitizeCanvasDownloadFileName: () => "original", fetchCanvasDownloadAsset: () => { throw new Error("Must use CDN delivery"); } },
})("app/api/canvas/download-image/route.ts");
const first = await route.POST(request());
expect(first.status).toBe(202);
expect(await first.json()).toMatchObject({ delivery: "preparing", requestId: "archive-task" });
ready = true;
const second = await route.POST(request());
expect(second.status).toBe(200);
expect(await second.json()).toMatchObject({ delivery: "cdn", bytes: 4000000 });
expect(queued).toEqual(["archive-task"]);
});
test("an expired archived source returns its permanent cause and download task ID", async () => {
const errors = serverLoader({})("lib/canvas/download-error.ts");
const route = serverLoader({
"@/app/(auth)/auth": auth, "next/server": { NextResponse: Response, after() {} },
"@/lib/storage/canvas-cdn-download": { resolveCanvasCdnDownload: async () => ({ task: {
id: "failed-archive", targetUrl: "https://cdn.example/missing.png",
metadata: { downloadAsset: { status: "abandoned", failure: errors.getDownloadFailure("HTTP 404") } },
}, canPrepareDirect: true, direct: null }) },
"@/lib/storage/image-download-preparation": { scheduleImageDownloadPreparation() { throw new Error("Do not retry a permanent failure"); } },
})("app/api/canvas/download-image/route.ts");
const response = await route.POST(request());
expect(response.status).toBe(404);
expect(await response.json()).toMatchObject({ requestId: "failed-archive", failure: { code: "SOURCE_NOT_FOUND" } });
});
test("the download browser keeps the structured cause, advice and feedback ID", async () => {
const failure = { code: "SOURCE_FORBIDDEN", message: "图片源站拒绝访问原图。", recommendation: "请联系管理员检查访问权限。", status: 403, retryable: false };
const client = serverLoader({ fetch: async () => Response.json({ failure, requestId: "real-feedback" }, { status: 403 }) })("lib/client/canvas-image-download.ts");
let caught: unknown;
try { await client.downloadCanvasImageAsPng({ url: "https://source.example/original" }); } catch (error) { caught = error; }
expect(client.getCanvasImageDownloadErrorMessage(caught)).toBe("图片源站拒绝访问原图。请联系管理员检查访问权限。\n下载编号：real-feedback");
});
test("the preparation deadline cancels the source body as well as its headers", async () => {
const cache = serverLoader({ fetch: async (_url: string, options: { signal: AbortSignal }) => ({
ok: true, headers: new Headers({ "content-type": "image/png" }),
arrayBuffer: () => new Promise((_resolve, reject) => options.signal.addEventListener("abort", () => reject(options.signal.reason), { once: true })),
}) })("lib/storage/image-byte-cache.ts");
const controller = new AbortController();
const fetching = cache.fetchImageBytes(`https://source.example/${randomUUID()}`, { timeoutMs: 10000, signal: controller.signal });
setTimeout(() => controller.abort(new Error("Preparation canceled")), 20);
await expect(fetching).rejects.toThrow("Preparation canceled");
});
test("requested downloads are prioritized with two workers before scanning background assets", async () => {
let active = 0; let maximum = 0; let scans = 0;
const releases: Array<() => void> = [];
const claimed: string[] = []; const saved: string[] = [];
const bytes = Buffer.from("compatible PNG fixture");
const worker = serverLoader({
"@/lib/observability/active-work": { trackRuntimeWork: (execute: () => Promise<void>) => execute() },
"./image-archive-db": {
claimImageDownloadTask: async (id: string) => { claimed.push(id); return { id, targetUrl: `https://cdn.example/${id}.png`, metadata: {} }; },
saveImageDownloadAsset: async (id: string) => saved.push(id),
getImageDownloadTasks: async () => { scans++; return []; }, hasPendingImageDownloads: async () => false,
},
"./image-byte-cache": { fetchImageBytes: async () => { active++; maximum = Math.max(maximum, active); await new Promise<void>(resolve => releases.push(resolve)); active--; return { buffer: bytes, contentType: "image/png" }; }, cacheImageBytes: async () => {} },
"@/lib/canvas/photoshop-safe-download": { normalizeCanvasDownloadAsset: async () => ({ ok: true, bytes, contentType: "image/png" }) },
"./service": { uploadFile() { throw new Error("Compatible PNG must retain its object"); } },
})("lib/storage/image-download-preparation.ts");
worker.scheduleImageDownloadPreparation("one"); worker.scheduleImageDownloadPreparation("two"); worker.scheduleImageDownloadPreparation("three");
await expect.poll(() => active).toBe(2);
expect(scans).toBe(0);
releases.splice(0).forEach(release => release());
await expect.poll(() => claimed.length).toBe(3);
releases.splice(0).forEach(release => release());
await expect.poll(() => saved.length).toBe(3);
expect(maximum).toBe(2); expect(scans).toBe(0);
});
test("archive URL replacement cannot block the download worker wakeup", async () => {
let scheduled = false; let finish!: () => void; let replacing = false;
const gate = new Promise<void>(resolve => { finish = resolve; });
const job = serverLoader({
"@/lib/observability/active-work": { trackRuntimeWork: (execute: () => Promise<unknown>) => execute() },
"@/lib/storage/image-download-preparation": { scheduleImageDownloadPreparation() { scheduled = true; } },
"@/lib/storage/image-archive-db": { recoverStaleImageArchiveTasks: async () => {}, getImageArchiveTasksToStore: async () => [],
getImageArchiveTasksToReplace: async () => [{ id: "archive", sourceUrl: "https://source.example/a", targetUrl: "https://cdn.example/a" }],
markImageArchiveTaskReplacing: async () => true, markImageArchiveTaskCompleted: async () => {}, hasPendingImageDownloads: async () => false,
getImageArchiveTaskStats: async () => ({ pendingStore: 0, pendingReplace: 0 }),
},
"@/lib/storage/image-url-replacement": { replaceImageUrlInDatabase: async () => { replacing = true; await gate; return { changed: 1 }; } },
"@/lib/storage/image-archive": {},
})("lib/jobs/image-archive-job.ts");
const running = job.runImageArchiveJob();
await expect.poll(() => replacing).toBe(true);
expect(scheduled).toBe(true);
finish();
expect((await running).replace.succeeded).toBe(1);
});

4
tests/routes/image-archive-flow.test.ts
View File

@ -224,7 +224,7 @@ test("bucket failure retains the provider URL and retry task", async () => {
let stored = 0;
let replaced = 0;
const module = serverLoader({
"@/lib/storage/image-download-preparation": { preparePendingImageDownloads: async () => 0 },
"@/lib/storage/image-download-preparation": { scheduleImageDownloadPreparation() {} },
"@/lib/storage/image-archive": {
archiveTemporaryImage: async () => {
throw new Error("Bucket unavailable");
@ -414,7 +414,7 @@ test("successful background archive replaces saved references immediately", asyn
let completed = false;
const calls: string[][] = [];
const module = serverLoader({
"@/lib/storage/image-download-preparation": { preparePendingImageDownloads: async () => 0 },
"@/lib/storage/image-download-preparation": { scheduleImageDownloadPreparation() {} },
"@/lib/storage/image-archive": {
archiveTemporaryImage: async () => ({ url: permanent, bytes: png.length }),
},

11
tests/routes/runtime-active-work.test.ts
View File

@ -17,3 +17,14 @@ test("release draining includes background work until its original promise settl
await expect(work.trackRuntimeWork(async () => { throw new Error("expected failure"); })).rejects.toThrow("expected failure");
expect(counts.at(-1)).toBe(0);
});
test("durable archive handoff is separate from unfinished original generation", async () => {
const records: Array<{ active: number; durable: number }> = [];
const work = serverLoader({ "node:fs": { writeFileSync: (_path: string, value: string) => records.push(JSON.parse(value)), unlinkSync() {} } })("lib/observability/active-work.ts");
let complete!: () => void;
const original = work.trackRuntimeWork(() => new Promise<void>(resolve => { complete = resolve; }));
await work.trackRuntimeWork(async () => "archive", { durable: true });
expect(records.map(x => [x.active, x.durable])).toEqual([[1, 0], [2, 1], [1, 0]]);
complete(); await original;
expect(records.at(-1)).toMatchObject({ active: 0, durable: 0 });
});