lecodes-sdk 2.0.6 → 2.0.8

package/src/server/files/host.ts

@@ -0,0 +1,496 @@
+/**
+ * The HOST's half of stored files (./models.ts) — the same code on the runner and under `lecodes dev`.
+ * Never bundled into project code.
+ *
+ * The bytes of a file are one file on disk, `<dir>/<id>`, named by its `File` row. Three steps:
+ *
+ *   receiveUploads   the process that owns the socket reads a multipart endpoint call: the files go to
+ *                    `<dir>/tmp/<id>`, what is known of them travels to the worker in the request
+ *                    context (`uploads`), the arguments keep `{ "$file": <index> }` in their places
+ *   createFilesHost  the worker, around every endpoint call: `adopt` gives each upload its `File` row
+ *                    (ownerless) and moves the bytes into place — the endpoint gets a `File` it can
+ *                    write to a `t.file()` field; `finish` deletes the uploads the endpoint attached
+ *                    to nothing, then removes the bytes of every row the database let go of
+ *   fileResponse     `GET <base>/files/<id>/<name>`
+ *
+ * An upload written to a `t.image()` field is rewritten before its row is attached (`seam.image`):
+ * turned as its Exif says, its metadata dropped, no larger than the field's `max`, WebP. The codec is
+ * sharp, which the host process brings (`FilesHostConfig.sharp`) — this package does not depend on it.
+ * sharp's own builds read no HEIC (an iPhone's photo as it is stored): a host that also brings
+ * `heic-decode` (libheif as wasm, `FilesHostConfig.heic`) has those decoded by it, and sharp is handed
+ * the pixels.
+ *
+ * One rule decides when bytes are removed: the `File` row was deleted. However it went — a field was
+ * given another file, its row was deleted, a cascade took it — marcidb's journal of the model says so
+ * (`$journal`, deletes), and `finish` reads it. Rows are the truth; a start reconciles the folder with
+ * them once, for the case where the database itself was replaced under the files (a reset, a schema
+ * that could not be migrated).
+ */
+
+import { createReadStream } from "node:fs"
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises"
+import { join } from "node:path"
+import { Readable } from "node:stream"
+import { currentRequest, type RequestContext } from "../context"
+import type { MarciOp, MarciTransport } from "../db/marci/query"
+import type { Db } from "../db/types"
+import { FILE_MODEL, setFilesSeam, type FilesSeam, type ImageFacts, type ImageRule } from "./models"
+
+/** What the receiving process knows of one uploaded file; its bytes are in `<dir>/tmp/<id>`. */
+export type Upload = { id: string, name: string, type: string, size: number, width?: number, height?: number }
+
+export type UploadLimits = {
+  /** One file, bytes (default 10 MB). */
+  maxFile?: number
+  /** Files in one call (default 10). */
+  maxFiles?: number
+}
+
+/** A refused upload: `status` is what the endpoint call answers with. */
+export class UploadError extends Error {
+  readonly status: number
+  constructor(status: number, message: string) {
+    super(message)
+    // read by the invoker the way a project's own ApiError is
+    this.name = "ApiError"
+    this.status = status
+  }
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+const JOURNAL = "lecodes-files"
+const MB = 1024 * 1024
+const TMP_MAX_AGE_MS = 60 * 60 * 1000
+/** The most pixels a picture may have to be decoded at all: a small file can claim a huge frame. */
+const MAX_IMAGE_PIXELS = 50_000_000
+const WEBP_QUALITY = 80
+
+// ───────────────────────────── what a file is ─────────────────────────────
+
+const ascii = (b: Uint8Array, at: number, text: string) => {
+  for (let i = 0; i < text.length; i++) if (b[at + i] !== text.charCodeAt(i)) return false
+  return true
+}
+
+/** The media type the BYTES say (their first ones are enough); null when they say nothing known. */
+export const sniffType = (b: Uint8Array): string | null => {
+  if (b.length < 12) return null
+  if (b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return "image/jpeg"
+  if (b[0] === 0x89 && ascii(b, 1, "PNG")) return "image/png"
+  if (ascii(b, 0, "GIF8")) return "image/gif"
+  if (ascii(b, 0, "RIFF") && ascii(b, 8, "WEBP")) return "image/webp"
+  if (ascii(b, 0, "RIFF") && ascii(b, 8, "WAVE")) return "audio/wav"
+  if (ascii(b, 4, "ftyp")) {
+    const brand = String.fromCharCode(b[8], b[9], b[10], b[11])
+    if (brand === "avif" || brand === "avis") return "image/avif"
+    if (brand.startsWith("hei") || brand === "mif1") return "image/heic"
+    if (brand === "M4A ") return "audio/mp4"
+    if (brand === "qt  ") return "video/quicktime"
+    return "video/mp4"
+  }
+  if (b[0] === 0x1a && b[1] === 0x45 && b[2] === 0xdf && b[3] === 0xa3) return "video/webm"
+  if (ascii(b, 0, "OggS")) return "audio/ogg"
+  if (ascii(b, 0, "ID3") || (b[0] === 0xff && (b[1] & 0xe0) === 0xe0)) return "audio/mpeg"
+  if (ascii(b, 0, "%PDF")) return "application/pdf"
+  return null
+}
+
+/** Types a browser may be handed to SHOW; anything else is a download (no page runs from this origin). */
+const INLINE = /^(image\/(jpeg|png|gif|webp|avif)|video\/|audio\/|application\/pdf$)/
+
+const EXT: Record<string, string> = {
+  "image/jpeg": "jpg", "image/png": "png", "image/gif": "gif", "image/webp": "webp", "image/avif": "avif", "image/heic": "heic",
+  "video/mp4": "mp4", "video/quicktime": "mov", "video/webm": "webm",
+  "audio/mpeg": "mp3", "audio/mp4": "m4a", "audio/wav": "wav", "audio/ogg": "ogg", "application/pdf": "pdf",
+}
+
+const u16 = (b: Uint8Array, at: number) => (b[at] << 8) | b[at + 1]
+const u32 = (b: Uint8Array, at: number) => ((b[at] << 24) | (b[at + 1] << 16) | (b[at + 2] << 8) | b[at + 3]) >>> 0
+const le16 = (b: Uint8Array, at: number) => b[at] | (b[at + 1] << 8)
+const le24 = (b: Uint8Array, at: number) => b[at] | (b[at + 1] << 8) | (b[at + 2] << 16)
+
+/**
+ * The orientation a JPEG's Exif block names (1…8; 1 = as stored), 1 when it names none. A camera
+ * stores the sensor's frame and says how to turn it: 5…8 are the quarter turns, where the picture
+ * as it is SHOWN is as wide as the stored frame is tall. `at` is the APP1 segment's payload.
+ */
+const exifOrientation = (b: Uint8Array, at: number, end: number): number => {
+  if (end - at < 14 || !ascii(b, at, "Exif")) return 1
+  const tiff = at + 6
+  const little = b[tiff] === 0x49
+  const r16 = (i: number) => little ? le16(b, i) : u16(b, i)
+  const r32 = (i: number) => little ? (b[i] | (b[i + 1] << 8) | (b[i + 2] << 16) | (b[i + 3] << 24)) >>> 0 : u32(b, i)
+  const ifd = tiff + r32(tiff + 4)
+  if (ifd + 2 > end) return 1
+  const count = r16(ifd)
+  for (let i = 0; i < count; i++) {
+    const entry = ifd + 2 + i * 12
+    if (entry + 12 > end) break
+    if (r16(entry) === 0x0112) { const value = r16(entry + 8); return value >= 1 && value <= 8 ? value : 1 }
+  }
+  return 1
+}
+
+/** An image's pixel size AS IT IS SHOWN, read from its header (PNG, GIF, JPEG, WebP); null for anything else. */
+export const imageSize = (b: Uint8Array, type: string | null): { width: number, height: number } | null => {
+  if (type === "image/png" && b.length >= 24) return { width: u32(b, 16), height: u32(b, 20) }
+  if (type === "image/gif" && b.length >= 10) return { width: le16(b, 6), height: le16(b, 8) }
+  if (type === "image/webp" && b.length >= 30) {
+    if (ascii(b, 12, "VP8X")) return { width: le24(b, 24) + 1, height: le24(b, 27) + 1 }
+    if (ascii(b, 12, "VP8L")) { const v = b[21] | (b[22] << 8) | (b[23] << 16) | (b[24] << 24); return { width: (v & 0x3fff) + 1, height: ((v >> 14) & 0x3fff) + 1 } }
+    if (ascii(b, 12, "VP8 ")) return { width: le16(b, 26) & 0x3fff, height: le16(b, 28) & 0x3fff }
+  }
+  if (type === "image/jpeg") {
+    // the frame header is the first SOFn marker; the segments before it are skipped by their lengths
+    let at = 2
+    let orientation = 1
+    while (at + 9 < b.length) {
+      if (b[at] !== 0xff) return null
+      const marker = b[at + 1]
+      if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+        const width = u16(b, at + 7), height = u16(b, at + 5)
+        // a quarter turn: every renderer shows the picture turned, so this is its size
+        return orientation >= 5 ? { width: height, height: width } : { width, height }
+      }
+      if (marker === 0xe1 && orientation === 1) orientation = exifOrientation(b, at + 4, Math.min(b.length, at + 2 + u16(b, at + 2)))
+      at += 2 + u16(b, at + 2)
+    }
+  }
+  return null
+}
+
+/** A name fit for a url's last segment; the extension follows what the bytes are. */
+const cleanName = (raw: string, type: string | null): string => {
+  let name = raw.split(/[\\/]/).pop()!.replace(/[\u0000-\u001f\u007f"<>|:*?]/g, "").trim().slice(-120) || "file"
+  const ext = type ? EXT[type] : undefined
+  if (ext && !new RegExp(`\\.(${ext === "jpg" ? "jpe?g" : ext})$`, "i").test(name)) name = `${name.replace(/\.[A-Za-z0-9]{1,5}$/, "")}.${ext}`
+  return name
+}
+
+// ───────────────────────────── pictures ─────────────────────────────
+
+/** The part of sharp this file uses (`import sharp from "sharp"` is one). */
+export type Sharp = (input: Uint8Array, options?: { limitInputPixels?: number, raw?: { width: number, height: number, channels: 4 } }) => {
+  rotate(): ReturnType<Sharp>
+  resize(options: { width: number, height: number, fit: "inside", withoutEnlargement: boolean }): ReturnType<Sharp>
+  webp(options?: { quality?: number }): ReturnType<Sharp>
+  toBuffer(options: { resolveWithObject: true }): Promise<{ data: Uint8Array, info: { width: number, height: number, size: number } }>
+}
+
+/** The part of heic-decode this file uses (`import heic from "heic-decode"` is one). */
+export type Heic = {
+  all(input: { buffer: Uint8Array }): Promise<{ width: number, height: number, decode(): Promise<{ width: number, height: number, data: Uint8ClampedArray }> }[] & { dispose(): void }>
+}
+
+/**
+ * `bytes` as a `t.image()` field keeps a picture: as it is SHOWN (the Exif turn applied to the
+ * pixels), nothing of its metadata, its longer side at most `rule.max`, WebP. Null for a GIF, which
+ * stays as it came (its frames). Throws `UploadError` for what is no picture, or one that cannot be read.
+ */
+export const fitImage = async (sharp: Sharp, bytes: Uint8Array, rule: ImageRule, heic?: Heic | null): Promise<{ data: Uint8Array, width: number, height: number } | null> => {
+  const type = sniffType(bytes)
+  if (!type?.startsWith("image/")) throw new UploadError(400, "a picture is expected")
+  if (type === "image/gif") return null
+  try {
+    let source = sharp(bytes, { limitInputPixels: MAX_IMAGE_PIXELS })
+    if (type === "image/heic" && heic) {
+      // the file's first picture, as libheif shows it (it applies the turn the file names)
+      const pictures = await heic.all({ buffer: bytes })
+      try {
+        const [first] = pictures
+        if (first.width * first.height > MAX_IMAGE_PIXELS) throw new Error("too large")
+        const { width, height, data } = await first.decode()
+        source = sharp(new Uint8Array(data.buffer, data.byteOffset, data.byteLength), { raw: { width, height, channels: 4 } })
+      } finally {
+        pictures.dispose()
+      }
+    }
+    const { data, info } = await source
+      .rotate()
+      .resize({ width: rule.max, height: rule.max, fit: "inside", withoutEnlargement: true })
+      .webp({ quality: WEBP_QUALITY })
+      .toBuffer({ resolveWithObject: true })
+    return { data, width: info.width, height: info.height }
+  } catch {
+    throw new UploadError(400, type === "image/heic" ? "a HEIC picture cannot be read — send it as JPEG" : "the picture cannot be read")
+  }
+}
+
+// ───────────────────────────── receiving ─────────────────────────────
+
+export const isMultipart = (req: Request) => /^multipart\/form-data/i.test(req.headers.get("content-type") ?? "")
+
+/**
+ * Read a multipart endpoint call: the field `args` is the JSON body of a plain call (`{"args":[…]}`,
+ * a file's place taken by `{"$file": <index>}`), the fields `file0…` are the files. Throws
+ * `UploadError`; nothing is left on disk then.
+ */
+export const receiveUploads = async (req: Request, dir: string, limits: UploadLimits = {}): Promise<{ args: unknown[], uploads: Upload[] }> => {
+  const maxFile = limits.maxFile ?? 10 * MB
+  const maxFiles = limits.maxFiles ?? 10
+  const tooBig = () => new UploadError(413, `a file is at most ${Math.round(maxFile / MB)} MB`)
+  if (Number(req.headers.get("content-length") ?? 0) > maxFile * maxFiles + MB) throw tooBig()
+
+  let form: Awaited<ReturnType<Request["formData"]>>
+  try { form = await req.formData() } catch { throw new UploadError(400, "the body is not multipart form data") }
+  let args: unknown
+  try { args = JSON.parse(String(form.get("args")))?.args } catch { args = null }
+  if (!Array.isArray(args)) throw new UploadError(400, "the field \"args\" must be {\"args\":[…]}")
+
+  const blobs: Blob[] = []
+  for (let i = 0; ; i++) {
+    const part = form.get(`file${i}`)
+    if (part === null) break
+    if (typeof part === "string") throw new UploadError(400, `file${i} is not a file`)
+    if (i >= maxFiles) throw new UploadError(413, `a call carries at most ${maxFiles} files`)
+    if (part.size > maxFile) throw tooBig()
+    blobs.push(part)
+  }
+
+  const tmp = join(dir, "tmp")
+  await mkdir(tmp, { recursive: true })
+  const uploads: Upload[] = []
+  try {
+    for (const blob of blobs) {
+      const bytes = new Uint8Array(await blob.arrayBuffer())
+      const sniffed = sniffType(bytes)
+      const size = imageSize(bytes, sniffed)
+      const upload: Upload = {
+        id: crypto.randomUUID(),
+        name: cleanName((blob as { name?: string }).name ?? "", sniffed),
+        // what the bytes are; for the rest, what the app said
+        type: sniffed ?? (blob.type && !/^(text\/html|image\/svg)/i.test(blob.type) ? blob.type : "application/octet-stream"),
+        size: bytes.length,
+        ...(size ?? {}),
+      }
+      await writeFile(join(tmp, upload.id), bytes)
+      uploads.push(upload)
+    }
+  } catch (e) {
+    await dropUploads(dir, uploads)
+    throw e
+  }
+  return { args, uploads }
+}
+
+/** Remove what `receiveUploads` left, for a call that never reached the worker. */
+export const dropUploads = async (dir: string, uploads: Upload[]) => {
+  for (const u of uploads) await rm(join(dir, "tmp", u.id), { force: true })
+}
+
+// ───────────────────────────── serving ─────────────────────────────
+
+/** `GET <base>/files/<id>/<name>` — `rest` is what follows `/files/`. */
+export const fileResponse = async (dir: string, rest: string, req: Request, headers: Record<string, string> = {}): Promise<Response> => {
+  const id = rest.split("/")[0]
+  const path = join(dir, id)
+  const info = UUID.test(id) ? await stat(path).catch(() => null) : null
+  if (!info?.isFile()) return new Response("Not found", { status: 404, headers })
+
+  // the type is what the BYTES say — never the name in the url, which anyone can write
+  const head = new Uint8Array(64)
+  await new Promise<void>((resolve, reject) => {
+    let at = 0
+    createReadStream(path, { start: 0, end: 63 })
+      .on("data", (chunk) => { head.set(chunk as Uint8Array, at); at += chunk.length })
+      .on("end", resolve).on("error", reject)
+  })
+  const type = sniffType(head)
+  const inline = type !== null && INLINE.test(type)
+
+  const out: Record<string, string> = {
+    ...headers,
+    "content-type": inline ? type : "application/octet-stream",
+    "x-content-type-options": "nosniff",
+    // an id is one upload: its bytes never change
+    "cache-control": "public, max-age=31536000, immutable",
+    "accept-ranges": "bytes",
+    ...(inline ? {} : { "content-disposition": "attachment" }),
+  }
+  let start = 0, end = info.size - 1, status = 200
+  const range = /^bytes=(\d*)-(\d*)$/.exec(req.headers.get("range") ?? "")
+  if (range && (range[1] || range[2])) {
+    if (range[1]) { start = Number(range[1]); if (range[2]) end = Math.min(end, Number(range[2])) }
+    else start = Math.max(0, info.size - Number(range[2]))
+    if (start > end) return new Response(null, { status: 416, headers: { ...headers, "content-range": `bytes */${info.size}` } })
+    status = 206
+    out["content-range"] = `bytes ${start}-${end}/${info.size}`
+  }
+  out["content-length"] = String(end - start + 1)
+  if (req.method === "HEAD" || info.size === 0) return new Response(null, { status, headers: out })
+  return new Response(Readable.toWeb(createReadStream(path, { start, end })) as unknown as ReadableStream, { status, headers: out })
+}
+
+// ───────────────────────────── the worker ─────────────────────────────
+
+export type FilesHostConfig = {
+  /** The project's db (the one with `t.file()` fields, when it has any). */
+  db: Db<any> | null
+  /** Where this database's files are. */
+  dir: string
+  /** The bytes all files of the database may take together (absent = no limit). */
+  quota?: number
+  /** The codec of `t.image()` fields, asked for at the first picture (`() => import("sharp")`'s default). */
+  sharp?: () => Promise<Sharp | null>
+  /** The reader of HEIC pictures, asked for at the first of them (`() => import("heic-decode")`'s default). */
+  heic?: () => Promise<Heic | null>
+  log?: (level: "info" | "warn" | "error", text: string) => void
+}
+
+export type FilesHost = {
+  /** The project has `t.file()` fields. */
+  readonly enabled: boolean
+  /** Give the bundle's db layer its seam (once, after the bundle is loaded). */
+  install(): void
+  /** The arguments with every `{ "$file": i }` turned into the `File` the endpoint receives. */
+  adopt(args: unknown[], rc: RequestContext): Promise<unknown[]>
+  /** After the call, whatever it ended with. */
+  finish(rc: RequestContext): Promise<void>
+}
+
+const isPlaceholder = (v: unknown): v is { $file: number } =>
+  typeof v === "object" && v !== null && typeof (v as { $file?: unknown }).$file === "number" && Object.keys(v).length === 1
+
+const hasPlaceholder = (v: unknown): boolean =>
+  isPlaceholder(v) || (Array.isArray(v) ? v.some(hasPlaceholder) : typeof v === "object" && v !== null && Object.values(v).some(hasPlaceholder))
+
+export const createFilesHost = (cfg: FilesHostConfig): FilesHost => {
+  const fields = cfg.db?.$files ?? []
+  const enabled = fields.length > 0
+  const log = cfg.log ?? (() => {})
+  const transport = (): MarciTransport => {
+    const t = (globalThis as unknown as { __lecodesDbTransport?: MarciTransport }).__lecodesDbTransport
+    if (!t) throw new Error("files: no db transport")
+    return t
+  }
+  const exec = (op: Omit<MarciOp, "model">) => transport().exec({ model: FILE_MODEL, ...op })
+  /** No field of any row holds it. */
+  const ownerless = Object.fromEntries(fields.map(f => [f.owner, null]))
+
+  /** The `File` objects of the calls in flight → their rows. */
+  const uploaded = new WeakMap<object, string>()
+  const inFlight = new WeakMap<RequestContext, string[]>()
+  /** What the uploads of the calls in flight are called (an image field renames: `cat.jpg` → `cat.webp`). */
+  const names = new Map<string, string>()
+  let sharp: Promise<Sharp | null> | null = null
+  let heic: Promise<Heic | null> | null = null
+  const image = async (id: string, rule: ImageRule): Promise<ImageFacts> => {
+    const codec = await (sharp ??= cfg.sharp?.() ?? Promise.resolve(null))
+    if (!codec) throw new Error("files: a t.image() field needs sharp, and this host has none")
+    const path = join(cfg.dir, id)
+    const bytes = new Uint8Array(await readFile(path))
+    const fit = await fitImage(codec, bytes, rule, sniffType(bytes) === "image/heic" ? await (heic ??= cfg.heic?.().catch(() => null) ?? Promise.resolve(null)) : null)
+    if (!fit) {
+      const size = imageSize(bytes, "image/gif")
+      if (!size) throw new UploadError(400, "the picture cannot be read")
+      return { name: cleanName(names.get(id) ?? "", "image/gif"), type: "image/gif", size: bytes.length, ...size }
+    }
+    // beside, then over: whoever reads the file sees one picture or the other, whole
+    await writeFile(join(cfg.dir, "tmp", id), fit.data)
+    await rename(join(cfg.dir, "tmp", id), path)
+    return { name: cleanName(names.get(id) ?? "", "image/webp"), type: "image/webp", size: fit.data.length, width: fit.width, height: fit.height }
+  }
+  const seam: FilesSeam = {
+    uploaded: (value) => typeof value === "object" && value !== null ? uploaded.get(value) : undefined,
+    url: (id, name) => `${currentRequest()?.filesBase ?? ""}/files/${id}/${encodeURIComponent(name)}`,
+    image,
+    dirty: false,
+  }
+
+  // The bytes of the rows the database let go of. One reader at a time: a read confirms the entries
+  // of the read before it.
+  let settling: Promise<void> = Promise.resolve()
+  const settle = () => (settling = settling.catch(() => {}).then(async () => {
+    let after: number | undefined
+    for (;;) {
+      const entries: { seq: number, row: { id: string } }[] = await exec({ action: "$journalRead", journal: { name: JOURNAL, after, limit: 100 } })
+      if (!entries.length) return
+      for (const entry of entries) {
+        await rm(join(cfg.dir, entry.row.id), { force: true })
+        after = entry.seq
+      }
+    }
+  }))
+
+  // Once, before the first call that has to do with files — not at load: a deploy loads the bundle
+  // before the database has its schema.
+  let ready: Promise<void> | null = null
+  const start = () => (ready ??= (async () => {
+    await mkdir(join(cfg.dir, "tmp"), { recursive: true })
+    await exec({ action: "$journalOpen", journal: { name: JOURNAL, on: ["delete"] } })
+    // uploads a crashed process attached to nothing (the ones of a call still running are younger)
+    await exec({ action: "deleteMany", query: { $where: { ...ownerless, createdAt: { $lt: Date.now() - TMP_MAX_AGE_MS } } } })
+    await settle()
+    // …and the folder against the rows: the database may be another one than the files were stored under
+    const rows: { id: string }[] = await exec({ action: "findMany", query: { id: true } })
+    const known = new Set(rows.map(r => r.id))
+    for (const name of await readdir(cfg.dir)) {
+      if (UUID.test(name) && !known.has(name)) await rm(join(cfg.dir, name), { force: true })
+    }
+    for (const name of await readdir(join(cfg.dir, "tmp"))) {
+      const path = join(cfg.dir, "tmp", name)
+      const info = await stat(path).catch(() => null)
+      if (info && Date.now() - info.mtimeMs > TMP_MAX_AGE_MS) await rm(path, { force: true })
+    }
+  })().catch((e) => { ready = null; throw e }))
+
+  return {
+    enabled,
+    install: () => setFilesSeam(enabled ? seam : null),
+
+    adopt: async (args, rc) => {
+      const uploads = (rc.uploads ?? []) as Upload[]
+      if (!uploads.length && !hasPlaceholder(args)) return args
+      try {
+        if (!enabled) throw new UploadError(400, "this project stores no files — a model needs a t.file() field")
+        await start()
+        if (cfg.quota !== undefined && uploads.length) {
+          const used = (await exec({ action: "aggregate", query: { $sum: "size" } }))?.sum ?? 0
+          if (used + uploads.reduce((n, u) => n + u.size, 0) > cfg.quota) throw new UploadError(413, "the project's file storage is full")
+        }
+        // the rows first, then the bytes into place: a file on disk always has its row
+        if (uploads.length) {
+          await transport().batch(uploads.map(u => ({
+            model: FILE_MODEL, action: "insert",
+            data: { id: u.id, name: u.name, type: u.type, size: u.size, ...(u.width ? { width: u.width, height: u.height } : {}) },
+          })))
+          inFlight.set(rc, uploads.map(u => u.id))
+          for (const u of uploads) names.set(u.id, u.name)
+          for (const u of uploads) await rename(join(cfg.dir, "tmp", u.id), join(cfg.dir, u.id))
+        }
+        const files = uploads.map((u) => {
+          const file = Object.freeze({ name: u.name, size: u.size, type: u.type })
+          uploaded.set(file, u.id)
+          return file
+        })
+        const place = (v: unknown): unknown => {
+          if (isPlaceholder(v)) return files[v.$file] ?? (() => { throw new UploadError(400, `the call names file ${v.$file}, and carries ${files.length}`) })()
+          if (Array.isArray(v)) return v.map(place)
+          if (typeof v === "object" && v !== null) return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, place(x)]))
+          return v
+        }
+        return place(args) as unknown[]
+      } catch (e) {
+        if (!inFlight.has(rc)) await dropUploads(cfg.dir, uploads)
+        throw e
+      }
+    },
+
+    finish: async (rc) => {
+      if (!enabled) return
+      const ids = inFlight.get(rc)
+      if (!ids && !seam.dirty) return
+      try {
+        inFlight.delete(rc)
+        for (const id of ids ?? []) names.delete(id)
+        // an upload the endpoint wrote to no field
+        if (ids) await exec({ action: "deleteMany", query: { $where: { ...ownerless, id: { $in: ids } } } })
+        seam.dirty = false
+        await start()
+        await settle()
+      } catch (e) {
+        log("error", `files: ${(e as Error)?.message ?? e}`)
+      }
+    },
+  }
+}

