Delivery

The library has a configurable strategy for writes (uploads.mode). delivery is its mirror image for reads.

Without it, every app re-derives the same decision by hand: call url() on a public bucket, signedUrl() on a private one — and when the storage isn't reachable from the internet at all (a bucket on a private network, MinIO on an internal host), hand-roll a route that opens a stream and pipes it. That route is the same in every app, so it belongs here.

export default defineConfig({
  delivery: {
    mode: 'auto',          // 'auto' (default) | 'public' | 'signed' | 'proxy'
    signedTtlSeconds: 300, // lifetime of the signed URL when mode resolves to 'signed'
  },
})

How auto decides

It asks the disk: getVisibility(key) — public ⇒ public, private ⇒ signed. Every @adonisjs/drive disk implements it, and the bundled disks.s3() answers from its declarative visibility option (default private, never an ACL round-trip).

A disk that can't answer leaves visibility genuinely unknown, and auto then resolves to signed — the safe read of "unknown", and one that works on a public object too. auto deliberately does not infer visibility from getUrl being callable: a URL can always be synthesised for a private object, so that inference would hand out links that 403.

Mounting a route

MediaDeliveryHandler is framework-agnostic, exactly like TusUploadHandler: you mount the route, with your own middleware, and delegate the "how do these bytes reach the client" question to it.

import { MediaDeliveryHandler, MediaManager } from '@adonis-agora/media'

const media = await app.container.make(MediaManager)
const delivery = new MediaDeliveryHandler({ library: media })

router
  .get('/media/:id', async ({ params, request, response, auth }) => {
    await authorizeMediaAccess(auth.user, params.id) // ← your rule, see below

    const result = await delivery.handle({
      mediaId: params.id,
      conversion: request.input('conversion'),
    })

    if (result.kind === 'redirect') return response.redirect(result.url)

    response.header('content-type', result.mimeType)
    if (result.size !== undefined) response.header('content-length', String(result.size))
    response.header('content-disposition', `inline; filename="${result.fileName}"`)
    return response.stream(result.stream)
  })
  .use(middleware.auth())

The handler's own mode / signedTtlSeconds override the configured ones, so one app can serve avatars as public URLs and exam PDFs through a proxy route.

Without a route

library.deliver() returns the same union, for jobs, console commands, or a controller you'd rather write yourself:

const result = await media.library.deliver(id, { conversion: 'thumb', mode: 'signed' })

In proxy mode the mimeType and size come from the disk's metadata rather than the record's, because a conversion has its own format and length — a thumb of a PNG may well be a WEBP.

HLS packages

A transformer-generated HLS conversion is not one file but a package of playlists and segments, and its playlists must be rewritten per request — deliver(id, { conversion: 'hls' }) would hand you the raw master playlist with storage-relative references. Serve those through the dedicated HlsDeliveryHandler, which follows this page's philosophy exactly: you mount one route, your auth guards it, the handler answers "how".