Feat: introduce accessType property in a share and remove the datatx "protocol"

IETF-RFC.md

@@ -623,11 +623,6 @@ contain the following information about its OCM API:
       endpoint.  This value is provided for documentation
       purposes, and it SHOULD NOT be intended as a prefix
       for share requests.
-    - datatx (string) - The top-level path used for data transfers.
-      This value is provided for documentation purposes,
-      and it SHOULD NOT be intended as a prefix.  In
-      addition, implementations are expected to execute
-      the transfer using WebDAV [RFC4918] as the wire protocol.
     - Any additional protocol supported for this Resource type MAY be
       advertised here, where the value MAY correspond to
       a top-level URI to be used for that protocol.
@@ -768,47 +763,53 @@ To create a Share, the Sending Server SHOULD make a HTTP POST request
   by the Receiving Server.
 * OPTIONAL expiration (integer)
   The expiration time for the OCM share, in seconds
-  of UTC time since Unix epoch.  If omitted, it is assumed
-  that the share does not expire.
+  of UTC time since Unix epoch.  If omitted, it is assumed that the
+  share does not expire.  A sender server MAY use it to signal that
+  the resource represents a cached copy of a dataset that was made
+  available for an efficient data transfer to the destination server.
 * REQUIRED protocol (object)
   JSON object with specific options for each protocol.
   The supported protocols are: - `webdav`, to access the data -
-  `webapp`, to access remote web applications - `datatx`, to transfer
-  the data to the remote endpoint.
-
-          Other custom protocols might be added in the future.
-
-          In case a single protocol is offered, there are three ways to
-          specify this object:
-          Option 1: Set the `name` field to the name of the protocol,
-          and put the protocol details in a field named `options`.
-          Option 2: Set the `name` field to the name of the protocol,
-          and put the protocol details in a field carrying the name of
-          the protocol.
-          Option 3: Set the `name` field to `multi`, and put the
-          protocol details in a field carrying the name of the protocol.
-
-                Option 1 using the `options` field is now deprecated.
-                Implementations are encouraged to transition to the new
-                optional properties defined below, such that this field
-                may be removed in a future major version of the spec.
-
-          When specifying more than one protocol as different ways to
-          access the Share, the `name` field needs to be set to `multi`.
-
-If `multi` is given, one or more protocol
-endpoints are expected to be defined according to the
-optional properties specified below.
-Otherwise, at least `webdav` is expected to be
-supported, and its options MAY be given in the opaque
-`options` payload for compatibility with v1.0
-implementations (see examples).  Note though that this
-format is deprecated.
-Warning: client implementers should be aware that v1.1
-servers MAY support both `webdav` and `multi`, but v1.0
-servers MAY only support `webdav`.
-
+  `webapp`, to access remote web applications.
+  Other custom protocols might be added in the future.
+  In case a single protocol is offered, there are three ways to
+  specify this object:
+  Option 1: Set the `name` field to the name of the protocol,
+  and put the protocol details in a field named `options`.
+  Option 2: Set the `name` field to the name of the protocol,
+  and put the protocol details in a field carrying the name of
+  the protocol.
+  Option 3: Set the `name` field to `multi`, and put the
+  protocol details in a field carrying the name of the protocol.
+  Option 1 using the `options` field is now deprecated.
+  Implementations are encouraged to transition to the new
+  optional properties defined below, such that this field
+  may be removed in a future major version of the spec.
+  When specifying more than one protocol as different ways to
+  access the Share, the `name` field needs to be set to `multi`.
+  If `multi` is given, one or more protocol
+  endpoints are expected to be defined according to the
+  optional properties specified below.
+  Otherwise, at least `webdav` is expected to be
+  supported, and its options MAY be given in the opaque
+  `options` payload for compatibility with v1.0
+  implementations (see examples).  Note though that this
+  format is deprecated.
+  Warning: client implementers should be aware that v1.1+
+  servers MAY support both `webdav` and `multi`, but v1.0
+  servers MAY only support `webdav`.
 * Protocol details for `webdav` MAY contain:
