docs/proposed/magic-folder/filesystem-integration.rst

   1 Magic Folder local filesystem integration design
   2 ================================================
   3
   4 *Scope*
   5
   6 This document describes how to integrate the local filesystem with Magic
   7 Folder in an efficient and reliable manner. For now we ignore Remote to
   8 Local synchronization; the design and implementation of this is scheduled
   9 for a later time. We also ignore multiple writers for the same Magic
  10 Folder, which may or may not be supported in future. The design here will
  11 be updated to account for those features in later Objectives. Objective 3
  12 may require modifying the database schema or operation, and Objective 5
  13 may modify the User interface.
  14
  15 Tickets on the Tahoe-LAFS trac with the `otf-magic-folder-objective2`_
  16 keyword are within the scope of the local filesystem integration for
  17 Objective 2.
  18
  19 .. _otf-magic-folder-objective2: https://tahoe-lafs.org/trac/tahoe-lafs/query?status=!closed&keywords=~otf-magic-folder-objective2
  20
  21 *Local scanning and database*
  22
  23 When a Magic-Folder-enabled node starts up, it scans all directories
  24 under the local directory and adds every file to a first-in first-out
  25 "scan queue". When processing the scan queue, redundant uploads are
  26 avoided by using the same mechanism the Tahoe backup command uses: we
  27 keep track of previous uploads by recording each file's metadata such as
  28 size, ``ctime`` and ``mtime``. This information is stored in a database,
  29 referred to from now on as the magic folder db. Using this recorded
  30 state, we ensure that when Magic Folder is subsequently started, the
  31 local directory tree can be scanned quickly by comparing current
  32 filesystem metadata with the previously recorded metadata. Each file
  33 referenced in the scan queue is uploaded only if its metadata differs at
  34 the time it is processed. If a change event is detected for a file that
  35 is already queued (and therefore will be processed later), the redundant
  36 event is ignored.
  37
  38 To implement the magic folder db, we will use an SQLite schema that
  39 initially is the existing Tahoe-LAFS backup schema. This schema may
  40 change in later objectives; this will cause no backward compatibility
  41 problems, because this new feature will be developed on a branch that
  42 makes no compatibility guarantees. However we will have a separate SQLite
  43 database file and separate mutex lock just for Magic Folder. This avoids
  44 usability problems related to mutual exclusion. (If a single file and
  45 lock were used, a backup would block Magic Folder updates for a long
  46 time, and a user would not be able to tell when backups are possible
  47 because Magic Folder would acquire a lock at arbitrary times.)
  48
  49
  50 *Eventual consistency property*
  51
  52 During the process of reading a file in order to upload it, it is not
  53 possible to prevent further local writes. Such writes will result in
  54 temporary inconsistency (that is, the uploaded file will not reflect
  55 what the contents of the local file were at any specific time). Eventual
  56 consistency is reached when the queue of pending uploads is empty. That
  57 is, a consistent snapshot will be achieved eventually when local writes
  58 to the target folder cease for a sufficiently long period of time.
  59
  60
  61 *Detecting filesystem changes*
  62
  63 For the Linux implementation, we will use the inotify Linux kernel
  64 subsystem to gather events on the local Magic Folder directory tree. This
  65 implementation was already present in Tahoe-LAFS 1.9.0, but needs to be
  66 changed to gather directory creation and move events, in addition to the
  67 events indicating that a file has been written that are gathered by the
  68 current code.
  69
  70 For the Windows implementation, we will use the ``ReadDirectoryChangesW``
  71 Win32 API. The prototype implementation simulates a Python interface to
  72 the inotify API in terms of ``ReadDirectoryChangesW``, allowing most of
  73 the code to be shared across platforms.
  74
  75 The alternative of using `NTFS Change Journals`_ for Windows was
  76 considered, but appears to be more complicated and does not provide any
  77 additional functionality over the scanning approach described above.
  78 The Change Journal mechanism is also only available for NTFS filesystems,
  79 but FAT32 filesystems are still common in user installations of Windows.
  80
  81 .. _`NTFS Change Journals`: https://msdn.microsoft.com/en-us/library/aa363803%28VS.85%29.aspx
  82
  83 When we detect the creation of a new directory below the local Magic
  84 Folder directory, we create it in the Tahoe-LAFS filesystem, and also
  85 scan the new local directory for new files. This scan is necessary to
  86 avoid missing events for creation of files in a new directory before it
  87 can be watched, and to correctly handle cases where an existing directory
  88 is moved to be under the local Magic Folder directory.
  89
  90
  91 *User interface*
  92
  93 The Magic Folder local filesystem integration will initially have a
  94 provisional configuration file-based interface that may not be ideal from
  95 a usability perspective. Creating our local filesystem integration in
  96 this manner will allow us to use and test it independently of the rest of
  97 the Magic Folder software components. We will focus greater attention on
  98 user interface design as a later milestone in our development roadmap.
  99
 100 The configuration file, ``tahoe.cfg``, must define a target local
 101 directory to be synchronized. Provisionally, this configuration will
 102 replace the current ``[drop_upload]`` section::
 103
 104  [magic_folder]
 105  enabled = true
 106  local.directory = "/home/human"
 107
 108 When a filesystem directory is first configured for Magic Folder, the user
 109 needs to create the remote Tahoe-LAFS directory using ``tahoe mkdir``,
 110 and configure the Magic-Folder-enabled node with its URI (e.g. by putting
 111 it in a file ``private/magic_folder_dircap``). If there are existing
 112 files in the local directory, they will be uploaded as a result of the
 113 initial scan described earlier.
 114