droboticflow/docs/drosync/product-requirements.md
2026-07-28 20:43:46 +08:00

2.1 KiB

Product requirements

User outcome

A user selects a local directory once. The daemon waits for files to stabilize, builds a deterministic manifest, uploads new or changed regular files through short-lived BOS URLs, and reports a traceable final session. Concurrent devices never silently overwrite one another.

File policy

  • Include regular files only.
  • Exclude hidden entries by default; allow an explicit mapping opt-in.
  • Never follow symlinks or ingest FIFO, socket, block, or character devices.
  • Ignore common temporary suffixes such as .tmp, .part, .partial, .crdownload, .swp, and .download.
  • Require 60 seconds of unchanged mtime/size before hashing; verify stat again after hashing.
  • A mapping may require a sidecar {file}.done marker.
  • Preserve source mtime in the manifest. Do not preserve owner or mode.
  • Treat rename as a candidate after 5 seconds, still subject to the 60-second stability rule.

Consistency policy

  • Upload bytes only to a random internal staging key.
  • Bind direct uploads to Content-MD5, Content-Length, and drosync metadata.
  • Bind each multipart part to Content-MD5 and Content-Length; persist each returned part ETag.
  • Treat multipart ETag only as a transport validator, never as file SHA-256.
  • Publish with server-side multipart copy. Complete the target multipart upload with If-None-Match: * for create or If-Match for update.
  • On precondition failure, retain the original object and publish the staged content to {original}.__conflict__{UTC}_{shortItemId}.
  • Record remote ETag, size, versionId when available, platform version, operation, session, item, and actor.

Availability and support objectives

  • Monthly API availability: 99.9%.
  • p95: begin uploading within 15 minutes after an incremental file stabilizes.
  • New control-plane requests rejected within 60 seconds after credential revocation.
  • RTO 4 hours and RPO 15 minutes.
  • Initial support window: 8x5.

Explicit non-goals

Two-way sync, remote deletion, file-content merging, POSIX filesystem semantics, offline-only networks, proxy/custom-CA support, VPN relay, and platform-external direct writes into update-enabled prefixes are outside v1.