@stacksjs/defaults 0.74.33 → 0.74.34

package/app/Actions/Dashboard/Content/file-pipeline.test.ts

@@ -0,0 +1,344 @@
+// The media pipeline behind uploads (stacksjs/stacks#2578).
+//
+// What is tested here is the dispatch and the state, not the encoders. Whether
+// `ts-images` produces a correct WebP is that package's business; what this
+// layer has to get right is which work an upload calls for, that a queue being
+// down leaves a visible failure rather than a silently unprocessed file, and
+// that the state survives the file being renamed.
+//
+// The dispatcher is a recording function rather than a real queue, so these run
+// without a worker.
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdtemp, mkdir, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { StorageManager } from '@stacksjs/storage'
+import type { DashboardFileNode } from './file-manager'
+import {
+  deleteDashboardFile,
+  dispatchDashboardFileTasks,
+  getDashboardFileSnapshot,
+  renameDashboardFile,
+  reprocessDashboardFile,
+} from './file-manager'
+import {
+  aggregateTaskState,
+  createMemoryMetadataStore,
+  describeError,
+  runTask,
+  tasksForContentType,
+} from './file-metadata'
+
+let root = ''
+let manager: StorageManager
+let store = createMemoryMetadataStore()
+let dispatched: Array<{ job: string, payload: Record<string, unknown> }> = []
+const dispatch = async (job: string, payload: Record<string, unknown>): Promise<void> => {
+  dispatched.push({ job, payload })
+}
+
+beforeEach(async () => {
+  store = createMemoryMetadataStore()
+  dispatched = []
+  root = await mkdtemp(join(tmpdir(), 'stacks-file-pipeline-'))
+  await mkdir(join(root, 'public'), { recursive: true })
+  manager = new StorageManager().init({
+    default: 'public',
+    disks: {
+      public: { driver: 'local', root: join(root, 'public'), url: '/storage', visibility: 'public' },
+    },
+  })
+})
+
+afterEach(async () => {
+  manager.reset()
+  await rm(root, { force: true, recursive: true })
+})
+
+function nodeAt(node: DashboardFileNode, path: string): DashboardFileNode | undefined {
+  if (node.path === path)
+    return node
+  for (const child of node.items ?? []) {
+    const found = nodeAt(child, path)
+    if (found)
+      return found
+  }
+  return undefined
+}
+
+describe('tasksForContentType', () => {
+  test('an image is optimized and tagged', () => {
+    expect(tasksForContentType('image/png')).toEqual(['optimize', 'tag'])
+    expect(tasksForContentType('image/jpeg; charset=binary')).toEqual(['optimize', 'tag'])
+  })
+
+  test('a video is transcoded and tagged', () => {
+    expect(tasksForContentType('video/mp4')).toEqual(['transcode', 'tag'])
+  })
+
+  test('SVG is left alone, because it is markup rather than a raster', () => {
+    // Nothing to re-encode, and running markup through an image decoder is a
+    // parser attack surface for no benefit.
+    expect(tasksForContentType('image/svg+xml')).toEqual([])
+  })
+
+  test('everything else calls for nothing', () => {
+    // Most uploads are documents. A queue entry per PDF that immediately finds
+    // nothing to do is noise in the one place somebody looks when a transcode
+    // is stuck.
+    expect(tasksForContentType('application/pdf')).toEqual([])
+    expect(tasksForContentType('text/plain')).toEqual([])
+    expect(tasksForContentType(undefined)).toEqual([])
+    expect(tasksForContentType('')).toEqual([])
+  })
+})
+
+describe('aggregateTaskState', () => {
+  test('is null when nothing was ever dispatched', () => {
+    // Not the same as work that finished: an image uploaded before
+    // optimization existed should not claim to have been optimized.
+    expect(aggregateTaskState([])).toBeNull()
+  })
+
+  test('reports the worst state, because a failure is what needs surfacing', () => {
+    const done = { kind: 'optimize', state: 'done', attempts: 1 } as const
+    const failed = { kind: 'tag', state: 'failed', attempts: 2 } as const
+    const running = { kind: 'transcode', state: 'running', attempts: 1 } as const
+    const queued = { kind: 'tag', state: 'queued', attempts: 0 } as const
+
+    expect(aggregateTaskState([done, failed])).toBe('failed')
+    expect(aggregateTaskState([done, running])).toBe('running')
+    expect(aggregateTaskState([done, queued])).toBe('queued')
+    expect(aggregateTaskState([done])).toBe('done')
+    // A failure outranks work still in flight.
+    expect(aggregateTaskState([running, failed])).toBe('failed')
+  })
+})
+
+describe('dispatchDashboardFileTasks', () => {
+  test('queues the jobs an image calls for, and records them', async () => {
+    await manager.disk('public').write('photo.png', 'x')
+
+    const tasks = await dispatchDashboardFileTasks(
+      { path: 'photo.png', contentType: 'image/png' },
+      manager,
+      store,
+      dispatch,
+    )
+
+    expect(tasks.map(task => task.kind)).toEqual(['optimize', 'tag'])
+    expect(dispatched.map(entry => entry.job)).toEqual(['OptimizeStorageImageJob', 'TagStorageMediaJob'])
+    expect(dispatched[0]?.payload).toEqual({ disk: 'public', path: 'photo.png' })
+
+    const recorded = (await store.tasksUnder('public', '')).get('photo.png')
+    expect(recorded?.every(task => task.state === 'queued')).toBeTrue()
+  })
+
+  test('dispatches nothing for a content type with no work', async () => {
+    await manager.disk('public').write('notes.pdf', 'x')
+
+    expect(await dispatchDashboardFileTasks({ path: 'notes.pdf', contentType: 'application/pdf' }, manager, store, dispatch)).toEqual([])
+    expect(dispatched).toEqual([])
+    expect(await store.tasksUnder('public', '')).toEqual(new Map())
+  })
+
+  test('holds a transcode back until it has a profile to build a ladder from', async () => {
+    // A job that guesses the source dimensions builds renditions nobody asked
+    // for. Tagging still runs, because it needs nothing.
+    await manager.disk('public').write('clip.mp4', 'x')
+
+    const withoutProfile = await dispatchDashboardFileTasks({ path: 'clip.mp4', contentType: 'video/mp4' }, manager, store, dispatch)
+    expect(withoutProfile.map(task => task.kind)).toEqual(['tag'])
+
+    dispatched = []
+    const withProfile = await dispatchDashboardFileTasks(
+      { path: 'clip.mp4', contentType: 'video/mp4', videoProfile: { width: 1920, height: 1080 } },
+      manager,
+      store,
+      dispatch,
+    )
+    expect(withProfile.map(task => task.kind)).toEqual(['transcode', 'tag'])
+    expect(dispatched[0]?.payload.profile).toEqual({ width: 1920, height: 1080 })
+  })
+
+  test('records a failure when the queue refuses, rather than losing the work', async () => {
+    // The whole reason the state is in a table the dashboard reads: a queue
+    // that is down should leave a visible failure, not a file that silently
+    // never gets processed.
+    await manager.disk('public').write('photo.png', 'x')
+
+    const tasks = await dispatchDashboardFileTasks(
+      { path: 'photo.png', contentType: 'image/png' },
+      manager,
+      store,
+      async () => { throw new Error('queue unavailable') },
+    )
+
+    expect(tasks.every(task => task.state === 'failed')).toBeTrue()
+    expect(tasks[0]?.error).toBe('queue unavailable')
+  })
+
+  test('narrows to the kinds asked for', async () => {
+    await manager.disk('public').write('photo.png', 'x')
+
+    const tasks = await dispatchDashboardFileTasks(
+      { path: 'photo.png', contentType: 'image/png', only: ['tag'] },
+      manager,
+      store,
+      dispatch,
+    )
+
+    expect(tasks.map(task => task.kind)).toEqual(['tag'])
+    expect(dispatched.map(entry => entry.job)).toEqual(['TagStorageMediaJob'])
+  })
+})
+
+describe('runTask', () => {
+  test('moves a task through running to done, counting the attempt', async () => {
+    await store.writeTask('public', 'a.png', { kind: 'optimize', state: 'queued', attempts: 0 })
+
+    const result = await runTask(store, 'public', 'a.png', 'optimize', async () => 'built')
+    expect(result).toBe('built')
+
+    const task = (await store.tasksUnder('public', '')).get('a.png')?.[0]
+    expect(task?.state).toBe('done')
+    expect(task?.attempts).toBe(1)
+    expect(task?.startedAt).toBeTruthy()
+    expect(task?.finishedAt).toBeTruthy()
+  })
+
+  test('records the failure and rethrows, so the queue still retries', async () => {
+    // The row and the queue answer different questions: the queue decides
+    // whether to try again, the row is what somebody looking at the file sees.
+    expect(runTask(store, 'public', 'a.png', 'optimize', async () => {
+      throw new Error('decode failed')
+    })).rejects.toThrow('decode failed')
+
+    await Bun.sleep(0)
+    const task = (await store.tasksUnder('public', '')).get('a.png')?.[0]
+    expect(task?.state).toBe('failed')
+    expect(task?.error).toBe('decode failed')
+  })
+
+  test('a retry that succeeds clears the previous error', async () => {
+    // A green file carrying a red message from two attempts ago is worse than
+    // no message.
+    await runTask(store, 'public', 'a.png', 'optimize', async () => { throw new Error('transient') }).catch(() => {})
+    await runTask(store, 'public', 'a.png', 'optimize', async () => 'ok')
+
+    const task = (await store.tasksUnder('public', '')).get('a.png')?.[0]
+    expect(task?.state).toBe('done')
+    expect(task?.error).toBeUndefined()
+    expect(task?.attempts).toBe(2)
+  })
+})
+
+describe('describeError', () => {
+  test('bounds what can reach the column', () => {
+    expect(describeError(new Error('boom'))).toBe('boom')
+    expect(describeError('a string')).toBe('a string')
+    expect(describeError(new Error('x'.repeat(5000)))).toHaveLength(2000)
+  })
+})
+
+describe('the snapshot reports processing', () => {
+  test('a queued file shows as queued, and names its tasks', async () => {
+    await manager.disk('public').write('photo.png', 'x')
+    await dispatchDashboardFileTasks({ path: 'photo.png', contentType: 'image/png' }, manager, store, dispatch)
+
+    const snapshot = await getDashboardFileSnapshot({}, manager, store)
+    const node = nodeAt(snapshot.root, 'photo.png')
+
+    expect(node?.processing).toBe('queued')
+    expect(node?.tasks.map(task => task.kind)).toEqual(['optimize', 'tag'])
+  })
+
+  test('a file nobody processed reports null, not done', async () => {
+    await manager.disk('public').write('notes.txt', 'x')
+
+    const snapshot = await getDashboardFileSnapshot({}, manager, store)
+    expect(nodeAt(snapshot.root, 'notes.txt')?.processing).toBeNull()
+  })
+})
+
+describe('tasks follow the file', () => {
+  test('a rename carries them, so a finished transcode is not lost', async () => {
+    await manager.disk('public').write('clip.mp4', 'x')
+    await store.writeTask('public', 'clip.mp4', { kind: 'transcode', state: 'done', attempts: 1 })
+
+    await renameDashboardFile({ path: 'clip.mp4', name: 'final.mp4' }, manager, store)
+
+    const tasks = await store.tasksUnder('public', '')
+    expect(tasks.get('clip.mp4')).toBeUndefined()
+    expect(tasks.get('final.mp4')?.[0]?.state).toBe('done')
+  })
+
+  test('a folder rename carries the tasks beneath it', async () => {
+    await manager.disk('public').write('media/clip.mp4', 'x')
+    await store.writeTask('public', 'media/clip.mp4', { kind: 'transcode', state: 'done', attempts: 1 })
+
+    await renameDashboardFile({ path: 'media', name: 'video' }, manager, store)
+
+    expect((await store.tasksUnder('public', '')).has('video/clip.mp4')).toBeTrue()
+  })
+
+  test('a delete forgets them', async () => {
+    await manager.disk('public').write('clip.mp4', 'x')
+    await store.writeTask('public', 'clip.mp4', { kind: 'transcode', state: 'done', attempts: 1 })
+
+    await deleteDashboardFile({ path: 'clip.mp4' }, manager, store)
+
+    expect(await store.tasksUnder('public', '')).toEqual(new Map())
+  })
+
+  test('a completed listing sweeps the ones whose file is gone', async () => {
+    await manager.disk('public').write('a.txt', 'x')
+    await store.writeTask('public', 'gone.png', { kind: 'optimize', state: 'done', attempts: 1 })
+
+    await getDashboardFileSnapshot({}, manager, store)
+
+    expect((await store.tasksUnder('public', '')).has('gone.png')).toBeFalse()
+  })
+})
+
+describe('reprocessDashboardFile', () => {
+  test('re-runs every kind the file calls for', async () => {
+    await manager.disk('public').write('photo.png', 'x')
+    await store.writeTask('public', 'photo.png', { kind: 'optimize', state: 'failed', attempts: 3, error: 'old' })
+
+    const result = await reprocessDashboardFile({ path: 'photo.png' }, manager, store, dispatch)
+
+    expect(result.tasks.map(task => task.kind)).toEqual(['optimize', 'tag'])
+    // The failed task is reset to queued rather than left showing its old
+    // error beside a job that is about to run.
+    const optimize = (await store.tasksUnder('public', '')).get('photo.png')?.find(task => task.kind === 'optimize')
+    expect(optimize?.state).toBe('queued')
+    expect(optimize?.error).toBeUndefined()
+  })
+
+  test('re-runs one kind when asked, leaving the others as they were', async () => {
+    await manager.disk('public').write('photo.png', 'x')
+    await store.writeTask('public', 'photo.png', { kind: 'optimize', state: 'done', attempts: 1 })
+
+    await reprocessDashboardFile({ path: 'photo.png', kinds: ['tag'] }, manager, store, dispatch)
+
+    expect(dispatched.map(entry => entry.job)).toEqual(['TagStorageMediaJob'])
+    const optimize = (await store.tasksUnder('public', '')).get('photo.png')?.find(task => task.kind === 'optimize')
+    expect(optimize?.state).toBe('done')
+  })
+
+  test('404s for a file that is gone, rather than queueing work against nothing', async () => {
+    expect(reprocessDashboardFile({ path: 'missing.png' }, manager, store, dispatch))
+      .rejects.toThrow(/was not found/)
+  })
+
+  test('rejects a kind that is not one of the three', async () => {
+    await manager.disk('public').write('photo.png', 'x')
+
+    expect(reprocessDashboardFile({ path: 'photo.png', kinds: ['reticulate'] }, manager, store, dispatch))
+      .rejects.toThrow(/Unknown task kind/)
+    expect(reprocessDashboardFile({ path: 'photo.png', kinds: 'tag' }, manager, store, dispatch))
+      .rejects.toThrow(/must be an array/)
+  })
+})

