@lupinum/nuxt-pdf 0.3.0

package/dist/runtime/server/assets/remote.js

@@ -0,0 +1,234 @@
+import { Buffer } from "node:buffer";
+import {
+  PDF_ASSET_ERROR_CODES,
+  PdfAssetError
+} from "./errors.js";
+export const DEFAULT_REMOTE_TIMEOUT_MS = 1e4;
+export const MAX_REMOTE_REDIRECTS = 3;
+export const redactUrl = (url) => {
+  try {
+    const parsed = new URL(url);
+    return `${parsed.protocol}//${parsed.host}/\u2026`;
+  } catch {
+    return "<redacted-url>";
+  }
+};
+const configError = (message) => {
+  throw new TypeError(message);
+};
+const blocked = (message, cause) => {
+  throw new PdfAssetError(PDF_ASSET_ERROR_CODES.Blocked, message, { cause });
+};
+const limitExceeded = (message) => {
+  throw new PdfAssetError(PDF_ASSET_ERROR_CODES.LimitExceeded, message);
+};
+const positiveSafeInteger = (value, fallback, name) => {
+  if (value === void 0) return fallback;
+  if (!Number.isSafeInteger(value) || value < 1) {
+    return configError(`pdf.remote.${name} must be a positive safe integer.`);
+  }
+  return value;
+};
+const parseAllowEntry = (entry) => {
+  if (typeof entry !== "string" || entry.trim() === "") {
+    return configError("pdf.remote.allow entries must be non-empty https://host/path/ prefixes.");
+  }
+  let parsed;
+  try {
+    parsed = new URL(entry);
+  } catch {
+    return configError("A pdf.remote.allow entry is not a valid URL prefix.");
+  }
+  if (parsed.protocol !== "https:") {
+    return configError("pdf.remote.allow entries must use the https:// scheme.");
+  }
+  if (parsed.username !== "" || parsed.password !== "") {
+    return configError("pdf.remote.allow entries must not embed credentials.");
+  }
+  if (parsed.search !== "" || parsed.hash !== "") {
+    return configError("pdf.remote.allow entries must not include a query or fragment.");
+  }
+  if (parsed.hostname === "" || parsed.hostname.includes("*")) {
+    return configError("pdf.remote.allow entries must name one exact host without wildcards.");
+  }
+  if (!parsed.pathname.endsWith("/")) {
+    return configError("pdf.remote.allow entries must end with a path slash (/).");
+  }
+  return Object.freeze({
+    host: parsed.hostname.toLowerCase(),
+    port: parsed.port,
+    pathPrefix: parsed.pathname
+  });
+};
+export const normalizeRemoteAssetPolicy = (options) => {
+  if (options === void 0) return void 0;
+  if (options === null || typeof options !== "object") {
+    return configError("pdf.remote must be an object with an allow list.");
+  }
+  if (!Array.isArray(options.allow) || options.allow.length === 0) {
+    return configError("pdf.remote.allow must list at least one https://host/path/ prefix.");
+  }
+  const unknownKey = Object.keys(options).find((key) => key !== "allow" && key !== "timeoutMs");
+  if (unknownKey) {
+    return configError(`pdf.remote.${unknownKey} is not supported.`);
+  }
+  return Object.freeze({
+    allow: Object.freeze(options.allow.map(parseAllowEntry)),
+    timeoutMs: positiveSafeInteger(
+      options.timeoutMs,
+      DEFAULT_REMOTE_TIMEOUT_MS,
+      "timeoutMs"
+    )
+  });
+};
+export const matchesAllowlist = (url, policy) => {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== "https:") return false;
+  if (parsed.username !== "" || parsed.password !== "") return false;
+  if (parsed.hash !== "") return false;
+  const hostname = parsed.hostname.toLowerCase();
+  return policy.allow.some(
+    (rule) => hostname === rule.host && parsed.port === rule.port && parsed.pathname.startsWith(rule.pathPrefix)
+  );
+};
+export const createRemoteRequestState = (limits) => ({ limits, active: 0, requests: 0, waiters: [] });
+const acquireRequestSlot = async (state) => {
+  state.limits.deadline.check();
+  if (state.limits.abortController.signal.aborted) {
+    throw state.limits.abortController.signal.reason;
+  }
+  state.requests += 1;
+  if (state.requests > state.limits.maxRemoteRequests) {
+    return limitExceeded(
+      `PDF remote requests exceed pdf.limits.maxRemoteRequests (${state.limits.maxRemoteRequests}).`
+    );
+  }
+  if (state.active < state.limits.maxRemoteConcurrency) {
+    state.active += 1;
+    return;
+  }
+  await new Promise((resolve, reject) => {
+    const signal = state.limits.abortController.signal;
+    const waiter = {
+      reject,
+      resolve: () => {
+        signal.removeEventListener("abort", onAbort);
+        state.active += 1;
+        resolve();
+      }
+    };
+    const onAbort = () => {
+      const index = state.waiters.indexOf(waiter);
+      if (index >= 0) state.waiters.splice(index, 1);
+      reject(signal.reason);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    state.waiters.push(waiter);
+  });
+};
+const releaseRequestSlot = (state) => {
+  state.active -= 1;
+  state.waiters.shift()?.resolve();
+};
+const readCapped = async (response, maxBytes, controller) => {
+  const body = response.body;
+  if (!body) return Buffer.alloc(0);
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of body) {
+    total += chunk.byteLength;
+    if (total > maxBytes) {
+      controller.abort();
+      return limitExceeded(
+        `A remote PDF image exceeds pdf.limits.maxImageBytes (${maxBytes}).`
+      );
+    }
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks, total);
+};
+const fetchOnce = async (url, policy, maxBytes, state) => {
+  await acquireRequestSlot(state);
+  const controller = new AbortController();
+  const renderSignal = state.limits.abortController.signal;
+  const abortFromRender = () => controller.abort(renderSignal.reason);
+  renderSignal.addEventListener("abort", abortFromRender, { once: true });
+  let timedOut = false;
+  const remaining = state.limits.deadline.remainingMs();
+  const timeoutMs = Math.min(policy.timeoutMs, Math.max(1, Math.ceil(remaining)));
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      redirect: "manual",
+      signal: controller.signal,
+      credentials: "omit"
+    });
+    if (response.status >= 300 && response.status < 400) {
+      await response.body?.cancel();
+      const location = response.headers.get("location");
+      if (!location) {
+        return blocked(`The remote PDF image from ${redactUrl(url)} returned a redirect without a Location.`);
+      }
+      return { redirectTo: new URL(location, url).toString() };
+    }
+    if (response.status !== 200) {
+      await response.body?.cancel();
+      return blocked(`The remote PDF image from ${redactUrl(url)} returned HTTP ${response.status}.`);
+    }
+    const declaredLength = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+      controller.abort();
+      return limitExceeded(
+        `A remote PDF image exceeds pdf.limits.maxImageBytes (${maxBytes}).`
+      );
+    }
+    return { buffer: await readCapped(response, maxBytes, controller) };
+  } catch (error) {
+    if (error instanceof PdfAssetError) throw error;
+    if (renderSignal.aborted) throw renderSignal.reason;
+    if (timedOut) {
+      if (state.limits.deadline.remainingMs() <= 0) {
+        state.limits.deadline.check();
+      }
+      return blocked(`The remote PDF image from ${redactUrl(url)} timed out after ${timeoutMs}ms.`);
+    }
+    return blocked(`The remote PDF image from ${redactUrl(url)} could not be fetched.`, error);
+  } finally {
+    clearTimeout(timer);
+    renderSignal.removeEventListener("abort", abortFromRender);
+    releaseRequestSlot(state);
+  }
+};
+const fetchResolved = async (initialUrl, policy, maxBytes, state) => {
+  let url = initialUrl;
+  for (let redirects = 0; redirects <= MAX_REMOTE_REDIRECTS; redirects += 1) {
+    if (!matchesAllowlist(url, policy)) {
+      return blocked(
+        `The remote PDF image from ${redactUrl(url)} is not permitted by pdf.remote.allow.`
+      );
+    }
+    const outcome = await fetchOnce(url, policy, maxBytes, state);
+    if ("buffer" in outcome) return outcome.buffer;
+    url = outcome.redirectTo;
+  }
+  return blocked(
+    `The remote PDF image from ${redactUrl(initialUrl)} exceeded the ${MAX_REMOTE_REDIRECTS}-redirect limit.`
+  );
+};
+export const fetchRemoteResource = (url, options) => {
+  const { policy, maxBytes, state, inflight } = options;
+  const existing = inflight?.get(url);
+  if (existing) return existing;
+  const promise = fetchResolved(url, policy, maxBytes, state);
+  inflight?.set(url, promise);
+  return promise;
+};

