# Storage
> File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / MinIO (R2 and GCS via their S3 interop) / Azure / database / filesystem / memory providers, presigned URLs, a dashboard browser.
---
## Storage
_File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / MinIO (R2 and GCS via their S3 interop) / Azure / database / filesystem / memory providers, presigned URLs, a dashboard browser._
`@voltro/plugin-storage` is file storage behind one `StorageService`. Wire a
provider in `app.config.ts`; consume it in handlers and actions via
`yield* StorageService`. The bytes live in the provider (S3-compatible bucket,
filesystem, or in-memory); metadata rows live in `_voltro_storage_refs` +
`_voltro_storage_grants` (both auto-migrated on a SQL store).
Every object is **public** or **private**:
- **Public** — cacheable + no auth. With `cdnBaseUrl` (or `STORAGE_CDN_URL`)
set to a CDN / publicly-readable bucket endpoint, the serve route 302s
straight there and the app never touches the read path (edge-cacheable).
WITHOUT `cdnBaseUrl`, the serve route streams the bytes through the app
from the (private) bucket with a 1-year `immutable` cache — still
browser-cacheable, bucket stays private. A bare S3/MinIO bucket is private
by default, so the framework never 302s to a raw bucket URL unless you've
declared a public base via `cdnBaseUrl` (otherwise it would land on a 403).
- **Private** (the default — secure by default) — gated by an **access policy**
plus **per-object grants**; delivered via a presigned URL or a short-lived
signed grant token.
## Quick start
```ts
// app.config.ts
import { storagePlugin } from '@voltro/plugin-storage'
export default {
type: 'api' as const,
name: 'myApi',
store: 'postgres' as const,
plugins: [
// dev: zero-config in-memory. prod: swap the provider (see below).
storagePlugin({ provider: 'memory' }),
],
}
```
```ts
// actions/uploadAvatar.action.server.ts (+ matching .action.ts)
import { StorageService } from '@voltro/plugin-storage'
import { Effect } from 'effect'
export default (input: { bytes: Uint8Array; contentType: string }, ctx) =>
Effect.gen(function* () {
const storage = yield* StorageService
const ref = yield* storage.put({
bytes: input.bytes,
contentType: input.contentType,
visibility: 'public', // public avatar
ownerId: ctx.request.subject.id,
key: `avatars/${ctx.request.subject.id}/avatar.png`,
})
// For a public object this is the CDN/bucket URL (no app round-trip).
return { url: yield* storage.getUrl(ref.id) }
})
```
The ref id is a `file_…` TypeID — URL-safe and unguessable.
## Uploading files — `useUpload()` (client)
The one-liner. Works on every provider (filesystem/dev, s3/r2/prod),
cross-origin, no base64:
```tsx
import { useUpload } from '@voltro/client'
function AvatarUpload() {
const { upload, progress, status, cancel } = useUpload('myApi')
return (
{
const file = e.target.files?.[0]
if (!file) return
const asset = await upload(file, { visibility: 'public', folder: 'avatars' })
// asset: { id, url, name, mime, size, width?, height? }
}} />
)
}
```
`useUpload(apiName)` returns `{ upload, uploadMany, progress (0..1), status,
error, cancel, reset }`. Under the hood it calls the authenticated
`storage.mintUploadTicket` rpc (which runs your auth chain and returns a
short-lived signed URL), then POSTs the file's **raw bytes** via XHR with
real per-byte progress — binary, so a 50 MB video never bloats the rpc
payload. The stored ref row appears **live** in any `useSubscription` over that
table (normal reactivity). For an instant preview, pair with
`URL.createObjectURL(file)` and swap to `asset.url` on completion.
**Drag-drop + paste** come for free. The handle also returns `onDrop`, `onPaste`,
and a `dropzoneProps` you spread onto any element for a zero-boilerplate dropzone:
```tsx
const { dropzoneProps, onPaste, uploadMany } = useUpload('myApi')