package/app/Jobs/OptimizeStorageImageJob.ts

@@ -0,0 +1,74 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { basename, join } from 'node:path'
+import { image } from '@stacksjs/image'
+import { log } from '@stacksjs/logging'
+import { Job } from '@stacksjs/queue'
+import { Storage } from '@stacksjs/storage'
+import { runTask } from '../Actions/Dashboard/Content/file-metadata'
+import { databaseMetadataStore } from '../Actions/Dashboard/Content/file-metadata-store'
+
+/**
+ * Build the responsive variants for an uploaded image (stacksjs/stacks#2578).
+ *
+ * Dispatched by the file manager's upload handler, not run inside it: encoding
+ * four widths in three formats is seconds of CPU, and an upload handler that
+ * waits for it is an upload handler that times out on a slow phone connection.
+ *
+ * Variants are written back to the SAME disk under `.variants/`, so they travel
+ * with the original and a disk that is swapped out does not leave them behind.
+ * The leading dot keeps them out of the file manager's listing, which skips
+ * hidden components - a folder of thirty derivatives beside every photo would
+ * make the browser useless.
+ *
+ * `ts-images` reads from the local filesystem, so a remote disk is staged
+ * through a temp file. That is the whole reason for the download: an S3 object
+ * has no path to hand a decoder.
+ */
+interface OptimizeStorageImagePayload {
+  disk: string
+  path: string
+}
+
+/** Where derivatives live, relative to the disk root. Hidden, so listings skip it. */
+export const VARIANT_PREFIX = '.variants'
+
+export default new Job({
+  name: 'OptimizeStorageImage',
+  description: 'Build responsive variants for an uploaded image (background)',
+  queue: 'media',
+  tries: 3,
+  backoff: [10, 30, 90],
+
+  async handle(payload: OptimizeStorageImagePayload) {
+    if (!payload?.disk || !payload?.path)
+      throw new Error('[OptimizeStorageImage] payload.disk and payload.path are required')
+
+    return await runTask(databaseMetadataStore, payload.disk, payload.path, 'optimize', async () => {
+      const adapter = Storage.disk(payload.disk)
+      const staging = await mkdtemp(join(tmpdir(), 'stacks-optimize-'))
+
+      try {
+        const source = join(staging, basename(payload.path))
+        await writeFile(source, await adapter.readToBuffer(payload.path))
+
+        const manifest = await image(source)
+          .preset('content')
+          .storage(adapter, `${VARIANT_PREFIX}/${payload.path}`)
+          .generate()
+
+        log.debug(`[OptimizeStorageImage] ${payload.path}: ${manifest.variants.length} variants`)
+
+        return {
+          variants: manifest.variants.length,
+          placeholder: manifest.placeholder,
+        }
+      }
+      finally {
+        // Always, including on the failure path: a staging directory left
+        // behind on every retry is how a worker fills its disk overnight.
+        await rm(staging, { force: true, recursive: true })
+      }
+    })
+  },
+})

