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

   1 Magic Folders local filesystem integration design
   2 =================================================
   3
   4 *Scope*
   5
   6 This document describes how to integrate the local filesystem with Magic
   7 Folders 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
  16 *Local scanning and database*
  17
  18 When a Magic-Folder-enabled node starts up, it scans all directories
  19 under the local directory and adds every file to a first-in first-out
  20 "scan queue". When processing the scan queue, redundant uploads are
  21 avoided by using the same mechanism the Tahoe backup command uses: we
  22 keep track of previous uploads by recording each file's metadata such as
  23 size, CTIME and MTIME. This information is stored in a database referred
  24 to from now on as the magic folder db. Using this recorded state, we
  25 ensure that when Magic Folder is subsequently started, the local
  26 directory tree can be scanned quickly by comparing current filesystem
  27 metadata with the previously recorded metadata. Each file referenced in
  28 the scan queue is uploaded only if its metadata differs at the time it is
  29 processed. If a change event is detected for a file that is already
  30 queued (and therefore will be processed later), the redundant event is
  31 ignored.
  32
  33 To implement the magic folder db, we will use an SQLite schema that
  34 initially is the existing Tahoe-LAFS backup schema. This schema may
  35 change in later objectives; this will cause no backward compatibility
  36 problems, because this new feature will be developed on a branch that
  37 makes no compatibility guarantees. However we will have a separate SQLite
  38 database file and separate mutex lock just for Magic Folder. This avoids
  39 usability problems related to mutual exclusion. (If a single file and
  40 lock were used, a backup would block Magic Folder updates for a long
  41 time, and a user would not be able to tell when backups are possible
  42 because Magic Folder acquires a lock at arbitrary times.)
  43
  44
  45 *Eventual consistency property*
  46
  47 It is not possible to prevent local writes to a file while it is being
  48 read in order to upload it. Such writes will result in temporary
  49 inconsistency. Eventual consistency is reached when the queue of pending
  50 uploads is empty. That is, a consistent snapshot will be achieved
  51 eventually when local writes to the target folder cease for a
  52 sufficiently long period of time.
  53
  54
  55 *Detecting filesystem changes*
  56
  57 For the Linux implementation we will use the inotify Linux kernel
  58 subsystem to gather events on the local Magic Folder directory tree. This
  59 implementation was already present in Tahoe-LAFS 1.9.0, but needs to be
  60 changed to gather directory creation and move events, as well as events
  61 indicating that a file has been written.
  62
  63 For the Windows implementation we will use the ``ReadDirectoryChangesW``
  64 Win32 API. The prototype implementation simulates the inotify API in
  65 terms of ``ReadDirectoryChangesW``, allowing most of the code to be
  66 shared across platforms.
  67
  68 When we detect the creation of a new directory below the local Magic
  69 Folder directory, we create it in the Tahoe-LAFS filesystem, and also
  70 scan the new local directory for new files. This scan is necessary to
  71 avoid missing events for creation of files in a new directory before it
  72 can be watched, and to correctly handle cases where an existing directory
  73 is moved to be under the local Magic Folder directory.
  74
  75
  76 *User interface*
  77
  78 The Magic Folders local filesystem integration will initially have a
  79 provisional configuration file-based interface that may not be ideal from
  80 a usability perspective. Creating our local filesystem integration in
  81 this manner will allow us to use and test it indepently of the rest of
  82 the Magic Folder software components. We will focus greater attention on
  83 user interface design as a later milestone in our development roadmap.
  84
  85 The configuration file, ``tahoe.cfg``, must define a target local
  86 directory to be synchronized. Provisionally, this configuration will
  87 replace the current "drop-upload" section::
  88
  89  [magic_folders]
  90  enabled = true
  91  local.directory = "/home/human"
  92
  93 When a filesystem directory is first "added" to Magic Folders, the user
  94 needs to create the remote Tahoe-LAFS directory using ``tahoe   mkdir``,
  95 and configure the Magic-Folder-enabled node with its URI (e.g. by putting
  96 it in a file ``private/magic_folder_dircap``). If there are existing
  97 files in the local directory, they will be uploaded as a result of the
  98 initial scan described earlier.
  99