Merge branch 'master' into try-gookikt-config

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.<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)
+- 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

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

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=