@rockhall/electron-offline-content 0.4.0

package/dist/internal/validation.js

@@ -0,0 +1,196 @@
+import { DataValidationError } from "../shared/errors.js";
+import { z } from "zod";
+//#region src/internal/validation.ts
+const nonNegativeIntegerSchema = z.number().int().nonnegative();
+const nonNegativeNumberSchema = z.number().nonnegative();
+/**
+* Schema for IPC/API string identifiers: asset key, index name, index value, file stem.
+* Enforces min 1 and max 2000 characters.
+*/
+const stringInputSchema = z.string().min(1).max(2e3);
+const jsonValueSchema = z.lazy(() => z.union([
+	z.string(),
+	z.number(),
+	z.boolean(),
+	z.null(),
+	z.array(jsonValueSchema),
+	z.record(z.string(), jsonValueSchema)
+]));
+const jsonObjectSchema = z.record(z.string(), jsonValueSchema);
+const stringRecordSchema = z.record(z.string(), z.string());
+const serializedMediaCacheErrorSchema = z.object({
+	name: z.string(),
+	code: z.string(),
+	message: z.string()
+});
+const syncRunStatsSchema = z.object({
+	totalAssets: nonNegativeIntegerSchema,
+	downloadedAssets: nonNegativeIntegerSchema,
+	skippedAssets: nonNegativeIntegerSchema,
+	bytesDownloaded: nonNegativeNumberSchema
+});
+const syncProgressSchema = z.object({
+	runId: nonNegativeIntegerSchema,
+	phase: z.enum([
+		"resolving-store",
+		"staging-generation",
+		"diffing",
+		"downloading",
+		"committing",
+		"pruning"
+	]),
+	totalAssets: nonNegativeIntegerSchema,
+	completedAssets: nonNegativeIntegerSchema,
+	downloadedAssets: nonNegativeIntegerSchema,
+	skippedAssets: nonNegativeIntegerSchema,
+	bytesDownloaded: nonNegativeNumberSchema
+});
+const syncRunSummarySchema = z.object({
+	id: nonNegativeIntegerSchema,
+	status: z.enum([
+		"running",
+		"success",
+		"error"
+	]),
+	startedAt: nonNegativeIntegerSchema,
+	finishedAt: nonNegativeIntegerSchema.nullable(),
+	errorCode: z.string().nullable(),
+	errorMessage: z.string().nullable(),
+	stats: syncRunStatsSchema
+});
+const mediaCacheStatusSchema = z.object({
+	phase: z.enum([
+		"idle",
+		"syncing",
+		"ready",
+		"error"
+	]),
+	storageRoot: z.string().nullable().default(null),
+	activeGenerationId: nonNegativeIntegerSchema.nullable(),
+	progress: syncProgressSchema.nullable(),
+	lastRun: syncRunSummarySchema.nullable(),
+	error: serializedMediaCacheErrorSchema.nullable(),
+	updatedAt: nonNegativeIntegerSchema
+});
+const mediaKindSchema = z.enum([
+	"video",
+	"image",
+	"audio",
+	"document",
+	"html",
+	"text",
+	"binary"
+]);
+const mediaCacheAppPathSchema = z.enum([
+	"home",
+	"appData",
+	"userData",
+	"sessionData",
+	"temp",
+	"exe",
+	"module",
+	"desktop",
+	"documents",
+	"downloads",
+	"music",
+	"pictures",
+	"videos",
+	"recent",
+	"logs",
+	"crashDumps"
+]);
+const storagePathSegmentSchema = z.string().min(1).refine((segment) => !/[/\\]/.test(segment), { message: "Storage path segments must not contain path separators" }).refine((segment) => segment !== "." && segment !== "..", { message: "Storage path segments must not be \".\" or \"..\"" });
+const mediaCacheStoragePathSchema = z.object({
+	appPath: mediaCacheAppPathSchema,
+	segments: z.array(storagePathSegmentSchema).optional()
+});
+const statusSnapshotRowSchema = z.object({ status_json: z.string() });
+const syncRunRowSchema = z.object({
+	id: nonNegativeIntegerSchema,
+	started_at_ms: nonNegativeIntegerSchema,
+	finished_at_ms: nonNegativeIntegerSchema.nullable(),
+	status: z.enum([
+		"running",
+		"success",
+		"error"
+	]),
+	error_code: z.string().nullable(),
+	error_message: z.string().nullable(),
+	stats_json: z.string()
+});
+const syncRunIdRowSchema = z.object({ id: nonNegativeIntegerSchema });
+const generationIdRowSchema = z.object({ id: nonNegativeIntegerSchema });
+const activeGenerationRowSchema = z.object({ generation_id: nonNegativeIntegerSchema });
+/** Row shape from getGenerationAssets used during sync diffing. */
+const generationAssetRowSchema = z.object({
+	assetKey: z.string(),
+	version: z.string(),
+	relativePath: z.string().nullable(),
+	mimeType: z.string(),
+	url: z.string()
+});
+/** Row shape for a fully joined active asset used for queries. */
+const activeAssetRowSchema = z.object({
+	generationId: nonNegativeIntegerSchema,
+	assetKey: z.string(),
+	displayKey: z.string(),
+	version: z.string(),
+	mimeType: z.string(),
+	mediaKind: mediaKindSchema,
+	byteLength: nonNegativeNumberSchema.nullable(),
+	metadata: z.string(),
+	indexesJson: z.string(),
+	relativePath: z.string().nullable(),
+	url: z.string(),
+	fileStem: z.string(),
+	orderIndex: nonNegativeIntegerSchema
+});
+const pendingDeletionSchema = z.object({
+	deletionKey: z.string(),
+	logicalKey: z.string(),
+	relativePath: z.string()
+});
+const protocolAssetTargetRowSchema = z.object({ relative_path: z.string().nullable() });
+const fileStemRowSchema = z.object({ assetKey: z.string() });
+const optionalNonNegativeIntegerSchema = z.number().int().nonnegative().nullish().transform((value) => value ?? void 0);
+const optionalStringSchema = z.string().nullish().transform((value) => value ?? void 0);
+const paginationInputSchema = z.object({
+	limit: optionalNonNegativeIntegerSchema,
+	cursor: optionalStringSchema
+});
+const optionalPaginationInputSchema = paginationInputSchema.nullish().transform((value) => value ?? void 0);
+const cursorPayloadSchema = z.object({ index: z.number().int().nonnegative() });
+function parseWithSchema(schema, value, context) {
+	const result = schema.safeParse(value);
+	if (result.success) return result.data;
+	throw new DataValidationError(`Invalid ${context}: ${formatZodIssues(result.error)}`, { cause: result.error });
+}
+function parseJsonWithSchema(rawJson, schema, context) {
+	let parsed;
+	try {
+		parsed = JSON.parse(rawJson);
+	} catch (error) {
+		throw new DataValidationError(`Invalid ${context}: failed to parse JSON.`, { cause: error });
+	}
+	return parseWithSchema(schema, parsed, context);
+}
+function stringifyWithSchema(value, schema, context) {
+	let rawJson;
+	try {
+		rawJson = JSON.stringify(value);
+	} catch (error) {
+		throw new DataValidationError(`Invalid ${context}: value is not JSON serializable.`, { cause: error });
+	}
+	if (rawJson === void 0) throw new DataValidationError(`Invalid ${context}: value is not JSON serializable.`);
+	parseJsonWithSchema(rawJson, schema, context);
+	return rawJson;
+}
+function formatZodIssues(error) {
+	return error.issues.map((issue) => {
+		return `${issue.path.length > 0 ? issue.path.join(".") : "(root)"}: ${issue.message}`;
+	}).join("; ");
+}
+//#endregion
+export { activeAssetRowSchema, activeGenerationRowSchema, cursorPayloadSchema, fileStemRowSchema, generationAssetRowSchema, generationIdRowSchema, jsonObjectSchema, jsonValueSchema, mediaCacheStatusSchema, mediaCacheStoragePathSchema, optionalPaginationInputSchema, paginationInputSchema, parseJsonWithSchema, parseWithSchema, pendingDeletionSchema, protocolAssetTargetRowSchema, serializedMediaCacheErrorSchema, statusSnapshotRowSchema, stringInputSchema, stringRecordSchema, stringifyWithSchema, syncProgressSchema, syncRunIdRowSchema, syncRunRowSchema, syncRunStatsSchema, syncRunSummarySchema };
+
+//# sourceMappingURL=validation.js.map

