diff --git a/developer_manual/client_apis/WebDAV/basic.rst b/developer_manual/client_apis/WebDAV/basic.rst index 01b6172c1fe..17712b4b8ad 100644 --- a/developer_manual/client_apis/WebDAV/basic.rst +++ b/developer_manual/client_apis/WebDAV/basic.rst @@ -108,7 +108,7 @@ The table below summarizes common WebDAV methods used by Nextcloud and the most +------------+-------------------------------------------+----------------------------------------------+-------------------------------------------------------------+ | PUT | ``/remote.php/dav/files/{user}/file`` | Optional: ``X-OC-MTime``, ``X-OC-CTime``, | Uploads/overwrites file content. | | | | ``OC-Checksum``, ``OC-Total-Length``, | | -| | | ``X-NC-WebDAV-AutoMkcol`` | | +| | | ``X-NC-WebDAV-Auto-Mkcol`` | | +------------+-------------------------------------------+----------------------------------------------+-------------------------------------------------------------+ | MKCOL | ``/remote.php/dav/files/{user}/folder`` | (none required) | Creates a folder. | +------------+-------------------------------------------+----------------------------------------------+-------------------------------------------------------------+ @@ -583,44 +583,44 @@ Request Headers You can set some special headers that Nextcloud will interpret. -+-----------------------+-----------------------------------------------------------------+--------------------------------------------+ -| Header | Description | Example | -+=======================+=================================================================+============================================+ -| X-OC-MTime | | Allow to specify a modification time. | ``1675789581`` | -| | | The response will contain the header ``X-OC-MTime: accepted`` | | -| | | if the mtime was accepted. | | -+-----------------------+-----------------------------------------------------------------+--------------------------------------------+ -| X-OC-CTime | | Allow to specify a creation time. | ``1675789581`` | -| | | The response will contain the header ``X-OC-CTime: accepted`` | | -| | | if the mtime was accepted. | | -+-----------------------+-----------------------------------------------------------------+--------------------------------------------+ -| OC-Checksum | | A checksum that will be stored in the DB. | ``md5:04c36b75222cd9fd47f2607333029106`` | -| | | For regular ``PUT`` uploads, the server stores the value | | -| | | without validation. During bulk uploads, the checksum | | -| | | **is** validated against the uploaded content. | | -| | | Currently used algorithms are ``MD5``, ``SHA1``, ``SHA256``, | | -| | | ``SHA3-256``, ``Adler32``. | | -+-----------------------+-----------------------------------------------------------------+--------------------------------------------+ -| X-Hash | | On ``PUT`` requests, instructs the server to compute a hash | ``md5``, ``sha1``, ``sha256``, | -| | | of the uploaded file content during the write. The server | or ``all`` | -| | | returns the hash(es) in response headers named | | -| | | ``X-Hash-MD5``, ``X-Hash-SHA1``, and/or ``X-Hash-SHA256``. | | -| | | Setting the value to ``all`` computes all three hashes. | | -| | | Beware of performance implications! | | -+-----------------------+-----------------------------------------------------------------+--------------------------------------------+ -| OC-Total-Length | | Contains the total size of the file during a chunk upload. | ``4052412`` | -| | | This allow the server to abort faster if the remaining | | -| | | user's quota is not enough. | | -+-----------------------+-----------------------------------------------------------------+--------------------------------------------+ -| X-NC-WebDAV-AutoMkcol | | When set to ``1``, instructs the server to automatically | | -| | | create any missing parent directories when uploading a file. | | -| | | Available since Nextcloud 32. | | -+-----------------------+-----------------------------------------------------------------+--------------------------------------------+ -| OC-Chunked | | Used for legacy chunk upload to differentiate a regular | Deprecated | -| | | upload from a chunked upload. It allowed checking for quota | | -| (deprecated) | | and various other things. Nowadays, you need to provide the | You do not have to provide | -| | | ``OC-Total-Length`` header on the ``PUT`` requests instead. | this anymore | -+-----------------------+-----------------------------------------------------------------+--------------------------------------------+ ++------------------------+-----------------------------------------------------------------+--------------------------------------------+ +| Header | Description | Example | ++========================+=================================================================+============================================+ +| X-OC-MTime | | Allow to specify a modification time. | ``1675789581`` | +| | | The response will contain the header ``X-OC-MTime: accepted`` | | +| | | if the mtime was accepted. | | ++------------------------+-----------------------------------------------------------------+--------------------------------------------+ +| X-OC-CTime | | Allow to specify a creation time. | ``1675789581`` | +| | | The response will contain the header ``X-OC-CTime: accepted`` | | +| | | if the mtime was accepted. | | ++------------------------+-----------------------------------------------------------------+--------------------------------------------+ +| OC-Checksum | | A checksum that will be stored in the DB. | ``md5:04c36b75222cd9fd47f2607333029106`` | +| | | For regular ``PUT`` uploads, the server stores the value | | +| | | without validation. During bulk uploads, the checksum | | +| | | **is** validated against the uploaded content. | | +| | | Currently used algorithms are ``MD5``, ``SHA1``, ``SHA256``, | | +| | | ``SHA3-256``, ``Adler32``. | | ++------------------------+-----------------------------------------------------------------+--------------------------------------------+ +| X-Hash | | On ``PUT`` requests, instructs the server to compute a hash | ``md5``, ``sha1``, ``sha256``, | +| | | of the uploaded file content during the write. The server | or ``all`` | +| | | returns the hash(es) in response headers named | | +| | | ``X-Hash-MD5``, ``X-Hash-SHA1``, and/or ``X-Hash-SHA256``. | | +| | | Setting the value to ``all`` computes all three hashes. | | +| | | Beware of performance implications! | | ++------------------------+-----------------------------------------------------------------+--------------------------------------------+ +| OC-Total-Length | | Contains the total size of the file during a chunk upload. | ``4052412`` | +| | | This allow the server to abort faster if the remaining | | +| | | user's quota is not enough. | | ++------------------------+-----------------------------------------------------------------+--------------------------------------------+ +| X-NC-WebDAV-Auto-Mkcol | | When set to ``1``, instructs the server to automatically | | +| | | create any missing parent directories when uploading a file. | | +| | | Available since Nextcloud 32. | | ++------------------------+-----------------------------------------------------------------+--------------------------------------------+ +| OC-Chunked | | Used for legacy chunk upload to differentiate a regular | Deprecated | +| | | upload from a chunked upload. It allowed checking for quota | | +| (deprecated) | | and various other things. Nowadays, you need to provide the | You do not have to provide | +| | | ``OC-Total-Length`` header on the ``PUT`` requests instead. | this anymore | ++------------------------+-----------------------------------------------------------------+--------------------------------------------+ Response Headers ---------------- diff --git a/docs/plans/15365-fix-webdav-automkcol-header.md b/docs/plans/15365-fix-webdav-automkcol-header.md new file mode 100644 index 00000000000..15e3b39677e --- /dev/null +++ b/docs/plans/15365-fix-webdav-automkcol-header.md @@ -0,0 +1,89 @@ +--- +title: Fix X-NC-WebDAV-AutoMkcol header name in WebDAV client API docs +date: 2026-08-07 +artifact_contract: ce-unified-plan/v1 +artifact_readiness: implementation-ready +execution: code +product_contract_source: ce-plan-bootstrap +origin: issue #15365 (https://github.com/nextcloud/documentation/issues/15365) +depth: lightweight +settled_decision_conflicts: [] +--- + +# Fix X-NC-WebDAV-AutoMkcol header name in WebDAV client API docs + +## Problem Frame + +The developer manual documents the optional upload header as +`X-NC-WebDAV-AutoMkcol` in `developer_manual/client_apis/WebDAV/basic.rst` +at two places (lines 111 and 615). The Nextcloud server reads +`X-NC-WebDAV-Auto-Mkcol` (with a second hyphen) in +`apps/dav/lib/Upload/UploadAutoMkcolPlugin.php` (line 41 of nextcloud/server +master). Clients following the documentation send the wrong header and +receive a 403 on uploads that should auto-create parent directories. + +## Requirements + +- R1. Rename the header from `X-NC-WebDAV-AutoMkcol` to + `X-NC-WebDAV-Auto-Mkcol` in both occurrences in + `developer_manual/client_apis/WebDAV/basic.rst`. +- R2. No other file in the repository may contain the misspelled + `AutoMkcol` variant after the change (verified by repository-wide grep). +- R3. The fix is documentation-only; no source code of this repository + changes, and no server-side behavior is proposed or requested. + +## Scope Boundary + +In scope: the two header-name occurrences in `basic.rst`. + +Out of scope: +- Any change to server code (the server name is canonical). +- Reformatting or rewording the affected tables beyond the header name. +- Other documented headers or WebDAV endpoint behavior. + +## Key Technical Decisions + +- KTD-1 (user-directed): use `X-NC-WebDAV-Auto-Mkcol` as the corrected name. + Rejected alternative: keeping `AutoMkcol` — the server's + `UploadAutoMkcolPlugin` checks `X-NC-WebDAV-Auto-Mkcol`; the docs are + wrong, not the server. Evidence: nextcloud/server + `apps/dav/lib/Upload/UploadAutoMkcolPlugin.php:41`. + +## Assumptions + +- The server-side header name remains stable for the current and upcoming + documented versions (the plugin line was verified on server master). +- The reporter's observed 403 was caused by the header mismatch; the fix + aligns docs with server behavior. + +## Implementation Units + +### U-1 Rename header in WebDAV request-headers table + +Files: `developer_manual/client_apis/WebDAV/basic.rst` + +- Line 111 (PUT row in the request-methods table): replace + ``X-NC-WebDAV-AutoMkcol`` with ``X-NC-WebDAV-Auto-Mkcol`` inside the + existing literal markup, keeping the table cell width intact. +- Line 615 (request-headers table row): replace the header cell + ``X-NC-WebDAV-AutoMkcol`` with ``X-NC-WebDAV-Auto-Mkcol`` and widen the + first table column to fit the longer name, keeping the RST grid-table + borders aligned (re-run `sphinx-build`/`rst-lint` equivalent check or + visually verify the table renders). + +Verification: +1. Repository-wide grep for `AutoMkcol` (excluding the hyphenated variant) + returns zero matches. +2. Grep confirms both `X-NC-WebDAV-Auto-Mkcol` occurrences exist at the + expected lines. +3. RST table structure remains valid (grid-table column widths consistent; + doc build succeeds or cell borders line up). + +## Dependencies and Sequencing + +Single unit; no ordering constraints. + +## Risks + +- RST grid tables break silently when column widths are edited + incorrectly — mitigation is the table-validity check in U-1 verification.