@michaelthielemann/kestrel 3.0.1 → 4.0.1

package/layers/media/server/utils/media-ops.ts

@@ -1,118 +0,0 @@
-import { eq, inArray, or, getTableColumns, sql } from 'drizzle-orm'
-import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
-import { findMediaUsagesForMany, type MediaUsage } from './usages'
-import type { AnySQLiteTable } from 'drizzle-orm/sqlite-core'
-import { media } from '../collections/media'
-import { folders } from '../database/folders'
-import { isUnder } from './folder-paths'
-import type { DerivativeManifest } from './record'
-import { emitMediaWrite } from './media-write'
-import type { StorageDriver } from '../../../core/server/utils/storage'
-import { escapeLike } from '../../../core/server/utils/sql'
-
-export type OpItem = { type: 'file'; id: number } | { type: 'folder'; path: string }
-
-export interface AffectedMedia {
-  id: number; storageKey: string; folder: string | null; filename: string
-  size: number; derivatives: DerivativeManifest | null
-}
-export interface AffectedSet { media: AffectedMedia[]; folders: string[] }
-
-/** Resolve op items into the concrete affected media rows + folder paths. A `folder` item
- *  expands to itself + every descendant (media + folder rows). Folders are returned deepest-first
- *  (so a delete removes children before parents); media is deduped by id. */
-export function collectAffected(db: BetterSQLite3Database, items: OpItem[]): AffectedSet {
-  const cols = getTableColumns(media) as Record<string, never>
-  const t = media as AnySQLiteTable
-  const mediaById = new Map<number, AffectedMedia>()
-  const folderSet = new Set<string>()
-  // Only a folder item ever consults the full folder list (to find its descendants) — an all-file list
-  // never touches it, so skip the read rather than materialize every row for nothing.
-  const allFolders = items.some((i) => i.type === 'folder')
-    ? db.select({ path: folders.path }).from(folders).all().map((f) => f.path)
-    : []
-
-  const add = (rows: Record<string, unknown>[]) => {
-    for (const r of rows) mediaById.set(r.id as number, {
-      id: r.id as number, storageKey: r.storageKey as string, folder: (r.folder as string | null) ?? null,
-      filename: r.filename as string, size: r.size as number, derivatives: (r.derivatives as DerivativeManifest | null) ?? null,
-    })
-  }
-
-  for (const item of items) {
-    if (item.type === 'file') {
-      const row = db.select().from(t).where(eq(cols.id, item.id)).get() as Record<string, unknown> | undefined
-      if (row) add([row])
-    } else {
-      for (const fp of allFolders) if (isUnder(item.path, fp)) folderSet.add(fp)
-      folderSet.add(item.path)
-      const rows = db.select().from(t).where(
-        or(eq(cols.folder, item.path), sql`${cols.folder} like ${`${escapeLike(item.path)}/%`} escape '\\'`),
-      ).all() as Record<string, unknown>[]
-      add(rows)
-    }
-  }
-
-  const folderList = [...folderSet].sort((a, b) => b.split('/').length - a.split('/').length)
-  return { media: [...mediaById.values()], folders: folderList }
-}
-
-/** Reverse-usage lookup for many media ids at once: id -> the records referencing it. */
-export function bulkUsages(db: BetterSQLite3Database, ids: number[]): Record<number, MediaUsage[]> {
-  return findMediaUsagesForMany(db, ids)
-}
-
-export interface DeleteReport {
-  summary: { files: number; folders: number; totalBytes: number }
-  usages?: Record<number, MediaUsage[]>
-  /** storageKeys whose blob delete failed — the row is already gone (rows commit before storage), so a
-   *  failure here is an orphaned object, not a retryable half-delete; surfaced for the caller to log/alert. */
-  failedKeys?: string[]
-}
-
-/** Two-wave delete. dryRun → report impact + per-media usages, no mutation. Otherwise → delete
- *  all affected media rows + folder rows in one transaction, then delete the storage objects
- *  (original + derivatives). Folder cascade included. */
-export async function deleteAffected(
-  db: BetterSQLite3Database, driver: StorageDriver, items: OpItem[], dryRun: boolean,
-): Promise<DeleteReport> {
-  const affected = collectAffected(db, items)
-  const summary = {
-    files: affected.media.length,
-    folders: affected.folders.length,
-    totalBytes: affected.media.reduce((n, m) => n + (m.size || 0), 0),
-  }
-  if (dryRun) return { summary, usages: bulkUsages(db, affected.media.map((m) => m.id)) }
-
-  const cols = getTableColumns(media) as Record<string, never>
-  const mediaIds = affected.media.map((m) => m.id)
-  db.transaction((tx) => {
-    if (mediaIds.length) tx.delete(media).where(inArray(cols.id, mediaIds)).run()
-    if (affected.folders.length) tx.delete(folders).where(inArray(folders.path, affected.folders)).run()
-  })
-
-  // Best-effort per item: the rows are already committed gone, so a storage error here means an orphan
-  // object, not a rollback candidate — one bad key (a throttled/5xx S3 call) must not abort the loop and
-  // leave every LATER item's blobs undeleted too with no row left to find them again.
-  const failedKeys: string[] = []
-  for (const m of affected.media) {
-    try {
-      await driver.delete(m.storageKey)
-      for (const d of Object.values(m.derivatives ?? {})) await driver.delete(d.key)
-    } catch (error) {
-      console.error(`[kestrel] media storage delete failed for ${m.storageKey}:`, (error as Error)?.message ?? error)
-      failedKeys.push(m.storageKey)
-    }
-    emitMediaWrite({ id: m.id }, null) // deleted media → re-render listings that query it
-  }
-  // Clean up the folder dir ONLY when nothing unmanaged remains under it. removeDir is a recursive subtree
-  // wipe, so a blind call would destroy any non-media object living under the same path — e.g. an extension's
-  // encrypted blob namespace, or any consumer blob written via useStorageDriver — which no media row (and no
-  // dryRun count) accounts for. If anything is still there, leave the whole path alone.
-  for (const it of items) {
-    if (it.type !== 'folder') continue
-    const remaining = driver.listPrefix ? await driver.listPrefix(it.path) : ['guard']
-    if (remaining.length === 0) await driver.removeDir?.(it.path)
-  }
-  return failedKeys.length ? { summary, failedKeys } : { summary }
-}

