Skip to content

/concepts/migrating-from-vola-spp/

Migrating from vola-spp

vola-spp is the earlier Python service that this one replaces. If your application has never called it, you can skip this page.

This version is a new API with no wire compatibility, and it starts empty with no data migration. The model is the same, so most of the work is changing paths and the shapes of a few requests.

A file still belongs to a tenant and an instance, and still has a slug, a folder path, a version chain, is_public and is_global_public, thumbnails that answer 202 while the worker renders, share links, stats and UDC list, describe and read.

These are different:

  • Paths lose the /api/v1 prefix and the /id/ segments: /vola/files/tickets/<uuid>/<fileId>.
  • Visibility and move are one PATCH with a JSON body.
  • Shares are created with a JSON body and followed at /vola/s/<token>.
  • Errors are {error: {code, message}} with stable snake_case codes.
  • The key goes in Authorization: Bearer, and X-Api-Key still works.

There are also new things: resumable uploads, live lists over WebSocket, OCR, encryption, keyrings and an audit trail.

vola-spp Now
Header X-API-Key Authorization: Bearer. X-Api-Key is accepted too, and header names are case-insensitive, so an existing X-API-Key keeps working. WebSockets use the subprotocol bearer.<key>
Key format vola_live_…, vola_test_…, vola_admin_… The same prefixes, with only the SHA-256 stored
The keys themselves New keys. The key table starts empty, so issue them with vola create-key
Scopes A JSON list on the key files:read, files:write, folders:read, folders:write, shares:write, keys:write, keyrings:write, encryption:caller, admin
Admin key X-Tenant-Slug selects the tenant The same
Acting user X-User-Id The same header, now also the owner of a keyring
Another tenant’s file 404 or 403 Always 404
Errors {detail: …} {error: {code, message, …}}

:type/:id is instance_type/instance_id. The full table has every route and its @vol-a/client method.

vola-spp Now
POST /api/v1/files/{type}/id/{id} POST /vola/files/:type/:id
PUT /api/v1/files/{type}/id/{id}/slug/{slug} PUT /vola/files/:type/:id/slug/:slug
GET /api/v1/files/{type}/id/{id}/id/{file_id} GET /vola/files/:type/:id/:fileId
GET …/id/{file_id}/info GET /vola/files/:type/:id/:fileId/info
GET …/id/{file_id}/thumb/{size}?crop= GET /vola/files/:type/:id/:fileId/thumb/:size?crop=
PATCH …/id/{file_id}/visibility PATCH /vola/files/:type/:id/:fileId with {is_public, is_global_public}
PATCH …/id/{file_id}/move PATCH /vola/files/:type/:id/:fileId with {folder_path}
DELETE …/id/{file_id}/purge DELETE /vola/files/:type/:id/:fileId/purge
POST /api/v1/folders/{type}/id/{id}/path/{path} POST /vola/folders/:type/:id/*path
POST /api/v1/share POST /vola/shares with a JSON body
DELETE /api/v1/share/id/{id} DELETE /vola/shares/:id
GET /share/token/{t} GET /vola/s/:token
GET /public/file/{id} GET /vola/public/:fileId
GET /api/v1/stats/tenant GET /vola/stats/tenant
GET /api/v1/instance-types GET /vola/instance-types
POST /api/v1/admin/transfer POST /vola/admin/transfer
POST /udc/list POST /vola/udc/list
GET /api/lookups GET /vola/lookups
  • The 202 thumbnail rule. A consumer that got this right against vola-spp needs no change. See Uploads and processing.
  • The sizes 64, 128, 256 and 512, the crops cover, fit and attention, and WebP.
  • Range, 206, 416, HEAD, ETag and 304 on downloads, and inline for images, video, audio and PDF.
  • instance_id is a UUID, instance_type is a lowercase identifier, and a slug names one live file.
  • The UDC files collection and its rule of a top-level instance_type filter or an empty list, with download_url and thumb_url on every row.
  • is_public and is_global_public.
  • Content-addressed storage, dedup, soft delete, and purge when nothing references the blob.
  • X-Tenant-Slug for admin keys and X-User-Id for attribution.
  • /share/token/{t}/download becomes ?download=1, and the password goes in X-Share-Password.
  • X-File-Hash on downloads is gone. The ETag carries the hash of a plain file.
  • Share passwords are argon2id, not bcrypt.
  • An upload answers the file info directly (201), and lists answer {files, next_cursor}.
  • POST /admin/transfer no longer creates the destination tenant, so it must exist. dry_run is new.
  • EXIF and AI_SUMMARY jobs, which existed only in vola-spp’s vocabulary, do not exist.

This version starts with a new database, a new storage directory and new keys. There is no script that reads vola-spp’s tables or its aa/bb/cc/<sha>.<ext> tree. The old tree keeps the extension in the blob name, and vola-spp’s rows carry no encryption, OCR or version metadata the new schema wants.

vola-spp keeps running for the consumers that have not moved. A consumer moves by pointing its configuration at the new server. If it needs its old files there, it uploads them again through the new API, from its own source of truth.

Share tokens are not carried over. Links sent out under vola-spp stay valid against vola-spp for as long as it runs.

  1. Keys. Create the tenants and new keys on the new server (vola create-tenant, vola create-key, create-admin-key) with the scopes the project needs. A backend that acts for several tenants keeps using an admin key and X-Tenant-Slug. See the CLI reference.
  2. Base URL and prefix. https://files.example.com/vola replaces the old host plus /api/v1. Replace a vola client module with @vol-a/client in TypeScript, or rewrite its route table in another language. The /udc/* calls move under the prefix.
  3. Uploads. Drop /id/ from the path. The field names (file, folder_path, folder_id, parent_id) are unchanged and metadata is new. The answer is the file info itself. Above a few MiB from a browser, switch to vola.uploads.resumable() or VolaUploadButton.
  4. Downloads and info. Drop /id/, and read the hash from ETag instead of X-File-Hash.
  5. Thumbnails. The path changes. Keep the 202 handling, or adopt files.thumb() or VolaThumb. Check that the project’s cache layer does not key a 202 body by hash.
  6. Visibility and move. Two routes become one PATCH with {is_public}, {is_global_public} or {folder_path}.
  7. Shares. POST /vola/shares with a JSON body. The link is url from the answer, so set VOLA_PUBLIC_URL on the server. /share/token/… URLs in templates become /vola/s/<token>. For an encrypted file the url has a #fragment the recipient’s client must send as X-Share-Secret, which VolaClient.openShare does.
  8. UDC. POST /vola/udc/list, describe and read take the same filter language. Rows gain kind, encryption, processing_status and ocr. A UI moves to @jsudc/react and @vol-a/react’s VolaFileBrowser.
  9. Stats, instance types, lookups. Only the paths change.
  10. Errors. Map {error: {code}} instead of {detail}. Codes to branch on include 423 vola_locked, 409 vola_integrity and 503 encryption_unavailable if the project adopts encryption. They are all in the API reference.
  11. Transfer. POST /vola/admin/transfer takes the same body. Create the destination tenant first, and try dry_run: true.
  12. Smoke test. Upload, read info, download with Range, fetch a thumbnail until 200, run a UDC list, open a share link without a key, delete and purge. Run it with Docker shows the commands.
  13. Decommission the vola-spp key for that project once the switch is done.
  • encryption: "tenant" on uploads, which is one header and no other client change.
  • Keyrings for per-user private files, with VolaPinGate.
  • OCR text through …/info?ocr=full and the UDC ocr filter.
  • The audit trail into memento.
  • Live lists instead of polling.

v1.1.1released built 519e3dc