package/src/server/files/models.ts

@@ -0,0 +1,116 @@
+/**
+ * Stored files: `t.file()` on a model.
+ *
+ * A project never declares where a file lives. A model that has a `t.file()` field makes the db carry
+ * one more model, the PLATFORM's `File` — a row per stored file: what it is (name, type, size, an
+ * image's dimensions) and whose it is. The owner is a reference FROM the file TO its row, with
+ * `onDelete("cascade")`, one optional reference per `t.file()` field of the schema (`postImage`,
+ * `userAvatar`): deleting a post — by name, or because its author was deleted — deletes its files in
+ * the same transaction, by the database's own rule. The field on the owner is the reverse side of
+ * that reference.
+ *
+ * The bytes are the host's (./host.ts): a file on disk named by the row's id. They go only because
+ * the row went — the host reads the deletions from marcidb's journal of this model.
+ *
+ * What a project sees is a VALUE: it writes a `File` (an upload, an endpoint's parameter) and reads a
+ * `StoredFile`. The url is computed when the row is read, never stored.
+ */
+
+import { t, type Field } from "../db/fields"
+
+export const FILE_MODEL = "File"
+
+/** A stored file as a project reads it. */
+export type StoredFile = {
+  /** Where the bytes are served from. Public, not guessable; it never changes for this file. */
+  url: string
+  name: string
+  /** The media type: `image/jpeg`, `video/mp4`, `application/pdf`. */
+  type: string
+  /** Bytes. */
+  size: number
+  /** An image's dimensions in pixels (absent for anything else). */
+  width?: number
+  height?: number
+}
+
+/** A stored picture (`t.image()`): its size is always known. */
+export type StoredImage = StoredFile & { width: number, height: number }
+
+/**
+ * A file as an endpoint receives it — the app's `File` (a picked file, a photo), uploaded with the
+ * call. Written to a `t.file()` field, it is stored; an endpoint that writes it nowhere drops it.
+ */
+export type UploadedFile = { readonly name: string, readonly size: number, readonly type: string }
+
+/** One `t.file()` field of the schema; `image` = it is a `t.image()`, with its rule. */
+export type FileField = { model: string, key: string, array: boolean, owner: string, image?: ImageRule }
+
+export type ImageRule = { max: number }
+/** What a file became when it was made fit for an image field: the facts its row carries from then on. */
+export type ImageFacts = { name: string, type: string, size: number, width: number, height: number }
+
+const cap = (s: string) => s.charAt(0).toUpperCase() + s.slice(1)
+const uncap = (s: string) => s.charAt(0).toLowerCase() + s.slice(1)
+/** The reference on `File` that says "I am this field of that row": `Post.image` → `postImage`. */
+export const fileOwnerKey = (model: string, key: string) => `${uncap(model)}${cap(key)}`
+
+/** What a data browser may show of a file (the rest is the platform's bookkeeping). */
+export const filePublicFields = () => ({
+  name:      t.string(),
+  type:      t.string(),
+  size:      t.int(),
+  width:     t.int().optional(),
+  height:    t.int().optional(),
+  createdAt: t.date().default("now"),
+})
+
+/** The whole `File` of a schema with these `t.file()` fields. */
+export const fileFields = (fields: FileField[]): Record<string, Field<any, any>> => {
+  const out: Record<string, Field<any, any>> = {
+    /** Also the name of the bytes on disk and the id in the url. */
+    id:       t.uuid(),
+    ...filePublicFields(),
+    /** The place in a `t.file().array()` field. */
+    position: t.int().default(0),
+  }
+  for (const f of fields) {
+    if (f.owner in out) throw new Error(`defineDb: ${f.model}.${f.key} — the name "${f.owner}" is taken on the platform's File model; name the field differently`)
+    out[f.owner] = t.one(f.model).optional().onDelete("cascade")
+  }
+  return out
+}
+
+// ───────────────────────────── the host's seam ─────────────────────────────
+
+/**
+ * What the host (./host.ts) gives the db layer of a bundle — a global, because the bundle carries its
+ * own copy of this module. Absent (a unit test without a host): nothing is an upload, urls are relative.
+ */
+export type FilesSeam = {
+  /** The id of the `File` row behind an upload of the current request; undefined for anything else —
+   *  a value the app sent as JSON is never an upload, whatever it looks like. */
+  uploaded(value: unknown): string | undefined
+  url(id: string, name: string): string
+  /** Make the upload `id` fit for a `t.image()` field (its bytes are rewritten in place) and say what
+   *  it is now. Throws an `ApiError` for what is no picture. */
+  image(id: string, rule: ImageRule): Promise<ImageFacts>
+  /** A write that may have removed rows of `File` went through the db (a delete, a rewritten file field): their bytes are due. */
+  dirty: boolean
+}
+const seam = globalThis as unknown as { __lecodesFiles?: FilesSeam }
+export const filesSeam = (): FilesSeam | undefined => seam.__lecodesFiles
+export const setFilesSeam = (value: FilesSeam | null) => {
+  if (value) seam.__lecodesFiles = value
+  else delete seam.__lecodesFiles
+}
+
+const URL_ID = /\/files\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})(?:\/|$)/
+/** The row a `StoredFile` the app handed back stands for (by its url); undefined for anything else. */
+export const storedFileId = (value: unknown): string | undefined => {
+  const url = (value as { url?: unknown } | null)?.url
+  return typeof url === "string" ? URL_ID.exec(url)?.[1] : undefined
+}
+
+export const fileUrl = (id: string, name: string): string =>
+  seam.__lecodesFiles?.url(id, name) ?? `/files/${id}/${encodeURIComponent(name)}`

