@adonis-agora/media 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,126 @@
 # @adonis-agora/media
 
+## 0.9.0
+
+### Minor Changes
+
+- [#20](https://github.com/DavideCarvalho/adonis-media/pull/20) [`a44014e`](https://github.com/DavideCarvalho/adonis-media/commit/a44014eb05c1aea460c163b1dd68c98bee01c284) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Session-backed direct uploads (`media.direct`) and a hand-rolled SigV4 presigner with split internal/public endpoints
+
+  **Why a third upload flow.** For video-sized files the deciding cost is bandwidth _through the app_. The TUS path resumes beautifully but streams every chunk client→app→S3 — 2× the bytes, and the app pays for both directions. The raw direct primitives (`media.uploads.initiateDirect` & friends) send bytes straight to S3, but they are stateless: `uploadId`, the part size and every collected `ETag` live only in the client's memory, so a page reload orphans the upload — and every consuming app was growing its own tracking table to compensate. `DirectUploadManager` (`media.direct`, config `uploads.direct`) combines the halves: the browser `PUT`s multipart parts straight to S3 through presigned URLs (the app moves **no** payload), while the session — `uploadId`, the agreed `partSize`, every confirmed part ETag — persists in the existing `UploadSessionStore` SPI. Same SPI, and with `uploadSessions.lucid()` the same tables, as TUS: **zero new migrations**; a part-size marker in the session metadata keeps the two flows from ever misreading each other's sessions in a shared store. TUS remains the right tool when the disk isn't S3 or bytes must flow through the app; direct sessions when they mustn't.
+
+  The lifecycle is deliberately front-loaded and resumable at every step:
+
+  - **`initiate`** validates part-size geometry (S3's 5 MiB floor and 10,000-part cap — caught here as the new `UploadPartSizeError`, instead of as S3's `EntityTooSmall` _after_ the whole file crossed the wire) and, given a `collection`, the declared `contentType` against that collection's `acceptsMimeTypes` — read from the same registry `attach` uses, so the gate and the barrier cannot drift — before the multipart upload even opens. Then it persists the session and presigns every part URL in one local batch.
+  - **`confirmPart`** records each uploaded part's ETag server-side — the resume currency. Everything else is disposable client state.
+  - **`status`** is the resume answer: confirmed ETags plus **fresh** presigned URLs for the parts still missing — which is also why the presign TTL no longer has to be sized to "the whole upload on a slow connection"; an expired URL costs one status round-trip, not the upload.
+  - **`complete(id, parts?)`** merges caller-supplied and confirmed parts and fails fast naming the exact missing part numbers (`UploadPartsIncompleteError`) instead of letting S3 return an opaque `InvalidPart`; **`abort`** frees the parts S3 is storing (best-effort — a lifecycle-reaped upload must still be deletable locally); expired sessions are reaped on access exactly like TUS.
+
+  `DirectUploadHandler` is the framework-neutral HTTP half in the `TusUploadHandler` mold — the provider mounts it under `uploads.direct.routes` (default `/media/uploads/direct/sessions`), it performs **no authorization** (the app guards the route), and the client sends a `fileName`, never a key: the key is resolved server-side via `keyFor`. `MediaManager.completeDirectUploadToLibrary(sessionId, input, parts?)` mirrors `completeUploadToLibrary`: complete + `attachExisting` in one step, zero-copy, with the collection whitelist re-validated against the **real** bytes (`verifyContentAgainstWhitelist` on a 16-byte head read) — the initiate gate checked what the client _declared_; this remains the barrier that checks what it _sent_.
+
+  **Presigned URLs are now hand-rolled SigV4 (query auth, `UNSIGNED-PAYLOAD`) — the `@aws-sdk/s3-request-presigner` peer is gone.** Presigning is pure local crypto (an HMAC chain over a canonical request; no round-trip to S3), so the SDK package bought nothing except a hard coupling of the signature to the client's configured endpoint. That coupling is precisely what breaks browser-consumed URLs behind a private network: SigV4 bakes the `Host` into the signature, and a URL signed for the internal MinIO FQDN is invalid on the public one — with the SDK the only fix is constructing a second client per endpoint. Owning the signer makes it a parameter: the new `publicEndpoint` option on `disks.s3()` signs **browser-facing** URLs (direct-upload part `PUT`s, signed `GET`s) for the public host while server-side operations — including the ListObjectsV2 XML-fallback fetch — stay on the internal `endpoint`. The signer (`presignS3Url`, exported) is verified byte-for-byte against AWS's published `examplebucket` presigned-GET test vector, plus an independently recomputed `UploadPart` vector locked as a regression pin; strict RFC 3986 encoding (including the `!'()*` set `encodeURIComponent` skips) and STS session tokens are covered. Credentials and region still resolve from the SDK client's own config, so every credential source (static, env, shared config, IAM role) keeps working.
+
+  Also new: typed `UploadPartOutOfRangeError` (a confirmed part number outside the agreed slicing) and `DirectUploadsNotConfiguredError` (accessing `media.direct` without `uploads.direct`), both alongside the errors above; `direct.partSize`/`direct.presignTtlSeconds` fall back to the shared `uploads.*` knobs, with a 20 MiB default part size (direct parts occupy no app memory, so a bigger part only enlarges the retry unit). Requires bucket CORS that allows `PUT` from the app's origin and exposes the `ETag` response header — the browser must read it to confirm parts.
+
+- [#21](https://github.com/DavideCarvalho/adonis-media/pull/21) [`75649a9`](https://github.com/DavideCarvalho/adonis-media/commit/75649a9c6793f9f8fc83da07ee2418ab9ff8432b) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Transformers — transformações de conteúdo plugáveis persistidas como conversions — com HLS de vídeo como implementação de referência
+
+  **O contrato `Transformer`.** Conversions de imagem respondem "mesma imagem, outro tamanho/formato". Tudo o mais que deriva de uma mídia — um pacote HLS, uma faixa de áudio extraída, metadados sondados, um blurhash — agora passa por um contrato único: um `Transformer` recebe um `TransformerContext` (o record, leitura do original via `getBytes`/`getStream`, o `storage` para assets auxiliares em outros disks) e produz artefatos + metadados persistidos como uma conversion nomeada no `MediaRecord`. O contrato foi validado contra os shapes possíveis antes de nascer: N artefatos com entry (HLS), 1 artefato (otimizar imagem, extrair áudio), **zero artefato** (probe/placeholder — só `meta`), input auxiliar (watermark via `context.storage`) e requisito de runtime declarável (`TransformerRuntimeMissingError` tipado para WebCodecs/peer ausente).
+
+  O sandbox é do context, não do transformer: todo `write(relativePath, contents)` cai sob o prefixo `…/conversions/<name>/`, é validado (sem `..`/caminho absoluto — `TransformerOutputError`) e **registrado** — a lista `files` persistida vem do que foi de fato escrito, nunca da contabilidade do transformer. É isso que torna um pacote de centenas de segmentos deletável (batch via `deleteMany` em disks capazes) e servível arquivo a arquivo sem aritmética de path sobre input do caller. `MediaConversion` ganhou o shape para isso: `path`/`disk` agora opcionais (transform metadata-only não tem artefato), mais `prefix`, `files` e `meta` — as conversions de imagem existentes seguem `{ path, disk }` sem migração (colunas JSON).
+
+  **Registro e disparo.** Transformers declaram-se por collection (`transformers: [transformers.hls()]`), no mesmo namespace de nomes das presets — colisão falha no boot com `TransformerConflictError`. Vídeo é pesado e assíncrono por natureza, então nada roda no attach por padrão: o app dispara `media.library.transform(id, 'hls')` do job dele (a lib não assume sistema de filas). A chamada é **idempotente** — conversion existente ⇒ skip — e falha no meio varre os artefatos parciais e nunca persiste entry, então retry recomeça limpo. `eager: true` (para transforms baratos) roda dentro de `attach` **e** `attachExisting` — o caminho do finalize TUS via `completeUploadToLibrary`, fechando o fluxo "TUS larga os bytes, transformers derivam depois" sem fiação extra — com o mesmo rollback das conversions eager (mídia nova desfeita inteira, a anterior de uma collection `single` fica de pé). Leitura nunca gera transform: `url()`/`deliver()` numa conversion de transformer ausente lançam `TransformNotReadyError` em vez de prender um request atrás de um remux (presets de imagem continuam lazy).
+
+  **`transformers.hls()` — o transformer de vídeo.** Remuxa o vídeo para HLS (segmentos MPEG-TS + playlists de mídia atrás de um master) com [mediabunny](https://mediabunny.dev) — TypeScript puro, **sem binário ffmpeg**, peer OPCIONAL importado só no primeiro `transform()` (padrão `processors.sharp()`/`disks.s3()`; ausente ⇒ `TransformerRuntimeMissingError` com hint de install, não `ERR_MODULE_NOT_FOUND` cinco imports abaixo). Incorpora os gotchas provados em produção no protótipo do eduliberta:
+
+  - **Remux-only por padrão, com o porquê documentado**: encodar exige WebCodecs, que o Node não expõe. h264/aac copia sem re-encode (sem perda, rápido); codec que o MPEG-TS não carrega (vp9/av1) falha com `HlsSourceUnsupportedError` listando codec e razão por track — definitivo para o arquivo, não retryável.
+  - **O trim do AAC priming**: áudio AAC com edit list começa em timestamp NEGATIVO; o default do mediabunny corta em t=0, o que tiraria a track do fast path de cópia. A conversão corta no `getFirstTimestamp()` real — todas as tracks deslocam igual, sync intacto, tudo continua stream-copy.
+  - **WebCodecs injetável**: `transformers.hls({ webcodecs: () => import('@napi-rs/webcodecs') })` instala a implementação em `globalThis` (só o que falta; nativo nunca é sobrescrito) e destrava o fallback de re-encode do mediabunny para fontes incompatíveis. `resolveWebCodecsSupport()` reporta `native`/`injected`/`absent`. Multi-qualidade (ladder 360p/480p/720p via fan-out) fica como evolução documentada no roadmap sobre esse mesmo seam — não é fingida hoje.
+
+  Meta persistida: duração, resolução, codecs, contagem de segmentos/playlists, targetDuration. O engine é injetável (`HlsRemuxEngine`), então a orquestração inteira (temp files, upload streaming com contentLength, content types) é testada sem mediabunny — e um teste de integração roda o mediabunny REAL contra uma fixture h264/aac de 12 KB no CI (JS puro, funciona no ubuntu-latest), provando o caminho de produção inclusive o trim.
+
+  **`transformers.probe()` — o transformer metadata-only.** Sonda duração/resolução/codecs/sample rate e persiste só `meta`, zero artefato — a prova real do shape "sem artefato" do contrato, e o substituto do serviço manual de "baixa o arquivo e lê a duração" que todo app de mídia acaba criando.
+
+  **Delivery HLS-aware.** Playlists são armazenadas com referências relativas ao layout do storage e precisam de rewrite a cada serve. `rewriteHlsPlaylist(content, rewrite)` cobre todos os lugares onde o RFC 8216 põe uma URI — linhas de URI, atributos `URI="…"` de `#EXT-X-MEDIA` (renditions de áudio), `#EXT-X-MAP`, `#EXT-X-I-FRAME-STREAM-INF`, `#EXT-X-KEY` — reescreve só referências **relativas** (absolutas/rooted ficam como estão), preserva o resto byte a byte (CRLF incluso) e aceita rewriter async. Em cima dela, `HlsDeliveryHandler` é a rota-metade framework-agnóstica no padrão `MediaDeliveryHandler`/`TusUploadHandler`: o app monta UMA rota `(:mediaId, :file?)` com o middleware dele — **a lib não decide autorização** — e o handler serve o pacote inteiro: playlist pedida ⇒ conteúdo reescrito (sub-playlists via `urlForPlaylist` do app, para cada hop voltar pela auth; segmentos via `urlForSegment` ou, por padrão, **presigned URL direto do disk** com TTL — o caso comum pronto); segmento pedido ⇒ `redirect` presigned ou `stream` proxied (`segmentDelivery`). Arquivo pedido é validado por pertencimento à lista `files` persistida — traversal estruturalmente impossível.
+
+  **Tipos inferidos da config.** `defineConfig` agora é `<const T>` e preserva nomes literais; `InferTransformers<typeof config>` / `InferConversions<typeof config>` extraem as unions de nomes (presets + transformers) para tipar payloads de job e rotas — o padrão `InferConverters` do @jrmc/adonis-attachment, sem `as const`.
+
+  **Testing kit**: `FakeTransformer` (registra contexts, escreve artefatos configurados, `behavior` custom) ao lado do `FakeImageProcessor`.
+
+  **Cortes explícitos** (registrados no roadmap, não neste PR): multi-qualidade/ladder (exige o WebCodecs injetado; seam pronto), PosterFrame (exige decoder — idem), watermark/audio-extract/image-optimize/placeholder/transcription (o contrato acomoda os seis shapes; nada de stubs mortos), DRM/EXT-X-KEY com criptografia, HLS live/low-latency (só VOD), decorator Lucid `@media` no model do app (API desenhada no roadmap; o shape novo de `MediaConversion` já a suporta sem refactor) e a rota de delivery nomeada com inferência Tuyau + helpers Edge (idem).
+
+  Sem breaking para consumidores existentes além do type de `MediaConversion` (`path`/`disk` opcionais — 0.x, sem shim): stores existentes leem os records antigos como sempre.
+
+- [#19](https://github.com/DavideCarvalho/adonis-media/pull/19) [`f81478e`](https://github.com/DavideCarvalho/adonis-media/commit/f81478e7a683347fa4ba56c9fb8d5614c2e95477) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Magic-byte signatures for the common video containers — and with them, video collections finally get a real whitelist
+
+  The signature table covered PNG/JPEG/GIF/WEBP/PDF and **no video format**. That had two concrete consequences for any collection gating video:
+
+  - No video was ever _detectable_, so a whitelist like `['video/mp4']` could never be **closed** (see 0.8.0): the closed-whitelist rejection for unrecognisable content simply never activated, and anything without a known signature — a `.txt`, an executable, random bytes — sailed through `attach`/`attachExisting`/TUS as long as the caller declared `video/mp4`.
+  - `attachExisting` could not catch content disguised as a video: a PNG uploaded as `clip.mp4` produced no `ContentTypeMismatchError`, because the detector had no idea what an MP4 looks like.
+
+  The table now recognises:
+
+  - **`video/mp4`** — ISO-BMFF `ftyp` box (bytes 4–7; the first 4 bytes are the box _size_ and vary per file, so they are skipped — the existing `[offset, hex]` parts mechanism already expresses this) with a major brand from the recognised set: `isom`, `iso2`–`iso6`, `mp41`, `mp42`, `avc1`, `av01`, `dash`. One table entry per brand, the GIF87a/GIF89a pattern.
+  - **`video/quicktime`** — the same `ftyp` box with major brand `qt  `. Same container, different type: a `.mov` relabeled `video/mp4` is now a positive **mismatch**, not a pass.
+  - **`video/webm`** / **`video/x-matroska`** — EBML magic `1A45DFA3` at offset 0, discriminated by the `DocType` element (`webm` vs `matroska`). DocType sits inside a variable-length EBML header, so its offset depends on the muxer — the one thing fixed offsets cannot express. The signature mechanism gained a minimal `scan` field: a byte run (element id + size + doc type string, so it cannot fire on stray text) that must appear _anywhere_ in the head, checked only **after** the fixed parts already identified the container. No EBML parser, no new dependency.
+  - **`video/x-msvideo`** — `RIFF` + `AVI ` form type (bytes 4–7 are the chunk size and skipped, exactly like WEBP).
+  - **`video/mp2t`** — MPEG transport stream. There is no magic number, only the `0x47` sync byte opening every 188-byte packet; one byte would collide with anything starting with `G`, so the sync byte is required at the start of the first **two** packets (offsets 0 and 188). It is the weakest signature and sits last in the table, so it can never shadow a stronger match.
+
+  `SIGNATURE_HEAD_BYTES` grows from 16 to **189** (the second TS sync byte). All the sniffing paths already read exactly this constant and handle short payloads: `attach` still peeks and replays the head without buffering the payload, `attachExisting` still tears the disk stream down after one short read, and a head shorter than a signature's deepest offset degrades to _unrecognised_, never to a false positive.
+
+  Deliberate non-guesses, so a legitimate file never turns into a false mismatch: an `ftyp` brand outside the set above (3GPP's `3gp*`, Apple's `M4A `/`M4V `) and an EBML DocType that is neither `webm` nor `matroska` stay **unrecognised** — under an open whitelist they fall back to the declared type exactly as before.
+
+  **Behaviour change to review if you gate video:** a whitelist made up entirely of the types above — `['video/mp4']` being the canonical case — was open and is now **closed**. Three things follow:
+
+  1. Content whose signature contradicts the declared type is rejected with `ContentTypeMismatchError` (`E_MEDIA_CONTENT_TYPE_MISMATCH`) — the PNG-disguised-as-MP4 case, previously accepted.
+  2. Content matching _no_ signature is rejected with `ContentSignatureUnrecognizedError` (`E_MEDIA_CONTENT_SIGNATURE_UNRECOGNIZED`), per the 0.8.0 closed-whitelist rule that never activated for video before.
+  3. Legitimate videos whose real container differs from the declared type — `.mov`/`.mkv`/`.avi` files uploaded under a blanket `video/mp4` — now fail instead of slipping through. If your collection genuinely accepts them, list what you accept: `acceptsMimeTypes: ['video/mp4', 'video/quicktime', 'video/webm']`.
+
+  Applies uniformly to `attach`, `attachExisting` and the TUS first-chunk check, which all share `verifyContentAgainstWhitelist`.
+
+## 0.8.2
+
+### Patch Changes
+
+- [#17](https://github.com/DavideCarvalho/adonis-media/pull/17) [`e911880`](https://github.com/DavideCarvalho/adonis-media/commit/e911880969a28dd6bdbc0c56181462628eec1a4d) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Corrige dois pontos onde este pacote ainda capturava um singleton do `@adonisjs/core` via `import`
+  de módulo em vez de recebê-lo do provider — o mesmo formato de dual-package hazard que já havia
+  derrubado o `Database` do Lucid em produção (ver o changeset `lucid-string-token`), só que agora nos
+  singletons `app` e `router` do próprio core.
+
+  **1 — `app` capturado eager em `services/main.ts` e `single_file_store.ts`.** Ambos faziam
+  `import app from '@adonisjs/core/services/app'` no topo do módulo. Esse binding só é preenchido via
+  `setApp()` chamado pelo Ignitor da app hospedeira; se a árvore de dependências contiver DUAS cópias
+  físicas de `@adonisjs/core` (pnpm workspace hoisting, pins divergentes, ou até a mesma versão
+  resolvida sob peer-sets diferentes), a cópia que este pacote importa nunca recebe esse `setApp()` — o
+  `app` fica `undefined` e qualquer uso quebra com um `Cannot read properties of undefined` opaco.
+
+  A correção segue o padrão já usado pelo `@adonis-agora/authz` (`services/booted_app.ts`): o
+  `MediaProvider.register()` agora captura a instância de `ApplicationService` que a própria aplicação
+  lhe entrega — que é sempre a cópia correta, seja qual for a duplicação na árvore — e a expõe via um
+  módulo interno (`src/services/booted_app.ts`) para `services/main.ts` e `single_file_store.ts`
+  lerem. Nenhuma mudança de API: `media.library.attach(...)` e as funções `storeSingleFile` /
+  `removeSingleFile` / `isSingleFileStoreAvailable` continuam idênticas por fora.
+
+  **2 — `router` resolvido eager e usado síncrono em `providers/media_provider.ts`.** O provider
+  importava `router` de `@adonisjs/core/services/router` no topo do módulo e chamava `router.get(...)`
+  / `router.post(...)` direto dentro de `boot()`. Esse serviço específico só é atribuído dentro de um
+  hook `app.booted(...)` no próprio módulo `services/router.ts` do core — que dispara estritamente
+  DEPOIS do `boot()` de todos os providers. Ou seja, mesmo numa árvore com uma única cópia do core,
+  usar esse import de forma síncrona em `boot()` já é uma corrida contra o próprio mecanismo que o
+  preenche; numa árvore duplicada o problema se soma ao caso 1.
+
+  A montagem das rotas (`/media/uploads/direct/*`, `/media/uploads/proxy`, `/media/uploads/tus/*`)
+  agora é adiada para dentro de `app.booted(...)` — o mesmo padrão já documentado e em produção no
+  `DashboardProvider` do `@adonis-agora/durable`. Verificado que isso é seguro para o ciclo de vida do
+  Adonis: os hooks `booted` de TODOS os providers disparam antes do `Server#boot()` do
+  `@adonisjs/http-server` (que roda dentro de `app.start()`) chamar `router.commit()` — o último ponto
+  em que rotas ainda podem ser adicionadas. Dentro do hook, o `router` é resolvido pelo container
+  (`app.container.make('router')`) a partir do `this.app` do provider, imune à duplicação da mesma
+  forma que o caso 1.
+
+  Nenhuma mudança de comportamento observável: as mesmas rotas são montadas, só que um instante mais
+  tarde no boot (antes do servidor HTTP subir, nunca depois).
+
+  Também adicionado `prepack` ao `package.json` do pacote publicável, espelhando o `build`.
+
 ## 0.8.1
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,206 @@
+# @adonis-agora/media
+
+Media-library for **AdonisJS**, part of the [Agora](https://github.com/DavideCarvalho) ecosystem — the
+spatie/laravel-media-library feel, on top of [`@adonisjs/drive`](https://github.com/adonisjs/drive).
+
+Attach files to entities, organize them into collections (MIME whitelist, single-file replace,
+ordering), and generate image conversions (eager or lazy). Storage is delegated entirely to Drive, so
+you reuse your existing `local` / `s3` / `gcs` disks — this package never reimplements disk drivers.
+
+This is the **core library**: `MediaLibrary`, `AttachmentManager`, the `MediaStore` SPI (in-memory +
+Lucid), the `ImageProcessor` SPI (sharp), the bundled `disks.s3()` driver, proxy/direct/resumable
+uploads, configurable delivery, the provider + `defineConfig`, and a testing kit. Pair it with
+[`@adonis-agora/media-react`](https://github.com/DavideCarvalho/adonis-media/tree/master/packages/react)
+for a browser upload client, or
+[`@adonis-agora/media-dashboard`](https://github.com/DavideCarvalho/adonis-media/tree/master/packages/dashboard)
+for a management console.
+
+## Subpath exports
+
+The package uses **subpath exports** (the Agora idiom), so heavy backends stay optional:
+
+| Subpath | What |
+|---|---|
+| `@adonis-agora/media` | barrel — `defineConfig`, `stores`, `processors`, `disks`, `uploadSessions`, `MediaManager`, `MediaLibrary`, `AttachmentManager`, `UploadManager`, `ResumableUploadManager`, `MediaDeliveryHandler`, SPIs, errors |
+| `@adonis-agora/media/media_provider` | the service provider (binds `MediaManager`, mounts optional upload/TUS routes) |
+| `@adonis-agora/media/configure` | `node ace configure` hook |
+| `@adonis-agora/media/single-file` | `storeSingleFile` / `removeSingleFile` / `isSingleFileStoreAvailable` — lets other packages delegate single-file uploads (e.g. avatars) to media without a hard dependency |
+| `@adonis-agora/media/stores/lucid` | the Lucid `MediaStore` (`@adonisjs/lucid` peer) |
+| `@adonis-agora/media/upload_sessions/lucid` | the Lucid resumable `UploadSessionStore` (`@adonisjs/lucid` peer) |
+| `@adonis-agora/media/disks/s3` | the bundled `S3Disk` (`@aws-sdk/client-s3` peer; presigning is hand-rolled SigV4) |
+| `@adonis-agora/media/processors/sharp` | the sharp `ImageProcessor` (`sharp` peer) |
+| `@adonis-agora/media/telescope` | `mediaTelescopeExtension` (`@adonis-agora/telescope` optional peer) |
+| `@adonis-agora/media/testing` | `InMemoryMediaStore`, `InMemoryDisk`, `inMemoryDiskResolver`, `FakeImageProcessor`, `InMemoryUploadSessionStore` |
+| `@adonis-agora/media/types` | the structural `Disk` / `DiskResolver` / `ExtendedDisk` / `MultipartUploadDisk` contracts |
+
+## Install
+
+```sh
+node ace add @adonisjs/drive   # storage backend (required)
+npm i @adonis-agora/media
+node ace configure @adonis-agora/media
+```
+
+`configure` registers the provider, publishes `config/media.ts`, and publishes the `media` table
+migration (delete it if you only use the in-memory store; otherwise `node ace migration:run`).
+
+Optional peers, loaded lazily only when selected:
+
+- `@adonisjs/lucid` (`^22.4.0`) — the `lucid` `MediaStore` / `UploadSessionStore`
+- `sharp` (`^0.33.0`) — image conversions
+- `@aws-sdk/client-s3` (`^3.0.0`) — the bundled `disks.s3()` driver (presigned URLs are hand-rolled SigV4, no presigner package)
+- `@adonis-agora/telescope` (`^0.4.0`) — the Telescope watcher extension
+
+## Configure
+
+```ts
+// config/media.ts
+import { defineConfig, stores, processors } from '@adonis-agora/media'
+
+export default defineConfig({
+  // disk: 's3',                 // omit to use Drive's default disk
+  store: 'lucid',
+  stores: {
+    memory: stores.memory(),
+    lucid: stores.lucid({ connection: 'pg' }),
+  },
+  imageProcessor: processors.sharp(),
+  collections: [
+    { name: 'avatar', single: true, acceptsMimeTypes: ['image/png', 'image/jpeg'] },
+    {
+      name: 'gallery',
+      conversions: [
+        { name: 'thumb', width: 200, height: 200 },
+        { name: 'og', width: 1200, eager: true },
+      ],
+    },
+  ],
+})
+```
+
+## Use
+
+The provider binds a singleton `MediaManager`; reach it with the service import (or `@inject()` it).
+A real upload controller loads the owner, validates the file, and streams its tmp bytes into a
+collection:
+
+```ts
+// app/controllers/post_images_controller.ts
+import { createReadStream } from 'node:fs'
+import Post from '#models/post'
+import media from '@adonis-agora/media/services/main'
+import type { HttpContext } from '@adonisjs/core/http'
+
+export default class PostImagesController {
+  async store({ request, response, params }: HttpContext) {
+    const post = await Post.findOrFail(params.id)
+
+    const image = request.file('image', { size: '5mb', extnames: ['jpg', 'png', 'webp'] })
+    if (!image) return response.badRequest({ error: 'An "image" file is required' })
+
+    const record = await media.library.attach({
+      ownerType: 'Post',
+      ownerId: post.id, // string | number — coerced for you
+      collection: 'gallery',
+      fileName: image.clientName,
+      mimeType: image.type!,
+      contents: createReadStream(image.tmpPath!), // Buffer | Readable
+    })
+
+    return response.created({ id: record.id, url: await media.library.url(record.id) })
+  }
+}
+```
+
+Reading, listing and deleting go through the same `media` singleton:
+
+```ts
+await media.library.url(record.id)            // public url of the original
+await media.library.url(record.id, 'thumb')   // generated lazily on first call, then cached
+await media.library.list('Post', post.id, 'gallery')
+await media.library.delete(record.id)
+
+// Or bind an owner once for a bulk upload
+const gallery = media.library.for('Post', post.id)
+await gallery.attach({ collection: 'gallery', fileName: image.clientName, mimeType: image.type!, contents })
+
+// Column attachments (adonis-attachment style) — store the value object on a JSON column
+const att = await media.attachments.createFromFile(
+  { fileName: image.clientName, mimeType: image.type!, contents },
+  { variants: [{ name: 'thumb', width: 100 }] },
+)
+user.avatarData = att.toJSON()
+await media.attachments.url(att, 'thumb')
+```
+
+A `ConversionPreset` is `{ name, width?, height?, fit?, format?, quality?, eager? }`. Eager presets are
+generated synchronously on `attach`; the rest are generated lazily on the first `url(id, name)` and
+cached on the record. `fit` and `format` map straight onto sharp.
+
+## Uploads, S3 and delivery
+
+Large-file uploads ship in three flavours — **proxy** (bytes stream through your app), **direct-S3
+multipart** (the browser uploads straight to the bucket via presigned part URLs), and **resumable
+[tus](https://tus.io)** sessions (pluggable in-memory + Lucid session stores). Opt in under `uploads`
+in `config/media.ts`; the provider mounts the routes under `/media/uploads` and `/media/uploads/tus`.
+
+```ts
+export default defineConfig({
+  // ...
+  uploads: {
+    mode: 'auto', // 'direct' | 'proxy' | 'auto'
+    routes: { enabled: true },
+    resumable: { routes: { enabled: true } },
+  },
+  delivery: { mode: 'auto' }, // 'public' | 'signed' | 'proxy' | 'auto'
+})
+```
+
+`delivery` is the read-side counterpart to `uploads.mode`: `MediaLibrary.deliver(id, options?)`
+resolves to a discriminated union — `{ kind: 'redirect', url }` for `public`/`signed`, or
+`{ kind: 'stream', stream, mimeType, size, fileName }` for `proxy` — so a private bucket doesn't need
+a hand-rolled streaming route. `MediaDeliveryHandler` and `TusUploadHandler` are the framework-agnostic
+route halves your app mounts with its own middleware; **neither performs authorization** — guard the
+route before calling `handle`.
+
+The bundled `disks.s3()` driver adds extended operations (copy/move/deleteMany/list/size/stat) and
+native multipart over the optional AWS SDK peer. Drive it from the browser with
+[`@adonis-agora/media-react`](https://github.com/DavideCarvalho/adonis-media/tree/master/packages/react).
+
+## Diagnostics
+
+Lifecycle events (`attach`, `delete`, `conversion`, `attachment.create`, `attachment.delete`) are
+emitted on the `agora:media:*` channel via the `@agora/diagnostics:emit` global slot — read
+structurally, with **no hard dependency** on `@adonis-agora/diagnostics`. When that package isn't
+installed, emitting is an inert no-op; when it is, the Telescope generic watcher (or
+`@adonis-agora/media/telescope`) captures every media event automatically.
+
+## Testing
+
+`@adonis-agora/media/testing` ships in-memory doubles for the SPIs so you can exercise the library
+without a disk, database, or sharp:
+
+```ts
+import { MediaLibrary, StorageManager } from '@adonis-agora/media'
+import { InMemoryMediaStore, inMemoryDiskResolver, FakeImageProcessor } from '@adonis-agora/media/testing'
+
+const { resolve, disks } = inMemoryDiskResolver(['fs'])
+const library = new MediaLibrary({
+  storage: new StorageManager({ default: 'fs', resolve }),
+  store: new InMemoryMediaStore(),
+  imageProcessor: new FakeImageProcessor(),
+})
+```
+
+In a real app you can also `drive.fake()` from `@adonisjs/drive` to back the disks with an in-memory
+fake while keeping the rest of the wiring intact.
+
+## Links
+
+- Repo: https://github.com/DavideCarvalho/adonis-media
+- Changelog: https://github.com/DavideCarvalho/adonis-media/blob/master/packages/adonis/CHANGELOG.md
+- Sibling packages: [`@adonis-agora/media-react`](https://github.com/DavideCarvalho/adonis-media/tree/master/packages/react), [`@adonis-agora/media-dashboard`](https://github.com/DavideCarvalho/adonis-media/tree/master/packages/dashboard)
+
+## License
+
+MIT

package/dist/providers/media_provider.d.ts

@@ -17,19 +17,9 @@ export default class MediaProvider {
     constructor(app: ApplicationService);
     register(): void;
     /**
-     * Mount the optional direct-S3 upload routes when `uploads.routes.enabled` is set. These are plain
-     * AdonisJS routes (NOT controllers): each resolves the {@link MediaManager} singleton lazily and
-     * delegates to its upload methods. The object key is taken from the request body/query — resolve
-     * it server-side (per user/tenant) in a real app so a client can't point an upload at another
-     * object.
-     *
-     * Routes (relative to `uploads.routes.prefix`, default `/media/uploads`):
-     * - `POST   /direct/initiate`                    → presign multipart parts
-     * - `POST   /direct/:uploadId/parts/:partNumber` → presign one (retried) part
-     * - `POST   /direct/:uploadId/complete`          → assemble the parts
-     * - `DELETE /direct/:uploadId`                   → abort the upload
-     * - `PUT    /proxy`                              → stream bytes through the app (proxy mode)
+     * Mount the media routes once the app has booted (see the comment inside for why). No-ops when
+     * neither the TUS resumable routes nor the direct-upload routes are enabled in config.
      */
-    boot(): void;
+    boot(): Promise<void>;
 }
 //# sourceMappingURL=media_provider.d.ts.map

package/dist/providers/media_provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"media_provider.d.ts","sourceRoot":"","sources":["../../providers/media_provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAe/D;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,OAAO,OAAO,aAAa;;IACpB,SAAS,CAAC,GAAG,EAAE,kBAAkB;gBAAvB,GAAG,EAAE,kBAAkB;IAE7C,QAAQ;IA4ER;;;;;;;;;;;;;OAaG;IACH,IAAI;CA0ML"}
+{"version":3,"file":"media_provider.d.ts","sourceRoot":"","sources":["../../providers/media_provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAqB,MAAM,sBAAsB,CAAC;AAkBlF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,OAAO,OAAO,aAAa;;IACpB,SAAS,CAAC,GAAG,EAAE,kBAAkB;gBAAvB,GAAG,EAAE,kBAAkB;IAE7C,QAAQ;IA+GR;;;OAGG;IACG,IAAI;CAqWX"}

package/dist/providers/media_provider.js

@@ -1,7 +1,8 @@
-import router from '@adonisjs/core/services/router';
+import { DirectUploadHandler } from '../src/direct_upload_handler.js';
 import { createDriveBackedResolver } from '../src/disks/drive.js';
 import { resolveConfiguredDisks } from '../src/disks/factory.js';
 import { MediaManager } from '../src/media_manager.js';
+import { setBootedApp } from '../src/services/booted_app.js';
 import { resolveStore } from '../src/stores/factory.js';
 import { TusUploadHandler } from '../src/tus.js';
 import { resolveUploadSessionStore } from '../src/upload_sessions/factory.js';
@@ -23,6 +24,11 @@ export default class MediaProvider {
         this.app = app;
     }
     register() {
+        // Hand the booted app to the internal singleton so it never has to `import` an
+        // `@adonisjs/core` copy that may not be the one `bin/server` booted (see
+        // `../src/services/booted_app.js`) — mirrors the fix already applied to the `@adonisjs/lucid`
+        // `Database` token (`'lucid.db'` string alias) for the same class of dual-package hazard.
+        setBootedApp(this.app);
         this.app.container.singleton(MediaManager, async () => {
             const config = this.app.config.get('media', {});
             // Validate + build the store from config first, so a misconfigured `store` fails fast (before
@@ -39,6 +45,16 @@ export default class MediaProvider {
                     ...(resumable.stores !== undefined ? { stores: resumable.stores } : {}),
                 }, { app: this.app })
                 : undefined;
+            // Same lazy, opt-in construction for the session-backed direct upload store. It may share
+            // the resumable store's Lucid tables, but each subsystem owns its store INSTANCE so enabling
+            // one never implies the other.
+            const direct = config.uploads?.direct;
+            const directUploadSessions = direct
+                ? await resolveUploadSessionStore({
+                    ...(direct.store !== undefined ? { store: direct.store } : {}),
+                    ...(direct.stores !== undefined ? { stores: direct.stores } : {}),
+                }, { app: this.app })
+                : undefined;
             // Build any disks declared in `config.disks` (e.g. the bundled `disks.s3()` driver). Each
             // factory lazily loads its peer (the AWS SDK), so nothing is imported unless an S3 disk is
             // actually configured.
@@ -77,6 +93,21 @@ export default class MediaProvider {
                 ...(resumable?.sessionTtlSeconds !== undefined
                     ? { resumableSessionTtlSeconds: resumable.sessionTtlSeconds }
                     : {}),
+                ...(directUploadSessions !== undefined ? { directUploadSessions } : {}),
+                // Direct settings fall back to the shared `uploads.*` knobs, so one part size / TTL can
+                // govern both the raw primitives and the session flow.
+                ...((direct?.partSize ?? config.uploads?.partSize)
+                    ? { directPartSize: (direct?.partSize ?? config.uploads?.partSize) }
+                    : {}),
+                ...((direct?.presignTtlSeconds ?? config.uploads?.presignTtlSeconds)
+                    ? {
+                        directPresignTtlSeconds: (direct?.presignTtlSeconds ??
+                            config.uploads?.presignTtlSeconds),
+                    }
+                    : {}),
+                ...(direct?.sessionTtlSeconds !== undefined
+                    ? { directSessionTtlSeconds: direct.sessionTtlSeconds }
+                    : {}),
                 // Delivery is config only — no route is mounted for it, deliberately: serving a record is
                 // an authorization decision, so the app owns the route (see `MediaDeliveryHandler`).
                 ...(config.delivery?.mode !== undefined ? { deliveryMode: config.delivery.mode } : {}),
@@ -86,6 +117,35 @@ export default class MediaProvider {
             });
         });
     }
+    /**
+     * Mount the media routes once the app has booted (see the comment inside for why). No-ops when
+     * neither the TUS resumable routes nor the direct-upload routes are enabled in config.
+     */
+    async boot() {
+        // Route registration can't happen synchronously in `boot()`: at this point in the AdonisJS
+        // lifecycle the HTTP server/router binding may not be resolvable yet (bindings from other
+        // providers' `boot()` methods can still be pending), and — critically — the *documented*
+        // `@adonisjs/core/services/router` singleton is only assigned once the app's "booted" hooks run
+        // (`await app.booted(async () => { router = ... })` inside that service module itself), which
+        // fire strictly AFTER every provider's own `boot()`. A provider that imports that singleton and
+        // calls `router.get(...)` directly inside `boot()` crashes every entrypoint (serve/ace/tests)
+        // that registers it, because `router` is still `undefined` at that point — the same hazard this
+        // provider now avoids for `MediaManager` itself (see `../src/services/booted_app.js`).
+        //
+        // Deferring to `app.booted(...)` runs our route registration as another "booted" hook — the
+        // same mechanism the router service uses to become available in the first place — which is
+        // guaranteed to fire BEFORE the HTTP server's own `boot()` commits the router (the last point at
+        // which routes can still be added; see `Server#boot()` in `@adonisjs/http-server`, which runs
+        // inside `app.start()`, strictly after all "booted" hooks). Resolving `router` fresh from the
+        // container here (rather than depending on that service singleton) is also the same pattern
+        // `@adonisjs/core`'s own `AppServiceProvider` and `@adonis-agora/durable`'s `DashboardProvider`
+        // use internally, and is immune to the dual-package hazard for the same reason `booted_app.ts`
+        // is: it comes from `this.app` (captured at registration), never from a module-level import.
+        await this.app.booted(async () => {
+            const router = await this.app.container.make('router');
+            this.#registerRoutes(router);
+        });
+    }
     /**
      * Mount the optional direct-S3 upload routes when `uploads.routes.enabled` is set. These are plain
      * AdonisJS routes (NOT controllers): each resolves the {@link MediaManager} singleton lazily and
@@ -100,9 +160,10 @@ export default class MediaProvider {
      * - `DELETE /direct/:uploadId`                   → abort the upload
      * - `PUT    /proxy`                              → stream bytes through the app (proxy mode)
      */
-    boot() {
+    #registerRoutes(router) {
         const config = this.app.config.get('media', {});
-        this.#mountTusRoutes(config);
+        this.#mountTusRoutes(router, config);
+        this.#mountDirectSessionRoutes(router, config);
         const routes = config.uploads?.routes;
         if (!routes?.enabled)
             return;
@@ -202,7 +263,7 @@ export default class MediaProvider {
      * Set `uploads.resumable.routes.collection` to have the handler enforce that collection's
      * `acceptsMimeTypes` at create time and on the first chunk (`415`), instead of only at attach.
      */
-    #mountTusRoutes(config) {
+    #mountTusRoutes(router, config) {
         const resumable = config.uploads?.resumable;
         if (!resumable?.routes?.enabled)
             return;
@@ -254,6 +315,92 @@ export default class MediaProvider {
         router.patch(`${prefix}/:id`, run('PATCH', true)).as('media.uploads.tus.patch');
         router.delete(`${prefix}/:id`, run('DELETE')).as('media.uploads.tus.delete');
     }
+    /**
+     * Mount the optional session-backed direct upload routes when `uploads.direct.routes.enabled`.
+     * Plain AdonisJS routes (NOT controllers), each driving a framework-agnostic
+     * {@link DirectUploadHandler} over `media.direct` — mirroring the TUS mount. The client sends a
+     * `fileName`, never a key: the key is resolved server-side by the handler's `keyFor`.
+     *
+     * Routes (relative to `uploads.direct.routes.prefix`, default `/media/uploads/direct/sessions`):
+     * - `POST   /`                      → initiate: persist a session, presign every part URL
+     * - `GET    /:id`                   → status: confirmed ETags + fresh URLs for pending parts
+     * - `POST   /:id/parts/:partNumber` → confirm one uploaded part's ETag
+     * - `POST   /:id/complete`          → assemble the parts into the final object
+     * - `DELETE /:id`                   → abort
+     *
+     * Like every built-in route these are UNGUARDED — add your own auth middleware, or leave them off
+     * and mount your own routes over the handler/manager.
+     */
+    #mountDirectSessionRoutes(router, config) {
+        const direct = config.uploads?.direct;
+        if (!direct?.routes?.enabled)
+            return;
+        const prefix = (direct.routes.prefix ?? '/media/uploads/direct/sessions').replace(/\/+$/, '');
+        const routeDisk = direct.routes.disk;
+        const maxSize = direct.routes.maxSize;
+        const collection = direct.routes.collection;
+        // Build the handler once, on first request, from the resolved MediaManager singleton.
+        let handler;
+        const getHandler = async () => {
+            if (!handler) {
+                const media = await this.app.container.make(MediaManager);
+                handler = new DirectUploadHandler({
+                    manager: media.direct,
+                    ...(routeDisk !== undefined ? { disk: routeDisk } : {}),
+                    ...(collection !== undefined ? { collection } : {}),
+                    ...(maxSize !== undefined ? { maxSize } : {}),
+                });
+            }
+            return handler;
+        };
+        const run = (toRequest) => {
+            return async (ctx) => {
+                const direct_ = await getHandler();
+                const res = await direct_.handle(toRequest(ctx));
+                ctx.response.status(res.status);
+                return res.body ?? '';
+            };
+        };
+        router
+            .post(prefix, run((ctx) => {
+            const body = ctx.request.body();
+            return {
+                action: 'initiate',
+                fileName: body.fileName,
+                size: body.size,
+                ...(body.contentType !== undefined ? { contentType: body.contentType } : {}),
+                ...(body.metadata !== undefined ? { metadata: body.metadata } : {}),
+            };
+        }))
+            .as('media.uploads.direct.sessions.initiate');
+        router
+            .get(`${prefix}/:id`, run((ctx) => ({ action: 'status', uploadId: String(ctx.params.id) })))
+            .as('media.uploads.direct.sessions.status');
+        router
+            .post(`${prefix}/:id/parts/:partNumber`, run((ctx) => {
+            const body = ctx.request.body();
+            return {
+                action: 'confirm-part',
+                uploadId: String(ctx.params.id),
+                partNumber: Number(ctx.params.partNumber),
+                etag: body.etag,
+            };
+        }))
+            .as('media.uploads.direct.sessions.confirmPart');
+        router
+            .post(`${prefix}/:id/complete`, run((ctx) => {
+            const body = ctx.request.body();
+            return {
+                action: 'complete',
+                uploadId: String(ctx.params.id),
+                ...(body.parts !== undefined ? { parts: body.parts } : {}),
+            };
+        }))
+            .as('media.uploads.direct.sessions.complete');
+        router
+            .delete(`${prefix}/:id`, run((ctx) => ({ action: 'abort', uploadId: String(ctx.params.id) })))
+            .as('media.uploads.direct.sessions.abort');
+    }
     /** A config `imageProcessor` may be a ready instance or a lazy factory thunk. */
     async #resolveImageProcessor(config) {
         const ip = config.imageProcessor;