Object-level versioning is a powerful content protection option that tracks, secures, and provides access to historical versions of objects, even after they are deleted. With versioning, applications can read, list, revert, and purge prior versions as well as restore objects deleted by mistake.

Versioning preserves a set of historical variants of an object, the original plus subsequent updates to it, up to and including the latest version:

Open

These are key capabilities of Swarm versioning:

• Unlimited Versions: The number of supported versions for a given object is unbounded, and all versions have a unique version ID. List all versions, access, restore, and permanently delete specific versions via the version ID.

• Flexible Policy: The cluster administrator changes the cluster policy settings to allow versioning; the domain administrator can then allow and even require versioning in that domain. A bucket owner can enable/disable versioning for a specific bucket if allowed by the cluster and domain.

• Lossless Concurrent Updates: Swarm captures simultaneous PUT updates and resolves the order in the version chain. Swarm preserves all versions, even those overlapping in time, with the latest update as the current version.

• Accurate Disk Reporting: Each object revision in a domain/bucket with versioning-enabled preserves and reports the full size on disk. Swarm includes all object revisions in the 'du' responses if requested. The size for deleted and historical versions counts towards bucket and domain totals.

• Support for Search and Replication: Swarm Versioning works with both https://perifery.atlassian.net/wiki/spaces/public/pages/2443814403/Search+Feeds?search_id=111c7637-58c7-450f-9a7b-ab923f12bf55 and https://perifery.atlassian.net/wiki/spaces/public/pages/2443814668/Replication+Feeds?search_id=908a7456-11cb-4a6b-ad5a-f853cc5b285c, provided all clusters are running the same version of Swarm.

Why use Versioning?

Versioning meets two key needs:

• Require extremely durable data retention and archiving.

• Require the ability to recover when data is erroneously overwritten or deleted.

With versioning enabled, prior versions of a stored object, can be retrieved and restored allowing recovery from data loss, whether caused by user error or application failure:

• Deleting an Object: Swarm inserts a delete marker instead of removing it permanently, which becomes the current object version. Previous versions can be restored.

• Overwriting an Object: Swarm performs the update by creating a new version, allowing restoring previous versions by rolling back a bad update.

By default, versioning is disabled across the cluster. To avoid excessive storage usage, enable versioning in a targeted way, where change control is required.

What is Versioned?

Choosing to use versioning enables the ability to preserve, retrieve, and restore every update of every object stored in that context (domain or bucket). With Versioning, Swarm archives another copy of an existing object when an update or delete is processed. GET requests retrieve the most recently written version, but retrieval of older versions of an object is performed by specifying a version in the request.

Administrators can selectively enable versioning at the following levels once the cluster is configured to allow versioning:

• The domain level (for alias objects)

• The bucket level (for named objects)

Open

When a DELETE operation is issued against a versioned object, Swarm creates a delete marker so subsequent unversioned requests no longer retrieve the object. Swarm stores all versions of an object so they can be retrieved and restored.

These types of Swarm objects cannot be versioned:

• Domains

• Buckets

• Unnamed objects (which are immutable)

• Alias objects not tenanted in a domain

Objects are versioned while domains and buckets are not (contexts). A bucket is lost if accidentally deleted. Swarm pauses the recursive delete of the bucket's contents for the duration of the grace period (health.recursiveDeleteDelay). There is time to recreate the bucket with the same headers to avoid data loss (See https://perifery.atlassian.net/wiki/spaces/public/pages/2443811433). The content starts to disappear as Swarm's Health Processor begins cleaning up all versions of the obsolete content, to reclaim space, if the bucket is not restored and the grace period expires.