package/layers/media/server/utils/media-write.ts

@@ -1,13 +0,0 @@
-import { emitWrite } from '../../../core/server/utils/write-events'
-import mediaCollection from '../collections/media'
-
-/**
- * Notify the publish runtime that a media row changed. The media-library write paths (relocate / duplicate
- * / delete / alt-edit) bypass core CRUD, so — unlike a normal content write — they emit no write event on
- * their own. Without this, a page that embeds the media (dep-tagged `media:<id>`) is never re-rendered, so
- * the static output keeps the old (now 404) URL or stale alt text. `before`/`after` need only carry `id`
- * for the media classification (non-pageLike, no status column).
- */
-export function emitMediaWrite(before: Record<string, unknown> | null, after: Record<string, unknown> | null): void {
-  emitWrite(mediaCollection.def, before, after)
-}

package/layers/media/server/utils/naming.ts

@@ -1,52 +0,0 @@
-export function sanitizeFilename(name: string): string {
-  const base = name.split(/[/\\]/).pop() ?? ''
-  const cleaned = base.replace(/ /g, '_').replace(/[^A-Za-z0-9._-]+/g, '_').replace(/_+/g, '_').slice(0, 120)
-  if (cleaned === '' || cleaned === '.' || cleaned === '..') return 'file'
-  return cleaned
-}
-
-/** The last extension of a filename (no leading dot), or '' when there is none. */
-export function extensionOf(name: string): string {
-  const dot = name.lastIndexOf('.')
-  return dot > 0 ? name.slice(dot + 1) : ''
-}
-
-/** Sanitize `name` and force its extension to `ext` (drops any client-supplied extension).
- *  The stored extension must follow the authenticated content type, never the upload filename. */
-export function withExtension(name: string, ext: string): string {
-  const cleaned = sanitizeFilename(name)
-  const dot = cleaned.lastIndexOf('.')
-  const stem = dot > 0 ? cleaned.slice(0, dot) : cleaned
-  return ext ? `${stem}.${ext}` : stem
-}
-
-/** Safe relative folder: drops `.`/`..` segments (no traversal) and cleans each segment.
- *  Deliberately NOT length-capped: truncating would silently map two distinct folders onto one
- *  storage path. An unusable path is caught where it is created — folders.post.ts runs `ensureDir`
- *  before committing the row, so an over-long name fails there instead of stranding a row. */
-export function sanitizeFolder(folder: string): string {
-  return folder
-    .split(/[/\\]+/)
-    .map((seg) => seg.trim())
-    .filter((seg) => seg && seg !== '.' && seg !== '..')
-    .map((seg) => seg.replace(/ /g, '_').replace(/[^A-Za-z0-9._-]+/g, '_').replace(/_+/g, '_'))
-    .filter((seg) => seg.length > 0)
-    .join('/')
-}
-
-export function buildKey(folder: string, filename: string): string {
-  const f = sanitizeFolder(folder)
-  return f ? `${f}/${filename}` : filename
-}
-
-export function suggestFreeName(filename: string, isFree: (name: string) => boolean): string {
-  if (isFree(filename)) return filename
-  const dot = filename.lastIndexOf('.')
-  const stem = dot > 0 ? filename.slice(0, dot) : filename
-  const ext = dot > 0 ? filename.slice(dot) : ''
-  for (let i = 2; i < 10000; i++) {
-    const candidate = `${stem}-${i}${ext}`
-    if (isFree(candidate)) return candidate
-  }
-  throw new Error('no free filename found')
-}

