radically simplify references

cs3/app/provider/v1beta1/provider_api.proto

@@ -84,8 +84,8 @@ message OpenInAppRequest {
  // 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 filepath to grant access, as
- // ResourceIds MUST NOT change when a resource is renamed.
+ // Service implementors should use a Reference with a root_id and an empty path to grant access, as
+ // root_ids MUST NOT change when a resource is renamed.
  // The access token MUST be short-lived.
  // TODO(labkode): investigate token derivation techniques.
  string access_token = 4;
@@ -134,8 +134,8 @@ message OpenFileInAppProviderRequest {
  // 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.
+ // Service implementors should use a Reference with a root_id and an empty path to grant access, as
+ // root_ids MUST NOT change when a resource is renamed.
  // The access token MUST be short-lived.
  // TODO(labkode): investigate token derivation techniques.
  string access_token = 4;

cs3/gateway/v1beta1/gateway_api.proto

@@ -103,7 +103,7 @@ service GatewayAPI {
  // MUST return CODE_NOT_FOUND if the reference does not exist.
  rpc Delete(cs3.storage.provider.v1beta1.DeleteRequest) returns (cs3.storage.provider.v1beta1.DeleteResponse);
  // Returns the path reference for
- // the provided resource id reference.
+ // the provided resource reference.
  // MUST return CODE_NOT_FOUND if the reference does not exist
  rpc GetPath(cs3.storage.provider.v1beta1.GetPathRequest) returns (cs3.storage.provider.v1beta1.GetPathResponse);
  // Returns the quota available under the provided

cs3/sharing/collaboration/v1beta1/collaboration_api.proto

@@ -150,14 +150,14 @@ message ListSharesRequest {
  enum Type {
  TYPE_INVALID = 0;
  TYPE_NO = 1;
- TYPE_RESOURCE_ID = 2;
+ TYPE_REFERENCE = 2;
  TYPE_OWNER = 3;
  TYPE_CREATOR = 4;
  }
  // REQUIRED.
  Type type = 2;
  oneof term {
- storage.provider.v1beta1.ResourceId resource_id = 3;
+ storage.provider.v1beta1.Reference ref = 3;
  cs3.identity.user.v1beta1.UserId owner = 4;
  cs3.identity.user.v1beta1.UserId creator = 5;
  }

cs3/sharing/collaboration/v1beta1/resources.proto

@@ -34,14 +34,14 @@ import "cs3/types/v1beta1/types.proto";
 
 // 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.
+// on a specified resource (reference). UserShares represents both user and groups.
 message Share {
  // REQUIRED.
  // Opaque unique identifier of the share.
  ShareId id = 1;
  // REQUIRED.
- // Unique identifier of the shared resource.
- storage.provider.v1beta1.ResourceId resource_id = 2;
+ // Unique identifier of the shared resource (path must be empty).
+ storage.provider.v1beta1.Reference ref = 2;
  // REQUIRED.
  // Permissions for the grantee to use
  // the resource.
@@ -122,7 +122,8 @@ message ShareKey {
  // REQUIRED.
  cs3.identity.user.v1beta1.UserId owner = 2;
  // REQUIRED.
- storage.provider.v1beta1.ResourceId resource_id = 3;
+ // Unique identifier of the shared resource (path must be empty).
+ storage.provider.v1beta1.Reference ref = 3;
  // REQUIRED.
  storage.provider.v1beta1.Grantee grantee = 4;
 }

cs3/sharing/link/v1beta1/link_api.proto

@@ -159,13 +159,14 @@ message ListPublicSharesRequest {
  // REQUIRED.
  enum Type {
  TYPE_INVALID = 0;
- TYPE_RESOURCE_ID = 1;
+ TYPE_REFERENCE = 1;
  TYPE_OWNER = 2;
  TYPE_CREATOR = 3;
  }
  Type type = 2;
  oneof term {
- storage.provider.v1beta1.ResourceId resource_id = 3;
+ // Unique identifier of the shared resource (path must be empty).
+ storage.provider.v1beta1.Reference ref = 3;
  cs3.identity.user.v1beta1.UserId owner = 4;
  cs3.identity.user.v1beta1.UserId creator = 5;
  }

cs3/sharing/link/v1beta1/resources.proto

@@ -48,7 +48,7 @@ import "cs3/types/v1beta1/types.proto";
 
 // 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.
+// on a specified resource (reference). 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.
@@ -61,8 +61,8 @@ message PublicShare {
  // to the public share.
  string token = 2;
  // REQUIRED.
- // Unique identifier of the shared resource.
- storage.provider.v1beta1.ResourceId resource_id = 3;
+ // Unique identifier of the shared resource (path must be empty).
+ storage.provider.v1beta1.Reference ref = 3;
  // REQUIRED.
  // Permissions for the grantee to use
  // the resource.

cs3/sharing/ocm/v1beta1/ocm_api.proto

@@ -87,8 +87,8 @@ message CreateOCMShareRequest {
  // Opaque information.
  cs3.types.v1beta1.Opaque opaque = 1;
  // REQUIRED.
- // The unique identifier for the shared storage resource.
- storage.provider.v1beta1.ResourceId resource_id = 2;
+ // Unique identifier of the shared resource (path must be empty).
+ storage.provider.v1beta1.Reference ref = 2;
  // REQUIRED.
  // The share grant for the share.
  ShareGrant grant = 3;
@@ -151,7 +151,7 @@ message ListOCMSharesRequest {
  enum Type {
  TYPE_INVALID = 0;
  TYPE_NO = 1;
- TYPE_RESOURCE_ID = 2;
+ TYPE_REFERENCE = 2;
  TYPE_OWNER = 3;
  TYPE_CREATOR = 4;
  TYPE_OWNER_PROVIDER = 5;
@@ -160,7 +160,8 @@ message ListOCMSharesRequest {
  // REQUIRED.
  Type type = 2;
  oneof term {
- storage.provider.v1beta1.ResourceId resource_id = 3;
+ // Unique identifier of the shared resource (path must be empty).
+ storage.provider.v1beta1.Reference ref = 3;
  cs3.identity.user.v1beta1.UserId owner = 4;
  cs3.identity.user.v1beta1.UserId creator = 5;
  }

cs3/sharing/ocm/v1beta1/resources.proto

@@ -34,14 +34,14 @@ import "cs3/types/v1beta1/types.proto";
 
 // 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.
+// on a specified resource (reference). UserShares represents both user and groups.
 message Share {
  // REQUIRED.
  // Opaque unique identifier of the share.
  ShareId id = 1;
  // REQUIRED.
- // Unique identifier of the shared resource.
- storage.provider.v1beta1.ResourceId resource_id = 2;
+ // Unique identifier of the shared resource (path must be empty).
+ storage.provider.v1beta1.Reference ref = 2;
  // REQUIRED.
  // Name of the shared resource.
  string name = 3;
@@ -134,7 +134,8 @@ message ShareKey {
  // REQUIRED.
  cs3.identity.user.v1beta1.UserId owner = 2;
  // REQUIRED.
- storage.provider.v1beta1.ResourceId resource_id = 3;
+ // Unique identifier of the shared resource (path must be empty).
+ storage.provider.v1beta1.Reference ref = 3;
  // REQUIRED.
  storage.provider.v1beta1.Grantee grantee = 4;
 }

cs3/storage/provider/v1beta1/provider_api.proto

@@ -64,7 +64,7 @@ service ProviderAPI {
  // MUST return CODE_NOT_FOUND if the reference does not exist.
  rpc Delete(DeleteRequest) returns (DeleteResponse);
  // Returns the path reference for
- // the provided resource id reference.
+ // the provided resource reference.
  // MUST return CODE_NOT_FOUND if the reference does not exist
  rpc GetPath(GetPathRequest) returns (GetPathResponse);
  // Returns the quota available under the provided
@@ -169,9 +169,8 @@ message GetHomeResponse {
  // Opaque information.
  cs3.types.v1beta1.Opaque opaque = 2;
  // 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/.
- string path = 3;
+ // The reference to the home in a storage provider.
+ Reference ref = 3;
 }
 
 message AddGrantRequest {
@@ -236,8 +235,8 @@ message GetPathRequest {
  // Opaque information.
  cs3.types.v1beta1.Opaque opaque = 1;
  // REQUIRED.
- // The resource id of the resource.
- ResourceId resource_id = 2;
+ // Unique identifier of the shared resource (path must be empty).
+ Reference ref = 2;
 }
 
 message GetPathResponse {
@@ -249,7 +248,7 @@ message GetPathResponse {
  cs3.types.v1beta1.Opaque opaque = 2;
  // REQUIRED.
  // The path of the resource.
- string path = 3;
+ Reference ref = 3;
 }
 
 message GetQuotaRequest {
@@ -540,7 +539,7 @@ message RestoreRecycleItemRequest {
  // the original.
  // If empty, service implementors MUST restore
  // to original location if possible.
- string restore_path = 4;
+ Reference restore_ref = 4;
 }
 
 message RestoreRecycleItemResponse {
@@ -625,7 +624,7 @@ message CreateSymlinkRequest {
  cs3.types.v1beta1.Opaque opaque = 1;
  // REQUIRED.
  // The location where to store the symlink.
- string path = 2;
+ Reference ref = 2;
  // REQUIRED.
  // The link target can hold arbitrary text; if later resolved,
  // a relative link is interpreted in relation to its parent directory
@@ -647,7 +646,7 @@ message CreateReferenceRequest {
  cs3.types.v1beta1.Opaque opaque = 1;
  // REQUIRED.
  // The location where to store the reference.
- string path = 2;
+ Reference ref = 2;
  // REQUIRED.
  // The reference resource by RFC3986.
  string target_uri = 3;

cs3/storage/provider/v1beta1/resources.proto

@@ -44,7 +44,7 @@ message ResourceInfo {
  ResourceType type = 2;
  // REQUIRED.
  // Opaque unique identifier of the resource.
- ResourceId id = 3;
+ Reference id = 3;
  // REQUIRED.
  // The data checksum for the file resource.
  // For all other resources, the checksum is unset.
@@ -64,9 +64,8 @@ message ResourceInfo {
  // For reference types this is NOT the mtime of the target.
  cs3.types.v1beta1.Timestamp mtime = 7;
  // REQUIRED.
- // The path for the resource.
- // It MUST start with the slash character (/).
- string path = 8;
+ // The reference for the resource.
+ Reference path = 8;
  // REQUIRED.
  // The set of permissions for the resource effective for the authenticated user.
  ResourcePermissions permission_set = 9;
@@ -189,33 +188,24 @@ message ResourceChecksumPriority {
  uint32 priority = 2;
 }
 
-// The mechanism to identify a resource
-// in the storage provider namespace. Note that the path OR the resourceId must be specifed, not both.
+// The mechanism to identify a resource in the CS3 namespace.
+// It can represent path based, id based and combined references:
+// The storage registry uses the storage_id to determine the responsible storage provider.
+// When the storage_id is not available it will use the path.
+// In a URL the different components can be represented in a string using the following layout:
+// <storage_id>!<node_id>:<path>
 message Reference {
- // REQUIRED.
- // One of the specifications MUST be specified.
- oneof spec {
- // The path to the resource.
- // MUST start with the slash character (/).
- string path = 1;
- // The id for the resource.
- // MUST NOT start with the slash character (/).
- ResourceId id = 2;
- }
-}
-
-// A resource id identifies uniquely a
-// resource in the storage provider namespace.
-// A ResourceId MUST be unique in the storage provider.
-message ResourceId {
- // REQUIRED.
- // The storage id of the storage provider.
+ // OPTIONAL.
+ // The logical id of a storage. Used by the storage registry to determine the responsible storage provider.
  string storage_id = 1;
- // REQUIRED.
- // The internal id used by service implementor to
- // uniquely identity the resource in the internal
- // implementation of the service.
- string opaque_id = 2;
+ // OPTIONAL.
+ // The logical node id used by a storage provider to uniquely identify a resource in a storage.
+ string node_id = 2;
+ // OPTIONAL.
+ // When starting with `/` the reference represents an absolute path. In this case the storage_id and the node_id must be empty.
+ // When not starting with `/` represents a path relative to the node_id.
+ // When node_id is empty the path is considered relative to the root of the storage.
+ string path = 3;
 }
 
 // The representation of permissions attached to a resource.
@@ -313,9 +303,8 @@ message RecycleItem {
  // The key to identify the deleted resource.
  string key = 3;
  // REQUIRED.
- // The original path of the deleted resource.
- // MUST start with the slash character (/).
- string path = 4;
+ // The original reference of the deleted resource.
+ Reference ref = 4;
  // OPTIONAL.
  // The size of the deleted resource.
  uint64 size = 5;
@@ -379,7 +368,7 @@ message StorageSpace {
  cs3.identity.user.v1beta1.User owner = 3;
  // OPTIONAL.
  // The root resource of the storage space.
- ResourceId root = 4;
+ Reference root = 4;
  // OPTIONAL.
  string name = 5;
  // OPTIONAL.