package/dist/internal/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","names":[],"sources":["../../src/internal/validation.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { DataValidationError } from \"../shared/errors.js\";\nimport type { ActiveAssetRow, GenerationAssetRow, PendingDeletion } from \"../main/database.js\";\nimport type {\n  JsonValue,\n  MediaCacheAppPath,\n  MediaCacheStatus,\n  MediaCacheStoragePath,\n  MediaKind,\n  SerializedMediaCacheError,\n  SyncProgress,\n  SyncRunStats,\n  SyncRunSummary,\n} from \"../shared/types.js\";\n\nconst nonNegativeIntegerSchema = z.number().int().nonnegative();\nconst nonNegativeNumberSchema = z.number().nonnegative();\n\n/**\n * Schema for IPC/API string identifiers: asset key, index name, index value, file stem.\n * Enforces min 1 and max 2000 characters.\n */\nexport const stringInputSchema = z.string().min(1).max(2000);\n\nexport const jsonValueSchema: z.ZodType<JsonValue> = z.lazy(() =>\n  z.union([\n    z.string(),\n    z.number(),\n    z.boolean(),\n    z.null(),\n    z.array(jsonValueSchema),\n    z.record(z.string(), jsonValueSchema),\n  ]),\n);\n\nexport const jsonObjectSchema: z.ZodType<Record<string, JsonValue>> = z.record(\n  z.string(),\n  jsonValueSchema,\n);\n\nexport const stringRecordSchema = z.record(z.string(), z.string());\n\nexport const serializedMediaCacheErrorSchema: z.ZodType<SerializedMediaCacheError> = z.object({\n  name: z.string(),\n  code: z.string(),\n  message: z.string(),\n});\n\nexport const syncRunStatsSchema: z.ZodType<SyncRunStats> = z.object({\n  totalAssets: nonNegativeIntegerSchema,\n  downloadedAssets: nonNegativeIntegerSchema,\n  skippedAssets: nonNegativeIntegerSchema,\n  bytesDownloaded: nonNegativeNumberSchema,\n});\n\nexport const syncProgressSchema: z.ZodType<SyncProgress> = z.object({\n  runId: nonNegativeIntegerSchema,\n  phase: z.enum([\n    \"resolving-store\",\n    \"staging-generation\",\n    \"diffing\",\n    \"downloading\",\n    \"committing\",\n    \"pruning\",\n  ]),\n  totalAssets: nonNegativeIntegerSchema,\n  completedAssets: nonNegativeIntegerSchema,\n  downloadedAssets: nonNegativeIntegerSchema,\n  skippedAssets: nonNegativeIntegerSchema,\n  bytesDownloaded: nonNegativeNumberSchema,\n});\n\nexport const syncRunSummarySchema: z.ZodType<SyncRunSummary> = z.object({\n  id: nonNegativeIntegerSchema,\n  status: z.enum([\"running\", \"success\", \"error\"]),\n  startedAt: nonNegativeIntegerSchema,\n  finishedAt: nonNegativeIntegerSchema.nullable(),\n  errorCode: z.string().nullable(),\n  errorMessage: z.string().nullable(),\n  stats: syncRunStatsSchema,\n});\n\nexport const mediaCacheStatusSchema: z.ZodType<MediaCacheStatus> = z.object({\n  phase: z.enum([\"idle\", \"syncing\", \"ready\", \"error\"]),\n  storageRoot: z.string().nullable().default(null),\n  activeGenerationId: nonNegativeIntegerSchema.nullable(),\n  progress: syncProgressSchema.nullable(),\n  lastRun: syncRunSummarySchema.nullable(),\n  error: serializedMediaCacheErrorSchema.nullable(),\n  updatedAt: nonNegativeIntegerSchema,\n});\n\nconst mediaKindSchema: z.ZodType<MediaKind> = z.enum([\n  \"video\",\n  \"image\",\n  \"audio\",\n  \"document\",\n  \"html\",\n  \"text\",\n  \"binary\",\n]);\n\nconst mediaCacheAppPathSchema: z.ZodType<MediaCacheAppPath> = z.enum([\n  \"home\",\n  \"appData\",\n  \"userData\",\n  \"sessionData\",\n  \"temp\",\n  \"exe\",\n  \"module\",\n  \"desktop\",\n  \"documents\",\n  \"downloads\",\n  \"music\",\n  \"pictures\",\n  \"videos\",\n  \"recent\",\n  \"logs\",\n  \"crashDumps\",\n]);\n\nconst storagePathSegmentSchema = z\n  .string()\n  .min(1)\n  .refine((segment) => !/[/\\\\]/.test(segment), {\n    message: \"Storage path segments must not contain path separators\",\n  })\n  .refine((segment) => segment !== \".\" && segment !== \"..\", {\n    message: 'Storage path segments must not be \".\" or \"..\"',\n  });\n\nexport const mediaCacheStoragePathSchema: z.ZodType<MediaCacheStoragePath> = z.object({\n  appPath: mediaCacheAppPathSchema,\n  segments: z.array(storagePathSegmentSchema).optional(),\n});\n\nexport const statusSnapshotRowSchema = z.object({\n  status_json: z.string(),\n});\n\nexport const syncRunRowSchema = z.object({\n  id: nonNegativeIntegerSchema,\n  started_at_ms: nonNegativeIntegerSchema,\n  finished_at_ms: nonNegativeIntegerSchema.nullable(),\n  status: z.enum([\"running\", \"success\", \"error\"]),\n  error_code: z.string().nullable(),\n  error_message: z.string().nullable(),\n  stats_json: z.string(),\n});\n\nexport const syncRunIdRowSchema = z.object({\n  id: nonNegativeIntegerSchema,\n});\n\nexport const generationIdRowSchema = z.object({\n  id: nonNegativeIntegerSchema,\n});\n\nexport const activeGenerationRowSchema = z.object({\n  generation_id: nonNegativeIntegerSchema,\n});\n\n/** Row shape from getGenerationAssets used during sync diffing. */\nexport const generationAssetRowSchema: z.ZodType<GenerationAssetRow> = z.object({\n  assetKey: z.string(),\n  version: z.string(),\n  relativePath: z.string().nullable(),\n  mimeType: z.string(),\n  url: z.string(),\n});\n\n/** Row shape for a fully joined active asset used for queries. */\nexport const activeAssetRowSchema: z.ZodType<ActiveAssetRow> = z.object({\n  generationId: nonNegativeIntegerSchema,\n  assetKey: z.string(),\n  displayKey: z.string(),\n  version: z.string(),\n  mimeType: z.string(),\n  mediaKind: mediaKindSchema,\n  byteLength: nonNegativeNumberSchema.nullable(),\n  metadata: z.string(),\n  indexesJson: z.string(),\n  relativePath: z.string().nullable(),\n  url: z.string(),\n  fileStem: z.string(),\n  orderIndex: nonNegativeIntegerSchema,\n});\n\nexport const pendingDeletionSchema: z.ZodType<PendingDeletion> = z.object({\n  deletionKey: z.string(),\n  logicalKey: z.string(),\n  relativePath: z.string(),\n});\n\nexport const protocolAssetTargetRowSchema = z.object({\n  relative_path: z.string().nullable(),\n});\n\nexport const fileStemRowSchema = z.object({\n  assetKey: z.string(),\n});\n\nconst optionalNonNegativeIntegerSchema = z\n  .number()\n  .int()\n  .nonnegative()\n  .nullish()\n  .transform((value) => value ?? undefined);\n\nconst optionalStringSchema = z\n  .string()\n  .nullish()\n  .transform((value) => value ?? undefined);\n\nexport const paginationInputSchema = z.object({\n  limit: optionalNonNegativeIntegerSchema,\n  cursor: optionalStringSchema,\n});\n\nexport const optionalPaginationInputSchema = paginationInputSchema\n  .nullish()\n  .transform((value) => value ?? undefined);\n\nexport const cursorPayloadSchema = z.object({\n  index: z.number().int().nonnegative(),\n});\n\nexport function parseWithSchema<T>(schema: z.ZodType<T>, value: unknown, context: string): T {\n  const result = schema.safeParse(value);\n  if (result.success) {\n    return result.data;\n  }\n\n  throw new DataValidationError(`Invalid ${context}: ${formatZodIssues(result.error)}`, {\n    cause: result.error,\n  });\n}\n\nexport function parseJsonWithSchema<T>(rawJson: string, schema: z.ZodType<T>, context: string): T {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(rawJson);\n  } catch (error) {\n    throw new DataValidationError(`Invalid ${context}: failed to parse JSON.`, {\n      cause: error,\n    });\n  }\n\n  return parseWithSchema(schema, parsed, context);\n}\n\nexport function stringifyWithSchema<T>(\n  value: unknown,\n  schema: z.ZodType<T>,\n  context: string,\n): string {\n  let rawJson: string | undefined;\n  try {\n    rawJson = JSON.stringify(value);\n  } catch (error) {\n    throw new DataValidationError(`Invalid ${context}: value is not JSON serializable.`, {\n      cause: error,\n    });\n  }\n  if (rawJson === undefined) {\n    throw new DataValidationError(`Invalid ${context}: value is not JSON serializable.`);\n  }\n\n  parseJsonWithSchema(rawJson, schema, context);\n  return rawJson;\n}\n\nfunction formatZodIssues(error: z.ZodError): string {\n  return error.issues\n    .map((issue) => {\n      const path = issue.path.length > 0 ? issue.path.join(\".\") : \"(root)\";\n      return `${path}: ${issue.message}`;\n    })\n    .join(\"; \");\n}\n"],"mappings":"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"}

package/dist/main/asset-download.cjs

@@ -0,0 +1,265 @@
+const require_shared_errors = require("../shared/errors.cjs");
+let node_fs = require("node:fs");
+let node_fs_promises = require("node:fs/promises");
+let node_stream = require("node:stream");
+let node_path = require("node:path");
+let node_stream_promises = require("node:stream/promises");
+//#region src/main/asset-download.ts
+/** When `reserveFreeBytes` is omitted, preserve this much free space on the cache volume (1 GiB). */
+const DEFAULT_RESERVE_FREE_BYTES = 1024 * 1024 * 1024;
+/**
+* Effective minimum free bytes: explicit option, or {@link DEFAULT_RESERVE_FREE_BYTES} when omitted.
+* `0` means no reserved headroom.
+* @internal
+*/
+function effectiveReserveFreeBytes(explicit) {
+	return explicit === void 0 ? DEFAULT_RESERVE_FREE_BYTES : explicit;
+}
+var AssetDownloader = class {
+	storageRoot;
+	deps;
+	options;
+	constructor(storageRoot, deps, options) {
+		this.storageRoot = storageRoot;
+		this.deps = deps;
+		this.options = options;
+	}
+	remainingDownloadBytes(download) {
+		const expectedBytes = download.byteLength ?? 0;
+		const partialBytes = this.partialDownloadBytes(download);
+		return Math.max(expectedBytes - partialBytes, 0);
+	}
+	partialDownloadPath(download) {
+		return (0, node_path.join)(this.storageRoot, "temp", sanitizeSegment(download.assetKey), sanitizeSegment(download.version), `${sanitizeSegment(download.fileName)}.part`);
+	}
+	cleanupObsoletePartialDownloads(downloads) {
+		const tempRoot = (0, node_path.join)(this.storageRoot, "temp");
+		if (!(0, node_fs.existsSync)(tempRoot)) return;
+		const resumablePaths = new Set(downloads.map((download) => this.partialDownloadPath(download)));
+		for (const filePath of listFilesRecursively(tempRoot)) {
+			if (!filePath.endsWith(".part") || resumablePaths.has(filePath)) continue;
+			(0, node_fs.rmSync)(filePath, { force: true });
+			pruneEmptyParents(filePath, this.storageRoot);
+		}
+	}
+	async downloadAsset(download, onChunk) {
+		const destinationRelativePath = (0, node_path.join)("blobs", sanitizeSegment(download.assetKey), sanitizeSegment(download.version), sanitizeSegment(download.fileName));
+		const destinationPath = (0, node_path.join)(this.storageRoot, destinationRelativePath);
+		(0, node_fs.mkdirSync)((0, node_path.dirname)(destinationPath), { recursive: true });
+		const tempPath = this.partialDownloadPath(download);
+		(0, node_fs.mkdirSync)((0, node_path.dirname)(tempPath), { recursive: true });
+		let lastError = null;
+		for (let attempt = 0; attempt < TOTAL_DOWNLOAD_ATTEMPTS; attempt += 1) try {
+			return await this.downloadAssetAttempt(download, destinationPath, destinationRelativePath, tempPath, onChunk);
+		} catch (error) {
+			lastError = error;
+			if (require_shared_errors.isNoSpaceError(error)) {
+				await (0, node_fs_promises.unlink)(tempPath).catch(() => void 0);
+				this.options.emitLog("error", "asset_download_storage_failed", {
+					asset_key: download.assetKey,
+					url: download.request.url
+				});
+				throw new require_shared_errors.StorageLimitError(`Disk is full while downloading ${download.assetKey}.`, { cause: error });
+			}
+			if (!isRetryableDownloadError(error)) {
+				await (0, node_fs_promises.unlink)(tempPath).catch(() => void 0);
+				throw error;
+			}
+			if (attempt === TOTAL_DOWNLOAD_ATTEMPTS - 1) {
+				this.options.emitLog("warn", "asset_download_retry_exhausted", {
+					asset_key: download.assetKey,
+					attempt: attempt + 1,
+					partial_path: tempPath
+				});
+				break;
+			}
+			const delayMs = calculateRetryDelay(attempt);
+			this.options.emitLog("warn", "asset_download_retry_scheduled", {
+				asset_key: download.assetKey,
+				attempt: attempt + 1,
+				retry_delay_ms: delayMs
+			});
+			await this.deps.sleep(delayMs);
+		}
+		throw lastError;
+	}
+	async ensureFileSpaceCommit() {
+		const stats = await this.deps.statfs(this.storageRoot);
+		const availableBytes = Number(stats.bavail) * Number(stats.bsize);
+		const reserve = effectiveReserveFreeBytes(this.options.reserveFreeBytes);
+		if (availableBytes < reserve) throw new require_shared_errors.StorageLimitError(`Committing download would violate reserveFreeBytes ${reserve}.`);
+	}
+	partialDownloadBytes(download) {
+		const tempPath = this.partialDownloadPath(download);
+		return (0, node_fs.existsSync)(tempPath) ? (0, node_fs.statSync)(tempPath).size : 0;
+	}
+	async downloadAssetAttempt(download, destinationPath, destinationRelativePath, tempPath, onChunk) {
+		let restartedWithoutRange = false;
+		for (;;) {
+			const resumeSize = (0, node_fs.existsSync)(tempPath) ? (0, node_fs.statSync)(tempPath).size : 0;
+			const headers = new Headers(download.request.headers);
+			if (resumeSize > 0) headers.set("range", `bytes=${resumeSize}-`);
+			const response = await this.deps.fetchImpl(download.request.url, {
+				method: download.request.method ?? "GET",
+				headers
+			});
+			if (resumeSize > 0 && response.status === 416) {
+				if (restartedWithoutRange) throw createDownloadError(`Server rejected range request for ${download.assetKey}.`, false, response.status);
+				restartedWithoutRange = true;
+				await (0, node_fs_promises.unlink)(tempPath).catch(() => void 0);
+				this.options.emitLog("debug", "asset_download_range_restart", {
+					asset_key: download.assetKey,
+					resumed_bytes: resumeSize,
+					response_status: response.status,
+					content_range: response.headers.get("content-range")
+				});
+				continue;
+			}
+			if (!response.ok || !response.body) {
+				this.options.emitLog("warn", "asset_download_rejected", {
+					asset_key: download.assetKey,
+					status: response.status,
+					status_text: response.statusText,
+					url: download.request.url
+				});
+				throw createDownloadError(`Download failed for ${download.assetKey}: ${response.status} ${response.statusText}`, isRetryableStatus(response.status), response.status);
+			}
+			if (resumeSize > 0 && (response.status !== 206 || parseContentRangeStart(response.headers.get("content-range")) !== resumeSize)) {
+				if (restartedWithoutRange) throw createDownloadError(`Server did not honor range request for ${download.assetKey}.`, false, response.status);
+				restartedWithoutRange = true;
+				await (0, node_fs_promises.unlink)(tempPath).catch(() => void 0);
+				this.options.emitLog("debug", "asset_download_range_restart", {
+					asset_key: download.assetKey,
+					resumed_bytes: resumeSize,
+					response_status: response.status,
+					content_range: response.headers.get("content-range")
+				});
+				continue;
+			}
+			const nodeStream = node_stream.Readable.fromWeb(response.body);
+			const writeStream = (0, node_fs.createWriteStream)(tempPath, { flags: resumeSize > 0 ? "a" : "w" });
+			nodeStream.on("data", (chunk) => {
+				onChunk(chunk.byteLength);
+			});
+			try {
+				await (0, node_stream_promises.pipeline)(nodeStream, writeStream);
+			} catch (error) {
+				throw wrapRetryableDownloadError(error);
+			}
+			await this.ensureFileSpaceCommit();
+			(0, node_fs.mkdirSync)((0, node_path.dirname)(destinationPath), { recursive: true });
+			(0, node_fs.rmSync)(destinationPath, { force: true });
+			(0, node_fs.renameSync)(tempPath, destinationPath);
+			return {
+				relativePath: destinationRelativePath,
+				fallbackMimeType: normalizeResponseMimeType(response.headers.get("content-type"))
+			};
+		}
+	}
+};
+function sanitizeSegment(segment) {
+	return encodeURIComponent(segment);
+}
+function pruneEmptyParents(pathToFile, storageRoot) {
+	let current = (0, node_path.dirname)(pathToFile);
+	while (current.startsWith(storageRoot) && current !== storageRoot) {
+		if ((0, node_fs.existsSync)(current) && (0, node_fs.readdirSync)(current).length === 0) {
+			(0, node_fs.rmSync)(current, {
+				recursive: true,
+				force: true
+			});
+			current = (0, node_path.dirname)(current);
+			continue;
+		}
+		break;
+	}
+}
+function listFilesRecursively(directory) {
+	if (!(0, node_fs.existsSync)(directory)) return [];
+	if ((0, node_fs.statSync)(directory).isFile()) return [directory];
+	return (0, node_fs.readdirSync)(directory).flatMap((entry) => listFilesRecursively((0, node_path.join)(directory, entry)));
+}
+const TOTAL_DOWNLOAD_ATTEMPTS = 4;
+const RETRYABLE_STATUS_CODES = new Set([
+	408,
+	429,
+	500,
+	502,
+	503,
+	504
+]);
+const RETRYABLE_ERROR_CODES = new Set([
+	"ECONNRESET",
+	"ECONNREFUSED",
+	"EHOSTUNREACH",
+	"ENETUNREACH",
+	"ENOTFOUND",
+	"ETIMEDOUT",
+	"UND_ERR_CONNECT_TIMEOUT",
+	"UND_ERR_HEADERS_TIMEOUT",
+	"UND_ERR_SOCKET"
+]);
+function calculateRetryDelay(attempt) {
+	const baseDelay = 1e3 * Math.pow(2, attempt);
+	return baseDelay + Math.floor(baseDelay * .25 * Math.random());
+}
+function createDownloadError(message, retryable, status, cause) {
+	const error = new require_shared_errors.SyncFailureError(message, cause ? { cause } : void 0);
+	error.retryable = retryable;
+	error.status = status;
+	return error;
+}
+function wrapRetryableDownloadError(error) {
+	if (error instanceof require_shared_errors.SyncFailureError) return error;
+	if (error instanceof Error) {
+		const wrapped = new require_shared_errors.SyncFailureError(error.message, { cause: error });
+		wrapped.retryable = hasRetryableDownloadSignal(error);
+		return wrapped;
+	}
+	const wrapped = new require_shared_errors.SyncFailureError(String(error));
+	wrapped.retryable = false;
+	return wrapped;
+}
+function isRetryableDownloadError(error) {
+	if (!(error instanceof Error)) return false;
+	const candidate = error;
+	if (candidate.retryable !== void 0) return candidate.retryable;
+	return hasRetryableDownloadSignal(error);
+}
+function isRetryableStatus(status) {
+	return RETRYABLE_STATUS_CODES.has(status);
+}
+function isRetryableErrorCode(code) {
+	return code !== void 0 && RETRYABLE_ERROR_CODES.has(code);
+}
+function isRetryableMessage(message) {
+	const value = message.toLowerCase();
+	return value.includes("aborted") || value.includes("connection") || value.includes("network") || value.includes("reset") || value.includes("socket") || value.includes("terminated") || value.includes("timeout");
+}
+function hasRetryableDownloadSignal(error) {
+	return collectErrorChain(error).some((entry) => isRetryableErrorCode(entry.code) || isRetryableMessage(entry.message));
+}
+function collectErrorChain(error) {
+	const chain = [];
+	let current = error;
+	while (current instanceof Error && !chain.includes(current)) {
+		chain.push(current);
+		current = current.cause;
+	}
+	return chain;
+}
+function normalizeResponseMimeType(contentType) {
+	const value = contentType?.trim();
+	return value && value.length > 0 ? value : null;
+}
+function parseContentRangeStart(contentRange) {
+	if (!contentRange) return null;
+	const match = contentRange.match(/^bytes (\d+)-\d+\/(?:\d+|\*)$/i);
+	return match?.[1] ? Number.parseInt(match[1], 10) : null;
+}
+//#endregion
+exports.AssetDownloader = AssetDownloader;
+exports.DEFAULT_RESERVE_FREE_BYTES = DEFAULT_RESERVE_FREE_BYTES;
+exports.effectiveReserveFreeBytes = effectiveReserveFreeBytes;
+
+//# sourceMappingURL=asset-download.cjs.map

