Streaming read/write in the plugin media API (MediaAccess)

[MA2153]

Summary

The capability-gated ctx.media given to plugins (MediaAccess / MediaAccessWithWrite) exposes no way to read media content and no streaming on either read or write. Plugins that transform media are forced to either buffer whole files in memory (OOM in the worker) or reach around the abstraction into the raw storage binding.

Current surface

MediaAccess / MediaAccessWithWrite:

• get(id) → MediaItem — metadata only (size, url, …); no content
• upload(filename, contentType, bytes: ArrayBuffer) — bytes-only
• getUploadUrl() — presigned URL, explicitly noted as unusable by sandboxed plugins (which can't make external requests)
• list, delete

There is no content-read method at all, and no ReadableStream path in or out.

Consequence

A sandboxed plugin (media:read / media:write) that reads a source object, transforms it, and writes a derived object must:

1. Bypass the abstraction to the deployment's raw storage binding to read content (which couples the plugin to the storage provider), and
2. Buffer the full output as an ArrayBuffer to call upload.

In a Worker (~128 MB memory ceiling), holding input + a copy + output simultaneously OOM-crashes on large files.

Notably, the underlying StorageProvider already streams both ways — download(key) → { body: ReadableStream } and upload({ body: ReadableStream }). The capability exists at the storage layer; it just isn't surfaced through the plugin-facing media API.

Proposed

• Add a content read to MediaAccess — e.g. download(id): Promise<{ body: ReadableStream<Uint8Array>; size: number | null; mimeType: string }> — plumbed to the provider's existing download.
• Add a streaming upload overload to MediaAccessWithWrite accepting ReadableStream<Uint8Array> alongside ArrayBuffer, plumbed to the provider's existing streaming upload.

This lets a sandboxed plugin stream source → transform → derived in O(1) memory, without touching the raw storage binding.

Trigger (abstract)

Any sandboxed media-transform plugin: for inputs larger than the worker memory ceiling it cannot complete without either bypassing ctx.media or OOMing. Reproducible with a trivial "copy/transform one media item to another" plugin, independent of content type.