feat(fonts): experimental_getFontFileURL()

.changeset/wacky-carrots-sin.md

@@ -0,0 +1,64 @@
+---
+'astro': minor
+---
+
+Adds a new `experimental_getFontBuffer()` method to retrieve font file buffers when using the Fonts API
+
+The `fontData` object exported from `astro:assets` was introduced to provide low-level access to font family data for advanced usage. One of the goals of this API was to be able to retrieve buffers using URLs. However, it turned out to be impractical, especially during prerendering.
+
+Astro now exports a new `experimental_getFontBuffer()` helper function from `astro:assets` to retrieve font file buffers from URL obtained via `fontData`. For example, when using [satori](https://github.com/vercel/satori) to generate Open Graph images:
+
+```diff
+// src/pages/og.png.ts
+
+import type { APIRoute } from "astro";
+-import { fontData } from "astro:assets";
++import { fontData, experimental_getFontBuffer } from "astro:assets";
+-import { outDir } from "astro:config/server";
+-import { readFile } from "node:fs/promises";
+import satori from "satori";
+import { html } from "satori-html";
+import sharp from "sharp";
+
+export const GET: APIRoute = async (context) => {
+  const fontPath = fontData["--font-roboto"][0]?.src[0]?.url;
+
+  if (fontPath === undefined) {
+    throw new Error("Cannot find the font path.");
+  }
+
+-  const data = import.meta.env.DEV
+-    ? await fetch(new URL(fontPath, context.url.origin)).then(async (res) => res.arrayBuffer())
+-    : await readFile(new URL(`.${fontPath}`, outDir));
++    const data = await experimental_getFontBuffer(fontPath, context.url)
+
+  const svg = await satori(
+    html`<div style="color: black;">hello, world</div>`,
+    {
+      width: 600,
+      height: 400,
+      fonts: [
+        {
+          name: "Roboto",
+          data,
+          weight: 400,
+          style: "normal",
+        },
+      ],
+    },
+  );
+
+  const pngBuffer = await sharp(Buffer.from(svg))
+    .resize(600, 400)
+    .png()
+    .toBuffer();
+
+  return new Response(new Uint8Array(pngBuffer), {
+    headers: {
+      "Content-Type": "image/png",
+    },
+  });
+};
+```
+
+See the [Fonts API documentation](https://docs.astro.build/en/guides/fonts/#accessing-font-data-programmatically) for more information.

packages/astro/client.d.ts

@@ -60,6 +60,7 @@ declare module 'astro:assets' {
 		import('astro:assets').CssVariable,
 		Array<import('astro:assets').FontData>
 	>;
+	export const experimental_getFontBuffer: typeof import('./dist/assets/fonts/runtime.js').experimental_getFontBuffer;
 
 	type ImgAttributes = import('./dist/type-utils.js').WithRequired<
 		Omit<import('./types').HTMLAttributes<'img'>, 'src' | 'width' | 'height'>,

packages/astro/dev-only.d.ts

@@ -11,6 +11,10 @@ declare module 'virtual:astro:assets/fonts/internal' {
 	export const fontDataByCssVariable: import('./src/assets/fonts/types.js').FontDataByCssVariable;
 }
 
+declare module 'virtual:astro:assets/fonts/runtime/font-fetcher' {
+	export const runtimeFontFetcher: import('./src/assets/fonts/definitions.js').RuntimeFontFetcher;
+}
+
 declare module 'virtual:astro:adapter-config/client' {
 	export const internalFetchHeaders: Record<string, string>;
 }

packages/astro/src/assets/fonts/constants.ts

@@ -16,6 +16,11 @@ export const RESOLVED_VIRTUAL_MODULE_ID = '\0' + VIRTUAL_MODULE_ID;
 export const RUNTIME_VIRTUAL_MODULE_ID = 'virtual:astro:assets/fonts/runtime';
 export const RESOLVED_RUNTIME_VIRTUAL_MODULE_ID = '\0' + RUNTIME_VIRTUAL_MODULE_ID;
 
+export const RUNTIME_FONT_FETCHER_VIRTUAL_MODULE_ID =
+	'virtual:astro:assets/fonts/runtime/font-fetcher';
+export const RESOLVED_RUNTIME_FONT_FETCHER_VIRTUAL_MODULE_ID =
+	'\0' + RUNTIME_FONT_FETCHER_VIRTUAL_MODULE_ID;
+
 export const ASSETS_DIR = 'fonts';
 export const CACHE_DIR = './fonts/';
 

packages/astro/src/assets/fonts/core/create-get-font-buffer.ts

@@ -0,0 +1,22 @@
+import { AstroError, AstroErrorData } from '../../../core/errors/index.js';
+import type { RuntimeFontFetcher } from './../definitions.js';
+
+export function createGetFontBuffer(runtimeFontFetcher: RuntimeFontFetcher) {
+	return async function getFontBuffer(url: string, requestUrl?: URL): Promise<ArrayBuffer> {
+		try {
+			const buffer = await runtimeFontFetcher.fetch(url, requestUrl);
+			if (buffer === null) {
+				throw new Error('Not found');
+			}
+			return buffer;
+		} catch (cause) {
+			throw new AstroError(
+				{
+					...AstroErrorData.FontBufferNotFound,
+					message: AstroErrorData.FontBufferNotFound.message(url),
+				},
+				{ cause },
+			);
+		}
+	};
+}

packages/astro/src/assets/fonts/core/font-file-middleware.ts

@@ -0,0 +1,82 @@
+import type { AstroLogger } from '../../../core/logger/core.js';
+import type { FontFetcher, FontTypeExtractor } from '../definitions.js';
+import type { FontFileById } from '../types.js';
+import { isAstroError } from '../../../core/errors/errors.js';
+import { formatErrorMessage } from '../../../core/messages/runtime.js';
+import { collectErrorMetadata } from '../../../core/errors/dev/utils.js';
+import type { ServerResponse } from 'node:http';
+
+interface MinimalResponse {
+	setHeader: (name: string, value: string) => void;
+	end: (buffer?: Buffer) => void;
+	setStatusCode: (statusCode: number) => void;
+}
+
+interface Options {
+	url: string | undefined;
+	response: MinimalResponse;
+	next: () => void;
+	fontFetcher: FontFetcher | null;
+	fontTypeExtractor: FontTypeExtractor | null;
+	logger: AstroLogger;
+	fontFileById: FontFileById | null;
+}
+
+export function resToMinimalResponse(res: ServerResponse): MinimalResponse {
+	return {
+		setHeader: (...args) => res.setHeader(...args),
+		end: (...args) => res.end(...args),
+		setStatusCode: (statusCode) => {
+			res.statusCode = statusCode;
+		},
+	};
+}
+
+export async function fontFileMiddleware({
+	url: _url,
+	response,
+	next,
+	fontFetcher,
+	fontTypeExtractor,
+	logger,
+	fontFileById,
+}: Options): Promise<void> {
+	if (!fontFetcher || !fontTypeExtractor || !fontFileById) {
+		logger.debug('assets', 'Fonts dependencies should be initialized by now, skipping middleware.');
+		return next();
+	}
+	if (!_url) {
+		return next();
+	}
+	const url = new URL(_url, 'http://localhost');
+	const fontId = url.pathname.slice(1);
+	const fontData = fontFileById.get(fontId);
+	if (!fontData) {
+		return next();
+	}
+	// We don't want the request to be cached in dev because we cache it already internally,
+	// and it makes it easier to debug without needing hard refreshes
+	response.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0');
+	response.setHeader('Pragma', 'no-cache');
+	response.setHeader('Expires', '0');
+
+	try {
+		const buffer = await fontFetcher.fetch({ id: fontId, ...fontData });
+
+		response.setHeader('Content-Length', buffer.byteLength.toString());
+		response.setHeader('Content-Type', `font/${fontTypeExtractor.extract(fontId)}`);
+
+		response.setStatusCode(200);
+		response.end(buffer);
+	} catch (err) {
+		logger.error('assets', 'Cannot download font file');
+		if (isAstroError(err)) {
+			logger.error(
+				'SKIP_FORMAT',
+				formatErrorMessage(collectErrorMetadata(err), logger.level() === 'debug'),
+			);
+		}
+		response.setStatusCode(500);
+		response.end();
+	}
+}

packages/astro/src/assets/fonts/definitions.ts

@@ -87,3 +87,7 @@ export interface FontResolver {
 	) => Promise<Array<unifont.FontFaceData>>;
 	listFonts: (options: { provider: FontProvider }) => Promise<string[] | undefined>;
 }
+
+export interface RuntimeFontFetcher {
+	fetch: (url: string, requestUrl: URL | undefined) => Promise<ArrayBuffer | null>;
+}

packages/astro/src/assets/fonts/infra/build-runtime-font-fetcher.ts

@@ -0,0 +1,29 @@
+import type { RuntimeFontFetcher } from '../definitions.js';
+
+export class BuildRuntimeFontFetcher implements RuntimeFontFetcher {
+	#ids: Set<string>;
+	#port: number;
+	#fetch: typeof globalThis.fetch;
+
+	constructor({
+		ids,
+		port,
+		fetch,
+	}: {
+		ids: Set<string>;
+		port: number;
+		fetch: typeof globalThis.fetch;
+	}) {
+		this.#ids = ids;
+		this.#port = port;
+		this.#fetch = fetch;
+	}
+
+	async fetch(url: string): Promise<ArrayBuffer | null> {
+		const id = url.split('/').pop() ?? '';
+		if (!this.#ids.has(id)) {
+			return null;
+		}
+		return this.#fetch(`http://localhost:${this.#port}/${id}`).then((res) => res.arrayBuffer());
+	}
+}

packages/astro/src/assets/fonts/infra/dev-runtime-font-fetcher.ts

@@ -0,0 +1,35 @@
+import type { RuntimeFontFetcher } from '../definitions.js';
+
+export class DevRuntimeFontFetcher implements RuntimeFontFetcher {
+	#ids: Set<string>;
+	#port: number;
+	#base: string;
+	#fetch: typeof globalThis.fetch;
+
+	constructor({
+		ids,
+		port,
+		base,
+		fetch,
+	}: {
+		ids: Set<string>;
+		port: number;
+		base: string;
+		fetch: typeof globalThis.fetch;
+	}) {
+		this.#ids = ids;
+		this.#port = port;
+		this.#base = base;
+		this.#fetch = fetch;
+	}
+
+	async fetch(url: string): Promise<ArrayBuffer | null> {
+		const id = url.split('/').pop() ?? '';
+		if (!this.#ids.has(id)) {
+			return null;
+		}
+		return this.#fetch(`http://localhost:${this.#port}${this.#base}${id}`).then((res) =>
+			res.arrayBuffer(),
+		);
+	}
+}

packages/astro/src/assets/fonts/infra/ssr-runtime-font-fetcher.ts

@@ -0,0 +1,33 @@
+import type { RuntimeFontFetcher } from '../definitions.js';
+import { MissingGetFontBufferRequestUrl } from '../../../core/errors/errors-data.js';
+import { AstroError } from '../../../core/errors/errors.js';
+
+export class SsrRuntimeFontFetcher implements RuntimeFontFetcher {
+	#ids: Set<string>;
+	#fetch: typeof globalThis.fetch;
+
+	constructor({
+		ids,
+		fetch,
+	}: {
+		ids: Set<string>;
+		fetch: typeof globalThis.fetch;
+	}) {
+		this.#ids = ids;
+		this.#fetch = fetch;
+	}
+
+	async fetch(url: string, requestUrl: URL | undefined): Promise<ArrayBuffer | null> {
+		const id = url.split('/').pop() ?? '';
+		if (!this.#ids.has(id)) {
+			return null;
+		}
+		if (url.startsWith('http')) {
+			return this.#fetch(url).then((res) => res.arrayBuffer());
+		}
+		if (!requestUrl) {
+			throw new AstroError(MissingGetFontBufferRequestUrl);
+		}
+		return this.#fetch(`${requestUrl.origin}${url}`).then((res) => res.arrayBuffer());
+	}
+}

packages/astro/src/assets/fonts/runtime.ts

@@ -1,3 +1,6 @@
 import { fontDataByCssVariable } from 'virtual:astro:assets/fonts/internal';
+import { runtimeFontFetcher } from 'virtual:astro:assets/fonts/runtime/font-fetcher';
+import { createGetFontBuffer } from './core/create-get-font-buffer.js';
 
 export const fontData = fontDataByCssVariable;
+export const experimental_getFontBuffer = createGetFontBuffer(runtimeFontFetcher);