Skip to content

build!: move to @ocfl/ocfl-fs 1.0 beta and arocapi 5.0.0-beta.10 - #64

Merged
johnf merged 6 commits into
mainfrom
spec/53-ocfl-fs-1-0-beta
Nov 16, 2026
Merged

johnf merged 6 commits into
mainfrom
spec/53-ocfl-fs-1-0-beta

Conversation

@johnf

@johnf johnf commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator

Moves ldacapi to @ocfl/ocfl-fs 1.0.0-beta.59 and arocapi 5.0.0-beta.10, whose OcflStorage now serves files through 1.0. This is the trial migration that checks the 1.0 API before it freezes (Language-Research-Technology/ocfl-js#309 and #310).

Closes #53.

What changes for users and operators

  • OCFL_SCRATCH is gone. 1.0 assembles versions in extensions/ocfl-js-workspace inside the repository. The README, .env.example and deploy/ no longer mention it.
  • File rows no longer carry a CRC32. Nothing read it: arocapi strips meta from responses, ldacapi has no file transformer, and Oni never uses it. 1.0 can't read stored fixity values, so keeping it would mean reading every byte of every file on each index.
  • Imported versions now record a message and a user: Imported from <source dir>, by ldacapi crates:import with ldacapi's URL as its address. 1.0 requires both.
  • Last-Modified changes meaning. It is now the commit time of the version in which the file took its current content, read from the inventory, not the stored file's mtime. It no longer changes when storage is copied or restored.
  • Production storage must support hard links (NFS does), with no mount point inside the repository, and the importer needs write access to extensions/ocfl-js-workspace. The API itself still only reads: 1.0 opens, lists and reads a fully read-only repository.

Code

  • src/ocfl-repository.ts opens or creates the repository. It doesn't load arocapi, so pnpm ocfl:init and pnpm crates:import start without it.
  • scripts/crates-import.ts creates each crate and, on OBJECT_EXISTS, opens and updates it. It still merges: files missing from the source stay. A crate that is locked or needs recovery is logged with its lockedAt and skipped, and the script exits non-zero. It never recovers a crate itself, because only a person can tell that its writer is dead.
  • Listing logs a damaged crate's object root and id, and carries on.
  • CrateObject.root and RepositoryObject.path are gone: 1.0 gives out no disk paths, and they were used only in logs that already had the crate id.
  • @ocfl/ocfl and the hand-written src/ocfl-modules.d.ts are gone; 1.0 ships its own types.

Before deploying

Stop every 0.4 writer of the repository first; 0.4 doesn't take 1.0's lock. Afterwards, delete the old scratch directory. Repositories written by 0.4 need no conversion: the dev repository opens, lists and takes updates as it is.

Measured

Per file request through OcflStorage, on local NVMe with a warm cache: 0.2 ms for a small crate, 21 ms for a crate of 10,000 files. arocapi opens the crate on every request, so the cost grows with the size of the inventory. It is not yet measured on NFS or with LDaCA's largest crates.

Testing

pnpm lint is clean and pnpm test passes (229 tests). New tests cover importing a crate again (no version when nothing changed, a merged version when something did) and a damaged crate being left out of indexing and the crate list.

Opens the repository with openStorageRoot/createStorageRoot, imports through
create then update, and reads files from the head. OCFL_SCRATCH is gone: the
workspace is inside the repository. File rows no longer carry a CRC32, which
nothing read and 1.0 doesn't record. Crates and repository listings no longer
carry a disk path.

The storage root is opened in its own module so the scripts don't load
arocapi, whose OCFL backend still needs 0.4.
…eta.59

arocapi's OcflStorage now serves files through @ocfl/ocfl-fs 1.0, so ldacapi
installs only 1.0. Listing reads beta.59's entries, and logs a damaged
crate's object root and id.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

OCFL: drop local workarounds once ocfl-js ships the fixes

1 participant