package/layers/media/server/utils/ondemand.ts

@@ -1,69 +0,0 @@
-import { inArray, getTableColumns } from 'drizzle-orm'
-import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
-import type { ResolvedImagePolicy, VariantFit } from '../../../core/server/utils/kestrel-config'
-import type { StorageDriver } from '../../../core/server/utils/storage'
-import { media } from '../collections/media'
-import { deriveImage, RASTER } from './derive'
-
-const FITS = new Set<VariantFit>(['cover', 'contain', 'inside', 'outside', 'fill'])
-
-/** The storage key a request addresses, or null when the request is not for media at all: outside the
- *  configured base URL, bare, or carrying a malformed %-escape (which must degrade to a static 404, never
- *  a 500). `baseUrl` is the media base as resolved config holds it — its default is the same `/uploads`. */
-export function variantKeyFromPath(path: string, baseUrl: string | undefined): string | null {
-  const base = (baseUrl || '/uploads').replace(/\/+$/, '')
-  const clean = path.split('?')[0]!
-  if (!clean.startsWith(`${base}/`)) return null
-  try {
-    return decodeURIComponent(clean.slice(base.length + 1)) || null
-  } catch {
-    return null
-  }
-}
-
-/** Inverse of variantName: `w<width>` | `c<w>x<h>[-<fit>]` → the shape to derive, or null for anything else. */
-export function parseVariantName(name: string): { width: number; height: number | null; fit: VariantFit } | null {
-  const w = /^w(\d+)$/.exec(name)
-  if (w) return { width: +w[1], height: null, fit: 'cover' }
-  const c = /^c(\d+)x(\d+)(?:-([a-z]+))?$/.exec(name)
-  if (c) {
-    const fit = (c[3] ?? 'cover') as VariantFit
-    return FITS.has(fit) ? { width: +c[1], height: +c[2], fit } : null
-  }
-  return null
-}
-
-export interface VariantRequest { storageKey: string; mime: string; name: string; format: string }
-
-// requestedKey is `<storageKey>-<name>.<format>`; storageKey contains dots and a name may contain '-', so
-// resolve the original by trying every '-' split and matching a real media row (longest storageKey wins).
-export function resolveVariantRequest(db: BetterSQLite3Database, requestedKey: string): VariantRequest | null {
-  const dot = requestedKey.lastIndexOf('.')
-  if (dot < 0) return null
-  const format = requestedKey.slice(dot + 1)
-  const stem = requestedKey.slice(0, dot)
-  const candidates: string[] = []
-  for (let i = 1; i < stem.length; i++) if (stem[i] === '-') candidates.push(stem.slice(0, i))
-  if (!candidates.length) return null
-  const cols = getTableColumns(media) as Record<string, never>
-  const rows = db.select({ storageKey: cols.storageKey, mime: cols.mime }).from(media).where(inArray(cols.storageKey, candidates)).all() as { storageKey: string; mime: string }[]
-  const match = rows.map((r) => ({ ...r, name: stem.slice(r.storageKey.length + 1), format })).sort((a, b) => b.storageKey.length - a.storageKey.length)[0]
-  return match ?? null
-}
-
-const MEDIA_CACHE_CONTROL = 'public, max-age=31536000'
-
-// DEV-only: derive one missing variant from the stored original and cache it. Registry-INDEPENDENT (parses
-// the name), so a size/format a KestrelImg declares but the scan hasn't registered yet still shows in the
-// editor preview without a full publish.
-export async function deriveOnDemand(db: BetterSQLite3Database, driver: StorageDriver, policy: ResolvedImagePolicy, requestedKey: string): Promise<{ bytes: Buffer; mime: string } | null> {
-  const req = resolveVariantRequest(db, requestedKey)
-  if (!req || !RASTER.has(req.mime) || (req.format !== 'webp' && req.format !== 'jpeg')) return null
-  const shape = parseVariantName(req.name)
-  if (!shape || typeof driver.get !== 'function') return null
-  const spec = { name: req.name, width: shape.width, height: shape.height, fit: shape.fit, position: 'centre', formats: [req.format] as ('webp' | 'jpeg')[] }
-  const v = (await deriveImage(await driver.get(req.storageKey), { ...policy, variants: [spec] })).variants[0]
-  if (!v) return null
-  await driver.put(requestedKey, v.bytes, v.mime, { cacheControl: MEDIA_CACHE_CONTROL })
-  return { bytes: v.bytes, mime: v.mime }
-}

