matthiasbeyer/imag
1
0
Fork 0
Code Releases Activity

Update documentation for new implementation

Browse source
This commit is contained in:
Matthias Beyer 2018-02-13 22:49:31 +01:00
parent cbb47cffcb
commit a5eaf0439c
1 changed files with 25 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

70
doc/src/05100-lib-entryref.md
View file

@ -3,27 +3,24 @@
This library crate contains functionality to generate _references_ within the This library crate contains functionality to generate _references_ within the
imag store. imag store.
It can be used to create references to other files on the filesystem (reachable A reference is a "pointer" to a file or directory on the filesystem and outside
via a filesystem path). It differs from `libimagentrylink`/external linking as the store.
It differs from `libimagentrylink`/external linking as
it is designed exclusively for filesystem references, not for URLs. it is designed exclusively for filesystem references, not for URLs.
A reference can have several properties, for example can a reference track the A reference is created with a unique identifier, like a hash. The implementation
content of a filesystem path by hashing the content with a hashsum (SHA1) and how this hash is calculated can be defined by the user of `libimagentryref`.
one can check whether a file was changed by that.
As files can get big (think of `debian.iso`) _partial hashing_ is supported
(think of "hash the first 2048 bytes of a file).
The library contains functionality to re-find a moved file automatically by
checking the content hash which was stored before.
Permission changes can be tracked as well.
So this library helps to resemble something like a _symlink_. 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 ### Limits
Please understand that this is _not_ intended to be a version control system or This is _not_ intended to be a version control system or something like that.
something like that.
We also can not use _real symlinks_ as we need imag-store-objects to be able to We also can not use _real symlinks_ as we need imag-store-objects to be able to
link stuff. link stuff.
@ -31,39 +28,22 @@ link stuff.
This library offers functionality to refer to content outside of the store. 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 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 Maildir - you add new mails by fetching them, but you mostly do not remove
and if you do you end up with a "null pointer" in the store, which can then be mails.
handled properly. 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
As this library supports custom hashes (you don't have to hash the full file, hashes only the `Message-Id` and that does not change.
you can also parse the file and hash only _some_ content) this is pretty
flexible.
For example if you want to implement a imag module which tracks a certain kind
of files which constantly change... but the first 5 lines do never change
after the file is created - you can write a custom hasher that only uses the
first 5 lines for the hash.
### Internals
Internally, in the store, the file gets created under
`/ref/<hash of the path to the file to refer to>`.
If the content of the file is hashed, we can still re-find the file via the
content hash (which is stored in the header of the store entry).
The reference object can, after the path was re-found, be updated.
### Long-term TODO ### Long-term TODO
Things which have to be done here or are not yet properly tested: Not implemented yet:
- [ ] Testing of different Hashers - [ ] Re-finding of files via their hash.
- [ ] Testing of re-finding of objects, including: This must be implemented with several things in mind
- [ ] Can a moved file automatically be found by content hash? * The user of the library should be able to provide a way how the
- [ ] Does a store-reference get updated automatically if it was moved, filesystem is searched. Basically a Functor which yields pathes to
including links (as in `libimaglink`)? check based on the original path of the missing file.
- [ ] If the content of a file changes, does the content hash get updated This enables implementations which do only search a certain subset
automatically? of pathes, or does depth-first-search rather than
breadth-first-search.
("automatically" is a strechable term here, as these things have to be triggered
by the user anyways)