Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.
TypeScript accessibilityalternativecloudflarecloudflare-workersdesignfreefrontendopen-sourceradix-uireactremixweb-developmentwebflowwebsite-builderwebsite-developmentwebsiteswebstudio
import warnOnce from "warn-once";
import type { AssetRuntimeData } from "@webstudio-is/content-engine";
import type { Asset, AssetType } from "./schema/assets";
export const MIME_CATEGORIES = [
"image",
"video",
"audio",
"font",
"text",
"application",
] as const;
export type MimeCategory = (typeof MIME_CATEGORIES)[number];
export type AssetTextEditorLanguage =
| "plain"
| "css"
| "html"
| "javascript"
| "json"
| "markdown"
| "xml";
// Assets created before display filenames were persisted must still derive their
// basename from storage keys generated by Nano ID's historical 21-character format.
const legacyNanoIdLength = 21;
export const getFileExtension = (fileName: string): string | undefined => {
const extensionAt = fileName.lastIndexOf(".");
const separatorAt = Math.max(
fileName.lastIndexOf("/"),
fileName.lastIndexOf("\\")
);
if (extensionAt <= separatorAt + 1 || extensionAt === fileName.length - 1) {
return;
}
return fileName.slice(extensionAt + 1);
};
export const getFileNameParts = (fileName: string) => {
const extension = getFileExtension(fileName) ?? "";
const extensionLength = extension === "" ? 0 : extension.length + 1;
return {
basename: fileName.slice(0, fileName.length - extensionLength),
extension,
};
};
export const getAssetContentHash = async (
data: ArrayBuffer | ArrayBufferView<ArrayBuffer>
) => {
const digest = await crypto.subtle.digest("SHA-256", data);
return Array.from(new Uint8Array(digest), (byte) =>
byte.toString(16).padStart(2, "0")
).join("");
};
const contentHashPattern = /^[0-9a-f]{64}$/;
export const isContentHash = (value: unknown): value is string =>
typeof value === "string" && contentHashPattern.test(value);
export const createAssetContentRevision = ({
storageName,
updatedAt,
size,
contentHash,
}: {
storageName: string;
updatedAt: string;
size: number;
contentHash?: string | null;
}) =>
isContentHash(contentHash)
? `sha256:${contentHash}`
: `file:${encodeURIComponent(storageName)}:${updatedAt}:${size}`;
export type ParsedAssetName = {
basename: string;
hash: string;
ext: string;
};
export const parseAssetName = (assetName: string): ParsedAssetName => {
const { basename, extension: ext } = getFileNameParts(assetName);
let name = basename;
let hash = "";
let separatorAt = name.length - legacyNanoIdLength - 1;
if (separatorAt < 0 || name[separatorAt] !== "_") {
// Support older storage suffixes that predate the Nano ID format.
separatorAt = name.lastIndexOf("_");
}
if (separatorAt > -1) {
hash = name.slice(separatorAt + 1);
name = name.slice(0, separatorAt);
}
return { basename: name, hash, ext };
};
type AssetName = {
name: string;
filename?: string | null;
};
export const getAssetDisplayNameParts = (asset: AssetName) => {
const { basename, ext } = parseAssetName(asset.name);
return { basename: asset.filename ?? basename, ext };
};
export const formatAssetName = (asset: AssetName) => {
const { basename, ext } = getAssetDisplayNameParts(asset);
return `${basename}${ext === "" ? "" : `.${ext}`}`;
};
type MimeType = `${MimeCategory}/${string}`;
type BinaryMimeType = `${Exclude<MimeCategory, "text">}/${string}`;
const binaryFile = <Mime extends BinaryMimeType>(mimeType: Mime) =>
({ mimeType, textEditor: false }) as const;
const textFile = <
Mime extends MimeType,
Language extends AssetTextEditorLanguage,
>(
mimeType: Mime,
textEditor: Language
) => ({ mimeType, textEditor }) as const;
/**
* Central registry of allowed file types, extensions, and MIME types
* for asset uploads and serving.
*
* IMPORTANT: For images, we only support formats that Cloudflare Image Resizing can process.
* Supported by Cloudflare: JPEG, PNG, GIF, WebP, SVG, AVIF
* See: https://developers.cloudflare.com/images/image-resizing/format-limitations/
*
* Other formats (BMP, ICO, TIFF) are allowed for upload but served as-is without optimization.
*/
const assetFileTypes = {
// Documents
pdf: binaryFile("application/pdf"),
doc: binaryFile("application/msword"),
docx: binaryFile(
"application/vnd.openxmlformats-officedocument.wordprocessingml.document"
),
xls: binaryFile("application/vnd.ms-excel"),
xlsx: binaryFile(
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
),
csv: textFile("text/csv", "plain"),
ppt: binaryFile("application/vnd.ms-powerpoint"),
pptx: binaryFile(
"application/vnd.openxmlformats-officedocument.presentationml.presentation"
),
// Code
txt: textFile("text/plain", "plain"),
md: textFile("text/markdown", "markdown"),
mdx: textFile("text/mdx", "markdown"),
js: textFile("text/javascript", "javascript"),
mjs: textFile("text/javascript", "javascript"),
css: textFile("text/css", "css"),
json: textFile("application/json", "json"),
html: textFile("text/html", "html"),
xml: textFile("application/xml", "xml"),
// Archives
zip: binaryFile("application/zip"),
rar: binaryFile("application/vnd.rar"),
// Audio
mp3: binaryFile("audio/mpeg"),
wav: binaryFile("audio/wav"),
ogg: binaryFile("audio/ogg"),
m4a: binaryFile("audio/mp4"),
// Video
mp4: binaryFile("video/mp4"),
mov: binaryFile("video/quicktime"),
avi: binaryFile("video/x-msvideo"),
webm: binaryFile("video/webm"),
// Images
// Note: Cloudflare Image Resizing supports: jpg, jpeg, png, gif, webp, svg, avif
// Other formats (bmp, ico) are served as-is without optimization
jpg: binaryFile("image/jpeg"),
jpeg: binaryFile("image/jpeg"),
png: binaryFile("image/png"),
gif: binaryFile("image/gif"),
svg: textFile("image/svg+xml", "xml"),
webp: binaryFile("image/webp"),
avif: binaryFile("image/avif"),
ico: binaryFile("image/vnd.microsoft.icon"),
bmp: binaryFile("image/bmp"),
// Fonts
woff: binaryFile("font/woff"),
woff2: binaryFile("font/woff2"),
ttf: binaryFile("font/ttf"),
otf: binaryFile("font/otf"),
} as const;
export const ALLOWED_FILE_TYPES = Object.fromEntries(
Object.entries(assetFileTypes).map(([extension, { mimeType }]) => [
extension,
mimeType,
])
) as {
readonly [Extension in keyof typeof assetFileTypes]: (typeof assetFileTypes)[Extension]["mimeType"];
};
export type AllowedFileExtension = keyof typeof ALLOWED_FILE_TYPES;
/**
* Set of allowed file extensions for quick lookup
*/
export const ALLOWED_FILE_EXTENSIONS: ReadonlySet<AllowedFileExtension> =
new Set<AllowedFileExtension>(
Object.keys(ALLOWED_FILE_TYPES) as AllowedFileExtension[]
);
/**
* File extensions grouped by MIME category for UI display and filtering
*/
export const FILE_EXTENSIONS_BY_CATEGORY: Readonly<
Record<MimeCategory, AllowedFileExtension[]>
> = (() => {
const categories = Object.fromEntries(
MIME_CATEGORIES.map((category) => [category, []])
) as unknown as Record<MimeCategory, AllowedFileExtension[]>;
Object.entries(ALLOWED_FILE_TYPES).forEach(([ext, mimeType]) => {
const [category] = mimeType.split("/") as [MimeCategory];
if (category in categories) {
categories[category].push(ext as AllowedFileExtension);
}
});
return categories;
})();
// Create extension-to-MIME map for utilities
const extensionToMime = new Map(
Object.entries(ALLOWED_FILE_TYPES).map(([ext, mime]) => [`.${ext}`, mime])
);
const mimeTypes = new Set<string>(extensionToMime.values());
const mimePatterns = new Set<string>([
...mimeTypes.values(),
...MIME_CATEGORIES.map((category): `${MimeCategory}/*` => `${category}/*`),
]);
const getCategory = (pattern: string): MimeCategory => {
const categoryAsString = pattern.split("/")[0];
const category = MIME_CATEGORIES.find(
(category) => category === categoryAsString
);
if (category === undefined) {
throw new Error(`Invalid mime pattern: ${pattern}`);
}
return category;
};
/**
* All image file extensions
*/
export const IMAGE_EXTENSIONS: readonly AllowedFileExtension[] =
FILE_EXTENSIONS_BY_CATEGORY.image;
/**
* All image MIME types
*/
export const IMAGE_MIME_TYPES: readonly string[] = IMAGE_EXTENSIONS.map(
(ext) => ALLOWED_FILE_TYPES[ext as keyof typeof ALLOWED_FILE_TYPES]
);
/**
* Subset of IMAGE_MIME_TYPES supported as input by the image resizing pipeline.
* Used in the Accept header when fetching external images to prevent services
* like Unsplash (with auto=format) from serving formats like AVIF that cause
* Cloudflare Image Resizing ERROR 9520 during transformation.
*
* See: https://developers.cloudflare.com/images/transform-images/#supported-input-formats
*/
export const RESIZABLE_IMAGE_MIME_TYPES: readonly string[] = [
"image/jpeg",
"image/png",
"image/gif",
"image/webp",
"image/svg+xml",
];
/**
* All video file extensions
*/
export const VIDEO_EXTENSIONS: readonly AllowedFileExtension[] =
FILE_EXTENSIONS_BY_CATEGORY.video;
/**
* All video MIME types
*/
export const VIDEO_MIME_TYPES: readonly string[] = VIDEO_EXTENSIONS.map(
(ext) => ALLOWED_FILE_TYPES[ext as keyof typeof ALLOWED_FILE_TYPES]
);
/**
* All font file extensions
*/
export const FONT_EXTENSIONS: readonly AllowedFileExtension[] =
FILE_EXTENSIONS_BY_CATEGORY.font;
/**
* Get MIME type for a given file extension
*/
export const getMimeTypeByExtension = (
extension: string
): string | undefined => {
return ALLOWED_FILE_TYPES[extension.toLowerCase() as AllowedFileExtension];
};
export const getAssetTextEditorLanguage = (
asset: Pick<Asset, "format">
): AssetTextEditorLanguage | undefined => {
const fileType =
assetFileTypes[asset.format.toLowerCase() as keyof typeof assetFileTypes];
return fileType?.textEditor || undefined;
};
export const isTextFileAsset = (asset: Pick<Asset, "format">): boolean =>
getAssetTextEditorLanguage(asset) !== undefined;
export const isMdxFileAsset = (
asset: Readonly<{ type: string; format: string }>
) => asset.type === "file" && asset.format.toLowerCase() === "mdx";
/**
* Get MIME type from a filename
*/
export const getMimeTypeByFilename = (fileName: string): string => {
const extension = getFileExtension(fileName);
if (!extension) {
return "application/octet-stream";
}
return getMimeTypeByExtension(extension) ?? "application/octet-stream";
};
export const isResizableImageFileName = (fileName: string): boolean =>
RESIZABLE_IMAGE_MIME_TYPES.includes(getMimeTypeByFilename(fileName));
/**
* Check if a file extension is allowed
*/
export const isAllowedExtension = (extension: string): boolean => {
return ALLOWED_FILE_EXTENSIONS.has(
extension.toLowerCase() as AllowedFileExtension
);
};
/**
* Check if a MIME type category is allowed
*/
export const isAllowedMimeCategory = (category: string): boolean => {
return MIME_CATEGORIES.includes(category as MimeCategory);
};
/**
* Convert accept attribute value to MIME patterns.
* `".svg,font/otf,text/*"` -> `"image/svg+xml", "font/otf", "text/*"`
*/
export const acceptToMimePatterns = (accept: string): Set<string> | "*" => {
const result = new Set<string>();
if (accept === "") {
return "*";
}
for (const type of accept.split(",")) {
const trimmed = type.trim();
if (trimmed === "*" || trimmed === "*/*") {
return "*";
}
if (mimePatterns.has(trimmed)) {
result.add(trimmed);
continue;
}
const mime = extensionToMime.get(trimmed);
if (mime === undefined) {
warnOnce(
true,
`Couldn't not parse accept attribute value: ${trimmed}. Falling back to "*".`
);
return "*";
}
result.add(mime);
}
return result;
};
/**
* Convert accept attribute value to MIME categories.
* `".svg,font/otf,text/*"` -> `"image", "font", "text"`
*/
export const acceptToMimeCategories = (
accept: string
): Set<MimeCategory> | "*" => {
const patterns = acceptToMimePatterns(accept);
if (patterns === "*") {
return "*";
}
const categories = new Set<MimeCategory>();
for (const pattern of patterns) {
categories.add(getCategory(pattern));
}
return categories;
};
/**
* Get MIME type for an asset based on its type and format
*/
export const getAssetMime = ({
type,
format,
}: {
type: AssetType;
format: string;
}): string | undefined => {
const lowerFormat = format.toLowerCase();
const mime = `${type}/${lowerFormat}`;
if (mimeTypes.has(mime)) {
return mime;
}
const mime2 = extensionToMime.get(`.${lowerFormat}`);
if (mime2 === undefined) {
warnOnce(
true,
`Couldn't determine mime type of asset: ${type}, ${format}.`
);
}
return mime2;
};
/**
* Check if an asset matches the given MIME patterns.
* Supports legacy assets that were incorrectly stored with type "file".
*/
export const doesAssetMatchMimePatterns = (
asset: Pick<Asset, "format" | "type" | "name">,
patterns: Set<string> | "*"
): boolean => {
if (patterns === "*") {
return true;
}
// Try matching based on asset type and format
const mime = getAssetMime(asset);
if (mime !== undefined) {
if (patterns.has(mime) || patterns.has(`${getCategory(mime)}/*`)) {
return true;
}
}
// If it doesn't match and the asset type is "file" and has a name,
// try detecting the actual MIME type from the filename extension
// This handles legacy assets that were incorrectly stored as type "file"
if (asset.type === "file" && asset.name) {
const extension = getFileExtension(asset.name)?.toLowerCase();
if (extension) {
const mimeFromExtension = extensionToMime.get(`.${extension}`);
if (mimeFromExtension) {
return (
patterns.has(mimeFromExtension) ||
patterns.has(`${getCategory(mimeFromExtension)}/*`)
);
}
}
}
return false;
};
export class InvalidAssetFileNameError extends Error {}
/**
* Validate a filename and return its extension and MIME type
* @throws InvalidAssetFileNameError if file extension is not allowed
*/
export const validateFileName = (
fileName: string
): { extension: string; mimeType: string } => {
const extension = getFileExtension(fileName)?.toLowerCase();
if (!extension) {
throw new InvalidAssetFileNameError("File must have an extension");
}
if (!isAllowedExtension(extension)) {
throw new InvalidAssetFileNameError(
`File type "${extension}" is not allowed. Allowed types: ${Array.from(
ALLOWED_FILE_EXTENSIONS
).join(", ")}`
);
}
const mimeType = getMimeTypeByExtension(extension);
if (!mimeType) {
throw new InvalidAssetFileNameError(
`Could not determine MIME type for extension: ${extension}`
);
}
return { extension, mimeType };
};
/**
* Detect the asset type from a file based on its extension
*/
export const detectAssetType = (fileName: string): AssetType => {
const ext = getFileExtension(fileName)?.toLowerCase();
if (!ext) {
return "file";
}
if (IMAGE_EXTENSIONS.includes(ext as AllowedFileExtension)) {
return "image";
}
if (FONT_EXTENSIONS.includes(ext as AllowedFileExtension)) {
return "font";
}
if (VIDEO_EXTENSIONS.includes(ext as AllowedFileExtension)) {
return "video";
}
return "file";
};
/**
* Safely decode a URL path fragment, preventing path traversal attacks
* @throws Error if the decoded path contains path traversal attempts
*/
export const decodePathFragment = (fragment: string): string => {
const decoded = decodeURIComponent(fragment);
// Prevent path traversal attacks
if (decoded.includes("..") || decoded.startsWith("/")) {
throw new Error("Invalid file path");
}
return decoded;
};
/**
* Generates the appropriate URL for an asset based on its format.
*
* @param asset - The asset to generate URL for
* @param origin - Origin to prepend (e.g., "https://example.com"). When provided, returns an absolute URL.
* @returns A URL object. Use .pathname for relative paths, .href for absolute URLs
*/
export const getAssetUrl = (
asset: Pick<Asset, "name">,
origin: string
): URL => {
const path = isResizableImageFileName(asset.name)
? `/cgi/image/${asset.name}?format=raw`
: `/cgi/asset/${asset.name}?format=raw`;
return new URL(path, origin);
};
/**
* Runtime asset data structure with only fields needed at runtime.
* This is a simplified version of the Asset type, optimized for client-side usage.
*/
export type RuntimeAsset = {
url: string;
width?: number;
height?: number;
family?: string;
style?: string;
weight?: number;
};
/**
* Type-specific metadata extractors that define what runtime data each asset type needs.
* Adding a new asset type requires implementing its extractor here.
*/
type RuntimeMetadata = Omit<RuntimeAsset, "url"> | undefined;
const extractImageMetadata = (asset: Asset): RuntimeMetadata => {
if (asset.type !== "image") {
return;
}
// Only include dimensions if they're non-zero
if (asset.meta.width && asset.meta.height) {
return {
width: asset.meta.width,
height: asset.meta.height,
};
}
};
const extractFontMetadata = (asset: Asset): RuntimeMetadata => {
if (asset.type !== "font") {
return;
}
const metadata: Omit<RuntimeAsset, "url"> = {
family: asset.meta.family,
style: asset.meta.style,
};
// Static fonts have weight, variable fonts have variationAxes
if ("weight" in asset.meta) {
metadata.weight = asset.meta.weight;
}
return metadata;
};
const extractVideoMetadata = (asset: Asset): RuntimeMetadata => {
if (asset.type !== "video") {
return;
}
if (asset.meta.width && asset.meta.height) {
return {
width: asset.meta.width,
height: asset.meta.height,
};
}
};
const extractFileMetadata = (_asset: Asset): RuntimeMetadata => {
// Generic files don't need additional metadata at runtime
return;
};
const metadataExtractors: Record<
Asset["type"],
(asset: Asset) => RuntimeMetadata
> = {
image: extractImageMetadata,
font: extractFontMetadata,
video: extractVideoMetadata,
file: extractFileMetadata,
};
/**
* Converts a full Asset to a minimal RuntimeAsset format.
* This reduces payload size by including only runtime-needed data.
*
* Each asset type defines its own metadata extractor to ensure we only
* include the fields that are actually needed at runtime.
*
* @param asset - The full asset object
* @param origin - Origin to use for generating the asset URL (only used for URL construction, result is always a relative path)
* @returns A minimal RuntimeAsset object with relative URL
*/
export const toRuntimeAsset = (asset: Asset, origin: string): RuntimeAsset => {
const extractor = metadataExtractors[asset.type];
const metadata = extractor(asset);
const url = getAssetUrl(asset, origin);
// Use pathname + search to get the relative path with query string
const relativeUrl = url.pathname + url.search;
return {
url: relativeUrl,
...metadata,
};
};
/** Runtime data used only when an Assets query expands a local asset reference. */
export const toAssetReferenceRuntimeData = (asset: Asset, origin: string) => {
const name = formatAssetName(asset);
return {
...asset,
...toRuntimeAsset(asset, origin),
name,
mimeType: getAssetMime(asset) ?? getMimeTypeByFilename(name),
} satisfies AssetRuntimeData;
};