package/layers/media/server/utils/persist-upload.ts

@@ -1,62 +0,0 @@
-import { eq, getTableColumns } from 'drizzle-orm'
-import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
-import { media } from '../collections/media'
-import { derivativeKey, withPreservedTranslations, type DerivativeManifest } from './record'
-import type { DerivedImage } from './derive'
-import type { StorageDriver } from '../../../core/server/utils/storage'
-import type { Translations } from './translations'
-
-// Long-lived (non-immutable, so a replace isn't pinned) cache for originals + derivatives — effective on
-// the S3 driver, ignored by the local driver (NGINX owns its cache). Mirrors the header in backfill.ts.
-export const MEDIA_CACHE_CONTROL = 'public, max-age=31536000'
-
-export interface PersistArgs {
-  storageKey: string
-  bytes: Buffer
-  mime: string
-  derived?: DerivedImage
-  values: Record<string, unknown>
-  existing?: { id: number; derivatives?: DerivativeManifest; translations?: Translations }
-  overwrite: boolean
-}
-
-/**
- * Write the original + derivative objects and insert/update the media row. On the CREATE path (no
- * pre-existing row) a failure at ANY step removes every blob written during the attempt — otherwise a
- * partial write (an S3 hiccup mid-derivative, a lost INSERT race) strands orphan blobs that permanently
- * 409-block the filename (overwrite can't reclaim a row-less key, and no reconcile removes them). The
- * OVERWRITE path leaves the (pre-existing) original in place on failure — it was there before this upload.
- */
-export async function persistUpload(db: BetterSQLite3Database, driver: StorageDriver, args: PersistArgs): Promise<Record<string, unknown>> {
-  const { storageKey, bytes, mime, derived, values, existing, overwrite } = args
-  const cols = getTableColumns(media) as Record<string, never>
-  const isOverwrite = !!(existing && overwrite)
-  const derivKeys = (derived?.variants ?? []).map((v) => derivativeKey(storageKey, v.name, v.format))
-
-  try {
-    await driver.put(storageKey, bytes, mime, { cacheControl: MEDIA_CACHE_CONTROL })
-    for (const v of derived?.variants ?? []) {
-      await driver.put(derivativeKey(storageKey, v.name, v.format), v.bytes, v.mime, { cacheControl: MEDIA_CACHE_CONTROL })
-    }
-    if (isOverwrite) {
-      // Drop any old derivative objects the new manifest no longer references, then update the row.
-      const newKeys = new Set(Object.values(values.derivatives as DerivativeManifest).map((d) => d.key))
-      for (const old of Object.values(existing!.derivatives ?? {})) {
-        if (!newKeys.has(old.key)) await driver.delete(old.key)
-      }
-      // Re-read translations fresh, right before the merge — `existing` was captured by the caller BEFORE
-      // the (potentially slow) driver.put calls above; a concurrent alt-text PATCH landing during that
-      // window would otherwise be silently reverted by merging the pre-I/O snapshot.
-      const fresh = db.select({ translations: cols.translations }).from(media)
-        .where(eq(cols.storageKey, storageKey)).get() as { translations?: Translations } | undefined
-      return db.update(media).set({ ...withPreservedTranslations(values, fresh ?? existing), updatedAt: new Date() })
-        .where(eq(cols.storageKey, storageKey)).returning().get() as Record<string, unknown>
-    }
-    return db.insert(media).values(values as never).returning().get() as Record<string, unknown>
-  } catch (error) {
-    if (!isOverwrite) {
-      for (const k of [storageKey, ...derivKeys]) await driver.delete(k).catch(() => {})
-    }
-    throw error
-  }
-}

