These are the canonical error codes used by CS3 APIs.
Adapted from Google APIs:
https://github.com/googleapis/googleapis/
Sometimes multiple error codes may apply. Services should return
the most specific error code that applies. For example, prefer
`OUT_OF_RANGE` over `FAILED_PRECONDITION` if both codes apply.
Similarly prefer `NOT_FOUND` or `ALREADY_EXISTS` over `FAILED_PRECONDITION`.
| Name | Number | Description |
| CODE_INVALID | 0 | A programmer would not intentionally set the code to CODE_INVALID. This code exists to force service implementors to set a specific code for the API call and to not rely on defaults. HTTP Mapping: 500 Internal Server Error |
| CODE_OK | 1 | Not an error; returned on success HTTP Mapping: 200 OK |
| CODE_CANCELLED | 2 | The operation was cancelled, typically by the caller. HTTP Mapping: 499 Client Closed Request |
| CODE_UNKNOWN | 3 | Unknown error. For example, this error may be returned when a `Status` value received from another address space belongs to an error space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error. HTTP Mapping: 500 Internal Server Error |
| CODE_INVALID_ARGUMENT | 4 | The client specified an invalid argument. Note that this differs from `FAILED_PRECONDITION`. `INVALID_ARGUMENT` indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name). HTTP Mapping: 400 Bad Request |
| CODE_DEADLINE_EXCEEDED | 5 | The deadline expired before the operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. HTTP Mapping: 504 Gateway Timeout |
| CODE_NOT_FOUND | 6 | Some requested entity (e.g., file or directory) was not found. Note to server developers: if a request is denied for an entire class of users, such as gradual feature rollout or undocumented whitelist, `NOT_FOUND` may be used. If a request is denied for some users within a class of users, such as user-based access control, `PERMISSION_DENIED` must be used. HTTP Mapping: 404 Not Found |
| CODE_ALREADY_EXISTS | 7 | The entity that a client attempted to create (e.g., file or directory) already exists. HTTP Mapping: 409 Conflict |
| CODE_PERMISSION_DENIED | 8 | The caller does not have permission to execute the specified operation. `PERMISSION_DENIED` must not be used for rejections caused by exhausting some resource (use `RESOURCE_EXHAUSTED` instead for those errors). `PERMISSION_DENIED` must not be used if the caller can not be identified (use `UNAUTHENTICATED` instead for those errors). This error code does not imply the request is valid or the requested entity exists or satisfies other pre-conditions. HTTP Mapping: 403 Forbidden |
| CODE_UNAUTHENTICATED | 9 | The request does not have valid authentication credentials for the operation. HTTP Mapping: 401 Unauthorized |
| CODE_RESOURCE_EXHAUSTED | 10 | Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. HTTP Mapping: 429 Too Many Requests |
| CODE_FAILED_PRECONDITION | 11 | The operation was rejected because the system is not in a state required for the operation's execution. For example, the directory to be deleted is non-empty, an rmdir operation is applied to a non-directory, etc. Service implementors can use the following guidelines to decide between `FAILED_PRECONDITION`, `ABORTED`, and `UNAVAILABLE`: (a) Use `UNAVAILABLE` if the client can retry just the failing call. (b) Use `ABORTED` if the client should retry at a higher level (e.g., when a client-specified test-and-set fails, indicating the client should restart a read-modify-write sequence). (c) Use `FAILED_PRECONDITION` if the client should not retry until the system state has been explicitly fixed. E.g., if an "rmdir" fails because the directory is non-empty, `FAILED_PRECONDITION` should be returned since the client should not retry unless the files are deleted from the directory. HTTP Mapping: 400 Bad Request |
| CODE_ABORTED | 12 | The operation was aborted, typically due to a concurrency issue such as a sequencer check failure or transaction abort. See the guidelines above for deciding between `FAILED_PRECONDITION`, `ABORTED`, and `UNAVAILABLE`. HTTP Mapping: 409 Conflict |
| CODE_OUT_OF_RANGE | 13 | The operation was attempted past the valid range. E.g., seeking or reading past end-of-file. Unlike `INVALID_ARGUMENT`, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate `INVALID_ARGUMENT` if asked to read at an offset that is not in the range [0,2^32-1], but it will generate `OUT_OF_RANGE` if asked to read from an offset past the current file size. There is a fair bit of overlap between `FAILED_PRECONDITION` and `OUT_OF_RANGE`. We recommend using `OUT_OF_RANGE` (the more specific error) when it applies so that callers who are iterating through a space can easily look for an `OUT_OF_RANGE` error to detect when they are done. HTTP Mapping: 400 Bad Request |
| CODE_UNIMPLEMENTED | 14 | The operation is not implemented or is not supported/enabled in this service. HTTP Mapping: 501 Not Implemented |
| CODE_INTERNAL | 15 | Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors. HTTP Mapping: 500 Internal Server Error |
| CODE_UNAVAILABLE | 16 | The service is currently unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff. See the guidelines above for deciding between `FAILED_PRECONDITION`, `ABORTED`, and `UNAVAILABLE`. HTTP Mapping: 503 Service Unavailable |
| CODE_DATA_LOSS | 17 | Unrecoverable data loss or corruption. HTTP Mapping: 500 Internal Server Error |
| CODE_REDIRECTION | 18 | Redirects the operation to another location. Used in a Status reponse with a reference to the target URI. |
The `Status` message contains two pieces of data: error code and error message.
The error code should be an enum value of [cs3.rpc.code].
The error message should be a developer-facing English
message that helps developers *understand* and *resolve* the error.
| Field | Type | Label | Description |
| code | Code | REQUIRED. The status code, which should be an enum value of [cs3.rpc.code][cs3.rpc.code]. |
|
| message | string | OPTIONAL. A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the |
|
| trace | string | OPTIONAL. A trace added to the response for helping support to identify client problems. |
|
| target_uri | string | OPTIONAL. A target URI as per RFC3986 to redirect requests to another location. A Status message with CODE_REDIRECT MUST always set the target_uri. https://golang.org/pkg/net/url/#URL provides a quick view of the format. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information (containing storage-specific information). For example, additional metadata attached to the resource. |
|
| provider_id | string | REQUIRED. The storage provider id that will become part of the resource id. For example, if the provider_id is "home", resources obtained from this storage provider will have a resource id like "home:1234". |
|
| provider_path | string | REQUIRED. The public path prefix this storage provider handles. In Unix literature, the mount path. For example, if the provider_path is "/home", resources obtained from this storage provier will have a resource path lik "/home/docs". |
|
| address | string | REQUIRED. The address where the storage provider can be reached. For example, tcp://localhost:1099. |
|
| description | string | OPTIONAL. Information to describe the functionalities offered by the storage provider. Meant to be read by humans. |
|
| features | ProviderInfo.Features | REQUIRED. List of available methods. |
REQUIRED.
Represents the list of features available
on this storage provider. If the feature is not supported,
the related service methods MUST return CODE_UNIMPLEMENTED.
| Field | Type | Label | Description |
| recycle | bool |
|
|
| file_versions | bool |
|
Opaque represents opaque information
in a form on a map.
For example, a local filesystem can
use this message to include filesystem
extended attributes.
| Field | Type | Label | Description |
| map | Opaque.MapEntry | repeated | REQUIRED. |
| Field | Type | Label | Description |
| key | string |
|
|
| value | OpaqueEntry |
|
OpaqueEntry represents the encoded
opaque value.
| Field | Type | Label | Description |
| decoder | string | REQUIRED. The decoder to use: json, xml, toml, ... TODO(labkode): make encoder a fixed set using a enum type? |
|
| value | bytes | REQUIRED. The encoded value. |
Adapted from Google google/protobuf/timestamp.proto.
A Timestamp represents a point in time independent of any time zone or local
calendar, encoded as a count of seconds and fractions of seconds at
nanosecond resolution. The count is relative to an epoch at UTC midnight on
January 1, 1970, in the proleptic Gregorian calendar which extends the
Gregorian calendar backwards to year one.
The range MUST be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.
Restricting to this range ensures the conversion from and to [RFC
3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.
| Field | Type | Label | Description |
| seconds | uint64 | Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive. |
|
| nanos | uint32 | Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Value MUST be from 0 to 999,999,999 inclusive. |
A UserId represents a user.
| Field | Type | Label | Description |
| idp | string | REQUIRED. The identity provider for the user. |
|
| opaque_id | string | REQUIRED. the unique identifier for the user in the scope of the identity provider. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| resource_info | cs3.storageproviderv0alpha.ResourceInfo | REQUIRED. The resource information. |
|
| access_token | string | REQUIRED. The access token this application provider will use when contacting the storage provider to read and write. Service implementors MUST make sure that the access token only grants access to the requested resource. Service implementors should use a ResourceId rather than a filename to grant access, as ResourceIds MUST NOT change when a resource is renamed. The access token MUST be short-lived. TODO(labkode): investigate token derivation techniques. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| iframe_url | string | REQUIRED. The url that user agents will render to clients. Usually the rendering happens by using HTML iframes, at least, Office 365, Collabora, OnlyOffice do like that. |
App Provider API
The App Provider API is responsible for creating urls that
will render a viewer or editor for the given resource.
For example, an OnlyOffice or HackMD editor.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
The following are global requirements that apply to all methods:
Any method MUST return CODE_OK on a succesful operation.
Any method MAY return NOT_IMPLEMENTED.
Any method MAY return INTERNAL.
Any method MAY return UNKNOWN.
Any method MAY return UNAUTHENTICATED.
| Method Name | Request Type | Response Type | Description |
| Open | OpenRequest | OpenResponse | Returns the iframe url MUST return CODE_NOT_FOUND if the resource does not exist. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| resource_info | cs3.storageproviderv0alpha.ResourceInfo | REQUIRED. The resource information. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| providers | ProviderInfo | repeated | REQUIRED. The app providers available for the given resource info. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. TODO(labkode): maybe add some filter? |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| providers | ProviderInfo | repeated | REQUIRED. The list of app providers this registry knows about. |
App Registry API
The App Registry API is meant to as registry that
contains mappings between mime types and app providers.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
The following are global requirements that apply to all methods:
Any method MUST return CODE_OK on a succesful operation.
Any method MAY return NOT_IMPLEMENTED.
Any method MAY return INTERNAL.
Any method MAY return UNKNOWN.
Any method MAY return UNAUTHENTICATED.
| Method Name | Request Type | Response Type | Description |
| GetAppProviders | GetAppProvidersRequest | GetAppProvidersResponse | Returns the app providers that are capable of handling this resource info. MUST return CODE_NOT_FOUND if no providers are available. |
| ListAppProviders | ListAppProvidersRequest | ListAppProvidersResponse | Returns a list of the available app providers known by this registry. |
Represents the information of the app provider.
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| mime_types | string | repeated | REQUIRED. The mimetypes handled by this provider. |
| address | string | REQUIRED. The address where the app provider can be reached. For example, tcp://localhost:1099. |
|
| description | string | OPTIONAL. Information to describe the functionalities offered by the app provider. Meant to be read by humans. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque |
|
|
| client_id | string |
|
|
| client_secret | string |
|
| Field | Type | Label | Description |
| status | cs3.rpc.Status |
|
|
| user_id | cs3.types.UserId |
|
| Method Name | Request Type | Response Type | Description |
| Authenticate | AuthenticateRequest | AuthenticateResponse |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| type | string | REQUIRED. The type of authentication provider. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| provider | ProviderInfo | REQUIRED. The auth provider handling the requested auth call. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. TODO(labkode): maybe add some filter? |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| providers | ProviderInfo | repeated | REQUIRED. The list of auth providers this registry knows about. |
Auth Registry API
The Auth Registry API is meant to as registry to obtain
information of available auth providers.
For example, to use OIDC or Kerberos for authentication.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
The following are global requirements that apply to all methods:
Any method MUST return CODE_OK on a succesful operation.
Any method MAY return NOT_IMPLEMENTED.
Any method MAY return INTERNAL.
Any method MAY return UNKNOWN.
Any method MAY return UNAUTHENTICATED.
| Method Name | Request Type | Response Type | Description |
| GetAuthProvider | GetAuthProviderRequest | GetAuthProviderResponse | Returns the auth provider that is reponsible for the given resource reference. MUST return CODE_NOT_FOUND if the reference does not exist. |
| ListAuthProviders | ListAuthProvidersRequest | ListAuthProvidersResponse | Returns a list of the available auth providers known by this registry. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information (containing storage-specific information). For example, additional metadata attached to the resource. |
|
| provider_type | string | REQUIRED. The storage provider id that will become part of the resource id. For example, if the provider_id is "home", resources obtained from this storage provider will have a resource id like "home:1234". |
|
| address | string | REQUIRED. The address where the storage provider can be reached. For example, tcp://localhost:1099. |
|
| description | string | OPTIONAL. Information to describe the functionalities offered by the storage provider. Meant to be read by humans. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| type | string | REQUIRED. The type of authentication to use. |
|
| client_id | string | OPTIONAL. The id of the client. For basic authentication with username and password both client_id and client_secret are expected to be filled. However, for example, for OIDC only a token is necessary. |
|
| client_secret | string | OPTIONAL. The secret of the client. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| token | string | REQUIRED. The access token. |
|
| user_id | cs3.types.UserId | REQUIRED. The user id. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | cs3.storageproviderv0alpha.Reference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| download_endpoint | string | REQUIRED. The endpoint where to downooad the data. The value MUST be a Uniform Resource Identifier (URI) as specified in RFC 3986. |
|
| expose | bool | REQUIRED. Tells to the gateway if the client should be exposed directly to the download_endpoint. |
|
| token | string | OPTIONAL. A token that MUST be validated by the data gateway for the upload. Only makes sense for uploads passing through the data gateway. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| upload_endpoint | string | REQUIRED. The endpoint where to upload the data. The value MUST be a Uniform Resource Identifier (URI) as specified in RFC 3986. |
|
| available_checksums | cs3.storageproviderv0alpha.ResourceChecksumPriority | repeated | REQUIRED. List of available checksums the client can use when sending the file. |
| token | string | OPTIONAL. A token that MUST be validated by the data gateway for the upload. Only makes sense for uploads passing through the data gateway. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| types | string | repeated | REQUIRED. The list of auth types. TODO(labkode): maybe add description? |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | cs3.storageproviderv0alpha.Reference | REQUIRED. The reference to which the action should be performed. |
|
| from_ts | cs3.types.Timestamp | OPTIONAL. SHOULD be specified. The start time range to query for recycle items. The value is the Unix Epoch timestamp in seconds. |
|
| to_ts | cs3.types.Timestamp | OPTIONAL. SHOULD be specified. The end time range to query for recycle items. The value is Unix Epoch timestamp in seconds. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | cs3.storageproviderv0alpha.Reference | REQUIRED. The reference to which the action should be performed. |
|
| from_ts | cs3.types.Timestamp | OPTIONAL. SHOULD be specified. The start time range to query for recycle items. The value is the Unix Epoch timestamp in seconds. |
|
| to_ts | cs3.types.Timestamp | OPTIONAL. SHOULD be specified. The end time range to query for recycle items. The value is Unix Epoch timestamp in seconds. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | cs3.storageproviderv0alpha.Reference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| token | string | REQUIRED. The access token. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| user | cs3.userproviderv0alpha.User | REQUIRED. The user information. |
Gateway API
The Gateway API is the only API exposed direclty to end-clients.
It is a facade API that all clients should connect to.
Other APIS like the StorageProviderAPI are internal APIS.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
The following are global requirements that apply to all methods:
Any method MUST return CODE_OK on a succesful operation.
Any method MAY return NOT_IMPLEMENTED.
Any method MAY return INTERNAL.
Any method MAY return UNKNOWN.
Any method MAY return UNAUTHENTICATED.
| Method Name | Request Type | Response Type | Description |
| Authenticate | AuthenticateRequest | AuthenticateResponse | AUTH ******** **************************/ *****************************************************************/ |
| WhoAmI | WhoAmIRequest | WhoAmIResponse | |
| CreateContainer | .cs3.storageproviderv0alpha.CreateContainerRequest | .cs3.storageproviderv0alpha.CreateContainerResponse | STORAGE PROVIDER ***********************/ *****************************************************************/ Creates a new resource of type container. MUST return CODE_PRECONDITION_FAILED if the container cannot be created at the specified reference. |
| Delete | .cs3.storageproviderv0alpha.DeleteRequest | .cs3.storageproviderv0alpha.DeleteResponse | Deletes a resource. If a resource specifies the non-empty container (directory, ...), then the entire directory is deleted recursively. If a resource specifies a reference or symlink type, only the reference is removed (not the target). MUST return CODE_NOT_FOUND if the reference does not exist. |
| GetPath | .cs3.storageproviderv0alpha.GetPathRequest | .cs3.storageproviderv0alpha.GetPathResponse | Returns the path reference for the provided resource id reference. MUST return CODE_NOT_FOUND if the reference does not exist |
| GetQuota | GetQuotaRequest | .cs3.storageproviderv0alpha.GetQuotaResponse | Returns the quota available under the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist MUST return CODE_RESOURCE_EXHAUSTED on exceeded quota limits. |
| InitiateFileDownload | .cs3.storageproviderv0alpha.InitiateFileDownloadRequest | InitiateFileDownloadResponse | Initiates the download of a file using an out-of-band data transfer mechanism. |
| InitiateFileUpload | .cs3.storageproviderv0alpha.InitiateFileUploadRequest | InitiateFileUploadResponse | Initiates the upload of a file using an out-of-band data transfer mechanism. |
| ListContainerStream | .cs3.storageproviderv0alpha.ListContainerStreamRequest | .cs3.storageproviderv0alpha.ListContainerStreamResponse stream | Returns a stream of resource informations for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exists. |
| ListContainer | .cs3.storageproviderv0alpha.ListContainerRequest | .cs3.storageproviderv0alpha.ListContainerResponse | Returns a list of resource information for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exists. |
| ListFileVersions | .cs3.storageproviderv0alpha.ListFileVersionsRequest | .cs3.storageproviderv0alpha.ListFileVersionsResponse | Returns a list of the versions for a resource of type file at the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist. MUST return CODE_OK and MUST return an empty list if no versions are available. TODO: What code if resource not of type file? |
| ListRecycleStream | ListRecycleStreamRequest | .cs3.storageproviderv0alpha.ListRecycleStreamResponse stream | Returns a stream of recycle items for this storage provider. |
| ListRecycle | ListRecycleRequest | .cs3.storageproviderv0alpha.ListRecycleResponse | Returns a list of recycle items for this storage provider. MUST return CODE_OK and MUST return an empty list if no recycle items are available. |
| Move | .cs3.storageproviderv0alpha.MoveRequest | .cs3.storageproviderv0alpha.MoveResponse | Moves a resource from one reference to another. MUST return CODE_NOT_FOUND if any of the references do not exist. MUST return CODE_PRECONDITION_FAILED if the source reference cannot be moved to the destination reference. |
| PurgeRecycle | PurgeRecycleRequest | .cs3.storageproviderv0alpha.PurgeRecycleResponse | Permanently removes a recycle item from the recycle. This operation is irrevocable. MUST return CODE_NOT_FOUND if the recycle item id does not exist. |
| RestoreFileVersion | .cs3.storageproviderv0alpha.RestoreFileVersionRequest | .cs3.storageproviderv0alpha.RestoreFileVersionResponse | Restores a file version for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist. MUST return CODE_NOT_FOUND if the version does not exist. |
| RestoreRecycleItem | .cs3.storageproviderv0alpha.RestoreRecycleItemRequest | .cs3.storageproviderv0alpha.RestoreRecycleItemResponse | Restores a recycle item from the recycle. MUST return CODE_NOT_FOUND if the recycle item id does not exist. MUST return CODE_PRECONDITION_FAILED if the restore_path is non-empty and the recycle item cannot be restored to the restore_path. |
| Stat | .cs3.storageproviderv0alpha.StatRequest | .cs3.storageproviderv0alpha.StatResponse | Returns the resource information at the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist. |
| SetArbitraryMetadata | .cs3.storageproviderv0alpha.SetArbitraryMetadataRequest | .cs3.storageproviderv0alpha.SetArbitraryMetadataResponse | Sets arbitrary metadata into a storage resource. Arbitrary metadata is returned in a cs3.storageproviderv0alpha.ResourceInfo. |
| UnsetArbitraryMetadata | .cs3.storageproviderv0alpha.UnsetArbitraryMetadataRequest | .cs3.storageproviderv0alpha.UnsetArbitraryMetadataResponse | Unsets arbitrary metdata into a storage resource. Arbitrary metadata is returned in a cs3.storageproviderv0alpha.ResourceInfo. |
| CreateShare | .cs3.usershareproviderv0alpha.CreateShareRequest | .cs3.usershareproviderv0alpha.CreateShareResponse | USER SHARE PROVIDER ********************/ *****************************************************************/ Creates a new share. MUST return CODE_NOT_FOUND if the resource reference does not exist. MUST return CODE_ALREADY_EXISTS if the share already exists for the 4-tuple consisting of (owner, shared_resource, grantee). New shares MUST be created in the state SHARE_STATE_PENDING. |
| RemoveShare | .cs3.usershareproviderv0alpha.RemoveShareRequest | .cs3.usershareproviderv0alpha.RemoveShareResponse | Removes a share. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| GetShare | .cs3.usershareproviderv0alpha.GetShareRequest | .cs3.usershareproviderv0alpha.GetShareResponse | Gets share information for a single share. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| ListShares | .cs3.usershareproviderv0alpha.ListSharesRequest | .cs3.usershareproviderv0alpha.ListSharesResponse | List the shares the authproviderenticated principal has created, both as owner and creator. If a filter is specified, only shares satisfying the filter MUST be returned. |
| UpdateShare | .cs3.usershareproviderv0alpha.UpdateShareRequest | .cs3.usershareproviderv0alpha.UpdateShareResponse | Updates a share. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| ListReceivedShares | .cs3.usershareproviderv0alpha.ListReceivedSharesRequest | .cs3.usershareproviderv0alpha.ListReceivedSharesResponse | List all shares the authproviderenticated principal has received. |
| UpdateReceivedShare | .cs3.usershareproviderv0alpha.UpdateReceivedShareRequest | .cs3.usershareproviderv0alpha.UpdateReceivedShareResponse | Update the received share to change the share state or the display name. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| GetReceivedShare | .cs3.usershareproviderv0alpha.GetReceivedShareRequest | .cs3.usershareproviderv0alpha.GetReceivedShareResponse | Get the information for the given received share reference. MUST return CODE_NOT_FOUND if the received share reference does not exist. |
| SetKey | .cs3.preferencesv0alpha.SetKeyRequest | .cs3.preferencesv0alpha.SetKeyResponse | PREFERENCES ***************************/ *****************************************************************/ Maps the key-value pair. |
| GetKey | .cs3.preferencesv0alpha.GetKeyRequest | .cs3.preferencesv0alpha.GetKeyResponse | Returns the value associated with the requested key. |
| CreatePublicShare | .cs3.publicshareproviderv0alpha.CreatePublicShareRequest | .cs3.publicshareproviderv0alpha.CreatePublicShareResponse | PUBLIC SHARE ***************************/ *****************************************************************/ Creates a new share. MUST return CODE_NOT_FOUND if the resource reference does not exist. MUST return CODE_ALREADY_EXISTS if the share already exists for the 4-tuple consisting of (owner, shared_resource, grantee). New shares MUST be created in the state SHARE_STATE_PENDING. |
| RemovePublicShare | .cs3.publicshareproviderv0alpha.RemovePublicShareRequest | .cs3.publicshareproviderv0alpha.RemovePublicShareResponse | Removes a share. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| GetPublicShare | .cs3.publicshareproviderv0alpha.GetPublicShareRequest | .cs3.publicshareproviderv0alpha.GetPublicShareResponse | Gets share information for a single share. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| GetPublicShareByToken | .cs3.publicshareproviderv0alpha.GetPublicShareByTokenRequest | .cs3.publicshareproviderv0alpha.GetPublicShareByTokenResponse | Gets share information for a single share by its unlisted token. MUST return CODE_NOT_FOUND if the share does not exist. |
| ListPublicShares | .cs3.publicshareproviderv0alpha.ListPublicSharesRequest | .cs3.publicshareproviderv0alpha.ListPublicSharesResponse | List the shares the authproviderenticated principal has created, both as owner and creator. If a filter is specified, only shares satisfying the filter MUST be returned. |
| UpdatePublicShare | .cs3.publicshareproviderv0alpha.UpdatePublicShareRequest | .cs3.publicshareproviderv0alpha.UpdatePublicShareResponse | Updates a share. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| CreateOCMShare | .cs3.ocmshareproviderv0alpha.CreateOCMShareRequest | .cs3.ocmshareproviderv0alpha.CreateOCMShareResponse | OCM SHARE PROVIDER *********************/ *****************************************************************/ Creates a new ocm share. MUST return CODE_NOT_FOUND if the resource reference does not exist. MUST return CODE_ALREADY_EXISTS if the share already exists for the 4-tuple consisting of (owner, shared_resource, grantee). New shares MUST be created in the state SHARE_STATE_PENDING. |
| RemoveOCMShare | .cs3.ocmshareproviderv0alpha.RemoveOCMShareRequest | .cs3.ocmshareproviderv0alpha.RemoveOCMShareResponse | Removes a share. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| GetOCMShare | .cs3.ocmshareproviderv0alpha.GetOCMShareRequest | .cs3.ocmshareproviderv0alpha.GetOCMShareResponse | Gets share information for a single share. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| ListOCMShares | .cs3.ocmshareproviderv0alpha.ListOCMSharesRequest | .cs3.ocmshareproviderv0alpha.ListOCMSharesResponse | List the shares the authproviderenticated principal has created, both as owner and creator. If a filter is specified, only shares satisfying the filter MUST be returned. |
| UpdateOCMShare | .cs3.ocmshareproviderv0alpha.UpdateOCMShareRequest | .cs3.ocmshareproviderv0alpha.UpdateOCMShareResponse | Updates a share. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| ListReceivedOCMShares | .cs3.ocmshareproviderv0alpha.ListReceivedOCMSharesRequest | .cs3.ocmshareproviderv0alpha.ListReceivedOCMSharesResponse | List all shares the authproviderenticated principal has received. |
| UpdateReceivedOCMShare | .cs3.ocmshareproviderv0alpha.UpdateReceivedOCMShareRequest | .cs3.ocmshareproviderv0alpha.UpdateReceivedOCMShareResponse | Update the received share to change the share state or the display name. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| GetAppProviders | .cs3.appregistryv0alpha.GetAppProvidersRequest | .cs3.appregistryv0alpha.GetAppProvidersResponse | APP REGISTRY ****************************/ *****************************************************************/ Returns the app providers that are capable of handling this resource info. MUST return CODE_NOT_FOUND if no providers are available. |
| ListAppProviders | .cs3.appregistryv0alpha.ListAppProvidersRequest | .cs3.appregistryv0alpha.ListAppProvidersResponse | Returns a list of the available app providers known by this registry. |
| GetUser | .cs3.userproviderv0alpha.GetUserRequest | .cs3.userproviderv0alpha.GetUserResponse | USER PROVIDER **************************/ *****************************************************************/ Gets the information about an user by its user id. |
| GetUserGroups | .cs3.userproviderv0alpha.GetUserGroupsRequest | .cs3.userproviderv0alpha.GetUserGroupsResponse | Gets the groups of a user. |
| IsInGroup | .cs3.userproviderv0alpha.IsInGroupRequest | .cs3.userproviderv0alpha.IsInGroupResponse | Tells if the user is in a certain group. |
| FindUsers | .cs3.userproviderv0alpha.FindUsersRequest | .cs3.userproviderv0alpha.FindUsersResponse | Finds users by any attribute of the user? TODO(labkode): to define the filters that make more sense. |
| ListAuthProviders | .cs3.authregistryv0alpha.ListAuthProvidersRequest | ListAuthProvidersResponse | AUTH REGISTRY **************************/ *****************************************************************/ Returns a list of the available auth providers known by this registry. |
| GetHome | .cs3.storageregistryv0alpha.GetHomeRequest | .cs3.storageregistryv0alpha.GetHomeResponse | STORAGE REGISTRY ** ********************/ *****************************************************************/ Returns the home path for the given authenticated user. When a user has access to multiple storage providers, one of them is the home. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| resource_id | cs3.storageproviderv0alpha.ResourceId | REQUIRED. The unique identifier for the shared storage resource. |
|
| grant | ShareGrant | REQUIRED. The share grant for the share. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| share | Share | REQUIRED. The created share. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | ShareReference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| share | Share | REQUIRED. The share. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| filters | ListOCMSharesRequest.Filter | repeated | OPTIONAL. The list of filters to apply if any. |
represents a filter to apply to the request.
| Field | Type | Label | Description |
| type | ListOCMSharesRequest.Filter.Type |
|
|
| resource_id | cs3.storageproviderv0alpha.ResourceId |
|
|
| owner | cs3.types.UserId |
|
|
| creator | cs3.types.UserId |
|
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| shares | Share | repeated | REQUIRED. The list of shares. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| shares | ReceivedShare | repeated | REQUIRED. The list of received shares. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | ShareReference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. REQUIRED. |
|
| ref | ShareReference |
|
|
| field | UpdateOCMShareRequest.UpdateField |
|
| Field | Type | Label | Description |
| permissions | SharePermissions | Update the permissions. |
|
| display_name | string | Update the display name. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
TODO(labkode): clean up display_name ? we'll use storage links for that.
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | ShareReference | REQUIRED. |
|
| field | UpdateReceivedOCMShareRequest.UpdateField |
|
| Field | Type | Label | Description |
| display_name | string | Update the display name. |
|
| state | ShareState | Update the share state |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Name | Number | Description |
| LIST_OCM_SHARES_REQUEST_FILTER_TYPE_INVALID | 0 | |
| LIST_OCM_SHARES_REQUEST_FILTER_TYPE_NO_FILTER | 1 | |
| LIST_OCM_SHARES_REQUEST_FILTER_TYPE_RESOURCE_ID | 2 | |
| LIST_OCM_SHARES_REQUEST_FILTER_TYPE_OWNER | 3 | |
| LIST_OCM_SHARES_REQUEST_FILTER_TYPE_CREATOR | 4 | |
| LIST_OCM_SHARES_REQUEST_FILTER_TYPE_OWNER_PROVIDER | 5 | |
| LIST_OCM_SHARES_REQUEST_FILTER_TYPE_CREATOR_PROVIDER | 6 |
OCM Share Provider API
The OCM Share Provider API is meant to manipulate share
resources from the perspective of the creator or the share and
from the perspective of the receiver of the share.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
The following are global requirements that apply to all methods:
Any method MUST return CODE_OK on a succesful operation.
Any method MAY return NOT_IMPLEMENTED.
Any method MAY return INTERNAL.
Any method MAY return UNKNOWN.
Any method MAY return UNAUTHENTICATED.
| Method Name | Request Type | Response Type | Description |
| CreateOCMShare | CreateOCMShareRequest | CreateOCMShareResponse | Creates a new ocm share. MUST return CODE_NOT_FOUND if the resource reference does not exist. MUST return CODE_ALREADY_EXISTS if the share already exists for the 4-tuple consisting of (owner, shared_resource, grantee). New shares MUST be created in the state SHARE_STATE_PENDING. |
| RemoveOCMShare | RemoveOCMShareRequest | RemoveOCMShareResponse | Removes a share. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| GetOCMShare | GetOCMShareRequest | GetOCMShareResponse | Gets share information for a single share. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| ListOCMShares | ListOCMSharesRequest | ListOCMSharesResponse | List the shares the authenticated principal has created, both as owner and creator. If a filter is specified, only shares satisfying the filter MUST be returned. |
| UpdateOCMShare | UpdateOCMShareRequest | UpdateOCMShareResponse | Updates a share. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| ListReceivedOCMShares | ListReceivedOCMSharesRequest | ListReceivedOCMSharesResponse | List all shares the authenticated principal has received. |
| UpdateReceivedOCMShare | UpdateReceivedOCMShareRequest | UpdateReceivedOCMShareResponse | Update the received share to change the share state or the display name. MUST return CODE_NOT_FOUND if the share reference does not exist. |
A received share is the share that a grantee will receive.
It expands the original share by adding state to the share,
a display name from the perspective of the grantee and a
resource mount path in case the share will be mounted
in a path in a storage provider.
| Field | Type | Label | Description |
| share | Share | REQUIRED. |
|
| state | ShareState | REQUIRED. The state of the share. |
Shares are relationships between a resource owner
(usually the authenticated user) who grants permissions to a recipient (grantee)
on a specified resource (resource_id). UserShares represents both user and groups.
| Field | Type | Label | Description |
| id | ShareId | REQUIRED. Opaque unique identifier of the share. |
|
| resource_id | cs3.storageproviderv0alpha.ResourceId | REQUIRED. Unique identifier of the shared resource. |
|
| permissions | SharePermissions | REQUIRED. Permissions for the grantee to use the resource. |
|
| grantee | cs3.storageproviderv0alpha.Grantee | REQUIRED. The receiver of the share, like a user, group ... |
|
| owner | cs3.types.UserId | REQUIRED. Uniquely identifies the owner of the share (the resource owner at the time of creating the share). In case the ownership of the underlying resource changes the share owner field MAY change to reflect the change of ownsership. |
|
| creator | cs3.types.UserId | REQUIRED. Uniquely identifies a principal who initiates the share creation. A creator can create shares on behalf of the owner (because of re-sharing, because belonging to special groups, ...). Creator and owner often result in being the same principal. |
|
| ctime | cs3.types.Timestamp | REQUIRED. Creation time of the share. |
|
| mtime | cs3.types.Timestamp | REQUIRED. Last modification time of the share. |
A share grant specifies the share permissions
for a grantee.
| Field | Type | Label | Description |
| grantee | cs3.storageproviderv0alpha.Grantee | REQUIRED. The grantee of the grant. |
|
| permissions | SharePermissions | REQUIRED. The share permissions for the grant. |
A share id identifies uniquely a // share in the share provider namespace.
A ShareId MUST be unique inside the share provider.
| Field | Type | Label | Description |
| opaque_id | string | REQUIRED. The internal id used by service implementor to uniquely identity the share in the internal implementation of the service. |
Uniquely identifies a share in the share provider.
A share MUST be uniquely identify by four (4) elements:
1) The share provider id
2) The owner of the share
3) The resource id
4) The grantee for the share
This 4-tuple MUST be unique.
For example, owner Alice shares the resource /home/docs with id
home:1234 to an user named Bob. The 4-tuple will consist of
1) The share provider id = "user"
2) The owner of the share = "Alice"
3) The resource id = "home:1234"
4) The grantee for the share = Grantee("type" = "user", "" => "Bob")
| Field | Type | Label | Description |
| owner | cs3.types.UserId | REQUIRED. |
|
| resource_id | cs3.storageproviderv0alpha.ResourceId | REQUIRED. |
|
| grantee | cs3.storageproviderv0alpha.Grantee | REQUIRED. |
The permissions for a share.
| Field | Type | Label | Description |
| permissions | cs3.storageproviderv0alpha.ResourcePermissions |
|
|
| reshare | bool |
|
The mechanism to identify a share
in the share provider namespace.
| Field | Type | Label | Description |
| id | ShareId | The id of the share. |
|
| key | ShareKey | The combination of fields that make the share unique. |
The state of the share.
| Name | Number | Description |
| SHARE_STATE_INVALID | 0 | The share is no longer valid, for example, the share expired. |
| SHARE_STATE_PENDING | 1 | New shares MUST be created in the SHARE_STATE_PENDING state. This state means the share is pending to be accepted or rejected by the recipient of the share. |
| SHARE_STATE_ACCEPTED | 2 | The recipient of the share has accepted the share. |
| SHARE_STATE_REJECTED | 3 | The recipient of the share has rejected the share. Do not means the share is removed, the recipient MAY change the state to accepted or pending. |
| Field | Type | Label | Description |
| key | string | REQUIRED. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| val | string | REQUIRED. The value associated with the key. |
| Field | Type | Label | Description |
| key | string | REQUIRED. |
|
| val | string | REQUIRED. The value associated with the key. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
Preferences API.
The Preferences API is responsible for creating
a key-value map according to user preferences.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
The following are global requirements that apply to all methods:
Any method MUST return CODE_OK on a succesful operation.
Any method MAY return NOT_IMPLEMENTED.
Any method MAY return INTERNAL.
Any method MAY return UNKNOWN.
Any method MAY return UNAUTHENTICATED.
| Method Name | Request Type | Response Type | Description |
| SetKey | SetKeyRequest | SetKeyResponse | Maps the key-value pair. |
| GetKey | GetKeyRequest | GetKeyResponse | Returns the value associated with the requested key. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| resource_info | cs3.storageproviderv0alpha.ResourceInfo | REQUIRED. The unique identifier for the shared storage resource. |
|
| grant | Grant | REQUIRED. The restrictions to apply to the share. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| share | PublicShare | REQUIRED. The created share. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| token | string | REQUIRED. The unlisted token to identify the public share. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| share | PublicShare | REQUIRED. The share. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | PublicShareReference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| share | PublicShare | REQUIRED. The share. |
Defines the restrictions for the public share;
| Field | Type | Label | Description |
| permissions | PublicSharePermissions | REQUIRED. The permissions for the share. |
|
| password | string | OPTIONAL. A password to protect the access to the public share. |
|
| expiration | cs3.types.Timestamp | OPTIONAL. An expiration date to protect the access to the public share. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| filters | ListPublicSharesRequest.Filter | repeated | OPTIONAL. The list of filters to apply if any. |
represents a filter to apply to the request.
| Field | Type | Label | Description |
| type | ListPublicSharesRequest.Filter.Type |
|
|
| resource_id | cs3.storageproviderv0alpha.ResourceId |
|
|
| owner | cs3.types.UserId |
|
|
| creator | cs3.types.UserId |
|
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| share | PublicShare | repeated | REQUIRED. The list of shares. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | PublicShareReference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. REQUIRED. |
|
| ref | PublicShareReference | REQUIRED. The reference to the public share. Available fields to update. |
| Field | Type | Label | Description |
| type | UpdatePublicShareRequest.Update.Type | REQUIRED. Defines the field to update |
|
| grant | Grant | REQUIRED. Contains the field that will be updated. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| share | PublicShare | REQUIRED. The updated public share. |
| Name | Number | Description |
| LIST_PUBLIC_SHARES_REQUEST_FILTER_TYPE_INVALID | 0 | |
| LIST_PUBLIC_SHARES_REQUEST_FILTER_TYPE_RESOURCE_ID | 1 | |
| LIST_PUBLIC_SHARES_REQUEST_FILTER_TYPE_OWNER | 2 | |
| LIST_PUBLIC_SHARES_REQUEST_FILTER_TYPE_CREATOR | 3 |
| Name | Number | Description |
| UPDATE_PUBLIC_SHARE_REQUEST_UPDATE_TYPE_INVALID | 0 | |
| UPDATE_PUBLIC_SHARE_REQUEST_UPDATE_TYPE_PERMISSIONS | 1 | |
| UPDATE_PUBLIC_SHARE_REQUEST_UPDATE_TYPE_PASSWORD | 2 | |
| UPDATE_PUBLIC_SHARE_REQUEST_UPDATE_TYPE_EXPIRATION | 3 |
PublicShare Provider API
The Public Share Provider API is meant to manipulate public shares
also called public links.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
The following are global requirements that apply to all methods:
Any method MUST return CODE_OK on a succesful operation.
Any method MAY return NOT_IMPLEMENTED.
Any method MAY return INTERNAL.
Any method MAY return UNKNOWN.
Any method MAY return UNAUTHENTICATED.
| Method Name | Request Type | Response Type | Description |
| CreatePublicShare | CreatePublicShareRequest | CreatePublicShareResponse | Creates a new share. MUST return CODE_NOT_FOUND if the resource reference does not exist. MUST return CODE_ALREADY_EXISTS if the share already exists for the 4-tuple consisting of (owner, shared_resource, grantee). New shares MUST be created in the state SHARE_STATE_PENDING. |
| RemovePublicShare | RemovePublicShareRequest | RemovePublicShareResponse | Removes a share. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| GetPublicShare | GetPublicShareRequest | GetPublicShareResponse | Gets share information for a single share. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| GetPublicShareByToken | GetPublicShareByTokenRequest | GetPublicShareByTokenResponse | Gets share information for a single share by its unlisted token. MUST return CODE_NOT_FOUND if the share does not exist. |
| ListPublicShares | ListPublicSharesRequest | ListPublicSharesResponse | List the shares the authenticated principal has created, both as owner and creator. If a filter is specified, only shares satisfying the filter MUST be returned. |
| UpdatePublicShare | UpdatePublicShareRequest | UpdatePublicShareResponse | Updates a share. MUST return CODE_NOT_FOUND if the share reference does not exist. |
Public share are relationships between a resource owner
(usually the authenticated user) who grants permissions to a recipient (grantee)
on a specified resource (resource_id). UserShares represents both user and groups.
TODO(labkode): do we need to have resource_type stored on the share?
This is not needed if when getting the shares a stat operation is launched against the
the storage provider.
| Field | Type | Label | Description |
| id | PublicShareId | REQUIRED. Opaque unique identifier of the share. |
|
| token | string | REQUIRED. The unlisted token to give public access to the public share. |
|
| resource_id | cs3.storageproviderv0alpha.ResourceId | REQUIRED. Unique identifier of the shared resource. |
|
| permissions | PublicSharePermissions | REQUIRED. Permissions for the grantee to use the resource. |
|
| owner | cs3.types.UserId | REQUIRED. Uniquely identifies the owner of the share (the resource owner at the time of creating the share). In case the ownership of the underlying resource changes the share owner field MAY change to reflect the change of ownsership. |
|
| creator | cs3.types.UserId | REQUIRED. Uniquely identifies a principal who initiates the share creation. A creator can create shares on behalf of the owner (because of re-sharing, because belonging to special groups, ...). Creator and owner often result in being the same principal. |
|
| ctime | cs3.types.Timestamp | REQUIRED. Creation time of the share. |
|
| mtime | cs3.types.Timestamp | REQUIRED. Last modification time of the share. |
|
| password_protected | bool | REQUIRED. Determines if the public share is password protected or not. |
|
| expiration | cs3.types.Timestamp | OPTIONAL. The expiration time for the public share. |
|
| display_name | string | OPTIONAL. Display name for the shared resource (such as file, directory basename or any user defined name). The display name MAY be different than the actual resource basename. This field is only useful for informational purposes, like for example, setting the window title in a public share HTML page. |
A share id identifies uniquely a // share in the share provider namespace.
A ShareId MUST be unique inside the share provider.
| Field | Type | Label | Description |
| opaque_id | string | REQUIRED. The internal id used by service implementor to uniquely identity the share in the internal implementation of the service. |
The permissions for a share.
| Field | Type | Label | Description |
| permissions | cs3.storageproviderv0alpha.ResourcePermissions | TODO(labkode): additional permissions for shares like re-sharing |
The mechanism to identify a share
in the share provider namespace.
| Field | Type | Label | Description |
| id | PublicShareId | The id of the share. |
|
| token | string | The token to identify the public share. |
| Field | Type | Label | Description |
| metadata | ArbitraryMetadata.MetadataEntry | repeated |
|
| Field | Type | Label | Description |
| key | string |
|
|
| value | string |
|
CanonicalMetadata contains extra metadata
attached to a resource. This message and the Opaque
message differ in that Opaque allows service implementors
to include any extra metadata in any format and most clients
will ignore it. However, the CanonicalMetadata message
contains well defined fileds that clients MUST understand if
they are specified.
| Field | Type | Label | Description |
| target | Reference | REQUIRED if resource type is RESOURCE_TYPE_REFERENCE. The target reference the resource points to. TODO(moscicki): what fields can fit here? executable bit? bool executable = 2; TODO(labkode): at some points maybe we could add here acls and other well-known metadata. |
The information for a file version.
TODO(labkode): make size and mtime OPTIONAL?
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| key | string | MUST the specified. The key to identify the version. |
|
| size | uint64 | REQUIRED. The size in bytes of the file version. |
|
| mtime | uint64 | REQUIRED. The Unix Epoch timestamp in seconds. |
A grant grants permissions
to a resource to a grantee.
| Field | Type | Label | Description |
| grantee | Grantee | REQUIRED. The grantee of the grant. |
|
| permissions | ResourcePermissions | REQUIRED. The permissions for the grant. |
A grantee is the receiver of a grant.
| Field | Type | Label | Description |
| type | GranteeType | REQUIRED. The type of the grantee. |
|
| id | cs3.types.UserId | The unique id for the grantee. For example, a group name, user name or uuid. |
A recycle item represents the information
of a deleted resource.
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| type | ResourceType | REQUIRED. The type of the resource. |
|
| key | string | REQUIRED. The key to identify the deleted resource. |
|
| path | string | REQUIRED. The original path of the deleted resource. |
|
| size | uint64 | OPTIONAL. The size of the deleted resource. |
|
| deletion_time | cs3.types.Timestamp | REQUIRED. The deletion time of the resource in Unix Epoch timestamp in seconds. |
The mechanism to identify a resource
in the storage provider namespace.
| Field | Type | Label | Description |
| path | string | The path to the resource. MUST start with the slash character (/). |
|
| id | ResourceId | The id for the resource. MUST NOT start with the slash character (/). |
The checksum to verify
the integrity of a resource.
| Field | Type | Label | Description |
| type | ResourceChecksumType | REQUIRED. The type of checksum to use. If no checksum is provided, type MUST be RESOURCE_CHECKSUM_TYPE_UNSET. |
|
| sum | string | MUST be specified if type is not RESOURCE_CHECKSUM_TYPE_UNSET or type is not RESOURCE_CHECKSUM_TYPE_INVALID. MUST be the hexadecimal representation of the cheksum. The value is case-insensitive, so "1E603A8", "1e603a8" or "1e603A8" are the same. |
When negotiating the user of checksum types
between client and server, this structure
defines the priority of the checksum.
Priority 0 means highest priority.
| Field | Type | Label | Description |
| type | ResourceChecksumType |
|
|
| priority | uint32 |
|
A resource id identifies uniquely a
resource in the storage provider namespace.
A ResourceId MUST be unique in the storage provider.
| Field | Type | Label | Description |
| storage_id | string | REQUIRED. The storage id of the storage provider. |
|
| opaque_id | string | REQUIRED. The internal id used by service implementor to uniquely identity the resource in the internal implementation of the service. |
Represents the information (metadata) about
a storage resource organized in a hierarchical namespace (file, directory/container, reference, symlink, ...).
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| type | ResourceType | REQUIRED. The type of the resource (container, file, ...) See the enum ResourceType for all possible types. |
|
| id | ResourceId | REQUIRED. Opaque unique identifier of the resource. |
|
| checksum | ResourceChecksum | REQUIRED. The data checksum for the file resource. For all other resources, the checksum is unset. |
|
| etag | string | REQUIRED. As decribed in https://tools.ietf.org/html/rfc7232#section-2.3 For file resources, the etag must change if data or metadata changes. For container types, the etag must change if etag of any of the (indirectly) contained resources change. For reference types, the etag must change if etag of the target changes and the target is on the same storage provider. In all other cases the etag does not change. |
|
| mime_type | string | REQUIRED. As described in [RFC 2015](https://tools.ietf.org/html/rfc2045#page-7) |
|
| mtime | cs3.types.Timestamp | REQUIRED. Last modification time (mtime) of file or directory contents. For reference types this is NOT the mtime of the target. |
|
| path | string | REQUIRED. The path for the resource. It MUST start with the slash character (/). |
|
| permission_set | ResourcePermissions | REQUIRED. The set of permissions for the resource effective for the authenticated user. |
|
| size | uint64 | REQUIRED. The size of the resource in bytes (file size) TODO(moscicki): This is undefined for container type. Is the accounting recursive?, could it be set to 0 for directories if recursive not supported? use another field? TODO(moscicki): This needs to be defined also for other types (such as a symlink to a directory or file) |
|
| owner | cs3.types.UserId | REQUIRED: Identifier of the owner of the resource. |
|
| canonical_metadata | CanonicalMetadata | OPTIONAL. Additional metadata attached to the resource. If resource type is RESOURCE_TYPE_REFERENCE it MUST be specified. |
|
| arbitrary_metadata | ArbitraryMetadata | OPTIONAL. Arbitrary metadata attached to a resource. |
The representation of permissions attached to a resource.
| Field | Type | Label | Description |
| add_grant | bool |
|
|
| create_container | bool |
|
|
| delete | bool |
|
|
| get_path | bool |
|
|
| get_quota | bool |
|
|
| initiate_file_download | bool |
|
|
| initiate_file_upload | bool |
|
|
| list_grants | bool |
|
|
| list_container | bool |
|
|
| list_file_versions | bool |
|
|
| list_recycle | bool |
|
|
| move | bool |
|
|
| remove_grant | bool |
|
|
| purge_recycle | bool |
|
|
| restore_file_version | bool |
|
|
| restore_recycle_item | bool |
|
|
| stat | bool |
|
|
| update_grant | bool |
|
The type of the grantee.
| Name | Number | Description |
| GRANTEE_TYPE_INVALID | 0 | |
| GRANTEE_TYPE_USER | 1 | This type represents an individual. |
| GRANTEE_TYPE_GROUP | 2 | This type represents a group of individuals. |
The type of checksum to use.
| Name | Number | Description |
| RESOURCE_CHECKSUM_TYPE_INVALID | 0 | |
| RESOURCE_CHECKSUM_TYPE_UNSET | 1 | unset means no checksum is set. |
| RESOURCE_CHECKSUM_TYPE_ADLER32 | 2 | Use Adler32 checksum. |
| RESOURCE_CHECKSUM_TYPE_MD5 | 3 | Use MD5 checksum. |
| RESOURCE_CHECKSUM_TYPE_SHA1 | 4 | Use SHA-1 checksum. |
The available types of resources.
| Name | Number | Description |
| RESOURCE_TYPE_INVALID | 0 | |
| RESOURCE_TYPE_FILE | 1 | The file type represents a type that holds arbitrary data. Service implementors usually map this type to files (local filesystem) or objects (Amazon S3). |
| RESOURCE_TYPE_CONTAINER | 2 | The container type represents a type that can contain another types. Service implementors usually map this type to folders (local filesystem) or buckets (Amazon S3). |
| RESOURCE_TYPE_REFERENCE | 3 | This represents a reference type which points to another resource where client MAY be redirected. Client SHOULD use the ResourceInfo.target reference for a subsequent call. |
| RESOURCE_TYPE_SYMLINK | 4 | This represents a symbolic link type if the underlying storage system supports it. Symlink target SHOULD NOT be interpreted by the clients. |
| RESOURCE_TYPE_INTERNAL | 5 | Internal resource type for some specific resources inside a storage implementation. For example, this type could be used to represent a device file on a Linux filesystem. Another example could be to represent an ongoing upload, where an hypothetically user interface could show a loading icon on this type of resources until the upload operation is completed. Internal resources SHOULD NOT be moved to a different storage provider. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | Reference | REQUIRED. The reference to which the action should be performed. |
|
| grant | Grant | REQUIRED. The grant to be added. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | Reference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| path | string | REQUIRED. The location where to store the reference. |
|
| target_uri | string | REQUIRED. The reference resource by RFC3986. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | Reference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| resource_id | ResourceId | REQUIRED. The resource id of the resource. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| path | string | REQUIRED. The path of the resource. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| info | cs3.storagetypes.ProviderInfo | REQUIRED. The information for the storage provider. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| total_bytes | uint64 | REQUIRED. The total available bytes. |
|
| used_bytes | uint64 | REQUIRED. The number of used bytes. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | Reference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| download_endpoint | string | REQUIRED. The endpoint where to downooad the data. The value MUST be a Uniform Resource Identifier (URI) as specified in RFC 3986. |
|
| expose | bool | REQUIRED. Tells to the gateway if the client should be exposed directly to the download_endpoint. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | Reference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| upload_endpoint | string | REQUIRED. The endpoint where to upload the data. The value MUST be a Uniform Resource Identifier (URI) as specified in RFC 3986. |
|
| available_checksums | ResourceChecksumPriority | repeated | REQUIRED. List of available checksums the client can use when sending the file. |
| expose | bool | REQUIRED. Tells to the gateway if the client should be exposed directly to the upload_endpoint. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | Reference | REQUIRED. The reference to which the action should be performed. |
|
| arbitrary_metadata_keys | string | repeated | OPTIONAL. Arbitrary metadata be included with the resource. A key with the name '*' means to return all available arbitrary metadata. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| infos | ResourceInfo | repeated | REQUIRED. The list of resource informations. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | Reference | REQUIRED. The reference to which the action should be performed. |
|
| arbitrary_metadata_keys | string | repeated | OPTIONAL. Arbitrary metadata be included with the resource. A key with the name '*' means to return all available arbitrary metadata. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| info | ResourceInfo | REQUIRED. The resource information. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | Reference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| versions | FileVersion | repeated | REQUIRED. The list of file versions. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | Reference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| grants | Grant | repeated | REQUIRED. The grants. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| from_ts | cs3.types.Timestamp | OPTIONAL. SHOULD be specified. The start time range to query for recycle items. The value is the Unix Epoch timestamp in seconds. |
|
| to_ts | cs3.types.Timestamp | OPTIONAL. SHOULD be specified. The end time range to query for recycle items. The value is Unix Epoch timestamp in seconds. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| recycle_items | RecycleItem | repeated | REQUIRED. The list of recycle items. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| from_ts | cs3.types.Timestamp | OPTIONAL. SHOULD be specified. The start time range to query for recycle items. The value is the Unix Epoch timestamp in seconds. |
|
| to_ts | cs3.types.Timestamp | OPTIONAL. SHOULD be specified. The end time range to query for recycle items. The value is Unix Epoch timestamp in seconds. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| recycle_item | RecycleItem | REQUIRED. The recycle items. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| source | Reference | REQUIRED. The source reference the resource is moved from. |
|
| destination | Reference | REQUIRED. The destination reference the resource is moved to. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | Reference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | Reference | REQUIRED. The reference to which the action should be performed. |
|
| grant | Grant | REQUIRED. The grant to remove. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | Reference | REQUIRED. The reference to which the action should be performed. |
|
| key | string | REQUIRED. The key to restore a specific file version. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
TODO: restore to original location if not specified as OPTIONAL?
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | Reference | REQUIRED. The reference to which the action should be performed. |
|
| key | string | REQUIRED. The key for the recycle item to be restored. |
|
| restore_path | string | OPTIONAL. An optional restore path for the deleted resource. It can be useful to restore to another location rather than the original. If empty, service implementors MUST restore to original location if possible. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | Reference | REQUIRED. The reference to which the action should be performed. |
|
| arbitrary_metadata | ArbitraryMetadata | REQUIRED. The arbitrary metadata to add to the resource. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | Reference | REQUIRED. The reference to which the action should be performed. |
|
| arbitrary_metadata_keys | string | repeated | OPTIONAL. Arbitrary metadata be included with the resource. A key with the name '*' means to return all available arbitrary metadata. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| info | ResourceInfo | REQUIRED. The resource information. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | Reference | REQUIRED. The reference to which the action should be performed. |
|
| arbitrary_metadata_keys | string | repeated | REQUIRED. The arbitrary metadata to delete. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | Reference | REQUIRED. The reference to which the action should be performed. |
|
| grant | Grant | REQUIRED. The grant to be updated. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
Storage Provider API
The Storage Provider API is meant to manipulate storage
resources in the underlying storage system behind the service.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
The following are global requirements that apply to all methods:
Any method MUST return CODE_OK on a succesful operation.
Any method MAY return NOT_IMPLEMENTED.
Any method MAY return INTERNAL.
Any method MAY return UNKNOWN.
Any method MAY return UNAUTHENTICATED.
| Method Name | Request Type | Response Type | Description |
| AddGrant | AddGrantRequest | AddGrantResponse | Adds a new grant for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist |
| CreateContainer | CreateContainerRequest | CreateContainerResponse | Creates a new resource of type container. MUST return CODE_PRECONDITION_FAILED if the container cannot be created at the specified reference. |
| Delete | DeleteRequest | DeleteResponse | Deletes a resource. If a resource specifies the non-empty container (directory, ...), then the entire directory is deleted recursively. If a resource specifies a reference or symlink type, only the reference is removed (not the target). MUST return CODE_NOT_FOUND if the reference does not exist. |
| GetProvider | GetProviderRequest | GetProviderResponse | Returns the information for this provider. |
| GetPath | GetPathRequest | GetPathResponse | Returns the path reference for the provided resource id reference. MUST return CODE_NOT_FOUND if the reference does not exist |
| GetQuota | GetQuotaRequest | GetQuotaResponse | Returns the quota available under the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist MUST return CODE_RESOURCE_EXHAUSTED on exceeded quota limits. |
| InitiateFileDownload | InitiateFileDownloadRequest | InitiateFileDownloadResponse | Initiates the download of a file using an out-of-band data transfer mechanism. |
| InitiateFileUpload | InitiateFileUploadRequest | InitiateFileUploadResponse | Initiates the upload of a file using an out-of-band data transfer mechanism. |
| ListGrants | ListGrantsRequest | ListGrantsResponse | Returns the list of grants for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exists. |
| ListContainerStream | ListContainerStreamRequest | ListContainerStreamResponse stream | Returns a stream of resource informations for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exists. |
| ListContainer | ListContainerRequest | ListContainerResponse | Returns a list of resource information for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exists. |
| ListFileVersions | ListFileVersionsRequest | ListFileVersionsResponse | Returns a list of the versions for a resource of type file at the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist. MUST return CODE_OK and MUST return an empty list if no versions are available. TODO: What code if resource not of type file? |
| ListRecycleStream | ListRecycleStreamRequest | ListRecycleStreamResponse stream | Returns a stream of recycle items for this storage provider. |
| ListRecycle | ListRecycleRequest | ListRecycleResponse | Returns a list of recycle items for this storage provider. MUST return CODE_OK and MUST return an empty list if no recycle items are available. |
| Move | MoveRequest | MoveResponse | Moves a resource from one reference to another. MUST return CODE_NOT_FOUND if any of the references do not exist. MUST return CODE_PRECONDITION_FAILED if the source reference cannot be moved to the destination reference. |
| RemoveGrant | RemoveGrantRequest | RemoveGrantResponse | Removes a grant for the provided reference. This is recursive and atomic for directories. Does not follow references. MUST return CODE_NOT_FOUND if the reference does not exist. MUST return CODE_NOT_FOUND if grant does not exist. |
| PurgeRecycle | PurgeRecycleRequest | PurgeRecycleResponse | Permanently removes a recycle item from the recycle. This operation is irrevocable. MUST return CODE_NOT_FOUND if the recycle item id does not exist. |
| RestoreFileVersion | RestoreFileVersionRequest | RestoreFileVersionResponse | Restores a file version for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist. MUST return CODE_NOT_FOUND if the version does not exist. |
| RestoreRecycleItem | RestoreRecycleItemRequest | RestoreRecycleItemResponse | Restores a recycle item from the recycle. MUST return CODE_NOT_FOUND if the recycle item id does not exist. MUST return CODE_PRECONDITION_FAILED if the restore_path is non-empty and the recycle item cannot be restored to the restore_path. |
| Stat | StatRequest | StatResponse | Returns the resource information at the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist. |
| UpdateGrant | UpdateGrantRequest | UpdateGrantResponse | Updates an ACL for the provided reference. MUST return CODE_NOT_FOUND if the reference does not exist. MUST return CODE_PRECONDITION_FAILED if the acl does not exist. |
| CreateReference | CreateReferenceRequest | CreateReferenceResponse | Creates a reference to another resource in the same cluster or another domain (OCM shares). The references resource can be accessed by the protocol specificied in the request message. |
| SetArbitraryMetadata | SetArbitraryMetadataRequest | SetArbitraryMetadataResponse | Sets arbitrary metadata into a storage resource. Arbitrary metadata is returned in a cs3.storageproviderv0alpha.ResourceInfo. |
| UnsetArbitraryMetadata | UnsetArbitraryMetadataRequest | UnsetArbitraryMetadataResponse | Unsets arbitrary metdata into a storage resource. Arbitrary metadata is returned in a cs3.storageproviderv0alpha.ResourceInfo. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| path | string | REQUIRED. The path to the home in a storage provider. For example /eos/user/h/hugo in the storage provider with root path /eos/user/. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | cs3.storageproviderv0alpha.Reference | REQUIRED. The reference for the resource. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| provider | cs3.storagetypes.ProviderInfo | REQUIRED. The storage provider handling the requested storage resource. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. TODO(labkode): maybe add some filter? |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| providers | cs3.storagetypes.ProviderInfo | repeated | REQUIRED. The list of storage providers this registry knows about. |
Storage Registry API
The Storage Registry API is meant to as registry to obtain
information of available storage providers.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
The following are global requirements that apply to all methods:
Any method MUST return CODE_OK on a succesful operation.
Any method MAY return NOT_IMPLEMENTED.
Any method MAY return INTERNAL.
Any method MAY return UNKNOWN.
Any method MAY return UNAUTHENTICATED.
| Method Name | Request Type | Response Type | Description |
| GetStorageProvider | GetStorageProviderRequest | GetStorageProviderResponse | Returns the storage provider that is reponsible for the given resource reference. MUST return CODE_NOT_FOUND if the reference does not exist. |
| ListStorageProviders | ListStorageProvidersRequest | ListStorageProvidersResponse | Returns a list of the available storage providers known by this registry. |
| GetHome | GetHomeRequest | GetHomeResponse | Returns the home path for the given authenticated user. When a user has access to multiple storage providers, one of them is the home. TODO(labkode): missing methods for adding and removing a storage provider with different visibility levels (system-wide, user-wide, group-wide)... |
| Field | Type | Label | Description |
| id | cs3.types.UserId |
|
|
| issuer | string |
|
|
| subject | string |
|
|
| username | string |
|
|
| string |
|
||
| display_name | string |
|
|
| groups | string | repeated |
|
| opaque | cs3.types.Opaque |
|
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| filter | string | REQUIRED. TODO(labkode): create propper filters for most common searchs. The filter to apply. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| users | User | repeated | REQUIRED. The groups for the user. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| user_id | cs3.types.UserId | REQUIRED. The id of the user. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| groups | string | repeated | REQUIRED. The groups for the user. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| user_id | cs3.types.UserId | REQUIRED. The id of the user. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| user | User | REQUIRED. The user information. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| user_id | cs3.types.UserId | REQUIRED. The id of the user. |
|
| group | string | REQUIRED. The group to check. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ok | bool | REQUIRED. Tells if the user belongs to the group. |
| Method Name | Request Type | Response Type | Description |
| GetUser | GetUserRequest | GetUserResponse | Gets the information about an user by its user id. |
| GetUserGroups | GetUserGroupsRequest | GetUserGroupsResponse | Gets the groups of a user. |
| IsInGroup | IsInGroupRequest | IsInGroupResponse | Tells if the user is in a certain group. |
| FindUsers | FindUsersRequest | FindUsersResponse | Finds users by any attribute of the user? TODO(labkode): to define the filters that make more sense. |
A received share is the share that a grantee will receive.
It expands the original share by adding state to the share,
a display name from the perspective of the grantee and a
resource mount path in case the share will be mounted
in a path in a storage provider.
| Field | Type | Label | Description |
| share | Share | REQUIRED. |
|
| state | ShareState | REQUIRED. The state of the share. |
Shares are relationships between a resource owner
(usually the authenticated user) who grants permissions to a recipient (grantee)
on a specified resource (resource_id). UserShares represents both user and groups.
| Field | Type | Label | Description |
| id | ShareId | REQUIRED. Opaque unique identifier of the share. |
|
| resource_id | cs3.storageproviderv0alpha.ResourceId | REQUIRED. Unique identifier of the shared resource. |
|
| permissions | SharePermissions | REQUIRED. Permissions for the grantee to use the resource. |
|
| grantee | cs3.storageproviderv0alpha.Grantee | REQUIRED. The receiver of the share, like a user, group ... |
|
| owner | cs3.types.UserId | REQUIRED. Uniquely identifies the owner of the share (the resource owner at the time of creating the share). In case the ownership of the underlying resource changes the share owner field MAY change to reflect the change of ownsership. |
|
| creator | cs3.types.UserId | REQUIRED. Uniquely identifies a principal who initiates the share creation. A creator can create shares on behalf of the owner (because of re-sharing, because belonging to special groups, ...). Creator and owner often result in being the same principal. |
|
| ctime | cs3.types.Timestamp | REQUIRED. Creation time of the share. |
|
| mtime | cs3.types.Timestamp | REQUIRED. Last modification time of the share. |
A share grant specifies the share permissions
for a grantee.
| Field | Type | Label | Description |
| grantee | cs3.storageproviderv0alpha.Grantee | REQUIRED. The grantee of the grant. |
|
| permissions | SharePermissions | REQUIRED. The share permissions for the grant. |
A share id identifies uniquely a // share in the share provider namespace.
A ShareId MUST be unique inside the share provider.
| Field | Type | Label | Description |
| opaque_id | string | REQUIRED. The internal id used by service implementor to uniquely identity the share in the internal implementation of the service. |
Uniquely identifies a share in the share provider.
A share MUST be uniquely identify by four (4) elements:
1) The share provider id
2) The owner of the share
3) The resource id
4) The grantee for the share
This 4-tuple MUST be unique.
For example, owner Alice shares the resource /home/docs with id
home:1234 to an user named Bob. The 4-tuple will consist of
1) The share provider id = "user"
2) The owner of the share = "Alice"
3) The resource id = "home:1234"
4) The grantee for the share = Grantee("type" = "user", "" => "Bob")
| Field | Type | Label | Description |
| owner | cs3.types.UserId | REQUIRED. |
|
| resource_id | cs3.storageproviderv0alpha.ResourceId | REQUIRED. |
|
| grantee | cs3.storageproviderv0alpha.Grantee | REQUIRED. |
The permissions for a share.
| Field | Type | Label | Description |
| permissions | cs3.storageproviderv0alpha.ResourcePermissions | TODO(labkode): additional permissions for shares like re-sharing |
The mechanism to identify a share
in the share provider namespace.
| Field | Type | Label | Description |
| id | ShareId | The id of the share. |
|
| key | ShareKey | The combination of fields that make the share unique. |
The state of the share.
| Name | Number | Description |
| SHARE_STATE_INVALID | 0 | The share is no longer valid, for example, the share expired. |
| SHARE_STATE_PENDING | 1 | New shares MUST be created in the SHARE_STATE_PENDING state. This state means the share is pending to be accepted or rejected by the recipient of the share. |
| SHARE_STATE_ACCEPTED | 2 | The recipient of the share has accepted the share. |
| SHARE_STATE_REJECTED | 3 | The recipient of the share has rejected the share. Do not means the share is removed, the recipient MAY change the state to accepted or pending. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| resource_info | cs3.storageproviderv0alpha.ResourceInfo | REQUIRED. The information of the resource to be shared. |
|
| grant | ShareGrant | REQUIRED. The share grant for the share. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| share | Share | REQUIRED. The created share. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | ShareReference | REQUIRED. The reference of the received share. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| share | ReceivedShare | REQUIRED. The share. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | ShareReference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| share | Share | REQUIRED. The share. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| shares | ReceivedShare | repeated | REQUIRED. The list of received shares. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| filters | ListSharesRequest.Filter | repeated | OPTIONAL. The list of filters to apply if any. |
represents a filter to apply to the request.
| Field | Type | Label | Description |
| type | ListSharesRequest.Filter.Type |
|
|
| resource_id | cs3.storageproviderv0alpha.ResourceId |
|
|
| owner | cs3.types.UserId |
|
|
| creator | cs3.types.UserId |
|
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| shares | Share | repeated | REQUIRED. The list of shares. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | ShareReference | REQUIRED. The reference to which the action should be performed. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
TODO(labkode): clean up display_name ? we'll use storage links for that.
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
|
| ref | ShareReference | REQUIRED. |
|
| field | UpdateReceivedShareRequest.UpdateField |
|
| Field | Type | Label | Description |
| display_name | string | Update the display name. |
|
| state | ShareState | Update the share state |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Field | Type | Label | Description |
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. REQUIRED. |
|
| ref | ShareReference |
|
|
| field | UpdateShareRequest.UpdateField |
|
| Field | Type | Label | Description |
| permissions | SharePermissions | Update the permissions. |
|
| display_name | string | Update the display name. |
| Field | Type | Label | Description |
| status | cs3.rpc.Status | REQUIRED. The response status. |
|
| opaque | cs3.types.Opaque | OPTIONAL. Opaque information. |
| Name | Number | Description |
| LIST_SHARES_REQUEST_FILTER_TYPE_INVALID | 0 | |
| LIST_SHARES_REQUEST_FILTER_TYPE_NO_FILTER | 1 | |
| LIST_SHARES_REQUEST_FILTER_TYPE_RESOURCE_ID | 2 | |
| LIST_SHARES_REQUEST_FILTER_TYPE_OWNER | 3 | |
| LIST_SHARES_REQUEST_FILTER_TYPE_CREATOR | 4 |
User Share Provider API
The User Share Provider API is meant to manipulate share
resources for a specific share type (user, group, ocm, ...)
from the perspective of the creator or the share and
from the perspective of the receiver of the share.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
The following are global requirements that apply to all methods:
Any method MUST return CODE_OK on a succesful operation.
Any method MAY return NOT_IMPLEMENTED.
Any method MAY return INTERNAL.
Any method MAY return UNKNOWN.
Any method MAY return UNAUTHENTICATED.
| Method Name | Request Type | Response Type | Description |
| CreateShare | CreateShareRequest | CreateShareResponse | Creates a new share. MUST return CODE_NOT_FOUND if the resource reference does not exist. MUST return CODE_ALREADY_EXISTS if the share already exists for the 4-tuple consisting of (owner, shared_resource, grantee). New shares MUST be created in the state SHARE_STATE_PENDING. |
| RemoveShare | RemoveShareRequest | RemoveShareResponse | Removes a share. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| GetShare | GetShareRequest | GetShareResponse | Gets share information for a single share. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| ListShares | ListSharesRequest | ListSharesResponse | List the shares the authenticated principal has created, both as owner and creator. If a filter is specified, only shares satisfying the filter MUST be returned. |
| UpdateShare | UpdateShareRequest | UpdateShareResponse | Updates a share. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| ListReceivedShares | ListReceivedSharesRequest | ListReceivedSharesResponse | List all shares the authenticated principal has received. |
| UpdateReceivedShare | UpdateReceivedShareRequest | UpdateReceivedShareResponse | Update the received share to change the share state or the display name. MUST return CODE_NOT_FOUND if the share reference does not exist. |
| GetReceivedShare | GetReceivedShareRequest | GetReceivedShareResponse | Get the information for the given received share reference. MUST return CODE_NOT_FOUND if the received share reference does not exist. |
| .proto Type | Notes | C++ Type | Java Type | Python Type |
| double | double | double | float | |
| float | float | float | float | |
| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
| uint32 | Uses variable-length encoding. | uint32 | int | int/long |
| uint64 | Uses variable-length encoding. | uint64 | long | int/long |
| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
| sfixed32 | Always four bytes. | int32 | int | int |
| sfixed64 | Always eight bytes. | int64 | long | int/long |
| bool | bool | boolean | boolean | |
| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |


-
Parallel Tensor Infrastructure (ParTI) on multicore CPUs and GPUs
Code released in Github: [ParTI]
-
CP Decomposition and Matriced Tensor Times Khatri-Rao Product (MTTKRP)
Improving MTTKRP performance for CP decomposition, and trying to find sparse tensor features to develop a new data structure for sparse tensors.
-
Tucker decomposition and Tensor-Times-Matrix Product (TTM)
Improved TTM performance by optimizing the data transformation time.
-
SMAT (SpMV Auto-tuner)
-
DGEMM on GPU [Click here for details]
-
Algebraic Multi-grid (AMG)