webdav.cpp

Go to the documentation of this file.

// Copyright (C) 2026 Douglas Quigg (dstroy0) <dquigg123@gmail.com>
// SPDX-License-Identifier: AGPL-3.0-or-later
 
/**
 * @file webdav.cpp
 * @brief WebDAV (RFC 4918) filesystem-backed request handler for PC.
 *
 * Split out of protocore.cpp (single-purpose server files). The pure WebDAV core - method
 * classification, the 207 Multi-Status XML builder, header parsing - lives in
 * services/file_transfer/webdav/webdav.{h,cpp} and is host-tested; this file is the PC glue that
 * needs a real filesystem (PROPFIND/PUT/COPY/MOVE/... over an fs::FS subtree). WEBDAV requires
 * FILE_SERVING (enforced in protocore_config.h), so the file-serving helpers it borrows are always
 * present. Behavior is identical to the pre-split code - a pure move.
 */
 
#include "services/file_transfer/webdav/webdav.h" // the pure WebDAV core
#include "network_drivers/transport/tcp.h"        // conn_pool
#include "protocore.h"
#include "server/protocore_internal.h"
#include "services/system/clock.h" // pc_millis() for lock timeouts
#include "shared_primitives/mime.h"
#include "shared_primitives/strbuf.h" // pc_sb frame builder
#include <string.h>
 
#if PC_ENABLE_WEBDAV
// ---------------------------------------------------------------------------
// WebDAV (RFC 4918) - filesystem-backed request handling. The pure core
// (method classification + 207 XML builder + header parsing) lives in
// services/file_transfer/webdav/webdav.{h,cpp} and is host-tested; this part needs a real FS.
// ---------------------------------------------------------------------------
 
// The parser's streaming-body sink is a SINGLE global hook (http_parser_set_stream_hooks): the
// last registrar wins, so an OTA or upload service registering after dav() would silently take
// the sink away and a bodied PUT to a DAV route would buffer (bounded by BODY_BUF_SIZE) instead
// of streaming. protocore_config.h documents "do not combine" but nothing enforced it; the buffered-PUT
// fallback below depends on it, so enforce it here rather than leaving it to the reader.
#if PC_ENABLE_OTA || PC_ENABLE_UPLOAD
#error "PC_ENABLE_WEBDAV cannot be combined with PC_ENABLE_OTA or PC_ENABLE_UPLOAD: the parser's \
streaming-body sink is a single global hook, so whichever registers last silently disables the others."
#endif
 
// A Depth-1 PROPFIND stops on whichever comes first: the 207 buffer filling, or PC_WEBDAV_MAX_ENTRIES
// children. Both are plain #ifndef knobs and nothing related them, so pin the relationship the listing
// loop's bound relies on - the buffer must fill first.
//
// The fixed text of one <D:response> (pc_webdav_ms_entry) is 204 bytes: 27 href prologue + 66
// prop/resourcetype opening + 18 resourcetype close + 93 propstat/response close. Add the href itself
// (>= 1 byte) and the shortest possible element is 205; a collection adds <D:collection/>, a file adds
// getcontentlength/getcontenttype, and both add getlastmodified, so every real shape is larger. 192 is
// therefore a safe floor: BUF_SIZE / 192 over-estimates how many entries the buffer can ever hold, and
// it still has to come out under MAX_ENTRIES. (It over-estimates further because ms_begin's prologue and
// ms_end's epilogue also come out of the same buffer.)
static const size_t PC_WEBDAV_MIN_ENTRY_BYTES = 192;
static_assert(PC_WEBDAV_BUF_SIZE / PC_WEBDAV_MIN_ENTRY_BYTES < PC_WEBDAV_MAX_ENTRIES,
              "PC_WEBDAV_BUF_SIZE is large enough to hold PC_WEBDAV_MAX_ENTRIES entries: raise "
              "PC_WEBDAV_MAX_ENTRIES or lower PC_WEBDAV_BUF_SIZE so the buffer bound stays the "
              "binding one (see the PROPFIND listing loop).");
 
// WebDAV response scratch, owned by one instance (internal linkage): the 207 Multi-Status build
// buffer (BSS). One named owner, unreachable from any other translation unit.
struct DavBufCtx
{
    char buf[PC_WEBDAV_BUF_SIZE];
};
static DavBufCtx s_dav;
 
// http_rfc1123() lives in the FILE_SERVING section above (WEBDAV requires
// FILE_SERVING), shared by both; used here for getlastmodified / creationdate.
 
// Join an FS root and a subpath into @p out (mirrors serve_static_request's
// separator handling). Returns false on overflow.
static bool dav_join(const char *root, const char *sub, char *out, size_t cap)
{
    size_t rlen = strnlen(root, MAX_PATH_LEN);
    bool root_slash = (rlen > 0 && root[rlen - 1] == '/');
    if (root_slash && sub[0] == '/')
    {
        sub++;
    }
    bool sub_slash = (sub[0] == '/');
    const char *sep = (root_slash || sub_slash) ? "" : "/";
    pc_sb sb_out = {out, cap, 0, true};
    pc_sb_put(&sb_out, root);
    pc_sb_put(&sb_out, sep);
    pc_sb_put(&sb_out, sub);
    int wn = (int)pc_sb_finish(&sb_out);
    // wn <= 0 cannot fire: snprintf only returns negative on an encoding error, which "%s%s%s"
    // cannot raise, and sep is "/" whenever root and sub are both empty, so the shortest join is
    // one byte. The truncation half (wn >= cap) is exercised.
    return wn > 0 && wn < (int)cap; // GCOVR_EXCL_BR_LINE  wn <= 0 unreachable (see above)
}
 
