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

@@ -19,6 +19,7 @@ export interface Hasher {
 export interface UrlResolver {
 	resolve: (id: string) => string;
 	readonly cspResources: Array<string>;
+	readonly urls: Array<string>;
 }
 
 export interface FontFileContentResolver {
@@ -87,3 +88,16 @@ export interface FontResolver {
 	) => Promise<Array<unifont.FontFaceData>>;
 	listFonts: (options: { provider: FontProvider }) => Promise<string[] | undefined>;
 }
+
+export interface RuntimeFontFetcher {
+	/**
+	 * @param url
+	 * URL obtained from `fontData` and provided by the user. Can look like
+	 * `/_astro/fonts/<hash>.<ext>` or be a full URL when using assetsPrefix.
+	 *
+	 * @param requestUrl
+	 * The current request URL. It can be used to construct a full URL to the
+	 * font file, for example in SSR.
+	 */
+	fetch: (url: string, requestUrl: URL | undefined) => Promise<ArrayBuffer | null>;
+}

packages/astro/src/assets/fonts/infra/build-url-resolver.ts

@@ -6,6 +6,7 @@ import type { UrlResolver } from '../definitions.js';
 
 export class BuildUrlResolver implements UrlResolver {
 	readonly #resources = new Set<string>();
+	readonly #urls = new Set<string>();
 	readonly #base: string;
 	readonly #assetsPrefix: AssetsPrefix;
 	readonly #searchParams: URLSearchParams;
@@ -43,10 +44,16 @@ export class BuildUrlResolver implements UrlResolver {
 			url.searchParams.set(key, value);
 		});
 
-		return stringifyPlaceholderURL(url);
+		const result = stringifyPlaceholderURL(url);
+		this.#urls.add(result);
+		return result;
 	}
 
 	get cspResources(): Array<string> {
 		return Array.from(this.#resources);
 	}
+
+	get urls(): Array<string> {
+		return Array.from(this.#urls);
+	}
 }

packages/astro/src/assets/fonts/infra/dev-url-resolver.ts

@@ -3,6 +3,7 @@ import { createPlaceholderURL, stringifyPlaceholderURL } from '../../utils/url.j
 import type { UrlResolver } from '../definitions.js';
 
 export class DevUrlResolver implements UrlResolver {
+	readonly #urls = new Set<string>();
 	#resolved = false;
 	readonly #base: string;
 	readonly #searchParams: URLSearchParams;
@@ -28,10 +29,16 @@ export class DevUrlResolver implements UrlResolver {
 			url.searchParams.set(key, value);
 		});
 
-		return stringifyPlaceholderURL(url);
+		const result = stringifyPlaceholderURL(url);
+		this.#urls.add(result);
+		return result;
 	}
 
 	get cspResources(): Array<string> {
 		return this.#resolved ? ["'self'"] : [];
 	}
+
+	get urls(): Array<string> {
+		return Array.from(this.#urls);
+	}
 }

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

@@ -0,0 +1,49 @@
+import type { AddressInfo } from 'node:net';
+import type { RuntimeFontFetcher } from '../definitions.js';
+
+/**
+ * In development, font files are served through a Vite middleware.
+ * During prerendering, a temporary Node HTTP server is started to
+ * serve font files.
+ *
+ * We send request to the provided server address. `requestUrl` on
+ * `fetch` is not implemented because we have the information from
+ * within the Vite plugin already.
+ */
+export class RemoteRuntimeFontFetcher implements RuntimeFontFetcher {
+	#urls: Set<string>;
+	#address: AddressInfo | null;
+	#fetch: typeof globalThis.fetch;
+
+	constructor({
+		urls,
+		address,
+		fetch,
+	}: {
+		urls: Set<string>;
+		address: AddressInfo | null;
+		fetch: typeof globalThis.fetch;
+	}) {
+		this.#urls = urls;
+		this.#address = address;
+		this.#fetch = fetch;
+	}
+
+	async fetch(url: string): Promise<ArrayBuffer | null> {
+		if (!this.#urls.has(url)) {
+			return null;
+		}
+		if (!this.#address) {
+			throw new Error('Server address unavailable, this should not happen. Open an issue.');
+		}
+		// assetsPrefix
+		if (!url.startsWith('/')) {
+			url = new URL(url).pathname;
+		}
+		const host =
+			this.#address.family === 'IPv6' ? `[${this.#address.address}]` : this.#address.address;
+		return this.#fetch(`http://${host}:${this.#address.port}${url}`).then((res) =>
+			res.arrayBuffer(),
+		);
+	}
+}

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

@@ -0,0 +1,38 @@
+import type { RuntimeFontFetcher } from '../definitions.js';
+import { MissingGetFontBufferRequestUrl } from '../../../core/errors/errors-data.js';
+import { AstroError } from '../../../core/errors/errors.js';
+
+/**
+ * During SSR, we don't know ahead of time where the server is located.
+ * We rely on `requestUrl` (provided by the user) to construct the URL.
+ */
+export class SsrRuntimeFontFetcher implements RuntimeFontFetcher {
+	#urls: Set<string>;
+	#fetch: typeof globalThis.fetch;
+
+	constructor({
+		urls,
+		fetch,
+	}: {
+		urls: Set<string>;
+		fetch: typeof globalThis.fetch;
+	}) {
+		this.#urls = urls;
+		this.#fetch = fetch;
+	}
+
+	async fetch(url: string, requestUrl: URL | undefined): Promise<ArrayBuffer | null> {
+		if (!this.#urls.has(url)) {
+			return null;
+		}
+		// assetsPrefix
+		if (!url.startsWith('/')) {
+			return this.#fetch(url).then((res) => res.arrayBuffer());
+		}
+		// We need the request URL to call the current server
+		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);