package/app/Jobs/TagStorageMediaJob.ts

@@ -0,0 +1,122 @@
+import type { ConfiguredAIOptions } from '@stacksjs/ai'
+import { buildMessageWithImages, createAIClient } from '@stacksjs/ai'
+import { config } from '@stacksjs/config'
+import { log } from '@stacksjs/logging'
+import { Job } from '@stacksjs/queue'
+import { Storage } from '@stacksjs/storage'
+import { runTask, setTags } from '../Actions/Dashboard/Content/file-metadata'
+import { databaseMetadataStore } from '../Actions/Dashboard/Content/file-metadata-store'
+
+/**
+ * Ask a vision model what is in an uploaded image, and record the answer as
+ * tags (stacksjs/stacks#2578).
+ *
+ * A background job because it is a network round trip to a third party, and one
+ * that can take ten seconds under load. It also costs money per call, which is
+ * the reason for the guards below: this runs once per upload, and a retry storm
+ * against a misconfigured key would be an invoice rather than an outage.
+ *
+ * Tags are MERGED with whatever a person already put on the file rather than
+ * replacing them. A human tag is a decision and a model's tag is a suggestion,
+ * and having the suggestion overwrite the decision is the version of this
+ * feature nobody wants twice.
+ */
+interface TagStorageMediaPayload {
+  disk: string
+  path: string
+  /**
+   * How many tags to ask for. Bounded low on purpose: a model asked for twenty
+   * will produce twenty, and the last fifteen are noise that make the tag list
+   * less useful rather than more.
+   */
+  limit?: number
+}
+
+/** What the model is asked to return, so the answer is parsed rather than scraped. */
+const TAG_SCHEMA = {
+  type: 'object',
+  properties: {
+    tags: {
+      type: 'array',
+      items: { type: 'string' },
+    },
+  },
+  required: ['tags'],
+  additionalProperties: false,
+} as const
+
+const DEFAULT_LIMIT = 5
+const MAX_LIMIT = 12
+
+/** Beyond this a base64 image is a request body the provider will refuse anyway. */
+const MAX_IMAGE_BYTES = 8 * 1024 * 1024
+
+export default new Job({
+  name: 'TagStorageMedia',
+  description: 'Ask a vision model to tag an uploaded image (background)',
+  queue: 'media',
+  // Two, not three: each attempt is a paid call, and the failures worth
+  // retrying here are transient network ones rather than a rejected image.
+  tries: 2,
+  backoff: [30, 120],
+
+  async handle(payload: TagStorageMediaPayload) {
+    if (!payload?.disk || !payload?.path)
+      throw new Error('[TagStorageMedia] payload.disk and payload.path are required')
+
+    const limit = Math.max(1, Math.min(payload.limit ?? DEFAULT_LIMIT, MAX_LIMIT))
+
+    return await runTask(databaseMetadataStore, payload.disk, payload.path, 'tag', async () => {
+      const adapter = Storage.disk(payload.disk)
+      const bytes = await adapter.readToBuffer(payload.path)
+
+      if (bytes.byteLength > MAX_IMAGE_BYTES) {
+        throw new Error(
+          `[TagStorageMedia] ${payload.path} is ${bytes.byteLength} bytes; the vision path is capped at ${MAX_IMAGE_BYTES}. `
+          + 'Tag a generated variant instead of the original.',
+        )
+      }
+
+      const mediaType = await adapter.mimeType(payload.path)
+      if (!mediaType.startsWith('image/'))
+        throw new Error(`[TagStorageMedia] ${payload.path} is ${mediaType}, which is not something a vision model reads`)
+
+      const aiConfig = (config.ai || {}) as ConfiguredAIOptions
+      const client = createAIClient(aiConfig)
+
+      // Sent as base64 rather than a URL: the file may be on a private disk,
+      // and handing a provider a signed URL would mean minting one that
+      // outlives the call.
+      const content = buildMessageWithImages(
+        `Give up to ${limit} short lowercase tags describing what is in this image. `
+        + 'Prefer concrete nouns over judgements. Return only the JSON object.',
+        [{ dataBase64: bytes.toString('base64'), mediaType }],
+      )
+
+      const { data } = await client.generateObject<{ tags: string[] }>(
+        [{ role: 'user', content }],
+        TAG_SCHEMA as unknown as Record<string, unknown>,
+        { maxTokens: 300, temperature: 0 },
+      )
+
+      const suggested = Array.isArray(data?.tags) ? data.tags.slice(0, limit) : []
+      if (suggested.length === 0)
+        return { tags: [] }
+
+      // Merged, not replaced. `setTags` normalizes and deduplicates, so a model
+      // suggesting a tag somebody already applied is a no-op rather than a
+      // duplicate.
+      const existing = (await databaseMetadataStore.under(payload.disk, payload.path)).get(payload.path)
+      const record = await setTags(
+        databaseMetadataStore,
+        payload.disk,
+        payload.path,
+        [...(existing?.tags ?? []), ...suggested],
+      )
+
+      log.debug(`[TagStorageMedia] ${payload.path}: ${suggested.length} suggested, ${record.tags.length} total`)
+
+      return { tags: record.tags }
+    })
+  },
+})

