Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs-only] add locking adr #2701

Merged
merged 2 commits into from
Oct 29, 2021
Merged

[docs-only] add locking adr #2701

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6fdca51
add locking adr
wkloucek Oct 28, 2021
bb512b1
add results of discussion
wkloucek Oct 29, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 94 additions & 0 deletions docs/ocis/adr/0013-locking.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
---
title: "13. Locking"
weight: 13
date: 2021-08-17T12:56:53+01:00
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs/ocis/adr
geekdocFilePath: 0013-locking.md
---

- Status: proposed
- Deciders: @pmaier1, @dragotin, @butonic, @micbar, @wkloucek
- Date: 2021-10-28

## Context and Problem Statement

At the time of this writing no locking mechanisms exists in oCIS / REVA for both directories and files. The CS3org WOPI server implements a file based locking in order to lock files. This ADR discusses if this approach is ok for the general availability of oCIS or if changes are needed.

## Decision Drivers

- Is the current situation acceptable for the GA
- Is locking needed or can we have oCIS / REVA without locking

## Considered Options

1. File based locking
2. No locking
3. CS3 API locking

## Decision Outcome

// TODO, but recommendation against file based locking. Because file based locking does not work on file-only shares

## Pros and Cons of the Options

### File based locking

The CS3org WOPI server creates a `.sys.wopilock.<filename>.` and `.~lock.<filename>#` file when opening a file in write mode

**File based locking is good**, because:

- it is already implemented in the current CS3org WOPI server

**File based locking is bad**, because:

- lock files should be checked by all partys manipulating files (eg. the WebDAV api)
- lock files can be deleted by everyone
- you can not lock files in a file-only share (you need a folder share to create a lock file besides the original file)

If we have file based locks, we can also sync them with eg. the Desktop Client.

**Syncing lock files is good**: because

- native office applications can notice lock files by the WOPI server and vice versa (Libre Office also creates `.lock.<filename>#` files)

**Syncing lock files is bad**, because:

- if lockfile is not deleted, no one can edit the file
- creating lock files in a folder shared with 2000000 users creates a lot of noise and pressure on the server (etag propagation, therefore oC Desktop sync client has an ignore rule for `.~lock.*` files)

### No locking

We remove or disable the file based locking of the CS3org WOPI server.

**No locking is good**, because:

- you don't need to release locks
- overwriting a file just creates a new version of it

**No locking is bad**, because:

- merging changes from different versions is a pain, since there is no way to calculate differences for most of the files (eg. docx or xlsx files)
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An additional item for this scenario (pure hypothetical I know, but for the sake of it):
- no locking breaks the WOPI specs, as the CS3 WOPI server won't be capable to honor the WOPI Lock related operations

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh yes, good point.

- no locking breaks the WOPI specs, as the CS3 WOPI server won't be capable to honor the WOPI Lock related operations

### CS3 API locking

- Add CS3 API for resource (files, directories) locking, unlocking and checking locks
- locking always with timeout
- lock creation is a "create-if-not-exists" operation
- locks need to have arbitrary metadata (eg. the CS3 WOPI server is stateless by storing information on / in the locks)
- Implement WebDAV locking using the CS3 API
- Implement Locking in storage drivers
- Change CS3 WOPI server to use CS3 API locking mechanism
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The semantic of the lock API would need to include the possibility to decorate the lock with some arbitrary metadata. Currently the CS3 WOPI server is stateless and stores some (JWT-encoded) information in the locks for its operations.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Couldn't it use the general API to store metadata to files in CS3? Or do you mean that it is lock-specific metadata, ie. who locked (should be considered) or when the lock started, or how long? Even that could, if it is in an unique namespace, be stored through the general API.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's correct indeed: the metadata is lock-specific, but locks and files are 1-to-1 so it is "syntactically equivalent" to use the general metadata API, say with a wopilock xattr.
Yet, there's a semantic catch: as today a user can delete a lock file, with this assumption the user may delete the wopilock xattr, making the lock totally useless from a WOPI perspective. So for the sake of a Lock API - which on top is expected to be atomic (where implementing cs3org/reva#1786 would help, if the lock is ultimately stored somewhere by the storageprovider) - the lock metadata should stay attached to the lock "object" for the whole lock's lifetime.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, the user must not have access to this xattr. Good point, we need a distinction between "user-editable" and system meta data.
The lock "object" I think is the file that is locked itself. And that operation does not really have to be atomic, only in the sense that if a lock is created, there must not be another lock exsting. That is a create-if-not-exists operation which in it has somehow to be atomic.

- Optional: manual lock / unlock in ownCloud Web (who is allowed to unlock locks of another user?)

**CS3 API locking is good**, because:

- you can lock files on the actual storage (if the storage supports that -> storage driver dependent)
- you can lock files in ownCloud 10 when using the ownCloudSQL storage driver in the migration deployment (but oC10 Collabora / OnlyOffice also need to implement locking, to fully leverage that)
- clients can get the lock information via the api without ignoring / hiding lock file changes
- clients can use the lock information to lock the file in their context (eg. via some file explorer integration)

**CS3 API locking is bad**, because:

- it needs to be defined and implemented, currently not planned for the GA