Expose TUS capability of a resource

[PVince81]

When a Webdav resource supports TUS, any request done to it (PROPFIND, OPTIONS) will return a Tus-Version: 1.0.0 header whenever the backend storage supports TUS (see cs3org/reva#661 and owncloud/web#3345)

The problem is that none of the relevant calls are exposing the headers to the caller.
For example here the client.files.list() call is directly returning an array.
And for a single file client.files.fileInfo() also returns the file info directly.
There is no room to add response headers or a new attribute tusSupported there without breaking API compatibility.

Here are other possible exotic approaches:

• Approach 0: break API compatibility and change the response format
• Approach 1: add a new attribute options.returnAsObject which changes the response format to the new thing
• Approach 2: duplicate the methods for which we change the return types and deprecate the olds ones
• Approach 3 (dirty hack): the API caller wraps the XHR object before the call and captures the response headers there
• Approach 4 (inelegant): have the SDK expose a "getLastHeaders()" function somewhere
• Approach 5: have an additional API call that does an OPTIONS call to an endpoint to return capabilities and headers. Drawback: an additional call.
• Approach 6 (dirty hack): add the headers array as an attribute of the array returned by list()

Thoughts ? @DeepDiver1975 @butonic @LukasHirt

[PVince81]

https://github.com/owncloud/owncloud-sdk/blob/master/src/fileManagement.js#L58

[PVince81]

As discussed with @butonic: the server will expose the headers that are usually returned by TUS' OPTIONS call but it will return them also with the PROPFIND so we save an additional request.

The headers would be:

• Tus-Version
• Tus-Extension
• Tus-Max-Size (if we chose to expose it)

Then the SDK will package those headers in an additional attribute of the "FileInfo" class of the folder. For the list call, this information will only be exposed on the root entry.

The API caller can then simply call fileInfo.getTusCapabilities() to retrieve the infos:

{
    isSupported: true,
    version: ['1.0.0', '1.2.3', ...],
    extensions: ['create', 'create-with-upload', ...],
    maxSize: 123456
}

If TUS is not supported the method getTusCapabilities() will return null

[PVince81]

PR here: #461