From ff9ad8185b3f2fb6c53f8a64fca529ade86be568 Mon Sep 17 00:00:00 2001 From: "Dustin J. Mitchell" Date: Sun, 12 Dec 2021 10:31:27 -0500 Subject: [PATCH] undo docs --- docs/src/storage.md | 52 ++++++++++++++++++++++++++++++++++++++---- docs/src/sync-model.md | 10 ++++++++ 2 files changed, 57 insertions(+), 5 deletions(-) diff --git a/docs/src/storage.md b/docs/src/storage.md index c1c34f7e1..f733f4f98 100644 --- a/docs/src/storage.md +++ b/docs/src/storage.md @@ -21,21 +21,63 @@ See [Tasks](./tasks.md) for details on the content of that map. Every change to the task database is captured as an operation. In other words, operations act as deltas between database states. -Operations are crucial to synchronization of replicas, using a technique known as Operational Transforms. +Operations are crucial to synchronization of replicas, described in [Synchronization Model](./sync-model.md). + +Operations are entirely managed by the replica, and some combinations of operations are described as "invalid" here. +A replica must not create invalid operations, but should be resilient to receiving invalid operations during a synchronization operation. Each operation has one of the forms * `Create(uuid)` - * `Delete(uuid)` - * `Update(uuid, property, value, timestamp)` + * `Delete(uuid, oldTask)` + * `Update(uuid, property, oldValue, newValue, timestamp)` + * `UndoPoint()` The Create form creates a new task. It is invalid to create a task that already exists. Similarly, the Delete form deletes an existing task. It is invalid to delete a task that does not exist. +The `oldTask` property contains the task data from before it was deleted. -The Update form updates the given property of the given task, where property and value are both strings. -Value can also be `None` to indicate deletion of a property. +The Update form updates the given property of the given task, where the property and values are strings. +The `oldValue` gives the old value of the property (or None to create a new property), while `newValue` gives the new value (or None to delete a property). It is invalid to update a task that does not exist. The timestamp on updates serves as additional metadata and is used to resolve conflicts. + +### Application + +Each operation can be "applied" to a task database in a natural way: + + * Applying `Create` creates a new, empty task in the task database. + * Applying `Delete` deletes a task, including all of its properties, from the task database. + * Applying `Update` modifies the properties of a task. + * Applying `UndoPoint` does nothing. + +### Undo + +Each operation also contains enough information to reverse its application: + + * Undoing `Create` deletes a task. + * Undoing `Delete` creates a task, including all of the properties in `oldTask`. + * Undoing `Update` modifies the properties of a task, reverting to `oldValue`. + * Undoing `UndoPoint` does nothing. + +The `UndoPoint` operation serves as a marker of points in the operation sequence to which the user might wish to undo. +For example, creation of a new task with several properities involves several operations, but is a single step from the user's perspective. +An "undo" command reverses operations, removing them from the operations sequence, until it reaches an `UndoPoint` operation. + +### Synchronizing Operations + +After operations are synchronized to the server, they can no longer be undone. +As such, the [synchronization model](./sync-model.md) uses simpler operations. +Replica operations are converted to sync operations as follows: + + * `Create(uuid)` -> `Create(uuid)` (no change) + * `Delete(uuid, oldTask)` -> `Delete(uuid)` + * `Update(uuid, property, oldValue, newValue, timestamp)` -> `Update(uuid, property, newValue, timestamp)` + * `UndoPoint()` -> Ø (dropped from operation sequence) + +Once a sequence of operations has been synchronized, there is no need to store those operations on the replica. +The current implementation deletes operations at that time. +An alternative approach is to keep operations for existing tasks, and provide access to those operations as a "history" of modifications to the task. diff --git a/docs/src/sync-model.md b/docs/src/sync-model.md index e75bab670..11d6e0855 100644 --- a/docs/src/sync-model.md +++ b/docs/src/sync-model.md @@ -34,6 +34,16 @@ Since the replicas are not connected, each may have additional operations that h The synchronization process uses operational transformation to "linearize" those operations. This process is analogous (vaguely) to rebasing a sequence of Git commits. +### Sync Operations + +The [Replica Storage](./storage.md) model contains additional information in its operations that is not included in operations synchronized to other replicas. +In this document, we will be discussing "sync operations" of the form + + * `Create(uuid)` + * `Delete(uuid)` + * `Update(uuid, property, value, timestamp)` + + ### Versions Occasionally, database states are given a name (that takes the form of a UUID).