Copyright (c) RISC OS Developments 2026. All rights reserved.
SPDX-License-Identifier: CDDL-1.0

# WebDAV review candidate

This copy contains newly implemented WebDAV support. Portable backend tests
and native compilation pass; native runtime and actual QNAP/pCloud account
acceptance are pending. Preserve your tested installation while evaluating this candidate.

## Connect

Use the existing LanMan98 connection window. Enter an `https://` URL in Server,
a local mount name, and your account credentials locally.
Enter a case-sensitive collection path in Share, or put the complete collection
URL in Server and leave Share empty. HTTP is available for local testing;
use HTTPS for cloud credentials.

QNAP: use `https://your-nas:configured-WebDAV-port/` and the shared folder
as Share, or the full folder URL with Share blank. Enable WebDAV on the NAS
and use its configured port and trusted certificate. See [QNAP instructions]
(https://www.qnap.com/en-us/how-to/faq/article/connecting-to-webdav-shared-folders-on-a-qnap-nas-in-windows-10).

pCloud: the documented endpoints are `https://webdav.pcloud.com` (US) and
`https://ewebdav.pcloud.com` (EU). Select the endpoint matching your account
region and enter the account email/password locally.
See [pCloud WebDAV help](https://help.pcloud.com/article/webdav).
Both endpoints answered an unauthenticated HTTPS OPTIONS request with
HTTP 401 and a Basic authentication challenge on 19 September 2026.
The portable LanMan HTTP code also parsed these responses through the host
OpenSSL adapter. No account login or file operation was exercised;
this does not validate native AcornSSL or account compatibility.

HTTPS requires a working AcornSSL installation and trusted server certificates.
There is no certificate-check bypass. Native transport currently resolves IPv4 hosts.

## Behaviour and limits

- Mounting and browsing use PROPFIND; files use GET and PUT; directories use MKCOL;
rename/move uses MOVE; deletion uses DELETE.
- Basic authentication is implemented. Digest, OAuth, automatic redirects and WebDAV
LOCK are not implemented. This is not a claim of compatibility with every cloud service.
- A whole file is staged on local scratch storage for random reads/writes;
allow sufficient local space. Changes upload on close.
The existing filesystem limit is 2 GiB minus one byte per file.
- Updating an existing file requires a strong ETag. A remote edit conflict rejects the
upload and preserves the local cached edit while its handle remains open.
This is not durable crash recovery; do not force unload during a conflict.
- Servers that support the custom dead properties can retain RISC OS metadata.
Otherwise server timestamps/default attributes are used; changing readonly
attributes can fail explicitly. Metadata support is checked by readback.
- Free-space reporting requires server quota properties; unsupported quota
returns an error instead of invented capacity
- XML responses are bounded to 16 MiB and 262144 nodes, with nesting limited
to 64 levels. Network operations have cooperative timeouts.

Protocol reference: [WebDAV RFC 4918](https://www.rfc-editor.org/info/rfc4918/).

Whole-file save/create errors cancel their internally-owned local staging cache
without retrying PUT, resizing back, or deleting the remote object during cleanup.
The caller receives the error and still owns its source data. A failed create can
therefore leave an empty or already-committed remote object; inspect it before
retrying. This differs from an ordinary open file whose rejected close retains
its cache for retry. Native FileSwitch/application error handling still requires
hardware testing.