package/app/Jobs/TranscodeStorageVideoJob.ts

@@ -0,0 +1,88 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { basename, join } from 'node:path'
+import { log } from '@stacksjs/logging'
+import { Job } from '@stacksjs/queue'
+import { Storage } from '@stacksjs/storage'
+import { video } from '@stacksjs/video'
+import { runTask } from '../Actions/Dashboard/Content/file-metadata'
+import { databaseMetadataStore } from '../Actions/Dashboard/Content/file-metadata-store'
+import { VARIANT_PREFIX } from './OptimizeStorageImageJob'
+
+/**
+ * Transcode an uploaded video to mp4 and HLS (stacksjs/stacks#2578).
+ *
+ * #2578 asked whether video was in scope at all, on the grounds that mp4 and
+ * HLS mean ffmpeg - a heavyweight external binary, its licensing, and its
+ * provisioning across every deploy target. That question is already answered
+ * here: `@stacksjs/video` is built on `ts-videos`, which does the encoding
+ * itself, so there is no external binary to provision and no licence to take a
+ * view on. The decision the issue wanted made was made before it was written.
+ *
+ * Renditions and the HLS playlist go to the same disk under `.variants/`,
+ * alongside the image variants and hidden from the listing for the same reason.
+ *
+ * The profile has to be supplied by the caller. `ts-videos` can inspect a file,
+ * but the dashboard already knows the dimensions it needs from the upload, and
+ * a job that guesses wrong builds a ladder nobody asked for.
+ */
+interface TranscodeStorageVideoPayload {
+  disk: string
+  path: string
+  profile: Parameters<ReturnType<typeof video>['profile']>[0]
+  /** Cap the ladder at this height. Omit for every rung up to the source. */
+  maxHeight?: number
+}
+
+export default new Job({
+  name: 'TranscodeStorageVideo',
+  description: 'Transcode an uploaded video to mp4 and HLS (background)',
+  queue: 'media',
+  // Fewer tries than the image job: a transcode is minutes of CPU, and a video
+  // that fails three times is not going to succeed on a fourth.
+  tries: 2,
+  backoff: [60, 300],
+
+  async handle(payload: TranscodeStorageVideoPayload) {
+    if (!payload?.disk || !payload?.path)
+      throw new Error('[TranscodeStorageVideo] payload.disk and payload.path are required')
+    if (!payload?.profile)
+      throw new Error('[TranscodeStorageVideo] payload.profile is required - the ladder is derived from it')
+
+    return await runTask(databaseMetadataStore, payload.disk, payload.path, 'transcode', async () => {
+      const adapter = Storage.disk(payload.disk)
+      const staging = await mkdtemp(join(tmpdir(), 'stacks-transcode-'))
+
+      try {
+        const source = join(staging, basename(payload.path))
+        await writeFile(source, await adapter.readToBuffer(payload.path))
+
+        const delivery = await video(source)
+          .profile(payload.profile)
+          .ladder(payload.maxHeight ?? 'auto')
+          .output(['mp4'])
+          .streaming(['hls'])
+          .process()
+
+        // `files` is the whole delivery - renditions, playlists and segments -
+        // keyed by its path within the output. Written one at a time rather
+        // than in parallel: a transcode already saturated the box, and a
+        // hundred concurrent uploads to object storage is how the last step of
+        // a ten-minute job fails on a rate limit.
+        const prefix = `${VARIANT_PREFIX}/${payload.path}`
+        for (const [name, bytes] of Object.entries(delivery.files))
+          await adapter.write(`${prefix}/${name}`, bytes)
+
+        log.debug(`[TranscodeStorageVideo] ${payload.path}: ${Object.keys(delivery.files).length} files`)
+
+        return {
+          files: Object.keys(delivery.files).length,
+          renditions: delivery.derivatives.length,
+        }
+      }
+      finally {
+        await rm(staging, { force: true, recursive: true })
+      }
+    })
+  },
+})