Skip to content

Concurrent writers and recovery

A storage root is often shared: several processes on one host, or several hosts on one NFS mount. This guide covers what happens when two of them write the same OCFL object, and what to do when a writer dies part of the way through.

The library refuses a second writer rather than managing one. It never waits, queues or retries for you. Whether and when to try again is your choice, and the error code tells you which choice is safe.

Each OCFL object has one lock, a file in the storage root’s workspace, which must be on the same file system as the rest of the storage root. root.create, object.update and root.remove take it before they do anything else, and release it only when they end cleanly. Readers take no lock, so opening an object or reading its files never waits on a writer.

Use NFS 4.1 or later. Its sessions carry out each request exactly once, so a reply lost on the network doesn’t turn a link or rename that worked into an error. On NFS 3 a lost reply to the rename that commits an update can fail the update with RECOVERY_NEEDED although the version was committed. NFS 4 also sends several operations in one request, so a write takes fewer round trips to the server.

The tests don’t run on an NFS mount. They cover lost replies by making a link or rename take effect and then report a failure.

The library never removes a lock because of its age, and never removes one it didn’t take. A process that is killed, or a host that loses power, leaves its lock behind. The library can’t tell a dead writer from a slow one on shared storage, so it doesn’t try: a slow writer is never trampled, however long it takes.

UPDATE_IN_PROGRESS: another writer holds the lock

Section titled “UPDATE_IN_PROGRESS: another writer holds the lock”

A create, update or remove that finds the lock taken throws an OcflError with code UPDATE_IN_PROGRESS, and changes nothing. Its lockedAt is the time the lock was taken.

