Skip to content

Releases

v1.1.1

Choose a tag to compare

@github-actions github-actions released this 16 Nov 22:45

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:cov and test:e2e in one command with one merged coverage
    report (tools/test-full.mjs), the command thilo.toml [testing] names for the board's
    Testing engine (docs/CONTRIBUTING.md).
  • Production of the website: https://vol-a.com is apps/website, built by
    deploy/website/prod.sh with 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, and SITE_NPM=off
    builds without asking it (apps/website/README.md).
  • Running without the image is documented: node dist/server.js and node 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/core 0.3.0, @jsudc/server 0.3.0, @jsudc/react 0.3.1, the
    lookups and row_link release) in @vol-a/server, @vol-a/client, @vol-a/react, the
    examples site and the website. Nothing changes on the wire: the files collection's rows,
    filters, cursors and GET /vola/udc/subscribe are as before. @jsudc/server 0.3 checks
    at startup that every lookup field names a served collection; vola's kind,
    encryption and processing_status are lookups into lookups.yaml, which name none, so
    @vol-a/server turns that check off and runs it itself without them (udc/links.ts):
    any other lookup or row_link of the registry still stops the start when it does not
    fit. @jsudc/server 0.3 still has no transport for capabilities.subscribe, so vola's
    own stays (docs/REALTIME.md).
  • @vol-a/react's @jsudc/core and @jsudc/react peer 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/react and @jsudc/core from 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

Choose a tag to compare

@github-actions github-actions released this 15 Nov 16:58

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 and subscribe,
      statistics, transfer, and the CLI (vola migrate creates 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 with foreign_keys = ON. There is one writer at a time:
      every transaction is BEGIN 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. With VOLA_REDIS_URL set, 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's busy_timeout, so it keeps serving;
      • the expired-upload sweep stays in the server, because the upload a tus PATCH streams
        into is guarded in the server's memory (409 upload_locked, as on PostgreSQL);
      • only :memory: refuses a worker: VOLA_WORKER_ENABLED=true with it is a configuration
        error.
    • The OCR text search on SQLite has the same API as on PostgreSQL. The ocr filter with
      words searches a contentless FTS5 index, drizzle-sqlite/0001_ocr_fts.sql (unicode61,
      remove_diacritics 0). Triggers keep the index in step with vola_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 with ocr_tsv.
      • One difference: any character that is not a letter or a digit separates words
        (e-mail is e and mail).
      • 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).
    • Its own migration set, packages/server/drizzle-sqlite/, shipped in the package. The
      server applies it at start, and vola migrate by hand, as with the PostgreSQL set.
      pnpm db:generate writes both.

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.

  • DatabaseHandle carries dialect instead of pool (node-postgres' pg.Pool).
  • Database is drizzle's query builder without the driver: PgDatabase<PgQueryResultHKT, …>
    instead of NodePgDatabase, 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_TEST accept file:<path> and :memory: next to
    postgres(ql)://. connect(url) picks the database from the URL scheme. Any other scheme
    throws a ConfigError that 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.ts and db/sqlite.ts behind 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 NOTHING and the OCR text match (ocrMatch(words)). capabilities says
    what a dialect has (rowLocks, ocrSearch). On PostgreSQL the SQL is the same as in 1.0.1.
  • The tables exported from db/schema.ts are those of the database the process connected to
    (db/schema-postgres.ts or db/schema-sqlite.ts, with the same row types), so a process
    speaks one dialect.
  • resolveJobsMode's input takes memoryDatabase: an in-memory SQLite is always sync.
  • The server and CLI test suites run on both databases (Vitest projects server /
    server-sqlite, cli / cli-sqlite). VOLA_TEST_DIALECT=postgres|sqlite runs 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

Choose a tag to compare

@github-actions github-actions released this 04 Nov 15:34

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, --filter and the source export condition (@vol-a/source):
    replace @vola/ with @vol-a/ in an application's package.json and 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.tgz and
    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

Choose a tag to compare

@github-actions github-actions released this 04 Nov 12:35

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 of apps/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 recorded 206, 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 from docs/ and
    CHANGELOG.md, and a broken link fails the build. Not part of the Docker image.

  • deploy/website/stage.sh and deploy/website/nginx/stage.vol-a.com.conf: build-and-swap of the
    website at https://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.md rewritten as the front page (what vola
    is, the quick start against docker-compose.yaml with curl, the packages, the documents);
    docs/API.md — every route with method, path, scope, body, answers and error codes, the
    Range/HEAD/ETag rules, the 202 thumbnail 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 and subscribe, 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, every VOLA_*
    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
    and VOLA_STORAGE_PATH together, upgrades; docs/CLI.md — every vola command;
    docs/MIGRATION-FROM-VOLA-SPP.md — old route → new route → @vola/client method, the auth
    differences, what stays (the 202 rule), no data migration, the checklist for the eight
    consumers; docs/CONTRIBUTING.md. .github/workflows/release.yml: on a v* 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/server and @vola/cli, repository.directory / files / exports / license /
    engines on every public package.

  • The examples site (plan 8.1, apps/examples, @vola/examples): a Vite + React 19 site on
    @vola/react and @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 → 200 sequence), Range & streaming (<video>/<audio> on /public/:id, a Range probe
    that shows the 206), Share (VolaShareDialog, the last link), Encrypted files (tenant
    on seeded files; keyring behind VolaPinGate over the visitor's private folder with the
    unlock countdown), API (the routes and curl with the demo key), /udc/:collection; the
    sidebar from menu.yaml (the menu collection, 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; a demoFetch sends every write to the server's write proxy. 48 tests.

  • @vola/server: the demo routes (VOLA_EXAMPLES=true, packages/server/src/examples/):
    GET /examples/config hands out VOLA_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-…) under VOLA_DEMO_WRITE_KEY after the policy — uploads (5 MiB, a
    type list enforced after the upload: a wrong type is purged and 415), the resumable
    protocol (Location rewritten), a visitor's own files and folders (seeded ones 403),
    shares (expiry capped at the TTL), the visitor's keyring — and a per-address rate limit
    (429 + Retry-After); POST /examples/regenerate/:fileId drops a file's thumbnails
    (StorageBackend.removeDerived); the purge removes a visitor's keyrings (crypto-shred),
    files and folders after VOLA_DEMO_TTL_HOURS (POST /examples/purge for 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_DIR serves a built SPA at /
    and /en/ with an index.html fallback (installUi); VOLA_TRUST_PROXY.

  • @vola/cli: vola demo-keys (a key pair for .env) and vola 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 set is_global_public; the compose seeder).

  • Compose / image: the image builds the site into /app/ui and carries the demo pack;
    docker-compose.yaml gains the examples variables, VOLA_SECRETS_DIR (the key and pepper
    files at /run/secrets/vola) and the seeder service under the demo profile.

  • 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 without VOLA_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/core and @tanstack/react-query; React 19).
    <VolaProvider client locale="en|sr"> — the client, i18n (VOLA_MESSAGES, en and sr,
    overridable through messages), the UDC providers, the keyring store with its auto-lock, and
    the in-memory cache of decrypted blob: 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 (every list ANDed 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's table renderer (VolaThumb in 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 multipart POST under
    VOLA_RESUMABLE_THRESHOLD (8 MiB), the resumable protocol above it with progress, cancel and
    ...

Read more