// The basename of an FS entry name (cores differ: name() may be a full path or a
// bare name).
static const char *dav_basename(const char *name)
{
    const char *slash = strrchr(name, '/');
    // The bare-name half is an ESP32-core shape: the host FS mock's File::name() always returns the
    // node's full path, so strrchr never comes back null here.
    return slash ? slash + 1 : name; // GCOVR_EXCL_BR_LINE  bare-name half is core-specific (see above)
}
 
// Recursively delete a file or directory tree (bounded depth). Re-opens the
// directory after each child removal so iteration is never mutated underneath us.
static bool dav_rm_recursive(fs::FS &fsys, const char *path, int depth)
{
    if (depth > 8)
    {
        return false; // refuse pathologically deep trees rather than overflow the stack
    }
    fs::File d = fsys.open(path, "r");
    if (!d)
    {
        return false;
    }
    if (!d.isDirectory())
    {
        d.close();
        return fsys.remove(path);
    }
    for (;;)
    {
        fs::File c = d.openNextFile();
        if (!c)
        {
            break;
        }
        char cp[256];
        pc_sb sb_cp = {cp, sizeof(cp), 0, true};
        pc_sb_put(&sb_cp, path);
        pc_sb_put(&sb_cp, "/");
        pc_sb_put(&sb_cp, dav_basename(c.name()));
        int wn = (int)pc_sb_finish(&sb_cp);
        c.close();
        // GCOVR_EXCL_START  neither half can fire on a host build. snprintf cannot return negative
        // for "%s/%s", and the child path cannot overflow cp[256]: `path` had to open, so it is a
        // path the FS mock actually stores (its node paths are capped at 160 bytes), and the child's
        // basename is what is left of that same 160-byte cap after `path` - so cp stays under 160.
        // On a real core (LittleFS: 255-byte names under a 240-byte mount root) it is reachable,
        // which is why the guard is here.
        if (wn <= 0 || wn >= (int)sizeof(cp))
        {
            d.close();
            return false;
        }
        // GCOVR_EXCL_STOP
        if (!dav_rm_recursive(fsys, cp, depth + 1))
        {
            d.close();
            return false;
        }
        d.close();
        d = fsys.open(path, "r"); // reset the directory cursor after the deletion
        // GCOVR_EXCL_START  TOCTOU re-open guard: `path` opened moments ago, so only a concurrent
        // delete / FS fault fails it here. The host mock's open-failure hook is a single stored path
        // that applies to every open, so it cannot fail this re-open while letting the first open
        // above succeed - there is no way to drive this arm from a host test.
        if (!d)
        {
            return false;
        }
        // GCOVR_EXCL_STOP
    }
    d.close();
    return fsys.rmdir(path);
}
 
// Recursively copy a file or directory tree from @p src to @p dst (bounded depth).
// Unlike dav_rm_recursive we cannot re-open + take the first child each step (the
// source is not consumed, so that would loop forever); instead we re-open and skip
// to child #idx, which is safe even if a core invalidates an open dir handle across
// the writes the copy makes to the destination tree.
static bool dav_copy_recursive(fs::FS &fsys, const char *src, const char *dst, int depth)
{
    if (depth > 8)
    {
        return false; // refuse pathologically deep trees rather than overflow the stack
    }
 
    fs::File s = fsys.open(src, "r");
    if (!s)
    {
        return false;
    }
    if (!s.isDirectory())
    {
        fs::File d = fsys.open(dst, "w");
        if (!d)
        {
            s.close();
            return false;
        }
        uint8_t cbuf[FILE_CHUNK_SIZE];
        size_t cn;
        while ((cn = s.read(cbuf, sizeof(cbuf))) > 0)
        {
            d.write(cbuf, cn);
        }
        s.close();
        d.close();
        return true;
    }
    s.close();
 
    if (!fsys.mkdir(dst)) // create the destination collection (caller cleared any existing dst)
    {
        return false;
    }
 
    for (int idx = 0;; idx++)
    {
        fs::File d = fsys.open(src, "r");
        // GCOVR_EXCL_START  TOCTOU re-open guard, same shape as dav_rm_recursive's: `src` opened at
        // the top of this call, so only a concurrent delete / FS fault fails it here, and the host
        // mock's open-failure hook is one stored path applied to every open - it cannot fail this
        // re-open while letting the first one succeed.
        if (!d)
        {
            return false;
        }
        // GCOVR_EXCL_STOP
        fs::File c;
        for (int i = 0; i <= idx; i++)
        {
            c = d.openNextFile();
            if (!c)
            {
                break;
            }
        }
        if (!c)
        {
            d.close();
            break; // no child at this index - done
        }
        char base[128];
        pc_sb sb_base = {base, sizeof(base), 0, true};
        pc_sb_put(&sb_base, dav_basename(c.name()));
        if (pc_sb_finish(&sb_base) == 0)
        {
            base[0] = '\0';
        }
        c.close();
        d.close();
 
        char sp[256];
        char dp[256];
        pc_sb sb_sp = {sp, sizeof(sp), 0, true};
        pc_sb_put(&sb_sp, src);
        pc_sb_put(&sb_sp, "/");
        pc_sb_put(&sb_sp, base);
        int wn1 = (int)pc_sb_finish(&sb_sp);
        pc_sb sb_dp = {dp, sizeof(dp), 0, true};
        pc_sb_put(&sb_dp, dst);
        pc_sb_put(&sb_dp, "/");
        pc_sb_put(&sb_dp, base);
        int wn2 = (int)pc_sb_finish(&sb_dp);
        // GCOVR_EXCL_START  none of the four halves can fire on a host build. snprintf cannot return
        // negative for "%s/%s"; and neither child path can reach 256 bytes, because `src` had to open
        // (so it is within the FS mock's 160-byte node-path cap, and `base` is what remains of that
        // cap) while `dst` is the mount root plus a Destination header value, which the parser caps
        // at MAX_VAL_LEN. Reachable on a real core, where names and roots are far longer.
        if (wn1 <= 0 || wn1 >= (int)sizeof(sp) || wn2 <= 0 || wn2 >= (int)sizeof(dp))
        {
            return false;
        }
        // GCOVR_EXCL_STOP
        if (!dav_copy_recursive(fsys, sp, dp, depth + 1))
        {
            return false;
        }
    }
    return true;
}
 
// Map a WebDAV request path to its on-disk path under the mount @p r. Strips the
// mount prefix, rejects traversal, joins onto the FS root, and drops a trailing
// '/'. Returns 0 on success, else the HTTP error code (403 traversal, 414 too
// long) - the single source of truth for the path check, shared by the request
// handler and the streaming-PUT begin hook.
static int dav_resolve_path(const Route *r, const char *reqpath, char *out, size_t cap)
{
    size_t plen = strnlen(r->path, MAX_PATH_LEN);
    // plen == 0 is unreachable: dav() always stores at least "*" - it appends the wildcard when the
    // prefix lacks one, so even dav("") yields a one-character pattern.
    if (plen > 0 && r->path[plen - 1] == '*') // GCOVR_EXCL_BR_LINE  plen == 0 unreachable (see above)
    {
        plen--;
    }
    // GCOVR_EXCL_BR_START  the "" arm is unreachable: both callers reached here through
    // path_matches() against this same route, which already required reqpath to carry the mount
    // prefix, so the length test always holds. Kept so a future caller that resolves without
    // matching first still cannot index past the end of reqpath.
    const char *sub = (strnlen(reqpath, MAX_PATH_LEN) >= plen) ? reqpath + plen : "";
    // GCOVR_EXCL_BR_STOP
    if (strstr(sub, ".."))
    {
        return 403;
    }
    const char *root = r->static_root ? r->static_root : "";
    if (!dav_join(root, sub, out, cap))
    {
        return 414;
    }
    size_t fpl = strnlen(out, cap);
    if (fpl > 1 && out[fpl - 1] == '/')
    {
        out[fpl - 1] = '\0';
    }
    return 0;
}
 
#if PC_ENABLE_STREAM_BODY
// Per-connection streaming-PUT state for WebDAV: each slot streams its body to its
// own file, so concurrent PUTs never clobber one another, and a transfer is never
// bounded by BODY_BUF_SIZE. Indexed by the request's slot (req - http_pool).
struct DavPut
{
    fs::File file;  ///< destination file for this slot's PUT.
    bool active;    ///< file opened for the current PUT.
    bool error;     ///< a write (or the open) failed.
    bool existed;   ///< target existed before this PUT (204 vs 201).
    bool locked;    ///< a lock blocked this PUT: consume the body but write nothing, then answer 423.
    size_t written; ///< bytes written so far.
};
 
// WebDAV streaming-PUT state, owned by one instance (internal linkage): the serving instance
// and the per-slot destination-file state (each slot streams to its own file, so concurrent
// PUTs never clobber one another). One named owner, unreachable from any other TU.
struct DavPutCtx
{
    PC *stream_srv = nullptr;
    DavPut put[MAX_CONNS];
};
static DavPutCtx s_davput;
 
// The server-global WebDAV lock state, owned by one instance (internal linkage): the lock table (RFC 4918
// §6-7). Zero-initialized, so every slot starts inactive and nothing is locked until a LOCK stores a token.
struct DavLockCtx
{
    DavLockTable table;
};
static DavLockCtx s_dav_lock;
 
// True if a write to the URL @p path is blocked by a lock the request does not present a token for. The
// token, if any, comes from the request's If header (RFC 4918 §10.4 / §7).
static bool dav_write_blocked(HttpReq *req, const char *path)
{
    const char *if_hdr = http_get_header(req, "If");
    char tok[PC_DAV_LOCK_TOKEN_MAX];
    const char *presented = (if_hdr && pc_dav_if_token(if_hdr, tok, sizeof(tok))) ? tok : nullptr;
    return !pc_dav_lock_can_write(&s_dav_lock.table, path, presented);
}
 
// True if the (always NUL-terminated) request body contains @p needle - used to spot a <shared> lockscope.
static bool dav_body_has(HttpReq *req, const char *needle)
{
    return strstr((const char *)req->body, needle) != nullptr;
}
 
// Extract the token from a Lock-Token Coded-URL ("<opaquelocktoken:...>") into @p out; false if malformed.
static bool dav_coded_url_token(const char *coded, char *out, size_t cap)
{
    const char *lt = strchr(coded, '<');
    if (!lt)
    {
        return false;
    }
    const char *gt = strchr(lt, '>');
    if (!gt)
    {
        return false;
    }
    size_t n = (size_t)(gt - lt - 1);
    if (n + 1 > cap)
    {
        return false;
    }
    memcpy(out, lt + 1, n);
    out[n] = 0;
    return true;
}
 
// GCOVR_EXCL_BR_START  the null-stream_srv arm of all three trampolines is unreachable: the only
// thing that installs them as the parser's stream hooks is dav(), which sets s_davput.stream_srv
// first and never clears it - so a trampoline cannot run before the instance pointer exists.
bool PC::dav_put_begin_tramp(HttpReq *req)
{
    return s_davput.stream_srv && s_davput.stream_srv->dav_stream_put_begin(req);
}
void PC::dav_put_data_tramp(HttpReq *req, const uint8_t *data, size_t len)
{
    if (s_davput.stream_srv)
    {
        s_davput.stream_srv->dav_stream_put_data(req, data, len);
    }
}
// GCOVR_EXCL_BR_STOP
void PC::dav_put_abort_tramp(HttpReq *req)
{
    // The PUT was torn down before the handler ran: close the half-written file so
    // the handle is not leaked (a leak eventually exhausts LittleFS's open slots).
    uint8_t slot = (uint8_t)(req - http_pool);
    // GCOVR_EXCL_BR_START  the slot >= MAX_CONNS half is unreachable: http_pool is CONN_POOL_SLOTS
    // long, but the streaming-body hooks are driven only by the HTTP/1.x byte parser, which never
    // parses for the internal dispatch slots at and above MAX_CONNS. s_davput.put[] is MAX_CONNS
    // long, so the bound still has to be tested here.
    if (slot < MAX_CONNS && s_davput.put[slot].active)
    {
        s_davput.put[slot].file.close();
        s_davput.put[slot].active = false;
    }
    // GCOVR_EXCL_BR_STOP
}
 
bool PC::dav_stream_put_begin(HttpReq *req)
{
    if (strcmp(req->method, "PUT") != 0)
    {
        return false;
    }
    uint8_t slot = (uint8_t)(req - http_pool);
    for (uint8_t i = 0; i < _route_count; i++)
    {
        Route *r = &_routes[i];
        // The !is_active half cannot fire: every entry below _route_count was filled by
        // fill_route_base, which sets is_active, and nothing ever clears it again.
        if (!r->is_active || r->type != RouteType::ROUTE_DAV) // GCOVR_EXCL_BR_LINE  see above
        {
            continue;
        }
        if (!path_matches(r->path, r->is_wildcard, req->path))
        {
            continue;
        }
        // GCOVR_EXCL_START  dav() has no interface-filtered overload, so a ROUTE_DAV entry's
        // iface_filter is always PC_IFACE_ANY and this gate never rejects. Kept so a DAV mount picks
        // up the per-route interface gate for free if that overload is ever added.
        if (r->iface_filter != pc_iface::PC_IFACE_ANY && r->iface_filter != pc_conn_iface(slot))
        {
            continue;
        }
        // GCOVR_EXCL_STOP
        // GCOVR_EXCL_START  a RouteType::ROUTE_DAV route always carries static_fs (set in dav()); this null-guard
        // cannot fire
        if (!r->static_fs)
        {
            return false;
        }
        // GCOVR_EXCL_STOP
        char fs_path[256];
        if (dav_resolve_path(r, req->path, fs_path, sizeof(fs_path)) != 0)
        {
            return false; // traversal / too long - let it buffer; the handler answers 403/414
        }
        DavPut *d = &s_davput.put[slot];
        d->active = false;
        d->error = false;
        d->locked = false;
        d->written = 0;
        if (dav_write_blocked(req, req->path))
        {
            // Locked by another principal: consume the body but open no file, so the resource is not
            // touched; the PUT handler answers 423 (RFC 4918 §7).
            d->locked = true;
            return true;
        }
        d->existed = r->static_fs->exists(fs_path);
        d->file = r->static_fs->open(fs_path, "w");
        if (d->file)
        {
            d->active = true;
        }
        else
        {
            d->error = true;
        }
        return true; // stream regardless so the body is consumed and the handler replies
    }
    return false;
}
 
void PC::dav_stream_put_data(HttpReq *req, const uint8_t *data, size_t len)
{
    uint8_t slot = (uint8_t)(req - http_pool);
    // GCOVR_EXCL_START  http_pool is CONN_POOL_SLOTS (MAX_CONNS + PC_INTERNAL_SLOTS) long, so an index >=
    // MAX_CONNS is a real address - but it belongs to an internal dispatch slot (e.g. HTTP/3), and the
    // streaming-body hooks this runs from are driven only by the HTTP/1.x byte parser, which never parses
    // for those slots. s_davput.put[] is MAX_CONNS long, so the bound still has to be here.
    if (slot >= MAX_CONNS)
    {
        return;
    }
    // GCOVR_EXCL_STOP
    DavPut *d = &s_davput.put[slot];
    if (d->active && !d->error)
    {
        if (d->file.write(data, len) != len)
        {
            d->error = true;
        }
        else
        {
            d->written += len;
        }
    }
}
#endif // PC_ENABLE_STREAM_BODY
 
void PC::dav(const char *url_prefix, fs::FS &file_sys, const char *fs_root)
{
    if (_route_count >= MAX_ROUTES)
    {
        return;
    }
    Route *r = &_routes[_route_count++];
 
    char pat[MAX_PATH_LEN];
    size_t n = strnlen(url_prefix, MAX_PATH_LEN);
    if (n > 0 && url_prefix[n - 1] == '*')
    {
        pc_sb sb_pat = {pat, sizeof(pat), 0, true};
        pc_sb_put(&sb_pat, url_prefix);
        if (pc_sb_finish(&sb_pat) == 0)
        {
            pat[0] = '\0';
        }
    }
    else
    {
        pc_sb sb_pat2 = {pat, sizeof(pat), 0, true};
        pc_sb_put(&sb_pat2, url_prefix);
        pc_sb_put(&sb_pat2, "*");
        if (pc_sb_finish(&sb_pat2) == 0)
        {
            pat[0] = '\0';
        }
    }
    fill_route_base(r, pat);
    r->type = RouteType::ROUTE_DAV;
    r->method = HttpMethod::HTTP_GET; // unused: WebDAV dispatch keys off the raw method token
    r->static_fs = &file_sys;
    r->static_root = fs_root;
 
#if PC_ENABLE_STREAM_BODY
    // Stream PUT bodies straight to the file (one global sink; see PC_ENABLE_STREAM_BODY).
    s_davput.stream_srv = this;
    http_parser_set_stream_hooks(dav_put_begin_tramp, dav_put_data_tramp, dav_put_abort_tramp);
#endif
}
 
void PC::dav_send_status(uint8_t slot_id, int code, const char *extra_headers)
{
    if (!pc_conn_active(slot_id))
    {
        http_reset(slot_id);
        return;
    }
    bool keep;
    const char *cl = pc_resp_conn_hdr(slot_id, &keep);
    char header[RESP_HDR_BUF_SIZE];
    // GCOVR_EXCL_BR_START  the null arm of the extra_headers ternary is unreachable: every call site
    // in this file passes either "" or a string literal. Kept so the parameter stays optional.
    pc_sb sb_header = {header, sizeof(header), 0, true};
    pc_sb_put(&sb_header, "HTTP/1.1 ");
    pc_sb_i64(&sb_header, (int64_t)(code));
    pc_sb_put(&sb_header, " ");
    pc_sb_put(&sb_header, status_text(code));
    pc_sb_put(&sb_header, "\r\n");
    pc_sb_put(&sb_header, extra_headers ? extra_headers : "");
    pc_sb_put(&sb_header, "Content-Length: 0\r\n");
    pc_sb_put(&sb_header, cl);
    pc_sb_put(&sb_header, "\r\n");
    int hlen = (int)pc_sb_finish(&sb_header);
    // GCOVR_EXCL_BR_STOP
    pc_conn_send(slot_id, header, (u16_t)hlen);
    pc_resp_end(slot_id, code, 0, keep);
}
 
bool PC::try_serve_dav(uint8_t slot_id, HttpReq *req)
{
    for (uint8_t i = 0; i < _route_count; i++)
    {
        Route *r = &_routes[i];
        // The !is_active half cannot fire: every entry below _route_count was filled by
        // fill_route_base, which sets is_active, and nothing ever clears it again.
        if (!r->is_active || r->type != RouteType::ROUTE_DAV) // GCOVR_EXCL_BR_LINE  see above
        {
            continue;
        }
        if (!path_matches(r->path, r->is_wildcard, req->path))
        {
            continue;
        }
        // GCOVR_EXCL_START  dav() has no interface-filtered overload, so a ROUTE_DAV entry's
        // iface_filter is always PC_IFACE_ANY and this gate never rejects. Kept so a DAV mount picks
        // up the per-route interface gate for free if that overload is ever added.
        if (r->iface_filter != pc_iface::PC_IFACE_ANY && r->iface_filter != pc_conn_iface(slot_id))
        {
            continue;
        }
        // GCOVR_EXCL_STOP
        serve_dav_request(slot_id, req, r);
        return true;
    }
    return false;
}
 
