File link

A file link is a pointer to another file.

Link format

It is an ASCII string in form LINKTYPE ARGS:

  • LINKTYPE is a valid link type, like package.

  • ARGS is zero or more link type specific arguments. Its size is limited to 65536 bytes.

Link types

A file's link type defines how Boomla treats the link during file operations.

Available link types and their main properties:

Link type Static / Dynamic Transparent Filesystem scope Mounts volume
package static yes yes yes, read-only
scope static yes yes yes, read-write
volume static yes no yes, read/write
path dynamic no no no

Link type: package

Example: package 012082bed9e173a334c59f43b3e9695579affedb5e

A package link mounts another filesystem into a file. The mounted filesystem is immutable, frozen at import time.

The hash above references the rootHash of the mounted filesystem. Note that it does not include the version history of the mounted filesystem, which is important as websites can grow quite large, this helps keeping them small.

When updating the package link, you can use one of 3 hash values:

  • the same as currently stored in the file link,

  • the current active rootHash of the package website, or

  • none (leave it out).

When you use the same file link value, you set the link to whatever it was already set to. In this case you are not changing it after all, that's a valid operation.

When the hash is not specified, you are instructing Boomla to fetch the latest rootHash of the remote package website and fill it in for you.

Using the current active rootHash means you set the package rootHash, the same that the system would also fetch for you. In fact, it will fetch it, this can simply be used as a safeguard to make sure you don’t mount an unexpected package state by accident.

A package link with an unspecified rootHash would look like this:

Note that when mounting a filesystem, you end up having a linking file that is shadowing the linked file - the root file of the linked filesystem. This is important to keep in mind, as you will end up working with a different file as you walk the filesystem upwards or downwards. This is not a bug but a useful intentional behavior.

You can also follow package links in both directions.

Package links are used to install packages on a website. It is often useful to view the documentation of a package that belongs to the exact version you have installed. For that reason, visiting the mounted package (by path) in your browser will pull up its documentation.

Accessing the filesystem root of the mounted package from within the package subtree will thus return the root of the package filesystem. This is needed to keep the package functional, to resolve file types properly. It is said that the package link establishes a new filesystem scope.

Link type: scope

A scope link is primarily used to make packages editable. Simply change the package link to a scope link. As a side effect, you will not be able to receive updates any longer.

Like the package link, the scope link also establishes a new filesystem scope. Read more on it below.

The only difference between a scope link and a volume link is that the former establishes a new filesystem scope, while the latter does not.

Link type: volume

A volume link is used to create a new fileNodeId space. One benefit of this is that you can create multiple copies of a volume without changing its root fileHash. Because of this, volume links can be used for version controlling a subtree: create a copy of the entire volume to make a snapshot. Because Boomla automatically deduplicates all files, you will only incur a storage cost for the difference between the versions.

Note that automatic URL redirection works only so long a file retains its fileId. Moving a file across volume boundaries will break this functionality.

Link type: path

A path link simply references another file by path. The link is never automatically followed thus all properties, attributes, body and children are accessed on the linking file. You have to explicitly follow the linking file to access the referenced file.

Link behavior

No automatic dereferencing

Boomla files have a dedicated link property so there is no need to immediately dereference file links upon access. It's best to think about file links in Boomla as pointers in programming languages. You can explicitly dereference a pointer, you can change where it points to or the pointer may be followed upon accessing its value. But your variable will still contain the original pointer, not the value.

Similarly in Boomla, some link types are followed when accessing the file’s properties, attributes, body or children - except for the link property. Accessing the link property is always accessed on the linking file, which is very important as you could not edit it otherwise.

Static links / dynamic links

A static link mounts another volume by its hash. The mounted volume is part of the filesystem and the link can not break. Modifying a statically mounted volume causes hash change propagation in the linking volume.

Any link that is not a static link is called a dynamic link. For example, path links do not mount another volume, simply point to another file by an internal path. The link may be broken as the referenced file may not exist. Also, changing the linked file will not cause hash change propagation in the filesystem.

Transparent link

A link is said to be a transparent link if it lets you transparently read and write the linked file's data except the following:

  • name,

  • file hash,

  • subtree size,

  • fileId,

  • fileNodeId,

  • link.

The rest of the file's data is accessed on the LINKED file:

  • type,

  • title,

  • status code,

  • attributes,

  • body,

  • children,

  • created, createdBy,

  • modified, modifiedBy,

  • subtreeModified, subtreeModifiedBy.

For example, a volume link is a transparent link while a path link is not.

Filesystem scope

The filesystem scope specifies the root file to be used for path resolutions. Filesystem scopes are implicitly created by some of the file link types. Filesystem scopes always start at volume roots. A filesystem scope may be local or global.

Filesystem scopes are used within packages to resolve file links and file types correctly.

Read-only / read-write mounted volumes

A mounted subtree may be read-only, as in the case of package links. Other links may allow writing the mounted subtree, as is the case for volume links.