mirror of
https://github.com/vrtmrz/obsidian-livesync.git
synced 2026-08-29 23:07:08 +00:00
97 lines
5.0 KiB
Markdown
97 lines
5.0 KiB
Markdown
# Architectural Decision Record: Gate Adaptive WebDAV with an Endpoint Safety Check
|
|
|
|
## Status
|
|
|
|
Proposed as an experimental provider after the S3 Adaptive path has completed adapter, CLI, host, and real-host
|
|
acceptance.
|
|
|
|
## Context
|
|
|
|
WebDAV exposes an object-shaped interface suitable for immutable packs, but method support and conditional semantics
|
|
vary across servers, gateways, reverse proxies, and authentication layers. A server can advertise WebDAV while failing
|
|
binary fidelity, replacing an object despite `If-None-Match: *`, returning incomplete listings, or ignoring Range.
|
|
|
|
The common protocol decision is recorded in
|
|
[Adaptive Journal as an explicit protocol](2026_07_adaptive_journal_protocol.md). The pack format, flat object mapping,
|
|
and detailed safety-check sequence are specified in the
|
|
[Adaptive Journal Sync design](../design_docs/adaptive_journal_sync.md).
|
|
|
|
## Decision
|
|
|
|
Adaptive WebDAV uses the same immutable pack and catalogue semantics proven by S3, with a WebDAV-specific flat object
|
|
mapping inside the configured collection. Logical writer ordering comes from the host ID, writer epoch, and dense
|
|
sequence embedded in authenticated records. Correctness does not depend on a server-provided `startAfter` order.
|
|
|
|
Before a new Adaptive repository becomes writable, a non-destructive endpoint safety checker exercises random reserved
|
|
probe keys and reports observed semantic capabilities:
|
|
|
|
- binary write and exact read-back;
|
|
- read-after-write visibility;
|
|
- complete collection listing for the probe keys;
|
|
- `If-None-Match: *` preventing replacement;
|
|
- delete visibility; and
|
|
- exact byte-range behaviour, reported separately as optional.
|
|
|
|
The checker is an implementation acceptance target for compatible servers, not a claim that every WebDAV server must
|
|
support Adaptive Journal. It touches no repository objects, attempts to remove every probe, reports incomplete cleanup,
|
|
and never interprets authentication, permission, timeout, malformed response, or server failure as absence.
|
|
|
|
Conditional create, binary fidelity, complete listing, read-after-write visibility, and delete visibility are required.
|
|
Range remains optional. The user selects whole-pack or Range retrieval based on their endpoint and own latency and
|
|
throughput preference; the checker does not benchmark or recommend a policy.
|
|
|
|
Successful mutations do not receive unconditional confirmation requests. An ambiguous response is classified as
|
|
`verify-first`, and the exact immutable key is read before retrying. The existing opaque WebDAV layout and Adaptive
|
|
layout are detected separately; a mismatch requires a remote rebuild or another namespace.
|
|
|
|
## Staged acceptance
|
|
|
|
### Adapter and Commonlib integration
|
|
|
|
Unit tests own HTTP status classification, conditional-create verification, flat-name round trips, complete listing,
|
|
probe isolation, cleanup reporting, Range validation, and whole-pack fallback. A disposable WebDAV integration runs
|
|
the safety checker before exercising Adaptive Metadata and Chunk synchronisation.
|
|
|
|
### CLI end-to-end acceptance
|
|
|
|
The built CLI applies an Adaptive WebDAV Setup URI to a second independent database and synchronises text and binary
|
|
Chunk-backed files through a real disposable server. One client uses whole-pack retrieval; Range is added to this layer
|
|
only when the selected test server proves it. The CLI test does not repeat the complete endpoint capability matrix.
|
|
|
|
### Host settings and UI
|
|
|
|
The WebDAV dialogue exposes Adaptive mode only with clear capability-check results. It persists the expected repository
|
|
ID and the selected retrieval policy, defaults to whole-pack, and reports that Range is optional. Focused tests own
|
|
profile and Setup URI preservation without contacting a server.
|
|
|
|
### Real-host end-to-end acceptance
|
|
|
|
One real-Obsidian workflow uses the same known disposable WebDAV implementation, runs the safety gate, and proves a
|
|
representative Chunk-backed transfer. Servers outside that fixture are diagnosed by the checker rather than added to a
|
|
large real-host matrix.
|
|
|
|
## Alternatives rejected
|
|
|
|
### Trust advertised WebDAV methods
|
|
|
|
Method advertisement does not prove the conditional, listing, visibility, and byte semantics required for immutable
|
|
publication.
|
|
|
|
### Treat Range as mandatory
|
|
|
|
Whole-pack retrieval is correct and often competitive for throughput. Requiring Range would exclude otherwise safe
|
|
servers for an optional optimisation.
|
|
|
|
### Add server-specific compatibility branches
|
|
|
|
The remote may be any implementation or proxy composition. Semantic checks produce a maintainable contract, while a
|
|
growing server-name table would remain incomplete and become stale.
|
|
|
|
## Consequences
|
|
|
|
- WebDAV remains experimental because suitability is endpoint-specific.
|
|
- The safety checker gives a concrete reason when a server cannot host Adaptive Journal.
|
|
- Common object-pack behaviour is inherited from the earlier S3 boundary, keeping WebDAV-specific tests focused on HTTP
|
|
semantics and name mapping.
|
|
- Optional Range support can improve request efficiency without becoming a data-availability requirement.
|