+  - OPTIONAL accessType (array of strings) - The type of access
+    being granted to the remote resource.  If omitted, it defaults to
+    `['remote']`.  A subset of: - `remote` signals the recipient that
+    the resource is available for remote access and interactive
+    browsing.  - `datatx` signals the recipient that the resource is
+    available for data transfer.  If no expiration is given, the share
+    is suitable e.g. for sync use-cases, whereas if an expiration date
+    is set, the above clause MAY apply and the recipient SHOULD notify
+    the sender upon completing the data transfer, in order to ease
+    cache operations on the Sending Server.  The recipient MAY delegate
+    a third-party service to execute the data transfer on their behalf.
   - REQUIRED uri (string)
     A URI to access the Remote Resource.  The URI
     SHOULD be relative, in which case the prefix
@@ -834,6 +835,9 @@ servers MAY only support `webdav`.
     to the Sending Server's {tokenEndPoint} [RFC6749].
     This MAY be used if the recipient provider exposes the
     `exchange-token` capability.
+  - OPTIONAL size (integer)
+    The size of the resource to be transferred, useful
+    especially in case of `datatx` access type.
 * Protocol details for `webapp` MAY contain:
   - REQUIRED uri (string)
     A URI to a client-browsable view of the Shared
@@ -850,20 +854,6 @@ servers MAY only support `webdav`.
   - OPTIONAL sharedSecret (string)
     An optional secret to be used to access the remote
     web app, for example in the form of a bearer token.
-* Protocol details for `datatx` MAY contain:
-  - REQUIRED srcUri (string)
-    A URI to access the Remote Resource.  The URI
-    SHOULD be relative, in which case the prefix
-    exposed by the `/.well-known/ocm` endpoint MUST be
-    used.  Absolute URIs are deprecated.
-  - OPTIONAL sharedSecret (string)
-    An optional secret to be used to access the
-    Resource, for example in the form of a bearer
-    token.  To prevent leaking it in logs it MUST NOT
-    appear in any URI.
-  - OPTIONAL size (integer)
-    The size of the file to be transferred from the
-    sending server.
 
 ## Decision to Discard
 

spec.yaml

@@ -388,14 +388,6 @@ components:
                       The top-level path for web apps at this endpoint. In order to
                       access a remote web app, implementations SHOULD use this path
                       as a prefix (see sharing examples).
-                  datatx:
-                    type: string
-                    description: >
-                      The top-level path to be used for data transfers. In order to
-                      access a remote shared resource, implementations SHOULD use
-                      this path as a prefix (see sharing examples). In addition,
-                      implementations are expected to execute the transfer using
-                      WebDAV as the wire protocol.
                 additionalProperties:
                     type: string
                     description: >
@@ -550,16 +542,18 @@ components:
         expiration:
           type: integer
           description: >
-            The expiration time for the share, in seconds of UTC time since
-            Unix epoch. If omitted, it is assumed that the share does not expire.
+            The expiration time for the share, in seconds of UTC time since Unix
+            epoch. If omitted, it is assumed that the share does not expire. A sender
+            server MAY use the `expiration` to signal that the resource represents
+            a cached copy of a dataset that was made available for an efficient
+            data transfer to the destination server.
         protocol:
           type: object
           description: |
             JSON object with specific options for each protocol.
             The supported protocols are:
             - `webdav`, to access the data
             - `webapp`, to access remote web applications
-            - `datatx`, to transfer the data to the remote endpoint
             Other custom protocols might be added in the future.
           required:
             - name
@@ -587,7 +581,25 @@ components:
                 this field may be removed in a future major version of the spec.
             webdav:
               type: object
+              required:
+                - uri
+                - permissions
               properties:
+                accessType:
+                  type: array
+                  description: >
+                    The type of access being granted to the remote resource.
+                    If omitted, it defaults to `['remote']`.
+                    - `remote` signals the recipient that the resource is available
+                      for remote access and interactive browsing.
+                    - `datatx` signals the recipient to transfer the resource
+                      from the given URI. The recipient MAY delegate a third-party
+                      service to execute the data transfer on their behalf.
+                  items:
+                    type: string
+                    enum:
+                      - remote
+                      - datatx
                 uri:
                   type: string
                   description: >
@@ -605,13 +617,13 @@ components:
                     To prevent leaking it in logs it MUST NOT appear in any URI.
                 permissions:
                   type: array
+                  description: >
+                    The permissions granted to the sharee.
+                    - `read` allows read-only access including download of a copy.
+                    - `write` allows create, update, and delete rights on the resource.
+                    - `share` allows re-share rights on the resource.
                   items:
                     type: string
-                    description: >
-                      The permissions granted to the sharee.
-                      - `read` allows read-only access including download of a copy.
-                      - `write` allows create, update, and delete rights on the resource.
-                      - `share` allows re-share rights on the resource.
                     enum:
                       - read
                       - write
@@ -621,8 +633,7 @@ components:
                   items:
                     type: string
                     description: >
-                      A list of requirements that the recipient provider MUST
-                      fulfill
+                      A list of requirements that the recipient provider MUST fulfill
                       to access the resource. Requirements are optional, but if it is
                       present it MUST NOT be empty. A recipient provider MUST reject
                       a share whose requirements it does not understand.
@@ -638,6 +649,11 @@ components:
                     enum:
                       - must-use-mfa
                       - must-exchange-token
+                size:
+                  type: integer
+                  description: >
+                    The size of the resource to be transferred, useful especially
+                    in case of `datatx` access type.
             webapp:
               type: object
               properties:
@@ -672,30 +688,6 @@ components:
                     in any URI.  In a multi-protocol share scenario with WebDAV, the
                     access requirements provided in the `webdav` part MUST apply for
                     `webapp` accesses as well.
-            datatx:
-              type: object
-              properties:
-                sharedSecret:
-                  type: string
-                  description: >
-                    An optional secret to be used to access the resource, such as
-                    a bearer token.  To prevent leaking it in logs it MUST NOT
-                    appear in any URI.  In a multi-protocol share scenario with WebDAV,
-                    the access requirements provided in the `webdav` part MUST apply
-                    for `datatx` transfers as well.
-                srcUri:
-                  type: string
-                  description: >
-                    An URI to access the resource at the sending server. The URI
-                    SHOULD be relative, such as a key or a UUID, in which case the
-                    prefix exposed by the `/.well-known/ocm` endpoint SHOULD be used
-                    to access the resource, or it MAY be absolute, including a
-                    hostname. Similar considerations as for the `webdav` case apply.
-                size:
-                  type: integer
-                  description: >
-                    The size of the file to be transferred from the sending
-                    server.
 
           additionalProperties:
             type: object
@@ -718,11 +710,10 @@ components:
                 permissions:
                   - read
                   - write
-                requirements:
-                  - none
             multipleProtocols:
               name: multi
               webdav:
+                accessType: ['remote', 'datatx']
                 uri: 7c084226-d9a1-11e6-bf26-cec0c932ce01
                 sharedSecret: hfiuhworzwnur98d3wjiwhr
                 permissions:
@@ -733,10 +724,6 @@ components:
                 uri: 7c084226-d9a1-11e6-bf26-cec0c932ce01
                 sharedSecret: hfiuhworzwnur98d3wjiwhr
                 viewMode: read
-              datatx:
-                srcUri: 7c084226-d9a1-11e6-bf26-cec0c932ce01
-                sharedSecret: hfiuhworzwnur98d3wjiwhr
-                size: 100000
     NewNotification:
       type: object
       required: