@zerotal/media 1.3.0

package/src/provider/MediaProvider.ts

@@ -0,0 +1,143 @@
+import { ServiceProvider } from "@zerotal/core";
+import type { AppEnvironment } from "@zerotal/core";
+import type { ConfigManager } from "@zerotal/core/config";
+import { MediaManager } from "../MediaManager.ts";
+import { BunImageDriver } from "../conversions/BunImageDriver.ts";
+import { SharpImageDriver } from "../conversions/SharpImageDriver.ts";
+import { setConversionDispatcher } from "../conversions/dispatch.ts";
+import { mediaDefaults, type MediaConfigShape } from "../config.ts";
+import { mediaSchemaConcern } from "../mediaSchemaConcern.ts";
+import { setMediaState } from "../state.ts";
+import { setPathGenerator } from "../MediaItem.ts";
+import { DefaultPathGenerator } from "../paths/PathGenerator.ts";
+import type { ImageDriver } from "../conversions/ImageDriver.ts";
+
+declare module "@zerotal/core" {
+  interface ContainerBindings {
+    media: MediaManager;
+  }
+}
+
+/**
+ * Registers the media system with the application.
+ *
+ * @example
+ * // bootstrap/providers.ts
+ * import { MediaProvider } from "@zerotal/media";
+ *
+ * export default [
+ *   DatabaseProvider,
+ *   StorageProvider, // media writes through disks — it needs this
+ *   MediaProvider,
+ * ];
+ *
+ * @example
+ * // config/media.ts
+ * import { MediaConfig } from "@zerotal/media";
+ * export default MediaConfig({ disk: "s3", driver: "sharp" });
+ */
+export class MediaProvider extends ServiceProvider {
+  static override provides = ["media"] as const;
+  static override environments: AppEnvironment[] = ["web", "console", "worker", "test", "repl"];
+
+  override onRegister(): void {
+    // Provision the media table on boot, after model discovery — no migration
+    // required. Idempotent, and skipped when autoCreateTable is off.
+    this.app.registerConcern?.(mediaSchemaConcern);
+
+    this.app.container.singleton("media", () => {
+      const config = this.resolveConfig();
+      const driver = _buildDriver(config);
+
+      setMediaState({ config, driver });
+      setPathGenerator(new DefaultPathGenerator());
+
+      return new MediaManager(config, driver);
+    });
+  }
+
+  override async onBooted(): Promise<void> {
+    // Pre-resolve so the MediaLibrary facade (makeSync) works after boot, and so the
+    // shared state is installed before the first request rather than on it.
+    const manager = (await this.app.container.make("media")) as MediaManager;
+
+    this.installQueueDispatcher();
+    await this.probeCodecs(manager);
+    this.registerCommands();
+  }
+
+  override async onStopping(): Promise<void> {
+    setConversionDispatcher(null);
+  }
+
+  /** Read `config/media.ts`, falling back to defaults field by field. */
+  private resolveConfig(): MediaConfigShape {
+    const config = this.app.container.tryMake("config") as ConfigManager | null;
+    const declared = config?.get<Partial<MediaConfigShape>>("media") ?? {};
+    return { ...mediaDefaults(), ...declared };
+  }
+
+  /**
+   * Wire queued conversions, but only when a queue actually exists.
+   *
+   * This is what keeps `@zerotal/media` free of a dependency on
+   * `@zerotal/queue`: the job class is imported lazily, inside the branch that
+   * already knows the binding is there.
+   */
+  private installQueueDispatcher(): void {
+    const queue = this.app.container.tryMake("queue");
+    if (!queue) {
+      setConversionDispatcher(null);
+      return;
+    }
+
+    setConversionDispatcher(async (mediaId, conversions) => {
+      const { dispatchConversionJob } = await import("../conversions/queueBridge.ts");
+      await dispatchConversionJob(mediaId, conversions);
+    });
+  }
+
+  /**
+   * Check once, at boot, which encoders this host actually has.
+   *
+   * `Bun.Image` encodes AVIF and HEIC through OS codecs that are missing on most
+   * Linux hosts. Without this the first sign of trouble is a queued job failing
+   * days later; with it, the boot log names the problem while someone is still
+   * looking at the deploy.
+   */
+  private async probeCodecs(manager: MediaManager): Promise<void> {
+    if (!manager.config.allowHostFormats) return;
+
+    const logger = this.app.container.tryMake("log") as
+      { warn(message: string): void } | null | undefined;
+    const missing: string[] = [];
+
+    for (const format of ["avif", "heic"] as const) {
+      if (!(await manager.driver.canEncode(format))) missing.push(format);
+    }
+
+    if (missing.length > 0) {
+      logger?.warn(
+        `[media] This host cannot encode ${missing.join(", ")} — conversions ` +
+          `targeting them will fail. Use jpeg, png or webp, or install the OS codec.`,
+      );
+    }
+  }
+
+  private registerCommands(): void {
+    const runner = this.app.container.tryMake("commands");
+    if (!runner) return;
+
+    runner.registerLazy("media:clean", () =>
+      import("../commands/MediaCleanCommand.ts").then((m) => m.MediaCleanCommand),
+    );
+    runner.registerLazy("media:regenerate", () =>
+      import("../commands/MediaRegenerateCommand.ts").then((m) => m.MediaRegenerateCommand),
+    );
+  }
+}
+
+/** Build the configured image driver. */
+function _buildDriver(config: MediaConfigShape): ImageDriver {
+  return config.driver === "sharp" ? new SharpImageDriver() : new BunImageDriver();
+}

package/src/sources.ts

@@ -0,0 +1,137 @@
+import { UploadedFile } from "@zerotal/core/http";
+import { MediaError } from "./errors.ts";
+import { diskFor } from "./support/disks.ts";
+
+/** A file's bytes plus the name it arrived under. */
+export interface ResolvedSource {
+  bytes: Uint8Array;
+  /** Original filename, used to derive the default media name. */
+  originalName: string;
+}
+
+/** Anything that can be resolved to bytes on demand. */
+export type SourceResolver = () => Promise<ResolvedSource>;
+
+/** Things `addMedia()` accepts directly. */
+export type MediaSource = UploadedFile | File | Blob | Uint8Array | ArrayBuffer;
+
+/**
+ * Turn an in-memory source into a lazy resolver.
+ *
+ * Resolution is deferred so a rule that can reject on metadata alone — a
+ * collection that accepts only PDFs, say — does not have to buffer the file
+ * first.
+ */
+export function fromValue(source: MediaSource, fileName?: string): SourceResolver {
+  if (source instanceof UploadedFile) {
+    return async () => ({
+      bytes: await source.bytes(),
+      originalName: fileName ?? source.originalName,
+    });
+  }
+
+  if (source instanceof File) {
+    return async () => ({
+      bytes: new Uint8Array(await source.arrayBuffer()),
+      originalName: fileName ?? source.name,
+    });
+  }
+
+  if (source instanceof Blob) {
+    return async () => ({
+      bytes: new Uint8Array(await source.arrayBuffer()),
+      originalName: fileName ?? "file",
+    });
+  }
+
+  if (source instanceof ArrayBuffer) {
+    return async () => ({ bytes: new Uint8Array(source), originalName: fileName ?? "file" });
+  }
+
+  if (source instanceof Uint8Array) {
+    return async () => ({ bytes: source, originalName: fileName ?? "file" });
+  }
+
+  throw new MediaError(
+    "addMedia() takes an UploadedFile, File, Blob, Uint8Array or ArrayBuffer. " +
+      "For a URL use addMediaFromUrl(), for a stored file addMediaFromDisk(), " +
+      "for a local path addMediaFromPath().",
+  );
+}
+
+/**
+ * Fetch a remote file.
+ *
+ * @param maxBytes - Refuse a response larger than this. A URL is attacker-supplied
+ *   often enough that downloading whatever arrives is how one request exhausts the
+ *   heap; the limit is checked against `Content-Length` first and again against
+ *   what actually arrived, since the header is a claim.
+ */
+export function fromUrl(url: string, maxBytes: number): SourceResolver {
+  return async () => {
+    let parsed: URL;
+    try {
+      parsed = new URL(url);
+    } catch {
+      throw new MediaError(`addMediaFromUrl() needs an absolute URL; got "${url}".`);
+    }
+
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      throw new MediaError(
+        `addMediaFromUrl() supports http and https; got "${parsed.protocol}".\n` +
+          "Fix: use addMediaFromPath() for a local file, addMediaFromDisk() for a stored one.",
+      );
+    }
+
+    const response = await fetch(parsed);
+    if (!response.ok) {
+      throw new MediaError(`Could not fetch ${url} — the server answered ${response.status}.`);
+    }
+
+    const declared = Number(response.headers.get("content-length") ?? "0");
+    if (declared > maxBytes) {
+      throw new MediaError(
+        `${url} declares ${declared} bytes, over the ${maxBytes}-byte limit. ` +
+          "Fix: raise media.maxConversionInputSize, or fetch and store it yourself.",
+      );
+    }
+
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if (bytes.byteLength > maxBytes) {
+      throw new MediaError(
+        `${url} returned ${bytes.byteLength} bytes, over the ${maxBytes}-byte limit.`,
+      );
+    }
+
+    return { bytes, originalName: _nameFromUrl(parsed) };
+  };
+}
+
+/** Read a file already sitting on one of the app's storage disks. */
+export function fromDisk(path: string, disk?: string): SourceResolver {
+  return async () => {
+    const bytes = await diskFor(disk).getBuffer(path);
+    if (bytes === null) {
+      throw new MediaError(`No file at "${path}" on disk "${disk ?? "default"}".`);
+    }
+    return { bytes, originalName: path.split("/").pop() ?? "file" };
+  };
+}
+
+/** Read a file from the local filesystem. */
+export function fromPath(path: string): SourceResolver {
+  return async () => {
+    const file = Bun.file(path);
+    if (!(await file.exists())) throw new MediaError(`No file at "${path}".`);
+    return {
+      bytes: new Uint8Array(await file.arrayBuffer()),
+      originalName: path.split(/[/\\]/).pop() ?? "file",
+    };
+  };
+}
+
+/** The filename a URL implies, ignoring query and fragment. */
+function _nameFromUrl(url: URL): string {
+  const last = url.pathname.split("/").filter(Boolean).pop();
+  return last !== undefined && last !== "" ? decodeURIComponent(last) : "file";
+}

package/src/state.ts

@@ -0,0 +1,36 @@
+import { BunImageDriver } from "./conversions/BunImageDriver.ts";
+import { mediaDefaults, type MediaConfigShape } from "./config.ts";
+import type { ImageDriver } from "./conversions/ImageDriver.ts";
+
+/** The resolved config and image driver the package operates with. */
+export interface MediaState {
+  config: MediaConfigShape;
+  driver: ImageDriver;
+}
+
+let _state: MediaState | null = null;
+
+/**
+ * The active media state.
+ *
+ * `MediaProvider` installs the real one at boot. Falling back to defaults rather
+ * than throwing keeps the model usable in a unit test that never builds an
+ * application — which is most tests that touch a model.
+ */
+export function mediaState(): MediaState {
+  if (_state === null) {
+    const config = mediaDefaults();
+    _state = { config, driver: new BunImageDriver() };
+  }
+  return _state;
+}
+
+/** Install the resolved state. Called by `MediaProvider`. */
+export function setMediaState(state: MediaState): void {
+  _state = state;
+}
+
+/** Drop the state so the next read rebuilds it from defaults. For tests. */
+export function resetMediaState(): void {
+  _state = null;
+}

package/src/support/disks.ts

@@ -0,0 +1,78 @@
+import { tryCurrentApp } from "@zerotal/core";
+import { Storage } from "@zerotal/core/storage";
+import type { StorageDriver } from "@zerotal/core/storage";
+
+/**
+ * How this package gets hold of a disk.
+ *
+ * `undefined` means "the default disk", matching `StorageManager.disk()`.
+ */
+export type DiskResolver = (name?: string) => StorageDriver;
+
+let _resolver: DiskResolver | null = null;
+
+/**
+ * Override how disks are resolved.
+ *
+ * The default path goes through the `Storage` facade, which needs an ambient
+ * application. That is right in an app and awkward in a unit test, which has a
+ * `StorageManager` in hand and no reason to build a container around it — so
+ * this is the seam. Pass `null` to restore facade resolution.
+ *
+ * `Storage.fake()` still works either way: it swaps the driver inside the
+ * manager, so whichever manager is resolved is the one that was faked.
+ */
+export function setDiskResolver(resolver: DiskResolver | null): void {
+  _resolver = resolver;
+}
+
+/**
+ * Resolve a disk by name, treating empty/absent as "the configured default".
+ *
+ * `StorageManager.disk()` falls back to the default only for `undefined` — an
+ * empty string is looked up literally and throws `DiskNotConfiguredError`. Media
+ * config uses `""` to mean "inherit the default", so every lookup goes through
+ * here rather than reaching for `Storage.disk()` directly.
+ */
+export function diskFor(name?: string | null): StorageDriver {
+  const trimmed = name?.trim();
+  const resolved = trimmed !== undefined && trimmed !== "" ? trimmed : undefined;
+
+  if (_resolver !== null) return _resolver(resolved);
+  return resolved === undefined ? Storage.disk() : Storage.disk(resolved);
+}
+
+/** The name a disk reference resolves to, for storing in the `disk` column. */
+export function diskNameFor(name: string | null | undefined, fallback: string): string {
+  const trimmed = name?.trim();
+  return trimmed !== undefined && trimmed !== "" ? trimmed : fallback;
+}
+
+let _defaultName: string | null = null;
+
+/** Override the recorded default disk name. Pass `null` to read it from config. */
+export function setDefaultDiskName(name: string | null): void {
+  _defaultName = name;
+}
+
+/**
+ * The concrete name of the default disk, e.g. `"local"`.
+ *
+ * Media rows record the disk they were written to by name rather than storing
+ * `""` and re-resolving on read. An app that later flips `storage.default` from
+ * `local` to `s3` would otherwise find every existing media row suddenly
+ * claiming to live on S3, where none of the files are.
+ *
+ * Falls back to `""` when there is no app or no storage config to ask — the read
+ * path treats that as "the default", which is the best answer available.
+ */
+export function defaultDiskName(): string {
+  if (_defaultName !== null) return _defaultName;
+  try {
+    const config = tryCurrentApp()?.container.tryMake("config") as
+      { get<T>(path: string, fallback?: T): T | undefined } | null | undefined;
+    return config?.get<string>("storage.default", "") ?? "";
+  } catch {
+    return "";
+  }
+}

package/src/types.ts

@@ -0,0 +1,139 @@
+// ── Public types for @zerotal/media ──────────────────────────────────────────
+
+/**
+ * Output formats a conversion may target.
+ *
+ * Deliberately narrower than what {@link https://bun.sh/docs/api/image | Bun.Image}
+ * can emit. `Bun.Image` reports `backend: "system"`, meaning AVIF/HEIC/TIFF encode
+ * through OS codecs that are simply absent on many hosts — a conversion that works
+ * on a developer's laptop then fails inside a queued job on an Alpine container.
+ * These three are available everywhere.
+ *
+ * Need AVIF? Set `allowHostFormats` in config and use {@link ConversionFormat} —
+ * the boot probe will tell you whether this host can actually do it.
+ */
+export type SafeConversionFormat = "jpeg" | "png" | "webp";
+
+/** Every format the image driver may be asked for, including host-dependent ones. */
+export type ConversionFormat = SafeConversionFormat | "avif" | "heic";
+
+/**
+ * How a source image is fitted into the target box.
+ *
+ * - `inside` — scale down to fit within `width` × `height`, preserving aspect
+ *   ratio. The result may be smaller than the box in one dimension.
+ * - `fill` — stretch to exactly `width` × `height`, ignoring aspect ratio.
+ * - `cover` — scale and centre-crop to exactly fill the box, preserving aspect
+ *   ratio. **Requires an image driver that can crop**; the default
+ *   `BunImageDriver` cannot, and says so with a named error.
+ */
+export type ConversionFit = "inside" | "fill" | "cover";
+
+/** A single derived image generated from an original. */
+export interface ConversionDefinition {
+  /** Target width in pixels. At least one of `width`/`height` is required. */
+  width?: number;
+  /** Target height in pixels. */
+  height?: number;
+  /** How to fit the source into the box. Default: `"inside"`. */
+  fit?: ConversionFit;
+  /** Output format. Default: the original's format when safe, else `"jpeg"`. */
+  format?: ConversionFormat;
+  /** Encoder quality, 1–100. Default: 82. */
+  quality?: number;
+  /** Clockwise rotation in degrees applied before resizing. */
+  rotate?: number;
+  /** Generate this conversion on the queue instead of inline. Default: `false`. */
+  queued?: boolean;
+}
+
+/** A named set of conversions. */
+export type ConversionMap = Record<string, ConversionDefinition>;
+
+/** Declarative rules for one media collection. */
+export interface CollectionDefinition {
+  /** Disk originals are written to. Default: the configured default disk. */
+  disk?: string;
+  /** Disk conversions are written to. Default: whatever `disk` resolves to. */
+  conversionsDisk?: string;
+  /**
+   * Allowed MIME types. Checked against the type **sniffed from the file's own
+   * bytes**, never the client-supplied one, so renaming `payload.html` to
+   * `photo.jpg` does not get past it.
+   */
+  accepts?: string[];
+  /** Maximum accepted size in bytes for a single file. */
+  maxSize?: number;
+  /** Keep only the most recently added file; adding a second removes the first. */
+  single?: boolean;
+  /** Keep only the `n` most recent files, removing older ones as they fall out. */
+  onlyKeepLatest?: number;
+  /** URL returned by `getFirstMediaUrl()` when the collection is empty. */
+  fallbackUrl?: string;
+  /** Path returned by `getFirstMediaPath()` when the collection is empty. */
+  fallbackPath?: string;
+  /** Conversions generated for files in this collection. */
+  conversions?: ConversionMap;
+  /**
+   * Generate a responsive width ladder plus an inline blur placeholder.
+   * `true` uses the configured default widths; an array pins them explicitly.
+   */
+  responsive?: boolean | number[];
+}
+
+/**
+ * The collections a model declares, as the static `mediaCollections` field.
+ *
+ * A function is accepted for values only known at runtime (a per-tenant disk,
+ * say); it is called once per operation, not cached.
+ */
+export type MediaCollections = Record<string, CollectionDefinition | (() => CollectionDefinition)>;
+
+/** What a generated conversion records in the `generated_conversions` column. */
+export interface GeneratedConversion {
+  /** File name on the conversions disk, e.g. `thumb.webp`. */
+  fileName: string;
+  /** Bytes written. */
+  size: number;
+  /** MIME type of the generated file. */
+  mimeType: string;
+  width: number;
+  height: number;
+  /** ISO-8601 timestamp of generation. */
+  generatedAt: string;
+}
+
+/** One entry in the responsive width ladder. */
+export interface ResponsiveImage {
+  fileName: string;
+  width: number;
+  height: number;
+}
+
+/** The `responsive_images` column payload. */
+export interface ResponsiveImageSet {
+  /** Generated widths, ascending. */
+  images: ResponsiveImage[];
+  /** A `data:image/png;base64,…` low-quality placeholder, when one was produced. */
+  placeholder?: string;
+}
+
+/** Metadata carried alongside a file being added to a collection. */
+export interface PendingMediaMeta {
+  /** Human-facing label. Defaults to the original filename without extension. */
+  name?: string;
+  /** Arbitrary JSON stored in `custom_properties`. */
+  customProperties?: Record<string, unknown>;
+  /** Explicit sort position. Defaults to the end of the collection. */
+  order?: number;
+  /** Override the collection's disk for this one file. */
+  disk?: string;
+}
+
+/** The minimum a model must expose for media to attach to it. */
+export interface MediaOwner {
+  /** Primary key. */
+  id: number | string;
+  /** Discriminator written to `model_type`. */
+  readonly constructor: { name: string };
+}