package/src/server/host.ts

@@ -6,7 +6,7 @@
  */
 
 export {
-  loadServerModules, createInvoker, createSubscribeGuard, setChannelPublisher, setRequestProvider,
+  loadServerModules, createInvoker, createFileWriter, createSubscribeGuard, setChannelPublisher, setRequestProvider,
 } from "./runtime"
 export type { LoadedServer, InvokeResult, InvokerOptions, ServerRegistration } from "./runtime"
 export type { RequestContext } from "./context"
@@ -25,6 +25,10 @@ export type { AuthHost, AuthHostConfig, AuthMail } from "./auth/host"
 export type { AuthState, AuthOps } from "./auth/types"
 export type { AppConfig } from "./auth/appConfig"
 export type { IdentityProvider } from "./auth/models"
+export { createFilesHost, receiveUploads, dropUploads, fileResponse, isMultipart, UploadError } from "./files/host"
+export type { FilesHost, FilesHostConfig, Heic, Sharp, Upload, UploadLimits } from "./files/host"
+export type { StoredFile, StoredImage } from "./files/models"
+import { FILE_MODEL, filePublicFields } from "./files/models"
 import { AUTH_IDENTITY_MODEL, AUTH_SESSION_MODEL, identityPublicFields, sessionPublicFields } from "./auth/models"
 
 import type { LoadedServer } from "./runtime"