import { OcflError, openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
const object = await root.open('arcp://name,corpus/item/1');
try {
await object.update({ message: 'Add notes', user: { name: 'Alice' } }, async (draft) => {
await draft.write('notes.txt', 'Recorded in the field');
});
} catch (error) {
if (!(error instanceof OcflError && error.code === 'UPDATE_IN_PROGRESS')) {
throw error;
}
const since = error.lockedAt?.toISOString() ?? 'an unknown time';
console.warn(`${object.id} has had a writer since ${since}; try again later`);
}

Nothing was written, so you can wait and try again. If the lock stays, its writer may have died: see When a writer dies.

lockedAt helps you judge that, but the judgement is yours:

  • It is the writing host’s clock, so it compares with yours only as far as the two clocks agree.
  • It is absent when the lock couldn’t be read, or was released between the refusal and the read. The lock still counted as held.

OBJECT_OUT_OF_DATE: the object changed since you opened it

Section titled “OBJECT_OUT_OF_DATE: the object changed since you opened it”

An opened OCFL object is the object as read at one moment. It doesn’t change when another writer commits a later version or removes the object. If you update an object that is no longer the head, or no longer exists, the update throws OBJECT_OUT_OF_DATE and is discarded, so your change is never built on files you didn’t see. That includes an object you have updated yourself: make the next update on the object update returned, as Updating objects explains.

Open the object again and repeat the update. Any error other than RECOVERY_NEEDED means the update wasn’t committed, so repeating it never applies a change twice.

import { OcflError, openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
const id = 'arcp://name,corpus/item/1';
for (let attempt = 1; ; attempt++) {
const object = await root.open(id);
try {
await object.update({ message: 'Add notes', user: { name: 'Alice' } }, async (draft) => {
await draft.write('notes.txt', 'Recorded in the field');
});
break;
} catch (error) {
const outOfDate = error instanceof OcflError && error.code === 'OBJECT_OUT_OF_DATE';
if (!outOfDate || attempt === 3) {
throw error;
}
}
}

The retry limit keeps a busy object from looping forever. Pick one that suits how often the object is written.

RECOVERY_NEEDED: the update may or may not be committed

Section titled “RECOVERY_NEEDED: the update may or may not be committed”

An update is committed at one moment: the rename that replaces the object’s root inventory.json, its commit point. A failure before it discards everything and throws the original error. A failure after it, or a failure while discarding, throws RECOVERY_NEEDED with the failure as its cause. The version may or may not be committed, so don’t simply repeat the update.

After RECOVERY_NEEDED:

  • The object stays readable.
  • The lock is kept, so later creates, updates and removes of the object throw UPDATE_IN_PROGRESS until it is recovered.
  • The object you called update on is unchanged. Opening the object again shows what is on disk.

Recover the object’s unfinished write, from root.unfinishedWrite(id), then open the object again. Its head says whether the update was committed. Repeat the update only if the head hasn’t moved.

import { type Draft, OcflError, openStorageRoot, type VersionDetails } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
const id = 'arcp://name,corpus/item/1';
const details: VersionDetails = { message: 'Add notes', user: { name: 'Alice' } };
const change = async (draft: Draft) => {
await draft.write('notes.txt', 'Recorded in the field');
};
let object = await root.open(id);
const headBefore = object.head.number;
try {
object = await object.update(details, change);
} catch (error) {
if (!(error instanceof OcflError && error.code === 'RECOVERY_NEEDED')) {
throw error;
}
// Safe only because this process is the object's one writer
await (await root.unfinishedWrite(id))?.recover();
object = await root.open(id);
if (object.head.number === headBefore) {
object = await object.update(details, change);
}
}

The same goes for the other writers:

  • Create: after RECOVERY_NEEDED, recover, then open the object to see whether it was created.
  • Remove: after RECOVERY_NEEDED, the object is partly or wholly deleted, and may still open with files missing. Recovering it finishes the remove.

Every held lock is an unfinished write: a create, update or remove whose writer is still working, or died. root.unfinishedWrites() lists them all, and root.unfinishedWrite(id) finds the one for an id, or gives undefined if the object isn’t locked. Each has the object’s id, the lockedAt time and whether it is removing the object. Listing changes nothing.

write.recover() clears what the write left and releases the lock last:

  • an update that wasn’t committed is discarded;
  • an update that was committed is completed, by writing the root inventory’s sidecar;
  • a create that wasn’t committed is discarded;
  • a remove that had begun deleting is finished.

It never makes a version the head, and never removes a version directory other than the one the dead writer was adding, with one exception: the lock doesn’t record whether its writer was a create, so an object that has only a first version and has lost its root inventory is taken for a dead create, and its first version is removed. If the lock has been released since you got the write, it does nothing. If another writer has taken the lock since, it throws UPDATE_IN_PROGRESS and changes nothing. If it fails part of the way through, the lock is still there and you can recover the write again.

You know a writer is dead when, for example, it is your own process and it has stopped, or the host that ran it has been restarted. A lockedAt from long ago is a hint, not proof: a writer can stall for minutes on a slow mount and then carry on.

Don’t delete a lock by hand. Recovery uses what the lock records to decide what to clear, and a write whose lock was removed by hand is no longer an unfinished write, so it can’t be recovered. A version its dead writer left in the workspace makes the next create or update of the object throw RECOVERY_NEEDED and keep its lock, so that write can then be recovered; the next remove deletes it. A dead create’s object root has to be removed by hand.

A writer that dies leaves its lock, and every later create, update or remove of the object throws UPDATE_IN_PROGRESS. Once you know the writer is dead, recover its unfinished write and then try again.

A host that crashed may have been writing objects you can’t name. List the unfinished writes and recover the ones whose writers you know are dead. There is no way to recover every lock at once: other hosts sharing the storage root may still be writing, so the choice is made one write at a time. Run this from one process only.

import { openStorageRoot } from '@ocfl/ocfl-fs';
const root = await openStorageRoot('/srv/ocfl');
// When this host, the storage root's only writer, came back up
const restartedAt = new Date('2026-11-12T03:20:00Z');
for await (const write of root.unfinishedWrites()) {
console.log(`${write.id}: locked at ${write.lockedAt.toISOString()}${write.removing ? ', being removed' : ''}`);
if (write.lockedAt < restartedAt) {
await write.recover();
}
}

This finds every write, whatever the layout, including a create that died before it was committed and so has no inventory naming its id.

A create writes the object declaration before the root inventory. If its writer dies in between, the object root has a declaration, no inventory and a held lock. Until it is recovered:

  • root.open(id) throws OBJECT_NOT_FOUND;
  • root.create(id, …) throws UPDATE_IN_PROGRESS;
  • root.objects() leaves it out without an error.

So a dead create doesn’t show up when you list the storage root’s objects, but it is among its unfinished writes. Listing also leaves out an object that has lost its declaration: see what the library doesn’t check or do.

The lock only keeps apart writers that take it. Writers on ocfl-js 0.4, or on a beta from before the lock, don’t. Upgrade every process and host that writes to a storage root at the same time, and don’t run old and new writers side by side.

Another tool writing to the same object is caught only if it has committed a new head by the time an update checks: the update then throws OBJECT_OUT_OF_DATE.

See StorageRoot and OcflObject in the API reference for every error each method throws, and Errors for what each code means and what to do.