Repository navigation
Releases
v1.1.1
The first release on npm. @vol-a/core, @vol-a/lookups, @vol-a/server,
@vol-a/client, @vol-a/react and @vol-a/cli are published to npm from this version on
(pnpm add @vol-a/client); 1.0.0, 1.0.1 and 1.1.0 exist only as tags, images and GitHub
releases. Since 1.1.0: @jsudc/* 0.3, one command for the whole test suite, a footer that
says which release and build a page is, and the production sites https://vol-a.com and
https://examples.vol-a.com. Nothing changes on the wire, in the CLI or in configuration.
Added
pnpm test:full:test:covandtest:e2ein one command with one merged coverage
report (tools/test-full.mjs), the commandthilo.toml[testing]names for the board's
Testing engine (docs/CONTRIBUTING.md).- Production of the website:
https://vol-a.comisapps/website, built by
deploy/website/prod.shwith its nginx vhost
(docs/DEPLOYMENT.md). - The website says how fresh it is. The footer of every page, the docs' included, shows
the version, the date of its release tag, when the site was built (UTC) and the commit;
the Packages table has an On npm column with the date each package's newest version
was published there, and that version when it is not the repository's (not on npm yet
while a package has never been published). Read once per build
(apps/website/src/build-info.mjs); the registry never fails the build, andSITE_NPM=off
builds without asking it (apps/website/README.md). - Running without the image is documented:
node dist/server.jsandnode dist/worker.js
of a built checkout as two services, and what the image would otherwise set
(docs/DEPLOYMENT.md).
https://examples.vol-a.com, the production examples site, runs that way
(deploy/examples/prod.sh, two systemd user units); the website's "live examples" links
now open it.
Changed
@jsudc/*0.3 (@jsudc/core0.3.0,@jsudc/server0.3.0,@jsudc/react0.3.1, the
lookups androw_linkrelease) in@vol-a/server,@vol-a/client,@vol-a/react, the
examples site and the website. Nothing changes on the wire: thefilescollection's rows,
filters, cursors andGET /vola/udc/subscribeare as before.@jsudc/server0.3 checks
at startup that everylookupfield names a served collection; vola'skind,
encryptionandprocessing_statusare lookups intolookups.yaml, which name none, so
@vol-a/serverturns that check off and runs it itself without them (udc/links.ts):
any other lookup orrow_linkof the registry still stops the start when it does not
fit.@jsudc/server0.3 still has no transport forcapabilities.subscribe, so vola's
own stays (docs/REALTIME.md).@vol-a/react's@jsudc/coreand@jsudc/reactpeer ranges are^0.2.0 || ^0.3.0
(were^0.2.0): an application embedding it can stay on@jsudc/*0.2 or move to 0.3,
with@jsudc/reactand@jsudc/corefrom the same line. The tutorial program
(apps/tutorial/ticket-desk) stays on 0.2, because its chapters show its
package.json.
Docker: docker pull ghcr.io/digital-cube/jsvola:1.1.1
npm: pnpm add @vol-a/client@1.1.1 · @vol-a/react · @vol-a/server · @vol-a/cli · @vol-a/core · @vol-a/lookups
v1.1.0
SQLite as a database option. A small installation on one host can run vola on a single
SQLite file (VOLA_DATABASE_URL=file:<path>), with no database service and, if it does
without background jobs, no Redis. PostgreSQL stays the default and the full-featured option.
Every API route, answer and error code is the same on both. For the HTTP API, the CLI, the
image and their configuration, this release only adds things. Code that embeds
@vol-a/server and reaches into its database handle has two type changes, listed under
Breaking for code that embeds the server below. The version is still minor because no
@vol-a/* package had been published to npm before this release.
Added
- SQLite as a database option. Set
VOLA_DATABASE_URL=file:<path>(relative to the
working directory),file:///abs/path, or:memory:for tests, in place of
postgresql://…. The guide is
docs/SQLITE.md: which database fits, the quick start without Docker,
embedding the plugin, the worker, backups, the limits. The features by database are also
in the README. What SQLite gives:- Every feature of the API, with the same routes, answers and error codes: files, folders,
versions, shares, tus uploads, the four encryption modes, UDC lists andsubscribe,
statistics, transfer, and the CLI (vola migratecreates and migrates the file). - The driver is Node's built-in
node:sqlite(Node 24+), so there is no new dependency.
The database runs in WAL mode withforeign_keys = ON. There is one writer at a time:
every transaction isBEGIN IMMEDIATE, and the server's transactions take turns. Reads
outside a transaction use a second, read-only connection. - One server process per file. Without Redis everything runs inline: thumbnails render
on/thumb, and no OCR job is created. WithVOLA_REDIS_URLset, one worker process
on the same host opens the same file and runs thumbnail and OCR jobs as on PostgreSQL:- its writes are single statements, and tesseract runs with no transaction open;
- a process waiting for the other's write lock waits on a timer, up to 10 s, instead of
inside SQLite'sbusy_timeout, so it keeps serving; - the expired-upload sweep stays in the server, because the upload a tus
PATCHstreams
into is guarded in the server's memory (409 upload_locked, as on PostgreSQL); - only
:memory:refuses a worker:VOLA_WORKER_ENABLED=truewith it is a configuration
error.
- The OCR text search on SQLite has the same API as on PostgreSQL. The
ocrfilter with
words searches a contentless FTS5 index,drizzle-sqlite/0001_ocr_fts.sql(unicode61,
remove_diacritics 0). Triggers keep the index in step withvola_file_metadata, and the
migration indexes text already there.- Search rules: every word must occur, case-insensitively, with no stemming and no
ranking. Diacritics are kept (č≠c), and the first 500 000 characters are indexed,
as withocr_tsv. - One difference: any character that is not a letter or a digit separates words
(e-mailiseandmail). - The server quotes the words, so FTS5 syntax typed by a user is plain text. It refuses to
open a SQLite database built without FTS5 (Node's built-in one has it).
- Search rules: every word must occur, case-insensitively, with no stemming and no
- Its own migration set,
packages/server/drizzle-sqlite/, shipped in the package. The
server applies it at start, andvola migrateby hand, as with the PostgreSQL set.
pnpm db:generatewrites both.
- Every feature of the API, with the same routes, answers and error codes: files, folders,
Breaking for code that embeds the server
These are two exports of @vol-a/server. They do not affect the HTTP API, the CLI, the
image or the configuration.
DatabaseHandlecarriesdialectinstead ofpool(node-postgres'pg.Pool).Databaseis drizzle's query builder without the driver:PgDatabase<PgQueryResultHKT, …>
instead ofNodePgDatabase, so its type no longer has$client.
Code that reached for handle.pool or db.$client uses handle.db for queries and
handle.close() on shutdown.
Changed
VOLA_DATABASE_URL/VOLA_DATABASE_URL_TESTacceptfile:<path>and:memory:next to
postgres(ql)://.connect(url)picks the database from the URL scheme. Any other scheme
throws aConfigErrorthat names the scheme and never the rest of the URL.@vol-a/server's database layer goes through one dialect seam,db/dialect.ts, with
db/postgres.tsanddb/sqlite.tsbehind it. What is not portable goes through the seam:
the advisory lock on a content hash, unique-violation and lock-not-available errors,
count(*) filter, JSON fields,LIKE/ILIKE,FOR UPDATE NOWAIT,
ON CONFLICT … DO NOTHINGand the OCR text match (ocrMatch(words)).capabilitiessays
what a dialect has (rowLocks,ocrSearch). On PostgreSQL the SQL is the same as in 1.0.1.- The tables exported from
db/schema.tsare those of the database the process connected to
(db/schema-postgres.tsordb/schema-sqlite.ts, with the same row types), so a process
speaks one dialect. resolveJobsMode's input takesmemoryDatabase: an in-memory SQLite is alwayssync.- The server and CLI test suites run on both databases (Vitest projects
server/
server-sqlite,cli/cli-sqlite).VOLA_TEST_DIALECT=postgres|sqliteruns one
(docs/CONTRIBUTING.md).
Docker: docker pull ghcr.io/digital-cube/jsvola:1.1.0
npm: pnpm add @vol-a/client@1.1.0 · @vol-a/react · @vol-a/server · @vol-a/cli · @vol-a/core · @vol-a/lookups
v1.0.1
The packages are renamed from @vola/* to @vol-a/* — @vol-a/core, @vol-a/lookups,
@vol-a/server, @vol-a/client, @vol-a/react, @vol-a/cli — because the vola scope on npm
is taken; the npm organisation is vol-a, like the site vol-a.com. This is the first npm
publication (1.0.0 went out as the Docker image and the GitHub release only). Nothing else
changes: the CLI is still vola, the image is still ghcr.io/digital-cube/jsvola, the
variables VOLA_*, the /vola prefix, the vola_* tables and the X-Vola-* headers stay.
Changed
- Every package name, import,
--filterand the source export condition (@vol-a/source):
replace@vola/with@vol-a/in an application'spackage.jsonand imports. The entries
below 1.0.0 keep the names the packages had then. - The tutorial's tarballs are
vol-a-core-1.0.1.tgz,vol-a-client-1.0.1.tgzand
vol-a-react-1.0.1.tgz; the chapters show the program with the new names.
Docker: docker pull ghcr.io/digital-cube/jsvola:1.0.1
npm: pnpm add @vol-a/client@1.0.1 · @vol-a/react · @vol-a/server · @vol-a/cli · @vol-a/core · @vol-a/lookups
v1.0.0
The first release: the TypeScript port of vola-spp, complete per docs/PLAN.md
— content-addressable, multi-tenant file storage with folders, versions, slugs, resumable
uploads, thumbnails, OCR, share links, statistics, admin transfer, live lists, encryption at
rest in four modes, a fetch SDK, React components, an examples site and one Docker image. Built
in eight phases, one ticket each; the detailed entries below follow them, newest first.
| phase | what | ticket |
|---|---|---|
| 1.1 | monorepo scaffold (pnpm, Turbo, Biome, Vitest), compose, Dockerfile, CI, health, VOLA_* config |
TCKW73Q7EJ |
| 1.2 | tenants, API keys with scopes, auth, admin keys with X-Tenant-Slug, CLI, /keys |
TCKMP7M57K |
| 2.1 | CAS storage: streaming upload with dedup, download with Range/206 and HEAD, slugs, soft delete, purge |
TCK5HPYMY2 |
| 2.2 | virtual folders, path routes, move and rename, version chains, visibility, anonymous /public |
TCKM5DHJTH |
| 2.3 | resumable uploads: tus 1.0 at /uploads |
TCKNPKC9XY |
| 3.1 | @vola/lookups, the UDC files collection, /instance-types |
TCKUHMFRRQ |
| 3.2 | real-time: UDC subscribe over WebSocket |
TCKFQMCFDT |
| 4.1 | BullMQ worker, processing jobs, thumbnails (images and PDF) with the 202 rule |
TCKXQCJ2YY |
| 4.2 | OCR (tesseract + pdftoppm), vola_file_metadata, full-text filter |
TCKPK3YTKR |
| 5.1 | share links (token, argon2 password, expiry, max_downloads, revoke, folder shares) and statistics |
TCKKQHMDJT |
| 5.2 | admin transfer of instances between tenants, optional memento audit trail | TCK59T5P65 |
| 6.1 | encryption I: the JSV segmented format, a key per file, the tenant provider |
TCKK5UTHJX |
| 6.2 | encryption II: the keyring (PIN) provider, unlock tokens, brute force, recovery, reset, encrypted folders |
TCKFT692JH |
| 6.3 | encryption III: the caller provider, sealed resumable uploads, encrypted thumbnails and OCR, share grants, client blobs |
TCKQ7JWCRJ |
| 7.1 | @vola/client |
TCKX7RMHKF |
| 7.2 | @vola/react |
TCK9NUHWW6 |
| 8.1 | apps/examples and the compose demo profile |
TCKKR2PUDE |
| 8.2 | documentation, the release workflow, npm metadata | TCKT9JUU59 |
Added
-
A tutorial on vol-a.com: a ticket desk on vola and memento, from an empty folder. Seven steps,
in English and Serbian, written from the history ofapps/tutorial/ticket-desk; every command on
the page was run as written (apps/website/scripts/tutorial.mjs). Code blocks of the site now keep
their tabs, so a copied Makefile works. -
apps/website(@vola/website, private): the website and documentation, for vol-a.com.
Astro with Starlight under the docs and Pagefind search; a home page of its own, dark first, in
Archivo and JetBrains Mono, drawn from the product: a thumbnail going from 202 to 200, a byte
ruler over a recorded206, a contact sheet of real renditions, the JSV v1 segment diagram.
Every request and answer it shows is recorded (scripts/capture.mjs), every command was run,
every program compiles against the workspace (scripts/check-snippets.mjs, part of
typecheck). The Reference section and the changelog page are generated fromdocs/and
CHANGELOG.md, and a broken link fails the build. Not part of the Docker image. -
deploy/website/stage.shanddeploy/website/nginx/stage.vol-a.com.conf: build-and-swap of the
website athttps://stage.vol-a.com/;deploy/examples/nginx/examples.stage.vol-a.com.conf:
the examples stack's vhost, now in the repository and answering its own name only. -
Documentation and release (plan 8.2):
README.mdrewritten as the front page (what vola
is, the quick start againstdocker-compose.yamlwithcurl, the packages, the documents);
docs/API.md— every route with method, path, scope, body, answers and error codes, the
Range/HEAD/ETagrules, the202thumbnail rules, tus, shares and grants, keyrings, UDC,
the examples routes, and why there is no generated OpenAPI yet;docs/ARCHITECTURE.md—
packages, schema,stageUpload→finalizeUpload, the CAS layout, the worker and its five
jobs, the event bus andsubscribe, encryption as a layer, transfer;docs/CRYPTO.md
completed with a one-page summary (§ 0), the client-side rules and the departures from the
Notes model (§ 14) and an operations checklist (§ 15), readable without
notes-crypto-for-vola.md;docs/DEPLOYMENT.md— the image, the stack, everyVOLA_*
variable with its default, the key and pepper files (generate, back up apart, rotate, "without
them encrypted files are lost"), volumes, the worker, a reverse proxy, backups of the database
andVOLA_STORAGE_PATHtogether, upgrades;docs/CLI.md— everyvolacommand;
docs/MIGRATION-FROM-VOLA-SPP.md— old route → new route →@vola/clientmethod, the auth
differences, what stays (the202rule), no data migration, the checklist for the eight
consumers;docs/CONTRIBUTING.md..github/workflows/release.yml: on av*tag — versions
checked against the tag, lint / typecheck / build / tests, the link check and
pnpm pack --dry-run, the image to ghcr.io with provenance, a GitHub release from this file,
and@vola/core,@vola/lookups,@vola/server,@vola/client,@vola/react,@vola/cli
published to npm with provenance (NPM_TOKEN).tools/check-links.mjs(every relative link
and anchor of the Markdown documents; in CI),pnpm pack:dry, READMEs for@vola/core,
@vola/serverand@vola/cli,repository.directory/files/exports/license/
engineson every public package. -
The examples site (plan 8.1,
apps/examples,@vola/examples): a Vite + React 19 site on
@vola/reactand@jsudc/react, one page per capability over a demo instance — Browse
(VolaFileBrowser, live, the folder in the URL), Upload (multipart under 1 MiB, resumable
above it in 256 KiB chunks with progress, cancel and resume, a drop zone, the demo's
limits), Thumbnails (every size × crop with each tile's state, Regenerate for the
202 → 200sequence), Range & streaming (<video>/<audio>on/public/:id, a Range probe
that shows the206), Share (VolaShareDialog, the last link), Encrypted files (tenant
on seeded files;keyringbehindVolaPinGateover the visitor's private folder with the
unlock countdown), API (the routes andcurlwith the demo key),/udc/:collection; the
sidebar frommenu.yaml(themenucollection, a built-in copy without it), EN / SR,
Settings (base URL, own key, instance, the visitor id with "New identity"). The visitor's
key is read-only; ademoFetchsends every write to the server's write proxy. 48 tests. -
@vola/server: the demo routes (VOLA_EXAMPLES=true,packages/server/src/examples/):
GET /examples/confighands outVOLA_DEMO_API_KEY(read-only), the demo instance, the
limits and the features;ANY /examples/write/<route>replays a visitor's write
(X-User-Id: demo-…) underVOLA_DEMO_WRITE_KEYafter the policy — uploads (5 MiB, a
type list enforced after the upload: a wrong type is purged and415), the resumable
protocol (Locationrewritten), a visitor's own files and folders (seeded ones403),
shares (expiry capped at the TTL), the visitor's keyring — and a per-address rate limit
(429+Retry-After);POST /examples/regenerate/:fileIddrops a file's thumbnails
(StorageBackend.removeDerived); the purge removes a visitor's keyrings (crypto-shred),
files and folders afterVOLA_DEMO_TTL_HOURS(POST /examples/purgefor an admin). At
startup the server creates the demo tenant and stores both keys (by hash, with their
scopes), and refuses a visitor key that can write.VOLA_UI_DIRserves a built SPA at/
and/en/with anindex.htmlfallback (installUi);VOLA_TRUST_PROXY. -
@vola/cli:vola demo-keys(a key pair for.env) andvola demo-seed(uploads
apps/examples/assets— ten generated files,ASSETS.md— into the demo instance over HTTP
with@vola/client, an upsert per slug, media setis_global_public; the composeseeder). -
Compose / image: the image builds the site into
/app/uiand carries the demo pack;
docker-compose.yamlgains the examples variables,VOLA_SECRETS_DIR(the key and pepper
files at/run/secrets/vola) and theseederservice under thedemoprofile. -
E2E:
packages/e2e/test/examples.e2e.ts— the built site at/and every page,
/examples/config, the seeder twice, the visitor's key,202 → 200,206, the proxy, and
a server withoutVOLA_EXAMPLES; the suite's own server now runs with the examples on. -
@vola/react(plan 7.2): the React components an application embeds for the whole vola
surface, on@jsudc/react(peer, with@jsudc/coreand@tanstack/react-query; React 19).
<VolaProvider client locale="en|sr">— the client, i18n (VOLA_MESSAGES,enandsr,
overridable throughmessages), the UDC providers, the keyring store with its auto-lock, and
the in-memory cache of decryptedblob:URLs.<VolaFileBrowser instanceType instanceId folderPath? onOpen? columns? actions?>— breadcrumbs, subfolders (open, rename, delete, new
folder) and<UdcDataView collection="files">scoped to the instance and the folder through a
ScopedUdcClient(everylistANDed with the scope), kept current through/udc/subscribe
(useFilesLive: a cached row is patched in place, anything else refetches; reconnect with
backoff), drawn by the package'stablerenderer (VolaThumbin the thumbnail column, the
name as the open link, a row-actions menu: download, rename, move, delete, versions, share,
visibility — each a dialog), the whole surface a drop zone.useVolaUpload()+
<VolaUploadButton>/<VolaUploadList>: one multipartPOSTunder
VOLA_RESUMABLE_THRESHOLD(8 MiB), the resumable protocol above it with progress, cancel and
...