[Feature Request]: Support iOS PhotoKit background upload capability negotiation

[marinofaggiana]

[Feature Request]: Support iOS PhotoKit background upload capability negotiation

Summary

Add server-side support for the capability negotiation required by the new iOS PHBackgroundResourceUploadExtension API.

PhotoKit performs an OPTIONS request against the upload destination before executing the actual PUT.

When the destination server does not support Apple's resumable upload protocol, PhotoKit expects:

HTTP/1.1 501 Not Implemented

Nextcloud currently handles the request as a normal WebDAV OPTIONS request and returns the standard WebDAV response.

The subsequent PUT can still upload the file successfully, but PhotoKit considers the background upload job failed.

A server-side response of 501 Not Implemented for the PhotoKit capability check has been tested and makes the same jobs complete successfully.

Proposed approach

The Nextcloud iOS client can mark PhotoKit background upload destinations with a dedicated request header:

X-NC-PhotoKit-Upload: 1

PhotoKit preserves this custom header when generating its preliminary OPTIONS request.

Nextcloud Server can therefore identify the PhotoKit capability check using:

method = OPTIONS
X-NC-PhotoKit-Upload = 1

and return:

HTTP/1.1 501 Not Implemented

Regular WebDAV OPTIONS requests remain unchanged.

The subsequent PUT request continues through the normal Nextcloud WebDAV upload flow.

Expected request flow

PhotoKit
    |
    | OPTIONS /remote.php/dav/files/<user>/<folder>/<file>
    | X-NC-PhotoKit-Upload: 1
    v
Nextcloud Server
    |
    | 501 Not Implemented
    v
PhotoKit
    |
    | PUT /remote.php/dav/files/<user>/<folder>/<file>
    v
Nextcloud WebDAV
    |
    | normal upload handling
    v
201 Created / 204 No Content

Verification

This behavior was verified on a Nextcloud test instance by temporarily configuring Apache to return 501 only when both conditions were true:

RewriteCond %{REQUEST_METHOD} =OPTIONS
RewriteCond %{HTTP:X-NC-PhotoKit-Upload} =1
RewriteRule ^ - [R=501,L]

No special upload path or folder was required.

The Nextcloud iOS Background Upload Extension used a normal WebDAV destination such as:

/remote.php/dav/files/<user>/<folder>/<filename>

with:

X-NC-PhotoKit-Upload: 1

The PhotoKit-generated OPTIONS request preserved the custom header, allowing Apache to return 501 only for the PhotoKit capability check.

With this configuration, the background upload jobs changed to:

state: succeeded (4)
type: upload (0)
method: PUT
error domain: <nil>
code: 0

and were subsequently completed and acknowledged successfully.

All tested HEIC and MOV resources completed, and the extension finished with no active jobs.

Current behavior

Without special handling:

PhotoKit OPTIONS
    ↓
Nextcloud WebDAV OPTIONS response
    ↓
PhotoKit does not fall back to the non-resumable upload behavior expected for servers that do not support the resumable upload protocol
    ↓
PUT uploads the file successfully
    ↓
PhotoKit job is reported as failed

The stored file itself is valid and the normal Nextcloud PUT implementation works correctly.

Desired behavior

When Nextcloud receives:

OPTIONS
X-NC-PhotoKit-Upload: 1

it should return:

HTTP/1.1 501 Not Implemented

unless Nextcloud implements the resumable upload protocol expected by PhotoKit.

All other WebDAV OPTIONS requests should continue to behave exactly as they do today.

Client-side requirement

The Nextcloud iOS Background Upload Extension only needs to add:

request.setValue("1", forHTTPHeaderField: "X-NC-PhotoKit-Upload")

to the destination URLRequest.

No change to the existing WebDAV PUT implementation is required.

Why this belongs on the server side

The regular WebDAV upload itself already works correctly.

Successful uploads return the expected Nextcloud DAV metadata, including:

oc-fileid
oc-etag
x-nc-ownerid
x-oc-ctime: accepted
x-oc-mtime: accepted

The compatibility issue exists only during PhotoKit's preliminary capability negotiation.

Handling the dedicated PhotoKit OPTIONS request on the server avoids:

• Apache-specific configuration;
• nginx-specific configuration;
• administrator-side workarounds;
• dedicated upload folders or URL paths;
• changes to the normal WebDAV upload behavior.

Test environment

Server: Nextcloud
Web server: Apache 2.4.68 (Ubuntu)
Client: Nextcloud iOS
API: PHBackgroundResourceUploadExtension
Upload destination: normal Nextcloud WebDAV URL
Upload method: PUT
Authentication: HTTP Basic
Resources tested: HEIC and MOV / Live Photo resources

[marinofaggiana]

cc @mpivchev @tobiasKaminsky

[tobiasKaminsky]

So the idea is that:

curl -v --request OPTIONS \ 
  --url http://localhost/nc/remote.php/dav/files/tobi/ \
--header 'X-NC-PhotoKit-Upload: 1' \
--user tobi:tobi

shall return: X-NC-PhotoKit-Upload: 1
since it has the specific header

Correct?

[marinofaggiana]

Required the response about "Resumable Uploads for HTTP" ... 501 if Not Implemented