make share manager single source of truth

[butonic]

Sharing

This document proposes changes on managing and accessing shares in reva. The goal is to streamline the information and make the process more robust.

Summary

• The share managers become the single source for all share information, including names / mountpoints
• Shares are no longer recorded on the storage using the storage providers
• Accepting shares no longer creates a reference in a storage provider but in the share manager
• The sharesstorageprovider provides both a file tree exposing all accepted shares as well as a separate space for each received share

Current implementation

Basic information about shares - i.e. who shared what with whom - are currently managed by the share manager. Additional information such as the names and the mountpoints of the shares are physically kept on the storage as references in the according locations and those references are being maintained by the storage providers.

This split of information makes it difficult to gather the mountpoints of all shares of user and is prone to inconcistencies between the data in the share manager and on the storage.

• There is no way around looking up the name of the accepted share, either in the storage provider or in the share manager: we need it to deduplicate shares with the same name.
• There is significant overhead when having to stat all shares to get the actual name (or path) of the accepted share

Proposed change

With this proposal shares will no longer be "mounted" on the storage. Instead the names and mountpoints move into the share manager alongside the basic share information and all references disappear from the storage (they can optionally be sent there as well and the storage driver can decide how to represent them, eg. as symlinks).

A SharesStorageProvider provides a file tree of all shares the currently logged in user has received and that tree can be mounted by the gateway at an appropriate location, eg.: /shares or /home/shares. In addition the SharesStorageProvider also takes care of exposing received shares as spaces.

With this change the manager becomes the single source of truth regarding shares. It can thus answer both:

• the question which resources a specific user shared with others, as well as
• the question which shares a specific user received, including their acceptance state and mount points.

The storage providers and drivers no longer have to keep track of shares, in fact they do not have to know shares exist in the first place.

This becomes optional, as was intended from the beginning, by configuring the gateway to (not) forward grant requests and create reference requests to the storage providers. See commit_share_to_storage_grant and commit_share_to_storage_ref. Administrators can still configure the gateway to forward grants to storage providers and they can still apply acls to share a resource on the os layer. The source of truth however is the share manager (think of it as periodically setting the ACLs on the storage, overwriting existing ACLs).

Expected Results

The SharesStorageProvider reads all metadate from the share manager and can provide access to all received shares by returning CS3 references.

FaQ

Share indicators require asking the share manager

To render a PROPFIND result for public and authenticated listings of folders, we need to know if a resource has been shared or not. If we are not persisting any share information in the storage provider we need to query the share manager for every PROPFIND. We can optimize this case when listing folders, but an overhead for merging two potenitially large lists remains.

Alternate solution: treat the storage provider like a cache for share properties. We could forward share requests to the storage providers and they could persist the data on the owners side, but only as a cache. The cache invalidation must happen when a share is being accessed (the share manager has to be checked, to verify the share still exists) and it should happen when a share is updated/removed.

Related Pull Requests

• Sharestorageprovider oc10 sm #2023 (old pr) implements the SharesStorageProvider
  • many of the now failing tests are caused by not being able to rename a received share in the current implementation. Shifting the responsibility to the share manager will make fixing them possible. It would also allow mounting multiple shares with the same name (by adding a number suffix as in oc10)
• [WIP] Add a SharesStorageProvider and an oc10 sql share manager owncloud/ocis#2232 add necessary config to ocis

Remaining tasks

• as an example teach the owncloudsql share manager where mount points are coming from
  • make renaming accepted shares possible by reading and updating the oc_share table
  • extend the necessary data structures so that the SharesStorageProvider can fetch the mount points: https://cs3org.github.io/cs3apis/#cs3.sharing.collaboration.v1beta1.ReceivedShare needs at least a mount point / path / reference
  • derive necessary changes for the cs3 share manager api
  • keep in mind that in oc10 group shares have 'child' share entries in the oc_share table for every user. It is used to persist the mount point of a share for every user (in oc10 users can rename and move the mount point to arbitrary paths).
• make SharesStorageProvider remove a cached grant from the storage provider if the share is no longer valid (also fixes expiry)

Difference to a owncloud10homestorageprovider

The SharesStorageProvider jails all accepted shares of a user in a single directory. In contrast to the owncloud 10 home it does not allow arbitrary mount points. When listing shares from an existing oc10 database the file_target column might contain a deep path like /some/deep/moint/point/for/received/share/foo. It will only be listed by the basename. Multiple received shares with the same base name are deduplicated by appending the shareid in brackets. This workaround will go away with spaces concept.

[butonic]

• extend collaboration ListReceivedSharesResponse with mountpoint (type reference)
• extend ocm ListReceivedSharesResponse with mountpoint (type reference)
• extend share manager UpdateShareRequest with mountpoint (not the gateway)
• replace UpdateShareRequest.UpdateField with FieldMask in UpdateShareRequest

[butonic]

blocked by cs3org/cs3apis-build#14