undo-redo-guide.md

Undo/Redo Technical Guide

Actions

A ActionType is a class which defines how to do, undo and redo a particular action in Baserow. It can freely use Handlers to do the logic, but it almost certainly shouldn't call any other ActionType's unless it is some sort of meta ActionAction if we ever have one. ActionTypes will be retrieved from a registry given a type and triggered by API methods ( e.g. action_type_registry.get_by_type(DeleteGroupAction).do(user, group_to_delete)).

1. In backend/src/baserow/core/actions/registries.py there is a action_type_registry which can be used to register ActionType's
2. An ActionType must implement do/undo/redo methods.
   1. do Performs the action when a user requests it to happen, it must also save a Action model using cls.register_action
   2. undo Must undo the action done by do. It must not save any Action models.
   3. redo Must redo the action after it has been undone by undo. It must not save any Action models.
3. An ActionType must implement a Params dataclass which it will store any parameters it needs to undo or redo the action in. An instance of this dataclass must be provided to cls.register_action in the do method, and it will be serialized to JSON and stored in the Action table. When redo or undo is called this dataclass will be created again from the json in the Action row and provided to the function.

Quick summary of the Action Table

See baserow.core.action.models.Action for more details.

id (serial)	user_id (fk to user table, nullable)	session (text nullable)	category (text)	created_on (auto_now_add DateTimeField)	type (text)	params (JSONB)	undone_at (nullable DateTimeField)	error (text nullable)
1	2	'some-uuid-from-client'	'root'	datetime	'group_created'	'{created_group_id:10}'	null	null

ActionHandler and Undo/Redo endpoints

The ActionHandler has undo and redo methods which can be used to trigger an undo/redo for a user. There are two corresponding endpoints in /api/user/undo and /api/user/redo which call the ActionHandler. To trigger an undo / redo we need three pieces of information:

1. The user triggering the undo/redo, so we can check if they still have permissions to undo/redo the action. For example a user might be redoing a deletion of a group, but if they have been banned from the group in the meantime they should be prevented from redoing.
2. A client session id. Every time a user does an action in Baserow we check the ClientSessionId header. If set we associate the action with that ClientSessionId. When a user then goes to undo or redo they also provide this header and we only let them undo/redo actions with a matching ClientSessionId. This lets us have different undo/redo histories per tab the user has open as each tab will generate a unique ClientSessionId.
3. A category. Every time an action is performed in Baserow we associate it with a particular category. This is literally just a text column on the Action model with values like root or table10 or group20. An actions category describes in which logical part of Baserow the action was performed. The ActionType implementation decides what to set its category to when calling cls.register_action. When an undo/redo occurs the web-frontend sends the categories the user is currently looking at. For example if I have table 20 open, with group 6 in the side bar and I press undo/redo the category sent will be:

{
  root: true,
  table: 20,
  group: 6
}

By sending this category to the undo/redo endpoint we are telling it to undo any actions which were done in:

1. The root category
2. The table 20 category
3. The group 6 category

For example, if I renamed table 20, then the table_update action would be in group 6 category. If I was then looking at table 20 in the UI and pressed undo, the UI would send the group 6 category as one of the active categories as table 20 is in group 6. Meaning I could then undo this rename. If i was to first switch to group 5 and press undo, the UI would send group 5 as the category and I wouldn't be able to undo the rename of table 20 until I switched back into a part of the UI where the group 6 category is active.

Undo Redo Worked Example

1. User A opens Table 10, which is in Application 2 in Group 1.
   1. On page load a ClientSessionId example_client_session_id is generated and stored in the auth store. (its a uuid normally).
   2. The current category for this page is set in the undoRedo store to be: {root: true, table_id:10, application_id:2, group_id:1}
2. User A changes the Tables name.
   1. A request is sent to the table update endpoint.
      1. The ClientSessionId header is set on the request to example_client_session_id
   2. The table update API endpoint will call action_type_registry.get(UpdateTableAction).do(user, ...)
   3. The change is made and a new Action is stored.
      1. UpdateTableAction sets the category of the action to be group1
      2. The ClientSessionId is found from the request and the session of the action is set to example_client_session_id
      3. The user of the action is set to User A
      4. The old tables name is stored in the action.params JSONField to facilitate undos and redos.
3. User A presses Undo
   1. A request is sent to the undo endpoint with the category request data value set to the current category of the page the user has open obtained from the undoRedo store (see above).
      1. The ClientSessionId header is set on the request to example_client_session_id
   2. ActionHandler.undo is called.
      1. It finds the latest action for User A in session example_client_session_id and in any of the following categories ["root", "group1", "application2", "table10"]. These were calculated from the category parameter provided to the endpoint.
      2. The table rename action is found as it's session matches, it is in category group, it was done by User A and it has not yet been undone ( the undone_at column is null).
      3. It deserializes the parameters for the latest action from the table into the action's Params dataclass
      4. It calls `action_type_registry.get(UpdateTableAction).undo(user, params, action_to_undo)
      5. UpdateTableAction using the params undoes the action
      6. Action.undone_at is set to timezone.now() indicating it has now been undone

What happens when an undo/redo fails

Imagine a situation when two users are working on a table at the same time, in order they: 1 User A changes a cell in a field called 'date'

2. User A changes a cell in a field called 'Name'
3. User B deletes the 'name' field
4. User A presses 'undo' - in our current implementation they get an error saying the undo failed and was skipped
5. User A presses 'undo' - in our current implementation Users A's first change now gets undone

We cannot undo User A's latest action as it was to a cell in the now deleted field ' name'. What will happen when is:

1. We will attempt to undo User A's action by calling ActionHandler.undo
2. It will crash and raise an exception
3. In the ActionHandler.undo method we catch this exception and:
   1. We store it on the action's error field
   2. We mark the action as undone by setting it's undone_at datetime field to timezone.now()
   3. We send a specific error back to the user saying the undo failed, and we skipped over it.

Interestingly, if the user then presses redo twice we will:

1. Redo user A's first action
2. Now we are trying to redo the action that failed. It has an error set. We see this error and send and error back to the user saying can't redo due to error, skipping.
3. However we also remove the error and mark the action as "redone".
4. Now the user can press "undo" again and the action will be attempted to be undone a second time just like the first. If User B has by this point restored the delete field it could now work!