github.com/cs3org/reva/v2@v2.27.7/pkg/storage/storage.go (about) 1 // Copyright 2018-2021 CERN 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 // 15 // In applying this license, CERN does not waive the privileges and immunities 16 // granted to it by virtue of its status as an Intergovernmental Organization 17 // or submit itself to any jurisdiction. 18 19 package storage 20 21 import ( 22 "context" 23 "io" 24 "net/url" 25 26 provider "github.com/cs3org/go-cs3apis/cs3/storage/provider/v1beta1" 27 registry "github.com/cs3org/go-cs3apis/cs3/storage/registry/v1beta1" 28 tusd "github.com/tus/tusd/v2/pkg/handler" 29 ) 30 31 // FS is the interface to implement access to the storage. 32 type FS interface { 33 // Minimal set for a readonly storage driver 34 35 // Shutdown is called when the process is exiting to give the driver a chance to flush and close all open handles 36 Shutdown(ctx context.Context) error 37 38 // ListStorageSpaces lists the spaces in the storage. 39 // FIXME The unrestricted parameter is an implementation detail of decomposedfs, remove it from the function? 40 ListStorageSpaces(ctx context.Context, filter []*provider.ListStorageSpacesRequest_Filter, unrestricted bool) ([]*provider.StorageSpace, error) 41 42 // GetQuota returns the quota on the referenced resource 43 GetQuota(ctx context.Context, ref *provider.Reference) ( /*TotalBytes*/ uint64 /*UsedBytes*/, uint64 /*RemainingBytes*/, uint64, error) 44 45 // GetMD returns the resuorce info for the referenced resource 46 GetMD(ctx context.Context, ref *provider.Reference, mdKeys, fieldMask []string) (*provider.ResourceInfo, error) 47 // ListFolder returns the resource infos for all children of the referenced resource 48 ListFolder(ctx context.Context, ref *provider.Reference, mdKeys, fieldMask []string) ([]*provider.ResourceInfo, error) 49 // Download returns a ReadCloser for the content of the referenced resource 50 Download(ctx context.Context, ref *provider.Reference, openReaderfunc func(*provider.ResourceInfo) bool) (*provider.ResourceInfo, io.ReadCloser, error) 51 52 // GetPathByID returns the path for the given resource id relative to the space root 53 // It should only reveal the path visible to the current user to not leak the names uf unshared parent resources 54 // FIXME should be deprecated in favor of calls to GetMD and the fieldmask 'path' 55 GetPathByID(ctx context.Context, id *provider.ResourceId) (string, error) 56 57 // Functions for a writeable storage space 58 59 // CreateReference creates a resource of type reference 60 CreateReference(ctx context.Context, path string, targetURI *url.URL) error 61 // CreateDir creates a resource of type container 62 CreateDir(ctx context.Context, ref *provider.Reference) error 63 // TouchFile sets the mtime of a resource, creating an empty file if it does not exist 64 // FIXME the markprocessing flag is an implementation detail of decomposedfs, remove it from the function 65 // FIXME the mtime should either be a time.Time or a CS3 Timestamp, not a string 66 TouchFile(ctx context.Context, ref *provider.Reference, markprocessing bool, mtime string) error 67 // Delete deletes a resource. 68 // If the storage driver supports a recycle bin it should moves it to the recycle bin 69 Delete(ctx context.Context, ref *provider.Reference) error 70 // Move changes the path of a resource 71 Move(ctx context.Context, oldRef, newRef *provider.Reference) error 72 // InitiateUpload returns a list of protocols with urls that can be used to append bytes to a new upload session 73 InitiateUpload(ctx context.Context, ref *provider.Reference, uploadLength int64, metadata map[string]string) (map[string]string, error) 74 // Upload creates or updates a resource of type file with a new revision 75 Upload(ctx context.Context, req UploadRequest, uploadFunc UploadFinishedFunc) (*provider.ResourceInfo, error) 76 77 // Revisions 78 79 // ListRevisions lists all revisions for the referenced resource 80 ListRevisions(ctx context.Context, ref *provider.Reference) ([]*provider.FileVersion, error) 81 // DownloadRevision downloads a revision 82 DownloadRevision(ctx context.Context, ref *provider.Reference, key string, openReaderFunc func(md *provider.ResourceInfo) bool) (*provider.ResourceInfo, io.ReadCloser, error) 83 // RestoreRevision restores a revision 84 RestoreRevision(ctx context.Context, ref *provider.Reference, key string) error 85 86 // Recyce bin 87 88 // ListRecycle lists the content of the recycle bin 89 ListRecycle(ctx context.Context, ref *provider.Reference, key, relativePath string) ([]*provider.RecycleItem, error) 90 // RestoreRecycleItem restores an item from the recyle bin 91 // if restoreRef is nil the resource should be restored at the original path 92 RestoreRecycleItem(ctx context.Context, ref *provider.Reference, key, relativePath string, restoreRef *provider.Reference) error 93 // PurgeRecycleItem removes a resource from the recycle bin 94 PurgeRecycleItem(ctx context.Context, ref *provider.Reference, key, relativePath string) error 95 // EmptyRecycle removes all resource from the recycle bin 96 EmptyRecycle(ctx context.Context, ref *provider.Reference) error 97 98 // Grants 99 100 // AddGrant adds a grant to a resource 101 AddGrant(ctx context.Context, ref *provider.Reference, g *provider.Grant) error 102 // DenyGrant marks a resource as denied for a recipient 103 // The resource and its children must be completely hidden for the recipient 104 DenyGrant(ctx context.Context, ref *provider.Reference, g *provider.Grantee) error 105 // RemoveGrant removes a grant from a resource 106 RemoveGrant(ctx context.Context, ref *provider.Reference, g *provider.Grant) error 107 // UpdateGrant updates a grant on a resource 108 UpdateGrant(ctx context.Context, ref *provider.Reference, g *provider.Grant) error 109 // ListGrants lists all grants on a resource 110 ListGrants(ctx context.Context, ref *provider.Reference) ([]*provider.Grant, error) 111 112 // Arbitrary Metadata 113 114 // SetArbitraryMetadata sets arbitraty metadata on a resource 115 SetArbitraryMetadata(ctx context.Context, ref *provider.Reference, md *provider.ArbitraryMetadata) error 116 // UnsetArbitraryMetadata removes arbitraty metadata from a resource 117 UnsetArbitraryMetadata(ctx context.Context, ref *provider.Reference, keys []string) error 118 119 // Locks 120 121 // GetLock returns an existing lock on the given reference 122 GetLock(ctx context.Context, ref *provider.Reference) (*provider.Lock, error) 123 // SetLock puts a lock on the given reference 124 SetLock(ctx context.Context, ref *provider.Reference, lock *provider.Lock) error 125 // RefreshLock refreshes an existing lock on the given reference 126 RefreshLock(ctx context.Context, ref *provider.Reference, lock *provider.Lock, existingLockID string) error 127 // Unlock removes an existing lock from the given reference 128 Unlock(ctx context.Context, ref *provider.Reference, lock *provider.Lock) error 129 130 // Spaces 131 132 // CreateStorageSpace creates a storage space 133 CreateStorageSpace(ctx context.Context, req *provider.CreateStorageSpaceRequest) (*provider.CreateStorageSpaceResponse, error) 134 // UpdateStorageSpace updates a storage space 135 UpdateStorageSpace(ctx context.Context, req *provider.UpdateStorageSpaceRequest) (*provider.UpdateStorageSpaceResponse, error) 136 // DeleteStorageSpace deletes a storage space 137 DeleteStorageSpace(ctx context.Context, req *provider.DeleteStorageSpaceRequest) error 138 139 // CreateHome creates a users home 140 // Deprecated: use CreateStorageSpace with type personal 141 CreateHome(ctx context.Context) error 142 // GetHome returns the path to the users home 143 // Deprecated: use ListStorageSpaces with type personal 144 GetHome(ctx context.Context) (string, error) 145 } 146 147 // UnscopeFunc is a function that unscopes a user 148 type UnscopeFunc func() 149 150 // Composable is the interface that a struct needs to implement 151 // to be composable, so that it can support the TUS methods 152 type ComposableFS interface { 153 UseIn(composer *tusd.StoreComposer) 154 } 155 156 // Registry is the interface that storage registries implement 157 // for discovering storage providers 158 type Registry interface { 159 // GetProvider returns the Address of the storage provider that should be used for the given space. 160 // Use it to determine where to create a new storage space. 161 GetProvider(ctx context.Context, space *provider.StorageSpace) (*registry.ProviderInfo, error) 162 // ListProviders returns the storage providers that match the given filter 163 ListProviders(ctx context.Context, filters map[string]string) ([]*registry.ProviderInfo, error) 164 } 165 166 // PathWrapper is the interface to implement for path transformations 167 type PathWrapper interface { 168 Unwrap(ctx context.Context, rp string) (string, error) 169 Wrap(ctx context.Context, rp string) (string, error) 170 }