Understanding Unnamed Objects

Owned by Rumena Zlatkova (Deactivated)
Last updated: Dec 19, 2023 by Bala Harish A(AC)
4 min read

 

Untenanted Objects

Earlier implementations of Swarm may have used untenanted unnamed objects, which are objects not tenanted in any domain.

  • Untenanted objects are reached using the query argument "domain="

  • Untenanted objects cannot be converted into tenanted objects and cannot be accessed using the Content UI.

Universally Unique Identifiers

Swarm assigns an unnamed object a unique identifier upon creation that is different from every other identifier assigned to every other unnamed object ever stored, past and future. This identifier is known as the object's Universally Unique Identifier (UUID).

Tip

Think of a UUID like a coat check ticket. When checking a coat at a restaurant, a coat check ticket identifies the coat owner. To retrieve the coat when ready to leave, present the ticket, not a description of the coat. No ticket, no coat.

A Swarm UUID is a sequence of 128 bits. In text-based languages and protocols such as Swarm's Simple Content Storage Protocol, a UUID is represented as a sequence of 32 hexadecimal digits:

http://companyname.example.com/12BFEA648C2697A56FD5618CAE15D5CA 

A UUID has no internal structure and cannot be parsed in any way to yield information about where or when the associated object was stored. An object's UUID is not derived from its content.

UUIDs and Replicas

Swarm produces replicas of an object to facilitate fault-tolerance, integrity, or speed of access. Every replica of a given object has exactly the same UUID as the original object. There is no external way to distinguish an original from a replica. Consider each replica of an object completely identical to every other replica of that object in the cluster.

Immutable Objects

By default, an unnamed object changes only by deleting it (if permitted by the object's lifepoint policy) once the object is stored in Swarm. There is no way to open an immutable object for updates or appends to the content or metadata. It is possible to decorate an immutable object with metadata that is stored separately in an annotation. (See https://perifery.atlassian.net/wiki/spaces/public/pages/2443822101).

To store an object in the cluster, an application must provide a size (in bytes) for the object. Swarm then allocates exactly enough space to store the given number of bytes. After that, every object replica has precisely the same byte size. There is no possibility a replica is updated or changed in some way while others are not changed.

If an application needs to update an immutable object with new content, the application is responsible for:

  • Storing a new Swarm object containing the updated data (or delete it if necessary)

  • Modifying any references to the old UUID to point to the new UUID

  • Maintaining association between the old object and the new revision

Consider using alias objects if those associations are important for a situation.

Unnamed Mutable (Alias) Objects

Alias objects are a special type of unnamed object in Swarm because the content can be replaced and the UUID remains constant (or alias). An alias object is created in much the same way as a regular object but uses an ?alias query argument on the WRITE request. Unlike an immutable object, where the contents do not change, the contents of an alias object can be replaced using an SCSP COPY, APPEND, or UPDATE request. Swarm always returns the most recent data associated with the alias object's UUID when reading an alias object.

Alias objects serve a very specific purpose for applications that store fixed content data. Many such applications must associate a symbolic name of some kind (e.g. a URI or a file pathname) to an object UUID returned from Swarm.

Identifying an alias object - Identify an alias object by examining the metadata:

  • An alias object's UUID is different from the ETag value.

  • An alias object may also have a castor-system-alias metadata entry as well

Update Frequency

Named and alias objects can be updated at a maximum frequency of once per second. Updating more frequently can cause unpredictable results with the stored object version. If an application updates objects faster than once per second, include the ?replicate query argument to guarantee more than one node can return the latest version in a subsequent read.

Accessing Unnamed Objects

Access unnamed objects using the UUID, placing it at the end of the URI as a string of 32 case-insensitive hexadecimal digits:

http://companyname.example.com/12BFEA648C2697A56FD5618CAE15D5CA

This URI specifies three things:

  • Protocol: http

  • Cluster: companyname.example.com

  • UUID: 12BFEA648C2697A56FD5618CAE15D5CA

Creating Unnamed Objects

The UUID is not assigned when storing an object for the first time, so an https://perifery.atlassian.net/wiki/spaces/public/pages/2443821645 request includes the first two components of the URI. Swarm generates and returns a new UUID to the storing application after the data is transferred and stored.

See https://caringo.atlassian.net/wiki/spaces/public/pages/2443821739/Normal+Responses+to+WRITE?search_id=83b5526e-5847-4ac8-8224-607395a8a856 for how the UUID is returned.

Every request must include one of the following:

  • a HOST header equivalent to the cluster name

  • the host IP address

  • a domain=clusterName query argument

© DataCore Software Corporation. · https://www.datacore.com · All rights reserved.