Adding Versions

Any write operation (POST, PUT, COPY, APPEND) in a versioning-enabled context creates a new version, and it changes the existing version to be the prior one. (Prior versions are not modified. All write operations create new versions.) 

• POST stores a brand new object as the current version. (PUT can be used if you have scsp.allowPutCreate enabled or add the putcreate query argument.)

• PUT adds a new version of the object, replacing the current version (which remains accessible by ETag); use PUT to update an existing alias. You cannot use PUT with the version query argument.

• COPY ?version={etag} creates a new version duplicating the content of a versioned object with the new headers specified.

• APPEND ?version={etag} creates a new version duplicating the headers of a versioned object with the new content specified (use 0-length to duplicate the existing content).

Retrieving Versions

There are different ways to retrieve current objects versus specific object versions. Add the version query argument to retrieve a specific version:

• GET retrieves the current version of an object. 

• GET ?version={etag} retrieves a specific version of an object, identified by its ETag header value. 

• HEAD retrieves the metadata of the current version of an object (and not the content). 

• HEAD ?version={etag} retrieves the metadata of a specific version of an object, identified by its ETag. 

Specify the object's ETag to retrieve the content or metadata of a specific version, which retrieves the specified version of the object. This can be the current version or any prior version.

An HTTP 404 Not Found response including the ETag for the delete marker (not the prior version) is received if a GET or HEAD is issued against the delete marker:

Open

Listing Versions

With Elasticsearch indexing your cluster, use it to access listings of your object versions. (Elasticsearch is not required to use versioning.)

Versioning headers – Swarm returns these additional headers with historical (non-current) versioned objects:

• uuidNextVersion – Points to the primary UUID of the object that is the newer version. This field transfers during replication within the cluster but not to remote clusters (each cluster resolves its own chains).

• tmNextVersion – Holds the birth date of the newer (uuidNextVersion) object (they update as a pair). This field transfers during replication within the cluster but not to remote clusters.

• tmDeleted – Holds the death date of this particular version. This field does transfer to remote clusters so the needed feed processing and clean up occurs.

Add the versions query argument to the GET Bucket request to list all versions of all objects in a bucket.

Use prefix query argument along with versions query argument to the GET Bucket request to list all versions of one object, which limits the set of versions returned to those related to the object.

Deleting Versions

The behavior is the same when versioning is enabled or suspended:

• Deleting without specifying a version: Swarm operates on the current version and creates a delete marker.

• Deleting with a version specified: Swarm permanently pushes the version out of existence, even if it is the current version. 

A DELETE does not permanently delete an object when versioning is enabled. Swarm inserts a delete marker instead, and the marker becomes the current version of the object with a new ID.

The response to a DELETE operation includes the ETag of the version being deleted, not that of the delete marker:

Open

Use DELETE Object and specify the ETag to permanently delete versioned objects:

Handling Delete Markers

A delete marker is a placeholder (marker) for a versioned object named in a DELETE request. Because the object was in a versioning-enabled bucket, the object was not deleted. The delete marker causes Swarm to operate as if it had been deleted. A delete marker has a name and version ETag like any other object, but it differs from other objects in several ways:

• It has no data.

• Its only operation is DELETE, which only the owner can request.

• It has nominal size.

Swarm can create a delete marker, and it does so when a DELETE Object request is sent on a versioning-enabled/suspended object . The object named in the DELETE request is not actually deleted. Instead, the delete marker becomes the current version of the object. (The object's name becomes the name of the delete marker.) 

The version ETag in a DELETE Object request must be included to permanently delete a delete marker. Owners can permanently delete these markers while the context is versioning-enabled/suspended. (The health processor cleans up the markers along with the prior versions if the context returns to versioning-disabled.)

Lifepoints for Versions

Object versions can be deleted on demand, but lifepoints can be defined for objects with a well-defined lifecycle to have Swarm permanently remove prior object versions as they expire. The Health Processor cleans up (erases) versions with expired lifepoints for both versioning-enabled and versioning-suspended states, deleting particular object versions. The Heath Processor repairs the gap in the version sequence caused by the deletion.

The Health Processor creates a delete marker that becomes the current version when the lifepoint expires on the current version of the object: it does not resurrect a previous version. 

The Health Processor acts on versioned objects in these ways:

• Evaluates lifepoints of current versions, performing EC-related conversions or lifepoint deletions.

• Keeps the desired number of replicas of versioned objects.

• Maintains the current version of an object and the chain of version linkages.

• Deletes prior versions of objects no longer accessible.

Renaming Versioned Objects

Renaming a versioned object is performed by ending the old one and starting a new one. There are two requests and two objects:

1. a DELETE on the old name, which terminates the version chain with a delete marker

2. a WRITE of a new object, with the new name

Note: the name change can be reversed by deleting the new object, reading the last good version, and appending the version.

Restoring Versions

A key benefit of versioning is the ability to restore previous versions of an object. There are several ways to restore content by referencing specific versions, depending on your situation: