Projects/tutoring/PoingCloud

Documentation status: (2020-04-02) currently under construction

Functional Description

PoingCloud (PC) is a GUI desktop application which synchronizes selected folders on a desktop computer with designated counterparts on a WebDAV server (such as, but not restricted to, NextCloud or ownCloud) while keeping a revertible journal of such changes. It is intended to be a drop-in replacement for the NextCloud and ownCloud clients, though it will not necessarily be able to read their configuration files. (An import/export feature might be a future project.)

All operations will be GUI-controlled, including operations designed specifically to interface with other software that expects text-based input.

Conceptual Design

Operations

The key operational elements of PC are:

• A connection between PC and a remote server, which includes:
  • the URL to the server's WebDAV API
  • the user credentials (either {username + password} or a shared secret) for accessing it
  • (phase 2) additional parameters including optional throttling of upload/download speeds
  • zero or more syncsets (at least one is needed for practical usage, but a connection can exist without any)
  • time interval between checks for changed files
• A syncset is essentially a mapping between a folder or file on the local machine and a folder or file on the remote.
  • One or the other must exist at the time the syncset is created, but they don't both have to exist.
  • Settings for each syncset include:
    • absolute path to local folder
    • path to remote folder (relative to user's root)
    • [ ] update local from remote (default: yes)
    • [ ] update remote from local (default: yes)
    • [ ] delete local if remote is deleted (default: yes)
    • [ ] delete remote if local is deleted (default: yes)
    • [ ] on first sync: delete local files not found on remote (default: no)
      • Why: When first connecting, we most likely want to have local copies of any existing remote files.
    • [ ] on first sync: delete remote files not found on local (default: no)
      • Why: When first connecting, we most likely want to copy over any existing local files.
    • Minimum time between syncs
      • Why: the user may want to keep backups of files that change frequently, such as logfiles, databases, or live media recordings. Repeated resyncs, especially of large files, can clog the queue.

Interface

The user has the ability to:

• add, edit, delete, export, and import connection specs
  • export may be individual or collective
• Within a connection, the user may:
  • add, edit, delete, export, and import syncsets
    • connection data may include or omit associated syncsets
  • view the interactions between client and server:
    • in raw text format (with large data blobs redacted for readability)
    • graphically, where appropriate (path to file currently being scanned or copied; status of copy if it takes longer than some lower limit), difference in timestamps
• Specify files to ignore when synchronizing.
  • Encountering a local file specified as ignorable should not generate an error or warning.
  • Encountering a remote file specified (locally) as ignorable must cause a display somewhere indicating that this has happened, which can then be queried for further action (e.g. the user could make the file non-ignorable, or could delete the file on the remote). Any indication must not block or interfere with the handling of any other warnings or errors, however.

Exports will use a standard text markup language designed for data storage and exchange, e.g. YAML, XML, JSON (to be determined).

Glossary

• local: the machine on which the application is running, and the set of syncable files it contains
• remote: the set of files which is not on the local machine, i.e. is on the WebDAV server
• revertible: capable of being "rolled back" to an earlier version
• syncset: a set of files which PC has been told to keep synchronized between local and remote
• synchronize: To "synchronize" means that:
  • Changes to either copy (remote or local) of a given file will result in the changed version overwriting the older version in the other location.
    • e.g. if the local copy is changed, it will be uploaded to the remote and overwrite the version there
  • If both copies appear to have been modified since they were last synchronized, PC should keep both copies and log the fact that there was an edit conflict.
    • We might eventually want to add the option to override this policy for some files, file-types, or folders, but that can be added later as needed.