package/dist/main/asset-download.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-download.cjs","names":["isNoSpaceError","StorageLimitError","Readable","SyncFailureError"],"sources":["../../src/main/asset-download.ts"],"sourcesContent":["import {\n  createWriteStream,\n  existsSync,\n  mkdirSync,\n  readdirSync,\n  renameSync,\n  rmSync,\n  statSync,\n} from \"node:fs\";\nimport { unlink } from \"node:fs/promises\";\nimport { Readable } from \"node:stream\";\nimport { pipeline } from \"node:stream/promises\";\nimport type { ReadableStream as NodeReadableStream } from \"node:stream/web\";\nimport { dirname, join } from \"node:path\";\nimport { isNoSpaceError, StorageLimitError, SyncFailureError } from \"../shared/errors.js\";\nimport type { JsonValue, MediaCacheLogLevel } from \"../shared/types.js\";\n\n/** When `reserveFreeBytes` is omitted, preserve this much free space on the cache volume (1 GiB). */\nexport const DEFAULT_RESERVE_FREE_BYTES = 1024 * 1024 * 1024;\n\n/**\n * Effective minimum free bytes: explicit option, or {@link DEFAULT_RESERVE_FREE_BYTES} when omitted.\n * `0` means no reserved headroom.\n * @internal\n */\nexport function effectiveReserveFreeBytes(explicit: number | undefined): number {\n  return explicit === undefined ? DEFAULT_RESERVE_FREE_BYTES : explicit;\n}\n\nexport interface QueuedAssetDownloadTarget {\n  assetKey: string;\n  fileName: string;\n  version: string;\n  byteLength?: number;\n}\n\nexport interface AssetDownloadTarget extends QueuedAssetDownloadTarget {\n  request: {\n    url: string;\n    method?: string;\n    headers?: HeadersInit;\n  };\n}\n\nexport interface AssetDownloadResult {\n  relativePath: string;\n  fallbackMimeType: string | null;\n}\n\nexport interface AssetDownloaderDependencies {\n  fetchImpl: typeof globalThis.fetch;\n  sleep: (delayMs: number) => Promise<void>;\n  statfs: (path: string) => Promise<StatFsResult>;\n}\n\nexport type AssetDownloadLogHandler = (\n  level: MediaCacheLogLevel,\n  event: string,\n  fields?: Record<string, JsonValue | undefined>,\n) => void;\n\ntype StatFsResult = Awaited<ReturnType<typeof import(\"node:fs/promises\").statfs>>;\n\nexport class AssetDownloader {\n  constructor(\n    private readonly storageRoot: string,\n    private readonly deps: AssetDownloaderDependencies,\n    private readonly options: {\n      reserveFreeBytes?: number;\n      emitLog: AssetDownloadLogHandler;\n    },\n  ) {}\n\n  remainingDownloadBytes(download: QueuedAssetDownloadTarget): number {\n    const expectedBytes = download.byteLength ?? 0;\n    const partialBytes = this.partialDownloadBytes(download);\n    return Math.max(expectedBytes - partialBytes, 0);\n  }\n\n  partialDownloadPath(download: QueuedAssetDownloadTarget): string {\n    return join(\n      this.storageRoot,\n      \"temp\",\n      sanitizeSegment(download.assetKey),\n      sanitizeSegment(download.version),\n      `${sanitizeSegment(download.fileName)}.part`,\n    );\n  }\n\n  cleanupObsoletePartialDownloads(downloads: QueuedAssetDownloadTarget[]): void {\n    const tempRoot = join(this.storageRoot, \"temp\");\n    if (!existsSync(tempRoot)) {\n      return;\n    }\n\n    const resumablePaths = new Set(downloads.map((download) => this.partialDownloadPath(download)));\n    for (const filePath of listFilesRecursively(tempRoot)) {\n      if (!filePath.endsWith(\".part\") || resumablePaths.has(filePath)) {\n        continue;\n      }\n\n      rmSync(filePath, { force: true });\n      pruneEmptyParents(filePath, this.storageRoot);\n    }\n  }\n\n  async downloadAsset(\n    download: AssetDownloadTarget,\n    onChunk: (chunkBytes: number) => void,\n  ): Promise<AssetDownloadResult> {\n    const destinationRelativePath = join(\n      \"blobs\",\n      sanitizeSegment(download.assetKey),\n      sanitizeSegment(download.version),\n      sanitizeSegment(download.fileName),\n    );\n    const destinationPath = join(this.storageRoot, destinationRelativePath);\n\n    mkdirSync(dirname(destinationPath), { recursive: true });\n    const tempPath = this.partialDownloadPath(download);\n    mkdirSync(dirname(tempPath), { recursive: true });\n\n    let lastError: unknown = null;\n\n    for (let attempt = 0; attempt < TOTAL_DOWNLOAD_ATTEMPTS; attempt += 1) {\n      try {\n        return await this.downloadAssetAttempt(\n          download,\n          destinationPath,\n          destinationRelativePath,\n          tempPath,\n          onChunk,\n        );\n      } catch (error) {\n        lastError = error;\n\n        if (isNoSpaceError(error)) {\n          await unlink(tempPath).catch(() => undefined);\n          this.options.emitLog(\"error\", \"asset_download_storage_failed\", {\n            asset_key: download.assetKey,\n            url: download.request.url,\n          });\n          throw new StorageLimitError(`Disk is full while downloading ${download.assetKey}.`, {\n            cause: error,\n          });\n        }\n\n        const retryable = isRetryableDownloadError(error);\n        if (!retryable) {\n          await unlink(tempPath).catch(() => undefined);\n          throw error;\n        }\n\n        if (attempt === TOTAL_DOWNLOAD_ATTEMPTS - 1) {\n          this.options.emitLog(\"warn\", \"asset_download_retry_exhausted\", {\n            asset_key: download.assetKey,\n            attempt: attempt + 1,\n            partial_path: tempPath,\n          });\n          break;\n        }\n\n        const delayMs = calculateRetryDelay(attempt);\n        this.options.emitLog(\"warn\", \"asset_download_retry_scheduled\", {\n          asset_key: download.assetKey,\n          attempt: attempt + 1,\n          retry_delay_ms: delayMs,\n        });\n        await this.deps.sleep(delayMs);\n      }\n    }\n\n    throw lastError;\n  }\n\n  async ensureFileSpaceCommit(): Promise<void> {\n    const stats = await this.deps.statfs(this.storageRoot);\n    const availableBytes = Number(stats.bavail) * Number(stats.bsize);\n    const reserve = effectiveReserveFreeBytes(this.options.reserveFreeBytes);\n    if (availableBytes < reserve) {\n      throw new StorageLimitError(`Committing download would violate reserveFreeBytes ${reserve}.`);\n    }\n  }\n\n  private partialDownloadBytes(download: QueuedAssetDownloadTarget): number {\n    const tempPath = this.partialDownloadPath(download);\n    return existsSync(tempPath) ? statSync(tempPath).size : 0;\n  }\n\n  private async downloadAssetAttempt(\n    download: AssetDownloadTarget,\n    destinationPath: string,\n    destinationRelativePath: string,\n    tempPath: string,\n    onChunk: (chunkBytes: number) => void,\n  ): Promise<AssetDownloadResult> {\n    let restartedWithoutRange = false;\n\n    for (;;) {\n      const resumeSize = existsSync(tempPath) ? statSync(tempPath).size : 0;\n      const headers = new Headers(download.request.headers);\n      if (resumeSize > 0) {\n        headers.set(\"range\", `bytes=${resumeSize}-`);\n      }\n\n      const response = await this.deps.fetchImpl(download.request.url, {\n        method: download.request.method ?? \"GET\",\n        headers,\n      });\n\n      if (resumeSize > 0 && response.status === 416) {\n        if (restartedWithoutRange) {\n          throw createDownloadError(\n            `Server rejected range request for ${download.assetKey}.`,\n            false,\n            response.status,\n          );\n        }\n\n        restartedWithoutRange = true;\n        await unlink(tempPath).catch(() => undefined);\n        this.options.emitLog(\"debug\", \"asset_download_range_restart\", {\n          asset_key: download.assetKey,\n          resumed_bytes: resumeSize,\n          response_status: response.status,\n          content_range: response.headers.get(\"content-range\"),\n        });\n        continue;\n      }\n\n      if (!response.ok || !response.body) {\n        this.options.emitLog(\"warn\", \"asset_download_rejected\", {\n          asset_key: download.assetKey,\n          status: response.status,\n          status_text: response.statusText,\n          url: download.request.url,\n        });\n        throw createDownloadError(\n          `Download failed for ${download.assetKey}: ${response.status} ${response.statusText}`,\n          isRetryableStatus(response.status),\n          response.status,\n        );\n      }\n\n      if (\n        resumeSize > 0 &&\n        (response.status !== 206 ||\n          parseContentRangeStart(response.headers.get(\"content-range\")) !== resumeSize)\n      ) {\n        if (restartedWithoutRange) {\n          throw createDownloadError(\n            `Server did not honor range request for ${download.assetKey}.`,\n            false,\n            response.status,\n          );\n        }\n\n        restartedWithoutRange = true;\n        await unlink(tempPath).catch(() => undefined);\n        this.options.emitLog(\"debug\", \"asset_download_range_restart\", {\n          asset_key: download.assetKey,\n          resumed_bytes: resumeSize,\n          response_status: response.status,\n          content_range: response.headers.get(\"content-range\"),\n        });\n        continue;\n      }\n\n      const nodeStream = Readable.fromWeb(\n        response.body as unknown as NodeReadableStream<Uint8Array>,\n      );\n      const writeStream = createWriteStream(tempPath, { flags: resumeSize > 0 ? \"a\" : \"w\" });\n\n      nodeStream.on(\"data\", (chunk) => {\n        onChunk((chunk as Buffer).byteLength);\n      });\n\n      try {\n        await pipeline(nodeStream, writeStream);\n      } catch (error) {\n        throw wrapRetryableDownloadError(error);\n      }\n\n      await this.ensureFileSpaceCommit();\n      mkdirSync(dirname(destinationPath), { recursive: true });\n      rmSync(destinationPath, { force: true });\n      renameSync(tempPath, destinationPath);\n      return {\n        relativePath: destinationRelativePath,\n        fallbackMimeType: normalizeResponseMimeType(response.headers.get(\"content-type\")),\n      };\n    }\n  }\n}\n\nfunction sanitizeSegment(segment: string): string {\n  return encodeURIComponent(segment);\n}\n\nfunction pruneEmptyParents(pathToFile: string, storageRoot: string): void {\n  let current = dirname(pathToFile);\n  while (current.startsWith(storageRoot) && current !== storageRoot) {\n    if (existsSync(current) && readdirSync(current).length === 0) {\n      rmSync(current, { recursive: true, force: true });\n      current = dirname(current);\n      continue;\n    }\n    break;\n  }\n}\n\nfunction listFilesRecursively(directory: string): string[] {\n  if (!existsSync(directory)) {\n    return [];\n  }\n\n  const stats = statSync(directory);\n  if (stats.isFile()) {\n    return [directory];\n  }\n\n  return readdirSync(directory).flatMap((entry) => listFilesRecursively(join(directory, entry)));\n}\n\nconst TOTAL_DOWNLOAD_ATTEMPTS = 4;\nconst RETRYABLE_STATUS_CODES = new Set([408, 429, 500, 502, 503, 504]);\nconst RETRYABLE_ERROR_CODES = new Set([\n  \"ECONNRESET\",\n  \"ECONNREFUSED\",\n  \"EHOSTUNREACH\",\n  \"ENETUNREACH\",\n  \"ENOTFOUND\",\n  \"ETIMEDOUT\",\n  \"UND_ERR_CONNECT_TIMEOUT\",\n  \"UND_ERR_HEADERS_TIMEOUT\",\n  \"UND_ERR_SOCKET\",\n]);\n\ntype RetryableDownloadError = Error & {\n  retryable?: boolean;\n  status?: number;\n};\n\nfunction calculateRetryDelay(attempt: number): number {\n  const baseDelay = 1000 * Math.pow(2, attempt);\n  const jitter = Math.floor(baseDelay * 0.25 * Math.random());\n  return baseDelay + jitter;\n}\n\nfunction createDownloadError(\n  message: string,\n  retryable: boolean,\n  status?: number,\n  cause?: unknown,\n): RetryableDownloadError {\n  const error = new SyncFailureError(\n    message,\n    cause ? { cause } : undefined,\n  ) as RetryableDownloadError;\n  error.retryable = retryable;\n  error.status = status;\n  return error;\n}\n\nfunction wrapRetryableDownloadError(error: unknown): RetryableDownloadError {\n  if (error instanceof SyncFailureError) {\n    return error as RetryableDownloadError;\n  }\n\n  if (error instanceof Error) {\n    const wrapped = new SyncFailureError(error.message, { cause: error }) as RetryableDownloadError;\n    wrapped.retryable = hasRetryableDownloadSignal(error);\n    return wrapped;\n  }\n\n  const wrapped = new SyncFailureError(String(error)) as RetryableDownloadError;\n  wrapped.retryable = false;\n  return wrapped;\n}\n\nfunction isRetryableDownloadError(error: unknown): boolean {\n  if (!(error instanceof Error)) {\n    return false;\n  }\n\n  const candidate = error as RetryableDownloadError;\n  if (candidate.retryable !== undefined) {\n    return candidate.retryable;\n  }\n\n  return hasRetryableDownloadSignal(error);\n}\n\nfunction isRetryableStatus(status: number): boolean {\n  return RETRYABLE_STATUS_CODES.has(status);\n}\n\nfunction isRetryableErrorCode(code: string | undefined): boolean {\n  return code !== undefined && RETRYABLE_ERROR_CODES.has(code);\n}\n\nfunction isRetryableMessage(message: string): boolean {\n  const value = message.toLowerCase();\n  return (\n    value.includes(\"aborted\") ||\n    value.includes(\"connection\") ||\n    value.includes(\"network\") ||\n    value.includes(\"reset\") ||\n    value.includes(\"socket\") ||\n    value.includes(\"terminated\") ||\n    value.includes(\"timeout\")\n  );\n}\n\nfunction hasRetryableDownloadSignal(error: Error): boolean {\n  return collectErrorChain(error).some(\n    (entry) =>\n      isRetryableErrorCode((entry as NodeJS.ErrnoException).code) ||\n      isRetryableMessage(entry.message),\n  );\n}\n\nfunction collectErrorChain(error: Error): Error[] {\n  const chain: Error[] = [];\n  let current: unknown = error;\n\n  while (current instanceof Error && !chain.includes(current)) {\n    chain.push(current);\n    current = current.cause;\n  }\n\n  return chain;\n}\n\nfunction normalizeResponseMimeType(contentType: string | null): string | null {\n  const value = contentType?.trim();\n  return value && value.length > 0 ? value : null;\n}\n\nfunction parseContentRangeStart(contentRange: string | null): number | null {\n  if (!contentRange) {\n    return null;\n  }\n\n  const match = contentRange.match(/^bytes (\\d+)-\\d+\\/(?:\\d+|\\*)$/i);\n  return match?.[1] ? Number.parseInt(match[1], 10) : null;\n}\n"],"mappings":"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"}

