Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

dbbasic-object-server/object_webdav.py
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

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
3A person's files (the ``files`` collection, bytes under ``user_files/``) are
4records, not a directory tree: each has an id, a ``filename`` that need not
5be unique, and no parent folder. WebDAV lets every desktop mount them as a
6folder anyway -- Linux (davfs2, the file manager's "Connect to Server"),
7macOS Finder, Windows -- without a client of our own. The server side lives
8in ``object_server._handle_webdav``; this module is what it needs that does
9no I/O: naming, paths, the XML, ranges.
10
11Decisions, 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
30from __future__ import annotations
31
32import mimetypes
33import re
34import xml.etree.ElementTree as ET
35from dataclasses import dataclass
36from datetime import datetime, timezone
37from email.utils import formatdate
38from typing import Any, Iterable
39from urllib.parse import quote, unquote, urlsplit
40from xml.sax.saxutils import escape
41
42DAV_ROOT = "/dav"
43FILES_FOLDER = "files"
44DAV_NS = "DAV:"
45MAX_NAME_LENGTH = 255
46MAX_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.
50LIVE_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.
62ON_REQUEST_PROPS = frozenset({"quota-used-bytes", "quota-available-bytes"})
63
64_CONTROL = re.compile(r"[\x00-\x1f\x7f]")
65
66
67class 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)
76class 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
96def 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
105def 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
116def _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
123def 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
141def 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
152def 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
173def 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
185def 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
192def 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
199def _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
212def 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
232def 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
244def http_date(ts: float) -> str:
245 return formatdate(ts, usegmt=True)
246
247
248def 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
257def 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
265def 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
272def 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
288def 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
300def 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
328def 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
337def _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): "&quot;"})}"/>')
344 parts.append(f"</D:prop><D:status>HTTP/1.1 {status}</D:status></D:propstat>")
345 return "".join(parts)
346
347
348def 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
376def 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
391def 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): "&quot;"})}">{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")