package/dist/runtime/server/assets/resolve-asset.d.ts

@@ -0,0 +1,53 @@
+import { Buffer } from 'node:buffer';
+import type { PdfDocumentNode } from '../../renderer/index.js';
+import { type RemoteAssetPolicy, type RemoteRequestState } from './remote.js';
+import { type RenderLimits } from '../render-limits.js';
+export { PDF_ASSET_ERROR_CODES, PdfAssetError, type PdfAssetErrorCode, } from './errors.js';
+export type PdfImageFormat = 'jpg' | 'png';
+export type PdfImageAsset = Readonly<{
+    data: Uint8Array;
+    format: PdfImageFormat;
+}>;
+export type LoadedPdfImageAsset = PdfImageAsset & Readonly<{
+    key: string;
+}>;
+export type PdfImageAssetMap = Readonly<Record<string, PdfImageAsset>>;
+export interface LoadPdfImageAssetOptions {
+    roots: readonly string[];
+    maxBytes?: number;
+    maxPixels?: number;
+}
+export interface ResolvePdfImageAssetsOptions {
+    assets: PdfImageAssetMap;
+    limits?: RenderLimits;
+    remote?: RemoteAssetPolicy;
+    /**
+     * Mutable accounting shared by every image-admission pass in one render.
+     * Multi-pass documents re-render their Vue tree between layout passes; this
+     * state keeps deduplication and byte/request budgets render-wide.
+     */
+    state?: PdfImageResolutionState;
+}
+type ImageBudgetState = {
+    bytes: number;
+    pixels: number;
+};
+type ImageResolutionCache = Map<unknown, Promise<Buffer>>;
+export interface PdfImageResolutionState {
+    readonly budget: ImageBudgetState;
+    readonly inflight: Map<string, Promise<Buffer>>;
+    readonly remote: RemoteRequestState;
+    readonly resolved: ImageResolutionCache;
+}
+/**
+ * Loads and validates one local image while the Nuxt module still has access to
+ * source files. Generated server code should store the returned bytes under
+ * `key`; rendering must not retain the absolute source path.
+ */
+export declare const loadPdfImageAsset: (relativePath: string, options: LoadPdfImageAssetOptions) => Promise<LoadedPdfImageAsset>;
+export declare const createPdfImageResolutionState: (limits: RenderLimits) => PdfImageResolutionState;
+/**
+ * Resolves every image on the canonical renderer tree before layout. The pass
+ * is atomic: no image prop changes unless all image sources validate.
+ */
+export declare const resolvePdfImageAssets: (document: PdfDocumentNode, options: ResolvePdfImageAssetsOptions) => Promise<PdfDocumentNode>;