diff --git a/docs/ocis/adr/0013-locking.md b/docs/ocis/adr/0013-locking.md new file mode 100644 index 0000000000..f5774223b7 --- /dev/null +++ b/docs/ocis/adr/0013-locking.md @@ -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..` and `.~lock.#` 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.#` 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) +- 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 +- 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 diff --git a/go.mod b/go.mod index 34f45d067a..3d48f53b1c 100644 --- a/go.mod +++ b/go.mod @@ -61,7 +61,7 @@ require ( go.opencensus.io v0.23.0 go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.25.0 go.opentelemetry.io/otel v1.1.0 - go.opentelemetry.io/otel/exporters/jaeger v1.0.1 + go.opentelemetry.io/otel/exporters/jaeger v1.1.0 go.opentelemetry.io/otel/sdk v1.1.0 go.opentelemetry.io/otel/trace v1.1.0 golang.org/x/crypto v0.0.0-20210921155107-089bfa567519 diff --git a/go.sum b/go.sum index ef5600eccf..4999acb841 100644 --- a/go.sum +++ b/go.sum @@ -1330,8 +1330,9 @@ go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.2 go.opentelemetry.io/otel v1.0.1/go.mod h1:OPEOD4jIT2SlZPMmwT6FqZz2C0ZNdQqiWcoK6M0SNFU= go.opentelemetry.io/otel v1.1.0 h1:8p0uMLcyyIx0KHNTgO8o3CW8A1aA+dJZJW6PvnMz0Wc= go.opentelemetry.io/otel v1.1.0/go.mod h1:7cww0OW51jQ8IaZChIEdqLwgh+44+7uiTdWsAL0wQpA= -go.opentelemetry.io/otel/exporters/jaeger v1.0.1 h1:fg9udWIWWJMAT+Gq2ATFd/DFy3OZvKEZy9VK2amxvkw= go.opentelemetry.io/otel/exporters/jaeger v1.0.1/go.mod h1:85Ym3qknJdIdfRzYS9Ofy9NeLi9gKPFzFDBEHCKpfXI= +go.opentelemetry.io/otel/exporters/jaeger v1.1.0 h1:VRF+Hf3EePFO6ab7/wfPoyWzSY4z5X0tTvQtV9/Mq8Y= +go.opentelemetry.io/otel/exporters/jaeger v1.1.0/go.mod h1:D/GIBwAdrFTTqCy1iITpC9nh5rgJpIbFVgkhlz2vCXk= go.opentelemetry.io/otel/sdk v1.0.1/go.mod h1:HrdXne+BiwsOHYYkBE5ysIcv2bvdZstxzmCQhxTcZkI= go.opentelemetry.io/otel/sdk v1.1.0 h1:j/1PngUJIDOddkCILQYTevrTIbWd494djgGkSsMit+U= go.opentelemetry.io/otel/sdk v1.1.0/go.mod h1:3aQvM6uLm6C4wJpHtT8Od3vNzeZ34Pqc6bps8MywWzo=