askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
object_webdav.py · 14.8 KB · 397 lines
| 1 | """Files as a folder: the pure half of the WebDAV surface at ``/dav/``. |
| 2 | |
| 3 | A person's files (the ``files`` collection, bytes under ``user_files/``) are |
| 4 | records, not a directory tree: each has an id, a ``filename`` that need not |
| 5 | be unique, and no parent folder. WebDAV lets every desktop mount them as a |
| 6 | folder anyway -- Linux (davfs2, the file manager's "Connect to Server"), |
| 7 | macOS Finder, Windows -- without a client of our own. The server side lives |
| 8 | in ``object_server._handle_webdav``; this module is what it needs that does |
| 9 | no I/O: naming, paths, the XML, ranges. |
| 10 | |
| 11 | Decisions, and what was rejected: |
| 12 | |
| 13 | - **Flat, by name.** ``/dav/files/`` holds the caller's own files, one |
| 14 | entry per record. Folders were rejected for now: the records have none, |
| 15 | and inventing a tree here would be a second, drifting notion of where a |
| 16 | file "is". MKCOL is refused (405), not faked. |
| 17 | - **Duplicate names get a suffix, oldest keeps the plain name.** Two uploads |
| 18 | of ``notes.txt`` show as ``notes.txt`` and ``notes (2).txt``, ordered by |
| 19 | creation then id, so the mapping is stable while both exist. The records |
| 20 | are not renamed: the suffix is only how the folder shows them. |
| 21 | - **No LOCK.** A lock that is not enforced is a stub that pretends, which |
| 22 | this codebase refuses (AGENTS.md section 4). Without it the server is DAV |
| 23 | class 1: davfs2 needs ``use_locks 0``, and macOS Finder mounts read-only. |
| 24 | Real locks (enforced on PUT/DELETE/MOVE) can come later. |
| 25 | - **Names from a record are made safe for a path, never trusted.** A |
| 26 | filename is data typed by a person; ``/`` and control characters would |
| 27 | split or corrupt the path a desktop sees. |
| 28 | """ |
| 29 | |
| 30 | from __future__ import annotations |
| 31 | |
| 32 | import mimetypes |
| 33 | import re |
| 34 | import xml.etree.ElementTree as ET |
| 35 | from dataclasses import dataclass |
| 36 | from datetime import datetime, timezone |
| 37 | from email.utils import formatdate |
| 38 | from typing import Any, Iterable |
| 39 | from urllib.parse import quote, unquote, urlsplit |
| 40 | from xml.sax.saxutils import escape |
| 41 | |
| 42 | DAV_ROOT = "/dav" |
| 43 | FILES_FOLDER = "files" |
| 44 | DAV_NS = "DAV:" |
| 45 | MAX_NAME_LENGTH = 255 |
| 46 | MAX_PROPFIND_BODY = 65_536 |
| 47 | |
| 48 | # The live properties this server answers; anything else asked for is |
| 49 | # reported missing (404 in its own propstat), as RFC 4918 requires. |
| 50 | LIVE_PROPS = ( |
| 51 | "displayname", |
| 52 | "resourcetype", |
| 53 | "getcontentlength", |
| 54 | "getcontenttype", |
| 55 | "getlastmodified", |
| 56 | "creationdate", |
| 57 | "getetag", |
| 58 | ) |
| 59 | |
| 60 | # Answered only when asked for by name (RFC 4331 says quota properties |
| 61 | # should stay out of allprop): what a desktop shows as the folder's free space. |
| 62 | ON_REQUEST_PROPS = frozenset({"quota-used-bytes", "quota-available-bytes"}) |
| 63 | |
| 64 | _CONTROL = re.compile(r"[\x00-\x1f\x7f]") |
| 65 | |
| 66 | |
| 67 | class DavRequestError(ValueError): |
| 68 | """A request this surface cannot honour; carries the HTTP status.""" |
| 69 | |
| 70 | def __init__(self, status: int, message: str): |
| 71 | super().__init__(message) |
| 72 | self.status = status |
| 73 | |
| 74 | |
| 75 | @dataclass(frozen=True) |
| 76 | class DavFile: |
| 77 | name: str # as the folder shows it: safe and unique |
| 78 | record: dict[str, Any] |
| 79 | size: int |
| 80 | modified: float # unix seconds |
| 81 | created: float |
| 82 | |
| 83 | @property |
| 84 | def record_id(self) -> str: |
| 85 | return str(self.record.get("id") or "") |
| 86 | |
| 87 | @property |
| 88 | def content_type(self) -> str: |
| 89 | return str(self.record.get("content_type") or "") or guess_type(self.name) |
| 90 | |
| 91 | @property |
| 92 | def etag(self) -> str: |
| 93 | return f'"{self.record_id}-{self.size}-{int(self.modified * 1000)}"' |
| 94 | |
| 95 | |
| 96 | def safe_name(filename: str) -> str: |
| 97 | """A record's filename as one path segment: no slashes, no control |
| 98 | characters, not empty, not ``.`` or ``..``, at most 255 characters.""" |
| 99 | name = _CONTROL.sub("", str(filename or "")).replace("/", "_").replace("\\", "_").strip() |
| 100 | if name in {"", ".", ".."}: |
| 101 | name = "unnamed" |
| 102 | return name[:MAX_NAME_LENGTH] |
| 103 | |
| 104 | |
| 105 | def check_new_name(name: str) -> str: |
| 106 | """A name a client asks to create or rename to; refused, not repaired, |
| 107 | because silently storing something other than what was asked for would |
| 108 | leave the client looking for a file that is not there.""" |
| 109 | if not name or name in {".", ".."} or "/" in name or "\\" in name or _CONTROL.search(name): |
| 110 | raise DavRequestError(400, "Not a usable file name.") |
| 111 | if len(name) > MAX_NAME_LENGTH: |
| 112 | raise DavRequestError(400, f"File names are limited to {MAX_NAME_LENGTH} characters.") |
| 113 | return name |
| 114 | |
| 115 | |
| 116 | def _with_suffix(name: str, n: int) -> str: |
| 117 | stem, dot, ext = name.rpartition(".") |
| 118 | if not dot or not stem: # no extension, or a dotfile like ".bashrc" |
| 119 | return f"{name} ({n})" |
| 120 | return f"{stem} ({n}).{ext}" |
| 121 | |
| 122 | |
| 123 | def folder_names(records: Iterable[dict[str, Any]]) -> dict[str, dict[str, Any]]: |
| 124 | """Name -> record for one folder: the oldest record keeps a name, later |
| 125 | ones get " (2)", " (3)"... Case-insensitive, because the desktops that |
| 126 | mount this (macOS, Windows) treat "A.txt" and "a.txt" as one file.""" |
| 127 | ordered = sorted(records, key=lambda r: (str(r.get("created_at") or ""), str(r.get("id") or ""))) |
| 128 | taken: set[str] = set() |
| 129 | out: dict[str, dict[str, Any]] = {} |
| 130 | for record in ordered: |
| 131 | base = safe_name(record.get("filename")) |
| 132 | name, n = base, 1 |
| 133 | while name.lower() in taken: |
| 134 | n += 1 |
| 135 | name = _with_suffix(base, n) |
| 136 | taken.add(name.lower()) |
| 137 | out[name] = record |
| 138 | return out |
| 139 | |
| 140 | |
| 141 | def lookup(names: dict[str, Any], name: str) -> str | None: |
| 142 | """The folder's own spelling of ``name``, matched without case.""" |
| 143 | if name in names: |
| 144 | return name |
| 145 | lowered = name.lower() |
| 146 | for existing in names: |
| 147 | if existing.lower() == lowered: |
| 148 | return existing |
| 149 | return None |
| 150 | |
| 151 | |
| 152 | def split_path(path: str) -> tuple[str, str | None]: |
| 153 | """Classify a decoded request path under /dav. |
| 154 | |
| 155 | Returns ("root", None), ("files", None) or ("file", name). Anything else |
| 156 | raises DavRequestError(404): there is nothing else in this tree. |
| 157 | """ |
| 158 | if path == DAV_ROOT or path == DAV_ROOT + "/": |
| 159 | return "root", None |
| 160 | rest = path[len(DAV_ROOT) + 1:] if path.startswith(DAV_ROOT + "/") else None |
| 161 | if rest is None: |
| 162 | raise DavRequestError(404, "Not under /dav.") |
| 163 | parts = [p for p in rest.split("/")] |
| 164 | if parts and parts[-1] == "": |
| 165 | parts = parts[:-1] # a trailing slash |
| 166 | if parts == [FILES_FOLDER]: |
| 167 | return "files", None |
| 168 | if len(parts) == 2 and parts[0] == FILES_FOLDER and parts[1]: |
| 169 | return "file", parts[1] |
| 170 | raise DavRequestError(404, "No such folder or file.") |
| 171 | |
| 172 | |
| 173 | def destination_path(header: str | None) -> str: |
| 174 | """The decoded path of a MOVE/COPY Destination header (absolute URL or |
| 175 | absolute path). The host is not compared: a client behind a proxy may |
| 176 | name any host, and the path alone decides what is touched.""" |
| 177 | if not header: |
| 178 | raise DavRequestError(400, "Destination header required.") |
| 179 | path = urlsplit(header.strip()).path |
| 180 | if not path.startswith("/"): |
| 181 | raise DavRequestError(400, "Destination must be an absolute URL or path.") |
| 182 | return unquote(path) |
| 183 | |
| 184 | |
| 185 | def parse_depth(header: str | None, *, default: str = "infinity") -> str: |
| 186 | value = (header or default).strip().lower() |
| 187 | if value not in {"0", "1", "infinity"}: |
| 188 | raise DavRequestError(400, "Depth must be 0, 1 or infinity.") |
| 189 | return value |
| 190 | |
| 191 | |
| 192 | def parse_overwrite(header: str | None) -> bool: |
| 193 | value = (header or "T").strip().upper() |
| 194 | if value not in {"T", "F"}: |
| 195 | raise DavRequestError(400, "Overwrite must be T or F.") |
| 196 | return value == "T" |
| 197 | |
| 198 | |
| 199 | def _parse_xml(body: bytes, what: str) -> ET.Element: |
| 200 | if len(body) > MAX_PROPFIND_BODY: |
| 201 | raise DavRequestError(413, f"{what} body too large.") |
| 202 | # No document type declarations at all: they are how entity expansion |
| 203 | # attacks get in, and no DAV client needs one. |
| 204 | if b"<!DOCTYPE" in body.upper() or b"<!ENTITY" in body.upper(): |
| 205 | raise DavRequestError(400, "Document type declarations are not accepted.") |
| 206 | try: |
| 207 | return ET.fromstring(body) |
| 208 | except ET.ParseError as exc: |
| 209 | raise DavRequestError(400, f"Malformed {what} body.") from exc |
| 210 | |
| 211 | |
| 212 | def parse_propfind(body: bytes) -> list[tuple[str, str]] | None: |
| 213 | """Which properties a PROPFIND asks for: None means all of them (an |
| 214 | empty body, <allprop/>), otherwise a list of (namespace, name). |
| 215 | <propname/> is answered like <allprop/>: values alongside names are a |
| 216 | superset no client has been seen to mind.""" |
| 217 | if not body.strip(): |
| 218 | return None |
| 219 | root = _parse_xml(body, "PROPFIND") |
| 220 | if root.tag != f"{{{DAV_NS}}}propfind": |
| 221 | raise DavRequestError(400, "Expected a DAV:propfind element.") |
| 222 | prop = root.find(f"{{{DAV_NS}}}prop") |
| 223 | if prop is None: |
| 224 | return None |
| 225 | wanted = [] |
| 226 | for child in prop: |
| 227 | ns, _, name = child.tag[1:].partition("}") if child.tag.startswith("{") else ("", "", child.tag) |
| 228 | wanted.append((ns, name)) |
| 229 | return wanted |
| 230 | |
| 231 | |
| 232 | def parse_proppatch(body: bytes) -> list[tuple[str, str]]: |
| 233 | """The (namespace, name) of every property a PROPPATCH tries to set or |
| 234 | remove. None of them are writable here; the caller answers 403 for each.""" |
| 235 | root = _parse_xml(body, "PROPPATCH") |
| 236 | names = [] |
| 237 | for prop in root.iter(f"{{{DAV_NS}}}prop"): |
| 238 | for child in prop: |
| 239 | ns, _, name = child.tag[1:].partition("}") if child.tag.startswith("{") else ("", "", child.tag) |
| 240 | names.append((ns, name)) |
| 241 | return names |
| 242 | |
| 243 | |
| 244 | def http_date(ts: float) -> str: |
| 245 | return formatdate(ts, usegmt=True) |
| 246 | |
| 247 | |
| 248 | def iso_date(ts: float) -> str: |
| 249 | return datetime.fromtimestamp(ts, tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") |
| 250 | |
| 251 | |
| 252 | # Types older Pythons' mimetypes lacks, so a file's type does not depend on |
| 253 | # which Python the server runs. |
| 254 | _EXTRA_TYPES = {".md": "text/markdown", ".markdown": "text/markdown"} |
| 255 | |
| 256 | |
| 257 | def guess_type(name: str) -> str: |
| 258 | guessed = mimetypes.guess_type(name)[0] |
| 259 | if guessed: |
| 260 | return guessed |
| 261 | _, dot, ext = name.rpartition(".") |
| 262 | return _EXTRA_TYPES.get(f".{ext.lower()}" if dot else "", "application/octet-stream") |
| 263 | |
| 264 | |
| 265 | def href(*segments: str, folder: bool = False) -> str: |
| 266 | path = DAV_ROOT + "/" + "/".join(quote(s, safe="") for s in segments if s) |
| 267 | if folder and not path.endswith("/"): |
| 268 | path += "/" |
| 269 | return path |
| 270 | |
| 271 | |
| 272 | def folder_props( |
| 273 | name: str, modified: float, *, used: int | None = None, available: int | None = None |
| 274 | ) -> dict[str, str | None]: |
| 275 | props: dict[str, str | None] = { |
| 276 | "displayname": escape(name), |
| 277 | "resourcetype": "<D:collection/>", |
| 278 | "getlastmodified": http_date(modified), |
| 279 | "creationdate": iso_date(modified), |
| 280 | "getcontenttype": "httpd/unix-directory", |
| 281 | } |
| 282 | if used is not None and available is not None: |
| 283 | props["quota-used-bytes"] = str(used) |
| 284 | props["quota-available-bytes"] = str(max(0, available)) |
| 285 | return props |
| 286 | |
| 287 | |
| 288 | def file_props(f: DavFile) -> dict[str, str | None]: |
| 289 | return { |
| 290 | "displayname": escape(f.name), |
| 291 | "resourcetype": "", |
| 292 | "getcontentlength": str(f.size), |
| 293 | "getcontenttype": escape(f.content_type), |
| 294 | "getlastmodified": http_date(f.modified), |
| 295 | "creationdate": iso_date(f.created), |
| 296 | "getetag": escape(f.etag), |
| 297 | } |
| 298 | |
| 299 | |
| 300 | def multistatus( |
| 301 | responses: Iterable[tuple[str, dict[str, str | None]]], |
| 302 | wanted: list[tuple[str, str]] | None, |
| 303 | ) -> bytes: |
| 304 | """A 207 body. ``responses`` is (href, {live prop name: XML value}); |
| 305 | values are already escaped. With ``wanted`` set, only those are |
| 306 | returned and the ones this resource lacks go in a 404 propstat.""" |
| 307 | out = ['<?xml version="1.0" encoding="utf-8"?>\n<D:multistatus xmlns:D="DAV:">'] |
| 308 | for target, props in responses: |
| 309 | out.append(f"<D:response><D:href>{escape(target)}</D:href>") |
| 310 | if wanted is None: |
| 311 | found = [(DAV_NS, k) for k in props if k not in ON_REQUEST_PROPS] |
| 312 | missing: list[tuple[str, str]] = [] |
| 313 | else: |
| 314 | found = [w for w in wanted if w[0] == DAV_NS and w[1] in props] |
| 315 | missing = [w for w in wanted if w not in found] |
| 316 | if found: |
| 317 | out.append("<D:propstat><D:prop>") |
| 318 | for _, name in found: |
| 319 | out.append(f"<D:{name}>{props[name] or ''}</D:{name}>") |
| 320 | out.append("</D:prop><D:status>HTTP/1.1 200 OK</D:status></D:propstat>") |
| 321 | if missing: |
| 322 | out.append(_propstat_status(missing, "404 Not Found")) |
| 323 | out.append("</D:response>") |
| 324 | out.append("</D:multistatus>\n") |
| 325 | return "".join(out).encode("utf-8") |
| 326 | |
| 327 | |
| 328 | def proppatch_refused(target: str, names: list[tuple[str, str]]) -> bytes: |
| 329 | return ( |
| 330 | '<?xml version="1.0" encoding="utf-8"?>\n<D:multistatus xmlns:D="DAV:">' |
| 331 | f"<D:response><D:href>{escape(target)}</D:href>" |
| 332 | + _propstat_status(names, "403 Forbidden") |
| 333 | + "</D:response></D:multistatus>\n" |
| 334 | ).encode("utf-8") |
| 335 | |
| 336 | |
| 337 | def _propstat_status(names: list[tuple[str, str]], status: str) -> str: |
| 338 | parts = ["<D:propstat><D:prop>"] |
| 339 | for i, (ns, name) in enumerate(names): |
| 340 | if ns == DAV_NS: |
| 341 | parts.append(f"<D:{name}/>") |
| 342 | else: |
| 343 | parts.append(f'<x{i}:{name} xmlns:x{i}="{escape(ns, {chr(34): """})}"/>') |
| 344 | parts.append(f"</D:prop><D:status>HTTP/1.1 {status}</D:status></D:propstat>") |
| 345 | return "".join(parts) |
| 346 | |
| 347 | |
| 348 | def parse_range(header: str | None, size: int) -> tuple[int, int] | None: |
| 349 | """One byte range as (start, end inclusive), or None for the whole file. |
| 350 | |
| 351 | Only a single range is served; a multi-range request gets the whole file |
| 352 | (allowed by RFC 9110, and what players that seek actually send is one |
| 353 | range). An unsatisfiable range raises DavRequestError(416). |
| 354 | """ |
| 355 | if not header or not header.strip().lower().startswith("bytes="): |
| 356 | return None |
| 357 | spec = header.strip()[6:] |
| 358 | if "," in spec: |
| 359 | return None |
| 360 | first, _, last = spec.strip().partition("-") |
| 361 | try: |
| 362 | if first == "": |
| 363 | n = int(last) |
| 364 | if n <= 0: |
| 365 | raise DavRequestError(416, "Range not satisfiable.") |
| 366 | return max(0, size - n), size - 1 |
| 367 | start = int(first) |
| 368 | end = int(last) if last else size - 1 |
| 369 | except ValueError: |
| 370 | return None |
| 371 | if start >= size or start < 0 or end < start: |
| 372 | raise DavRequestError(416, "Range not satisfiable.") |
| 373 | return start, min(end, size - 1) |
| 374 | |
| 375 | |
| 376 | def etag_matches(header: str | None, etag: str | None) -> bool: |
| 377 | """If-Match / If-None-Match: does any listed tag (or *) match?""" |
| 378 | if not header: |
| 379 | return False |
| 380 | for tag in header.split(","): |
| 381 | tag = tag.strip() |
| 382 | if tag == "*": |
| 383 | return etag is not None |
| 384 | if tag.startswith("W/"): |
| 385 | tag = tag[2:] |
| 386 | if etag is not None and tag == etag: |
| 387 | return True |
| 388 | return False |
| 389 | |
| 390 | |
| 391 | def folder_html(title: str, entries: Iterable[tuple[str, str]]) -> bytes: |
| 392 | """A plain index for a browser that opens a folder URL: (href, label).""" |
| 393 | rows = "".join(f'<li><a href="{escape(h, {chr(34): """})}">{escape(label)}</a></li>' for h, label in entries) |
| 394 | return ( |
| 395 | f"<!doctype html><meta charset=utf-8><title>{escape(title)}</title>" |
| 396 | f"<h1>{escape(title)}</h1><ul>{rows}</ul>" |
| 397 | ).encode("utf-8") |