void PC::serve_dav_request(uint8_t slot_id, HttpReq *req, const Route *r)
{
    // GCOVR_EXCL_START  a RouteType::ROUTE_DAV route always carries static_fs (set in dav()); this null-guard cannot
    // fire
    if (!r->static_fs)
    {
        dav_send_status(slot_id, 404, "");
        return;
    }
    // GCOVR_EXCL_STOP
    fs::FS &fsys = *r->static_fs;
 
    char fs_path[256];
    int rc = dav_resolve_path(r, req->path, fs_path, sizeof(fs_path));
    if (rc != 0)
    {
        dav_send_status(slot_id, rc, ""); // 403 traversal / 414 too long
        return;
    }
 
    // Mount-prefix length and FS root, used by COPY/MOVE to resolve the Destination. As in
    // dav_resolve_path, plen == 0 is unreachable: dav() always stores at least "*".
    size_t plen = strnlen(r->path, MAX_PATH_LEN);
    if (plen > 0 && r->path[plen - 1] == '*') // GCOVR_EXCL_BR_LINE  plen == 0 unreachable (see above)
    {
        plen--;
    }
    const char *root = r->static_root ? r->static_root : "";
 
    // Expire any timed-out locks (RFC 4918 §6.6) before this request consults the table, so a stale lock
    // never gates a write. The clock is pc_millis() (pluggable); seconds are enough for lock lifetimes.
    uint32_t dav_now_s = (uint32_t)(pc_millis() / 1000u);
    pc_dav_lock_sweep(&s_dav_lock.table, dav_now_s);
 
    switch (pc_webdav_method(req->method))
    {
    case WebDavMethod::DAV_M_OPTIONS:
        add_response_header(slot_id, "DAV", "1, 2");
        add_response_header(slot_id, "Allow",
                            "OPTIONS, GET, HEAD, PUT, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK");
        add_response_header(slot_id, "MS-Author-Via", "DAV");
        send_empty(slot_id, 200);
        return;
 
    case WebDavMethod::DAV_M_GET:
    case WebDavMethod::DAV_M_HEAD: {
        fs::File f = fsys.open(fs_path, "r");
        if (!f)
        {
            dav_send_status(slot_id, 404, "");
            return;
        }
        bool isdir = f.isDirectory();
        f.close();
        if (isdir)
        {
            dav_send_status(slot_id, 405, ""); // GET on a collection is not a download
            return;
        }
        serve_file_internal(slot_id, pc_webdav_method(req->method) == WebDavMethod::DAV_M_HEAD, fsys, fs_path,
                            mime_type(fs_path), nullptr);
        return;
    }
 
    case WebDavMethod::DAV_M_PUT: {
#if PC_ENABLE_STREAM_BODY
        if (req->body_streaming)
        {
            // The body was written to this slot's file as it arrived (dav_stream_put_*).
            DavPut *d = &s_davput.put[slot_id];
            if (d->locked)
            {
                d->locked = false;
                dav_send_status(slot_id, 423, ""); // Locked: the body was consumed but nothing was written
                return;
            }
            if (d->active)
            {
                d->file.close();
                d->active = false; // closed here: the abort hook must not double-close
            }
            else
            {
                dav_send_status(slot_id, 409, ""); // parent missing / not writable
                return;
            }
            if (d->error)
            {
                dav_send_status(slot_id, 507, ""); // a write failed (e.g. disk full)
                return;
            }
            dav_send_status(slot_id, d->existed ? 204 : 201, "");
            return;
        }
#endif
        // Buffered fallback (streaming disabled): body bounded by BODY_BUF_SIZE.
        if (dav_write_blocked(req, req->path))
        {
            dav_send_status(slot_id, 423, ""); // Locked: no / wrong lock token in the If header
            return;
        }
        bool existed = fsys.exists(fs_path);
        fs::File f = fsys.open(fs_path, "w");
        if (!f)
        {
            dav_send_status(slot_id, 409, ""); // parent missing / not writable
            return;
        }
        // GCOVR_EXCL_START  only an empty CL:0 PUT reaches this buffered path, so body_len is always
        // 0 and the write never runs: a bodied PUT to a DAV route always streams (dav() registers the
        // sink, and the #error at the top of this file is what makes that hold - no other service can
        // have taken the single global hook), and stream_begin's only decline reasons for a matched
        // DAV route are the ones that also fail the top-level resolve above. Kept as a fail-safe so a
        // caller that somehow does arrive buffered writes its body instead of silently dropping it.
        if (req->body_len)
        {
            f.write(req->body, req->body_len);
        }
        // GCOVR_EXCL_STOP
        f.close();
        dav_send_status(slot_id, existed ? 204 : 201, "");
        return;
    }
 
    case WebDavMethod::DAV_M_DELETE: {
        if (dav_write_blocked(req, req->path))
        {
            dav_send_status(slot_id, 423, "");
            return;
        }
        if (!fsys.exists(fs_path))
        {
            dav_send_status(slot_id, 404, "");
            return;
        }
        dav_send_status(slot_id, dav_rm_recursive(fsys, fs_path, 0) ? 204 : 403, "");
        return;
    }
 
    case WebDavMethod::DAV_M_MKCOL:
        if (dav_write_blocked(req, req->path))
        {
            dav_send_status(slot_id, 423, "");
            return;
        }
        if (fsys.exists(fs_path))
        {
            dav_send_status(slot_id, 405, ""); // already exists
            return;
        }
        dav_send_status(slot_id, fsys.mkdir(fs_path) ? 201 : 409, "");
        return;
 
    case WebDavMethod::DAV_M_COPY:
    case WebDavMethod::DAV_M_MOVE: {
        const char *dest_hdr = http_get_header(req, "Destination");
        char dest_url[256];
        if (!dest_hdr || !pc_webdav_dest_path(dest_hdr, dest_url, sizeof(dest_url)))
        {
            dav_send_status(slot_id, 400, "");
            return;
        }
        // The destination must live under this same mount.
        if (strncmp(dest_url, r->path, plen) != 0)
        {
            dav_send_status(slot_id, 502, "");
            return;
        }
        const char *dest_sub = dest_url + plen;
        if (strstr(dest_sub, ".."))
        {
            dav_send_status(slot_id, 403, "");
            return;
        }
        // Both COPY and MOVE write the destination; MOVE additionally removes the source. Each locked
        // target needs the matching token in the If header (RFC 4918 §7).
        bool is_move = pc_webdav_method(req->method) == WebDavMethod::DAV_M_MOVE;
        if (dav_write_blocked(req, dest_url) || (is_move && dav_write_blocked(req, req->path)))
        {
            dav_send_status(slot_id, 423, "");
            return;
        }
        char dest_fs[256];
        if (!dav_join(root, dest_sub, dest_fs, sizeof(dest_fs)))
        {
            dav_send_status(slot_id, 414, "");
            return;
        }
        size_t dpl = strnlen(dest_fs, sizeof(dest_fs));
        if (dpl > 1 && dest_fs[dpl - 1] == '/')
        {
            dest_fs[dpl - 1] = '\0';
        }
 
        const char *ow = http_get_header(req, "Overwrite");
        bool overwrite = !(ow && (ow[0] == 'F' || ow[0] == 'f'));
        bool dest_exists = fsys.exists(dest_fs);
        if (dest_exists && !overwrite)
        {
            dav_send_status(slot_id, 412, "");
            return;
        }
 
        if (pc_webdav_method(req->method) == WebDavMethod::DAV_M_MOVE)
        {
            if (dest_exists)
            {
                dav_rm_recursive(fsys, dest_fs, 0); // replace
            }
            bool ok = fsys.rename(fs_path, dest_fs);
            dav_send_status(slot_id, ok ? (dest_exists ? 204 : 201) : 409, "");
            return;
        }
 
        // COPY: a file or a whole collection (RFC 4918 9.8). Depth applies to a
        // collection source: "0" copies just the collection itself, "infinity"
        // (the default, also when absent) copies the entire tree.
        fs::File src = fsys.open(fs_path, "r");
        if (!src)
        {
            dav_send_status(slot_id, 404, "");
            return;
        }
        bool src_is_dir = src.isDirectory();
        src.close();
 
        const char *depth_h = http_get_header(req, "Depth");
        bool shallow = depth_h && depth_h[0] == '0'; // Depth: 0
 
        if (dest_exists)
        {
            dav_rm_recursive(fsys, dest_fs, 0); // overwrite: clear the target first
        }
 
        bool ok;
        if (src_is_dir && shallow)
        {
            ok = fsys.mkdir(dest_fs); // collection, Depth:0 - just the collection, no members
        }
        else
        {
            ok = dav_copy_recursive(fsys, fs_path, dest_fs, 0);
        }
        dav_send_status(slot_id, ok ? (dest_exists ? 204 : 201) : 409, "");
        return;
    }
 
    case WebDavMethod::DAV_M_LOCK: {
        const uint32_t timeout_s = 3600; // the lock lifetime advertised in <D:timeout> below
        uint32_t expiry_s = dav_now_s + timeout_s;
 
        // A LOCK carrying the token in its If header is a refresh (RFC 4918 §9.10.2): extend the held
        // lock's timeout rather than taking a new one.
        const char *if_hdr = http_get_header(req, "If");
        char iftok[PC_DAV_LOCK_TOKEN_MAX];
        const DavLock *lk = nullptr;
        if (if_hdr && pc_dav_if_token(if_hdr, iftok, sizeof(iftok)))
        {
            lk = pc_dav_lock_refresh(&s_dav_lock.table, iftok, expiry_s);
        }
 
        char token[PC_DAV_LOCK_TOKEN_MAX];
        bool shared, depth_inf;
        if (lk) // refreshed an existing lock: echo its stored scope / depth / token
        {
            pc_sb sb_token = {token, sizeof(token), 0, true};
            pc_sb_put(&sb_token, lk->token);
            if (pc_sb_finish(&sb_token) == 0)
            {
                token[0] = '\0';
            }
            shared = !lk->exclusive;
            depth_inf = lk->depth_infinity;
        }
        else
        {
            // New lock: a lockinfo body naming <shared> is a shared lock (else exclusive); a LOCK defaults
            // to Depth: infinity when the header is absent (RFC 4918 §9.10.3).
            shared = req->body_len && dav_body_has(req, "shared");
            depth_inf = pc_webdav_depth(http_get_header(req, "Depth"), PC_DAV_DEPTH_INFINITY) != 0;
            unsigned long tok = (unsigned long)millis();
#ifdef ARDUINO
            tok ^= (unsigned long)esp_random();
#endif
            pc_sb sb_token2 = {token, sizeof(token), 0, true};
            pc_sb_put(&sb_token2, "opaquelocktoken:");
            pc_sb_hex(&sb_token2, (uint64_t)(tok), 8);
            pc_sb_put(&sb_token2, "-pc");
            if (pc_sb_finish(&sb_token2) == 0)
            {
                token[0] = '\0';
            }
            if (!pc_dav_lock_acquire(&s_dav_lock.table, req->path, token, /*exclusive=*/!shared, depth_inf, expiry_s))
            {
                dav_send_status(slot_id, 423, ""); // a conflicting lock already holds this resource / subtree
                return;
            }
        }
        pc_sb sb_buf = {s_dav.buf, sizeof(s_dav.buf), 0, true};
        pc_sb_put(
            &sb_buf,
            "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<D:prop "
            "xmlns:D=\"DAV:\"><D:lockdiscovery><D:activelock><D:locktype><D:write/></D:locktype><D:lockscope><D:");
        pc_sb_put(&sb_buf, shared ? "shared" : "exclusive");
        pc_sb_put(&sb_buf, "/></D:lockscope><D:depth>");
        pc_sb_put(&sb_buf, depth_inf ? "infinity" : "0");
        pc_sb_put(&sb_buf, "</D:depth><D:timeout>Second-");
        pc_sb_u32(&sb_buf, (uint32_t)((unsigned long)timeout_s));
        pc_sb_put(&sb_buf, "</D:timeout><D:locktoken><D:href>");
        pc_sb_put(&sb_buf, token);
        pc_sb_put(&sb_buf, "</D:href></D:locktoken></D:activelock></D:lockdiscovery></D:prop>\n");
        if (pc_sb_finish(&sb_buf) == 0)
        {
            s_dav.buf[0] = '\0';
        }
        // RFC 4918 §10.5: Lock-Token uses a Coded-URL (angle-bracketed).
        char lt[64];
        pc_sb sb_lt = {lt, sizeof(lt), 0, true};
        pc_sb_put(&sb_lt, "<");
        pc_sb_put(&sb_lt, token);
        pc_sb_put(&sb_lt, ">");
        if (pc_sb_finish(&sb_lt) == 0)
        {
            lt[0] = '\0';
        }
        add_response_header(slot_id, "Lock-Token", lt);
        send(slot_id, 200, "application/xml; charset=utf-8", s_dav.buf);
        return;
    }
 
    case WebDavMethod::DAV_M_UNLOCK: {
        // Release the lock named by the Lock-Token header (a Coded-URL: "<opaquelocktoken:...>").
        const char *lt = http_get_header(req, "Lock-Token");
        char token[PC_DAV_LOCK_TOKEN_MAX];
        if (!lt || !dav_coded_url_token(lt, token, sizeof(token)) || !pc_dav_lock_release(&s_dav_lock.table, token))
        {
            dav_send_status(slot_id, 409, ""); // no such lock to release (RFC 4918 §9.11.1)
            return;
        }
        dav_send_status(slot_id, 204, "");
        return;
    }
 
    case WebDavMethod::DAV_M_PROPFIND: {
        fs::File f = fsys.open(fs_path, "r");
        if (!f)
        {
            dav_send_status(slot_id, 404, "");
            return;
        }
        bool isdir = f.isDirectory();
        uint32_t fsize = (uint32_t)f.size();
        time_t mtime = f.getLastWrite();
 
        int depth = pc_webdav_depth(http_get_header(req, "Depth"), 1);
 
        // RFC 4918 9.1.1: this server lists at most one level, so a Depth: infinity
        // PROPFIND is rejected with 403 + the propfind-finite-depth precondition rather
        // than silently returning a partial (one-level) 207 the client would read as
        // complete. Clients wanting a listing use Depth: 0 or 1.
        if (depth == PC_DAV_DEPTH_INFINITY)
        {
            f.close();
            static const char body[] = "<?xml version=\"1.0\" encoding=\"utf-8\"?>\r\n"
                                       "<D:error xmlns:D=\"DAV:\"><D:propfind-finite-depth/></D:error>\r\n";
            send(slot_id, 403, "application/xml", body);
            return;
        }
 
        // Self href: the request path, with a trailing '/' for a collection.
        char self_href[MAX_PATH_LEN + 2];
        pc_sb sb_self_href = {self_href, sizeof(self_href), 0, true};
        pc_sb_put(&sb_self_href, req->path);
        if (pc_sb_finish(&sb_self_href) == 0)
        {
            self_href[0] = '\0';
        }
        size_t sl = strnlen(self_href, sizeof(self_href));
        // GCOVR_EXCL_BR_START  two halves here cannot fire, both for the same reason: req->path is
        // HttpReq::path[MAX_PATH_LEN] and the parser always leaves at least "/" in it, so sl is
        // between 1 and MAX_PATH_LEN-1. That makes `sl == 0` impossible, and makes the room test
        // below always true (self_href is MAX_PATH_LEN+2). Both are kept as bounds on an index.
        if (isdir && (sl == 0 || self_href[sl - 1] != '/'))
        {
            if (sl + 1 < sizeof(self_href))
            {
                self_href[sl++] = '/';
                self_href[sl] = '\0';
            }
        }
        // GCOVR_EXCL_BR_STOP
 
        size_t cap = sizeof(s_dav.buf), len = 0;
        len = pc_webdav_ms_begin(s_dav.buf, cap, len);
        char mt[40];
        http_rfc1123(mtime, mt, sizeof(mt));
        len = pc_webdav_ms_entry(s_dav.buf, cap, len, self_href, isdir, fsize, mt, isdir ? "" : mime_type(fs_path));
 
        if (isdir && depth >= 1)
        {
            int count = 0;
            for (;;)
            {
                fs::File c = f.openNextFile();
                if (!c)
                {
                    break;
                }
                // GCOVR_EXCL_START  the buffer-full break below always preempts this cap: the
                // static_assert at the top of this file pins PC_WEBDAV_BUF_SIZE small enough that
                // s_dav.buf cannot hold PC_WEBDAV_MAX_ENTRIES entries. Kept so the count is bounded
                // whatever those two knobs are set to.
                if (count >= PC_WEBDAV_MAX_ENTRIES)
                {
                    c.close();
                    break;
                }
                // GCOVR_EXCL_STOP
                const char *base = dav_basename(c.name());
                bool cdir = c.isDirectory();
                uint32_t csize = (uint32_t)c.size();
                time_t cmt = c.getLastWrite();
                char chref[MAX_PATH_LEN + 80];
                pc_sb sb_chref = {chref, sizeof(chref), 0, true};
                pc_sb_put(&sb_chref, self_href);
                pc_sb_put(&sb_chref, base);
                pc_sb_put(&sb_chref, cdir ? "/" : "");
                if (pc_sb_finish(&sb_chref) == 0)
                {
                    chref[0] = '\0';
                }
                char cmtbuf[40];
                http_rfc1123(cmt, cmtbuf, sizeof(cmtbuf));
                c.close();
                size_t before = len;
                len = pc_webdav_ms_entry(s_dav.buf, cap, len, chref, cdir, csize, cmtbuf, cdir ? "" : mime_type(base));
                if (len == before)
                {
                    break; // buffer full - stop listing
                }
                count++;
            }
        }
        f.close();
        len = pc_webdav_ms_end(s_dav.buf, cap, len);
        send(slot_id, 207, "application/xml; charset=utf-8", s_dav.buf);
        return;
    }
 
    case WebDavMethod::DAV_M_PROPPATCH: {
        // Read-only properties (no dead-property store): answer 207 with each
        // requested property refused 403, rather than 405 - keeps Explorer/Finder,
        // which PROPPATCH a timestamp right after a PUT, from erroring.
        if (!fsys.exists(fs_path))
        {
            dav_send_status(slot_id, 404, "");
            return;
        }
        size_t n =
            pc_webdav_proppatch_ms(s_dav.buf, sizeof(s_dav.buf), req->path, (const char *)req->body, req->body_len);
        // GCOVR_EXCL_START  the builder cannot run out of room at this env's PC_WEBDAV_BUF_SIZE: its
        // output is the ~120-byte prologue, the escaped href (capped at 256 by the builder's own esc
        // buffer), at most PC_WEBDAV_MAX_PROPS echoed tags whose bytes all come out of req->body
        // (capped at BODY_BUF_SIZE), and the ~110-byte epilogue - about 1.2 KB against a 2 KB buffer.
        // It IS reachable at the 256-byte floor protocore_config.h enforces, so the guard stays.
        if (!n)
        {
            dav_send_status(slot_id, 507, ""); // Insufficient Storage: response did not fit the buffer
            return;
        }
        // GCOVR_EXCL_STOP
        send(slot_id, 207, "application/xml; charset=utf-8", s_dav.buf);
        return;
    }
 
    case WebDavMethod::DAV_M_UNSUPPORTED:
    default:
        dav_send_status(
            slot_id, 405,
            "Allow: OPTIONS, GET, HEAD, PUT, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK\r\n");
        return;
    }
}
#endif // PC_ENABLE_WEBDAV