@@ -42,8 +46,10 @@ export type ServerDescription = {
   marci: string
   /** `auth: true` = one of the platform's two models (`Session`, `Identity` — they come with
    *  `withAuth`), described WITHOUT its secrets (token and password hashes, a pending code): what a
-   *  data browser may show, read-only. */
-  models: Record<string, { fields: Record<string, FieldDescription>, auth?: true }>
+   *  data browser may show, read-only. `files: true` = the platform's `File` (it comes with a
+   *  `t.file()` field): what each stored file is, read-only too — a file is written through its field.
+   *  A `t.file()` field itself is described as `kind: "file"`. */
+  models: Record<string, { fields: Record<string, FieldDescription>, auth?: true, files?: true }>
   endpoints: { id: string, params: unknown[] | null }[]
   channels: string[]
   /** The project's model of a user (`null` = its db has no sign-in). */
@@ -72,9 +78,16 @@ export const describeServer = (server: LoadedServer): ServerDescription => {
       [AUTH_SESSION_MODEL]: [...Object.keys(sessionPublicFields()), "user"],
       [AUTH_IDENTITY_MODEL]: [...Object.keys(identityPublicFields()), "user"],
     } : {}
+    const files = db.$files
+    if (files.length) shown[FILE_MODEL] = ["id", ...Object.keys(filePublicFields())]
     for (const [name, m] of Object.entries(db.$models as Record<string, Model>)) {
       const fields = Object.entries(m.fields as Record<string, Field<any, any>>).filter(([k]) => !shown[name] || shown[name].includes(k))
-      models[name] = { fields: Object.fromEntries(fields.map(([k, f]) => [k, describeField(f)])), ...(shown[name] ? { auth: true as const } : {}) }
+      const described = Object.fromEntries(fields.map(([k, f]) => [k, describeField(f)]))
+      // a file field is, in the database, a relation to File: what a project declared is said here
+      for (const f of files) {
+        if (f.model === name) described[f.key] = { kind: "file", optional: false, unique: false, index: false, hasDefault: false, array: f.array, isId: false }
+      }
+      models[name] = { fields: described, ...(name === FILE_MODEL ? { files: true as const } : shown[name] ? { auth: true as const } : {}) }
     }
   }
   const params = (server.manifest.params ?? {}) as Record<string, unknown[]>

package/src/server/inject.ts

@@ -11,3 +11,4 @@ export { t, model, defineDb, ref } from "./db"
 export { ApiError } from "./errors"
 export { channel } from "./channel"
 export { request } from "./context"
+export type { StoredFile, StoredImage } from "./files/models"