package/dist/main/asset-download.d.cts

@@ -0,0 +1,12 @@
+//#region src/main/asset-download.d.ts
+/** When `reserveFreeBytes` is omitted, preserve this much free space on the cache volume (1 GiB). */
+declare const DEFAULT_RESERVE_FREE_BYTES: number;
+/**
+ * Effective minimum free bytes: explicit option, or {@link DEFAULT_RESERVE_FREE_BYTES} when omitted.
+ * `0` means no reserved headroom.
+ * @internal
+ */
+declare function effectiveReserveFreeBytes(explicit: number | undefined): number;
+//#endregion
+export { DEFAULT_RESERVE_FREE_BYTES, effectiveReserveFreeBytes };
+//# sourceMappingURL=asset-download.d.cts.map

package/dist/main/asset-download.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-download.d.cts","names":[],"sources":["../../src/main/asset-download.ts"],"mappings":";AAkBA;AAAA,cAAa,0BAAA;;;;AAOb;;iBAAgB,yBAAA,CAA0B,QAAA"}

package/dist/main/asset-download.d.ts

@@ -0,0 +1,12 @@
+//#region src/main/asset-download.d.ts
+/** When `reserveFreeBytes` is omitted, preserve this much free space on the cache volume (1 GiB). */
+declare const DEFAULT_RESERVE_FREE_BYTES: number;
+/**
+ * Effective minimum free bytes: explicit option, or {@link DEFAULT_RESERVE_FREE_BYTES} when omitted.
+ * `0` means no reserved headroom.
+ * @internal
+ */
+declare function effectiveReserveFreeBytes(explicit: number | undefined): number;
+//#endregion
+export { DEFAULT_RESERVE_FREE_BYTES, effectiveReserveFreeBytes };
+//# sourceMappingURL=asset-download.d.ts.map

package/dist/main/asset-download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-download.d.ts","names":[],"sources":["../../src/main/asset-download.ts"],"mappings":";AAkBA;AAAA,cAAa,0BAAA;;;;AAOb;;iBAAgB,yBAAA,CAA0B,QAAA"}