package/layers/media/server/utils/populate.ts

@@ -1,47 +0,0 @@
-import { fieldIs } from '../../../core/server/utils/defineCollection'
-import type { FieldPopulator } from '../../../core/server/utils/populate'
-import { memoDuringPrerender } from '../../../core/server/utils/prerender-memo'
-import { memoResolver } from '../../../core/server/utils/resolve-scope'
-import { captureRead } from '../../../core/server/utils/read-capture'
-import type { ResolvedMedia } from './resolve'
-
-export type ResolveById = (id: number, locale: string) => ResolvedMedia | null
-
-function attach(target: Record<string, unknown>, key: string, value: unknown): void {
-  // Clone the existing $media bag rather than mutate it in place: if `target` is a shallow clone that
-  // happens to share a pre-existing $media sidecar with the stored row, in-place mutation would leak into
-  // the original. No current caller feeds a $media-bearing bag into the walker, but this keeps the
-  // populator unconditionally non-destructive (future-proof against a double-populate / pre-seeded bag).
-  target.$media = { ...((target.$media as Record<string, unknown> | undefined) ?? {}), [key]: value }
-}
-
-/**
- * The `media` field populator: resolves a media id (single, key `${name}Id` in columns / bare `name` in
- * props) or id array (multiple, always bare) to a `ResolvedMedia` under the row/entry's `$media` bag,
- * leaving the raw id column untouched. Registered per-type via `registerFieldPopulator('media', …)`; the
- * shared field-tree walker drives it over top-level fields, block props, and (now) repeater entries.
- */
-export function buildMediaFieldPopulator(resolveById: ResolveById): FieldPopulator {
-  // The same media id+locale is resolved once — build-wide during a generate run, request-/publish-run-
-  // wide via the resolve scope (which also budgets one live request's distinct fan-out).
-  // memoResolver OUTERMOST so a per-scope budget-skip null is never cached build-wide by the prerender memo.
-  const key = (id: number, locale: string) => `media:${id}:${locale}`
-  const resolve = memoResolver(memoDuringPrerender(resolveById, key), key)
-  return (bag, key, field, ctx, keyMode) => {
-    if (!fieldIs(field, 'media')) return
-    // captureRead runs even on a memo hit (each embedding page must record the dep), so it sits here, not
-    // inside `resolve`: it durably ties this render's route to `media:<id>`, so a later media change
-    // (rename/move/alt-edit) re-renders the page instead of leaving a stale/broken image in the static output.
-    if (!field.options?.multiple) {
-      const id = bag[keyMode === 'columns' ? `${key}Id` : key]
-      if (typeof id === 'number') { captureRead('media', id); attach(bag, key, resolve(id, ctx.locale)) }
-    } else {
-      const ids = bag[key]
-      if (Array.isArray(ids)) {
-        const nums = ids.filter((x): x is number => typeof x === 'number')
-        for (const id of nums) captureRead('media', id)
-        attach(bag, key, nums.map((id) => resolve(id, ctx.locale)))
-      }
-    }
-  }
-}

