This module manages a file store in which a label is associated with every file and directory. The file store is grouped into directories by label. Files are stored under names like:

 LabelHash/OpaqueName

where LabelHash is a SHA-224 hash of the label, and OpaqueName is either a regular file (containing contents) or a directory populated exclusively by symbolic links pointing back into LabelHash directories. Each LabelHash directory also has a file called

 LabelHash/LABEL

which actually contains the label of all the files in that directory.

There is also a symbolic link root, pointing to the root directory. For efficiency, LabelHash actually consists of multiple directories.

There are two externally-visible abstractions. The first is Name, which refers to a file name in a user directory, of the form:

 LabelHash/OpaqueName/UserName

There is also a special Name, rootDir, which refers to the root directory. Untrusted user code has access to the rootDir Name, and can walk the tree from there using the lookupName function. The LIO.Handle module contains functions mkDir and mkLHandle which permit untrusted code to make new Names as well as to do handle-based IO on protected files.

The second is Node, which refers to one of the OpaqueNames that Names point to. Currently, any functions that operate on Nodes are in the IO Monad so as not to be executable by untrusted code. This is important because in order to use a file, someone must have the right to know know that the file exists, and this requires read permission on the file's Name. It would be insecure if untrusted code could execute openNode in the LIO Monad.

Note that if a machine crashes, the code in this module could leave the filesystem in an inconsistent state. However, the code tries to maitain the invariant that any inconsistencies will either be:

1. temporary files or directories whose names end with the "~" character, or
2. dangling symbolic links.

Both of these inconsistencies can be checked and cleaned up locally without examining the whole file system. The code tries to fix up these inconsistencies on-the-fly as it encounters them. However, it could possibly lieave some stranded temporary LABEL...~ files. You could also end up with some weirdness like a file that shows up in getDirectoryContents, but that you can't open for reading.

To keep from having to examine the whole file system to fix errors, the code tries to maintain the invariant that if a 'Node'\'s file name doesn't end with ~, then there must be a link pointing to it somewhere. This is why the code uses a separate NewNode type to represent a Node whose name ends ~. The function linkNode renames the NewNode to a name without a trailing ~ only after creating a Name that points to the permenent Node path.

Assuming a file system that preserves the order of metadata operations, the code should mostly be okay to recover from any crashes. If using soft updates, which can re-order metadata operations, you could end up with symbolic links that point nowhere.

In the worst case scenario if inconsistencies develop, you can manually fix up the file system by deleting all danglinng symbolic links and all files and directories ending ~. Make sure no application is concurrently accessing the file system, however.