imag/doc/src/05100-lib-entryref.md

2 KiB

libimagentryref

This library crate contains functionality to generate references within the imag store.

A reference is a "pointer" to a file or directory on the filesystem and outside the store. It differs from libimagentrylink/external linking as it is designed exclusively for filesystem references, not for URLs.

A reference is created with a unique identifier, like a hash. The implementation how this hash is calculated can be defined by the user of libimagentryref.

So this library helps to resemble something like a symlink.

Usage

Users have to implement the UniqueRefPathGenerator trait which should implement a hashing functionality for pathes.

Limits

This is not intended to be a version control system or something like that. We also can not use real symlinks as we need imag-store-objects to be able to link stuff.

Usecase

This library offers functionality to refer to content outside of the store. It can be used to refer to nearly static stuff pretty easily - think of a Maildir - you add new mails by fetching them, but you mostly do not remove mails. If mails get moved, they can be re-found via their hash, because Maildir objects hardly change. Or because the hash implementation which is used to refer to them hashes only the Message-Id and that does not change.

Long-term TODO

Not implemented yet:

  • Re-finding of files via their hash. This must be implemented with several things in mind * The user of the library should be able to provide a way how the filesystem is searched. Basically a Functor which yields pathes to check based on the original path of the missing file. This enables implementations which do only search a certain subset of pathes, or does depth-first-search rather than breadth-first-search.

Known problems

The functionality this library provides fails to work when syncing the imag store between two devices where the data layout is different on each device.