package/layers/media/server/utils/record.ts

@@ -1,71 +0,0 @@
-import type { DerivedImage } from './derive'
-import { mergeTranslations, type Translations } from './translations'
-
-export interface DerivativeEntry { key: string; width: number; height: number; mime: string }
-export type DerivativeManifest = Record<string, DerivativeEntry>
-
-export interface MediaInput {
-  storageKey: string
-  folder: string
-  filename: string
-  mime: string
-  ext: string
-  size: number
-  checksum: string
-  derived?: DerivedImage
-  translations?: Record<string, { alt?: string; title?: string; description?: string }>
-  /** EU AI Act disclosure to write. Omitted/null ⇒ the column is left out of the values entirely, which is
-   *  what keeps an overwrite from wiping a disclosure the re-upload did not re-send. */
-  aiSourceType?: string | null
-  aiNote?: string | null
-}
-
-/**
- * Object key for a resized/reformatted variant of an original. The stem is the FULL original key
- * (extension included), so two same-stem uploads that differ only in extension — `logo.png` and
- * `logo.jpg`, a designer exporting both formats — never derive the same key and overwrite/cross-delete
- * each other's variants. `storageKey` is unique, so this stays injective per original.
- */
-export function derivativeKey(originalKey: string, name: string, format: string): string {
-  return `${originalKey}-${name}.${format}`
-}
-
-export function buildMediaValues(input: MediaInput): Record<string, unknown> {
-  const manifest: DerivativeManifest = {}
-  const src = input.derived
-  for (const v of src?.variants ?? []) {
-    // Name-keyed (`<name>.<format>`); height is the variant's REAL output dim (crops break the aspect ratio).
-    manifest[`${v.name}.${v.format}`] = { key: derivativeKey(input.storageKey, v.name, v.format), width: v.width, height: v.height, mime: v.mime }
-  }
-  return {
-    storageKey: input.storageKey,
-    folder: input.folder || null,
-    filename: input.filename,
-    mime: input.mime,
-    ext: input.ext,
-    size: input.size,
-    width: input.derived?.width ?? null,
-    height: input.derived?.height ?? null,
-    checksum: input.checksum,
-    thumbhash: input.derived?.thumbhash ?? null,
-    derivatives: manifest,
-    translations: input.translations ?? {},
-    // Written only when there is something to write: the overwrite path feeds these same values to an
-    // UPDATE, and a null here would silently clear a disclosure an editor set on the existing row.
-    ...(input.aiSourceType != null ? { aiSourceType: input.aiSourceType } : {}),
-    ...(input.aiNote != null ? { aiNote: input.aiNote } : {}),
-  }
-}
-
-/**
- * On overwrite (re-upload of an existing storageKey) the multipart request rarely re-sends
- * alt/title/description — the conflict-dialog overwrite path never does — so a bare re-upload must not
- * wipe the per-locale metadata editors maintain via the viewer. Merge any incoming fields over the
- * existing map (same semantics as the PATCH endpoint); an empty incoming map leaves the existing intact.
- */
-export function withPreservedTranslations(
-  values: Record<string, unknown>,
-  existing: { translations?: Translations } | undefined,
-): Record<string, unknown> {
-  return { ...values, translations: mergeTranslations(existing?.translations, (values.translations ?? {}) as Translations) }
-}