@holo-js/media 0.3.27 → 0.4.0

package/dist/index.mjs

@@ -9,33 +9,12 @@ import { Entity as Entity2 } from "@holo-js/db";
 // src/registry.ts
 import { Entity } from "@holo-js/db";
 
+// src/runtime/image.ts
+import { mimeTypeFromFileName } from "@holo-js/kernel/file-content";
+import { imageDecodingLimits } from "@holo-js/kernel/image-decoding";
+
 // src/runtime/binary.ts
 import { basename, extname } from "path";
-var MIME_TYPES = Object.freeze({
-  avif: "image/avif",
-  gif: "image/gif",
-  jpeg: "image/jpeg",
-  jpg: "image/jpeg",
-  json: "application/json",
-  pdf: "application/pdf",
-  png: "image/png",
-  svg: "image/svg+xml",
-  txt: "text/plain",
-  webp: "image/webp"
-});
-var IMAGE_EXTENSIONS = /* @__PURE__ */ new Set([
-  "avif",
-  "gif",
-  "heic",
-  "heif",
-  "jpeg",
-  "jpg",
-  "png",
-  "svg",
-  "tif",
-  "tiff",
-  "webp"
-]);
 var SHARP_OUTPUT_FORMATS = /* @__PURE__ */ new Set([
   "avif",
   "jpeg",
@@ -47,13 +26,6 @@ function sanitizeFileName(value) {
   const sanitized = value.trim().replace(/\\/g, "/").split("/").filter(Boolean).join("-");
   return sanitized || "media.bin";
 }
-function inferMimeType(fileName, explicit) {
-  if (explicit?.trim()) {
-    return explicit.trim();
-  }
-  const extension = extname(fileName).replace(/^\./, "").toLowerCase();
-  return MIME_TYPES[extension];
-}
 function getExtension(fileName) {
   const extension = extname(fileName).replace(/^\./, "").toLowerCase();
   return extension || void 0;
@@ -86,12 +58,6 @@ function getContentSize(value) {
   }
   return value.size;
 }
-function isImageSource(mimeType, extension) {
-  if (mimeType?.trim().toLowerCase().startsWith("image/")) {
-    return true;
-  }
-  return extension ? IMAGE_EXTENSIONS.has(extension.trim().toLowerCase()) : false;
-}
 function normalizeOutputFormat(extension, conversionFormat) {
   if (conversionFormat) {
     return conversionFormat;
@@ -131,16 +97,22 @@ function resolveFit(mode) {
 function createDefaultMediaConversionExecutor() {
   return {
     async generate({ source, conversion: conversion2 }) {
-      if (!isImageSource(source.mimeType, source.extension)) {
+      if (!source.mimeType?.toLowerCase().startsWith("image/")) {
         return null;
       }
       const outputFormat = normalizeOutputFormat(source.extension, conversion2.format);
       try {
         const sharp = await loadSharp();
-        let pipeline = sharp(await toBuffer(source.contents), {
+        const image = sharp(await toBuffer(source.contents), {
           animated: true,
-          failOn: "warning"
-        }).rotate();
+          failOn: "warning",
+          limitInputPixels: imageDecodingLimits.maximumDecodedPixels
+        });
+        const metadata = await image.metadata();
+        if ((metadata.pages ?? 1) > imageDecodingLimits.maximumFrames) {
+          throw new Error(`The image has more than ${imageDecodingLimits.maximumFrames} frames.`);
+        }
+        let pipeline = image.rotate();
         if (conversion2.width || conversion2.height) {
           pipeline = pipeline.resize({
             width: conversion2.width,
@@ -181,41 +153,18 @@ function createDefaultMediaConversionExecutor() {
         return {
           contents,
           fileName,
-          mimeType: inferMimeType(fileName)
+          mimeType: mimeTypeFromFileName(fileName) ?? void 0
         };
       } catch (error) {
         throw new Error(
-          `[Holo Media] Failed to generate conversion "${conversion2.name}" for "${source.fileName}": ${error.message}`
+          `[Holo Media] Failed to generate conversion "${conversion2.name}" for "${source.fileName}": ${error.message}`,
+          { cause: error }
         );
       }
     }
   };
 }
 var defaultMediaConversionExecutor = createDefaultMediaConversionExecutor();
-var imageMimeTypes = {
-  gif: "image/gif",
-  jpeg: "image/jpeg",
-  png: "image/png",
-  webp: "image/webp"
-};
-var mediaRuntimeInternals = Object.freeze({
-  async inspectImage(contents, maximumPixels = 4e7) {
-    if (!Number.isSafeInteger(maximumPixels) || maximumPixels < 1) throw new TypeError("[Holo Media] Image pixel limits require a positive integer.");
-    const factory = await loadSharp();
-    try {
-      const image = factory(Buffer.from(contents), { animated: true, failOn: "warning", limitInputPixels: maximumPixels });
-      const metadata = await image.metadata();
-      const { width, height } = metadata;
-      const format = metadata.format;
-      if (format !== "gif" && format !== "jpeg" && format !== "png" && format !== "webp") throw new Error("[Holo Media] Unsupported raster image format.");
-      if (!width || !height || !Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width * height > maximumPixels) throw new Error("[Holo Media] Image exceeds the pixel limit.");
-      await image.stats();
-      return { mimeType: imageMimeTypes[format], width, height: metadata.pageHeight ?? height, pages: metadata.pages ?? 1 };
-    } catch (error) {
-      throw new Error("[Holo Media] Image could not be decoded.", { cause: error });
-    }
-  }
-});
 
 // src/registry.ts
 var mediaRegistrySymbol = /* @__PURE__ */ Symbol.for("@holo-js/media.registry");
@@ -405,7 +354,14 @@ import { BlockList, isIP } from "net";
 import { tmpdir } from "os";
 import { basename as basename2, resolve, sep } from "path";
 import { Readable } from "stream";
-import { Storage as Storage4 } from "@holo-js/storage/runtime";
+import { config } from "@holo-js/config";
+import { localStoragePathInternals } from "@holo-js/kernel";
+import { inspectFileContent } from "@holo-js/kernel/file-content";
+import {
+  Storage as Storage4,
+  StorageMetadataUnsupportedError,
+  StorageStreamingUnsupportedError
+} from "@holo-js/storage/runtime";
 
 // src/queue.ts
 import {
@@ -417,27 +373,24 @@ import {
 import { connectionAsyncContext } from "@holo-js/db";
 
 // src/model/conversions.ts
+import { randomBytes } from "crypto";
+import { mimeTypeFromFileName as mimeTypeFromFileName2 } from "@holo-js/kernel/file-content";
 import { Storage as Storage2 } from "@holo-js/storage/runtime";
 
 // src/model/mutation.ts
 import { DB } from "@holo-js/db";
 import { Storage } from "@holo-js/storage/runtime";
 var MediaMutation = class {
-  written = [];
+  created = [];
   async put(disk, path, contents) {
-    const previous = await Storage.disk(disk).getBytes(path);
-    this.written.push({ disk, path, previous });
+    this.created.push({ disk, path });
     await Storage.disk(disk).put(path, contents);
   }
   async compensate() {
     const failures = [];
-    for (const file of this.written.splice(0).reverse()) {
+    for (const file of this.created.splice(0).reverse()) {
       try {
-        if (file.previous) {
-          await Storage.disk(file.disk).put(file.path, file.previous);
-        } else {
-          await Storage.disk(file.disk).delete(file.path);
-        }
+        await Storage.disk(file.disk).delete(file.path);
       } catch (error) {
         failures.push(error);
       }
@@ -446,41 +399,62 @@ var MediaMutation = class {
     if (failures.length > 1) throw new AggregateError(failures, "[Holo Media] File compensation failed.");
   }
 };
+async function compensateAfterFailure(mutation, error) {
+  try {
+    await mutation.compensate();
+  } catch (cleanupError) {
+    return new AggregateError([error, cleanupError], "[Holo Media] File compensation failed.");
+  }
+  return error;
+}
 async function runMediaMutation(options) {
   const mutation = new MediaMutation();
-  return await DB.writeTransaction(async (transaction) => {
-    transaction.afterRollback(async () => {
-      const failures = [];
-      try {
-        await mutation.compensate();
-      } catch (error) {
-        failures.push(error);
-      }
-      try {
-        await options.afterRollback?.();
-      } catch (error) {
-        failures.push(error);
-      }
-      if (failures.length === 1) throw failures[0];
-      if (failures.length > 1) throw new AggregateError(failures, "[Holo Media] Rollback restoration failed.");
-    });
-    const result = await options.operation(mutation);
-    transaction.afterCommit(async () => {
-      const failures = [];
-      for (const effect of options.afterCommit ?? []) {
+  let written;
+  try {
+    written = await options.write(mutation);
+  } catch (error) {
+    throw await compensateAfterFailure(mutation, error);
+  }
+  let transactionStarted = false;
+  try {
+    return await DB.writeTransaction(async (transaction) => {
+      transactionStarted = true;
+      transaction.afterRollback(async () => {
+        const failures = [];
         try {
-          await effect(result);
+          await mutation.compensate();
         } catch (error) {
           failures.push(error);
         }
-      }
-      options.afterEffects?.();
-      if (failures.length === 0) return;
-      const cause = failures.length === 1 ? failures[0] : new AggregateError(failures, "[Holo Media] Post-commit effects failed.");
-      throw new Error(options.committedMessage, { cause });
+        try {
+          await options.afterRollback?.();
+        } catch (error) {
+          failures.push(error);
+        }
+        if (failures.length === 1) throw failures[0];
+        if (failures.length > 1) throw new AggregateError(failures, "[Holo Media] Rollback restoration failed.");
+      });
+      const result = await options.operation(mutation, written);
+      transaction.afterCommit(async () => {
+        const failures = [];
+        for (const effect of options.afterCommit ?? []) {
+          try {
+            await effect(result);
+          } catch (error) {
+            failures.push(error);
+          }
+        }
+        options.afterEffects?.();
+        if (failures.length === 0) return;
+        const cause = failures.length === 1 ? failures[0] : new AggregateError(failures, "[Holo Media] Post-commit effects failed.");
+        throw new Error(options.committedMessage, { cause });
+      });
+      return result;
     });
-    return result;
-  });
+  } catch (error) {
+    if (transactionStarted) throw error;
+    throw await compensateAfterFailure(mutation, error);
+  }
 }
 async function removeStoredFiles(files, retained = []) {
   const failures = [];
@@ -508,6 +482,7 @@ async function deleteMediaItems(items, owner) {
   if (items.length === 0) return;
   await runMediaMutation({
     committedMessage: "[Holo Media] Deletion remains committed; post-commit file cleanup failed.",
+    write: async () => void 0,
     operation: async () => {
       for (const item of items) await item.getEntity().delete();
       owner?.forgetRelation("media");
@@ -588,7 +563,13 @@ function resolveQueuedConversionNames(options) {
     ).filter((conversion2) => conversion2.queued).map((conversion2) => conversion2.name)
   );
 }
-async function generateStoredConversions(options) {
+function withUniqueSuffix(path) {
+  const token = randomBytes(8).toString("hex");
+  const slash = path.lastIndexOf("/");
+  const dot = path.lastIndexOf(".");
+  return dot > slash + 1 ? `${path.slice(0, dot)}.${token}${path.slice(dot)}` : `${path}.${token}`;
+}
+async function writeStoredConversions(options) {
   const requested = normalizeRequestedConversions(options.requestedConversions);
   const matchingConversions = resolveMatchingConversions(
     options.definition,
@@ -596,9 +577,6 @@ async function generateStoredConversions(options) {
     requested,
     { includeQueued: options.includeQueued === true }
   );
-  if (matchingConversions.length === 0) {
-    return Object.freeze({});
-  }
   const generatedConversions = /* @__PURE__ */ Object.create(null);
   const executor = getMediaConversionExecutor();
   for (const conversion2 of matchingConversions) {
@@ -611,7 +589,7 @@ async function generateStoredConversions(options) {
       continue;
     }
     const generatedFileName = sanitizeFileName(generated.fileName ?? options.source.fileName);
-    const conversionPath = getMediaPathGenerator().conversionPath({
+    const plannedPath = getMediaPathGenerator().conversionPath({
       uuid: options.source.uuid,
       fileName: options.source.fileName,
       extension: options.source.extension,
@@ -619,27 +597,22 @@ async function generateStoredConversions(options) {
       conversion: conversion2,
       generatedFileName
     });
-    const targetDisk = generated.disk ?? options.conversionsDisk;
-    const conversionMimeType = inferMimeType(generatedFileName, generated.mimeType);
-    const conversionContents = await toBinaryContent(generated.contents);
-    await options.mutation.put(targetDisk, conversionPath, conversionContents);
+    const path = options.unique ? withUniqueSuffix(plannedPath) : plannedPath;
+    const disk = generated.disk ?? options.conversionsDisk;
+    const contents = await toBinaryContent(generated.contents);
+    await options.mutation.put(disk, path, contents);
     generatedConversions[conversion2.name] = Object.freeze({
-      path: conversionPath,
-      disk: targetDisk,
+      path,
+      disk,
       fileName: generatedFileName,
-      mimeType: conversionMimeType,
-      size: getContentSize(conversionContents)
+      mimeType: generated.mimeType?.trim() || mimeTypeFromFileName2(generatedFileName) || void 0,
+      size: getContentSize(contents)
     });
   }
   return Object.freeze(generatedConversions);
 }
-async function deleteObsoleteConversions(current, next, fallbackDisk, requested) {
-  const obsolete = Object.entries(current).filter(([name, conversion2]) => {
-    if (requested?.length && !requested.includes(name) || !conversion2?.path) return false;
-    const nextConversion = next[name];
-    return nextConversion?.path !== conversion2.path || (nextConversion.disk ?? fallbackDisk) !== (conversion2.disk ?? fallbackDisk);
-  }).map(([, conversion2]) => ({ disk: conversion2.disk ?? fallbackDisk, path: conversion2.path }));
-  await removeStoredFiles(obsolete);
+function obsoleteConversionFiles(current, next, fallbackDisk) {
+  return Object.entries(current).filter(([name, conversion2]) => conversion2?.path && next[name]?.path !== conversion2.path).map(([, conversion2]) => ({ disk: conversion2.disk ?? fallbackDisk, path: conversion2.path }));
 }
 async function regenerateMediaEntityConversions(options) {
   const media = options.media;
@@ -648,7 +621,6 @@ async function regenerateMediaEntityConversions(options) {
   const collectionName = String(media.get("collection_name"));
   const collection2 = resolveCollectionDefinition(definition, collectionName);
   const requested = normalizeRequestedConversions(options.conversions);
-  const current = media.get("generated_conversions") ?? {};
   const conversionsDisk = String(media.get("conversions_disk") ?? media.get("disk"));
   resolveMatchingConversions(definition, collectionName, requested, {
     includeQueued: options.includeQueued === true
@@ -659,46 +631,56 @@ async function regenerateMediaEntityConversions(options) {
       `[Holo Media] Cannot regenerate conversions for media "${media.get("uuid")}" because the original file is missing.`
     );
   }
-  const nextBase = requested?.length ? Object.fromEntries(
-    Object.entries(current).filter(([name]) => !requested.includes(name))
-  ) : {};
-  return await runMediaMutation({
+  const mediaId = media.get("id");
+  const result = await runMediaMutation({
     committedMessage: "[Holo Media] Regeneration remains committed; post-commit cleanup or conversion dispatch failed.",
     afterRollback: async () => {
       options.owner?.forgetRelation("media");
       await media.refresh();
     },
-    operation: async (mutation) => {
-      const regenerated = await generateStoredConversions({
-        definition,
-        collection: collection2,
-        conversionsDisk,
-        requestedConversions: requested,
-        includeQueued: options.includeQueued === true,
-        mutation,
-        source: {
-          uuid: String(media.get("uuid")),
-          fileName: String(media.get("file_name")),
-          extension: media.get("extension") ?? void 0,
-          mimeType: media.get("mime_type") ?? void 0,
-          size: sourceContents.byteLength,
-          contents: sourceContents
-        }
-      });
+    write: async (mutation) => await writeStoredConversions({
+      definition,
+      collection: collection2,
+      conversionsDisk,
+      requestedConversions: requested,
+      includeQueued: options.includeQueued === true,
+      unique: true,
+      mutation,
+      source: {
+        uuid: String(media.get("uuid")),
+        fileName: String(media.get("file_name")),
+        extension: media.get("extension") ?? void 0,
+        mimeType: media.get("mime_type") ?? void 0,
+        size: sourceContents.byteLength,
+        contents: sourceContents
+      }
+    }),
+    operation: async (_mutation, regenerated) => {
+      const locked = await Media.query().where("id", mediaId).lockForUpdate().first();
+      if (!locked) {
+        throw new Error(`[Holo Media] Cannot regenerate conversions for media "${media.get("uuid")}" because the media row no longer exists.`);
+      }
+      const current = locked.get("generated_conversions") ?? {};
+      const nextBase = requested?.length ? Object.fromEntries(
+        Object.entries(current).filter(([name]) => !requested.includes(name))
+      ) : {};
       const generatedConversions = Object.freeze({ ...nextBase, ...regenerated });
       media.forceFill({ generated_conversions: generatedConversions });
       await media.save();
       options.owner?.forgetRelation("media");
-      return generatedConversions;
+      return {
+        generatedConversions,
+        obsolete: obsoleteConversionFiles(current, generatedConversions, conversionsDisk)
+      };
     },
     afterCommit: [
-      async (generatedConversions) => {
-        await deleteObsoleteConversions(current, generatedConversions, conversionsDisk, requested);
+      async ({ obsolete }) => {
+        await removeStoredFiles(obsolete);
       },
       async () => {
         if (options.includeQueued) return;
         await dispatchQueuedMediaConversionsForModel({
-          mediaId: media.get("id"),
+          mediaId,
           conversionNames: resolveQueuedConversionNames({ definition, collectionName, requestedConversions: requested })
         }, async () => {
           await media.refresh();
@@ -709,6 +691,7 @@ async function regenerateMediaEntityConversions(options) {
       options.owner?.forgetRelation("media");
     }
   });
+  return result.generatedConversions;
 }
 
 // src/queue.ts
@@ -839,6 +822,8 @@ var MediaItem = class {
     this.entity = entity;
     this.owner = owner;
   }
+  entity;
+  owner;
   get record() {
     return this.entity.toAttributes();
   }
@@ -923,8 +908,34 @@ var MediaItem = class {
 };
 
 // src/model/adder.ts
+var RemoteMediaSource = class {
+  constructor(url) {
+    this.url = url;
+  }
+  url;
+};
+var StoredMediaSource = class {
+  constructor(disk, path) {
+    this.disk = disk;
+    this.path = path;
+  }
+  disk;
+  path;
+};
 var DEFAULT_REMOTE_MEDIA_MAX_SIZE = 10 * 1024 * 1024;
+var REMOTE_MEDIA_TIMEOUT_MS = 3e4;
+var DEFAULT_MEDIA_DISK = "public";
 var BLOCKED_REMOTE_MEDIA_ADDRESSES = createBlockedRemoteMediaAddresses();
+var GLOBALLY_REACHABLE_BLOCKED_IPV4_ADDRESSES = createGloballyReachableBlockedIPv4Addresses();
+var GLOBAL_UNICAST_IPV6_ADDRESSES = createGlobalUnicastIPv6Addresses();
+var IETF_PROTOCOL_ASSIGNMENTS = createIETFProtocolAssignmentsBlockList();
+var GLOBALLY_REACHABLE_IETF_PROTOCOL_ASSIGNMENTS = createGloballyReachableIETFProtocolAssignments();
+var NAT64_WELL_KNOWN_PREFIX = Buffer.concat([Buffer.from([0, 100, 255, 155]), Buffer.alloc(8)]);
+var SIX_TO_FOUR_PREFIX = Buffer.from([32, 2]);
+var IPV4_COMPATIBLE_PREFIX = Buffer.alloc(12);
+var TRANSLATED_IPV4_PREFIX = Buffer.from([0, 0, 0, 0, 0, 0, 0, 0, 255, 255, 0, 0]);
+var IPV4_MAPPED_PREFIX = Buffer.from([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255]);
+var TEREDO_PREFIX = Buffer.from([32, 1, 0, 0]);
 var LOCAL_MEDIA_SOURCE_ROOTS = Object.freeze([
   tmpdir(),
   resolve(process.cwd(), "storage")
@@ -934,9 +945,9 @@ var defaultRemoteMediaAddressResolver = async (hostname) => await lookup(hostnam
   verbatim: true
 });
 function createRemoteMediaDownloader(resolver, requester) {
-  return async (url) => {
+  return async (url, signal) => {
     const address = await resolveRemoteMediaAddress(url, resolver);
-    return await requester(url, address);
+    return await requester(url, address, signal);
   };
 }
 var defaultRemoteMediaDownloader = createRemoteMediaDownloader(defaultRemoteMediaAddressResolver, requestRemoteMedia);
@@ -950,19 +961,14 @@ var MediaAddValidationException = class extends Error {
     this.error = error;
   }
 };
-function resolveImplicitDiskName() {
-  const defaultDisk = Storage4.disk();
-  if (defaultDisk.visibility === "public") {
-    return defaultDisk.name;
-  }
+function resolveMediaDefaultDisk() {
+  let configuredDisk;
   try {
-    const publicDisk = Storage4.disk("public");
-    if (publicDisk.visibility === "public") {
-      return publicDisk.name;
-    }
+    configuredDisk = config("media.disk");
   } catch {
+    return DEFAULT_MEDIA_DISK;
   }
-  return defaultDisk.name;
+  return typeof configuredDisk === "string" && configuredDisk.trim() ? configuredDisk.trim() : DEFAULT_MEDIA_DISK;
 }
 function parseRemoteFileName(url) {
   const parsedUrl = new URL(url);
@@ -1007,53 +1013,61 @@ function createMaxSizeError(fileName, collectionName, maxSize, actualSize) {
 async function readRemoteMediaContents(response, fileName, maxSize, collectionName) {
   const resolvedMaxSize = typeof maxSize === "number" ? maxSize : DEFAULT_REMOTE_MEDIA_MAX_SIZE;
   if (!response.body) {
-    const contents2 = new Uint8Array(await response.arrayBuffer());
-    if (contents2.byteLength > resolvedMaxSize) {
-      throw createMaxSizeError(fileName, collectionName, resolvedMaxSize, contents2.byteLength);
+    const contents = new Uint8Array(await response.arrayBuffer());
+    if (contents.byteLength > resolvedMaxSize) {
+      throw createMaxSizeError(fileName, collectionName, resolvedMaxSize, contents.byteLength);
     }
-    return contents2;
+    return contents;
   }
-  const reader = response.body.getReader();
-  const chunks = [];
-  let totalSize = 0;
+  return await readBoundedMediaContents(
+    readWebStreamChunks(response.body),
+    fileName,
+    resolvedMaxSize,
+    collectionName
+  );
+}
+async function* readWebStreamChunks(stream) {
+  const reader = stream.getReader();
   try {
     while (true) {
       const { done, value } = await reader.read();
       if (done) {
-        break;
-      }
-      if (!value) {
-        continue;
+        return;
       }
-      totalSize += value.byteLength;
-      if (totalSize > resolvedMaxSize) {
-        await reader.cancel().catch(() => void 0);
-        throw createMaxSizeError(fileName, collectionName, resolvedMaxSize, totalSize);
+      if (value) {
+        yield value;
       }
-      chunks.push(value);
     }
   } finally {
+    await reader.cancel().catch(() => void 0);
     reader.releaseLock();
   }
+}
+async function readBoundedMediaContents(chunks, fileName, maxSize, collectionName) {
+  const parts = [];
+  let totalSize = 0;
+  for await (const chunk of chunks) {
+    totalSize += chunk.byteLength;
+    if (totalSize > maxSize) {
+      throw createMaxSizeError(fileName, collectionName, maxSize, totalSize);
+    }
+    parts.push(chunk);
+  }
   const contents = new Uint8Array(totalSize);
   let offset = 0;
-  for (const chunk of chunks) {
-    contents.set(chunk, offset);
-    offset += chunk.byteLength;
+  for (const part of parts) {
+    contents.set(part, offset);
+    offset += part.byteLength;
   }
   return contents;
 }
 async function resolveMediaSource(input, overrideFileName, overrideName, options) {
-  if (typeof input === "string" && /^https?:\/\//i.test(input)) {
-    return resolveRemoteMediaSource(
-      { url: input },
-      overrideFileName,
-      overrideName,
-      options.maxSize,
-      options.collectionName
-    );
-  }
-  if (typeof input !== "string" && isUrlInput(input)) {
+  const source = await readMediaSource(input, overrideFileName, overrideName, options);
+  const { mimeType } = await inspectFileContent(source.contents, source.fileName);
+  return mimeType ? { ...source, mimeType } : source;
+}
+async function readMediaSource(input, overrideFileName, overrideName, options) {
+  if (input instanceof RemoteMediaSource) {
     return resolveRemoteMediaSource(
       input,
       overrideFileName,
@@ -1062,6 +1076,12 @@ async function resolveMediaSource(input, overrideFileName, overrideName, options
       options.collectionName
     );
   }
+  if (input instanceof StoredMediaSource) {
+    return resolveStorageMediaSource(input, overrideFileName, overrideName, options);
+  }
+  if (typeof input === "string" && /^https?:\/\//i.test(input) || typeof input === "object" && input !== null && "url" in input) {
+    throw new Error("[@holo-js/media] addMedia() reads file paths and binary contents. Use addMediaFromUrl() to download a URL.");
+  }
   if (typeof input === "string" || isPathInput(input)) {
     const path = await resolveLocalMediaSourcePath(typeof input === "string" ? input : input.path);
     const contents2 = await readFile(path);
@@ -1069,7 +1089,6 @@ async function resolveMediaSource(input, overrideFileName, overrideName, options
     return {
       contents: contents2,
       fileName: fileName2,
-      mimeType: inferMimeType(fileName2),
       extension: getExtension(fileName2),
       size: contents2.byteLength,
       name: getDisplayName(fileName2, overrideName)
@@ -1081,7 +1100,6 @@ async function resolveMediaSource(input, overrideFileName, overrideName, options
     return {
       contents: contents2,
       fileName: fileName2,
-      mimeType: inferMimeType(fileName2, input.mimeType),
       extension: getExtension(fileName2),
       size: getContentSize(contents2),
       name: getDisplayName(fileName2, overrideName ?? input.name)
@@ -1092,7 +1110,6 @@ async function resolveMediaSource(input, overrideFileName, overrideName, options
   return {
     contents,
     fileName,
-    mimeType: inferMimeType(fileName, getBinaryMimeType(input)),
     extension: getExtension(fileName),
     size: getContentSize(contents),
     name: getDisplayName(fileName, overrideName)
@@ -1102,52 +1119,133 @@ function getBinaryFileName(input) {
   const name = input.name;
   return typeof name === "string" && name.trim() ? name : "media.bin";
 }
-function getBinaryMimeType(input) {
-  const type = input.type;
-  return typeof type === "string" && type.trim() ? type : void 0;
-}
 function isPathInput(input) {
   return typeof input === "object" && input !== null && "path" in input;
 }
-function isUrlInput(input) {
-  return typeof input === "object" && input !== null && "url" in input;
-}
-async function resolveRemoteMediaSource(input, overrideFileName, overrideName, maxSize, collectionName) {
-  const remoteUrl = resolveRemoteMediaUrl(input.url);
-  const response = await remoteMediaDownloader(remoteUrl);
-  if (response.status >= 300 && response.status < 400) {
-    throw new Error("[@holo-js/media] Remote media downloads do not follow redirects.");
-  }
-  if (!response.ok) {
+async function resolveStorageMediaSource(input, overrideFileName, overrideName, options) {
+  const disk = Storage4.disk(input.disk);
+  const fileName = sanitizeFileName(overrideFileName ?? localStoragePathInternals.splitLocalStoragePath(input.path).at(-1) ?? "");
+  const maxSize = options.maxSize;
+  const metadataAvailable = typeof maxSize === "number" && await checkStoredFileSize(disk, input, fileName, maxSize, options.collectionName);
+  const chunks = await openStoredFileStream(disk, input);
+  if (chunks === null) {
+    throw missingStoredFileError(input);
+  }
+  let contents;
+  if (chunks) {
+    contents = await readBoundedMediaContents(chunks, fileName, maxSize ?? Number.POSITIVE_INFINITY, options.collectionName);
+  } else if (typeof maxSize !== "number") {
+    contents = await readWholeStoredFile(disk, input);
+  } else if (!metadataAvailable) {
     throw new Error(
-      `[Holo Media] Failed to download media from "${remoteUrl.toString()}" (${response.status} ${response.statusText}).`
+      `[@holo-js/media] Collection "${options.collectionName}" has a maxSize, so "${input.path}" on disk "${input.disk}" needs a disk that supports file metadata or streaming.`
     );
+  } else {
+    contents = await readWholeStoredFile(disk, input);
+    if (contents.byteLength > maxSize) {
+      throw createMaxSizeError(fileName, options.collectionName, maxSize, contents.byteLength);
+    }
   }
-  const fileName = sanitizeFileName(
-    overrideFileName ?? input.fileName ?? parseRemoteFileName(remoteUrl.toString())
-  );
-  const responseMimeType = response.headers.get("content-type")?.split(";")[0];
-  const contentLengthHeader = response.headers.get("content-length");
-  const contentLength = contentLengthHeader?.trim() ? Number(contentLengthHeader) : Number.NaN;
-  const resolvedMaxSize = typeof maxSize === "number" ? maxSize : DEFAULT_REMOTE_MEDIA_MAX_SIZE;
-  if (Number.isFinite(contentLength) && contentLength > resolvedMaxSize) {
-    throw createMaxSizeError(fileName, collectionName, resolvedMaxSize, contentLength);
-  }
-  const contents = await readRemoteMediaContents(
-    response,
-    fileName,
-    maxSize,
-    collectionName
-  );
   return {
     contents,
     fileName,
-    mimeType: inferMimeType(fileName, input.mimeType ?? responseMimeType ?? void 0),
     extension: getExtension(fileName),
     size: contents.byteLength,
-    name: getDisplayName(fileName, overrideName ?? input.name)
+    name: getDisplayName(fileName, overrideName)
   };
 }
+async function checkStoredFileSize(disk, input, fileName, maxSize, collectionName) {
+  let metadata;
+  try {
+    metadata = await disk.stat(input.path);
+  } catch (error) {
+    if (error instanceof StorageMetadataUnsupportedError) {
+      return false;
+    }
+    throw error;
+  }
+  if (!metadata) {
+    throw missingStoredFileError(input);
+  }
+  if (metadata.size > maxSize) {
+    throw createMaxSizeError(fileName, collectionName, maxSize, metadata.size);
+  }
+  return true;
+}
+async function openStoredFileStream(disk, input) {
+  try {
+    return await disk.readStream(input.path);
+  } catch (error) {
+    if (error instanceof StorageStreamingUnsupportedError) {
+      return void 0;
+    }
+    throw error;
+  }
+}
+async function readWholeStoredFile(disk, input) {
+  const contents = await disk.getBytes(input.path);
+  if (!contents) {
+    throw missingStoredFileError(input);
+  }
+  return contents;
+}
+function missingStoredFileError(input) {
+  return new Error(`[@holo-js/media] File "${input.path}" was not found on disk "${input.disk}".`);
+}
+async function withRemoteMediaDeadline(download) {
+  const controller = new AbortController();
+  let timer;
+  const deadline = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => {
+      const error = new Error(
+        `[@holo-js/media] Remote media downloads must finish within ${REMOTE_MEDIA_TIMEOUT_MS / 1e3} seconds.`
+      );
+      controller.abort(error);
+      reject(error);
+    }, REMOTE_MEDIA_TIMEOUT_MS);
+  });
+  try {
+    return await Promise.race([download(controller.signal), deadline]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function resolveRemoteMediaSource(input, overrideFileName, overrideName, maxSize, collectionName) {
+  const remoteUrl = resolveRemoteMediaUrl(input.url);
+  return await withRemoteMediaDeadline(async (signal) => {
+    const response = await remoteMediaDownloader(remoteUrl, signal);
+    if (response.status >= 300 && response.status < 400) {
+      throw new Error("[@holo-js/media] Remote media downloads do not follow redirects.");
+    }
+    if (!response.ok) {
+      throw new Error(
+        `[Holo Media] Failed to download media from "${remoteUrl.toString()}" (${response.status} ${response.statusText}).`
+      );
+    }
+    const fileName = sanitizeFileName(
+      overrideFileName ?? parseRemoteFileName(remoteUrl.toString())
+    );
+    const contentLengthHeader = response.headers.get("content-length");
+    const contentLength = contentLengthHeader?.trim() ? Number(contentLengthHeader) : Number.NaN;
+    const resolvedMaxSize = typeof maxSize === "number" ? maxSize : DEFAULT_REMOTE_MEDIA_MAX_SIZE;
+    if (Number.isFinite(contentLength) && contentLength > resolvedMaxSize) {
+      throw createMaxSizeError(fileName, collectionName, resolvedMaxSize, contentLength);
+    }
+    const contents = await readRemoteMediaContents(
+      response,
+      fileName,
+      maxSize,
+      collectionName
+    );
+    return {
+      contents,
+      fileName,
+      extension: getExtension(fileName),
+      size: contents.byteLength,
+      name: getDisplayName(fileName, overrideName)
+    };
+  });
+}
 async function resolveLocalMediaSourcePath(path) {
   const resolvedPath = await realpath(path);
   const allowedRoots = await Promise.all(LOCAL_MEDIA_SOURCE_ROOTS.map(async (root) => await realpath(root).catch(() => null)));
@@ -1172,9 +1270,13 @@ function resolveRemoteMediaUrl(value) {
   if (url.username || url.password) {
     throw new Error("[@holo-js/media] Remote media URLs must not include credentials.");
   }
-  if (isBlockedRemoteMediaHost(url.hostname)) {
+  if (isLocalRemoteMediaName(url.hostname)) {
     throw new Error("[@holo-js/media] Remote media URLs must not target local or private hosts.");
   }
+  const literal = parseRemoteMediaIPLiteral(url.hostname);
+  if (literal) {
+    assertRemoteMediaAddressesAllowed([literal]);
+  }
   return url;
 }
 function createBlockedRemoteMediaAddresses() {
@@ -1188,42 +1290,167 @@ function createBlockedRemoteMediaAddresses() {
     ["172.16.0.0", 12],
     ["192.0.0.0", 24],
     ["192.0.2.0", 24],
+    ["192.88.99.2", 32],
     ["192.168.0.0", 16],
     ["198.18.0.0", 15],
     ["198.51.100.0", 24],
     ["203.0.113.0", 24],
-    ["224.0.0.0", 4]
+    ["224.0.0.0", 4],
+    ["240.0.0.0", 4],
+    ["255.255.255.255", 32]
   ]) {
     blockList.addSubnet(network, prefix, "ipv4");
   }
   for (const [network, prefix] of [
     ["::", 128],
     ["::1", 128],
+    ["100::", 64],
+    ["100:0:0:1::", 64],
+    ["2001:db8::", 32],
+    ["3fff::", 20],
+    ["5f00::", 16],
     ["fc00::", 7],
     ["fe80::", 10],
+    ["fec0::", 10],
     ["ff00::", 8]
   ]) {
     blockList.addSubnet(network, prefix, "ipv6");
   }
   return blockList;
 }
+function createGloballyReachableBlockedIPv4Addresses() {
+  const blockList = new BlockList();
+  for (const [network, prefix] of [
+    ["192.0.0.9", 32],
+    ["192.0.0.10", 32]
+  ]) {
+    blockList.addSubnet(network, prefix, "ipv4");
+  }
+  return blockList;
+}
+function createGlobalUnicastIPv6Addresses() {
+  const blockList = new BlockList();
+  blockList.addSubnet("2000::", 3, "ipv6");
+  return blockList;
+}
+function createIETFProtocolAssignmentsBlockList() {
+  const blockList = new BlockList();
+  blockList.addSubnet("2001::", 23, "ipv6");
+  return blockList;
+}
+function createGloballyReachableIETFProtocolAssignments() {
+  const blockList = new BlockList();
+  for (const [network, prefix] of [
+    ["2001::", 32],
+    ["2001:1::1", 128],
+    ["2001:1::2", 128],
+    ["2001:1::3", 128],
+    ["2001:3::", 32],
+    ["2001:4:112::", 48],
+    ["2001:20::", 28],
+    ["2001:30::", 28]
+  ]) {
+    blockList.addSubnet(network, prefix, "ipv6");
+  }
+  return blockList;
+}
+function isBlockedRemoteMediaIPv4Address(address) {
+  return BLOCKED_REMOTE_MEDIA_ADDRESSES.check(address, "ipv4") && !GLOBALLY_REACHABLE_BLOCKED_IPV4_ADDRESSES.check(address, "ipv4");
+}
 function isBlockedRemoteMediaAddress(address) {
-  return BLOCKED_REMOTE_MEDIA_ADDRESSES.check(address.address, address.family === 4 ? "ipv4" : "ipv6");
+  if (address.family === 4) {
+    return isBlockedRemoteMediaIPv4Address(address.address);
+  }
+  return isBlockedRemoteMediaIPv6Address(address.address);
+}
+function isBlockedRemoteMediaIPv6Address(address) {
+  const bytes = findIPv6Bytes(address);
+  if (!bytes) {
+    return true;
+  }
+  if (!GLOBAL_UNICAST_IPV6_ADDRESSES.check(address, "ipv6")) {
+    const mappedAddress = findMappedIPv4Address(bytes);
+    return mappedAddress === null || isBlockedRemoteMediaIPv4Address(mappedAddress);
+  }
+  if (BLOCKED_REMOTE_MEDIA_ADDRESSES.check(address, "ipv6")) {
+    return true;
+  }
+  if (IETF_PROTOCOL_ASSIGNMENTS.check(address, "ipv6") && !GLOBALLY_REACHABLE_IETF_PROTOCOL_ASSIGNMENTS.check(address, "ipv6")) {
+    return true;
+  }
+  return findEmbeddedIPv4Addresses(bytes).some(isBlockedRemoteMediaIPv4Address);
+}
+function findMappedIPv4Address(bytes) {
+  const mappedPrefixes = [NAT64_WELL_KNOWN_PREFIX, IPV4_COMPATIBLE_PREFIX, IPV4_MAPPED_PREFIX, TRANSLATED_IPV4_PREFIX];
+  if (!mappedPrefixes.some((prefix) => bytes.subarray(0, 12).equals(prefix))) {
+    return null;
+  }
+  return formatIPv4Octets(bytes.subarray(12, 16));
+}
+function findEmbeddedIPv4Addresses(bytes) {
+  const embeddedAddresses = [];
+  if (bytes.subarray(0, 2).equals(SIX_TO_FOUR_PREFIX)) {
+    embeddedAddresses.push(formatIPv4Octets(bytes.subarray(2, 6)));
+  }
+  if (bytes.subarray(0, 4).equals(TEREDO_PREFIX)) {
+    embeddedAddresses.push(formatIPv4Octets(bytes.subarray(12, 16).map((octet) => octet ^ 255)));
+  }
+  const interfaceIdentifierPrefix = bytes.readUInt16BE(8);
+  if ((interfaceIdentifierPrefix === 0 || interfaceIdentifierPrefix === 512) && bytes.readUInt16BE(10) === 24318) {
+    embeddedAddresses.push(formatIPv4Octets(bytes.subarray(12, 16)));
+  }
+  return embeddedAddresses;
+}
+function findIPv6Bytes(address) {
+  let canonical;
+  try {
+    canonical = new URL(`http://[${address}]`).hostname.slice(1, -1);
+  } catch {
+    return null;
+  }
+  const halves = canonical.split("::");
+  const head = halves[0] ? halves[0].split(":") : [];
+  const tail = halves[1] ? halves[1].split(":") : [];
+  const zeroGroups = halves.length === 2 ? 8 - head.length - tail.length : 0;
+  const groups = [...head, ...Array(zeroGroups).fill("0"), ...tail];
+  if (groups.length !== 8) {
+    return null;
+  }
+  return Buffer.from(groups.flatMap((group) => {
+    const value = Number.parseInt(group, 16);
+    return [value >> 8, value & 255];
+  }));
+}
+function formatIPv4Octets(octets) {
+  return Array.from(octets).join(".");
 }
 async function resolveRemoteMediaAddress(url, resolver) {
-  const addresses = await resolver(url.hostname);
+  const addresses = await resolveRemoteMediaHostAddresses(url.hostname, resolver);
+  assertRemoteMediaAddressesAllowed(addresses);
+  return addresses[0];
+}
+function assertRemoteMediaAddressesAllowed(addresses) {
   if (addresses.length === 0 || addresses.some(isBlockedRemoteMediaAddress)) {
     throw new Error("[@holo-js/media] Remote media URLs must not resolve to local or private hosts.");
   }
-  return addresses[0];
 }
-function requestRemoteMedia(url, address) {
+async function resolveRemoteMediaHostAddresses(hostname, resolver) {
+  const literal = parseRemoteMediaIPLiteral(hostname);
+  return literal ? [literal] : await resolver(hostname);
+}
+function parseRemoteMediaIPLiteral(hostname) {
+  const address = hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+  const family = isIP(address);
+  return family === 0 ? null : { address, family };
+}
+function requestRemoteMedia(url, address, signal) {
   return new Promise((resolveResponse, reject) => {
     const request = resolveRemoteMediaRequest(url.protocol)(url, {
       headers: {
         host: url.host
       },
-      lookup: createPinnedRemoteMediaLookup(address)
+      lookup: createPinnedRemoteMediaLookup(address),
+      signal
     }, (response) => {
       const headers = new Headers();
       appendRemoteMediaHeaders(headers, response.headers);
@@ -1252,14 +1479,9 @@ function appendRemoteMediaHeaders(headers, source) {
 function resolveRemoteMediaRequest(protocol) {
   return protocol === "https:" ? requestHttps : requestHttp;
 }
-function isBlockedRemoteMediaHost(hostname) {
+function isLocalRemoteMediaName(hostname) {
   const lowerCaseHostname = hostname.toLowerCase();
-  const normalized = lowerCaseHostname.startsWith("[") && lowerCaseHostname.endsWith("]") ? lowerCaseHostname.slice(1, -1) : lowerCaseHostname;
-  if (normalized === "localhost" || normalized.endsWith(".localhost")) {
-    return true;
-  }
-  const family = isIP(normalized);
-  return family !== 0 && isBlockedRemoteMediaAddress({ address: normalized, family });
+  return lowerCaseHostname === "localhost" || lowerCaseHostname.endsWith(".localhost");
 }
 function validateSource(collection2, source) {
   if (typeof collection2.maxSize === "number" && source.size > collection2.maxSize) {
@@ -1295,6 +1517,9 @@ var MediaAdder = class _MediaAdder {
     this.source = source;
     this.state = state;
   }
+  entity;
+  source;
+  state;
   usingName(name) {
     return new _MediaAdder(this.entity, this.source, {
       ...this.state,
@@ -1356,7 +1581,7 @@ var MediaAdder = class _MediaAdder {
       collection: collection2,
       definition: mediaDefinition,
       source,
-      disk: this.state.disk ?? collection2.disk ?? resolveImplicitDiskName()
+      disk: this.state.disk ?? collection2.disk ?? resolveMediaDefaultDisk()
     });
   }
 };
@@ -1373,16 +1598,18 @@ async function attachMedia(options) {
     afterRollback: () => {
       owner.forgetRelation("media");
     },
-    operation: async (mutation) => {
-      const existing = collection2.singleFile ? await owner.getMedia(options.collectionName) : [];
+    write: async (mutation) => {
       await mutation.put(disk, path, source.contents);
-      const generatedConversions = await generateStoredConversions({
+      return await writeStoredConversions({
         definition: options.definition,
         collection: collection2,
         conversionsDisk,
         source: { ...source, uuid },
         mutation
       });
+    },
+    operation: async (_mutation, generatedConversions) => {
+      const existing = collection2.singleFile ? await owner.getMedia(options.collectionName) : [];
       const max = await Media.query().where("model_type", ownerDefinition.morphClass).where("model_id", ownerId).where("collection_name", options.collectionName).max("order_column");
       const media = await Media.create({
         uuid,
@@ -1481,7 +1708,10 @@ function installEntityMediaMethods() {
     return new MediaAdder(this, source);
   };
   prototype.addMediaFromUrl = function addMediaFromUrl(url) {
-    return new MediaAdder(this, { url });
+    return new MediaAdder(this, new RemoteMediaSource(url));
+  };
+  prototype.addMediaFromDisk = function addMediaFromDisk(path, disk) {
+    return new MediaAdder(this, new StoredMediaSource(disk, path));
   };
   prototype.getMedia = async function getMedia(collectionName) {
     const query = createQuery(this, collectionName);
@@ -1800,7 +2030,6 @@ export {
   getMediaDefinition,
   getMediaDefinitionForMorphClass,
   getMediaPathGenerator,
-  mediaRuntimeInternals,
   normalizeCollectionDefinitions,
   normalizeConversionDefinitions,
   normalizeMediaConfig,